@openzeppelin/miden-multisig-client 0.18.0 → 0.18.2

package/src/session/key.ts

@@ -0,0 +1,215 @@
+import type {
+  RequestAuthPayload,
+  SessionEndReason,
+  SessionRequestSigner,
+} from '@openzeppelin/guardian-client';
+import type { Word } from '@miden-sdk/miden-sdk';
+import { AuthDigest } from '../utils/digest.js';
+import { EcdsaFormat } from '../utils/ecdsa.js';
+import { bytesToHex } from '../utils/encoding.js';
+import { wordToBytes } from '../utils/word.js';
+import { sessionLogoutDigest } from './grant.js';
+
+const ALGORITHM = { name: 'ECDSA', namedCurve: 'P-256' } as const;
+const SIGNATURE = { name: 'ECDSA', hash: 'SHA-256' } as const;
+
+function subtle(): SubtleCrypto {
+  if (!globalThis.crypto?.subtle) {
+    throw new Error('Guardian sessions require WebCrypto (crypto.subtle)');
+  }
+  return globalThis.crypto.subtle;
+}
+
+/**
+ * A P-256 session key whose private half is a non-extractable WebCrypto key:
+ * page scripts can use it to sign while it is loaded, but can never read or
+ * export it.
+ */
+export class WebCryptoSessionKey {
+  constructor(
+    readonly privateKey: CryptoKey,
+    /** Hex SEC1-compressed public key. */
+    readonly publicKey: string,
+  ) {}
+
+  static async generate(): Promise<WebCryptoSessionKey> {
+    const pair = await subtle().generateKey(ALGORITHM, false, ['sign', 'verify']);
+    const raw = new Uint8Array(await subtle().exportKey('raw', pair.publicKey));
+    return new WebCryptoSessionKey(pair.privateKey, EcdsaFormat.compressPublicKey(bytesToHex(raw)));
+  }
+
+  /** Sign the 32 bytes of a word: ECDSA P-256 over SHA-256, `r || s` hex. */
+  async signWord(word: Word): Promise<string> {
+    const message = new Uint8Array(wordToBytes(word));
+    const signature = await subtle().sign(SIGNATURE, this.privateKey, message);
+    return bytesToHex(new Uint8Array(signature));
+  }
+}
+
+export interface GuardianSessionOptions {
+  /** The store keeping this session's key; its record is removed when the session ends. */
+  store?: SessionKeyStore;
+  /**
+   * Called once when the Guardian client stops using the session. Requests
+   * are then signed by the wallet again. On `expired`, `revoked` or
+   * `rejected`, start a new session to stop the prompts; `logout` means the
+   * app ended it itself (logout, revoke-all or a replacement session).
+   */
+  onEnded?: (reason: SessionEndReason, session: GuardianSession) => void;
+}
+
+/**
+ * Signs Guardian requests for a wallet after its session grant was
+ * registered. Plug into `GuardianHttpClient.setSession`.
+ */
+export class GuardianSession implements SessionRequestSigner {
+  constructor(
+    private readonly key: WebCryptoSessionKey,
+    /** Commitment of the wallet that signed the grant. */
+    readonly signerCommitment: string,
+    /** Unix seconds. */
+    readonly expiresAt: number,
+    /** Where a `SessionKeyStore` keeps this session's key. */
+    readonly storeId: string,
+    private readonly options: GuardianSessionOptions = {},
+  ) {}
+
+  get publicKey(): string {
+    return this.key.publicKey;
+  }
+
+  /**
+   * Forgets the stored key (best effort: a dead key left behind fails its
+   * first request after a reload and ends then) and tells the app.
+   */
+  onEnded(reason: SessionEndReason): void {
+    if (this.options.store) {
+      void forgetSessionKey(this.options.store, this).catch(() => undefined);
+    }
+    this.options.onEnded?.(reason, this);
+  }
+
+  signRequest(
+    accountId: string,
+    timestamp: number,
+    requestPayload: RequestAuthPayload,
+  ): Promise<string> {
+    return this.key.signWord(AuthDigest.fromRequest(accountId, timestamp, requestPayload));
+  }
+
+  signLogout(timestampMs: number): Promise<string> {
+    return this.key.signWord(sessionLogoutDigest(this.key.publicKey, timestampMs));
+  }
+}
+
+/** A session key persisted across page loads. */
+export interface StoredSessionKey {
+  /** `<guardian key commitment>:<signer commitment>`. */
+  id: string;
+  privateKey: CryptoKey;
+  publicKey: string;
+  /** Unix seconds. */
+  expiresAt: number;
+}
+
+export interface SessionKeyStore {
+  load(id: string): Promise<StoredSessionKey | null>;
+  save(record: StoredSessionKey): Promise<void>;
+  /**
+   * Remove the record `id` only if it still holds `publicKey`, as one atomic
+   * step, so a newer key another tab saved for the same wallet and Guardian is
+   * never deleted.
+   */
+  remove(id: string, publicKey: string): Promise<void>;
+}
+
+/**
+ * Remove the stored key of `session`, unless the record already holds the key
+ * of a newer session for the same wallet and Guardian.
+ */
+export async function forgetSessionKey(
+  store: SessionKeyStore,
+  session: { storeId: string; publicKey: string },
+): Promise<void> {
+  await store.remove(session.storeId, session.publicKey);
+}
+
+/**
+ * Keeps session keys in IndexedDB so a reload does not need another wallet
+ * signature. The browser stores the `CryptoKey` object itself; it stays
+ * non-extractable.
+ */
+export class IndexedDbSessionKeyStore implements SessionKeyStore {
+  private static readonly STORE = 'sessions';
+  private database: Promise<IDBDatabase> | null = null;
+
+  constructor(private readonly databaseName = 'guardian-sessions') {}
+
+  async load(id: string): Promise<StoredSessionKey | null> {
+    const record = await this.request<StoredSessionKey | undefined>('readonly', (store) =>
+      store.get(id),
+    );
+    return record ?? null;
+  }
+
+  async save(record: StoredSessionKey): Promise<void> {
+    await this.request('readwrite', (store) => store.put(record));
+  }
+
+  async remove(id: string, publicKey: string): Promise<void> {
+    const database = await this.open();
+    return new Promise<void>((resolve, reject) => {
+      const transaction = database.transaction(IndexedDbSessionKeyStore.STORE, 'readwrite');
+      const store = transaction.objectStore(IndexedDbSessionKeyStore.STORE);
+      const lookup = store.get(id);
+      lookup.onsuccess = () => {
+        if ((lookup.result as StoredSessionKey | undefined)?.publicKey === publicKey) {
+          store.delete(id);
+        }
+      };
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () => reject(transaction.error);
+      transaction.onabort = () => reject(transaction.error);
+    });
+  }
+
+
+  private async request<T>(
+    mode: IDBTransactionMode,
+    run: (store: IDBObjectStore) => IDBRequest,
+  ): Promise<T> {
+    const database = await this.open();
+    return new Promise<T>((resolve, reject) => {
+      const transaction = database.transaction(IndexedDbSessionKeyStore.STORE, mode);
+      const request = run(transaction.objectStore(IndexedDbSessionKeyStore.STORE));
+      transaction.oncomplete = () => resolve(request.result as T);
+      transaction.onerror = () => reject(transaction.error ?? request.error);
+      transaction.onabort = () => reject(transaction.error ?? request.error);
+    });
+  }
+
+  /** Opens the database once; a failed open is retried on the next call. */
+  private open(): Promise<IDBDatabase> {
+    if (!this.database) {
+      const opening = new Promise<IDBDatabase>((resolve, reject) => {
+        if (!globalThis.indexedDB) {
+          reject(new Error('IndexedDB is not available'));
+          return;
+        }
+        const request = globalThis.indexedDB.open(this.databaseName, 1);
+        request.onupgradeneeded = () => {
+          request.result.createObjectStore(IndexedDbSessionKeyStore.STORE, { keyPath: 'id' });
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+      });
+      opening.catch(() => {
+        if (this.database === opening) {
+          this.database = null;
+        }
+      });
+      this.database = opening;
+    }
+    return this.database;
+  }
+}

package/src/session/manager.ts

@@ -0,0 +1,273 @@
+import type {
+  GuardianHttpClient,
+  SessionGrantFields,
+  Signer,
+} from '@openzeppelin/guardian-client';
+import {
+  GuardianSession,
+  type GuardianSessionOptions,
+  type SessionKeyStore,
+  type StoredSessionKey,
+  WebCryptoSessionKey,
+  forgetSessionKey,
+} from './key.js';
+
+/**
+ * A grant is shortened by this much below the Guardian's maximum lifetime so
+ * client clock drift cannot push it over the limit.
+ */
+const MAX_TTL_MARGIN_SECONDS = 60;
+
+/**
+ * Guardian accepts a grant only while it is at most this old, and only if it
+ * expires more than this far in the future.
+ */
+const GRANT_WINDOW_SECONDS = 300;
+
+/** Matches `GuardianHttpClient`: a session this close to expiry is not used. */
+const SESSION_EXPIRY_MARGIN_SECONDS = 30;
+
+/** The Guardian does not advertise sessions on `GET /status`. */
+export class GuardianSessionsUnsupportedError extends Error {
+  constructor() {
+    super('This Guardian does not accept sessions');
+    this.name = 'GuardianSessionsUnsupportedError';
+  }
+}
+
+/** `confirm` returned `false`: the user declined the grant. */
+export class SessionGrantDeclinedError extends Error {
+  constructor() {
+    super('Session grant was declined');
+    this.name = 'SessionGrantDeclinedError';
+  }
+}
+
+export interface StartSessionOptions extends Pick<GuardianSessionOptions, 'onEnded'> {
+  /**
+   * Requested lifetime, more than 300 seconds; capped below the Guardian's
+   * advertised maximum.
+   */
+  ttlSeconds?: number;
+  /**
+   * The website asking for the session, shown to the user by the wallet.
+   * Defaults to the page's `location.origin` in a browser and to none
+   * elsewhere. Guardian does not check it against requests.
+   */
+  origin?: string;
+  /**
+   * Called with the grant before the wallet signs it; return `false` to
+   * abort. Required for raw (non-EIP-712) wallets, which show only a hash:
+   * display {@link describeSessionGrant} to the user here.
+   */
+  confirm?: (grant: SessionGrantFields) => boolean | Promise<boolean>;
+  /** Persist the session key so a reload can `resume` without the wallet. */
+  store?: SessionKeyStore;
+}
+
+/** The current page's origin in a browser; empty elsewhere. */
+function pageOrigin(): string {
+  const location = (globalThis as { location?: { origin?: string } }).location;
+  return location?.origin && location.origin !== 'null' ? location.origin : '';
+}
+
+function storeId(guardianCommitment: string, signerCommitment: string): string {
+  return `${guardianCommitment.toLowerCase()}:${signerCommitment.toLowerCase()}`;
+}
+
+function nowSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+/**
+ * Start a Guardian session: `signer` signs one grant and, once the session is
+ * registered, becomes `guardian`'s signer; a non-extractable P-256 delegated
+ * signer then signs the
+ * session-eligible requests on `guardian` (reads, proposal list/get, proposal
+ * create/sign). Every other route, including `configure`, `pushDelta`,
+ * `abandonCandidate`, account lookup and `revokeAllSessions`, keeps using the
+ * wallet. A session already set on `guardian` is replaced but stays valid on
+ * the server until it expires; end it first with {@link endGuardianSession}.
+ *
+ * The grant is dated after `confirm` returns, so a slow confirmation still
+ * registers; only its start moves, the confirmed expiry stays. If storing the
+ * key fails, the registered session is logged out and the error rethrown.
+ */
+export async function startGuardianSession(
+  guardian: GuardianHttpClient,
+  signer: Signer,
+  options: StartSessionOptions = {},
+): Promise<GuardianSession> {
+  if (!signer.signSessionGrant) {
+    throw new Error('This signer cannot sign Guardian session grants');
+  }
+  if (signer.requestAuthFormat !== 'eip712' && !options.confirm) {
+    throw new Error(
+      'This wallet signs a session grant as a hash: pass `confirm` and show ' +
+        'describeSessionGrant(grant) to the user first',
+    );
+  }
+  const [status, { commitment: guardianCommitment }, key] = await Promise.all([
+    guardian.getStatus(),
+    guardian.getPubkey(signer.scheme),
+    WebCryptoSessionKey.generate(),
+  ]);
+  if (!status.sessions) {
+    throw new GuardianSessionsUnsupportedError();
+  }
+  const maxTtl = status.sessions.maxTtlSeconds - MAX_TTL_MARGIN_SECONDS;
+  const ttl = Math.min(options.ttlSeconds ?? maxTtl, maxTtl);
+  if (!Number.isInteger(ttl) || ttl <= GRANT_WINDOW_SECONDS) {
+    throw new Error(
+      `Session lifetime must be a whole number of seconds above ${GRANT_WINDOW_SECONDS}`,
+    );
+  }
+
+  const issuedAt = nowSeconds();
+  let grant: SessionGrantFields = {
+    signerCommitment: signer.commitment,
+    sessionPublicKey: key.publicKey,
+    origin: options.origin ?? pageOrigin(),
+    issuedAt,
+    expiresAt: issuedAt + ttl,
+    guardianCommitment,
+    network: status.environment,
+  };
+  if (options.confirm) {
+    if (!(await options.confirm(grant))) {
+      throw new SessionGrantDeclinedError();
+    }
+    grant = { ...grant, issuedAt: Math.max(issuedAt, nowSeconds()) };
+    if (grant.expiresAt - grant.issuedAt <= GRANT_WINDOW_SECONDS) {
+      throw new Error('The session grant was confirmed too late; start the session again');
+    }
+  }
+  const signature = await signer.signSessionGrant(grant);
+  if (nowSeconds() - grant.issuedAt > GRANT_WINDOW_SECONDS) {
+    throw new Error(
+      `The wallet took more than ${GRANT_WINDOW_SECONDS} seconds to sign the session grant; ` +
+        'start the session again',
+    );
+  }
+  await guardian.createSession({
+    scheme: signer.scheme,
+    ...(signer.requestAuthFormat === 'eip712' ? { authFormat: 'eip712' as const } : {}),
+    ...(signer.scheme === 'ecdsa' ? { publicKey: signer.publicKey } : {}),
+    signature,
+    grant,
+  });
+
+  const session = new GuardianSession(
+    key,
+    signer.commitment,
+    grant.expiresAt,
+    storeId(guardianCommitment, signer.commitment),
+    { store: options.store, onEnded: options.onEnded },
+  );
+  if (options.store) {
+    try {
+      await options.store.save({
+        id: session.storeId,
+        privateKey: key.privateKey,
+        publicKey: key.publicKey,
+        expiresAt: grant.expiresAt,
+      });
+    } catch (error) {
+      const unreachable = new GuardianSession(key, signer.commitment, grant.expiresAt, session.storeId);
+      await guardian.revokeSession(unreachable).catch(() => false);
+      throw error;
+    }
+  }
+  guardian.setSigner(signer);
+  guardian.setSession(session);
+  return session;
+}
+
+/**
+ * Reuse a session key persisted by `startGuardianSession` without asking the
+ * wallet again; `signer` becomes `guardian`'s signer when a session resumes.
+ * Returns `null` when none
+ * is stored or it expires within 30 seconds. A session revoked elsewhere
+ * fails its next request with `session_revoked` and ends then (`onEnded`);
+ * start a new one.
+ */
+export async function resumeGuardianSession(
+  guardian: GuardianHttpClient,
+  signer: Signer,
+  store: SessionKeyStore,
+  options: Pick<GuardianSessionOptions, 'onEnded'> = {},
+): Promise<GuardianSession | null> {
+  const { commitment: guardianCommitment } = await guardian.getPubkey(signer.scheme);
+  const id = storeId(guardianCommitment, signer.commitment);
+  const record = await store.load(id);
+  if (!record) {
+    return null;
+  }
+  if (record.expiresAt - SESSION_EXPIRY_MARGIN_SECONDS <= nowSeconds()) {
+    await store.remove(id, record.publicKey);
+    return null;
+  }
+  const session = new GuardianSession(
+    new WebCryptoSessionKey(record.privateKey, record.publicKey),
+    signer.commitment,
+    record.expiresAt,
+    id,
+    { store, onEnded: options.onEnded },
+  );
+  guardian.setSigner(signer);
+  guardian.setSession(session);
+  return session;
+}
+
+/**
+ * Revoke `session` on the server, stop using it if it is the current one, and
+ * forget its stored key. Returns whether the server still had it active. On
+ * error nothing changes.
+ */
+export async function endGuardianSession(
+  guardian: GuardianHttpClient,
+  session: GuardianSession,
+  store?: SessionKeyStore,
+): Promise<boolean> {
+  const revoked = await guardian.revokeSession(session);
+  if (store) {
+    await forgetSessionKey(store, session);
+  }
+  return revoked;
+}
+
+/**
+ * Revoke every session of `signer` on the Guardian with a wallet signature,
+ * including sessions started in other tabs or devices, stop using the current
+ * one, and forget its stored key (a newer key another tab stored meanwhile
+ * is kept). `signer` becomes `guardian`'s signer. Use it when a session key
+ * may be compromised: page logout alone cannot stop a script that holds the
+ * key. Returns how many sessions the server revoked.
+ *
+ * It ends sessions already registered with Guardian. A page that got a grant
+ * signed can still register it for up to about 10 minutes, and a device whose
+ * clock runs behind can miss sessions started just before; run it again 10
+ * minutes later when a key may be compromised.
+ */
+export async function revokeAllGuardianSessions(
+  guardian: GuardianHttpClient,
+  signer: Signer,
+  store?: SessionKeyStore,
+): Promise<number> {
+  guardian.setSigner(signer);
+  const stored = store ? await storedKey(guardian, signer, store) : null;
+  const revoked = await guardian.revokeAllSessions();
+  if (store && stored) {
+    await forgetSessionKey(store, { storeId: stored.id, publicKey: stored.publicKey });
+  }
+  return revoked;
+}
+
+async function storedKey(
+  guardian: GuardianHttpClient,
+  signer: Signer,
+  store: SessionKeyStore,
+): Promise<StoredSessionKey | null> {
+  const { commitment: guardianCommitment } = await guardian.getPubkey(signer.scheme);
+  return store.load(storeId(guardianCommitment, signer.commitment));
+}

package/src/signers/ecdsa.ts

@@ -1,9 +1,10 @@
-import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
+import type { RequestAuthPayload, SessionGrantFields } from '@openzeppelin/guardian-client';
 import { AccountId, AuthSecretKey, type MidenClient, type Word } from '@miden-sdk/miden-sdk';
 import type { Signer, SignatureScheme } from '../types.js';
 import { bytesToHex, normalizeHexWord } from '../utils/encoding.js';
 import { AuthDigest } from '../utils/digest.js';
 import { lookupAuthDigest } from '../lookupAuth.js';
+import { sessionGrantDigest, sessionRevokeAllDigest } from '../session/grant.js';
 
 export class EcdsaSigner implements Signer {
   readonly commitment: string;
@@ -49,6 +50,16 @@ export class EcdsaSigner implements Signer {
     return this.signWord(digest);
   }
 
+  /** Sign a session grant as its raw RPO digest. */
+  async signSessionGrant(grant: SessionGrantFields): Promise<string> {
+    return this.signWord(sessionGrantDigest(grant));
+  }
+
+  /** Sign a session revoke-all as its raw RPO digest. */
+  async signSessionRevokeAll(signerCommitment: string, timestampMs: number): Promise<string> {
+    return this.signWord(sessionRevokeAllDigest(signerCommitment, timestampMs));
+  }
+
   async bindAccountKey(midenClient: MidenClient, accountId: string): Promise<void> {
     const targetAccountId = AccountId.fromHex(accountId);
     const existingAccountId = await midenClient.keystore.getAccountId(this.publicKeyCommitment);

package/src/signers/falcon.ts

@@ -1,9 +1,10 @@
-import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
+import type { RequestAuthPayload, SessionGrantFields } from '@openzeppelin/guardian-client';
 import { AccountId, AuthSecretKey, type MidenClient, type Word } from '@miden-sdk/miden-sdk';
 import type { Signer, SignatureScheme } from '../types.js';
 import { bytesToHex } from '../utils/encoding.js';
 import { AuthDigest } from '../utils/digest.js';
 import { lookupAuthDigest } from '../lookupAuth.js';
+import { sessionGrantDigest, sessionRevokeAllDigest } from '../session/grant.js';
 
 export class FalconSigner implements Signer {
   readonly commitment: string;
@@ -50,6 +51,16 @@ export class FalconSigner implements Signer {
     return this.signWord(digest);
   }
 
+  /** Sign a session grant as its raw RPO digest. */
+  async signSessionGrant(grant: SessionGrantFields): Promise<string> {
+    return this.signWord(sessionGrantDigest(grant));
+  }
+
+  /** Sign a session revoke-all as its raw RPO digest. */
+  async signSessionRevokeAll(signerCommitment: string, timestampMs: number): Promise<string> {
+    return this.signWord(sessionRevokeAllDigest(signerCommitment, timestampMs));
+  }
+
   async bindAccountKey(midenClient: MidenClient, accountId: string): Promise<void> {
     const targetAccountId = AccountId.fromHex(accountId);
     const existingAccountId = await midenClient.keystore.getAccountId(this.publicKeyCommitment);

package/src/signers/ledger.ts

@@ -1,14 +1,17 @@
 import { secp256k1 } from '@noble/curves/secp256k1';
 import { keccak_256 } from '@noble/hashes/sha3.js';
-import type { RequestAuthPayload, Signer } from '@openzeppelin/guardian-client';
+import type { RequestAuthPayload, SessionGrantFields, Signer } from '@openzeppelin/guardian-client';
 import { AuthDigest } from '../utils/digest.js';
 import { lookupAuthDigest } from '../lookupAuth.js';
 import { EcdsaFormat } from '../utils/ecdsa.js';
 import { bytesToHex, hexToBytes } from '../utils/encoding.js';
 import {
+  type GuardianTypedData,
   guardianKeyDiscoveryTypedData,
   guardianLookupTypedData,
   guardianRequestTypedData,
+  guardianSessionRevokeAllTypedData,
+  guardianSessionTypedData,
   midenTransactionTypedData,
   typedDataDigest,
 } from '../utils/eip712.js';
@@ -99,7 +102,21 @@ export class Eip712Signer implements Signer {
     return this.signTypedData(midenTransactionTypedData(wordToBytes(commitment)));
   }
 
-  private async signTypedData(data: ReturnType<typeof guardianRequestTypedData>): Promise<string> {
+  /**
+   * Sign a session grant as readable `GuardianSession` typed
+   * data, so the device shows the Guardian, network and expiry rather than a
+   * hash. Devices without registered display metadata need "Verbose EIP-712".
+   */
+  async signSessionGrant(grant: SessionGrantFields): Promise<string> {
+    return this.signTypedData(guardianSessionTypedData(grant));
+  }
+
+  /** Sign a session revoke-all as readable `GuardianSessionRevokeAll` typed data. */
+  async signSessionRevokeAll(signerCommitment: string, timestampMs: number): Promise<string> {
+    return this.signTypedData(guardianSessionRevokeAllTypedData(signerCommitment, timestampMs));
+  }
+
+  private async signTypedData(data: GuardianTypedData): Promise<string> {
     const result = await this.provider.request({
       method: 'eth_signTypedData_v4',
       params: [this.address, JSON.stringify(data)],

package/src/signers/miden-wallet.ts

@@ -1,9 +1,10 @@
-import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
+import type { RequestAuthPayload, SessionGrantFields } from '@openzeppelin/guardian-client';
 import type { Signer, SignatureScheme } from '../types.js';
 import { AuthDigest } from '../utils/digest.js';
 import { EcdsaFormat } from '../utils/ecdsa.js';
 import { bytesToHex, normalizeHexWord } from '../utils/encoding.js';
 import { lookupAuthDigest } from '../lookupAuth.js';
+import { sessionGrantDigest, sessionRevokeAllDigest } from '../session/grant.js';
 import { tryComputeEcdsaCommitmentHex } from '../utils/signature.js';
 import { wordToBytes } from '../utils/word.js';
 
@@ -128,6 +129,14 @@ export class MidenWalletSigner implements Signer {
     return candidate;
   }
 
+  /**
+   * The delegate `localAuthSigner` signs request auth, session grants and
+   * revoke-all, so Guardian must read its signatures in its format.
+   */
+  get requestAuthFormat(): 'eip712' | undefined {
+    return this.localAuthSigner?.requestAuthFormat;
+  }
+
   async signAccountIdWithTimestamp(accountId: string, timestamp: number): Promise<string> {
     if (this.localAuthSigner) {
       return this.localAuthSigner.signAccountIdWithTimestamp(accountId, timestamp);
@@ -164,6 +173,25 @@ export class MidenWalletSigner implements Signer {
     return this.signWord(digest);
   }
 
+  /**
+   * Sign a session grant. Follows the same signer as request
+   * authentication, so the session acts for the key Guardian already knows.
+   */
+  async signSessionGrant(grant: SessionGrantFields): Promise<string> {
+    if (this.localAuthSigner?.signSessionGrant) {
+      return this.localAuthSigner.signSessionGrant(grant);
+    }
+    return this.signWord(sessionGrantDigest(grant));
+  }
+
+  /** Sign a session revoke-all with the same signer as request authentication. */
+  async signSessionRevokeAll(signerCommitment: string, timestampMs: number): Promise<string> {
+    if (this.localAuthSigner?.signSessionRevokeAll) {
+      return this.localAuthSigner.signSessionRevokeAll(signerCommitment, timestampMs);
+    }
+    return this.signWord(sessionRevokeAllDigest(signerCommitment, timestampMs));
+  }
+
   private async signWord(word: { toFelts: () => Array<{ asInt: () => bigint }> }): Promise<string> {
     const bytes = wordToBytes(word);
     const signatureBytes = await this.wallet.signBytes(bytes, 'word');

package/src/signers/para.ts

@@ -1,9 +1,10 @@
-import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
+import type { RequestAuthPayload, SessionGrantFields } from '@openzeppelin/guardian-client';
 import type { Signer, SignatureScheme } from '../types.js';
 import { AuthDigest } from '../utils/digest.js';
 import { EcdsaFormat } from '../utils/ecdsa.js';
 import { hexToBytes, uint8ArrayToBase64 } from '../utils/encoding.js';
 import { lookupAuthDigest } from '../lookupAuth.js';
+import { sessionGrantDigest, sessionRevokeAllDigest } from '../session/grant.js';
 import { wordToBytes } from '../utils/word.js';
 
 export interface ParaSigningContext {
@@ -69,6 +70,16 @@ export class ParaSigner implements Signer {
     return this.signWord(digest);
   }
 
+  /** Sign a session grant as its raw RPO digest. */
+  async signSessionGrant(grant: SessionGrantFields): Promise<string> {
+    return this.signWord(sessionGrantDigest(grant));
+  }
+
+  /** Sign a session revoke-all as its raw RPO digest. */
+  async signSessionRevokeAll(signerCommitment: string, timestampMs: number): Promise<string> {
+    return this.signWord(sessionRevokeAllDigest(signerCommitment, timestampMs));
+  }
+
   private async signWord(word: { toHex: () => string; toFelts: () => Array<{ asInt: () => bigint }> }): Promise<string> {
     const messageBase64 = uint8ArrayToBase64(
       hexToBytes(EcdsaFormat.keccakDigestHex(wordToBytes(word))),

package/src/transaction/authArgs.ts

@@ -36,8 +36,8 @@ export interface MultisigRequestDraft {
  * The salt is `options.salt` or a fresh one. `approvalExpirationDelta` left
  * out means the approval never expires, the upstream default. `boundBlockNum`
  * left out binds the store's sync height, which is what a proposer wants; a
- * rebuild pins the proposal's anchor block and the expiration the summary
- * already binds.
+ * rebuild pins the block the proposal's summary binds and the expiration the
+ * summary already binds.
  *
  * The salt is moved across the WASM boundary, so a handle is built here from
  * the hex rather than taken from the caller, and nothing frees it afterwards.