@openzeppelin/guardian-client 0.19.0-rc.1 → 0.19.0-rc.2

package/src/http.ts

@@ -1,3 +1,8 @@
+import {
+  SESSION_REQUEST_AUTH_FORMAT,
+  SessionOperation,
+  isSessionWrite,
+} from './session-request.js';
 import {
   type GuardianErrorCode,
   normalizeGuardianErrorCode,
@@ -24,6 +29,7 @@ import type {
   SignatureScheme,
   Signer,
   StateObject,
+  StateTail,
   StatusResponse,
   CanonicalNonce,
 } from './types.js';
@@ -45,6 +51,7 @@ import type {
   ServerProposalsResponse,
   ServerPubkeyResponse,
   ServerStateObject,
+  ServerStateTail,
   ServerConfigureResponse,
   ServerCreateSessionResponse,
   ServerPushDeltaResponse,
@@ -61,6 +68,7 @@ import {
   fromServerHistoryPage,
   fromServerLookupResponse,
   fromServerStateObject,
+  fromServerStateTail,
   toServerConfigureRequest,
   toServerCreateSessionRequest,
   toServerDeltaProposalRequest,
@@ -281,6 +289,9 @@ function parseRetryAfterSeconds(header: string | null | undefined): number | und
  */
 const SESSION_EXPIRY_MARGIN_MS = 30_000;
 
+/** Replay rejections a request is re-signed and resent for. */
+const REPLAY_RETRIES = 2;
+
 /** Codes that end a session-signed request's session for good. */
 const SESSION_END_REASONS: Record<string, SessionEndReason> = {
   session_expired: 'expired',
@@ -292,13 +303,13 @@ const SESSION_END_REASONS: Record<string, SessionEndReason> = {
  * Which key signs a per-account request. Mirrors the server: requests are
  * wallet-signed unless the route is session-eligible.
  */
-type AuthMode = 'session' | 'wallet';
+type AuthMode = SessionOperation | 'wallet';
 
 function authHeaders(
   publicKey: string,
   signature: string,
   timestamp: number,
-  format?: 'eip712' | 'session'
+  format?: 'eip712' | typeof SESSION_REQUEST_AUTH_FORMAT
 ): Record<string, string> {
   return {
     'x-pubkey': publicKey,
@@ -480,6 +491,9 @@ export class GuardianHttpClient {
         ? {
             sessions: {
               maxTtlSeconds: data.sessions.max_ttl_seconds,
+              ...(data.sessions.request_auth_version === undefined
+                ? {}
+                : { requestAuthVersion: data.sessions.request_auth_version }),
             },
           }
         : {}),
@@ -502,11 +516,35 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/state?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetState);
     const server = (await response.json()) as ServerStateObject;
     return fromServerStateObject(server);
   }
 
+  /**
+   * The queue tail (`GET /state/tail`, issue #517): the state a new delta or
+   * proposal must build on, and the queued candidates that lead to it. With
+   * nothing queued it is the canonical state and `queue` is empty. Otherwise
+   * it is not on chain until the queued candidates land, and if one never
+   * does, the tail is abandoned with it. `acceptsSubmissions` is false while
+   * the queue would refuse anything built on the tail with
+   * `conflict_pending_delta` (a full queue, which at the default depth of 1 is
+   * any queue; a tail that changes the signers or the guardian key; a
+   * candidate a server before 0.19.0 queued under another label): wait for
+   * the queue to drain instead of building. Each read replays the queue on the
+   * server, so read it before building on the account; poll
+   * `getCanonicalNonce` instead. A server before 0.19.0 answers 404.
+   */
+  async getStateTail(accountId: string): Promise<StateTail> {
+    const requestQuery = { account_id: accountId };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/state/tail?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery, SessionOperation.GetStateTail);
+    const server = (await response.json()) as ServerStateTail;
+    return fromServerStateTail(server);
+  }
+
   /**
    * Nonce and commitment of the latest canonical state, without the state
    * blob (`GET /state/nonce`). A client can skip `getState` when the
@@ -519,7 +557,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/state/nonce?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetCanonicalNonce);
     const server = (await response.json()) as ServerCanonicalNonceResponse;
     return fromServerCanonicalNonce(server);
   }
@@ -546,7 +584,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetDeltaProposals);
     const data = (await response.json()) as ServerProposalsResponse;
     return data.proposals.map(fromServerDeltaObject);
   }
@@ -556,7 +594,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal/single?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetDeltaProposal);
     const data = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(data);
   }
@@ -566,7 +604,7 @@ export class GuardianHttpClient {
     const response = await this.fetchAuthenticated('/delta/proposal', {
       method: 'POST',
       body: JSON.stringify(serverRequest),
-    }, request.accountId, serverRequest, 'session');
+    }, request.accountId, serverRequest, SessionOperation.PushDeltaProposal);
     const server = (await response.json()) as ServerDeltaProposalResponse;
     return {
       delta: fromServerDeltaObject(server.delta),
@@ -591,7 +629,7 @@ export class GuardianHttpClient {
     const response = await this.fetchSigned('/delta/proposal/execution', {
       method: 'POST',
       body: JSON.stringify(serverRequest),
-    }, accountId, RequestAuthPayload.forOperation('ExecuteDeltaProposal', serverRequest), 'session');
+    }, accountId, RequestAuthPayload.forOperation('ExecuteDeltaProposal', serverRequest), SessionOperation.ExecuteDeltaProposal);
     return fromServerExecution((await response.json()) as ServerProposalExecution);
   }
 
@@ -601,7 +639,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal/execution?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetDeltaProposalExecution);
     return fromServerExecution((await response.json()) as ServerProposalExecution);
   }
 
@@ -611,7 +649,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/execution/current?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetCurrentExecution);
     const server = (await response.json()) as ServerCurrentExecution;
     return server.execution === null ? null : fromServerExecution(server.execution);
   }
@@ -721,7 +759,7 @@ export class GuardianHttpClient {
     const response = await this.fetchAuthenticated('/delta/proposal', {
       method: 'PUT',
       body: JSON.stringify(serverRequest),
-    }, request.accountId, serverRequest, 'session');
+    }, request.accountId, serverRequest, SessionOperation.SignDeltaProposal);
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -743,7 +781,7 @@ export class GuardianHttpClient {
       init,
       delta.accountId,
       serverDelta,
-      'session'
+      SessionOperation.PushDelta
     ).catch((err: unknown) => {
       if (err instanceof GuardianHttpError && err.code === 'wallet_signature_required') {
         return this.fetchAuthenticated('/delta', init, delta.accountId, serverDelta, 'wallet');
@@ -773,7 +811,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload, 'session');
+    }, accountId, requestPayload, SessionOperation.GetDelta);
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -790,7 +828,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/since?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload, 'session');
+    }, accountId, requestPayload, SessionOperation.GetDeltaSince);
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -817,7 +855,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestPayload);
     const response = await this.fetchAuthenticated(`/delta/history?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload, 'session');
+    }, accountId, requestPayload, SessionOperation.GetDeltaHistory);
     const server = (await response.json()) as ServerHistoryPage;
     return fromServerHistoryPage(server);
   }
@@ -894,19 +932,55 @@ export class GuardianHttpClient {
     init: RequestInit,
     accountId: string,
     authPayload: RequestAuthPayload,
-    mode: AuthMode,
-    retries = 2
+    mode: AuthMode
   ): Promise<Response> {
-    const timestamp = this.nextTimestamp();
-    const session = mode === 'session' ? this.getSession() : null;
-    const headers = session
+    for (;;) {
+      const session = mode === 'wallet' ? null : this.getSession();
+      const response =
+        session && mode !== 'wallet' && isSessionWrite(mode)
+          ? await session.writeSequencer.run(accountId, () =>
+              this.sendSigned(path, init, accountId, authPayload, mode, session)
+            )
+          : await this.sendSigned(path, init, accountId, authPayload, mode, session);
+      if (response) {
+        return response;
+      }
+    }
+  }
+
+  /**
+   * Signs with `session` (the wallet when null) and retries replay
+   * rejections. Returns null, without sending, once `session` is no longer
+   * this client's session: a session write only ever signs within the write
+   * turn of the session it holds, and the caller starts over with the
+   * current one.
+   */
+  private async sendSigned(
+    path: string,
+    init: RequestInit,
+    accountId: string,
+    authPayload: RequestAuthPayload,
+    mode: AuthMode,
+    session: SessionRequestSigner | null,
+    retries = REPLAY_RETRIES
+  ): Promise<Response | null> {
+    if (session && this.getSession() !== session) {
+      return null;
+    }
+    const timestamp = session
+      ? await session.nextTimestamp(accountId, retries < REPLAY_RETRIES)
+      : this.nextTimestamp();
+    const headers = session && mode !== 'wallet'
       ? authHeaders(
           session.publicKey,
-          await session.signRequest(accountId, timestamp, authPayload),
+          await session.signRequest(mode, accountId, timestamp, authPayload),
           timestamp,
-          'session'
+          SESSION_REQUEST_AUTH_FORMAT
         )
       : await this.walletAuthHeaders(accountId, timestamp, authPayload);
+    if (session && this.getSession() !== session) {
+      return null;
+    }
 
     try {
       return await this.fetch(path, {
@@ -939,7 +1013,7 @@ export class GuardianHttpClient {
         err.code === 'authentication_replay'
       ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
-        return this.fetchSigned(path, init, accountId, authPayload, mode, retries - 1);
+        return this.sendSigned(path, init, accountId, authPayload, mode, session, retries - 1);
       }
       throw err;
     }

package/src/index.ts

@@ -7,6 +7,20 @@ export {
 } from './error-codes.js';
 export type { GuardianErrorCode } from './error-codes.js';
 export { RequestAuthPayload } from './auth-request.js';
+export {
+  SESSION_REQUEST_AUTH_FORMAT,
+  SESSION_REQUEST_ENVELOPE_LENGTH,
+  SESSION_REQUEST_VERSION,
+  SESSION_TIMESTAMP_MAX_AHEAD_MS,
+  SessionOperation,
+  SessionTimestamps,
+  WriteSequencer,
+  isSessionWrite,
+  SessionTransport,
+  UnsupportedAuthVersionError,
+  assertSupportedSessionPolicy,
+  sessionRequestEnvelope,
+} from './session-request.js';
 export type { SignedOperation } from './auth-request.js';
 export {
   ENVELOPE_FORMAT_VERSION,
@@ -56,6 +70,8 @@ export type {
   DeltaObject,
   ExecutionDelta,
   StateObject,
+  StateTail,
+  QueuedCandidate,
   ProposalType,
   ProposalMetadata,
   ConfigureRequest,

package/src/request-envelope.test.ts

@@ -2,10 +2,10 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { describe, it, expect } from 'vitest';
-import { sealTransactionRequest } from './request-envelope.js';
+import { PROTOCOL_LINE, sealTransactionRequest } from './request-envelope.js';
 
 describe('sealTransactionRequest', () => {
-  it('produces the envelope the Rust SDK and the server produce for the same bytes', async () => {
+  it('seals bytes with this SDK\'s protocol line, checksum and base64 body', async () => {
     const envelope = await sealTransactionRequest(new TextEncoder().encode('abc'));
     expect(envelope).toEqual({
       format_version: 1,
@@ -17,7 +17,7 @@ describe('sealTransactionRequest', () => {
 });
 
 describe('the shared envelope fixture', () => {
-  it('seals to the envelope the Rust SDK and the server produce', async () => {
+  it('seals to the shared vector for this SDK\'s protocol line', async () => {
     const fixture = JSON.parse(
       readFileSync(
         join(dirname(fileURLToPath(import.meta.url)), '../../../fixtures/miden-multisig-client/request-envelope.json'),
@@ -25,6 +25,6 @@ describe('the shared envelope fixture', () => {
       ),
     );
     const bytes = Uint8Array.from(Buffer.from(fixture.bytes_hex, 'hex'));
-    expect(await sealTransactionRequest(bytes)).toEqual(fixture.sealed);
+    expect(await sealTransactionRequest(bytes)).toEqual(fixture.sealed[PROTOCOL_LINE]);
   });
 });

package/src/request-envelope.ts

@@ -1,12 +1,12 @@
 /**
  * The envelope a Guardian-executable proposal stores its serialized `TransactionRequest` in.
  * Mirrors `guardian_shared::request_envelope`; the same bytes seal to the same envelope in both
- * SDKs.
+ * SDKs, apart from the protocol line each one declares.
  */
 
 export const ENVELOPE_FORMAT_VERSION = 1;
 
-/** The Miden protocol line requests are serialized for, as `MAJOR.MINOR`. */
+/** The Miden protocol line this SDK serializes requests for, as `MAJOR.MINOR`: that of its web SDK pin. */
 export const PROTOCOL_LINE = '0.17';
 
 /** Wire form: snake_case, exactly as the server stores it. */

package/src/server-types.ts

@@ -122,6 +122,18 @@ export interface ServerStateObject {
   auth_scheme?: string;
 }
 
+export interface ServerQueuedCandidate {
+  nonce: number;
+  prev_commitment: string;
+  new_commitment: string;
+}
+
+export interface ServerStateTail {
+  state: ServerStateObject;
+  queue: ServerQueuedCandidate[];
+  accepts_submissions: boolean;
+}
+
 export interface ServerCanonicalNonceResponse {
   account_id: string;
   nonce: number;
@@ -159,6 +171,7 @@ export interface ServerDeltaProposalRequest {
     signatures: Array<{ signer_id: string; signature: ServerProposalSignature }>;
     metadata?: ServerProposalMetadata;
     transaction_request?: TransactionRequestEnvelope;
+    base_commitment?: string;
   };
 }
 
@@ -206,6 +219,7 @@ export interface ServerStatusResponse {
   execution?: ServerExecutionCapabilityWire | null;
   sessions?: {
     max_ttl_seconds: number;
+    request_auth_version?: number;
   };
 }
 
@@ -228,6 +242,7 @@ export interface ServerCreateSessionRequest {
 export interface ServerCreateSessionResponse {
   signer_commitment: string;
   expires_at: string;
+  request_auth_version?: number;
 }
 
 export interface ServerRevokeSessionResponse {

package/src/session-request.test.ts

@@ -0,0 +1,178 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import {
+  SESSION_TIMESTAMP_MAX_AHEAD_MS,
+  SessionTimestamps,
+  WriteSequencer,
+  isSessionWrite,
+  SESSION_REQUEST_AUTH_FORMAT,
+  SESSION_REQUEST_VERSION,
+  SessionOperation,
+  sessionRequestEnvelope,
+  type SessionTransport,
+} from './session-request.js';
+
+interface RequestVector {
+  name: string;
+  transport: number;
+  operation: number;
+  request_word_hex: string;
+  envelope_hex: string;
+}
+
+interface Fixture {
+  auth_format: string;
+  version: number;
+  operations: Array<{ id: number; name: string; replay_policy: string }>;
+  vectors: RequestVector[];
+}
+
+const fixture = JSON.parse(
+  readFileSync(
+    new URL('../../../crates/shared/tests/fixtures/session_request_vectors.json', import.meta.url),
+    'utf8'
+  )
+) as Fixture;
+
+const fromHex = (hex: string): Uint8Array =>
+  Uint8Array.from(Buffer.from(hex.replace(/^0x/, ''), 'hex'));
+
+describe('session request envelope', () => {
+  it('matches the Rust format, version and operation registry', () => {
+    expect(SESSION_REQUEST_AUTH_FORMAT).toBe(fixture.auth_format);
+    expect(SESSION_REQUEST_VERSION).toBe(fixture.version);
+    expect(
+      Object.entries(SessionOperation).map(([name, id]) => ({ id, name }))
+    ).toEqual(fixture.operations.map(({ id, name }) => ({ id, name })));
+  });
+
+  it('classifies writes as the Rust registry does', () => {
+    for (const { id, name, replay_policy } of fixture.operations) {
+      expect(isSessionWrite(id as SessionOperation), name).toBe(replay_policy === 'write');
+    }
+  });
+
+  it('encodes every vector byte for byte', () => {
+    for (const vector of fixture.vectors) {
+      const envelope = sessionRequestEnvelope(
+        vector.transport as SessionTransport,
+        vector.operation as SessionOperation,
+        fromHex(vector.request_word_hex)
+      );
+      expect(Buffer.from(envelope).toString('hex'), vector.name).toBe(
+        vector.envelope_hex.replace(/^0x/, '')
+      );
+    }
+  });
+
+  it('refuses a request word of the wrong length', () => {
+    expect(() =>
+      sessionRequestEnvelope(1, SessionOperation.GetState, new Uint8Array(31))
+    ).toThrow();
+  });
+});
+
+describe('SessionTimestamps', () => {
+  const NOW = 1_800_000_000_000;
+
+  it('gives equal clock readings distinct timestamps', async () => {
+    const timestamps = new SessionTimestamps(() => NOW);
+    expect(await timestamps.next('0xa')).toBe(NOW);
+    expect(await timestamps.next('0xa')).toBe(NOW + 1);
+  });
+
+  it('keeps accounts independent', async () => {
+    const timestamps = new SessionTimestamps(() => NOW);
+    for (let i = 0; i < 500; i++) {
+      await timestamps.next('0xa');
+    }
+    expect(await timestamps.next('0xb')).toBe(NOW);
+  });
+
+  it('waits instead of running more than a second ahead of the clock', async () => {
+    let now = NOW;
+    const timestamps = new SessionTimestamps(() => now);
+    for (let i = 0; i <= SESSION_TIMESTAMP_MAX_AHEAD_MS; i++) {
+      await timestamps.next('0xa');
+    }
+    const pending = timestamps.next('0xa');
+    now = NOW + 1;
+    expect(await pending).toBe(NOW + SESSION_TIMESTAMP_MAX_AHEAD_MS + 1);
+  });
+
+  it('never gives two waiting callers the same timestamp', async () => {
+    let now = NOW;
+    const timestamps = new SessionTimestamps(() => now);
+    for (let i = 0; i <= SESSION_TIMESTAMP_MAX_AHEAD_MS; i++) {
+      await timestamps.next('0xa');
+    }
+    const waiting = Array.from({ length: 50 }, () => timestamps.next('0xa'));
+    const ticker = setInterval(() => {
+      now += 1;
+    }, 1);
+    const issued = await Promise.all(waiting);
+    clearInterval(ticker);
+    expect(new Set(issued).size).toBe(issued.length);
+    for (const timestamp of issued) {
+      expect(timestamp).toBeGreaterThan(NOW + SESSION_TIMESTAMP_MAX_AHEAD_MS);
+    }
+  });
+
+  it('restarts from the clock when it steps back instead of waiting', async () => {
+    let now = NOW;
+    const timestamps = new SessionTimestamps(() => now);
+    expect(await timestamps.next('0xa')).toBe(NOW);
+    now = NOW - 10 * 60 * 1000;
+    expect(await timestamps.next('0xa')).toBe(now);
+    expect(await timestamps.next('0xa')).toBe(now + 1);
+  });
+
+  it('jumps near the ahead limit after a replay rejection', async () => {
+    const timestamps = new SessionTimestamps(() => NOW);
+    expect(await timestamps.next('0xa')).toBe(NOW);
+    const retried = await timestamps.next('0xa', true);
+    expect(retried).toBeGreaterThan(NOW + 1_000 - 200 - 1);
+    expect(retried).toBeLessThanOrEqual(NOW + 1_000);
+    expect(await timestamps.next('0xb')).toBe(NOW);
+  });
+});
+
+describe('WriteSequencer', () => {
+  it('runs writes to one account one at a time and keeps going after a failure', async () => {
+    const sequencer = new WriteSequencer();
+    const order: string[] = [];
+    let releaseFirst!: () => void;
+    const first = sequencer.run('0xa', async () => {
+      order.push('first start');
+      await new Promise<void>((resolve) => (releaseFirst = resolve));
+      order.push('first end');
+      throw new Error('first failed');
+    });
+    const second = sequencer.run('0xa', async () => {
+      order.push('second');
+      return 2;
+    });
+    const otherAccount = sequencer.run('0xb', async () => {
+      order.push('other account');
+      return 3;
+    });
+
+    expect(await otherAccount).toBe(3);
+    expect(order).toEqual(['first start', 'other account']);
+    releaseFirst();
+    await expect(first).rejects.toThrow('first failed');
+    expect(await second).toBe(2);
+    expect(order).toEqual(['first start', 'other account', 'first end', 'second']);
+  });
+
+  it('classifies only the four write operations as writes', () => {
+    expect(
+      Object.values(SessionOperation).filter((operation) => isSessionWrite(operation))
+    ).toEqual([
+      SessionOperation.PushDelta,
+      SessionOperation.PushDeltaProposal,
+      SessionOperation.SignDeltaProposal,
+      SessionOperation.ExecuteDeltaProposal,
+    ]);
+  });
+});