fix(auth): server-issued SIWN nonces + skew-tolerant freshness + distinct verify error codes (#824)

* fix(auth): server-issued SIWN nonces + skew-tolerant freshness + distinct verify error codes

A device clock even slightly ahead of the server failed sign-in
deterministically across every wallet: the nonce embedded the client's
Date.now() and the server rejected any future timestamp (age < 0).

- signWithWallet() now fetches the nonce from /near/nonce (server
  clock), falling back to a local nonce if the endpoint is unavailable;
  accountId is optional on the nonce request so fresh-connect flows can
  get a nonce before the wallet account is known
- nonce freshness tolerates up to 60s of future skew on both verify
  paths (ed25519 via near-kit's nonceValidation: "none" + local check,
  ML-DSA-65 in the shared check)
- verify failures return distinct codes (UNAUTHORIZED_NONCE_EXPIRED,
  UNAUTHORIZED_NONCE_FROM_FUTURE, UNAUTHORIZED_SIGNATURE_INVALID,
  UNAUTHORIZED_PUBLIC_KEY_INVALID, UNAUTHORIZED_ACCESS_KEY_NOT_FOUND,
  UNAUTHORIZED_NOT_FULL_ACCESS_KEY, VERIFY_RPC_ERROR) instead of one
  blanket "Invalid signature"; RPC failures on the access-key lookup no
  longer masquerade as bad signatures
- client propagates error codes to onError; login page maps
  NONCE_FROM_FUTURE to a "device clock ahead" message (4 locales)

* test(auth): sandbox integration tests for real quantum-key sign-in

Full SIWN flow against a local nearcore sandbox (near-kit Sandbox,
nearcore 2.13.4): the test provisions real accounts via AddKey
transactions carrying an ML-DSA-65 full-access key, points the plugin's
rpcUrl at the sandbox node, and drives /near/verify end to end with
zero mocked crypto — real borsh serialization, real SHA-256, real
ml_dsa65 signatures, real on-chain access-key lookups.

Covers: ml-dsa-65 sign-in happy path, nonce replay detection, tampered
signature (UNAUTHORIZED_SIGNATURE_INVALID), key-not-on-account
(UNAUTHORIZED_ACCESS_KEY_NOT_FOUND), stale nonce
(UNAUTHORIZED_NONCE_EXPIRED), and an ed25519 parity path. Skips cleanly
when the sandbox binary is unavailable.

* fix(auth): true borsh Option encoding in ML-DSA-65 NEP-413 verification

The ML-DSA-65 verifier serialized callback_url as a u32 (4 zero bytes
when absent), but borsh Option<T> is a single discriminant byte — so
every signature from a real quantum-capable wallet (Rust/borsh side,
e.g. Intear) failed verification with "Invalid signature" even though
key, nonce, and message all matched. The ed25519 path never hit this
because near-kit serializes the Option correctly.

Proven against a captured failing request from a real wallet:
ml_dsa65.verify flips false→true with the 1-byte encoding, same key and
signature. Test helpers now sign with the spec encoding, and the sandbox
integration test signs without callbackUrl while the request includes
it, exercising the callbackUrl retry against the real chain.

* test(auth): sandbox E2E for the gasless flow — quantum login, gas keys, relay

Full gasless-write chain against a local nearcore sandbox: quantum SIWN
login, gas-key bootstrap signed by the ML-DSA parent (KeyType 2
transaction accepted on-chain — proves noble/aws-lc interop for
transaction signatures), sponsor funding through /near/gas-key/fund
(real transferToGasKey), a gasless write signed by the gas key on its
own nonce lane with gas paid from the prepaid balance, and a
quantum-signed delegate relayed through /near/relay and executed by the
chain.

The receiver contract is a hand-built minimal wasm module exporting
__fastdata_kv, so the suite needs no external fixtures.

Also aligns relayedTransaction test-schema optionality with the
production migration: gasUsed and updatedAt are nullable there, but the
test DDL inferred NOT NULL, breaking any relay-route create under test.

* ci: cache the near-sandbox binary for better-near-auth sandbox tests

The sandbox integration tests boot a local nearcore node via near-kit,
which downloads the ~30MB near-sandbox binary to ~/.near-kit/sandbox/bin
on first use. Cache it keyed on the near-kit version (the binary version
source) with a restore fallback so version bumps only pay for the new
download, not the whole directory.

Author: elliotBraem

.changeset/better-near-auth-server-nonce.md

@@ -0,0 +1,11 @@
+---
+"better-near-auth": minor
+---
+
+Fix deterministic sign-in failures caused by client/server clock skew, and make SIWN verification failures diagnosable.
+
+ML-DSA-65 NEP-413 verification now uses correct borsh serialization for `callback_url: Option<String>` (one discriminant byte, Some followed by [u32 len][bytes]). The previous encoding wrote the Option as a u32, so signatures from real quantum-capable wallets (Rust/borsh — e.g. Intear) failed verification with "Invalid signature" even when the key, nonce, and message all matched. Test helpers now sign with the spec encoding, and the sandbox integration test signs without callbackUrl while the request includes it, matching real wallet behavior.
+
+New sandbox integration tests run the full quantum flow against a local nearcore sandbox node (near-kit's `Sandbox`, nearcore 2.13.4, skipped when the binary is unavailable): quantum-signed SIWN login, session gas-key bootstrap signed by the ML-DSA parent key, sponsor funding via `/near/gas-key/fund`, a gasless write signed by the gas key on its own nonce lane, and a quantum-signed delegate relayed through `/near/relay`. Also aligns the `relayedTransaction` test schema with the production migration (`gasUsed`/`updatedAt` nullable).
+
+Sign-in nonces are now issued by the server (`/near/nonce`, server clock) instead of being generated from the user's device clock, so a device clock ahead of the server no longer fails login outright; the client falls back to a local nonce if the endpoint is unavailable. `accountId` on the nonce request is now optional (omit it to get a nonce before the wallet account is known). Nonce freshness validation tolerates up to 60s of future skew (previously any future timestamp was rejected), applied to both the ed25519 (via `nonceValidation: "none"` + local check) and ML-DSA-65 paths. Verify failures now return distinct error codes — `UNAUTHORIZED_NONCE_EXPIRED`, `UNAUTHORIZED_NONCE_FROM_FUTURE`, `UNAUTHORIZED_SIGNATURE_INVALID`, `UNAUTHORIZED_PUBLIC_KEY_INVALID`, `UNAUTHORIZED_ACCESS_KEY_NOT_FOUND`, `UNAUTHORIZED_NOT_FULL_ACCESS_KEY`, `VERIFY_RPC_ERROR` — instead of a single blanket "Invalid signature", and the client propagates those codes to `onError` callbacks.

.github/workflows/ci.yml

@@ -370,6 +370,19 @@ jobs:
       - name: Test everything-dev
         run: pnpm --filter everything-dev test
 
+      - name: Get near-kit version
+        id: near-kit
+        working-directory: packages/better-near-auth
+        run: echo "version=$(node -p "require('near-kit/package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Cache near-sandbox binary
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5 (Node 24)
+        with:
+          path: ~/.near-kit/sandbox/bin
+          key: ${{ runner.os }}-near-sandbox-${{ steps.near-kit.outputs.version }}
+          restore-keys: |
+            ${{ runner.os }}-near-sandbox-
+
       - name: Test better-near-auth
         run: pnpm --filter better-near-auth test
 

packages/better-near-auth/README.md

@@ -326,7 +326,14 @@ interface AuthCallbacks {
 | Code | Description |
 |---|---|
 | `UNAUTHORIZED_NONCE_REPLAY` | Nonce already used (replay attack detected) |
-| `UNAUTHORIZED` | Generic auth failure (invalid signature, account mismatch, etc.) |
+| `UNAUTHORIZED_NONCE_EXPIRED` | Nonce timestamp older than the freshness window |
+| `UNAUTHORIZED_NONCE_FROM_FUTURE` | Nonce timestamp more than 60s ahead of the server clock (device clock wrong) |
+| `UNAUTHORIZED_SIGNATURE_INVALID` | NEP-413 signature failed verification |
+| `UNAUTHORIZED_PUBLIC_KEY_INVALID` | Public key malformed (bad encoding or wrong length) |
+| `UNAUTHORIZED_ACCESS_KEY_NOT_FOUND` | Signing key not found on the account on-chain |
+| `UNAUTHORIZED_NOT_FULL_ACCESS_KEY` | Signing key is not a full access key |
+| `VERIFY_RPC_ERROR` | On-chain access-key lookup failed (RPC unavailable) |
+| `UNAUTHORIZED` | Generic auth failure (account mismatch, recipient mismatch, etc.) |
 
 ### Server Endpoints
 
@@ -420,7 +427,8 @@ The plugin detects the network from the account ID:
 ## Security
 
 ### NEP-413 Compliance
-- Proper nonce handling prevents replay attacks
+- Nonces are issued by the server (`/near/nonce`, server clock) during sign-in, so client/server clock skew cannot fail login; the client falls back to a local nonce if the endpoint is unavailable
+- Nonce freshness tolerates up to 60s of future clock skew; older timestamps are rejected with `UNAUTHORIZED_NONCE_EXPIRED`, future timestamps beyond the tolerance with `UNAUTHORIZED_NONCE_FROM_FUTURE`
 - Message format and recipient validation
 - 15-minute server-side nonce expiration with DB replay detection
 
@@ -436,7 +444,7 @@ The plugin detects the network from the account ID:
 - Configurable validation for limited access keys
 
 ### Post-Quantum Keys
-- `ml-dsa-65:` (FIPS 204) full-access keys are accepted on `/api/auth/near/verify` and `/api/auth/near/link-account`. Signature verification is delegated to `@noble/post-quantum`'s `ml_dsa65.verify`, while the on-chain access-key check stays the same as ed25519. The NEP-413 SHA-256 + borsh payload format is unchanged from the ed25519 path.
+- `ml-dsa-65:` (FIPS 204) full-access keys are accepted on `/api/auth/near/verify` and `/api/auth/near/link-account`. Signature verification is delegated to `@noble/post-quantum`'s `ml_dsa65.verify`, while the on-chain access-key check stays the same as ed25519. The NEP-413 payload uses true borsh serialization (1-byte Option discriminant for `callback_url`), matching Rust wallets.
 
 ## Troubleshooting
 

packages/better-near-auth/src/client.ts

@@ -495,13 +495,58 @@ export const siwnClient = (config: SIWNClientConfig) => {
     });
   };
 
-  const signWithWallet = async (): Promise<SignWithWalletResult> => {
+  const errorWithCode = (
+    message: string,
+    response: {
+      error?: {
+        code?: string;
+        status?: number;
+        error?: { code?: string; status?: number };
+        body?: { code?: string; status?: number };
+      } | null;
+    },
+    fallback: string,
+  ): Error & { code?: string; status?: number } => {
+    const err = new Error(message || fallback) as Error & { code?: string; status?: number };
+    const fe = response.error;
+    err.code = fe?.code ?? fe?.error?.code ?? fe?.body?.code;
+    err.status = fe?.status ?? fe?.error?.status ?? fe?.body?.status;
+    return err;
+  };
+
+  const fetchServerNonce = async (
+    $fetch: BetterFetch,
+    net: NearNetwork,
+    accountId?: string,
+  ): Promise<{ nonceBytes: Uint8Array; nonceHex: string; serverIssued: boolean }> => {
+    try {
+      const response = await $fetch<{ nonce: string }>("/near/nonce", {
+        method: "POST",
+        body: accountId ? { accountId, networkId: net } : { networkId: net },
+      });
+      if (response.error || !response.data?.nonce) {
+        throw new Error(response.error?.message || "nonce endpoint unavailable");
+      }
+      return {
+        nonceBytes: hex.decode(response.data.nonce),
+        nonceHex: response.data.nonce,
+        serverIssued: true,
+      };
+    } catch (error) {
+      console.warn(
+        "[siwn] Server nonce unavailable, falling back to local clock nonce:",
+        error instanceof Error ? error.message : error,
+      );
+      const nonceBytes = generateNonce();
+      return { nonceBytes, nonceHex: hex.encode(nonceBytes), serverIssued: false };
+    }
+  };
+
+  const signWithWallet = async ($fetch: BetterFetch): Promise<SignWithWalletResult> => {
     const net = activeNetwork.get();
     const conn = await requireConnector(net);
     const recipient = getRecipient(net);
 
-    const nonceBytes = generateNonce();
-    const nonceHex = hex.encode(nonceBytes);
     const message = `Sign in to ${recipient}`;
     const callbackUrl = typeof window === "undefined" ? undefined : window.location.href;
 
@@ -519,20 +564,26 @@ export const siwnClient = (config: SIWNClientConfig) => {
       throw new Error("NEAR network changed while connecting wallet");
     }
 
+    let nonce: { nonceBytes: Uint8Array; nonceHex: string } | null = null;
     if (connectedWallet?.accounts?.length) {
       const accountId: string = connectedWallet.accounts[0]!.accountId;
       const isTestnetAccount = accountId.endsWith(".testnet");
       const isExpectedNetwork = (net === "testnet") === isTestnetAccount;
       if (!isExpectedNetwork) {
         connectedWallet = null;
+      } else {
+        nonce = await fetchServerNonce($fetch, net, accountId);
       }
     }
+    if (!nonce) {
+      nonce = await fetchServerNonce($fetch, net);
+    }
 
     if (connectedWallet?.accounts?.length) {
       const signMessageParams: SignMessageParamsWithCallback = {
         message,
         recipient,
-        nonce: nonceBytes,
+        nonce: nonce.nonceBytes,
         network: net,
         callbackUrl,
       };
@@ -546,7 +597,7 @@ export const siwnClient = (config: SIWNClientConfig) => {
         signedMessage,
         accountId: signedMessage.accountId,
         publicKey: signedMessage.publicKey,
-        nonceHex,
+        nonceHex: nonce.nonceHex,
         callbackUrl,
       };
     }
@@ -573,7 +624,7 @@ export const siwnClient = (config: SIWNClientConfig) => {
         signMessageParams: {
           message,
           recipient,
-          nonce: nonceBytes,
+          nonce: nonce.nonceBytes,
           callbackUrl,
         } as SignMessageParamsWithCallback,
       });
@@ -593,7 +644,7 @@ export const siwnClient = (config: SIWNClientConfig) => {
       signedMessage: result.value.signedMessage,
       accountId: result.value.accountId,
       publicKey: result.value.publicKey,
-      nonceHex,
+      nonceHex: nonce.nonceHex,
       callbackUrl,
     };
   };
@@ -969,7 +1020,8 @@ export const siwnClient = (config: SIWNClientConfig) => {
             const net = activeNetwork.get();
             const recipient = getRecipient(net);
             try {
-              const { signedMessage, accountId, nonceHex, callbackUrl } = await signWithWallet();
+              const { signedMessage, accountId, nonceHex, callbackUrl } =
+                await signWithWallet($fetch);
               const message = `Sign in to ${recipient}`;
 
               await handleAccountConnection(accountId, signedMessage.publicKey, net);
@@ -992,7 +1044,11 @@ export const siwnClient = (config: SIWNClientConfig) => {
               });
 
               if (linkResponse.error) {
-                throw new Error(linkResponse.error.message || "Failed to link NEAR account");
+                throw errorWithCode(
+                  linkResponse.error.message || "",
+                  linkResponse,
+                  "Failed to link NEAR account",
+                );
               }
 
               if (!linkResponse?.data?.success) {
@@ -1199,7 +1255,8 @@ export const siwnClient = (config: SIWNClientConfig) => {
         signIn: {
           near: async (callbacks?: AuthCallbacks, fetchOptions?: BetterFetchOption) => {
             try {
-              const { signedMessage, accountId, nonceHex, callbackUrl } = await signWithWallet();
+              const { signedMessage, accountId, nonceHex, callbackUrl } =
+                await signWithWallet($fetch);
               const net = activeNetwork.get();
               const recipient = getRecipient(net);
               const message = `Sign in to ${recipient}`;
@@ -1223,7 +1280,11 @@ export const siwnClient = (config: SIWNClientConfig) => {
               );
 
               if (verifyResponse.error) {
-                throw new Error(verifyResponse.error.message || "Failed to verify signature");
+                throw errorWithCode(
+                  verifyResponse.error.message || "",
+                  verifyResponse,
+                  "Failed to verify signature",
+                );
               }
 
               if (!verifyResponse?.data?.success) {

packages/better-near-auth/src/gas-key-routes.test.ts

@@ -52,7 +52,8 @@ let nonceCounter = 0;
 function makeUniqueNonce(): Uint8Array {
   nonceCounter++;
   const nonce = new Uint8Array(32);
-  for (let i = 0; i < 32; i++) nonce[i] = (i + 1) ^ (nonceCounter & 0xff);
+  new DataView(nonce.buffer).setBigUint64(0, BigInt(Date.now()), false);
+  for (let i = 8; i < 32; i++) nonce[i] = (i + 1) ^ (nonceCounter & 0xff);
   return nonce;
 }