@interop/wallet-core 0.23.1 → 0.24.0

package/dist/keys/index.js

@@ -13,13 +13,15 @@
  *   strict validation of the local client-key record each client keeps its own
  *   key material in (storage and wrapping stay app-side).
  * - `ensureUserKeyRoster` / `addUserKeyRosterRecipient` / `readUserKeyRoster` /
- *   `userKeyRosterRecipientResolver` -- the `key-map/user-key.json` roster over the
- *   was-client descriptor-store seam, with the three client-side guards a
- *   resource-hosted descriptor needs (`epochsMac`, the latest-seen epoch pin,
- *   and a recipient resolver backed by the locally verified did:webvh
- *   document).
- * - `userKeyRosterDescriptorStore` -- that descriptor store, built from a bare
- *   signing client for the login-time direct read.
+ *   `userKeyRosterRecipientResolver` -- the user key roster over the
+ *   was-client descriptor-store seam, with the client-side guards a
+ *   resource-hosted descriptor needs (the governing resource log, the
+ *   latest-seen epoch pin, and a recipient resolver backed by the locally
+ *   verified did:webvh document).
+ * - `userKeyRosterDescriptorStore` / `logGovernedDescriptorStore` -- that
+ *   descriptor store: reads resolve to the roster log's verified head
+ *   (`key-map/user-key.jsonl`), writes append signed entries; built from a
+ *   bare signing client for the login-time direct read.
  * - `rosterRecipientKid` -- the one builder of a client's roster kid, shared by
  *   the enrollment wrap, the roster read, and the rotation that retires it.
  * - `convergeUserKeyRosterToDocument` -- the standing detector for a revocation
@@ -42,9 +44,10 @@
  */
 export { mintUserKey, userKeyVaultKeys } from './userKey.js';
 export { assertEnrolledClientKeyRecord, decodeClientKeyRecord, encodeClientKeyRecord, parseClientRecordUserKey, parseClientRecordWebvhKeys } from './clientKeyRecord.js';
-export { addUserKeyRosterRecipient, convergeUserKeyRosterToDocument, ensureUserKeyRoster, UserKeyRosterContinuityError, UserKeyRosterIntegrityError, UserKeyRosterUnwrapError, userKeyRosterEpochsSigner, userKeyRosterRecipientResolver, readUserKeyRoster, rosterRecipientKid, rotateUserKeyRoster, verifyUserKeyRosterEpochsSig } from './userKeyRoster.js';
+export { addUserKeyRosterRecipient, convergeUserKeyRosterToDocument, ensureUserKeyRoster, UserKeyRosterContinuityError, UserKeyRosterIntegrityError, UserKeyRosterUnwrapError, userKeyRosterLogSigner, userKeyRosterRecipientResolver, readUserKeyRoster, rosterRecipientKid, rotateUserKeyRoster } from './userKeyRoster.js';
 export { cascadeCollectionsToUserKey, userKeyAsRecipient, rotateCollectionEpochsToUserKey, unwrapUserKeyGenerations } from './userKeyCascade.js';
 export { userKeyRosterDescriptorStore } from './rosterStore.js';
+export { EPOCH_CONFIGURATION_STATE_TYPE, logGovernedDescriptorStore } from './rosterLogStore.js';
 export { ensureWalletSpaceEpochs } from './spaceEpochs.js';
 export { readClientLabels, removeClientLabel, setClientLabel } from './clientLabels.js';
 export { wasClientLabelsStore } from './wasLabelsStore.js';

package/dist/keys/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG5D,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,sBAAsB,CAAA;AAO7B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAU5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAE/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAG1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG5D,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,sBAAsB,CAAA;AAO7B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,EACtB,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAU5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC3B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAG1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/keys/rosterLogStore.d.ts

@@ -0,0 +1,34 @@
+import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
+import { type ResourceLogStore } from '@interop/was-client/log';
+import { type ResourceLogController, type ResourceLogPinStore, type ResourceLogSigner } from '../resourceLog/index.js';
+/**
+ * The state-document schema identifier an encryption descriptor carries in a
+ * governed log entry, per WAS-EC.
+ */
+export declare const EPOCH_CONFIGURATION_STATE_TYPE = "WasEpochConfiguration";
+/**
+ * Builds the log-governed `EncryptionDescriptorStore`.
+ *
+ * The controller view is resolved per operation (never held), so a caller
+ * that just edited the account document -- a revocation about to rotate the
+ * roster -- writes entries anchored at the post-edit head it now verifies,
+ * which is exactly what makes its rotation the sealing append.
+ *
+ * @param options {object}
+ * @param options.log {ResourceLogStore}   the log's transport seam
+ * @param options.resolveController {function}   `() => Promise<ResourceLogController>`
+ *   -- the caller's currently verified controller view
+ *   (`webvhResourceLogController` over a `verifyAccountLog` result)
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head pin
+ *   for this log
+ * @param options.signer {ResourceLogSigner}   this client's enrolled signing
+ *   key, for the appends this store writes
+ * @returns {EncryptionDescriptorStore}
+ */
+export declare function logGovernedDescriptorStore({ log, resolveController, pinStore, signer }: {
+    log: ResourceLogStore;
+    resolveController: () => Promise<ResourceLogController>;
+    pinStore: ResourceLogPinStore;
+    signer: ResourceLogSigner;
+}): EncryptionDescriptorStore;
+//# sourceMappingURL=rosterLogStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rosterLogStore.d.ts","sourceRoot":"","sources":["../../src/keys/rosterLogStore.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAOL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EAEvB,MAAM,yBAAyB,CAAA;AAEhC;;;GAGG;AACH,eAAO,MAAM,8BAA8B,0BAA0B,CAAA;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,GAAG,EACH,iBAAiB,EACjB,QAAQ,EACR,MAAM,EACP,EAAE;IACD,GAAG,EAAE,gBAAgB,CAAA;IACrB,iBAAiB,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACvD,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,MAAM,EAAE,iBAAiB,CAAA;CAC1B,GAAG,yBAAyB,CAqG5B"}

package/dist/keys/rosterLogStore.js

@@ -0,0 +1,110 @@
+import { confirmAppend, WAS_RESOURCE_LOG_METHOD } from '@interop/was-client/log';
+import { buildResourceLogEntry, buildResourceLogGenesis, readResourceLog, ResourceLogClosedError, ResourceLogIntegrityError, verifyResourceLog } from '../resourceLog/index.js';
+/**
+ * The state-document schema identifier an encryption descriptor carries in a
+ * governed log entry, per WAS-EC.
+ */
+export const EPOCH_CONFIGURATION_STATE_TYPE = 'WasEpochConfiguration';
+/**
+ * Builds the log-governed `EncryptionDescriptorStore`.
+ *
+ * The controller view is resolved per operation (never held), so a caller
+ * that just edited the account document -- a revocation about to rotate the
+ * roster -- writes entries anchored at the post-edit head it now verifies,
+ * which is exactly what makes its rotation the sealing append.
+ *
+ * @param options {object}
+ * @param options.log {ResourceLogStore}   the log's transport seam
+ * @param options.resolveController {function}   `() => Promise<ResourceLogController>`
+ *   -- the caller's currently verified controller view
+ *   (`webvhResourceLogController` over a `verifyAccountLog` result)
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head pin
+ *   for this log
+ * @param options.signer {ResourceLogSigner}   this client's enrolled signing
+ *   key, for the appends this store writes
+ * @returns {EncryptionDescriptorStore}
+ */
+export function logGovernedDescriptorStore({ log, resolveController, pinStore, signer }) {
+    // The verified log observed by the most recent read on this store instance;
+    // a replace builds its entry on that head, pinned to the same read's etag,
+    // so a stale head loses the CAS instead of forking.
+    let lastVerified = null;
+    function toState(descriptor) {
+        const { history: _history, ...rest } = descriptor;
+        return { ...rest, type: EPOCH_CONFIGURATION_STATE_TYPE };
+    }
+    async function settle({ entry, controller }) {
+        const readBack = await confirmAppend({ store: log, entry });
+        const confirmed = await verifyResourceLog({
+            entries: readBack.entries,
+            controller,
+            expectedMethod: WAS_RESOURCE_LOG_METHOD,
+            pin: await pinStore.read()
+        });
+        await pinStore.write(confirmed.pin);
+        lastVerified = confirmed;
+    }
+    return {
+        async read() {
+            const controller = await resolveController();
+            const current = await readResourceLog({
+                store: log,
+                controller,
+                expectedMethod: WAS_RESOURCE_LOG_METHOD,
+                pinStore
+            });
+            if (current === null) {
+                lastVerified = null;
+                return null;
+            }
+            const state = current.verified.state;
+            if (state.type !== EPOCH_CONFIGURATION_STATE_TYPE) {
+                throw new ResourceLogIntegrityError(`The governed descriptor log carries state of type ` +
+                    `"${state.type}", not "${EPOCH_CONFIGURATION_STATE_TYPE}".`);
+            }
+            lastVerified = current.verified;
+            return {
+                descriptor: state,
+                etag: current.etag
+            };
+        },
+        async replace(descriptor, { ifMatch }) {
+            if (lastVerified === null) {
+                throw new Error('Cannot replace the governed descriptor: replace must follow a ' +
+                    'read on the same store instance.');
+            }
+            if (ifMatch === undefined) {
+                throw new Error('Cannot replace the governed descriptor: the backend returned no ' +
+                    'validator, and the profile forbids an unconditional write.');
+            }
+            if (lastVerified.terminal) {
+                throw new ResourceLogClosedError({ nextLog: lastVerified.terminal });
+            }
+            const controller = await resolveController();
+            const entry = await buildResourceLogEntry({
+                head: lastVerified.head,
+                state: toState(descriptor),
+                controller,
+                signer
+            });
+            // A stale validator throws PreconditionFailedError here, which the edv
+            // machinery's CAS loop re-reads and rebases on.
+            await log.append(entry, { ifMatch });
+            await settle({ entry, controller });
+        },
+        async create(descriptor) {
+            const controller = await resolveController();
+            const genesis = await buildResourceLogGenesis({
+                state: toState(descriptor),
+                method: WAS_RESOURCE_LOG_METHOD,
+                controller,
+                signer
+            });
+            // A lost guarded-create race throws PreconditionFailedError, and the
+            // edv machinery re-reads and adopts the winner's descriptor.
+            await log.create(genesis);
+            await settle({ entry: genesis, controller });
+        }
+    };
+}
+//# sourceMappingURL=rosterLogStore.js.map

package/dist/keys/rosterLogStore.js.map

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

package/dist/keys/rosterStore.d.ts

@@ -1,18 +1,32 @@
 import type { ZcapClient } from '@interop/ezcap';
-import { type EncryptionDescriptorStore } from '@interop/was-client/edv';
+import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
+import type { ResourceLogController, ResourceLogPinStore, ResourceLogSigner } from '../resourceLog/index.js';
 /**
- * Builds the compare-and-swap descriptor store over `key-map/user-key.json` in
- * a data Space.
+ * Builds the log-governed descriptor store over the user key roster in a
+ * data Space: reads resolve to the verified head of
+ * `key-map/user-key.jsonl`, writes append to it.
  *
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}   the session's root signing client
  * @param options.spaceId {string}   the data Space id
+ * @param options.resolveController {function}
+ *   `() => Promise<ResourceLogController>` -- the caller's currently verified
+ *   controller view (`webvhResourceLogController` over a `verifyAccountLog`
+ *   result), resolved per operation so post-edit writers anchor at the head
+ *   they just verified
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pin for the roster log
+ * @param options.signer {ResourceLogSigner}   this client's enrolled signing
+ *   key ({@link userKeyRosterLogSigner})
  * @returns {EncryptionDescriptorStore}
  */
-export declare function userKeyRosterDescriptorStore({ storageServerUrl, zcapClient, spaceId }: {
+export declare function userKeyRosterDescriptorStore({ storageServerUrl, zcapClient, spaceId, resolveController, pinStore, signer }: {
     storageServerUrl: string;
     zcapClient: ZcapClient;
     spaceId: string;
+    resolveController: () => Promise<ResourceLogController>;
+    pinStore: ResourceLogPinStore;
+    signer: ResourceLogSigner;
 }): EncryptionDescriptorStore;
 //# sourceMappingURL=rosterStore.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rosterStore.d.ts","sourceRoot":"","sources":["../../src/keys/rosterStore.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,yBAAyB,CAAA;AAMhC;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,gBAAgB,EAChB,UAAU,EACV,OAAO,EACR,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,yBAAyB,CAQ5B"}
+{"version":3,"file":"rosterStore.d.ts","sourceRoot":"","sources":["../../src/keys/rosterStore.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAExE,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,yBAAyB,CAAA;AAOhC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,MAAM,EACP,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,iBAAiB,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACvD,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,MAAM,EAAE,iBAAiB,CAAA;CAC1B,GAAG,yBAAyB,CAa5B"}

package/dist/keys/rosterStore.js

@@ -2,37 +2,56 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The descriptor store over a Space's user key wrap-set roster
- * (`key-map/user-key.json`). Standalone rather than a method on a wallet's
- * remote-store class, because the login-time direct read checks the roster
- * BEFORE any storage client (or cipher) is built: it takes the bare signing
- * client instead of a store instance.
+ * The descriptor store over a Space's user key wrap-set roster -- since the
+ * roster became log-governed, over its resource log (`key-map/user-key.jsonl`).
+ * Standalone rather than a method on a wallet's remote-store class, because the
+ * login-time direct read checks the roster BEFORE any storage client (or
+ * cipher) is built: it takes the bare signing client instead of a store
+ * instance.
  *
- * The `plaintext` collection override is load-bearing. Without it the client
- * decides plaintext vs encrypted by describing the collection first, and a 404
- * from an absent Space or collection then surfaces as an encryption error
- * rather than as an absent roster.
+ * The `plaintext` collection override is load-bearing twice over. Without it
+ * the client decides plaintext vs encrypted by describing the collection
+ * first, and a 404 from an absent Space or collection then surfaces as an
+ * encryption error rather than as an absent roster; and on an encrypted
+ * collection the EDV codec would compute the write preconditions itself, so
+ * the log's compare-and-swap append guard would not be honored.
  */
 import { WasClient } from '@interop/was-client';
-import { resourceDescriptorStore } from '@interop/was-client/edv';
-import { KEY_MAP_COLLECTION, USER_KEY_ROSTER_RESOURCE } from '../space/collections.js';
+import { resourceLogStore } from '@interop/was-client/log';
+import { KEY_MAP_COLLECTION, USER_KEY_ROSTER_LOG_RESOURCE } from '../space/collections.js';
+import { logGovernedDescriptorStore } from './rosterLogStore.js';
 /**
- * Builds the compare-and-swap descriptor store over `key-map/user-key.json` in
- * a data Space.
+ * Builds the log-governed descriptor store over the user key roster in a
+ * data Space: reads resolve to the verified head of
+ * `key-map/user-key.jsonl`, writes append to it.
  *
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}   the session's root signing client
  * @param options.spaceId {string}   the data Space id
+ * @param options.resolveController {function}
+ *   `() => Promise<ResourceLogController>` -- the caller's currently verified
+ *   controller view (`webvhResourceLogController` over a `verifyAccountLog`
+ *   result), resolved per operation so post-edit writers anchor at the head
+ *   they just verified
+ * @param options.pinStore {ResourceLogPinStore}   this client's chain-head
+ *   pin for the roster log
+ * @param options.signer {ResourceLogSigner}   this client's enrolled signing
+ *   key ({@link userKeyRosterLogSigner})
  * @returns {EncryptionDescriptorStore}
  */
-export function userKeyRosterDescriptorStore({ storageServerUrl, zcapClient, spaceId }) {
+export function userKeyRosterDescriptorStore({ storageServerUrl, zcapClient, spaceId, resolveController, pinStore, signer }) {
     const was = new WasClient({ serverUrl: storageServerUrl, zcapClient });
     const collection = was
         .space(spaceId)
         .collection(KEY_MAP_COLLECTION.id, { encryption: 'plaintext' });
-    return resourceDescriptorStore({
-        resource: collection.resource(USER_KEY_ROSTER_RESOURCE)
+    return logGovernedDescriptorStore({
+        log: resourceLogStore({
+            resource: collection.resource(USER_KEY_ROSTER_LOG_RESOURCE)
+        }),
+        resolveController,
+        pinStore,
+        signer
     });
 }
 //# sourceMappingURL=rosterStore.js.map

package/dist/keys/rosterStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"rosterStore.js","sourceRoot":"","sources":["../../src/keys/rosterStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE/C,OAAO,EACL,uBAAuB,EAExB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,yBAAyB,CAAA;AAEhC;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,EAC3C,gBAAgB,EAChB,UAAU,EACV,OAAO,EAKR;IACC,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAA;IACtE,MAAM,UAAU,GAAG,GAAG;SACnB,KAAK,CAAC,OAAO,CAAC;SACd,UAAU,CAAC,kBAAkB,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAA;IACjE,OAAO,uBAAuB,CAAC;QAC7B,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,wBAAwB,CAAC;KACxD,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"rosterStore.js","sourceRoot":"","sources":["../../src/keys/rosterStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAM1D,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC7B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,4BAA4B,CAAC,EAC3C,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,MAAM,EAQP;IACC,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAA;IACtE,MAAM,UAAU,GAAG,GAAG;SACnB,KAAK,CAAC,OAAO,CAAC;SACd,UAAU,CAAC,kBAAkB,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAA;IACjE,OAAO,0BAA0B,CAAC;QAChC,GAAG,EAAE,gBAAgB,CAAC;YACpB,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,4BAA4B,CAAC;SAC5D,CAAC;QACF,iBAAiB;QACjB,QAAQ;QACR,MAAM;KACP,CAAC,CAAA;AACJ,CAAC"}

package/dist/keys/userKeyCascade.d.ts

@@ -138,7 +138,7 @@ export interface UserKeyCascadeResult {
  *   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/user-key.json` roster (the source of the user key generations)
+ *   `key-map/user-key.jsonl` 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.userKey {UserKey}   the roster's current user key

package/dist/keys/userKeyCascade.js

@@ -170,7 +170,7 @@ export async function rotateCollectionEpochsToUserKey({ store, userKey, generati
  *   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/user-key.json` roster (the source of the user key generations)
+ *   `key-map/user-key.jsonl` 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.userKey {UserKey}   the roster's current user key

package/dist/keys/userKeyRoster.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The user key wrap set: the `key-map/user-key.json` roster resource. Its body
+ * The user key wrap set: the roster governed by `key-map/user-key.jsonl`. Its state
  * is a `CollectionEncryption` descriptor verbatim, whose current epoch IS the
  * current user key -- the epoch id is the user key's did:key and the wrapped
  * secret is the user key's raw 32-byte key, wrapped to each enrolled client's
@@ -10,25 +10,34 @@
  * each client keeps the user key in its own local state under the unlock layer,
  * and the roster's epoch stamp marks a cached copy stale.
  *
- * Everything mutates through was-client's descriptor-store seam (the
- * plain-resource adapter): read-with-etag, compare-and-swap writes, and a
- * guarded create for the initially-absent roster. No descriptor logic is
+ * Everything mutates through was-client's descriptor-store seam -- since the
+ * roster became log-governed, the log-backed adapter
+ * (`logGovernedDescriptorStore`): reads resolve to the roster log's VERIFIED
+ * head state, writes append signed entries. No descriptor logic is
  * reimplemented here.
  *
  * A resource-hosted descriptor gets NONE of the server-side epoch invariants a
  * Collection Description enforces (append-only epochs, monotone
- * `currentEpoch`), so four client-side compensations are load-bearing alone
+ * `currentEpoch`), so the client-side compensations are load-bearing alone
  * against a tampering host:
  *
- * - **`epochsMac`** -- the epoch configuration is authenticated under the
- *   current epoch's secret, which the server never holds; a fabricated
- *   configuration fails the MAC (`UserKeyRosterIntegrityError`).
+ * - **The resource log** -- the roster is governed by a hash-linked log whose
+ *   every entry is signed by an enrolled client's key, anchored in the
+ *   locally verified did:webvh document, and continuity-checked against the
+ *   client's chain-head pin (the `resourceLog` module). A fabricated roster
+ *   fails entry-proof verification (`ResourceLogIntegrityError`); a rolled
+ *   back, forked, or format-switched log fails continuity
+ *   (`ResourceLogContinuityError`). This is the successor of the retired
+ *   detached `epochsSig`: the entry proof covers the whole configuration, on
+ *   every read instead of only the adopt path. (The `epochsMac`
+ *   epoch-configuration MAC that used to sit beneath it is retired stack-wide:
+ *   on a log-governed resource its coverage was a strict subset of chain
+ *   verification.)
  * - **The epoch pin** -- the latest-seen roster epoch is pinned locally by the
  *   consuming app (beside the account-pointer pin); a served
  *   roster that rolls back behind the pin is refused
- *   (`UserKeyRosterContinuityError`) rather than followed. Stale-roster replay
- *   thereby lands in the same accepted continuity class as a substituted
- *   account pointer.
+ *   (`UserKeyRosterContinuityError`) rather than followed, even where the
+ *   chain-head pin was lost with a reinstalled client.
  * - **The roster delivers, never sources** -- the recipient-key source of
  *   record is the locally verified did:webvh document (one `keyAgreement`
  *   verification method per enrolled client). When an epoch rotates, each
@@ -37,28 +46,18 @@
  *   verification method is dropped and never receives a wrap, so a
  *   server-injected entry sits ignored. Wraps are minted only by enrolled
  *   clients, against log-verified keys.
- * - **`epochsSig`** -- the epoch configuration is additionally SIGNED by the
- *   writing client's enrolled Ed25519 key (`userKeyRosterEpochsSigner`), and a
- *   read that adopts an epoch this client has not vouched for itself (a
- *   rotated read, or a freshly enrolled client's first read) verifies that
- *   signature against the locally verified did:webvh document
- *   (`verifyUserKeyRosterEpochsSig`). This is the check the `epochsMac` alone
- *   cannot make on those paths: the MAC is keyed by a secret unwrapped from
- *   the served descriptor itself, so a host that mints its own epoch, wraps
- *   it to this client's world-readable key-agreement key, and MACs the
- *   fabricated configuration under the same minted secret passes the MAC --
- *   but it cannot produce a signature by a key the document backs.
  */
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
 import type { CollectionEncryption } from '@interop/was-client';
-import { type EncryptionDescriptorStore, type EpochsSigner, type RecipientPublicKey } from '@interop/was-client/edv';
+import { type EncryptionDescriptorStore, type RecipientPublicKey } from '@interop/was-client/edv';
+import type { ResourceLogSigner } from '../resourceLog/index.js';
 import { type ICapabilityAgent } from '../webvh/zcap.js';
 import type { UserKey } from './userKey.js';
 /**
- * Thrown when a served roster fails its client-side authentication: a
- * missing/unsupported/invalid `epochsMac`, or a descriptor whose `currentEpoch`
- * names no epoch in its own list. The server (or whoever can write to it) has
- * produced a configuration no enrolled client authenticated.
+ * Thrown when a served roster fails its client-side consistency checks: a
+ * descriptor whose `currentEpoch` names no epoch in its own list. The server
+ * (or whoever can write to it) has produced a configuration no enrolled
+ * client authenticated.
  */
 export declare class UserKeyRosterIntegrityError extends Error {
     constructor(message: string);
@@ -67,8 +66,7 @@ export declare class UserKeyRosterIntegrityError extends Error {
  * Thrown when a served roster conflicts with the locally pinned latest-seen
  * epoch -- the epochs list no longer contains the pinned epoch, or
  * `currentEpoch` precedes it in the (append-only) list. A rollback/replay of
- * an older consistent configuration, which a valid `epochsMac` alone cannot
- * catch; refused rather than followed.
+ * an older consistent configuration; refused rather than followed.
  */
 export declare class UserKeyRosterContinuityError extends Error {
     pinnedEpochId: string;
@@ -101,40 +99,22 @@ export interface RosterRecipientDocument {
     }>;
 }
 /**
- * The roster's epoch-configuration signer: signs each roster write's epoch
- * configuration with this client's own Ed25519 signing key, under a `kid`
- * that is the key's public multibase -- exactly the string enrolled as this
- * client's verification method in the did:webvh document, so a reader
- * resolves the signature against the document rather than anything the
- * roster (or the server) supplies.
+ * The roster's log signer: signs each roster log append with this client's
+ * own Ed25519 signing key, named by its public multibase -- exactly the
+ * string enrolled as this client's verification method in the did:webvh
+ * document, so a reader resolves the entry proof against the document rather
+ * than anything the roster (or the server) supplies. Successor of the retired
+ * `epochsSig` signer under the log design.
  *
  * @param options {object}
  * @param options.keyAgent {ICapabilityAgent}   this client's signing key
  *   agent (the `keyAgent` of `agentsFromSeed`)
- * @returns {EpochsSigner}   the `signEpochs` hook for roster writes
+ * @returns {ResourceLogSigner}   the signer for the log-governed store's
+ *   appends
  */
-export declare function userKeyRosterEpochsSigner({ keyAgent }: {
+export declare function userKeyRosterLogSigner({ keyAgent }: {
     keyAgent: ICapabilityAgent;
-}): EpochsSigner;
-/**
- * Verifies a served roster's `epochsSig` against the locally verified
- * did:webvh document -- the root of trust the server cannot mint. The
- * signature must be present and supported, its `kid` must be the public
- * multibase of one of the document's verification methods (an enrolled
- * client's signing key), and it must verify over the canonical
- * epoch-configuration payload. Throws {@link UserKeyRosterIntegrityError}
- * otherwise: a configuration no enrolled client signed.
- *
- * @param options {object}
- * @param options.descriptor {CollectionEncryption}   the served roster
- * @param options.document {RosterRecipientDocument}   the locally verified
- *   did:webvh document (never a server-supplied roster field)
- * @returns {Promise<void>}
- */
-export declare function verifyUserKeyRosterEpochsSig({ descriptor, document }: {
-    descriptor: CollectionEncryption;
-    document: RosterRecipientDocument;
-}): Promise<void>;
+}): ResourceLogSigner;
 /**
  * A wallet client's roster kid: its key-agreement key's id exactly as
  * `agentsFromSeed` derives it at the client's own logins
@@ -185,16 +165,12 @@ export declare function userKeyRosterRecipientResolver({ document }: {
  * @param options.userKey {UserKey}   the account's user key
  * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
  *   (identity) key-agreement key -- the roster recipient
- * @param options.signEpochs {EpochsSigner}   this client's epoch-configuration
- *   signer ({@link userKeyRosterEpochsSigner}), so the first configuration is
- *   vouched for by an enrollable key rather than only its own MAC
  * @returns {Promise<CollectionEncryption>}   the roster descriptor
  */
-export declare function ensureUserKeyRoster({ store, userKey, clientKeyAgreementKey, signEpochs }: {
+export declare function ensureUserKeyRoster({ store, userKey, clientKeyAgreementKey }: {
     store: EncryptionDescriptorStore;
     userKey: UserKey;
     clientKeyAgreementKey: IKeyAgreementKey;
-    signEpochs: EpochsSigner;
 }): Promise<CollectionEncryption>;
 /**
  * Wraps the user key to a client being enrolled -- the roster half of the
@@ -246,16 +222,12 @@ export declare function addUserKeyRosterRecipient({ store, recipient, ownerKeyAg
  *   did:webvh document, AFTER the removal edit
  * @param options.retireRecipientId {string}   the removed recipient's roster
  *   kid
- * @param options.signEpochs {EpochsSigner}   the rotating client's
- *   epoch-configuration signer ({@link userKeyRosterEpochsSigner}), vouching for
- *   the fresh epoch so other clients' rotated reads accept it
  * @returns {Promise<CollectionEncryption>}   the rotated roster descriptor
  */
-export declare function rotateUserKeyRoster({ store, document, retireRecipientId, signEpochs }: {
+export declare function rotateUserKeyRoster({ store, document, retireRecipientId }: {
     store: EncryptionDescriptorStore;
     document: RosterRecipientDocument;
     retireRecipientId: string;
-    signEpochs: EpochsSigner;
 }): Promise<CollectionEncryption>;
 /**
  * Converges the roster onto the account document: the standing detector for a
@@ -291,18 +263,14 @@ export declare function rotateUserKeyRoster({ store, document, retireRecipientId
  * @param [options.descriptor] {CollectionEncryption}   a descriptor the caller
  *   has just read (a login-time roster read), to save a re-read; omitted, the
  *   roster is read fresh
- * @param options.signEpochs {EpochsSigner}   the converging client's
- *   epoch-configuration signer ({@link userKeyRosterEpochsSigner}), for the
- *   rotation this call may perform
  * @returns {Promise<object>}   whether the roster rotated on this call, the
  *   stale recipient kids found, and the roster descriptor as it now stands
  *   (`null` when the account has no roster yet)
  */
-export declare function convergeUserKeyRosterToDocument({ store, document, descriptor, signEpochs }: {
+export declare function convergeUserKeyRosterToDocument({ store, document, descriptor }: {
     store: EncryptionDescriptorStore;
     document: RosterRecipientDocument;
     descriptor?: CollectionEncryption;
-    signEpochs: EpochsSigner;
 }): Promise<{
     rotated: boolean;
     staleRecipientIds: string[];
@@ -325,24 +293,19 @@ export interface UserKeyRosterReadResult {
  * mismatch. Resolves `null` when the roster does not exist yet (an account
  * provisioned before the roster, or provisioning still in flight); otherwise:
  *
- * 1. **Continuity**: the served epochs must contain the pinned latest-seen
+ * 1. **Provenance** is the store's: a log-governed store resolves the read
+ *    from the roster log's verified head -- entry proofs checked against the
+ *    locally verified did:webvh document, chain-head pin enforced -- so
+ *    every epoch this read can deliver was signed onto the log by an
+ *    enrolled client. (The detached `epochsSig` this step used to verify on
+ *    the adopt path is retired; the entry proof covers every read.)
+ * 2. **Continuity**: the served epochs must contain the pinned latest-seen
  *    epoch, and `currentEpoch` must not precede it in the append-only list
  *    (`UserKeyRosterContinuityError` -- the rollback/replay refusal).
- * 2. **Possession**: `currentEpoch === userKey.id` confirms the cached user key
+ * 3. **Possession**: `currentEpoch === userKey.id` confirms the cached user key
  *    current; otherwise the current epoch was rotated by another client and
  *    this client's wrap is unwrapped with its own key-agreement key
  *    (`UserKeyRosterUnwrapError` when it holds none).
- * 3. **Provenance** (the rotated/first-read path only): the epoch
- *    configuration's `epochsSig` is verified against the locally verified
- *    did:webvh document ({@link verifyUserKeyRosterEpochsSig}) BEFORE the epoch
- *    it delivers is adopted. On this path the `epochsMac` alone proves
- *    nothing against the host -- its key is unwrapped from the served
- *    descriptor itself -- so an epoch no enrolled client signed is refused
- *    (`UserKeyRosterIntegrityError`). The cached-current path needs no signature:
- *    there the MAC is keyed by a secret this client already trusts.
- * 4. **Authentication**: the descriptor's `epochsMac` is verified under the
- *    current epoch's secret (`UserKeyRosterIntegrityError` on any mismatch -- a
- *    fabricated configuration).
  *
  * A rotated read returns the fresh user key; its Ed25519 signing seed does not
  * travel through the roster (the roster wraps the key-agreement secret
@@ -351,10 +314,7 @@ export interface UserKeyRosterReadResult {
  * A caller with no cached user key at all -- a freshly enrolled client making
  * its first post-enrollment read -- omits `userKey` and always takes the unwrap
  * path; the result's `rotated` is then true (the user key was adopted from the
- * roster). Every unwrap-path caller must therefore supply the account document
- * (or a way to resolve it): `document` when it already holds a verified copy,
- * or `resolveDocument` to fetch-and-verify lazily, only when the read actually
- * rotates.
+ * roster).
  *
  * @param options {object}
  * @param options.store {EncryptionDescriptorStore}   the roster's descriptor
@@ -364,19 +324,12 @@ export interface UserKeyRosterReadResult {
  *   (identity) key-agreement key, unwrapping a rotated epoch
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch, when this client has seen the roster before
- * @param [options.document] {RosterRecipientDocument}   the locally verified
- *   did:webvh document, when the caller already holds one
- * @param [options.resolveDocument] {function}   resolves the locally verified
- *   did:webvh document on demand; called only when the read takes the
- *   rotated/first-read path
  * @returns {Promise<UserKeyRosterReadResult | null>}
  */
-export declare function readUserKeyRoster({ store, userKey, clientKeyAgreementKey, pinnedEpochId, document, resolveDocument }: {
+export declare function readUserKeyRoster({ store, userKey, clientKeyAgreementKey, pinnedEpochId }: {
     store: EncryptionDescriptorStore;
     userKey?: UserKey;
     clientKeyAgreementKey: IKeyAgreementKey;
     pinnedEpochId?: string | null;
-    document?: RosterRecipientDocument;
-    resolveDocument?: () => Promise<RosterRecipientDocument>;
 }): Promise<UserKeyRosterReadResult | null>;
 //# sourceMappingURL=userKeyRoster.d.ts.map