@calimero-network/mero-js 22.6.0 → 22.8.0

package/dist/login/login.d.ts

@@ -31,6 +31,7 @@
  * order is implicit in a `derive`, so nothing on that side forces anyone to
  * notice this file depends on both. This module's test asserts the same vectors.
  */
+import { type Signer } from '../signer/signer.js';
 /**
  * The client surface a session is bound to.
  *
@@ -87,8 +88,17 @@ export interface LoginStatementInput {
      *
      * Never sent anywhere. It signs locally and only the signature travels, which
      * is what lets a statement be minted by something holding no node.
+     *
+     * Mutually exclusive with {@link LoginStatementInput.signer}, and the weaker
+     * of the two in a browser: a secret that exists as a string can be read by
+     * anything running on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The device's signer — use instead of
+     * {@link LoginStatementInput.deviceSecret} when the key cannot be exported.
      */
-    deviceSecret: string;
+    signer?: Signer;
 }
 /**
  * Sign a login statement and return it hex-encoded, ready to present with an

package/dist/login/login.js

@@ -31,7 +31,8 @@
  * order is implicit in a `derive`, so nothing on that side forces anyone to
  * notice this file depends on both. This module's test asserts the same vectors.
  */
-import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { concat, domainHash, fromHex, hex, u32le, u64le, } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
 const SIGN_DOMAIN = new TextEncoder().encode('calimero.auth.login.v1');
 /** The borsh enum tag for each variant, in core's declaration order. */
 const AUDIENCE_TAG = {
@@ -91,8 +92,8 @@ export async function signLoginStatement(input) {
     const node = fromHex(input.node, 'node', 32);
     const challenge = fromHex(input.challenge, 'challenge', 32);
     const sessionKey = fromHex(input.sessionKey, 'sessionKey', 32);
-    const key = await importSigningKey(input.deviceSecret);
-    const deviceKey = await derivePublicKey(input.deviceSecret);
+    const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const deviceKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
     const issuedAt = u64le(input.issuedAt);
     const expiresAt = u64le(input.expiresAt);
     const preimage = await domainHash(SIGN_DOMAIN, [
@@ -104,6 +105,6 @@ export async function signLoginStatement(input) {
         issuedAt,
         expiresAt,
     ]);
-    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const signature = await signer.sign(preimage);
     return hex(concat(node, audienceWire(input.audience), challenge, sessionKey, deviceKey, issuedAt, expiresAt, signature));
 }

package/dist/login/session.d.ts

@@ -31,6 +31,7 @@
  * cannot be escalated into use of the key that authorised it.
  */
 import { type Audience } from './login.js';
+import { type Signer } from '../signer/signer.js';
 /** A freshly minted ephemeral keypair, hex-encoded. */
 export interface SessionKeyPair {
     /** The public half — what the statement is signed over. */
@@ -59,8 +60,18 @@ export interface LoginConfig {
      * module note.
      */
     node: string;
-    /** The device's ed25519 signing secret, hex (32 bytes). Never sent. */
-    deviceSecret: string;
+    /**
+     * The device's ed25519 signing secret, hex (32 bytes). Never sent.
+     *
+     * Mutually exclusive with {@link LoginConfig.signer}, and the weaker of the
+     * two in a browser — see {@link Signer}.
+     */
+    deviceSecret?: string;
+    /**
+     * The device's signer — use instead of {@link LoginConfig.deviceSecret} when
+     * the key cannot be exported to hex.
+     */
+    signer?: Signer;
     /**
      * The device's account proof, hex — the credential certifying that this
      * device belongs to its account.
@@ -73,9 +84,14 @@ export interface LoginConfig {
     /** The client surface this session is bound to. */
     audience: Audience;
     /**
-     * How this client names itself to the node. Defaults to the audience's own
-     * spelling, which is the honest answer: a session bound to an origin should
-     * say that origin.
+     * The token request's `client_name`. Defaults to {@link LoginConfig.nodeUrl}.
+     *
+     * mero-auth records this value as the session's `node_url` and, on every
+     * later request, refuses one whose Host is not that URL's host ("Token is not
+     * valid for this host"). So it must name the node being logged in to — which
+     * is what core's own clients send. The audience is not a substitute: a browser
+     * page's origin is a different host from the relay it talks to, and a token
+     * bound to the page's host is refused on the first call.
      */
     clientName?: string;
     /** Seconds the statement stays valid. Defaults to {@link DEFAULT_TTL_SECONDS}. */

package/dist/login/session.js

@@ -33,6 +33,7 @@
 import { HTTPError } from '../http-client/web-client.js';
 import { derivePublicKey, hex } from '../crypto/internal.js';
 import { signLoginStatement } from './login.js';
+import { resolveSigner } from '../signer/signer.js';
 /** Seconds a statement stays valid unless told otherwise. */
 const DEFAULT_TTL_SECONDS = 300;
 /**
@@ -47,17 +48,6 @@ export async function generateSessionKey() {
     const secret = hex(crypto.getRandomValues(new Uint8Array(32)));
     return { publicKey: hex(await derivePublicKey(secret)), secret };
 }
-/** The audience's own spelling, used as the default client name. */
-function audienceLabel(audience) {
-    switch (audience.kind) {
-        case 'webOrigin':
-            return audience.origin;
-        case 'codeSigningId':
-            return audience.id;
-        case 'cli':
-            return 'cli';
-    }
-}
 /**
  * Log in with a device key and return the session.
  *
@@ -75,9 +65,9 @@ export async function login(config) {
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         let response;
         try {
+            // Called as `globalThis.fetch(...)`, never through a detached reference:
+            // a browser's fetch throws "Illegal invocation" when its receiver is lost.
             const requestInit = { ...init, signal: controller.signal };
-            // globalThis.fetch must be called as a method on globalThis, not through a
-            // variable, or browsers throw "Illegal invocation".
             response = config.fetch
                 ? await config.fetch(`${baseUrl}${path}`, requestInit)
                 : await globalThis.fetch(`${baseUrl}${path}`, requestInit);
@@ -113,7 +103,9 @@ export async function login(config) {
         sessionKey: session.publicKey,
         issuedAt,
         expiresAt: issuedAt + (config.ttlSeconds ?? DEFAULT_TTL_SECONDS),
-        deviceSecret: config.deviceSecret,
+        // Resolved once and handed on, so a config carrying a secret and a config
+        // carrying a `CryptoKey` take exactly the same path from here down.
+        signer: await resolveSigner(config.deviceSecret, config.signer, 'deviceSecret'),
     });
     // `timestamp` is required and the request refuses unknown fields, so a body
     // missing it is rejected during deserialization — before the provider runs,
@@ -126,7 +118,7 @@ export async function login(config) {
         body: JSON.stringify({
             auth_method: 'account_proof',
             public_key: session.publicKey,
-            client_name: config.clientName ?? audienceLabel(config.audience),
+            client_name: config.clientName ?? baseUrl,
             timestamp: issuedAt,
             provider_data: {
                 challenge,

package/dist/namespace-op/namespace-op.d.ts

@@ -14,6 +14,7 @@
  * op, which is what the e2e does.
  */
 import type { SignedGroupOpenInvitation } from '../admin-api/admin-types.js';
+import { type Signer } from '../signer/signer.js';
 /**
  * Core's `SIGNED_NAMESPACE_OP_SCHEMA_VERSION`. A node refuses any other value.
  *
@@ -55,8 +56,19 @@ export interface SignMemberJoinInput {
      * when applying the join and refuses otherwise.
      */
     readonly credential: string;
-    /** The device signing secret, 64 hex. Must match the credential's `sign_pk`. */
-    readonly deviceSecret: string;
+    /**
+     * The device signing secret, 64 hex. Must match the credential's `sign_pk`.
+     *
+     * Mutually exclusive with {@link SignMemberJoinInput.signer}. A browser should
+     * prefer the signer: joining is the one governance op a keyholder signs for
+     * itself, and it should not need the key in a form script can read.
+     */
+    readonly deviceSecret?: string;
+    /**
+     * The joiner's signer — use instead of
+     * {@link SignMemberJoinInput.deviceSecret} when the key cannot be exported.
+     */
+    readonly signer?: Signer;
     /**
      * Heads this op is written against. Empty means "signed against an empty head"
      * — which is NOT the same as genesis, and a node with a non-empty head will

package/dist/namespace-op/namespace-op.js

@@ -1,4 +1,5 @@
-import { concat, derivePublicKey, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { concat, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
 /**
  * Core's `SIGNED_NAMESPACE_OP_SCHEMA_VERSION`. A node refuses any other value.
  *
@@ -122,10 +123,13 @@ export async function signMemberJoinOp(input) {
         ? concat(new Uint8Array([ROOT_OP.MemberJoinedAt]), fromHex(input.member, 'member', 32), encodeSignedInvitation(input.invitation), u64le(joinedAt), credential)
         : concat(new Uint8Array([ROOT_OP.MemberJoined]), fromHex(input.member, 'member', 32), encodeSignedInvitation(input.invitation), credential);
     const op = concat(new Uint8Array([NAMESPACE_OP_ROOT]), rootOp);
-    const key = await importSigningKey(input.deviceSecret);
-    const signer = await derivePublicKey(input.deviceSecret);
-    const signable = concat(new Uint8Array([SIGNED_NAMESPACE_OP_SCHEMA_VERSION]), fromHex(input.namespaceId, 'namespaceId', 32), u32le(parents.length), ...parents.map((p, i) => fromHex(p, `parentOpHashes[${i}]`, 32)), signer, u64le(input.nonce), op);
-    const signature = new Uint8Array(await crypto.subtle.sign('Ed25519', key, concat(NAMESPACE_SIGN_DOMAIN, signable)));
+    const signingKey = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    // Named apart from the signer itself: this is the public half the op carries
+    // as its `signer` field, which every peer compares with the credential's
+    // `sign_pk` before applying the join.
+    const signerPublicKey = fromHex(signingKey.publicKey, 'signer.publicKey', 32);
+    const signable = concat(new Uint8Array([SIGNED_NAMESPACE_OP_SCHEMA_VERSION]), fromHex(input.namespaceId, 'namespaceId', 32), u32le(parents.length), ...parents.map((p, i) => fromHex(p, `parentOpHashes[${i}]`, 32)), signerPublicKey, u64le(input.nonce), op);
+    const signature = await signingKey.sign(concat(NAMESPACE_SIGN_DOMAIN, signable));
     // The signed struct repeats the signable fields, then the signature, then the
     // admitter endorsement. The domain is a signing prefix only and is never part
     // of the encoded op.

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, } from './relay-client.js';
-export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';
-export type { NonceSource } from './nonce-source.js';
+export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, FoundNamespaceInput, FoundedNamespace, } from './relay-client.js';
+export { createMemoryNonceSource, createLocalStorageNonceSource, createRecoveringNonceSource, authorNonceLookup, WarrantNonceExhaustedError, } from './nonce-source.js';
+export type { NonceSource, WarrantNonceLookup, RecoveringNonceSourceOptions, } from './nonce-source.js';

package/dist/relay/index.js

@@ -1,2 +1,2 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';
+export { createMemoryNonceSource, createLocalStorageNonceSource, createRecoveringNonceSource, authorNonceLookup, WarrantNonceExhaustedError, } from './nonce-source.js';

package/dist/relay/nonce-source.d.ts

@@ -22,9 +22,22 @@
  * is the one you have to ask for. It is also why a source may jump: reserving a
  * block and losing the tail is the correct trade.
  */
+import type { WarrantNonceState } from '../admin-api/admin-types.js';
 /** Produces the next nonce for one author device. Must never go backwards. */
 export interface NonceSource {
     next(): Promise<bigint>;
+    /**
+     * Raise the floor of the sequence to `floor`, if this source can record it.
+     *
+     * Optional, and additive: a source that does not implement it still works
+     * everywhere a `NonceSource` is taken, and {@link createRecoveringNonceSource}
+     * keeps the floor itself in that case. Implementing it is what lets a
+     * *persistent* source remember a jump, so a later cold start that cannot
+     * reach a node resumes above the mark rather than below it.
+     *
+     * Never lowers: a smaller `floor` than the source's own position is ignored.
+     */
+    advanceTo?(floor: bigint): Promise<void>;
 }
 /**
  * A counter in memory, starting at `start`.
@@ -58,3 +71,125 @@ export declare function createLocalStorageNonceSource(key: string, storage?: {
     getItem(k: string): string | null;
     setItem(k: string, v: string): void;
 }): NonceSource;
+/** A node (or anything else) that can answer where a device's sequence stands. */
+export interface WarrantNonceLookup {
+    getWarrantNonce(contextId: string, authorDeviceKey: string): Promise<WarrantNonceState>;
+}
+/**
+ * A lookup a delegated client can actually use.
+ *
+ * {@link WarrantNonceLookup} names the device key because the admin route takes
+ * it in the path. The delegated route does not: it reads the key from the
+ * certificate it verifies, so the only way to ask is to present that
+ * certificate. This adapter bridges the two — it satisfies the interface, and
+ * ignores the device key argument because the credential already determines it.
+ *
+ * That the argument is ignored is not an oversight to tidy away. The whole
+ * point of the delegated route is that the device key is not caller-supplied:
+ * a key passed alongside the proof would be a second spelling of a fact the
+ * signature already fixes, and two spellings can differ. The adapter therefore
+ * has nothing to check it against, and pretending otherwise would invent a
+ * comparison the protocol deliberately does not make.
+ *
+ * Use with {@link createRecoveringNonceSource} exactly as an `AdminApiClient`
+ * would be used — on a relay, this is the form that works.
+ */
+export declare function authorNonceLookup(options: {
+    /** Anything that can reach the node's admin path; an `AdminApiClient` does. */
+    client: {
+        getWarrantNonceAsAuthor(contextId: string, authorProof: string): Promise<WarrantNonceState>;
+    };
+    /** Hex borsh `AccountProof<DeviceCert>` — the same one the relay client sends. */
+    authorProof: string;
+}): WarrantNonceLookup;
+/** Thrown when every node asked says this device has spent `u64::MAX` here. */
+export declare class WarrantNonceExhaustedError extends Error {
+    readonly contextId: string;
+    readonly authorDeviceKey: string;
+    name: string;
+    constructor(contextId: string, authorDeviceKey: string);
+}
+/** What {@link createRecoveringNonceSource} needs to know. */
+export interface RecoveringNonceSourceOptions {
+    /**
+     * The node(s) to ask. Pass an {@link AdminApiClient} — it satisfies this
+     * structurally — or several, one per relay this author writes through.
+     *
+     * With more than one, the **highest** answer wins. Nonce state folds per peer,
+     * so a node can only be behind a client whose warrants it has not applied,
+     * never ahead of the truth; taking the highest is therefore the only reading
+     * that cannot hand out a nonce somebody has already spent.
+     */
+    lookups: WarrantNonceLookup | readonly WarrantNonceLookup[];
+    contextId: string;
+    /** The author device's SIGNING key, base58 or hex. Not its `deviceId`. */
+    authorDeviceKey: string;
+    /**
+     * The client's own counter, folded in with `max`. Defaults to an in-memory
+     * one starting at 1.
+     *
+     * Pass {@link createLocalStorageNonceSource} to keep both halves: the local
+     * counter carries the sequence forward between calls, the node supplies the
+     * floor when that counter has been cleared.
+     */
+    local?: NonceSource;
+    /**
+     * What to do when no node can be reached on the cold-start lookup.
+     *
+     * `'throw'` (the default) refuses to mint. That is the conservative reading:
+     * a source that quietly fell back to a cleared local counter would replay
+     * spent nonces, which is the exact failure this exists to prevent, and it
+     * would do it invisibly. `'local'` mints from the local counter anyway —
+     * correct only when that counter is known to be intact and the app would
+     * rather write offline than not at all.
+     */
+    onLookupFailure?: 'throw' | 'local';
+}
+/**
+ * A nonce source that asks the node where the sequence stands before its first
+ * mint, then carries on locally.
+ *
+ * # Why this is not the default
+ *
+ * It costs a round trip and an admin credential, and an author that never lost
+ * its counter gains nothing from it. It earns its place in exactly one
+ * situation, which is common rather than exotic: a client whose local state is
+ * gone. A browser keyholder lives in storage that is partitioned per top-level
+ * site and cleared on a schedule it does not control, so for it, losing the
+ * counter is the normal lifecycle. Without this, such a client either restarts
+ * at 1 — replaying every nonce it already spent, each write refused, which
+ * reads to the user as the app silently not saving — or guesses upward, one
+ * burnt round trip per wrong guess.
+ *
+ * # What it does
+ *
+ * The lookup happens once, lazily, on the first {@link NonceSource.next}: a
+ * source that is constructed and never used costs nothing, and an app that
+ * builds its relay client at startup does not pay a network call for it. The
+ * answer becomes a **floor**, and every nonce handed out afterwards is
+ * `max(localCounter, floor)`. It never goes backwards from either input, which
+ * is the one property a nonce source owes its caller.
+ *
+ * If the local counter is the one that is ahead, it wins — the node may simply
+ * not have applied this client's recent warrants yet.
+ *
+ * The floor is also pushed into the local source through
+ * {@link NonceSource.advanceTo} when it has one, so a persistent counter
+ * remembers the jump.
+ *
+ * # Exhaustion
+ *
+ * A node reporting no `nextNonce` means `u64::MAX` is spent and this device can
+ * never write here again. `next()` rejects with
+ * {@link WarrantNonceExhaustedError} rather than guessing, because every guess
+ * from there is refused forever.
+ *
+ * # On an older node
+ *
+ * The route is new and absent from core `master` builds, which answer 404 —
+ * {@link AdminApiClient.getWarrantNonce} surfaces that as
+ * `WarrantNonceRouteUnavailableError`. It reaches the caller as a lookup
+ * failure, so `onLookupFailure` decides: refuse to mint, or fall back to the
+ * local counter.
+ */
+export declare function createRecoveringNonceSource(options: RecoveringNonceSourceOptions): NonceSource;

package/dist/relay/nonce-source.js

@@ -41,6 +41,11 @@ export function createMemoryNonceSource(start = 1) {
             next += 1n;
             return Promise.resolve(value);
         },
+        advanceTo(floor) {
+            if (floor > next)
+                next = floor;
+            return Promise.resolve();
+        },
     };
 }
 /**
@@ -67,29 +72,192 @@ export function createLocalStorageNonceSource(key, storage) {
     if (!store) {
         throw new Error('no localStorage in this runtime: pass a storage implementation, or use createMemoryNonceSource for a process that owns its whole sequence');
     }
+    // A missing, empty, or corrupted value means "no sequence recorded", and the
+    // safe reading of that is not 1 — a cleared storage on a device that has
+    // already written would replay. But the client cannot know, and 1 is the only
+    // defensible start, so it is what a fresh key gets. This is why the doc above
+    // tells apps to key per device: a device whose storage was cleared should be
+    // re-paired rather than resumed — or handed a recovering source, which asks
+    // the node what it already spent instead of guessing.
+    const lastHandedOut = () => {
+        const raw = store.getItem(key);
+        if (raw === null || raw === '')
+            return 0n;
+        try {
+            const parsed = BigInt(raw);
+            return parsed > 0n ? parsed : 0n;
+        }
+        catch {
+            return 0n;
+        }
+    };
     return {
         next() {
-            const raw = store.getItem(key);
-            // A missing, empty, or corrupted value means "no sequence recorded", and
-            // the safe reading of that is not 1 — a cleared storage on a device that
-            // has already written would replay. But the client cannot know, and 1 is
-            // the only defensible start, so it is what a fresh key gets. This is why
-            // the doc above tells apps to key per device: a device whose storage was
-            // cleared should be re-paired rather than resumed.
-            let current = 0n;
-            if (raw !== null && raw !== '') {
-                try {
-                    const parsed = BigInt(raw);
-                    if (parsed > 0n)
-                        current = parsed;
-                }
-                catch {
-                    current = 0n;
-                }
-            }
-            const value = current + 1n;
+            const value = lastHandedOut() + 1n;
             store.setItem(key, value.toString());
             return Promise.resolve(value);
         },
+        advanceTo(floor) {
+            // Stored is the last number handed out, so the floor is recorded as the
+            // one below it — persisted rather than held in memory, which is the whole
+            // point: the next cold start resumes above the jump even if the node
+            // cannot be reached then.
+            const wanted = floor > 0n ? floor - 1n : 0n;
+            if (wanted > lastHandedOut())
+                store.setItem(key, wanted.toString());
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * A lookup a delegated client can actually use.
+ *
+ * {@link WarrantNonceLookup} names the device key because the admin route takes
+ * it in the path. The delegated route does not: it reads the key from the
+ * certificate it verifies, so the only way to ask is to present that
+ * certificate. This adapter bridges the two — it satisfies the interface, and
+ * ignores the device key argument because the credential already determines it.
+ *
+ * That the argument is ignored is not an oversight to tidy away. The whole
+ * point of the delegated route is that the device key is not caller-supplied:
+ * a key passed alongside the proof would be a second spelling of a fact the
+ * signature already fixes, and two spellings can differ. The adapter therefore
+ * has nothing to check it against, and pretending otherwise would invent a
+ * comparison the protocol deliberately does not make.
+ *
+ * Use with {@link createRecoveringNonceSource} exactly as an `AdminApiClient`
+ * would be used — on a relay, this is the form that works.
+ */
+export function authorNonceLookup(options) {
+    return {
+        getWarrantNonce: (contextId, _authorDeviceKey) => options.client.getWarrantNonceAsAuthor(contextId, options.authorProof),
+    };
+}
+/** Thrown when every node asked says this device has spent `u64::MAX` here. */
+export class WarrantNonceExhaustedError extends Error {
+    constructor(contextId, authorDeviceKey) {
+        super(`author device ${authorDeviceKey} has spent every nonce in context ${contextId}; it must re-key to write again`);
+        this.contextId = contextId;
+        this.authorDeviceKey = authorDeviceKey;
+        this.name = 'WarrantNonceExhaustedError';
+    }
+}
+/**
+ * A nonce source that asks the node where the sequence stands before its first
+ * mint, then carries on locally.
+ *
+ * # Why this is not the default
+ *
+ * It costs a round trip and an admin credential, and an author that never lost
+ * its counter gains nothing from it. It earns its place in exactly one
+ * situation, which is common rather than exotic: a client whose local state is
+ * gone. A browser keyholder lives in storage that is partitioned per top-level
+ * site and cleared on a schedule it does not control, so for it, losing the
+ * counter is the normal lifecycle. Without this, such a client either restarts
+ * at 1 — replaying every nonce it already spent, each write refused, which
+ * reads to the user as the app silently not saving — or guesses upward, one
+ * burnt round trip per wrong guess.
+ *
+ * # What it does
+ *
+ * The lookup happens once, lazily, on the first {@link NonceSource.next}: a
+ * source that is constructed and never used costs nothing, and an app that
+ * builds its relay client at startup does not pay a network call for it. The
+ * answer becomes a **floor**, and every nonce handed out afterwards is
+ * `max(localCounter, floor)`. It never goes backwards from either input, which
+ * is the one property a nonce source owes its caller.
+ *
+ * If the local counter is the one that is ahead, it wins — the node may simply
+ * not have applied this client's recent warrants yet.
+ *
+ * The floor is also pushed into the local source through
+ * {@link NonceSource.advanceTo} when it has one, so a persistent counter
+ * remembers the jump.
+ *
+ * # Exhaustion
+ *
+ * A node reporting no `nextNonce` means `u64::MAX` is spent and this device can
+ * never write here again. `next()` rejects with
+ * {@link WarrantNonceExhaustedError} rather than guessing, because every guess
+ * from there is refused forever.
+ *
+ * # On an older node
+ *
+ * The route is new and absent from core `master` builds, which answer 404 —
+ * {@link AdminApiClient.getWarrantNonce} surfaces that as
+ * `WarrantNonceRouteUnavailableError`. It reaches the caller as a lookup
+ * failure, so `onLookupFailure` decides: refuse to mint, or fall back to the
+ * local counter.
+ */
+export function createRecoveringNonceSource(options) {
+    const lookups = Array.isArray(options.lookups)
+        ? options.lookups
+        : [options.lookups];
+    if (lookups.length === 0) {
+        throw new Error('a recovering nonce source needs at least one node to ask');
+    }
+    const local = options.local ?? createMemoryNonceSource(1);
+    const onLookupFailure = options.onLookupFailure ?? 'throw';
+    let floor = null;
+    // Memoised so concurrent first calls ask once. Cleared on failure, since a
+    // node that was unreachable a moment ago may answer the next call — caching
+    // the failure would make one flaky request poison the whole session.
+    let pending = null;
+    const resolveFloor = async () => {
+        const answers = await Promise.allSettled(lookups.map((lookup) => lookup.getWarrantNonce(options.contextId, options.authorDeviceKey)));
+        let highest = null;
+        let exhausted = false;
+        for (const answer of answers) {
+            if (answer.status !== 'fulfilled')
+                continue;
+            const state = answer.value;
+            if (state.kind === 'exhausted') {
+                exhausted = true;
+                continue;
+            }
+            if (highest === null || state.nextNonce > highest)
+                highest = state.nextNonce;
+        }
+        // Exhaustion is only decisive when nothing usable came back. One node
+        // saturated while another still has room is not a thing the ledger can
+        // produce — the sequence is the device's, not the node's — but if it ever
+        // is, the usable answer is the actionable one.
+        if (highest === null && exhausted) {
+            throw new WarrantNonceExhaustedError(options.contextId, options.authorDeviceKey);
+        }
+        if (highest === null) {
+            const first = answers.find((a) => a.status === 'rejected');
+            const reason = first && first.status === 'rejected' ? first.reason : undefined;
+            if (onLookupFailure === 'local') {
+                floor = 0n;
+                return;
+            }
+            throw reason instanceof Error
+                ? reason
+                : new Error(`no node could answer where the warrant-nonce sequence stands: ${String(reason)}`);
+        }
+        floor = highest;
+        await local.advanceTo?.(highest);
+    };
+    return {
+        async next() {
+            if (floor === null) {
+                pending ?? (pending = resolveFloor().finally(() => {
+                    pending = null;
+                }));
+                await pending;
+            }
+            const mine = await local.next();
+            const value = floor !== null && floor > mine ? floor : mine;
+            // Advance the floor past what was just handed out, so a local source that
+            // is behind cannot re-offer this number on the next call.
+            floor = value + 1n;
+            return value;
+        },
+        async advanceTo(wanted) {
+            if (floor === null || wanted > floor)
+                floor = wanted;
+            await local.advanceTo?.(wanted);
+        },
     };
 }