@interop/wallet-core 0.41.0 → 0.43.0

package/dist/unlock/ladder.js

@@ -0,0 +1,144 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The update-key ladder: a standing unlock credential's latent-and-consumed
+ * did:webvh update authority. Rungs derive deterministically from a random
+ * 32-byte ladder seed carried inside the credential's unlock record -- never
+ * from the unlock secret itself, because a revealed rung lives verbatim in
+ * the world-readable `updateKeys` forever, where no hash commitment can
+ * protect it, so a secret-derived rung would be a standing offline grind
+ * oracle against the credential.
+ *
+ * Between uses only `hash(rung i)` stands in the document's `nextKeyHashes`;
+ * each self-enrollment is one loud reveal-and-commit entry signing with rung
+ * `i` and committing `hash(rung i + 1)`, after which the add entry retires
+ * the spent rung. The credential never holds a standing `updateKeys` member.
+ *
+ * There is no stored counter: which rung is current is recovered by
+ * re-deriving and scanning the published log's standing parameters
+ * ({@link attributeLadderRung}), and ambiguity fails closed rather than
+ * guessing -- the clients-listing attribution precedent. A lost
+ * compare-and-swap race resolves by determinism: the winner's entry commits
+ * `hash(rung i + 1)`, which IS the loser's retry key, so a re-run
+ * re-attributes and climbs one rung.
+ *
+ * The rung derivation is wire-level (both wallet apps must climb the same
+ * ladder from the same seed), so the salt and info labels are permanent.
+ */
+import { deriveNextKeyHash } from '@interop/did-method-webvh';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { updateKeyMultibase } from '../webvh/didWebvh.js';
+/**
+ * The byte length of a ladder seed: 32 random bytes, minted at bind time and
+ * carried only inside the unlock record's sealed ladder member.
+ */
+export const LADDER_SEED_BYTES = 32;
+/**
+ * The HKDF salt for rung derivation and the per-rung info prefix (the rung
+ * index in decimal follows it). Both permanent -- changing either orphans
+ * every bound credential's ladder.
+ */
+const LADDER_SALT = 'freewallet/unlock/update-ladder/v1';
+const LADDER_RUNG_INFO_PREFIX = 'rung/';
+/**
+ * How many rungs {@link attributeLadderRung} derives before concluding the
+ * log commits none of them. Generous: one rung is consumed per
+ * self-enrollment, so a real ladder's standing commitment sits at the number
+ * of self-enrollments the credential has ever performed.
+ */
+export const LADDER_MAX_SCAN = 128;
+/**
+ * Thrown when the published log's standing parameters match no derivable rung
+ * -- the credential's posture was revoked (or never published), the ladder
+ * seed does not belong to this account, or the scan bound was exceeded -- or
+ * when they match more than one rung in the same role, which no legitimate
+ * history produces. Self-enrollment refuses loudly rather than guessing.
+ */
+export class LadderAttributionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LadderAttributionError';
+    }
+}
+/**
+ * Generates a fresh random ladder seed.
+ *
+ * @returns {Uint8Array}
+ */
+export function generateLadderSeed() {
+    return crypto.getRandomValues(new Uint8Array(LADDER_SEED_BYTES));
+}
+/**
+ * Derives the 32-byte update-key seed of rung `index`.
+ *
+ * @param options {object}
+ * @param options.ladderSeed {Uint8Array}
+ * @param options.index {number}   the rung index, from 0
+ * @returns {Uint8Array}
+ */
+export function ladderRungSeed({ ladderSeed, index }) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`Invalid ladder rung index "${String(index)}".`);
+    }
+    return hkdf(sha256, ladderSeed, new TextEncoder().encode(LADDER_SALT), new TextEncoder().encode(`${LADDER_RUNG_INFO_PREFIX}${index}`), 32);
+}
+/**
+ * Derives rung `index` in full: seed and public multibase.
+ *
+ * @param options {object}
+ * @param options.ladderSeed {Uint8Array}
+ * @param options.index {number}   the rung index, from 0
+ * @returns {Promise<LadderRung>}
+ */
+export async function ladderRung({ ladderSeed, index }) {
+    const seed = ladderRungSeed({ ladderSeed, index });
+    return { index, seed, keyMultibase: await updateKeyMultibase({ seed }) };
+}
+/**
+ * Recovers the ladder's current rung from the published log's standing
+ * parameters -- the counter recovery that replaces any stored counter. Scans
+ * rungs `0..maxScan - 1`; a rung whose key stands in `updateKeys` is a torn
+ * self-enrollment to resume (`'revealed'`), else a rung whose hash stands in
+ * `nextKeyHashes` is the standing commitment (`'committed'`). Exactly one
+ * revealed rung, or exactly one committed rung beside it, is legitimate --
+ * the reveal entry keeps the spent rung's hash committed so a resumed run can
+ * re-state it, which is why a revealed rung wins over a committed one.
+ * Anything else fails closed with {@link LadderAttributionError}.
+ *
+ * @param options {object}
+ * @param options.ladderSeed {Uint8Array}
+ * @param options.published {object}   the resolved log's standing parameters
+ * @param options.published.updateKeys {string[]}
+ * @param options.published.nextKeyHashes {string[]}
+ * @param [options.maxScan] {number}   how many rungs to derive before giving
+ *   up; defaults to {@link LADDER_MAX_SCAN}
+ * @returns {Promise<{ rung: LadderRung, state: LadderRungState }>}
+ */
+export async function attributeLadderRung({ ladderSeed, published, maxScan = LADDER_MAX_SCAN }) {
+    const revealed = [];
+    const committed = [];
+    for (let index = 0; index < maxScan; index++) {
+        const rung = await ladderRung({ ladderSeed, index });
+        if (published.updateKeys.includes(rung.keyMultibase)) {
+            revealed.push(rung);
+        }
+        else if (published.nextKeyHashes.includes(await deriveNextKeyHash(rung.keyMultibase))) {
+            committed.push(rung);
+        }
+    }
+    if (revealed.length > 1 || committed.length > 1) {
+        throw new LadderAttributionError('The published log commits more than one rung of this ladder in the ' +
+            'same role; refusing to self-enroll on an ambiguous attribution.');
+    }
+    if (revealed.length === 1) {
+        return { rung: revealed[0], state: 'revealed' };
+    }
+    if (committed.length === 1) {
+        return { rung: committed[0], state: 'committed' };
+    }
+    throw new LadderAttributionError('The published log commits no rung of this ladder; the credential has ' +
+        'been revoked, was never published, or does not belong to this account.');
+}
+//# sourceMappingURL=ladder.js.map

package/dist/unlock/ladder.js.map

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

package/dist/unlock/selfEnroll.d.ts

@@ -0,0 +1,83 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The self-enrollment completion core: what a fresh browser runs once its
+ * typed credential has located the account, proven the unlock record genuine,
+ * and handed over the bridge delegation and the ladder seed. One call turns
+ * the credential's latent authority into an ordinary enrolled client, with no
+ * second party involved:
+ *
+ * 1. Mint the new client's whole key set locally (client seed, did:webvh
+ *    update-key seeds). Nothing is durable before the ceremony succeeds.
+ * 2. Write the self-enrolling continuation through the delegated `did.jsonl`
+ *    bridge ({@link selfEnrollWebvhClient}): the reveal-and-commit entry
+ *    signed by the attributed ladder rung, then the add entry that publishes
+ *    the new client and retires the rung. Loud by construction -- the
+ *    world-readable, hash-chained log extends before a single byte can be
+ *    read.
+ * 3. Verify the account log locally and perform the first roster read,
+ *    signed with the just-published `<did:webvh>#<multibase>` key and
+ *    unwrapping the user key from the CREDENTIAL's standing wrap (escrowed
+ *    into every epoch at bind time, kept alive by rotation fan-out).
+ * 4. Escrow the new client into the roster as its own recipient
+ *    (`addUserKeyRosterRecipient`, epochs unwrapped with the credential's
+ *    key-agreement key), so later logins on this browser read the roster the
+ *    ordinary enrolled way.
+ *
+ * Persisting the key set under the app's own unlock layer is the caller's
+ * job, exactly as with the enrollment ceremony's completion: this module
+ * hands back the key set, the user key, and the roster epoch to pin, and
+ * stops there. Every stage is idempotent, so a torn run converges by
+ * re-running with the same credential (step 2 resumes from the standing
+ * commitments; a re-run after completion mints a fresh client, which is the
+ * ordinary next self-enrollment).
+ */
+import type { IKeyAgreementKey } from '@interop/data-integrity-core';
+import type { UserKey } from '../keys/userKey.js';
+import type { AccountPointer } from '../keyring/record.js';
+import { type ResourceLogPinStore } from '../resourceLog/index.js';
+import type { ClientWebvhUpdateKeys } from '../webvh/didWebvh.js';
+import type { UnlockLogStore } from './standingWebvh.js';
+/**
+ * Runs the whole self-enrollment described in the module doc. The caller has
+ * already unwrapped the credential's unlock record (so it holds the
+ * credential-authenticated pointer, the bridge delegation behind `logStore`,
+ * and the ladder seed) and derived the credential's client identity (so it
+ * holds the key-agreement key with its secret half).
+ *
+ * @param options {object}
+ * @param options.pointer {AccountPointer}   the credential-authenticated
+ *   account pointer; must name a did:webvh
+ * @param options.ladderSeed {Uint8Array}   the credential's update-key ladder
+ *   seed, from its unlock record
+ * @param options.credentialKeyAgreementKey {IKeyAgreementKey}   the
+ *   credential's own key-agreement key (secret half included) -- its roster
+ *   entry, which the user key is unwrapped from and every epoch re-wrapped
+ *   with
+ * @param options.logStore {UnlockLogStore}   the public log read plus the
+ *   delegated `did.jsonl` PUT, built by the app around the record's bridge
+ *   delegation
+ * @param [options.accountLogPinStore] {ResourceLogPinStore}   this client's
+ *   chain-head pin for the account log. A fresh browser normally has none
+ *   (this is its first contact), which is exactly the pin's
+ *   trust-on-first-use establishment
+ * @returns {Promise<object>}   the new client's key set (for the caller to
+ *   persist under its unlock layer), its did:key, the account DID, the user
+ *   key, and the roster epoch to pin
+ */
+export declare function selfEnrollClientCore({ pointer, ladderSeed, credentialKeyAgreementKey, logStore, accountLogPinStore }: {
+    pointer: AccountPointer;
+    ladderSeed: Uint8Array;
+    credentialKeyAgreementKey: IKeyAgreementKey;
+    logStore: UnlockLogStore;
+    accountLogPinStore?: ResourceLogPinStore;
+}): Promise<{
+    clientSeed: Uint8Array;
+    webvhUpdateKeys: ClientWebvhUpdateKeys;
+    clientDid: string;
+    did: string;
+    userKey: UserKey;
+    latestEpochId: string;
+}>;
+//# sourceMappingURL=selfEnroll.d.ts.map

package/dist/unlock/selfEnroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfEnroll.d.ts","sourceRoot":"","sources":["../../src/unlock/selfEnroll.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AASpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAA;AAKhC,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,sBAAsB,CAAA;AAQ7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,UAAU,EACV,yBAAyB,EACzB,QAAQ,EACR,kBAAkB,EACnB,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,UAAU,CAAA;IACtB,yBAAyB,EAAE,gBAAgB,CAAA;IAC3C,QAAQ,EAAE,cAAc,CAAA;IACxB,kBAAkB,CAAC,EAAE,mBAAmB,CAAA;CACzC,GAAG,OAAO,CAAC;IACV,UAAU,EAAE,UAAU,CAAA;IACtB,eAAe,EAAE,qBAAqB,CAAA;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;CACtB,CAAC,CAqGD"}

package/dist/unlock/selfEnroll.js

@@ -0,0 +1,126 @@
+import { agentsFromSeed } from '../identity/agents.js';
+import { addUserKeyRosterRecipient, readUserKeyRoster, rosterRecipientKid, userKeyRosterLogSigner } from '../keys/userKeyRoster.js';
+import { userKeyRosterDescriptorStore } from '../keys/rosterStore.js';
+import { memoryResourceLogPinStore, webvhResourceLogController } from '../resourceLog/index.js';
+import { mintClientWebvhUpdateKeys, updateKeyMultibase } from '../webvh/didWebvh.js';
+import { verifyAccountLog } from '../webvh/verifyLog.js';
+import { clientSigningKeyMultibase, isWebvhDid, webvhZcapClient } from '../webvh/zcap.js';
+import { selfEnrollWebvhClient } from './standingWebvh.js';
+/**
+ * Runs the whole self-enrollment described in the module doc. The caller has
+ * already unwrapped the credential's unlock record (so it holds the
+ * credential-authenticated pointer, the bridge delegation behind `logStore`,
+ * and the ladder seed) and derived the credential's client identity (so it
+ * holds the key-agreement key with its secret half).
+ *
+ * @param options {object}
+ * @param options.pointer {AccountPointer}   the credential-authenticated
+ *   account pointer; must name a did:webvh
+ * @param options.ladderSeed {Uint8Array}   the credential's update-key ladder
+ *   seed, from its unlock record
+ * @param options.credentialKeyAgreementKey {IKeyAgreementKey}   the
+ *   credential's own key-agreement key (secret half included) -- its roster
+ *   entry, which the user key is unwrapped from and every epoch re-wrapped
+ *   with
+ * @param options.logStore {UnlockLogStore}   the public log read plus the
+ *   delegated `did.jsonl` PUT, built by the app around the record's bridge
+ *   delegation
+ * @param [options.accountLogPinStore] {ResourceLogPinStore}   this client's
+ *   chain-head pin for the account log. A fresh browser normally has none
+ *   (this is its first contact), which is exactly the pin's
+ *   trust-on-first-use establishment
+ * @returns {Promise<object>}   the new client's key set (for the caller to
+ *   persist under its unlock layer), its did:key, the account DID, the user
+ *   key, and the roster epoch to pin
+ */
+export async function selfEnrollClientCore({ pointer, ladderSeed, credentialKeyAgreementKey, logStore, accountLogPinStore }) {
+    const expectedDid = pointer.did;
+    if (!expectedDid || !isWebvhDid(expectedDid)) {
+        throw new Error('The account pointer names no did:webvh; only a promoted account can ' +
+            'self-enroll a client.');
+    }
+    // The new client's whole key set, minted locally; nothing travels but the
+    // public halves the log entries publish.
+    const clientSeed = crypto.getRandomValues(new Uint8Array(32));
+    const { keyAgent, keyAgreementKey } = await agentsFromSeed({
+        seed: clientSeed
+    });
+    const { publicKeyMultibase: keyAgreementKeyMultibase } = keyAgreementKey;
+    if (!keyAgreementKeyMultibase) {
+        throw new Error('The minted key-agreement key has no public multibase.');
+    }
+    const signingKeyMultibase = clientSigningKeyMultibase({ keyAgent });
+    const webvhUpdateKeys = await mintClientWebvhUpdateKeys();
+    const newClientKeys = {
+        signingKeyMultibase,
+        keyAgreementKeyMultibase,
+        updateKeyMultibase: await updateKeyMultibase({
+            seed: webvhUpdateKeys.updateSeed
+        }),
+        stagedUpdateKeyMultibase: await updateKeyMultibase({
+            seed: webvhUpdateKeys.stagedSeed
+        })
+    };
+    // The loud half: two log entries through the delegated bridge.
+    await selfEnrollWebvhClient({
+        store: logStore,
+        ladderSeed,
+        newClientKeys,
+        newClientUpdateSeeds: webvhUpdateKeys,
+        expectedDid
+    });
+    // Verify the continuation from the world-readable log -- the same
+    // first-contact read an enrollee's completion runs, and the controller the
+    // roster log's entry proofs are checked against.
+    const verified = await verifyAccountLog({
+        did: expectedDid,
+        spaceId: pointer.spaceId,
+        host: pointer.host,
+        ...(accountLogPinStore ? { pinStore: accountLogPinStore } : {})
+    });
+    // The first roster read: signed with the `<did:webvh>#<multibase>` keyId
+    // the add entry just published, unwrapping the user key from the
+    // CREDENTIAL's standing wrap. First contact: the chain-head pin this read
+    // establishes is session-local here; the app's durable pin is established
+    // by its own first login read.
+    const zcapClient = webvhZcapClient({ keyAgent, did: expectedDid });
+    const store = userKeyRosterDescriptorStore({
+        storageServerUrl: pointer.host,
+        zcapClient,
+        spaceId: pointer.spaceId,
+        resolveController: async () => webvhResourceLogController({ did: expectedDid, log: verified.log }),
+        pinStore: memoryResourceLogPinStore(),
+        signer: userKeyRosterLogSigner({ keyAgent })
+    });
+    const read = await readUserKeyRoster({
+        store,
+        clientKeyAgreementKey: credentialKeyAgreementKey
+    });
+    if (!read) {
+        throw new Error('The account has no user key roster; it must finish provisioning ' +
+            'before a client can self-enroll.');
+    }
+    // Escrow the new client into the roster as its own recipient, so later
+    // logins on this browser read the roster the ordinary enrolled way.
+    // Idempotent: a wrap already standing is returned as-is.
+    await addUserKeyRosterRecipient({
+        store,
+        recipient: {
+            id: rosterRecipientKid({
+                signingKeyMultibase,
+                keyAgreementKeyMultibase
+            }),
+            publicKeyMultibase: keyAgreementKeyMultibase
+        },
+        ownerKeyAgreementKey: credentialKeyAgreementKey
+    });
+    return {
+        clientSeed,
+        webvhUpdateKeys,
+        clientDid: keyAgent.id,
+        did: expectedDid,
+        userKey: read.userKey,
+        latestEpochId: read.latestEpochId
+    };
+}
+//# sourceMappingURL=selfEnroll.js.map

package/dist/unlock/selfEnroll.js.map

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

package/dist/unlock/standingClient.d.ts

@@ -0,0 +1,68 @@
+import type { ProfileAgents } from '../identity/agents.js';
+/**
+ * The HKDF salt for a standing credential's client-side expansions, and the
+ * per-key info labels. All permanent. The salt differs from the recovery
+ * code's client salt (`freewallet/recovery/client-keys/v1`), so a code and a
+ * standing method that somehow shared input material could still never derive
+ * the same client identity.
+ */
+export declare const STANDING_CLIENT_SALT = "freewallet/unlock/standing-client/v1";
+/**
+ * A credential-derived client identity, assembled from its 32-byte client
+ * seed: the derived agents, the client did:key, the public multibases the
+ * document and roster carry, and the roster recipient kid. The shared shape
+ * of a standing credential's identity and a recovery code's (which extends it
+ * with the code's single update key).
+ */
+export interface UnlockClientIdentity {
+    clientSeed: Uint8Array;
+    agents: ProfileAgents;
+    clientDid: string;
+    signingKeyMultibase: string;
+    keyAgreementKeyMultibase: string;
+    /**
+     * The kid of the credential's user-key-roster entry -- its key-agreement
+     * key's id exactly as `agentsFromSeed` derives it (`did:key:<ed>#<x>`), so
+     * the wrap minted at bind time is the one a fresh browser's roster read
+     * looks for.
+     */
+    recipientKid: string;
+}
+/**
+ * Assembles a client identity from its 32-byte client seed: the one place the
+ * agents, multibases, and roster kid are derived, shared by the standing
+ * credential derivation here and the recovery code's
+ * (`recoveryClientFromCode`), so the two postures can never disagree on how a
+ * seed becomes an identity.
+ *
+ * @param options {object}
+ * @param options.clientSeed {Uint8Array}   the 32-byte client seed
+ * @returns {Promise<UnlockClientIdentity>}
+ */
+export declare function unlockClientIdentityFromSeed({ clientSeed }: {
+    clientSeed: Uint8Array;
+}): Promise<UnlockClientIdentity>;
+/**
+ * A standing unlock credential's full client-side key set: the client
+ * identity plus the binding MAC key that authenticates the unlock record's
+ * account core (computed at bind time, verified before the pointer is
+ * trusted -- the storage host never holds it).
+ */
+export interface StandingUnlockClient extends UnlockClientIdentity {
+    bindingMacKey: Uint8Array;
+}
+/**
+ * Derives a standing credential's client key set from the method's 32-byte
+ * unlock seed (the output of `deriveUnlockSeed` under the method's own KDF).
+ * Deterministic: the same secret under the same KDF always yields the same
+ * key set, which is what makes a fresh browser's self-enrollment possible
+ * with nothing but the credential in hand.
+ *
+ * @param options {object}
+ * @param options.unlockSeed {Uint8Array}   the method's 32-byte unlock seed
+ * @returns {Promise<StandingUnlockClient>}
+ */
+export declare function standingClientFromUnlockSeed({ unlockSeed }: {
+    unlockSeed: Uint8Array;
+}): Promise<StandingUnlockClient>;
+//# sourceMappingURL=standingClient.d.ts.map

package/dist/unlock/standingClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standingClient.d.ts","sourceRoot":"","sources":["../../src/unlock/standingClient.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,yCAAyC,CAAA;AAI1E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,aAAa,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,wBAAwB,EAAE,MAAM,CAAA;IAChC;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAAC,EACjD,UAAU,EACX,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;CACvB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgBhC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,aAAa,EAAE,UAAU,CAAA;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAAC,EACjD,UAAU,EACX,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;CACvB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkBhC"}

package/dist/unlock/standingClient.js

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The standing unlock credential's client identity: the deterministic key set
+ * every unlock method (a passphrase, a passkey PRF output) derives from its
+ * own unlock seed under the standing-credential posture -- the recovery-code
+ * posture minus spend-on-use. The credential's key-agreement key holds a
+ * standing wrap in the user key roster (escrowed into every epoch, kept alive
+ * by rotation fan-out), and its binding MAC key authenticates the unlock
+ * record's account core, so a fresh browser holding nothing but the
+ * credential can locate the account, prove the record genuine, and decrypt.
+ * Update authority stays latent and rides the record instead: the ladder seed
+ * (`./ladder`) never derives from the secret.
+ *
+ * The derivations are wire-level: two wallet apps must produce byte-identical
+ * output for the same secret and KDF, so every salt and info label below is
+ * permanent. The HKDF input is the method's own 32-byte unlock seed
+ * (`deriveUnlockSeed`), so the expensive passphrase stretch runs once per
+ * typed secret and each unlock method's distinct KDF salt keeps two methods'
+ * client identities from ever colliding.
+ */
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { agentsFromSeed } from '../identity/agents.js';
+/**
+ * The HKDF salt for a standing credential's client-side expansions, and the
+ * per-key info labels. All permanent. The salt differs from the recovery
+ * code's client salt (`freewallet/recovery/client-keys/v1`), so a code and a
+ * standing method that somehow shared input material could still never derive
+ * the same client identity.
+ */
+export const STANDING_CLIENT_SALT = 'freewallet/unlock/standing-client/v1';
+const STANDING_CLIENT_SEED_INFO = 'client-seed';
+const STANDING_BINDING_MAC_INFO = 'binding-mac';
+/**
+ * Assembles a client identity from its 32-byte client seed: the one place the
+ * agents, multibases, and roster kid are derived, shared by the standing
+ * credential derivation here and the recovery code's
+ * (`recoveryClientFromCode`), so the two postures can never disagree on how a
+ * seed becomes an identity.
+ *
+ * @param options {object}
+ * @param options.clientSeed {Uint8Array}   the 32-byte client seed
+ * @returns {Promise<UnlockClientIdentity>}
+ */
+export async function unlockClientIdentityFromSeed({ clientSeed }) {
+    const agents = await agentsFromSeed({ seed: clientSeed });
+    const { publicKeyMultibase: keyAgreementKeyMultibase } = agents.keyAgreementKey;
+    if (!keyAgreementKeyMultibase) {
+        throw new Error('The derived key-agreement key has no public multibase.');
+    }
+    const [, , signingKeyMultibase] = agents.keyAgent.id.split(':');
+    return {
+        clientSeed,
+        agents,
+        clientDid: agents.keyAgent.id,
+        signingKeyMultibase: signingKeyMultibase,
+        keyAgreementKeyMultibase,
+        recipientKid: `${agents.keyAgent.id}#${keyAgreementKeyMultibase}`
+    };
+}
+/**
+ * Derives a standing credential's client key set from the method's 32-byte
+ * unlock seed (the output of `deriveUnlockSeed` under the method's own KDF).
+ * Deterministic: the same secret under the same KDF always yields the same
+ * key set, which is what makes a fresh browser's self-enrollment possible
+ * with nothing but the credential in hand.
+ *
+ * @param options {object}
+ * @param options.unlockSeed {Uint8Array}   the method's 32-byte unlock seed
+ * @returns {Promise<StandingUnlockClient>}
+ */
+export async function standingClientFromUnlockSeed({ unlockSeed }) {
+    const salt = new TextEncoder().encode(STANDING_CLIENT_SALT);
+    const clientSeed = hkdf(sha256, unlockSeed, salt, new TextEncoder().encode(STANDING_CLIENT_SEED_INFO), 32);
+    const bindingMacKey = hkdf(sha256, unlockSeed, salt, new TextEncoder().encode(STANDING_BINDING_MAC_INFO), 32);
+    const identity = await unlockClientIdentityFromSeed({ clientSeed });
+    return { ...identity, bindingMacKey };
+}
+//# sourceMappingURL=standingClient.js.map

package/dist/unlock/standingClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standingClient.js","sourceRoot":"","sources":["../../src/unlock/standingClient.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAGtD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sCAAsC,CAAA;AAC1E,MAAM,yBAAyB,GAAG,aAAa,CAAA;AAC/C,MAAM,yBAAyB,GAAG,aAAa,CAAA;AAwB/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,EACjD,UAAU,EAGX;IACC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAA;IACzD,MAAM,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,GACpD,MAAM,CAAC,eAA6D,CAAA;IACtE,IAAI,CAAC,wBAAwB,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IACD,MAAM,CAAC,EAAE,AAAD,EAAG,mBAAmB,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC/D,OAAO;QACL,UAAU;QACV,MAAM;QACN,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE;QAC7B,mBAAmB,EAAE,mBAAoB;QACzC,wBAAwB;QACxB,YAAY,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,wBAAwB,EAAE;KAClE,CAAA;AACH,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,EACjD,UAAU,EAGX;IACC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAA;IAC3D,MAAM,UAAU,GAAG,IAAI,CACrB,MAAM,EACN,UAAU,EACV,IAAI,EACJ,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,yBAAyB,CAAC,EACnD,EAAE,CACH,CAAA;IACD,MAAM,aAAa,GAAG,IAAI,CACxB,MAAM,EACN,UAAU,EACV,IAAI,EACJ,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,yBAAyB,CAAC,EACnD,EAAE,CACH,CAAA;IACD,MAAM,QAAQ,GAAG,MAAM,4BAA4B,CAAC,EAAE,UAAU,EAAE,CAAC,CAAA;IACnE,OAAO,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,CAAA;AACvC,CAAC"}