@interop/wallet-core 0.16.0 → 0.18.0

package/dist/enrollment/enrollment.js

@@ -1,11 +1,12 @@
 import { base64urlnopad } from '@scure/base';
+import { multibaseDecode, MULTICODEC_X25519_PUB_HEADER } from '@interop/x25519-key-agreement-key';
 import { agentsFromSeed } from '../identity/agents.js';
 import { enrollWebvhClient, mintClientWebvhUpdateKeys, updateKeyMultibase } from '../webvh/didWebvh.js';
 import { clientSigningKeyMultibase, isWebvhDid, webvhZcapClient } from '../webvh/zcap.js';
 import { AccountLogMissingError, verifyAccountLog } from '../webvh/verifyLog.js';
-import { addPukRosterRecipient } from '../keys/pukRoster.js';
-import { readPukRoster, rosterRecipientKid } from '../keys/pukRoster.js';
-import { pukRosterDescriptorStore } from '../keys/rosterStore.js';
+import { addUserKeyRosterRecipient } from '../keys/userKeyRoster.js';
+import { readUserKeyRoster, rosterRecipientKid } from '../keys/userKeyRoster.js';
+import { userKeyRosterDescriptorStore } from '../keys/rosterStore.js';
 import { CONNECT_CODE_PREFIX } from './connectCode.js';
 /**
  * The connect-code payload version this build mints and accepts.
@@ -29,6 +30,48 @@ export class EnrollmentPendingError extends Error {
  */
 const ED25519_MULTIBASE_PREFIX = 'z6Mk';
 const X25519_MULTIBASE_PREFIX = 'z6LS';
+/**
+ * The multicodec varint header of an `ed25519-pub` value, the registry
+ * constant the `z6Mk` prefix renders. The X25519 counterpart is imported from
+ * the key suite that owns it; there is no exported Ed25519 equivalent.
+ */
+const MULTICODEC_ED25519_PUB_HEADER = new Uint8Array([0xed, 0x01]);
+/**
+ * The byte length of both public key types a connect code carries.
+ */
+const PUBLIC_KEY_BYTES = 32;
+/**
+ * Validates one connect-code key all the way down to its bytes: the multibase
+ * prefix, a real base58btc decode, the multicodec header, and the key length.
+ * The prefix alone is worth nothing here -- these keys are signed into an
+ * append-only did:webvh log, where a key that only LOOKS like a multibase is
+ * published forever.
+ *
+ * @param options {object}
+ * @param options.value {unknown}   the payload member
+ * @param options.prefix {string}   the expected multibase prefix
+ * @param options.header {Uint8Array}   the expected multicodec header bytes
+ * @param options.name {string}   the key's name, for the error message
+ * @returns {string}   the key, verbatim
+ */
+function requireConnectCodeKey({ value, prefix, header, name }) {
+    if (typeof value !== 'string' || !value.startsWith(prefix)) {
+        throw new Error(`The connect code carries a malformed ${name}.`);
+    }
+    let bytes;
+    try {
+        bytes = multibaseDecode(header, value);
+    }
+    catch (err) {
+        throw new Error(`The connect code carries a malformed ${name}.`, {
+            cause: err
+        });
+    }
+    if (bytes.length !== PUBLIC_KEY_BYTES) {
+        throw new Error(`The connect code carries a malformed ${name}.`);
+    }
+    return value;
+}
 /**
  * Encodes an enrollment request as a connect code.
  *
@@ -42,9 +85,11 @@ export function encodeEnrollmentRequest({ request }) {
 }
 /**
  * Parses and validates a connect code: the prefix, the payload version, and
- * the shape of each key (Ed25519 multibase for the signing and update keys,
- * X25519 for the key-agreement key). Throws on anything malformed -- a code
- * is typed or scanned, so a clear refusal beats a half-parsed ceremony.
+ * each key decoded to its bytes (Ed25519 multibase for the signing and update
+ * keys, X25519 for the key-agreement key). Throws on anything malformed -- a
+ * code is typed or scanned, so a clear refusal beats a half-parsed ceremony,
+ * and the approving client signs these keys into an append-only log where a
+ * corrupted one would be published permanently.
  *
  * @param options {object}
  * @param options.code {string}   the pasted/scanned connect code
@@ -69,17 +114,31 @@ export function parseEnrollmentRequest({ code }) {
     if (v !== CONNECT_CODE_VERSION) {
         throw new Error(`Unsupported connect code version "${String(v)}".`);
     }
-    const requireKey = (value, prefix, name) => {
-        if (typeof value !== 'string' || !value.startsWith(prefix)) {
-            throw new Error(`The connect code carries a malformed ${name}.`);
-        }
-        return value;
-    };
     return {
-        signingKeyMultibase: requireKey(signingKeyMultibase, ED25519_MULTIBASE_PREFIX, 'signing key'),
-        keyAgreementKeyMultibase: requireKey(keyAgreementKeyMultibase, X25519_MULTIBASE_PREFIX, 'key-agreement key'),
-        updateKeyMultibase: requireKey(updateKey, ED25519_MULTIBASE_PREFIX, 'update key'),
-        stagedUpdateKeyMultibase: requireKey(stagedUpdateKeyMultibase, ED25519_MULTIBASE_PREFIX, 'staged update key')
+        signingKeyMultibase: requireConnectCodeKey({
+            value: signingKeyMultibase,
+            prefix: ED25519_MULTIBASE_PREFIX,
+            header: MULTICODEC_ED25519_PUB_HEADER,
+            name: 'signing key'
+        }),
+        keyAgreementKeyMultibase: requireConnectCodeKey({
+            value: keyAgreementKeyMultibase,
+            prefix: X25519_MULTIBASE_PREFIX,
+            header: MULTICODEC_X25519_PUB_HEADER,
+            name: 'key-agreement key'
+        }),
+        updateKeyMultibase: requireConnectCodeKey({
+            value: updateKey,
+            prefix: ED25519_MULTIBASE_PREFIX,
+            header: MULTICODEC_ED25519_PUB_HEADER,
+            name: 'update key'
+        }),
+        stagedUpdateKeyMultibase: requireConnectCodeKey({
+            value: stagedUpdateKeyMultibase,
+            prefix: ED25519_MULTIBASE_PREFIX,
+            header: MULTICODEC_ED25519_PUB_HEADER,
+            name: 'staged update key'
+        })
     };
 }
 /**
@@ -148,8 +207,8 @@ export async function mintEnrollmentRequest() {
     };
 }
 /**
- * ENROLLING CLIENT: the whole approval, in the push order -- the PUK wrapped
- * into the roster first (escrow: every epoch, so the new client reads
+ * ENROLLING CLIENT: the whole approval, in the push order -- the user key
+ * wrapped into the roster first (escrow: every epoch, so the new client reads
  * pre-enrollment history), then the two log entries. Quorum-of-one: this
  * client's own update key signs both entries. Idempotent at every stage, so
  * re-approving the same code after any tear converges.
@@ -161,19 +220,19 @@ export async function mintEnrollmentRequest() {
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   the approving
  *   client's own (identity) key-agreement key, unwrapping each epoch for
  *   re-wrapping
- * @param options.pukRosterStore {EncryptionDescriptorStore}   the account's
- *   `key-map/puk.json` descriptor store
+ * @param options.userKeyRosterStore {EncryptionDescriptorStore}   the account's
+ *   `key-map/user-key.json` descriptor store
  * @param options.idStore {WebvhIdStore}   the account's `id` collection
  * @returns {Promise<object>}   the account's did:webvh, plus the enrollee's
  *   own identity as this call already knows it: its did:key and its signing-key
  *   multibase (the key a label or a listing row is filed under), so the caller
  *   needs no second parse of the connect code
  */
-export async function approveEnrollment({ request, clientWebvhKeys, clientKeyAgreementKey, pukRosterStore, idStore }) {
+export async function approveEnrollment({ request, clientWebvhKeys, clientKeyAgreementKey, userKeyRosterStore, idStore }) {
     // Decryption material before authorization: the wrap lands first, so no
     // enrolled client is ever authorized but blind.
-    await addPukRosterRecipient({
-        store: pukRosterStore,
+    await addUserKeyRosterRecipient({
+        store: userKeyRosterStore,
         recipient: {
             id: enrollmentRecipientKid({ request }),
             publicKeyMultibase: request.keyAgreementKeyMultibase
@@ -195,12 +254,12 @@ export async function approveEnrollment({ request, clientWebvhKeys, clientKeyAgr
  * ENROLLEE, step two (after the other client approves): verifies the
  * enrollment from the world-readable log and performs this client's first
  * roster read -- signed with its just-published `<did:webvh>#<multibase>`
- * key -- to obtain the PUK.
+ * key -- to obtain the user key.
  *
  * The portable core of the completion step: the caller supplies the account
  * pointer (from its own keyring lookup) and persists what comes back -- the
- * PUK, the roster epoch to pin, and the key set itself -- under its own unlock
- * layer. After that, an ordinary unlock finds an enrolled client.
+ * user key, the roster epoch to pin, and the key set itself -- under its own
+ * unlock layer. After that, an ordinary unlock finds an enrolled client.
  *
  * Throws `EnrollmentPendingError` while the add entry is not published yet
  * (complete again once the other client finishes); any integrity failure
@@ -213,7 +272,7 @@ export async function approveEnrollment({ request, clientWebvhKeys, clientKeyAgr
  *   `mintEnrollmentRequest`
  * @param options.pointer {AccountPointer}   the account pointer the enrollee's
  *   keyring lookup recovered
- * @returns {Promise<{ puk: Puk, latestEpochId: string }>}
+ * @returns {Promise<{ userKey: UserKey, latestEpochId: string }>}
  */
 export async function completeEnrollmentCore({ clientSeed, webvhUpdateKeys, pointer }) {
     const did = pointer.did;
@@ -251,22 +310,27 @@ export async function completeEnrollmentCore({ clientSeed, webvhUpdateKeys, poin
         throw new EnrollmentPendingError();
     }
     // The first roster read: signed with the `<did:webvh>#<multibase>` keyId
-    // the add entry just published, unwrapping the PUK the enrolling client
-    // escrowed to this client's key-agreement key.
+    // the add entry just published, unwrapping the user key the enrolling client
+    // escrowed to this client's key-agreement key. The verified document just
+    // resolved above is what the roster's epoch-configuration signature is
+    // checked against -- a first read adopts whatever epoch the roster serves,
+    // so it must trace to a key the document backs, not to the served
+    // descriptor's own MAC.
     const zcapClient = webvhZcapClient({ keyAgent, did });
-    const store = pukRosterDescriptorStore({
+    const store = userKeyRosterDescriptorStore({
         storageServerUrl: pointer.host,
         zcapClient,
         spaceId: pointer.spaceId
     });
-    const read = await readPukRoster({
+    const read = await readUserKeyRoster({
         store,
-        clientKeyAgreementKey: keyAgreementKey
+        clientKeyAgreementKey: keyAgreementKey,
+        document: verified.doc
     });
     if (!read) {
-        throw new Error('The account has no PUK roster; it must finish provisioning before ' +
+        throw new Error('The account has no user key roster; it must finish provisioning before ' +
             'a client can be enrolled.');
     }
-    return { puk: read.puk, latestEpochId: read.latestEpochId };
+    return { userKey: read.userKey, latestEpochId: read.latestEpochId };
 }
 //# sourceMappingURL=enrollment.js.map

package/dist/enrollment/enrollment.js.map

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

package/dist/enrollment/index.d.ts

@@ -14,7 +14,7 @@
  * - `approveEnrollment` -- the enrolling client's half, in the push order
  *   (roster wrap, then the two did:webvh log entries).
  * - `completeEnrollmentCore` -- the enrollee's half: verify from the published
- *   log, read the roster, hand back the PUK and the epoch to pin. Persisting
+ *   log, read the roster, hand back the user key and the epoch to pin. Persisting
  *   the key set stays with the caller's own unlock layer.
  */
 export { approveEnrollment, completeEnrollmentCore, encodeEnrollmentRequest, EnrollmentPendingError, enrollmentClientDid, enrollmentRecipientKid, mintEnrollmentRequest, parseEnrollmentRequest } from './enrollment.js';

package/dist/enrollment/index.js

@@ -14,7 +14,7 @@
  * - `approveEnrollment` -- the enrolling client's half, in the push order
  *   (roster wrap, then the two did:webvh log entries).
  * - `completeEnrollmentCore` -- the enrollee's half: verify from the published
- *   log, read the roster, hand back the PUK and the epoch to pin. Persisting
+ *   log, read the roster, hand back the user key and the epoch to pin. Persisting
  *   the key set stays with the caller's own unlock layer.
  */
 export { approveEnrollment, completeEnrollmentCore, encodeEnrollmentRequest, EnrollmentPendingError, enrollmentClientDid, enrollmentRecipientKid, mintEnrollmentRequest, parseEnrollmentRequest } from './enrollment.js';

package/dist/index.d.ts

@@ -19,8 +19,8 @@
  * - `@interop/wallet-core/webvh` -- the account's did:webvh identity: the
  *   hosted DID log, its per-client update-key rotation, the client enrollment
  *   entries, and ZCap signing under the did:webvh verification-method id.
- * - `@interop/wallet-core/keys` -- the per-user key (PUK) and its
- *   `key-map/puk.json` wrap-set roster.
+ * - `@interop/wallet-core/keys` -- the user key and its
+ *   `key-map/user-key.json` wrap-set roster.
  * - `@interop/wallet-core/descriptors` -- collection encryption-descriptor
  *   acquisition (fetch / cache / offline fallback) and the unknown-epoch
  *   refresh policy, including a self-refreshing EDV document cipher.

package/dist/index.js

@@ -19,8 +19,8 @@
  * - `@interop/wallet-core/webvh` -- the account's did:webvh identity: the
  *   hosted DID log, its per-client update-key rotation, the client enrollment
  *   entries, and ZCap signing under the did:webvh verification-method id.
- * - `@interop/wallet-core/keys` -- the per-user key (PUK) and its
- *   `key-map/puk.json` wrap-set roster.
+ * - `@interop/wallet-core/keys` -- the user key and its
+ *   `key-map/user-key.json` wrap-set roster.
  * - `@interop/wallet-core/descriptors` -- collection encryption-descriptor
  *   acquisition (fetch / cache / offline fallback) and the unknown-epoch
  *   refresh policy, including a self-refreshing EDV document cipher.

package/dist/keys/clientKeyRecord.d.ts

@@ -1,16 +1,16 @@
 import type { ClientWebvhUpdateKeys } from '../webvh/didWebvh.js';
-import type { Puk } from './puk.js';
+import type { UserKey } from './userKey.js';
 /**
  * A client-key record's contents, decoded.
  *
  * `clientSeed` is the only always-present member: the rest are absent on
- * records written before that member existed (a PUK-less account, a record
+ * records written before that member existed (a user-key-less account, a record
  * written before the update keys became client-held, a first client whose own
  * did:key IS the account controller), or simply not stored by the app.
  */
 export interface ClientKeyRecord {
     clientSeed: Uint8Array;
-    puk?: Puk;
+    userKey?: UserKey;
     webvhUpdateKeys?: ClientWebvhUpdateKeys;
     controller?: string;
     pointerDid?: string;
@@ -22,7 +22,7 @@ export interface ClientKeyRecord {
  */
 export interface ClientKeyRecordJson {
     clientSeed: string;
-    puk?: {
+    userKey?: {
         id: string;
         secret: string;
         signingSeed?: string;
@@ -38,28 +38,28 @@ export interface ClientKeyRecordJson {
 }
 /**
  * A record whose every member is present: what an ENROLLED client holds once
- * the enrollment ceremony has landed (a key set, a delivered PUK, its own
+ * the enrollment ceremony has landed (a key set, a delivered user key, its own
  * update-key seeds, and the account it belongs to).
  */
 export interface EnrolledClientKeyRecord extends ClientKeyRecord {
-    puk: Puk;
+    userKey: UserKey;
     webvhUpdateKeys: ClientWebvhUpdateKeys;
     controller: string;
     pointerDid: string;
 }
 /**
- * Parses and validates the optional `puk` member. An absent member resolves to
- * `undefined` (a record written for an account minted before the PUK); a
- * present-but-malformed one throws.
+ * Parses and validates the optional `userKey` member. An absent member resolves
+ * to `undefined` (a record written for an account minted before the user key);
+ * a present-but-malformed one throws.
  *
- * The signing seed is absent on a PUK adopted from a roster rotation (the
+ * The signing seed is absent on a user key adopted from a roster rotation (the
  * roster wraps the key-agreement secret alone); when present it must be
  * well-formed.
  *
- * @param value {unknown}   the record's `puk` member
- * @returns {Puk | undefined}
+ * @param value {unknown}   the record's `userKey` member
+ * @returns {UserKey | undefined}
  */
-export declare function parseClientRecordPuk(value: unknown): Puk | undefined;
+export declare function parseClientRecordUserKey(value: unknown): UserKey | undefined;
 /**
  * Parses and validates the optional `webvh` member: this client's did:webvh
  * update-key seeds. An absent member resolves to `undefined` (a record written
@@ -72,11 +72,13 @@ export declare function parseClientRecordPuk(value: unknown): Puk | undefined;
 export declare function parseClientRecordWebvhKeys(value: unknown): ClientWebvhUpdateKeys | undefined;
 /**
  * Encodes a client-key record's contents for storage: base64url byte fields,
- * optional members omitted rather than written as null.
+ * optional members omitted rather than written as null. Every secret is
+ * length-checked on the way out, exactly as the decoder checks it on the way
+ * back in -- an undecodable stored record is a lost account.
  *
  * @param options {object}
  * @param options.clientSeed {Uint8Array}   this client's 32-byte seed
- * @param [options.puk] {Puk}   the cached per-user key
+ * @param [options.userKey] {UserKey}   the cached user key
  * @param [options.webvhUpdateKeys] {ClientWebvhUpdateKeys}   this client's
  *   did:webvh update-key seeds
  * @param [options.controller] {string}   the account controller this key set
@@ -87,9 +89,9 @@ export declare function parseClientRecordWebvhKeys(value: unknown): ClientWebvhU
  *   to now
  * @returns {ClientKeyRecordJson}
  */
-export declare function encodeClientKeyRecord({ clientSeed, puk, webvhUpdateKeys, controller, pointerDid, createdAt }: {
+export declare function encodeClientKeyRecord({ clientSeed, userKey, webvhUpdateKeys, controller, pointerDid, createdAt }: {
     clientSeed: Uint8Array;
-    puk?: Puk;
+    userKey?: UserKey;
     webvhUpdateKeys?: ClientWebvhUpdateKeys;
     controller?: string;
     pointerDid?: string;

package/dist/keys/clientKeyRecord.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clientKeyRecord.d.ts","sourceRoot":"","sources":["../../src/keys/clientKeyRecord.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAOnC;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,UAAU,CAAA;IACtB,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,eAAe,CAAC,EAAE,qBAAqB,CAAA;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1D,KAAK,CAAC,EAAE;QACN,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAC3B,CAAA;IACD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,GAAG,EAAE,GAAG,CAAA;IACR,eAAe,EAAE,qBAAqB,CAAA;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,GAAG,SAAS,CA2BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,qBAAqB,GAAG,SAAS,CA8BnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,GAAG,EACH,eAAe,EACf,UAAU,EACV,UAAU,EACV,SAAoC,EACrC,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;IACtB,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,eAAe,CAAC,EAAE,qBAAqB,CAAA;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,mBAAmB,CAsCtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACT,EAAE;IACD,QAAQ,EAAE,OAAO,CAAA;CAClB,GAAG,eAAe,CAiClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,EAC5C,MAAM,EACP,EAAE;IACD,MAAM,EAAE,eAAe,CAAA;CACxB,GAAG,uBAAuB,CAe1B"}
+{"version":3,"file":"clientKeyRecord.d.ts","sourceRoot":"","sources":["../../src/keys/clientKeyRecord.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAO3C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,eAAe,CAAC,EAAE,qBAAqB,CAAA;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,KAAK,CAAC,EAAE;QACN,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAC3B,CAAA;IACD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,qBAAqB,CAAA;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CA8B5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,qBAAqB,GAAG,SAAS,CA8BnC;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,OAAO,EACP,eAAe,EACf,UAAU,EACV,UAAU,EACV,SAAoC,EACrC,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,eAAe,CAAC,EAAE,qBAAqB,CAAA;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,mBAAmB,CAgDtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACT,EAAE;IACD,QAAQ,EAAE,OAAO,CAAA;CAClB,GAAG,eAAe,CAiClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,EAC5C,MAAM,EACP,EAAE;IACD,MAAM,EAAE,eAAe,CAAA;CACxB,GAAG,uBAAuB,CAe1B"}

package/dist/keys/clientKeyRecord.js

@@ -5,7 +5,7 @@
  * The client-key record: the contents codec and validation for the local
  * record every wallet client keeps its own key material in -- the random
  * 32-byte client seed behind its Ed25519 signing key and X25519 twin, the
- * cached per-user key (PUK) delivered through the wrap-set roster, this
+ * cached user key delivered through the wrap-set roster, this
  * client's own did:webvh update-key seeds, the account controller the record
  * was bound for, and (when the app stores it beside the keys) the account's
  * did:webvh pointer.
@@ -17,11 +17,11 @@
  * wallet writes is a record the other accepts.
  *
  * Byte fields travel as base64url without padding; every one of them is a
- * 32-byte secret and is length-checked on the way back in. Validation is
- * strict on purpose: an absent optional member is a record written before that
- * member existed, but a present-and-malformed one throws, because both of the
- * members that can be malformed are load-bearing -- the account's encrypted
- * collections are keyed on the PUK, and the account's identity log can only be
+ * 32-byte secret and is length-checked on the way back in. Validation is strict
+ * on purpose: an absent optional member is a record written before that member
+ * existed, but a present-and-malformed one throws, because both of the members
+ * that can be malformed are load-bearing -- the account's encrypted collections
+ * are keyed on the user key, and the account's identity log can only be
  * extended with the update-key seeds, so proceeding without either would
  * silently orphan data or strand update authority.
  *
@@ -29,7 +29,8 @@
  * Neither is enforceable here (the writes are the app's), and both are
  * durability rules a crash must not be able to break:
  *
- * 1. **The PUK and the roster epoch pin persist atomically.** The pin is what
+ * 1. **The user key and the roster epoch pin persist atomically.** The pin is
+ *    what
  *    refuses a rolled-back roster, so it must never advance without the key
  *    that authenticated the roster it advanced to -- and the key must never be
  *    adopted without the pin moving with it. One write, or none.
@@ -79,29 +80,32 @@ function decodeSecret({ value, name }) {
     return bytes;
 }
 /**
- * Parses and validates the optional `puk` member. An absent member resolves to
- * `undefined` (a record written for an account minted before the PUK); a
- * present-but-malformed one throws.
+ * Parses and validates the optional `userKey` member. An absent member resolves
+ * to `undefined` (a record written for an account minted before the user key);
+ * a present-but-malformed one throws.
  *
- * The signing seed is absent on a PUK adopted from a roster rotation (the
+ * The signing seed is absent on a user key adopted from a roster rotation (the
  * roster wraps the key-agreement secret alone); when present it must be
  * well-formed.
  *
- * @param value {unknown}   the record's `puk` member
- * @returns {Puk | undefined}
+ * @param value {unknown}   the record's `userKey` member
+ * @returns {UserKey | undefined}
  */
-export function parseClientRecordPuk(value) {
+export function parseClientRecordUserKey(value) {
     if (value === undefined) {
         return undefined;
     }
     if (value === null || typeof value !== 'object') {
-        throw new Error('Client-key record has a malformed PUK.');
+        throw new Error('Client-key record has a malformed user key.');
     }
     const { id, secret, signingSeed } = value;
     if (typeof id !== 'string' || !id) {
-        throw new Error('Client-key record PUK is missing its key id.');
+        throw new Error('Client-key record user key is missing its key id.');
     }
-    const secretBytes = decodeSecret({ value: secret, name: 'PUK key material' });
+    const secretBytes = decodeSecret({
+        value: secret,
+        name: 'user key material'
+    });
     if (signingSeed === undefined) {
         return { id, secret: secretBytes };
     }
@@ -110,7 +114,7 @@ export function parseClientRecordPuk(value) {
         secret: secretBytes,
         signingSeed: decodeSecret({
             value: signingSeed,
-            name: 'PUK signing seed'
+            name: 'user key signing seed'
         })
     };
 }
@@ -150,13 +154,31 @@ export function parseClientRecordWebvhKeys(value) {
             : {})
     };
 }
+/**
+ * Encodes one byte field, checking its length -- the encode-side twin of
+ * {@link decodeSecret}, so a record this codec writes is always a record it
+ * can read back.
+ *
+ * @param options {object}
+ * @param options.value {Uint8Array}   the secret
+ * @param options.name {string}   the member's name, for the error message
+ * @returns {string}
+ */
+function encodeSecret({ value, name }) {
+    if (value.length !== SECRET_BYTES) {
+        throw new Error(`Client-key record ${name} is not ${SECRET_BYTES} bytes.`);
+    }
+    return base64urlnopad.encode(value);
+}
 /**
  * Encodes a client-key record's contents for storage: base64url byte fields,
- * optional members omitted rather than written as null.
+ * optional members omitted rather than written as null. Every secret is
+ * length-checked on the way out, exactly as the decoder checks it on the way
+ * back in -- an undecodable stored record is a lost account.
  *
  * @param options {object}
  * @param options.clientSeed {Uint8Array}   this client's 32-byte seed
- * @param [options.puk] {Puk}   the cached per-user key
+ * @param [options.userKey] {UserKey}   the cached user key
  * @param [options.webvhUpdateKeys] {ClientWebvhUpdateKeys}   this client's
  *   did:webvh update-key seeds
  * @param [options.controller] {string}   the account controller this key set
@@ -167,19 +189,24 @@ export function parseClientRecordWebvhKeys(value) {
  *   to now
  * @returns {ClientKeyRecordJson}
  */
-export function encodeClientKeyRecord({ clientSeed, puk, webvhUpdateKeys, controller, pointerDid, createdAt = new Date().toISOString() }) {
-    if (clientSeed.length !== SECRET_BYTES) {
-        throw new Error(`Client-key record client seed is not ${SECRET_BYTES} bytes.`);
-    }
+export function encodeClientKeyRecord({ clientSeed, userKey, webvhUpdateKeys, controller, pointerDid, createdAt = new Date().toISOString() }) {
     return {
-        clientSeed: base64urlnopad.encode(clientSeed),
-        ...(puk
+        clientSeed: encodeSecret({ value: clientSeed, name: 'client seed' }),
+        ...(userKey
             ? {
-                puk: {
-                    id: puk.id,
-                    secret: base64urlnopad.encode(puk.secret),
-                    ...(puk.signingSeed
-                        ? { signingSeed: base64urlnopad.encode(puk.signingSeed) }
+                userKey: {
+                    id: userKey.id,
+                    secret: encodeSecret({
+                        value: userKey.secret,
+                        name: 'user key material'
+                    }),
+                    ...(userKey.signingSeed
+                        ? {
+                            signingSeed: encodeSecret({
+                                value: userKey.signingSeed,
+                                name: 'user key signing seed'
+                            })
+                        }
                         : {})
                 }
             }
@@ -187,11 +214,20 @@ export function encodeClientKeyRecord({ clientSeed, puk, webvhUpdateKeys, contro
         ...(webvhUpdateKeys
             ? {
                 webvh: {
-                    updateSeed: base64urlnopad.encode(webvhUpdateKeys.updateSeed),
-                    stagedSeed: base64urlnopad.encode(webvhUpdateKeys.stagedSeed),
+                    updateSeed: encodeSecret({
+                        value: webvhUpdateKeys.updateSeed,
+                        name: 'did:webvh update seed'
+                    }),
+                    stagedSeed: encodeSecret({
+                        value: webvhUpdateKeys.stagedSeed,
+                        name: 'did:webvh staged seed'
+                    }),
                     ...(webvhUpdateKeys.pendingStagedSeed
                         ? {
-                            pendingStagedSeed: base64urlnopad.encode(webvhUpdateKeys.pendingStagedSeed)
+                            pendingStagedSeed: encodeSecret({
+                                value: webvhUpdateKeys.pendingStagedSeed,
+                                name: 'did:webvh pending staged seed'
+                            })
                         }
                         : {})
                 }
@@ -216,7 +252,7 @@ export function decodeClientKeyRecord({ contents }) {
     if (contents === null || typeof contents !== 'object') {
         throw new Error('Malformed client-key record.');
     }
-    const { clientSeed, puk, webvh, controller, pointerDid } = contents;
+    const { clientSeed, userKey, webvh, controller, pointerDid } = contents;
     const seed = decodeSecret({ value: clientSeed, name: 'client seed' });
     if (controller !== undefined &&
         (typeof controller !== 'string' || !controller)) {
@@ -226,11 +262,11 @@ export function decodeClientKeyRecord({ contents }) {
         (typeof pointerDid !== 'string' || !pointerDid)) {
         throw new Error('Client-key record has a malformed account pointer DID.');
     }
-    const parsedPuk = parseClientRecordPuk(puk);
+    const parsedUserKey = parseClientRecordUserKey(userKey);
     const webvhUpdateKeys = parseClientRecordWebvhKeys(webvh);
     return {
         clientSeed: seed,
-        ...(parsedPuk ? { puk: parsedPuk } : {}),
+        ...(parsedUserKey ? { userKey: parsedUserKey } : {}),
         ...(webvhUpdateKeys ? { webvhUpdateKeys } : {}),
         ...(controller ? { controller } : {}),
         ...(pointerDid ? { pointerDid } : {})
@@ -247,9 +283,9 @@ export function decodeClientKeyRecord({ contents }) {
  * @returns {EnrolledClientKeyRecord}
  */
 export function assertEnrolledClientKeyRecord({ record }) {
-    const { puk, webvhUpdateKeys, controller, pointerDid } = record;
-    if (!puk) {
-        throw new Error('Client-key record carries no per-user key.');
+    const { userKey, webvhUpdateKeys, controller, pointerDid } = record;
+    if (!userKey) {
+        throw new Error('Client-key record carries no user key.');
     }
     if (!webvhUpdateKeys) {
         throw new Error('Client-key record carries no did:webvh update keys.');
@@ -260,6 +296,6 @@ export function assertEnrolledClientKeyRecord({ record }) {
     if (!pointerDid) {
         throw new Error('Client-key record carries no account pointer DID.');
     }
-    return { ...record, puk, webvhUpdateKeys, controller, pointerDid };
+    return { ...record, userKey, webvhUpdateKeys, controller, pointerDid };
 }
 //# sourceMappingURL=clientKeyRecord.js.map