@calimero-network/mero-js 22.7.0 → 22.9.0

package/dist/invitation/index.d.ts

@@ -0,0 +1,2 @@
+export { signGroupInvitation, encodeGroupInvitation, groupInvitationHash, defaultAdmitters, MAX_INVITATION_VALIDITY_SECS, INVITED_ROLE, } from './invitation.js';
+export type { GroupInvitationInput } from './invitation.js';

package/dist/invitation/index.js

@@ -0,0 +1,2 @@
+// Minting a group invitation off-node, with a device key.
+export { signGroupInvitation, encodeGroupInvitation, groupInvitationHash, defaultAdmitters, MAX_INVITATION_VALIDITY_SECS, INVITED_ROLE, } from './invitation.js';

package/dist/invitation/invitation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Minting a group invitation without a node.
+ *
+ * An invitation is not a governance op. Nothing is published when one is made:
+ * it is a bearer credential, `GroupInvitationFromAdmin` borsh-encoded, hashed
+ * with SHA-256 and signed by the inviter's key. A node mints one with its own
+ * namespace key; an account with **no node** signs it here with its device key.
+ *
+ * Every peer that later folds the join resolves `inviter_identity` — the
+ * signing key — to an account through the namespace's device bindings, and then
+ * checks that account holds admin or `CAN_INVITE_MEMBERS` at the join's causal
+ * cut. So the device key must be **bound** in the namespace first. It is when
+ * the account joined through an invitation; an account that was added by
+ * account (`MemberAdded`) has no binding, and a relay has to carry its device
+ * link first — see `AdminApiClient.linkAccountDevice` and `signDeviceScope`.
+ * Without that, every peer refuses the join as signed by a key "bound to no
+ * account".
+ *
+ * Derived from core:
+ *
+ * - `GroupInvitationFromAdmin` / `SignedGroupOpenInvitation` —
+ *   `crates/context/config/src/types.rs`
+ * - the signing — `crates/context/src/handlers/create_group_invitation.rs`:
+ *   `sign(sha256(borsh(invitation)))`
+ * - the admitter default — `NamespaceMembershipService::default_admitters`
+ *
+ * The unit tests pin bytes and a signature produced by core's own types.
+ */
+import type { GroupInvitationFromAdmin, GroupMember, SignedGroupOpenInvitation } from '../admin-api/admin-types.js';
+import { type Signer } from '../signer/signer.js';
+/**
+ * Core's `MAX_INVITATION_VALIDITY_SECS`: one day. Core clamps what a node mints
+ * to it, and this does the same, so a leaked invitation is redeemable no longer
+ * than one a node would have issued.
+ */
+export declare const MAX_INVITATION_VALIDITY_SECS: number;
+/** `invited_role` values, as core numbers them. */
+export declare const INVITED_ROLE: {
+    readonly Admin: 0;
+    readonly Member: 1;
+    readonly ReadOnly: 2;
+};
+/** Borsh-encode the signed body of an invitation, field for field with core. */
+export declare function encodeGroupInvitation(body: GroupInvitationFromAdmin): Uint8Array;
+/** `sha256(borsh(invitation))`: the 32 bytes the inviter's key signs. */
+export declare function groupInvitationHash(body: GroupInvitationFromAdmin): Promise<Uint8Array>;
+/**
+ * The admitters a node names when its caller names none: the group's admins,
+ * sorted by account bytes and deduplicated, as core's `BTreeSet` leaves them.
+ *
+ * Core also adds TEE-admitted accounts, which a member list cannot tell apart
+ * from members by role alone; name those in `admitters` explicitly.
+ */
+export declare function defaultAdmitters(members: readonly GroupMember[]): string[];
+/** What {@link signGroupInvitation} needs. */
+export interface GroupInvitationInput {
+    /** The group (or namespace) invited to, 64 hex. */
+    groupId: string;
+    /**
+     * The account the inviter acts as, 64 hex. An unsigned bootstrap hint the
+     * joiner seeds the group's admin view from; it confers nothing.
+     */
+    inviterAccount: string;
+    /** The device key as a {@link Signer}. Pass this or {@link deviceSecret}. */
+    signer?: Signer;
+    /** The device signing secret, 64 hex. Pass this or {@link signer}. */
+    deviceSecret?: string;
+    /**
+     * Accounts permitted to admit a claim, 64 hex each. Signed.
+     *
+     * Omitted or empty, it defaults to the group's admins, which is what a node
+     * does — pass {@link members} (from `listGroupMembers`) to derive them. An
+     * empty list would mean *claimable by broadcast*, which publishes the
+     * invitation to every subscriber of the namespace topic, so this never
+     * produces one.
+     */
+    admitters?: readonly string[];
+    /** The group's members, to default {@link admitters} from. */
+    members?: readonly GroupMember[];
+    /**
+     * The role granted, as {@link INVITED_ROLE} numbers it. Defaults to Member.
+     * Only an admin may invite an admin; peers refuse the join otherwise.
+     */
+    invitedRole?: number;
+    /**
+     * Seconds from now until it expires, clamped to
+     * {@link MAX_INVITATION_VALIDITY_SECS} (also the default).
+     */
+    validForSecs?: number;
+    /** Unix seconds to count from. Defaults to the clock; for tests. */
+    now?: number;
+    /** The 32-byte uniqueness nonce. Defaults to fresh random bytes. */
+    nonce?: Uint8Array;
+    /** Unsigned bootstrap: the group's application id, 64 hex. */
+    applicationId?: string;
+    /** Unsigned bootstrap: the group's `app_key` (core's `bytecode_id`), 64 hex. */
+    appKey?: string;
+    /** Unsigned bootstrap: multiaddrs for the admitters, `/p2p/<peer>` included. */
+    admitterAddrs?: readonly string[];
+}
+/**
+ * Sign a group invitation with a device key, returning it in the JSON shape a
+ * node's `createGroupInvitation` returns — so it goes to `joinGroup`,
+ * `signMemberJoinOp` and `admitJoin` unchanged.
+ */
+export declare function signGroupInvitation(input: GroupInvitationInput): Promise<SignedGroupOpenInvitation>;

package/dist/invitation/invitation.js

@@ -0,0 +1,104 @@
+import { concat, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+/**
+ * Core's `MAX_INVITATION_VALIDITY_SECS`: one day. Core clamps what a node mints
+ * to it, and this does the same, so a leaked invitation is redeemable no longer
+ * than one a node would have issued.
+ */
+export const MAX_INVITATION_VALIDITY_SECS = 24 * 60 * 60;
+/** `invited_role` values, as core numbers them. */
+export const INVITED_ROLE = { Admin: 0, Member: 1, ReadOnly: 2 };
+/** Borsh-encode the signed body of an invitation, field for field with core. */
+export function encodeGroupInvitation(body) {
+    const admitters = body.admitters ?? [];
+    return concat(
+    // `SignerId` and `ContextGroupId` cross JSON as 32 numbers; `AccountId`
+    // crosses as hex. Same width, different spelling.
+    bytes32(body.inviter_identity, 'inviter_identity'), bytes32(body.group_id, 'group_id'), u64le(body.expiration_timestamp), bytes32(body.secret_salt, 'secret_salt'), new Uint8Array([body.invited_role]), u32le(admitters.length), ...admitters.map((a, i) => fromHex(a, `admitters[${i}]`, 32)));
+}
+/** `sha256(borsh(invitation))`: the 32 bytes the inviter's key signs. */
+export async function groupInvitationHash(body) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', encodeGroupInvitation(body)));
+}
+/**
+ * The admitters a node names when its caller names none: the group's admins,
+ * sorted by account bytes and deduplicated, as core's `BTreeSet` leaves them.
+ *
+ * Core also adds TEE-admitted accounts, which a member list cannot tell apart
+ * from members by role alone; name those in `admitters` explicitly.
+ */
+export function defaultAdmitters(members) {
+    const admins = new Set(members.filter((m) => m.role === 'Admin').map((m) => m.identity.toLowerCase()));
+    // Lowercase hex sorts as the bytes do.
+    return [...admins].sort();
+}
+/**
+ * Sign a group invitation with a device key, returning it in the JSON shape a
+ * node's `createGroupInvitation` returns — so it goes to `joinGroup`,
+ * `signMemberJoinOp` and `admitJoin` unchanged.
+ */
+export async function signGroupInvitation(input) {
+    const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const inviterKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
+    const groupId = fromHex(input.groupId, 'groupId', 32);
+    fromHex(input.inviterAccount, 'inviterAccount', 32);
+    let admitters = [...(input.admitters ?? [])].map((a) => a.trim().toLowerCase());
+    if (admitters.length === 0) {
+        if (!input.members) {
+            throw new Error('name the admitters, or pass the group members to default them to its admins: ' +
+                'an invitation with no admitters is claimable by broadcast');
+        }
+        admitters = defaultAdmitters(input.members);
+        if (admitters.length === 0) {
+            throw new Error('the member list names no admin, so there is nobody to default the admitters to');
+        }
+    }
+    admitters.forEach((a, i) => fromHex(a, `admitters[${i}]`, 32));
+    const invitedRole = input.invitedRole ?? INVITED_ROLE.Member;
+    if (![0, 1, 2].includes(invitedRole)) {
+        throw new Error(`invitedRole must be 0 (Admin), 1 (Member) or 2 (ReadOnly), got ${invitedRole}`);
+    }
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const validFor = Math.min(input.validForSecs ?? MAX_INVITATION_VALIDITY_SECS, MAX_INVITATION_VALIDITY_SECS);
+    if (!Number.isInteger(validFor) || validFor <= 0) {
+        throw new Error(`validForSecs must be a positive whole number, got ${input.validForSecs}`);
+    }
+    const nonce = input.nonce ?? crypto.getRandomValues(new Uint8Array(32));
+    if (nonce.length !== 32) {
+        throw new Error(`nonce must be 32 bytes, got ${nonce.length}`);
+    }
+    const invitation = {
+        inviter_identity: Array.from(inviterKey),
+        group_id: Array.from(groupId),
+        expiration_timestamp: now + validFor,
+        secret_salt: Array.from(nonce),
+        invited_role: invitedRole,
+        admitters,
+    };
+    const signature = await signer.sign(await groupInvitationHash(invitation));
+    if (signature.length !== 64) {
+        throw new Error(`signer returned ${signature.length} bytes, expected a 64-byte Ed25519 signature`);
+    }
+    const signed = {
+        invitation,
+        inviter_signature: hex(signature),
+        inviter_account: input.inviterAccount.trim().toLowerCase(),
+    };
+    if (input.admitterAddrs?.length)
+        signed.admitter_addrs = [...input.admitterAddrs];
+    if (input.applicationId) {
+        signed.application_id = Array.from(fromHex(input.applicationId, 'applicationId', 32));
+    }
+    if (input.appKey)
+        signed.app_key = Array.from(fromHex(input.appKey, 'appKey', 32));
+    // The brand marks a value as one to pass through unchanged. This one is
+    // signed, so it qualifies the same way a node's does.
+    return signed;
+}
+/** A required `[u8; 32]`, as JSON carries it: 32 byte values. */
+function bytes32(value, label) {
+    if (value.length !== 32) {
+        throw new Error(`${label} must be 32 bytes, got ${value.length}`);
+    }
+    return new Uint8Array(value);
+}

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,6 @@
-import { concat, derivePublicKey, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { encodeGroupInvitation } from '../invitation/invitation.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.
  *
@@ -37,13 +39,6 @@ const ROOT_OP = {
     NamespaceCreatedV2: 9,
     MemberJoinedViaTeeAttestation: 10,
 };
-/** A required `[u8; 32]`, as JSON carries it: 32 byte values. */
-function bytes32(value, label) {
-    if (value.length !== 32) {
-        throw new Error(`${label} must be 32 bytes, got ${value.length}`);
-    }
-    return new Uint8Array(value);
-}
 /**
  * Borsh `Option<[u8; 32]>` from the byte array JSON carries it as.
  *
@@ -77,15 +72,11 @@ function borshString(value) {
  */
 export function encodeSignedInvitation(signed) {
     const body = signed.invitation;
-    const admitters = body.admitters ?? [];
     const admitterAddrs = signed.admitter_addrs ?? [];
     return concat(
-    // GroupInvitationFromAdmin.
-    //
-    // `SignerId` and `ContextGroupId` cross JSON as 32 numbers; `AccountId`
-    // crosses as hex. Same width, different spelling, and reading either the
-    // wrong way yields 32 bytes that encode cleanly and verify as nothing.
-    bytes32(body.inviter_identity, 'inviter_identity'), bytes32(body.group_id, 'group_id'), u64le(body.expiration_timestamp), bytes32(body.secret_salt, 'secret_salt'), new Uint8Array([body.invited_role]), u32le(admitters.length), ...admitters.map((a, i) => fromHex(a, `admitters[${i}]`, 32)), 
+    // GroupInvitationFromAdmin, from the one encoder the SDK's own invitation
+    // signer uses: the bytes signed and the bytes carried must not drift.
+    encodeGroupInvitation(body), 
     // ...then the enclosing SignedGroupOpenInvitation, in declaration order.
     // `inviter_account` sits between the signature and the addresses; putting it
     // anywhere else still encodes 32 bytes and still verifies as nothing.
@@ -122,10 +113,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, FoundNamespaceInput, FoundedNamespace, } from './relay-client.js';
-export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';
-export type { NonceSource } from './nonce-source.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;