@interop/wallet-core 0.17.1 → 0.18.0

package/dist/keys/{pukCascade.d.ts → userKeyCascade.d.ts}

@@ -2,92 +2,92 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The per-collection half of the PUK rotation cascade: once the roster's
- * current epoch has moved to a fresh PUK (a client revoked, a recovery code
- * spent or revoked), every encrypted collection must take a new epoch naming
- * the fresh PUK and retire the old one -- otherwise writes keep landing under
- * an epoch key the revoked party still holds.
+ * The per-collection half of the user key rotation cascade: once the roster's
+ * current epoch has moved to a fresh user key (a client revoked, a recovery
+ * code spent or revoked), every encrypted collection must take a new epoch
+ * naming the fresh user key and retire the old one -- otherwise writes keep
+ * landing under an epoch key the revoked party still holds.
  *
  * The staleness rule is the one the revocation spike verified: **a collection
- * is stale exactly when its current epoch names a PUK KAK other than the
+ * is stale exactly when its current epoch names a user key KAK other than the
  * roster's current** -- detectable from durable data alone, no checkpoint
- * resource anywhere, which is what makes a crashed cascade resumable by a
- * naive full re-run (and what the login-time completion sweep re-checks).
- * Which KAKs are "PUK generations" is read from the roster itself: its epochs
- * ARE the PUK generations, each escrow-wrapped to every enrolled client, so
- * any enrolled client can recover any generation's key
- * ({@link unwrapPukGenerations}) -- needed both to recognize a stale epoch
- * and to escrow the fresh PUK into a stranded collection's history.
+ * resource anywhere, which is what makes a crashed cascade resumable by a naive
+ * full re-run (and what the login-time completion sweep re-checks). Which KAKs
+ * are "user key generations" is read from the roster itself: its epochs ARE the
+ * user key generations, each escrow-wrapped to every enrolled client, so any
+ * enrolled client can recover any generation's key ({@link
+ * unwrapUserKeyGenerations}) -- needed both to recognize a stale epoch and to
+ * escrow the fresh user key into a stranded collection's history.
  *
  * One residue, accepted: a collection with NO epochs gets the newest prior
  * generation installed as its first epoch (pre-epoch envelopes are sealed to
- * the era's PUK KAK, and the PUK IS the epoch construction, so they ARE
- * epoch-of-that-generation envelopes) -- envelopes older than that
- * generation, on a collection every prior cascade missed, stay readable only
- * to sessions that held the older key.
+ * the era's user key KAK, and the user key IS the epoch construction, so they
+ * ARE epoch-of-that-generation envelopes) -- envelopes older than that
+ * generation, on a collection every prior cascade missed, stay readable only to
+ * sessions that held the older key.
  */
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
 import type { CollectionEncryption } from '@interop/was-client';
 import { type EncryptionDescriptorStore, type RecipientPublicKey } from '@interop/was-client/edv';
-import { type Puk } from './puk.js';
+import { type UserKey } from './userKey.js';
 /**
- * A PUK presented as an epoch-roster recipient: the kid is the
+ * A user key presented as an epoch-roster recipient: the kid is the
  * self-describing `<did:key>#<fingerprint>` form every collection epoch names
  * the user under, and the public key is the did:key's own multibase.
  *
  * @param options {object}
- * @param options.puk {Puk}
+ * @param options.userKey {UserKey}
  * @returns {RecipientPublicKey}
  */
-export declare function pukAsRecipient({ puk }: {
-    puk: Puk;
+export declare function userKeyAsRecipient({ userKey }: {
+    userKey: UserKey;
 }): RecipientPublicKey;
 /**
- * Recovers every PUK generation from the roster descriptor: each roster epoch
- * is one generation (its id the generation's did:key, its wrapped secret the
- * generation's raw key), escrow-wrapped to every enrolled client -- so this
- * client's key-agreement key unwraps them all, in roster (chronological)
- * order. A generation whose wrap is missing or fails to unwrap is skipped
- * rather than fatal (the cascade then simply cannot recognize or escrow that
- * generation; the current epoch always unwraps or the roster read itself
- * would have refused).
+ * Recovers every user key generation from the roster descriptor: each roster
+ * epoch is one generation (its id the generation's did:key, its wrapped secret
+ * the generation's raw key), escrow-wrapped to every enrolled client -- so this
+ * client's key-agreement key unwraps them all, in roster (chronological) order.
+ * A generation whose wrap is missing or fails to unwrap is skipped rather than
+ * fatal (the cascade then simply cannot recognize or escrow that generation;
+ * the current epoch always unwraps or the roster read itself would have
+ * refused).
  *
  * @param options {object}
  * @param options.descriptor {CollectionEncryption}   the roster descriptor
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key
- * @returns {Promise<Puk[]>}   the generations, oldest first
+ * @returns {Promise<UserKey[]>}   the generations, oldest first
  */
-export declare function unwrapPukGenerations({ descriptor, clientKeyAgreementKey }: {
+export declare function unwrapUserKeyGenerations({ descriptor, clientKeyAgreementKey }: {
     descriptor: CollectionEncryption;
     clientKeyAgreementKey: IKeyAgreementKey;
-}): Promise<Puk[]>;
+}): Promise<UserKey[]>;
 /**
- * What one collection's cascade step did: `noop` (already on the current
- * PUK), `installed` (a pre-epoch collection on a first-generation account
- * gained its first epoch; nothing to retire), `escrowed` (the current PUK's
- * wrap was completed into history with no stale epoch to rotate), or
- * `rotated` (a fresh epoch sealed to the current PUK, the stale generations
- * retired -- the pre-epoch install falls through to this).
+ * What one collection's cascade step did: `noop` (already on the current user
+ * key), `installed` (a pre-epoch collection on a first-generation account
+ * gained its first epoch; nothing to retire), `escrowed` (the current user
+ * key's wrap was completed into history with no stale epoch to rotate), or
+ * `rotated` (a fresh epoch sealed to the current user key, the stale
+ * generations retired -- the pre-epoch install falls through to this).
  */
-export type CollectionPukRotationOutcome = 'noop' | 'installed' | 'escrowed' | 'rotated';
+export type CollectionUserKeyRotationOutcome = 'noop' | 'installed' | 'escrowed' | 'rotated';
 /**
- * Brings ONE encrypted collection's epoch roster onto the current PUK -- the
- * per-collection op of the revocation cascade and of the completion sweep:
+ * Brings ONE encrypted collection's epoch roster onto the current user key --
+ * the per-collection op of the revocation cascade and of the completion sweep:
  *
  * - **No epochs yet**: install the newest PRIOR generation as the first epoch
- *   (see the module doc), wrapped to that generation and the current PUK,
+ *   (see the module doc), wrapped to that generation and the current user key,
  *   then fall through to the rotation. A first-generation account (nothing
- *   prior) installs the current PUK alone and is done.
+ *   prior) installs the current user key alone and is done.
  * - **Stale current epoch** (names a non-current generation): one
- *   `replaceRecipient` write -- the current PUK escrowed into every epoch,
+ *   `replaceRecipient` write -- the current user key escrowed into every epoch,
  *   a fresh epoch minted without the stale generations. Two requests per
  *   collection; app recipients and other readers ride through untouched (the
  *   default did:key resolver re-wraps them).
  * - **Current already** and fully escrowed: no write at all, so a naive
  *   re-run after a mid-cascade crash converges with zero redundant epochs.
  *
- * The pull axis is deliberately a no-op here: a PUK rotation follows a
+ * The pull axis is deliberately a no-op here: a user key rotation follows a
  * document edit (client revocation, code retirement) that already killed the
  * revoked party's server-side access everywhere under the current-key-set
  * rule -- there is no per-collection revoke.
@@ -95,35 +95,35 @@ export type CollectionPukRotationOutcome = 'noop' | 'installed' | 'escrowed' | '
  * @param options {object}
  * @param options.store {EncryptionDescriptorStore}   the collection's
  *   descriptor store
- * @param options.puk {Puk}   the roster's CURRENT PUK
- * @param options.generations {Puk[]}   every roster generation this client
- *   could unwrap ({@link unwrapPukGenerations}), oldest first
- * @returns {Promise<CollectionPukRotationOutcome>}
+ * @param options.userKey {UserKey}   the roster's CURRENT user key
+ * @param options.generations {UserKey[]}   every roster generation this client
+ *   could unwrap ({@link unwrapUserKeyGenerations}), oldest first
+ * @returns {Promise<CollectionUserKeyRotationOutcome>}
  */
-export declare function rotateCollectionEpochsToPuk({ store, puk, generations }: {
+export declare function rotateCollectionEpochsToUserKey({ store, userKey, generations }: {
     store: EncryptionDescriptorStore;
-    puk: Puk;
-    generations: Puk[];
-}): Promise<CollectionPukRotationOutcome>;
+    userKey: UserKey;
+    generations: UserKey[];
+}): Promise<CollectionUserKeyRotationOutcome>;
 /**
  * What the collection fan-out did, per collection id: the outcomes for every
  * collection that needed (or took) work, and the per-collection failures the
  * caller surfaces -- the cascade never aborts on one stuck collection.
  */
-export interface PukCascadeResult {
-    outcomes: Record<string, CollectionPukRotationOutcome>;
+export interface UserKeyCascadeResult {
+    outcomes: Record<string, CollectionUserKeyRotationOutcome>;
     failed: Array<{
         collectionId: string;
         error: unknown;
     }>;
 }
 /**
- * The collection fan-out of the PUK rotation cascade: re-epochs every named
- * collection onto the roster's current PUK, in parallel, unwrapping the PUK
- * generations from the roster once. The wallet supplies what only it knows --
- * which collections exist (`collectionIds`) and how to reach each one's
- * descriptor (`storeFor`); the per-collection staleness rule and re-epoch live
- * in {@link rotateCollectionEpochsToPuk}.
+ * The collection fan-out of the user key rotation cascade: re-epochs every
+ * named collection onto the roster's current user key, in parallel, unwrapping
+ * the user key generations from the roster once. The wallet supplies what only
+ * it knows -- which collections exist (`collectionIds`) and how to reach each
+ * one's descriptor (`storeFor`); the per-collection staleness rule and re-epoch
+ * live in {@link rotateCollectionEpochsToUserKey}.
  *
  * A collection that fails is reported in `failed` and the rest proceed; the
  * caller decides what a failure means (the login-time completion sweep is the
@@ -140,18 +140,18 @@ export interface PukCascadeResult {
  *   own task so a throwing check lands in that collection's `failed` entry
  *   (e.g. a standard collection an account never provisioned server-side)
  * @param options.rosterDescriptor {CollectionEncryption}   the freshly read
- *   `key-map/puk.json` roster (the source of the PUK generations)
+ *   `key-map/user-key.json` roster (the source of the user key generations)
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key, unwrapping the generations
- * @param options.puk {Puk}   the roster's current PUK
- * @returns {Promise<PukCascadeResult>}
+ * @param options.userKey {UserKey}   the roster's current user key
+ * @returns {Promise<UserKeyCascadeResult>}
  */
-export declare function cascadeCollectionsToPuk({ collectionIds, storeFor, isEncrypted, rosterDescriptor, clientKeyAgreementKey, puk }: {
+export declare function cascadeCollectionsToUserKey({ collectionIds, storeFor, isEncrypted, rosterDescriptor, clientKeyAgreementKey, userKey }: {
     collectionIds: string[];
     storeFor: (collectionId: string) => EncryptionDescriptorStore;
     isEncrypted?: (collectionId: string) => Promise<boolean>;
     rosterDescriptor: CollectionEncryption;
     clientKeyAgreementKey: IKeyAgreementKey;
-    puk: Puk;
-}): Promise<PukCascadeResult>;
-//# sourceMappingURL=pukCascade.d.ts.map
+    userKey: UserKey;
+}): Promise<UserKeyCascadeResult>;
+//# sourceMappingURL=userKeyCascade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"userKeyCascade.d.ts","sourceRoot":"","sources":["../../src/keys/userKeyCascade.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAML,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACR,EAAE;IACD,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,kBAAkB,CAKrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,UAAU,EACV,qBAAqB,EACtB,EAAE;IACD,UAAU,EAAE,oBAAoB,CAAA;IAChC,qBAAqB,EAAE,gBAAgB,CAAA;CACxC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAkBrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gCAAgC,GAC1C,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,+BAA+B,CAAC,EACpD,KAAK,EACL,OAAO,EACP,WAAW,EACZ,EAAE;IACD,KAAK,EAAE,yBAAyB,CAAA;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,OAAO,EAAE,CAAA;CACvB,GAAG,OAAO,CAAC,gCAAgC,CAAC,CA6H5C;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAAA;IAC1D,MAAM,EAAE,KAAK,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,2BAA2B,CAAC,EAChD,aAAa,EACb,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,OAAO,EACR,EAAE;IACD,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,yBAAyB,CAAA;IAC7D,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACxD,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwBhC"}

package/dist/keys/{pukCascade.js → userKeyCascade.js}

@@ -1,38 +1,38 @@
 import { addRecipient, epochKeyIdFor, initRecipients, replaceRecipient, unwrapEpochSecret } from '@interop/was-client/edv';
 import { ValidationError } from '@interop/was-client';
-import { pukVaultKeys } from './puk.js';
+import { userKeyVaultKeys } from './userKey.js';
 /**
- * A PUK presented as an epoch-roster recipient: the kid is the
+ * A user key presented as an epoch-roster recipient: the kid is the
  * self-describing `<did:key>#<fingerprint>` form every collection epoch names
  * the user under, and the public key is the did:key's own multibase.
  *
  * @param options {object}
- * @param options.puk {Puk}
+ * @param options.userKey {UserKey}
  * @returns {RecipientPublicKey}
  */
-export function pukAsRecipient({ puk }) {
+export function userKeyAsRecipient({ userKey }) {
     return {
-        id: epochKeyIdFor(puk.id),
-        publicKeyMultibase: puk.id.split(':')[2]
+        id: epochKeyIdFor(userKey.id),
+        publicKeyMultibase: userKey.id.split(':')[2]
     };
 }
 /**
- * Recovers every PUK generation from the roster descriptor: each roster epoch
- * is one generation (its id the generation's did:key, its wrapped secret the
- * generation's raw key), escrow-wrapped to every enrolled client -- so this
- * client's key-agreement key unwraps them all, in roster (chronological)
- * order. A generation whose wrap is missing or fails to unwrap is skipped
- * rather than fatal (the cascade then simply cannot recognize or escrow that
- * generation; the current epoch always unwraps or the roster read itself
- * would have refused).
+ * Recovers every user key generation from the roster descriptor: each roster
+ * epoch is one generation (its id the generation's did:key, its wrapped secret
+ * the generation's raw key), escrow-wrapped to every enrolled client -- so this
+ * client's key-agreement key unwraps them all, in roster (chronological) order.
+ * A generation whose wrap is missing or fails to unwrap is skipped rather than
+ * fatal (the cascade then simply cannot recognize or escrow that generation;
+ * the current epoch always unwraps or the roster read itself would have
+ * refused).
  *
  * @param options {object}
  * @param options.descriptor {CollectionEncryption}   the roster descriptor
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key
- * @returns {Promise<Puk[]>}   the generations, oldest first
+ * @returns {Promise<UserKey[]>}   the generations, oldest first
  */
-export async function unwrapPukGenerations({ descriptor, clientKeyAgreementKey }) {
+export async function unwrapUserKeyGenerations({ descriptor, clientKeyAgreementKey }) {
     const generations = [];
     for (const epoch of descriptor.epochs ?? []) {
         const entry = epoch.recipients.find(recipient => recipient.header.kid === clientKeyAgreementKey.id);
@@ -50,22 +50,22 @@ export async function unwrapPukGenerations({ descriptor, clientKeyAgreementKey }
     return generations;
 }
 /**
- * Brings ONE encrypted collection's epoch roster onto the current PUK -- the
- * per-collection op of the revocation cascade and of the completion sweep:
+ * Brings ONE encrypted collection's epoch roster onto the current user key --
+ * the per-collection op of the revocation cascade and of the completion sweep:
  *
  * - **No epochs yet**: install the newest PRIOR generation as the first epoch
- *   (see the module doc), wrapped to that generation and the current PUK,
+ *   (see the module doc), wrapped to that generation and the current user key,
  *   then fall through to the rotation. A first-generation account (nothing
- *   prior) installs the current PUK alone and is done.
+ *   prior) installs the current user key alone and is done.
  * - **Stale current epoch** (names a non-current generation): one
- *   `replaceRecipient` write -- the current PUK escrowed into every epoch,
+ *   `replaceRecipient` write -- the current user key escrowed into every epoch,
  *   a fresh epoch minted without the stale generations. Two requests per
  *   collection; app recipients and other readers ride through untouched (the
  *   default did:key resolver re-wraps them).
  * - **Current already** and fully escrowed: no write at all, so a naive
  *   re-run after a mid-cascade crash converges with zero redundant epochs.
  *
- * The pull axis is deliberately a no-op here: a PUK rotation follows a
+ * The pull axis is deliberately a no-op here: a user key rotation follows a
  * document edit (client revocation, code retirement) that already killed the
  * revoked party's server-side access everywhere under the current-key-set
  * rule -- there is no per-collection revoke.
@@ -73,32 +73,35 @@ export async function unwrapPukGenerations({ descriptor, clientKeyAgreementKey }
  * @param options {object}
  * @param options.store {EncryptionDescriptorStore}   the collection's
  *   descriptor store
- * @param options.puk {Puk}   the roster's CURRENT PUK
- * @param options.generations {Puk[]}   every roster generation this client
- *   could unwrap ({@link unwrapPukGenerations}), oldest first
- * @returns {Promise<CollectionPukRotationOutcome>}
+ * @param options.userKey {UserKey}   the roster's CURRENT user key
+ * @param options.generations {UserKey[]}   every roster generation this client
+ *   could unwrap ({@link unwrapUserKeyGenerations}), oldest first
+ * @returns {Promise<CollectionUserKeyRotationOutcome>}
  */
-export async function rotateCollectionEpochsToPuk({ store, puk, generations }) {
+export async function rotateCollectionEpochsToUserKey({ store, userKey, generations }) {
     const current = await store.read();
     if (current === null) {
         return 'noop';
     }
     let descriptor = current.descriptor;
-    const staleGenerations = generations.filter(generation => generation.id !== puk.id);
+    const staleGenerations = generations.filter(generation => generation.id !== userKey.id);
     if (!descriptor.epochs?.length || !descriptor.currentEpoch) {
-        // Pre-epoch: the collection's envelopes are sealed to the era's PUK KAK,
-        // which -- the PUK being the epoch construction -- makes them epoch-of-
+        // Pre-epoch: the collection's envelopes are sealed to the era's user key KAK,
+        // which -- the user key being the epoch construction -- makes them epoch-of-
         // that-generation envelopes. Install that generation as the first epoch.
         const previous = staleGenerations[staleGenerations.length - 1];
         try {
             const installed = await initRecipients({
                 store,
                 recipients: previous
-                    ? [pukAsRecipient({ puk: previous }), pukAsRecipient({ puk })]
-                    : [pukAsRecipient({ puk })],
+                    ? [
+                        userKeyAsRecipient({ userKey: previous }),
+                        userKeyAsRecipient({ userKey })
+                    ]
+                    : [userKeyAsRecipient({ userKey })],
                 epoch: previous
                     ? { epochId: previous.id, secret: previous.secret }
-                    : { epochId: puk.id, secret: puk.secret }
+                    : { epochId: userKey.id, secret: userKey.secret }
             });
             if (!previous) {
                 // A first-generation account: nothing prior to escrow, nothing to
@@ -126,65 +129,65 @@ export async function rotateCollectionEpochsToPuk({ store, puk, generations }) {
     const staleKids = staleGenerations
         .map(generation => epochKeyIdFor(generation.id))
         .filter(kid => currentKids.has(kid));
-    const pukKid = epochKeyIdFor(puk.id);
+    const userKeyKid = epochKeyIdFor(userKey.id);
     if (staleKids.length === 0) {
-        const escrowComplete = (descriptor.epochs ?? []).every(epoch => epoch.recipients.some(entry => entry.header.kid === pukKid));
-        if (currentKids.has(pukKid) && escrowComplete) {
+        const escrowComplete = (descriptor.epochs ?? []).every(epoch => epoch.recipients.some(entry => entry.header.kid === userKeyKid));
+        if (currentKids.has(userKeyKid) && escrowComplete) {
             return 'noop';
         }
     }
     if (staleKids.length > 0) {
         // The escrow owner: the newest stale generation still named by the
         // current epoch, which the cascade invariant escrowed into every prior
-        // epoch -- so it unwraps the whole history for the fresh PUK's escrow.
+        // epoch -- so it unwraps the whole history for the fresh user key's escrow.
         const ownerGeneration = [...staleGenerations]
             .reverse()
             .find(generation => currentKids.has(epochKeyIdFor(generation.id)));
-        const owner = pukVaultKeys({ puk: ownerGeneration });
+        const owner = userKeyVaultKeys({ userKey: ownerGeneration });
         await replaceRecipient({
             store,
             retire: staleKids,
-            recipient: pukAsRecipient({ puk }),
+            recipient: userKeyAsRecipient({ userKey }),
             owner: { keyAgreementKey: owner.keyAgreementKey },
             pull: async () => { }
         });
         return 'rotated';
     }
-    if (!currentKids.has(pukKid)) {
-        // No stale generation to retire, but the current PUK is not a recipient
-        // at all: this collection's roster is not PUK-owned in a shape this
+    if (!currentKids.has(userKeyKid)) {
+        // No stale generation to retire, but the current user key is not a recipient
+        // at all: this collection's roster is not user-key-owned in a shape this
         // cascade can heal -- surface it rather than silently minting an epoch
         // whose history the account cannot read.
-        throw new Error('The collection current epoch names no PUK generation this client ' +
-            'can recognize; its roster cannot be rotated to the current PUK.');
+        throw new Error('The collection current epoch names no user key generation this client ' +
+            'can recognize; its roster cannot be rotated to the current user key.');
     }
-    // Escrow completion only: the current epoch is already on the current PUK,
+    // Escrow completion only: the current epoch is already on the current user key,
     // but some historical epoch is missing its wrap. The owner must unwrap
     // exactly those epochs -- the newest generation named by every incomplete
     // epoch.
-    const incomplete = (descriptor.epochs ?? []).filter(epoch => !epoch.recipients.some(entry => entry.header.kid === pukKid));
+    const incomplete = (descriptor.epochs ?? []).filter(epoch => !epoch.recipients.some(entry => entry.header.kid === userKeyKid));
     const escrowOwner = [...generations]
         .reverse()
         .find(generation => incomplete.every(epoch => epoch.recipients.some(entry => entry.header.kid === epochKeyIdFor(generation.id))));
     if (!escrowOwner) {
-        throw new Error("The current PUK cannot be escrowed into this collection's history: " +
-            'no held PUK generation is a recipient of every incomplete epoch.');
+        throw new Error("The current user key cannot be escrowed into this collection's history: " +
+            'no held user key generation is a recipient of every incomplete epoch.');
     }
-    const owner = pukVaultKeys({ puk: escrowOwner });
+    const owner = userKeyVaultKeys({ userKey: escrowOwner });
     await addRecipient({
         store,
-        recipient: pukAsRecipient({ puk }),
+        recipient: userKeyAsRecipient({ userKey }),
         owner: { keyAgreementKey: owner.keyAgreementKey }
     });
     return 'escrowed';
 }
 /**
- * The collection fan-out of the PUK rotation cascade: re-epochs every named
- * collection onto the roster's current PUK, in parallel, unwrapping the PUK
- * generations from the roster once. The wallet supplies what only it knows --
- * which collections exist (`collectionIds`) and how to reach each one's
- * descriptor (`storeFor`); the per-collection staleness rule and re-epoch live
- * in {@link rotateCollectionEpochsToPuk}.
+ * The collection fan-out of the user key rotation cascade: re-epochs every
+ * named collection onto the roster's current user key, in parallel, unwrapping
+ * the user key generations from the roster once. The wallet supplies what only
+ * it knows -- which collections exist (`collectionIds`) and how to reach each
+ * one's descriptor (`storeFor`); the per-collection staleness rule and re-epoch
+ * live in {@link rotateCollectionEpochsToUserKey}.
  *
  * A collection that fails is reported in `failed` and the rest proceed; the
  * caller decides what a failure means (the login-time completion sweep is the
@@ -201,14 +204,14 @@ export async function rotateCollectionEpochsToPuk({ store, puk, generations }) {
  *   own task so a throwing check lands in that collection's `failed` entry
  *   (e.g. a standard collection an account never provisioned server-side)
  * @param options.rosterDescriptor {CollectionEncryption}   the freshly read
- *   `key-map/puk.json` roster (the source of the PUK generations)
+ *   `key-map/user-key.json` roster (the source of the user key generations)
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key, unwrapping the generations
- * @param options.puk {Puk}   the roster's current PUK
- * @returns {Promise<PukCascadeResult>}
+ * @param options.userKey {UserKey}   the roster's current user key
+ * @returns {Promise<UserKeyCascadeResult>}
  */
-export async function cascadeCollectionsToPuk({ collectionIds, storeFor, isEncrypted, rosterDescriptor, clientKeyAgreementKey, puk }) {
-    const generations = await unwrapPukGenerations({
+export async function cascadeCollectionsToUserKey({ collectionIds, storeFor, isEncrypted, rosterDescriptor, clientKeyAgreementKey, userKey }) {
+    const generations = await unwrapUserKeyGenerations({
         descriptor: rosterDescriptor,
         clientKeyAgreementKey
     });
@@ -219,9 +222,9 @@ export async function cascadeCollectionsToPuk({ collectionIds, storeFor, isEncry
             if (isEncrypted && !(await isEncrypted(collectionId))) {
                 return;
             }
-            outcomes[collectionId] = await rotateCollectionEpochsToPuk({
+            outcomes[collectionId] = await rotateCollectionEpochsToUserKey({
                 store: storeFor(collectionId),
-                puk,
+                userKey,
                 generations
             });
         }
@@ -231,4 +234,4 @@ export async function cascadeCollectionsToPuk({ collectionIds, storeFor, isEncry
     }));
     return { outcomes, failed };
 }
-//# sourceMappingURL=pukCascade.js.map
+//# sourceMappingURL=userKeyCascade.js.map

package/dist/keys/userKeyCascade.js.map

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