@interop/wallet-core 0.16.0 → 0.18.0

package/README.md

@@ -71,19 +71,19 @@ The subpaths:
   store they write through, 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: minting, the roster's init/read/rotate
-  primitives with their client-side guards (`epochsMac`, the latest-seen epoch
-  pin, the document-backed recipient resolver), the roster's compare-and-swap
-  descriptor store, and the PUK rotation cascade's per-collection op (re-epoch a
-  collection onto the roster's current PUK, staleness detected from durable
-  state alone, history escrowed -- also the completion sweep's building block),
-  plus the detector that converges a roster left wrapping the current key to a
-  recipient the account document no longer keys. Also the enrolled-client
-  display labels (`key-map/client-labels.json`) and their WAS-backed store. Also
-  the client-key record codec: the contents and strict validation of the local
-  record each wallet client keeps its own key material in (storage and wrapping
-  stay app-side).
+- **`@interop/wallet-core/keys`** -- the user key and its
+  `key-map/user-key.json` wrap-set roster: minting, the roster's
+  init/read/rotate primitives with their client-side guards (`epochsMac`, the
+  latest-seen epoch pin, the document-backed recipient resolver), the roster's
+  compare-and-swap descriptor store, and the user key rotation cascade's
+  per-collection op (re-epoch a collection onto the roster's current user key,
+  staleness detected from durable state alone, history escrowed -- also the
+  completion sweep's building block), plus the detector that converges a roster
+  left wrapping the current key to a recipient the account document no longer
+  keys. Also the enrolled-client display labels (`key-map/client-labels.json`)
+  and their WAS-backed store. Also the client-key record codec: the contents and
+  strict validation of the local record each wallet client keeps its own key
+  material in (storage and wrapping stay app-side).
 
 - **`@interop/wallet-core/clients`** -- the enrolled-client management surface:
   the listing over the locally verified did:webvh log with display labels

package/dist/clients/index.d.ts

@@ -17,7 +17,8 @@
  * - `revokeAccountClient` -- the revocation cascade in dependency order
  *   (document edit, roster rotation, collection fan-out, optional recovery
  *   re-mints), with the app-specific stages injected.
- * - `checkPukRosterAtLogin` / `convergePukRosterToAccount` -- the login-time
+ * - `checkUserKeyRosterAtLogin` / `convergeUserKeyRosterToAccount` -- the
+ *   login-time
  *   roster policy: which roster failures refuse a session, and the standing
  *   convergence of the roster onto the account document.
  */
@@ -27,6 +28,6 @@ export { cascadeCompletion, disconnectEligibility, revokedClientKeysFor } from '
 export type { DisconnectRefusal } from './policy.js';
 export { revokeAccountClient } from './revocation.js';
 export type { CascadeCollections, ClientRevocationResult } from './revocation.js';
-export { checkPukRosterAtLogin, convergePukRosterToAccount } from './rosterPolicy.js';
-export type { AdoptedPuk } from './rosterPolicy.js';
+export { checkUserKeyRosterAtLogin, convergeUserKeyRosterToAccount } from './rosterPolicy.js';
+export type { AdoptedUserKey } from './rosterPolicy.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/clients/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC5E,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC5E,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC/B,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/clients/index.js

@@ -17,12 +17,13 @@
  * - `revokeAccountClient` -- the revocation cascade in dependency order
  *   (document edit, roster rotation, collection fan-out, optional recovery
  *   re-mints), with the app-specific stages injected.
- * - `checkPukRosterAtLogin` / `convergePukRosterToAccount` -- the login-time
+ * - `checkUserKeyRosterAtLogin` / `convergeUserKeyRosterToAccount` -- the
+ *   login-time
  *   roster policy: which roster failures refuse a session, and the standing
  *   convergence of the roster onto the account document.
  */
 export { currentAccountSigningKeys, listAccountClients } from './listing.js';
 export { cascadeCompletion, disconnectEligibility, revokedClientKeysFor } from './policy.js';
 export { revokeAccountClient } from './revocation.js';
-export { checkPukRosterAtLogin, convergePukRosterToAccount } from './rosterPolicy.js';
+export { checkUserKeyRosterAtLogin, convergeUserKeyRosterToAccount } from './rosterPolicy.js';
 //# sourceMappingURL=index.js.map

package/dist/clients/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAO5E,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAMrD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAO5E,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAMrD,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC/B,MAAM,mBAAmB,CAAA"}

package/dist/clients/policy.d.ts

@@ -29,7 +29,7 @@
  * that as an error would contradict its own refreshed listing.
  */
 import type { RevokedClientKeys } from '../webvh/index.js';
-import type { PukCascadeResult } from '../keys/index.js';
+import type { UserKeyCascadeResult } from '../keys/index.js';
 import type { AccountClientView } from './listing.js';
 /**
  * Why a listed row cannot be disconnected. See the module doc.
@@ -70,10 +70,10 @@ export declare function revokedClientKeysFor({ client }: {
  * success, never an error (see the module doc).
  *
  * @param options {object}
- * @param options.collections {PukCascadeResult}   the collection fan-out result
+ * @param options.collections {UserKeyCascadeResult}   the collection fan-out result
  * @returns {'complete' | 'partial'}
  */
 export declare function cascadeCompletion({ collections }: {
-    collections: PukCascadeResult;
+    collections: UserKeyCascadeResult;
 }): 'complete' | 'partial';
 //# sourceMappingURL=policy.d.ts.map

package/dist/clients/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/clients/policy.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAC3B,MAAM,GAAG,aAAa,GAAG,yBAAyB,CAAA;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,OAAO,EACR,EAAE;IACD,MAAM,EAAE,iBAAiB,CAAA;IACzB,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACP,EAAE;IACD,MAAM,EAAE,iBAAiB,CAAA;CAC1B,GAAG,iBAAiB,CAYpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,WAAW,EACZ,EAAE;IACD,WAAW,EAAE,gBAAgB,CAAA;CAC9B,GAAG,UAAU,GAAG,SAAS,CAEzB"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/clients/policy.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAC3B,MAAM,GAAG,aAAa,GAAG,yBAAyB,CAAA;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,OAAO,EACR,EAAE;IACD,MAAM,EAAE,iBAAiB,CAAA;IACzB,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACP,EAAE;IACD,MAAM,EAAE,iBAAiB,CAAA;CAC1B,GAAG,iBAAiB,CAYpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,WAAW,EACZ,EAAE;IACD,WAAW,EAAE,oBAAoB,CAAA;CAClC,GAAG,UAAU,GAAG,SAAS,CAEzB"}

package/dist/clients/policy.js

@@ -46,7 +46,7 @@ export function revokedClientKeysFor({ client }) {
  * success, never an error (see the module doc).
  *
  * @param options {object}
- * @param options.collections {PukCascadeResult}   the collection fan-out result
+ * @param options.collections {UserKeyCascadeResult}   the collection fan-out result
  * @returns {'complete' | 'partial'}
  */
 export function cascadeCompletion({ collections }) {

package/dist/clients/revocation.d.ts

@@ -16,7 +16,7 @@
  *    leaves the document. There is no per-collection revoke anywhere in the
  *    cascade; apps a revoked client had connected reconnect through the
  *    ordinary connect flow.
- * 2. **The per-user key rotation** in the wrap-set roster, recipients resolved
+ * 2. **The user key rotation** in the wrap-set roster, recipients resolved
  *    from the document the edit itself just resolved to (no re-fetch of the
  *    log this call just extended). The roster delivers, never sources, so the
  *    revoked client's entry is dropped even before the retire filter. An
@@ -46,9 +46,9 @@
  */
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
 import type { CollectionEncryption } from '@interop/was-client';
-import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
+import type { EncryptionDescriptorStore, EpochsSigner } from '@interop/was-client/edv';
 import { type ClientWebvhUpdateKeys, type RevokedClientKeys, type WebvhIdStore } from '../webvh/index.js';
-import { type Puk, type PukCascadeResult } from '../keys/index.js';
+import { type UserKey, type UserKeyCascadeResult } from '../keys/index.js';
 /**
  * Where the cascade's collection fan-out gets its work: which encrypted
  * collections exist (only the app knows -- a mobile replica names the
@@ -69,9 +69,9 @@ export interface CascadeCollections {
  */
 export interface ClientRevocationResult {
     rotated: boolean;
-    collections: PukCascadeResult;
+    collections: UserKeyCascadeResult;
     document: object;
-    puk?: Puk;
+    userKey?: UserKey;
     rosterDescriptor?: CollectionEncryption;
     recovery?: {
         reminted: number;
@@ -109,36 +109,39 @@ export interface ClientRevocationResult {
  *   key; supplied, self-revocation is refused up front by the rule the surface
  *   should name, rather than by the update-key check inside the edit
  * @param options.rosterStore {EncryptionDescriptorStore}   the
- *   `key-map/puk.json` roster store
- * @param [options.puk] {Puk}   this client's cached per-user key
+ *   `key-map/user-key.json` roster store
+ * @param [options.userKey] {UserKey}   this client's cached user key
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key -- its roster entry
+ * @param options.signEpochs {EpochsSigner}   this client's epoch-configuration
+ *   signer (`userKeyRosterEpochsSigner`), vouching for the rotated roster epoch
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch
- * @param [options.onPukAdopted] {Function}   persists a rotated key: called
- *   with `{ puk, latestEpochId, descriptor }` after the roster read and BEFORE
+ * @param [options.onUserKeyAdopted] {Function}   persists a rotated key: called
+ *   with `{ userKey, latestEpochId, descriptor }` after the roster read and BEFORE
  *   the fan-out. The key and the epoch pin must persist atomically
  * @param options.collections {CascadeCollections}   the fan-out's work
  * @param [options.remintRecoveryDelegations] {Function}   `({ document }) =>
  *   Promise<{ reminted, skipped }>` -- the recovery-delegation re-mint stage,
  *   for a wallet that issues recovery codes
- * @param [options.onRotationAdopted] {Function}   `({ puk }) => Promise<void>`
+ * @param [options.onRotationAdopted] {Function}   `({ userKey }) => Promise<void>`
  *   -- the live-session adoption of a rotated key, run last so the session
  *   keeps operating without a re-login
  * @returns {Promise<ClientRevocationResult>}
  */
-export declare function revokeAccountClient({ idStore, updateKeys, revokedClient, knownLatentHashes, ownSigningKeyMultibase, rosterStore, puk, clientKeyAgreementKey, pinnedEpochId, onPukAdopted, collections, remintRecoveryDelegations, onRotationAdopted }: {
+export declare function revokeAccountClient({ idStore, updateKeys, revokedClient, knownLatentHashes, ownSigningKeyMultibase, rosterStore, userKey, clientKeyAgreementKey, signEpochs, pinnedEpochId, onUserKeyAdopted, collections, remintRecoveryDelegations, onRotationAdopted }: {
     idStore: WebvhIdStore;
     updateKeys: ClientWebvhUpdateKeys;
     revokedClient: RevokedClientKeys;
     knownLatentHashes?: string[];
     ownSigningKeyMultibase?: string;
     rosterStore: EncryptionDescriptorStore;
-    puk?: Puk;
+    userKey?: UserKey;
     clientKeyAgreementKey: IKeyAgreementKey;
+    signEpochs: EpochsSigner;
     pinnedEpochId?: string | null;
-    onPukAdopted?: (adopted: {
-        puk: Puk;
+    onUserKeyAdopted?: (adopted: {
+        userKey: UserKey;
         latestEpochId: string;
         descriptor: CollectionEncryption;
     }) => Promise<void>;
@@ -150,7 +153,7 @@ export declare function revokeAccountClient({ idStore, updateKeys, revokedClient
         skipped: number;
     }>;
     onRotationAdopted?: (rotation: {
-        puk: Puk;
+        userKey: UserKey;
     }) => Promise<void>;
 }): Promise<ClientRevocationResult>;
 //# sourceMappingURL=revocation.d.ts.map

package/dist/clients/revocation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"revocation.d.ts","sourceRoot":"","sources":["../../src/clients/revocation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAKL,KAAK,GAAG,EACR,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AAEzB;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACnD,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,yBAAyB,CAAA;IAC7D,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,gBAAgB,CAAA;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,gBAAgB,CAAC,EAAE,oBAAoB,CAAA;IACvC,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CACjD;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,OAAO,EACP,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,GAAG,EACH,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,yBAAyB,EACzB,iBAAiB,EAClB,EAAE;IACD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,aAAa,EAAE,iBAAiB,CAAA;IAChC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,yBAAyB,CAAA;IACtC,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,GAAG,EAAE,GAAG,CAAA;QACR,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,EAAE,oBAAoB,CAAA;KACjC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,WAAW,EAAE,kBAAkB,CAAA;IAC/B,yBAAyB,CAAC,EAAE,CAAC,OAAO,EAAE;QACpC,QAAQ,EAAE,MAAM,CAAA;KACjB,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAAE,GAAG,EAAE,GAAG,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9D,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuFlC"}
+{"version":3,"file":"revocation.d.ts","sourceRoot":"","sources":["../../src/clients/revocation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EACV,yBAAyB,EACzB,YAAY,EACb,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAA;AAEzB;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACnD,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,yBAAyB,CAAA;IAC7D,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,oBAAoB,CAAA;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gBAAgB,CAAC,EAAE,oBAAoB,CAAA;IACvC,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CACjD;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,OAAO,EACP,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,OAAO,EACP,qBAAqB,EACrB,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,yBAAyB,EACzB,iBAAiB,EAClB,EAAE;IACD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,aAAa,EAAE,iBAAiB,CAAA;IAChC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,yBAAyB,CAAA;IACtC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,UAAU,EAAE,YAAY,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC3B,OAAO,EAAE,OAAO,CAAA;QAChB,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,EAAE,oBAAoB,CAAA;KACjC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,WAAW,EAAE,kBAAkB,CAAA;IAC/B,yBAAyB,CAAC,EAAE,CAAC,OAAO,EAAE;QACpC,QAAQ,EAAE,MAAM,CAAA;KACjB,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuGlC"}

package/dist/clients/revocation.js

@@ -1,5 +1,5 @@
 import { revokeWebvhClient } from '../webvh/index.js';
-import { cascadeCollectionsToPuk, readPukRoster, rosterRecipientKid, rotatePukRoster } from '../keys/index.js';
+import { cascadeCollectionsToUserKey, readUserKeyRoster, rosterRecipientKid, rotateUserKeyRoster } from '../keys/index.js';
 /**
  * Resolves the collection ids the fan-out covers, whether they are a fixed set
  * or a listing the app performs.
@@ -45,25 +45,27 @@ async function collectionIdsOf({ collections }) {
  *   key; supplied, self-revocation is refused up front by the rule the surface
  *   should name, rather than by the update-key check inside the edit
  * @param options.rosterStore {EncryptionDescriptorStore}   the
- *   `key-map/puk.json` roster store
- * @param [options.puk] {Puk}   this client's cached per-user key
+ *   `key-map/user-key.json` roster store
+ * @param [options.userKey] {UserKey}   this client's cached user key
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key -- its roster entry
+ * @param options.signEpochs {EpochsSigner}   this client's epoch-configuration
+ *   signer (`userKeyRosterEpochsSigner`), vouching for the rotated roster epoch
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch
- * @param [options.onPukAdopted] {Function}   persists a rotated key: called
- *   with `{ puk, latestEpochId, descriptor }` after the roster read and BEFORE
+ * @param [options.onUserKeyAdopted] {Function}   persists a rotated key: called
+ *   with `{ userKey, latestEpochId, descriptor }` after the roster read and BEFORE
  *   the fan-out. The key and the epoch pin must persist atomically
  * @param options.collections {CascadeCollections}   the fan-out's work
  * @param [options.remintRecoveryDelegations] {Function}   `({ document }) =>
  *   Promise<{ reminted, skipped }>` -- the recovery-delegation re-mint stage,
  *   for a wallet that issues recovery codes
- * @param [options.onRotationAdopted] {Function}   `({ puk }) => Promise<void>`
+ * @param [options.onRotationAdopted] {Function}   `({ userKey }) => Promise<void>`
  *   -- the live-session adoption of a rotated key, run last so the session
  *   keeps operating without a re-login
  * @returns {Promise<ClientRevocationResult>}
  */
-export async function revokeAccountClient({ idStore, updateKeys, revokedClient, knownLatentHashes, ownSigningKeyMultibase, rosterStore, puk, clientKeyAgreementKey, pinnedEpochId, onPukAdopted, collections, remintRecoveryDelegations, onRotationAdopted }) {
+export async function revokeAccountClient({ idStore, updateKeys, revokedClient, knownLatentHashes, ownSigningKeyMultibase, rosterStore, userKey, clientKeyAgreementKey, signEpochs, pinnedEpochId, onUserKeyAdopted, collections, remintRecoveryDelegations, onRotationAdopted }) {
     if (ownSigningKeyMultibase &&
         ownSigningKeyMultibase === revokedClient.signingKeyMultibase) {
         throw new Error('This wallet cannot disconnect itself; use another enrolled wallet ' +
@@ -83,30 +85,44 @@ export async function revokeAccountClient({ idStore, updateKeys, revokedClient,
         ...(knownLatentHashes ? { knownLatentHashes } : {})
     });
     // 2. The roster rotation, recipients resolved from that same document.
-    await rotatePukRoster({
+    // Whether there IS a roster is settled BEFORE the rotation: an account with
+    // no `key-map/user-key.json` (its collections are not encrypted yet) has nothing
+    // to rotate, and the rotation itself refuses an absent descriptor rather
+    // than no-op'ing. The document edit has already landed, so the client IS
+    // disconnected -- a completed cascade with nothing rotated, not a failure.
+    const roster = await rosterStore.read();
+    if (roster === null) {
+        return {
+            rotated: false,
+            collections: { outcomes: {}, failed: [] },
+            document: doc
+        };
+    }
+    await rotateUserKeyRoster({
         store: rosterStore,
         document: doc,
-        retireRecipientId: rosterRecipientKid(revokedClient)
+        retireRecipientId: rosterRecipientKid(revokedClient),
+        signEpochs
     });
-    const read = await readPukRoster({
+    const read = await readUserKeyRoster({
         store: rosterStore,
-        ...(puk ? { puk } : {}),
+        ...(userKey ? { userKey } : {}),
         clientKeyAgreementKey,
-        pinnedEpochId
+        pinnedEpochId,
+        document: doc
     });
     if (!read) {
-        // No roster to rotate (an account whose collections are not encrypted
-        // yet). The document edit has already landed, so the client IS
-        // disconnected -- a completed cascade with nothing rotated, not a failure.
-        return {
-            rotated: false,
-            collections: { outcomes: {}, failed: [] },
-            document: doc
-        };
+        // The roster stood a moment ago and the rotation just wrote it, so its
+        // disappearance is a real fault, not the no-roster case above: the fresh
+        // key is only readable from the roster, and reporting success here would
+        // fan out under the retired one.
+        throw new Error('The wrap-set roster vanished between its rotation and the read that ' +
+            'adopts the fresh user key; the client is disconnected, but the ' +
+            'rotation must be completed by re-running the revocation.');
     }
     if (read.rotated) {
-        await onPukAdopted?.({
-            puk: read.puk,
+        await onUserKeyAdopted?.({
+            userKey: read.userKey,
             latestEpochId: read.latestEpochId,
             descriptor: read.descriptor
         });
@@ -114,7 +130,7 @@ export async function revokeAccountClient({ idStore, updateKeys, revokedClient,
     // 3. The collection fan-out, in parallel -- run even when this call found
     // the roster already rotated (a re-run after a crash), because the staleness
     // rule finds exactly the stranded collections.
-    const cascade = await cascadeCollectionsToPuk({
+    const cascade = await cascadeCollectionsToUserKey({
         collectionIds: await collectionIdsOf({ collections }),
         storeFor: collections.storeFor,
         ...(collections.isEncrypted
@@ -122,19 +138,19 @@ export async function revokeAccountClient({ idStore, updateKeys, revokedClient,
             : {}),
         rosterDescriptor: read.descriptor,
         clientKeyAgreementKey,
-        puk: read.puk
+        userKey: read.userKey
     });
     // 4. The recovery re-mints, while the registry is still readable under the
     // session's pre-adoption vault keys.
     const recovery = await remintRecoveryDelegations?.({ document: doc });
     if (read.rotated) {
-        await onRotationAdopted?.({ puk: read.puk });
+        await onRotationAdopted?.({ userKey: read.userKey });
     }
     return {
         rotated: read.rotated,
         collections: cascade,
         document: doc,
-        puk: read.puk,
+        userKey: read.userKey,
         rosterDescriptor: read.descriptor,
         ...(recovery ? { recovery } : {})
     };

package/dist/clients/revocation.js.map

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

package/dist/clients/rosterPolicy.d.ts

@@ -3,12 +3,13 @@
  */
 /**
  * The login-time wrap-set roster policy: what a wallet does with
- * `key-map/puk.json` when a session starts, and how it decides between
+ * `key-map/user-key.json` when a session starts, and how it decides between
  * refusing the session and carrying on offline.
  *
  * Two steps, in this order:
  *
- * - {@link checkPukRosterAtLogin} -- one direct read of the roster, before any
+ * - {@link checkUserKeyRosterAtLogin} -- one direct read of the roster, before
+ *   any
  *   storage client or cipher is built (a stale key would silently fail to
  *   decrypt everything written since another client rotated it). The served
  *   roster is authenticated and checked against the locally pinned latest-seen
@@ -22,7 +23,7 @@
  *   (an unreachable server, a transport hiccup) is warned about and resolves
  *   `null`, so an offline start keeps working from the cached key.
  *
- * - {@link convergePukRosterToAccount} -- the roster stage of the
+ * - {@link convergeUserKeyRosterToAccount} -- the roster stage of the
  *   cascade-completion sweep, which the collection fan-out then runs behind. A
  *   revocation torn between its document edit and its roster rotation leaves
  *   the roster wrapping the CURRENT key to a client the document no longer
@@ -45,25 +46,35 @@
  */
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
 import type { CollectionEncryption } from '@interop/was-client';
-import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
-import { type Puk, type PukRosterReadResult } from '../keys/index.js';
+import type { EncryptionDescriptorStore, EpochsSigner } from '@interop/was-client/edv';
+import { type UserKey, type UserKeyRosterReadResult } from '../keys/index.js';
 import type { AccountLogPointer } from './listing.js';
 /**
- * What an adopted per-user key carries: the key itself, the roster epoch to
+ * What an adopted user key carries: the key itself, the roster epoch to
  * pin as latest-seen, and the descriptor it was read from.
  */
-export interface AdoptedPuk {
-    puk: Puk;
+export interface AdoptedUserKey {
+    userKey: UserKey;
     latestEpochId: string;
     descriptor: CollectionEncryption;
 }
 /**
  * The login-time roster read. See the module doc for the failure semantics.
  *
+ * A read that adopts an epoch from the roster (a rotation by another client,
+ * or this client's first read) must trace it to the account document, so the
+ * account log is fetched and verified lazily on exactly that path (via
+ * `pointer`). A log that cannot be fetched then lands in the
+ * transport-failure class -- the session carries on under the cached key,
+ * WITHOUT adopting the unverifiable rotation -- while a roster whose epoch
+ * configuration no enrolled client signed is a refusal like the other three.
+ *
  * @param options {object}
  * @param options.store {EncryptionDescriptorStore}   the roster's descriptor
  *   store
- * @param [options.puk] {Puk}   this client's cached per-user key; omitted (a
+ * @param options.pointer {AccountLogPointer}   where the account log lives,
+ *   for the lazy document verification above
+ * @param [options.userKey] {UserKey}   this client's cached user key; omitted (a
  *   freshly enrolled client's first read) the key is always taken from the
  *   roster
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
@@ -71,54 +82,65 @@ export interface AdoptedPuk {
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch
  * @param [options.onRosterRead] {Function}   called with the
- *   {@link AdoptedPuk} of every successful read (whether or not it rotated),
+ *   {@link AdoptedUserKey} of every successful read (whether or not it rotated),
  *   so the epoch pin advances to the epoch just authenticated; the key and the
  *   pin must persist atomically
- * @returns {Promise<PukRosterReadResult | null>}   the read, or `null` when
+ * @returns {Promise<UserKeyRosterReadResult | null>}   the read, or `null` when
  *   the account has no roster yet or the server could not be reached
  */
-export declare function checkPukRosterAtLogin({ store, puk, clientKeyAgreementKey, pinnedEpochId, onRosterRead }: {
+export declare function checkUserKeyRosterAtLogin({ store, pointer, userKey, clientKeyAgreementKey, pinnedEpochId, onRosterRead }: {
     store: EncryptionDescriptorStore;
-    puk?: Puk;
+    pointer: AccountLogPointer;
+    userKey?: UserKey;
     clientKeyAgreementKey: IKeyAgreementKey;
     pinnedEpochId?: string | null;
-    onRosterRead?: (adopted: AdoptedPuk) => Promise<void>;
-}): Promise<PukRosterReadResult | null>;
+    onRosterRead?: (adopted: AdoptedUserKey) => Promise<void>;
+}): Promise<UserKeyRosterReadResult | null>;
 /**
  * Converges the roster onto the account's locally verified did:webvh document,
  * adopting a rotation the ordinary way (a roster re-read) and handing back the
  * key and descriptor the collection fan-out should run against.
  *
- * Best-effort throughout: any failure resolves to the unchanged input, since
- * the fan-out is still worth running on the key this start already has.
+ * Best-effort UP TO the rotation: a log that cannot be fetched or verified, or
+ * a roster that turns out to need nothing, resolves to the unchanged input,
+ * since the fan-out is still worth running on the key this start already has.
+ * Past the rotation it is not best-effort at all -- once the roster has moved
+ * to a fresh key, that key is readable only from the roster, so a failed
+ * adoption throws rather than reporting `rotated: false` with the retired key
+ * and descriptor (which would skip `onUserKeyAdopted` and fan the collections
+ * out onto the pre-rotation epoch). The three roster refusals rethrow
+ * throughout, exactly as {@link checkUserKeyRosterAtLogin} rethrows them.
  *
  * @param options {object}
  * @param options.pointer {AccountLogPointer}   where the account log lives
  * @param options.store {EncryptionDescriptorStore}   the roster's descriptor
  *   store
- * @param options.puk {Puk}   the start's current per-user key
+ * @param options.userKey {UserKey}   the start's current user key
  * @param options.descriptor {CollectionEncryption}   the start's roster read
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key
+ * @param options.signEpochs {EpochsSigner}   this client's epoch-configuration
+ *   signer (`userKeyRosterEpochsSigner`), for the rotation this call may perform
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch
- * @param [options.onPukAdopted] {Function}   called with the
- *   {@link AdoptedPuk} of a rotation, before the fan-out runs
+ * @param [options.onUserKeyAdopted] {Function}   called with the
+ *   {@link AdoptedUserKey} of a rotation, before the fan-out runs
  * @returns {Promise<object>}   whether the roster rotated on this call, the
  *   stale recipient kids found, and the key + descriptor to fan out with
  */
-export declare function convergePukRosterToAccount({ pointer, store, puk, descriptor, clientKeyAgreementKey, pinnedEpochId, onPukAdopted }: {
+export declare function convergeUserKeyRosterToAccount({ pointer, store, userKey, descriptor, clientKeyAgreementKey, signEpochs, pinnedEpochId, onUserKeyAdopted }: {
     pointer: AccountLogPointer;
     store: EncryptionDescriptorStore;
-    puk: Puk;
+    userKey: UserKey;
     descriptor: CollectionEncryption;
     clientKeyAgreementKey: IKeyAgreementKey;
+    signEpochs: EpochsSigner;
     pinnedEpochId?: string | null;
-    onPukAdopted?: (adopted: AdoptedPuk) => Promise<void>;
+    onUserKeyAdopted?: (adopted: AdoptedUserKey) => Promise<void>;
 }): Promise<{
     rotated: boolean;
     staleRecipientIds: string[];
-    puk: Puk;
+    userKey: UserKey;
     descriptor: CollectionEncryption;
 }>;
 //# sourceMappingURL=rosterPolicy.d.ts.map

package/dist/clients/rosterPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rosterPolicy.d.ts","sourceRoot":"","sources":["../../src/clients/rosterPolicy.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,EAML,KAAK,GAAG,EACR,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAErD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,GAAG,CAAA;IACR,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,oBAAoB,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,KAAK,EACL,GAAG,EACH,qBAAqB,EACrB,aAAa,EACb,YAAY,EACb,EAAE;IACD,KAAK,EAAE,yBAAyB,CAAA;IAChC,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAkCtC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,0BAA0B,CAAC,EAC/C,OAAO,EACP,KAAK,EACL,GAAG,EACH,UAAU,EACV,qBAAqB,EACrB,aAAa,EACb,YAAY,EACb,EAAE;IACD,OAAO,EAAE,iBAAiB,CAAA;IAC1B,KAAK,EAAE,yBAAyB,CAAA;IAChC,GAAG,EAAE,GAAG,CAAA;IACR,UAAU,EAAE,oBAAoB,CAAA;IAChC,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,GAAG,EAAE,GAAG,CAAA;IACR,UAAU,EAAE,oBAAoB,CAAA;CACjC,CAAC,CAmDD"}
+{"version":3,"file":"rosterPolicy.d.ts","sourceRoot":"","sources":["../../src/clients/rosterPolicy.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EACV,yBAAyB,EACzB,YAAY,EACb,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,uBAAuB,EAE7B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAErD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,oBAAoB,CAAA;CACjC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,yBAAyB,CAAC,EAC9C,KAAK,EACL,OAAO,EACP,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,YAAY,EACb,EAAE;IACD,KAAK,EAAE,yBAAyB,CAAA;IAChC,OAAO,EAAE,iBAAiB,CAAA;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA+B1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,8BAA8B,CAAC,EACnD,OAAO,EACP,KAAK,EACL,OAAO,EACP,UAAU,EACV,qBAAqB,EACrB,UAAU,EACV,aAAa,EACb,gBAAgB,EACjB,EAAE;IACD,OAAO,EAAE,iBAAiB,CAAA;IAC1B,KAAK,EAAE,yBAAyB,CAAA;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,oBAAoB,CAAA;IAChC,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,UAAU,EAAE,YAAY,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9D,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,oBAAoB,CAAA;CACjC,CAAC,CAiFD"}