@openzeppelin/miden-multisig-client 0.18.0 → 0.18.2

package/dist/recovery/transportDrain.js

@@ -1,10 +1,13 @@
 /**
  * Recovery primitives for restoring note state after device loss.
  *
- * After recovery on a fresh device the local store has no note-transport
- * cursor — and in a shared dirty store another account's sync may have
- * advanced the cursor past notes belonging to the newly recovered account.
- * The primitives here rescan sources that normal forward sync would skip.
+ * After recovery on a fresh device, or after adding a recovered account to a
+ * shared store, the account's note tag has no note-transport cursor yet.
+ * Since miden-client 0.17.1 the transport keeps one cursor per tag and scans
+ * a tag without one from the first retained note, but each sync fetches a
+ * bounded number of pages. The drain here keeps fetching until a fetch moves
+ * no tag's cursor, so a recovery flow does not have to wait for later
+ * background syncs.
  */
 import { errorMessage, isLikelyNetworkError } from '../connectivity.js';
 import { isTransientRpcError } from '../rpc/errors.js';
@@ -42,18 +45,60 @@ export const NODE_RPC_FRAGMENT = 'grpc request failed';
  */
 export const NODE_CONNECT_FRAGMENT = 'failed to connect to the Miden node';
 /**
- * The covered-tags bookkeeping key, mirror of miden-client's
- * `NOTE_TRANSPORT_COVERED_TAGS_KEY` (the JS surface does not re-export it).
- * Exported for the drift-guard test, which pins it against the shipped WASM
- * binary so a silent upstream rename cannot degrade the drain to a no-op.
+ * Mirror of the Rust SDK's `MAX_DRAIN_PASSES`: upper bound on transport
+ * fetches one drain runs. Each fetch reads up to 32 pages per request group
+ * of up to 128 tags; a backlog whose cursors still move after this many
+ * fetches is reported as a retryable failure, and the stored per-tag cursors
+ * let the next drain or sync continue from there.
+ */
+const MAX_DRAIN_PASSES = 64;
+/**
+ * miden-client's `NOTE_TRANSPORT_CURSORS_KEY`, a setting in its client-owned
+ * scope (`SettingScope::Client` = 0), which the SDK's `settings` API does not
+ * reach. Exported for the drift-guard test, which pins the key and the
+ * store layout below against the shipped SDK.
  */
-export const NOTE_TRANSPORT_COVERED_TAGS_KEY = 'note_transport_covered_tags';
+export const NOTE_TRANSPORT_CURSORS_KEY = 'note_transport_cursors';
+const CLIENT_SETTING_SCOPE = 0;
+/** The SDK's IndexedDB table for settings, keyed by `[scope, key]`. */
+const SETTINGS_TABLE = 'settings';
 /**
- * Mirror of miden-client's `Client::MAX_BACKFILL_TAGS_PER_SYNC`: upstream
- * backfills at most this many uncovered tags per transport sync, deferring
- * the remainder to the next sync.
+ * The stored per-tag note-transport cursors, as the raw bytes miden-client
+ * keeps, read from the client's IndexedDB store. Compared, never decoded: a
+ * fetch that leaves them unchanged found every tracked tag's history
+ * exhausted. Throws when the store cannot be read, which is a local-store
+ * failure the caller must see.
  */
-const MAX_BACKFILL_TAGS_PER_SYNC = 64;
+export async function readTransportCursors(midenClient) {
+    const name = await midenClient.storeIdentifier();
+    const db = await new Promise((resolve, reject) => {
+        const request = indexedDB.open(name);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+    try {
+        if (!db.objectStoreNames.contains(SETTINGS_TABLE)) {
+            throw new Error(`storage error: the store ${name} has no ${SETTINGS_TABLE} table`);
+        }
+        const row = await new Promise((resolve, reject) => {
+            const request = db
+                .transaction(SETTINGS_TABLE, 'readonly')
+                .objectStore(SETTINGS_TABLE)
+                .get([CLIENT_SETTING_SCOPE, NOTE_TRANSPORT_CURSORS_KEY]);
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+        return row?.value ?? null;
+    }
+    finally {
+        db.close();
+    }
+}
+function sameBytes(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.length === b.length && a.every((byte, index) => byte === b[index]);
+}
 /**
  * Mirror of the Rust SDK's `CONNECT_PERMANENT_SIGNALS`: connection-failure
  * wording a retry cannot fix (misconfigured endpoint, TLS/certificate
@@ -106,10 +151,8 @@ function classifyDrainFailure(err) {
     if (lower.includes(TRANSPORT_DISABLED_FRAGMENT)) {
         return { status: 'unavailable', retryable: false, reason, scanned: false };
     }
-    // The upstream convergence guard tripped (the server cursor kept advancing
-    // for 1000 iterations without an empty batch) — a server-side bug, not an
-    // honest backlog. Retryable in the sense that a rerun is safe (imports are
-    // idempotent) and succeeds once the server recovers.
+    // The upstream convergence guard of miden-client before 0.17.1, which no
+    // longer raises it. A rerun is safe (imports are idempotent).
     if (lower.includes(PAGINATION_GUARD_FRAGMENT)) {
         return { status: 'failed', retryable: true, reason, scanned: true };
     }
@@ -143,42 +186,21 @@ function classifyDrainFailure(err) {
     return { status: 'failed', retryable: false, reason, scanned: true };
 }
 /**
- * Restores the covered-tags value after a failed drain: returning it to its
- * pre-drain state keeps a client that synced fine before the attempt
- * syncing fine after it. Unlike the Rust twin — which merges the snapshot
- * with whatever the interrupted backfill re-covered — this restores the
- * snapshot verbatim (the WASM surface exposes the set only as an opaque
- * value); at worst the next successful drain re-covers tags the failed
- * attempt already handled, which is idempotent. A failed restoring write
- * throws: the store is left with its bookkeeping cleared and subsequent
- * normal syncs may re-drain (and re-fail on) old history — a local-store
- * environment failure the caller must not fold into a transport report.
- */
-async function restoreCoveredTags(midenClient, snapshot, drainReason) {
-    if (snapshot === null || snapshot === undefined)
-        return;
-    try {
-        await midenClient.settings.set(NOTE_TRANSPORT_COVERED_TAGS_KEY, snapshot);
-    }
-    catch (restoreError) {
-        throw new Error(`the transport drain failed (${drainReason}) and restoring the covered-tags bookkeeping also failed (${errorMessage(restoreError)}); subsequent syncs may re-drain old transport history`);
-    }
-}
-/**
- * Rescans the full private-note transport backlog for every tracked note tag
- * and imports what it finds, regardless of the stored transport
- * cursor. Counterpart of `MultisigClient::drain_private_note_backlog`
- * in the Rust SDK; the WASM boundary exposes only error message text, so
- * failure classification here is message-based, keyed on the upstream
- * Display prefixes pinned by the drift-guard test.
+ * Fetches the private-note transport backlog for every tracked note tag and
+ * imports what it finds. Counterpart of
+ * `MultisigClient::drain_private_note_backlog` in the Rust SDK; the WASM
+ * boundary exposes only error message text, so failure classification here
+ * is message-based, keyed on the upstream Display prefixes pinned by the
+ * drift-guard test.
  *
  * Use after account recovery, passing the **same** `MidenClient` instance
- * that was injected into `MultisigClient`: a fresh store has no transport
- * cursor, and in a shared store another account's sync may have advanced the
- * cursor past this account's notes. The drain is idempotent, tag-scoped (the
- * recovered account must already be in the store so its note tag is tracked
- * — `MultisigClient.load` does this), and never regresses an
- * already-advanced cursor.
+ * that was injected into `MultisigClient`. The recovered account must already
+ * be in the store so its note tag is tracked (`MultisigClient.load` does
+ * this). Its tag has no transport cursor yet, so the transport serves it from
+ * the first retained note. The drain runs transport fetches until one moves
+ * no tag's cursor, which only an exhausted backlog leaves unchanged: a fetch
+ * whose pages were all duplicates or screened out still advances it. The
+ * drain is idempotent: imports dedupe, and per-tag cursors only move forward.
  *
  * Transport recovery is bounded by the transport service's retention:
  * senders may bypass the transport entirely and relayed blobs are pruned
@@ -186,77 +208,55 @@ async function restoreCoveredTags(midenClient, snapshot, drainReason) {
  * backup. Transport-disabled and transport-unreachable outcomes are reported
  * in the {@link TransportRecoveryReport} rather than thrown; this function
  * only throws when the local store itself fails.
- *
- * The rescan runs as many transport syncs as the upstream per-sync tag
- * backfill cap requires to cover every tracked tag, and a failed drain
- * restores the pre-drain covered-tags bookkeeping so normal sync keeps
- * working exactly as it did before the attempt.
  */
 export async function drainPrivateNoteBacklog(midenClient) {
-    const before = (await midenClient.notes.list()).length;
+    const noteCount = async () => (await midenClient.notes.list()).length;
+    const before = await noteCount();
     // Records are never removed by a drain, so the length delta is the count
     // of newly imported records. Caveat: it is a store delta — notes imported
     // by concurrent activity on the same store (a background sync, another
     // tab) during the drain are attributed to it.
-    const importedSince = async () => Math.max((await midenClient.notes.list()).length - before, 0);
-    // Snapshot the covered-tags value before clearing it: the clear is
-    // durable, and upstream re-marks a tag covered only after its backfill
-    // succeeds — so without a restore, a drain that fails on a tag with a
-    // permanently bad relay blob would leave every tag uncovered and make
-    // every subsequent normal sync re-attempt (and fail) the same backfill.
-    // Store errors here propagate like the count above.
-    const coveredSnapshot = await midenClient.settings.get(NOTE_TRANSPORT_COVERED_TAGS_KEY);
-    let cleared = false;
-    try {
-        // The incremental fetch doubles as the transport probe: miden-sdk 0.16's
-        // syncNoteTransport silently no-ops when the transport is disabled, but
-        // this drain must report `unavailable`, and fetchPrivate still throws
-        // the upstream disabled error.
-        await midenClient.notes.fetchPrivate();
-        // miden-sdk 0.16 replaced the explicit full drain with covered-tag
-        // bookkeeping inside syncNoteTransport: every tag not yet marked covered
-        // is drained from the start with a local cursor (the global cursor is
-        // never regressed), then the steady-state fetch runs. Clearing the
-        // covered-tags marker first forces that full per-tag re-drain — exactly
-        // the recovery semantic this primitive promises. Imports dedupe, so
-        // re-draining already-seen history is harmless.
-        await midenClient.settings.remove(NOTE_TRANSPORT_COVERED_TAGS_KEY);
-        cleared = true;
-        // Upstream backfills at most `MAX_BACKFILL_TAGS_PER_SYNC` uncovered tags
-        // per sync, so run enough passes to cover every tracked tag before
-        // reporting the backlog fully scanned.
-        const tagCount = (await midenClient.tags.list()).length;
-        const passes = Math.max(1, Math.ceil(tagCount / MAX_BACKFILL_TAGS_PER_SYNC));
-        for (let pass = 0; pass < passes; pass += 1) {
-            await midenClient.syncNoteTransport();
-        }
-    }
-    catch (err) {
-        // A broken local store is an environment failure, not a transport
-        // outcome: the whole recovery flow needs to know, so it propagates
-        // (matching the Rust `StoreError` branch) instead of being folded into
-        // the report.
-        if (isLocalStoreError(err)) {
-            throw err;
+    const importedSince = async () => Math.max((await noteCount()) - before, 0);
+    let last = await readTransportCursors(midenClient);
+    for (let pass = 0; pass < MAX_DRAIN_PASSES; pass += 1) {
+        try {
+            // fetchPrivate throws the upstream disabled error when no transport is
+            // configured, where syncNoteTransport silently no-ops; this drain must
+            // report `unavailable`. A failed fetch still imports the pages fetched
+            // before it.
+            await midenClient.notes.fetchPrivate();
         }
-        const { status, retryable, reason, scanned } = classifyDrainFailure(err);
-        if (cleared) {
-            await restoreCoveredTags(midenClient, coveredSnapshot, reason);
+        catch (err) {
+            // A broken local store is an environment failure, not a transport
+            // outcome: the whole recovery flow needs to know, so it propagates
+            // (matching the Rust `StoreError` branch) instead of being folded into
+            // the report.
+            if (isLocalStoreError(err)) {
+                throw err;
+            }
+            const { status, retryable, reason, scanned } = classifyDrainFailure(err);
+            // A disabled transport throws before fetching anything, so skip the
+            // re-count entirely.
+            const imported = scanned ? await importedSince() : 0;
+            if (status === 'unavailable' && imported > 0) {
+                // `unavailable` promises "nothing was imported"; pages imported before
+                // the failure make it an interrupted drain, so report it as a failure,
+                // keeping the classified retryability, like the Rust twin.
+                return { status: 'failed', imported, retryable, reason };
+            }
+            return { status, imported, retryable, reason };
         }
-        // Count even when the drain failed: each fetched batch is imported as it
-        // arrives, so notes recovered before the failure stay in the store. A
-        // disabled transport throws before fetching anything, so skip the
-        // re-count entirely.
-        const imported = scanned ? await importedSince() : 0;
-        if (status === 'unavailable' && imported > 0) {
-            // `unavailable` promises "nothing was imported"; a connection lost
-            // mid-drain after partial progress is an interrupted drain, so report
-            // it as a failure — keeping the classified retryability, like the
-            // Rust twin.
-            return { status: 'failed', imported, retryable, reason };
+        const cursors = await readTransportCursors(midenClient);
+        if (sameBytes(cursors, last)) {
+            return { status: 'completed', imported: await importedSince(), retryable: false };
         }
-        return { status, imported, retryable, reason };
+        last = cursors;
     }
-    return { status: 'completed', imported: await importedSince(), retryable: false };
+    return {
+        status: 'failed',
+        imported: await importedSince(),
+        retryable: true,
+        reason: `the transport backlog was not exhausted after ${MAX_DRAIN_PASSES} fetches; rerun the drain to continue from the stored cursors`,
+    };
 }
 //# sourceMappingURL=transportDrain.js.map

package/dist/recovery/transportDrain.js.map

@@ -1 +1 @@
-{"version":3,"file":"transportDrain.js","sourceRoot":"","sources":["../../src/recovery/transportDrain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AA2CvD;;;;;GAKG;AACH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,2BAA2B,GAAG,4BAA4B,CAAC;AACxE,0FAA0F;AAC1F,MAAM,CAAC,MAAM,yBAAyB,GAAG,kBAAkB,CAAC;AAC5D;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,8BAA8B,CAAC;AACzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,kBAAkB,CAAC;AAChE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AACvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,qCAAqC,CAAC;AAC3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,6BAA6B,CAAC;AAE7E;;;;GAIG;AACH,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,yBAAyB,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,oBAAoB,CAAC,CAAC;AAC9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEpD;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,0BAA0B,CAAC,CAAC;AAErH;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAY;IACrC,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,IAAI,GACR,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QACtF,CAAC,CAAC,GAAG,CAAC,IAAI;QACV,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxE,oEAAoE;IACpE,2CAA2C;IAC3C,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpF,IAAI,IAAI,KAAK,YAAY,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QAC3F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAaD,SAAS,oBAAoB,CAAC,GAAY;IACxC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,0EAA0E;IAC1E,wEAAwE;IACxE,IAAI,KAAK,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC7E,CAAC;IACD,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,qDAAqD;IACrD,IAAI,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACtE,CAAC;IACD,sEAAsE;IACtE,wEAAwE;IACxE,2EAA2E;IAC3E,0EAA0E;IAC1E,kBAAkB;IAClB,IAAI,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,qBAAqB,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC7F,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,mBAAmB,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1F,CAAC;IACD,yEAAyE;IACzE,YAAY;IACZ,IAAI,KAAK,CAAC,QAAQ,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAC/C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IACD,qEAAqE;IACrE,2EAA2E;IAC3E,sEAAsE;IACtE,4CAA4C;IAC5C,IAAI,KAAK,CAAC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC;QAClD,MAAM,SAAS,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACrF,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACjF,CAAC;IACD,wEAAwE;IACxE,mEAAmE;IACnE,WAAW;IACX,IAAI,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,kBAAkB,CAC/B,WAAwB,EACxB,QAAiB,EACjB,WAAmB;IAEnB,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACxD,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,+BAA+B,EAAE,QAAQ,CAAC,CAAC;IAC5E,CAAC;IAAC,OAAO,YAAY,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,+BAA+B,WAAW,6DAA6D,YAAY,CAAC,YAAY,CAAC,wDAAwD,CAC1L,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,WAAwB;IAExB,MAAM,MAAM,GAAG,CAAC,MAAM,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IACvD,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,8CAA8C;IAC9C,MAAM,aAAa,GAAG,KAAK,IAAqB,EAAE,CAChD,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;IAEhE,mEAAmE;IACnE,uEAAuE;IACvE,sEAAsE;IACtE,sEAAsE;IACtE,wEAAwE;IACxE,oDAAoD;IACpD,MAAM,eAAe,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IACxF,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,IAAI,CAAC;QACH,yEAAyE;QACzE,wEAAwE;QACxE,sEAAsE;QACtE,+BAA+B;QAC/B,MAAM,WAAW,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QACvC,mEAAmE;QACnE,yEAAyE;QACzE,sEAAsE;QACtE,mEAAmE;QACnE,wEAAwE;QACxE,oEAAoE;QACpE,gDAAgD;QAChD,MAAM,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,+BAA+B,CAAC,CAAC;QACnE,OAAO,GAAG,IAAI,CAAC;QACf,yEAAyE;QACzE,mEAAmE;QACnE,uCAAuC;QACvC,MAAM,QAAQ,GAAG,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,0BAA0B,CAAC,CAAC,CAAC;QAC7E,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;YAC5C,MAAM,WAAW,CAAC,iBAAiB,EAAE,CAAC;QACxC,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kEAAkE;QAClE,mEAAmE;QACnE,uEAAuE;QACvE,cAAc;QACd,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;QACzE,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,kBAAkB,CAAC,WAAW,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;QACjE,CAAC;QACD,yEAAyE;QACzE,sEAAsE;QACtE,kEAAkE;QAClE,qBAAqB;QACrB,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,IAAI,MAAM,KAAK,aAAa,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC7C,mEAAmE;YACnE,sEAAsE;YACtE,kEAAkE;YAClE,aAAa;YACb,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACpF,CAAC"}
+{"version":3,"file":"transportDrain.js","sourceRoot":"","sources":["../../src/recovery/transportDrain.ts"],"names":[],"mappings":"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"}

package/dist/session/grant.d.ts

@@ -0,0 +1,40 @@
+import type { SessionGrantFields } from '@openzeppelin/guardian-client';
+import { Word } from '@miden-sdk/miden-sdk';
+/**
+ * Session grant, logout and revoke-all digests (issue #219). MUST produce
+ * byte-identical digests to `crates/shared/src/session_grant.rs`; parity is
+ * verified against `crates/shared/tests/fixtures/session_grant_vectors.json`.
+ */
+/**
+ * The scope every v1 grant states, shown by the wallet: the delegated signer
+ * acts for every account its wallet key cosigns on this Guardian, including
+ * accounts the key is added to later, until the grant expires.
+ */
+export declare const SESSION_GRANT_SCOPE = "Every account this signer cosigns on this Guardian, now or later, until this grant expires";
+export declare function sessionDomainTag(): Word;
+export declare function sessionLogoutDomainTag(): Word;
+export declare function sessionRevokeAllDomainTag(): Word;
+/** The canonical readable expiry, `YYYY-MM-DD HH:MM:SS UTC`, derived from `expiresAt`. */
+export declare function formatUtcSeconds(unixSeconds: number): string;
+/**
+ * Digest signed by Falcon and raw ECDSA wallets: the domain tag followed by
+ * every grant field in the clear, in the order the wallet displays them.
+ */
+export declare function sessionGrantDigest(grant: SessionGrantFields): Word;
+/**
+ * The grant as the label/value pairs a wallet shows, in signing order. Raw
+ * (Falcon or raw ECDSA) wallets display only a hash, so show these to the
+ * user before asking such a wallet to sign.
+ */
+export declare function describeSessionGrant(grant: SessionGrantFields): Array<{
+    label: string;
+    value: string;
+}>;
+/** Digest of the account-less, session-key-signed `POST /session/logout`. */
+export declare function sessionLogoutDigest(sessionPublicKey: string, timestampMs: number): Word;
+/**
+ * Digest of the account-less, wallet-signed `POST /session/revoke-all`, which
+ * ends every session of `signerCommitment` on the Guardian.
+ */
+export declare function sessionRevokeAllDigest(signerCommitment: string, timestampMs: number): Word;
+//# sourceMappingURL=grant.d.ts.map

package/dist/session/grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/session/grant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAA2B,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAIrE;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,+FAC8D,CAAC;AAU/F,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAuBD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG5D;AAUD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAkBlE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,GACxB,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAWzC;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAOvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAO1F"}

package/dist/session/grant.js

@@ -0,0 +1,125 @@
+import { Felt, FeltArray, Rpo256, Word } from '@miden-sdk/miden-sdk';
+import { domainTagWord, feltFromU64Reduced } from '../utils/felt.js';
+import { hexToBytes } from '../utils/encoding.js';
+/**
+ * Session grant, logout and revoke-all digests (issue #219). MUST produce
+ * byte-identical digests to `crates/shared/src/session_grant.rs`; parity is
+ * verified against `crates/shared/tests/fixtures/session_grant_vectors.json`.
+ */
+/**
+ * The scope every v1 grant states, shown by the wallet: the delegated signer
+ * acts for every account its wallet key cosigns on this Guardian, including
+ * accounts the key is added to later, until the grant expires.
+ */
+export const SESSION_GRANT_SCOPE = 'Every account this signer cosigns on this Guardian, now or later, until this grant expires';
+const DOMAIN_TAG_BYTES = new TextEncoder().encode('guardian.session.v1');
+const LOGOUT_DOMAIN_TAG_BYTES = new TextEncoder().encode('guardian.session.logout.v1');
+const REVOKE_ALL_DOMAIN_TAG_BYTES = new TextEncoder().encode('guardian.session.revoke_all.v1');
+let cachedDomainTag = null;
+let cachedLogoutDomainTag = null;
+let cachedRevokeAllDomainTag = null;
+export function sessionDomainTag() {
+    cachedDomainTag ??= domainTagWord(DOMAIN_TAG_BYTES);
+    return cachedDomainTag;
+}
+export function sessionLogoutDomainTag() {
+    cachedLogoutDomainTag ??= domainTagWord(LOGOUT_DOMAIN_TAG_BYTES);
+    return cachedLogoutDomainTag;
+}
+export function sessionRevokeAllDomainTag() {
+    cachedRevokeAllDomainTag ??= domainTagWord(REVOKE_ALL_DOMAIN_TAG_BYTES);
+    return cachedRevokeAllDomainTag;
+}
+/**
+ * `[len, u32_le_chunk...]` felts: injective for arbitrary bytes, including
+ * public keys. Mirrors `felts_from_bytes` in the Rust crate.
+ */
+function feltsFromBytes(bytes) {
+    const felts = [new Felt(BigInt(bytes.length))];
+    for (let offset = 0; offset < bytes.length; offset += 4) {
+        let value = 0;
+        for (let i = 0; i < 4; i += 1) {
+            const byte = offset + i < bytes.length ? bytes[offset + i] : 0;
+            value += byte * 2 ** (8 * i);
+        }
+        felts.push(new Felt(BigInt(value)));
+    }
+    return felts;
+}
+function hashBytes(bytes) {
+    return Rpo256.hashElements(new FeltArray(feltsFromBytes(bytes)));
+}
+/** The canonical readable expiry, `YYYY-MM-DD HH:MM:SS UTC`, derived from `expiresAt`. */
+export function formatUtcSeconds(unixSeconds) {
+    const iso = new Date(unixSeconds * 1000).toISOString();
+    return `${iso.slice(0, 10)} ${iso.slice(11, 19)} UTC`;
+}
+function sessionPublicKeyBytes(hex) {
+    const bytes = hexToBytes(hex);
+    if (bytes.length !== 33 || (bytes[0] !== 0x02 && bytes[0] !== 0x03)) {
+        throw new Error('Session public key must be a 33-byte SEC1 compressed P-256 point');
+    }
+    return bytes;
+}
+/**
+ * Digest signed by Falcon and raw ECDSA wallets: the domain tag followed by
+ * every grant field in the clear, in the order the wallet displays them.
+ */
+export function sessionGrantDigest(grant) {
+    if (grant.expiresAt <= grant.issuedAt) {
+        throw new Error('Session grant expiresAt must be after issuedAt');
+    }
+    const encoder = new TextEncoder();
+    const felts = [
+        ...sessionDomainTag().toFelts(),
+        ...Word.fromHex(grant.signerCommitment).toFelts(),
+        ...feltsFromBytes(sessionPublicKeyBytes(grant.sessionPublicKey)),
+        ...hashBytes(encoder.encode(grant.origin)).toFelts(),
+        feltFromU64Reduced(BigInt(grant.issuedAt)),
+        feltFromU64Reduced(BigInt(grant.expiresAt)),
+        ...hashBytes(encoder.encode(formatUtcSeconds(grant.expiresAt))).toFelts(),
+        ...hashBytes(encoder.encode(SESSION_GRANT_SCOPE)).toFelts(),
+        ...Word.fromHex(grant.guardianCommitment).toFelts(),
+        ...hashBytes(encoder.encode(grant.network)).toFelts(),
+    ];
+    return Rpo256.hashElements(new FeltArray(felts));
+}
+/**
+ * The grant as the label/value pairs a wallet shows, in signing order. Raw
+ * (Falcon or raw ECDSA) wallets display only a hash, so show these to the
+ * user before asking such a wallet to sign.
+ */
+export function describeSessionGrant(grant) {
+    return [
+        { label: 'Signer', value: grant.signerCommitment },
+        { label: 'Session key', value: grant.sessionPublicKey },
+        { label: 'Website', value: grant.origin || '(none: outside a browser)' },
+        { label: 'Valid from', value: formatUtcSeconds(grant.issuedAt) },
+        { label: 'Expires', value: formatUtcSeconds(grant.expiresAt) },
+        { label: 'Scope', value: SESSION_GRANT_SCOPE },
+        { label: 'Guardian key', value: grant.guardianCommitment },
+        { label: 'Network', value: grant.network },
+    ];
+}
+/** Digest of the account-less, session-key-signed `POST /session/logout`. */
+export function sessionLogoutDigest(sessionPublicKey, timestampMs) {
+    const felts = [
+        ...sessionLogoutDomainTag().toFelts(),
+        feltFromU64Reduced(BigInt(timestampMs)),
+        ...feltsFromBytes(sessionPublicKeyBytes(sessionPublicKey)),
+    ];
+    return Rpo256.hashElements(new FeltArray(felts));
+}
+/**
+ * Digest of the account-less, wallet-signed `POST /session/revoke-all`, which
+ * ends every session of `signerCommitment` on the Guardian.
+ */
+export function sessionRevokeAllDigest(signerCommitment, timestampMs) {
+    const felts = [
+        ...sessionRevokeAllDomainTag().toFelts(),
+        feltFromU64Reduced(BigInt(timestampMs)),
+        ...Word.fromHex(signerCommitment).toFelts(),
+    ];
+    return Rpo256.hashElements(new FeltArray(felts));
+}
+//# sourceMappingURL=grant.js.map

package/dist/session/grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant.js","sourceRoot":"","sources":["../../src/session/grant.ts"],"names":[],"mappings":"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"}

package/dist/session/key.d.ts

@@ -0,0 +1,103 @@
+import type { RequestAuthPayload, SessionEndReason, SessionRequestSigner } from '@openzeppelin/guardian-client';
+import type { Word } from '@miden-sdk/miden-sdk';
+/**
+ * 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 declare class WebCryptoSessionKey {
+    readonly privateKey: CryptoKey;
+    /** Hex SEC1-compressed public key. */
+    readonly publicKey: string;
+    constructor(privateKey: CryptoKey, 
+    /** Hex SEC1-compressed public key. */
+    publicKey: string);
+    static generate(): Promise<WebCryptoSessionKey>;
+    /** Sign the 32 bytes of a word: ECDSA P-256 over SHA-256, `r || s` hex. */
+    signWord(word: Word): Promise<string>;
+}
+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 declare class GuardianSession implements SessionRequestSigner {
+    private readonly key;
+    /** 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;
+    constructor(key: WebCryptoSessionKey, 
+    /** Commitment of the wallet that signed the grant. */
+    signerCommitment: string, 
+    /** Unix seconds. */
+    expiresAt: number, 
+    /** Where a `SessionKeyStore` keeps this session's key. */
+    storeId: string, options?: GuardianSessionOptions);
+    get publicKey(): string;
+    /**
+     * 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;
+    signRequest(accountId: string, timestamp: number, requestPayload: RequestAuthPayload): Promise<string>;
+    signLogout(timestampMs: number): Promise<string>;
+}
+/** 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 declare function forgetSessionKey(store: SessionKeyStore, session: {
+    storeId: string;
+    publicKey: string;
+}): Promise<void>;
+/**
+ * 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 declare class IndexedDbSessionKeyStore implements SessionKeyStore {
+    private readonly databaseName;
+    private static readonly STORE;
+    private database;
+    constructor(databaseName?: string);
+    load(id: string): Promise<StoredSessionKey | null>;
+    save(record: StoredSessionKey): Promise<void>;
+    remove(id: string, publicKey: string): Promise<void>;
+    private request;
+    /** Opens the database once; a failed open is retried on the next call. */
+    private open;
+}
+//# sourceMappingURL=key.d.ts.map

package/dist/session/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/session/key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAiBjD;;;;GAIG;AACH,qBAAa,mBAAmB;IAE5B,QAAQ,CAAC,UAAU,EAAE,SAAS;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAFjB,UAAU,EAAE,SAAS;IAC9B,sCAAsC;IAC7B,SAAS,EAAE,MAAM;WAGf,QAAQ,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAMrD,2EAA2E;IACrE,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;CAK5C;AAED,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;CACxE;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,oBAAoB;IAExD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IACjC,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAPP,GAAG,EAAE,mBAAmB;IACzC,sDAAsD;IAC7C,gBAAgB,EAAE,MAAM;IACjC,oBAAoB;IACX,SAAS,EAAE,MAAM;IAC1B,0DAA0D;IACjD,OAAO,EAAE,MAAM,EACP,OAAO,GAAE,sBAA2B;IAGvD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAOvC,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,kBAAkB,GACjC,OAAO,CAAC,MAAM,CAAC;IAIlB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGjD;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAIlD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAHzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAqC;gBAExB,YAAY,SAAsB;IAEzD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAOlD,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAkB5C,OAAO;IAcrB,0EAA0E;IAC1E,OAAO,CAAC,IAAI;CAuBb"}