@interop/wallet-core 0.4.1 → 0.6.0

package/dist/keyring/unlockSpace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlockSpace.d.ts","sourceRoot":"","sources":["../../src/keyring/unlockSpace.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAA;AAoIrD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,UAAU,EACV,IAAwB,EACzB,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACR,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAQ1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,MAAM,EACP,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACR,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,+BAA+B,CAAC,EACpD,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,KAAK,CAAA;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB"}

package/dist/keyring/unlockSpace.js

@@ -0,0 +1,226 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The unlock Space: a minimal second Space, controlled by an unlock identity
+ * and separate from the wallet data Space, holding the one keyring record.
+ * These are standalone functions rather than methods on a wallet's remote-store
+ * class (that store is bound to the data identity): each builds its own
+ * `WasClient` over the unlock agent's `zcapClient`, whose invocation signer is
+ * the unlock root key (root invocation, no capability attached -- the same
+ * posture the data Space uses).
+ *
+ * The one resource is a plaintext JSON document (its keyring payload is
+ * already ciphertext), so no encryption provider is wired in -- and the
+ * read/write handles pass the explicit `{ encryption: 'plaintext' }` override.
+ * The override is load-bearing: without it, the client decides plaintext vs
+ * encrypted by reading the collection description, and when the unlock Space
+ * does not exist yet (every keyring lookup for a fresh unlock secret) that read
+ * 404s and the client refuses to guess, throwing an EncryptionError instead of
+ * surfacing the miss as a 404-shaped `null`.
+ */
+import { WasClient } from '@interop/was-client';
+import { errorStatus } from '@interop/was-client/sync';
+import { KEYRING_COLLECTION, KEYRING_RESOURCE } from '../space/collections.js';
+/**
+ * The default Space Description name an unlock Space is configured with.
+ * Wire-visible (it is the Space's stored name), so it stays stable across
+ * apps unless a caller deliberately overrides it.
+ */
+export const UNLOCK_SPACE_NAME = 'Freewallet Keyring';
+/**
+ * The bare WAS client for an unlock Space (see the module doc for why it wires
+ * in no encryption provider).
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}   built on the unlock agent's signer
+ * @returns {WasClient}
+ */
+function unlockSpaceClient({ storageServerUrl, zcapClient }) {
+    return new WasClient({
+        serverUrl: storageServerUrl,
+        zcapClient
+    });
+}
+/**
+ * Ensures a plaintext collection exists in a Space (upsert -- idempotent),
+ * running with the invoking client's root capability so `force` lets the upsert
+ * treat a 404 from the pre-merge describe as genuinely absent rather than
+ * unreadable.
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.name {string}
+ * @returns {Promise<void>}
+ */
+async function ensurePlaintextCollection({ storageServerUrl, zcapClient, spaceId, collectionId, name }) {
+    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+    await was
+        .space(spaceId)
+        .collection(collectionId)
+        .configure({ name, force: true });
+}
+/**
+ * Reads a single plaintext JSON record from a Space collection, or `null` when
+ * it does not exist yet (a missing Space, collection, or resource all surface
+ * as a 404-shaped `null` from `resource.get()`). A network / unreachable error
+ * propagates, so callers can distinguish "no record" from "could not check".
+ * The explicit `plaintext` override is load-bearing (see the module doc).
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {Promise<unknown | null>}
+ */
+async function getPlaintextRecord({ storageServerUrl, zcapClient, spaceId, collectionId, resourceId }) {
+    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+    const result = await was
+        .space(spaceId)
+        .collection(collectionId, { encryption: 'plaintext' })
+        .resource(resourceId)
+        .get();
+    return result === null ? null : result;
+}
+/**
+ * Writes (upserts) a single plaintext JSON record into a Space collection.
+ * Serialized to bytes with an explicit `application/json` content-type.
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @param options.record {object}
+ * @returns {Promise<void>}
+ */
+async function putPlaintextRecord({ storageServerUrl, zcapClient, spaceId, collectionId, resourceId, record }) {
+    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+    const body = new TextEncoder().encode(JSON.stringify(record));
+    await was
+        .space(spaceId)
+        .collection(collectionId, { encryption: 'plaintext' })
+        .resource(resourceId)
+        .put(body, { contentType: 'application/json' });
+}
+/**
+ * Ensures the unlock Space and its single `keyring` collection exist
+ * (upsert -- idempotent). Runs with the unlock root capability, so `force`
+ * lets the collection upsert treat a 404 from the pre-merge describe as
+ * genuinely absent rather than unreadable.
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}   the unlock Space id
+ * @param options.controller {string}   the unlock did:key
+ * @param [options.name] {string}   the Space Description name
+ * @returns {Promise<void>}
+ */
+export async function ensureUnlockSpace({ storageServerUrl, zcapClient, spaceId, controller, name = UNLOCK_SPACE_NAME }) {
+    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+    await was.space(spaceId).configure({ name, controller });
+    await ensurePlaintextCollection({
+        storageServerUrl,
+        zcapClient,
+        spaceId,
+        collectionId: KEYRING_COLLECTION.id,
+        name: KEYRING_COLLECTION.name
+    });
+}
+/**
+ * Reads the keyring record from the unlock Space, or returns `null` when it
+ * does not exist yet. A network / unreachable error propagates, so callers can
+ * distinguish "no keyring" from "could not check".
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}   the unlock Space id
+ * @returns {Promise<unknown | null>}
+ */
+export async function getUnlockKeyring({ storageServerUrl, zcapClient, spaceId }) {
+    return getPlaintextRecord({
+        storageServerUrl,
+        zcapClient,
+        spaceId,
+        collectionId: KEYRING_COLLECTION.id,
+        resourceId: KEYRING_RESOURCE
+    });
+}
+/**
+ * Writes (upserts) the keyring record into the unlock Space as a JSON document.
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}   the unlock Space id
+ * @param options.record {object}   the keyring record
+ * @returns {Promise<void>}
+ */
+export async function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId, record }) {
+    await putPlaintextRecord({
+        storageServerUrl,
+        zcapClient,
+        spaceId,
+        collectionId: KEYRING_COLLECTION.id,
+        resourceId: KEYRING_RESOURCE,
+        record
+    });
+}
+/**
+ * Deletes the whole unlock Space (what retires an old passphrase on a
+ * passphrase change). `space.delete()` is idempotent, so an already-absent
+ * Space is a success.
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}
+ * @param options.spaceId {string}   the unlock Space id
+ * @returns {Promise<void>}
+ */
+export async function deleteUnlockSpace({ storageServerUrl, zcapClient, spaceId }) {
+    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+    await was.space(spaceId).delete();
+}
+/**
+ * Deletes an unlock Space with an explicitly attached management capability,
+ * rather than by root invocation. The `zcapClient` here is the DATA identity's
+ * (not the unlock identity's); the attached `capability` -- the management zcap
+ * the unlock identity delegated to the data identity at bind time -- is what
+ * authorizes the DELETE against the unlock Space. This is the tap-free
+ * revocation path for a lost unlock method: the data identity can retire it
+ * without re-deriving the unlock identity from the (possibly lost) secret. A
+ * 404 is treated as success (idempotent -- the Space is already gone).
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.zcapClient {ZcapClient}   the data identity's client
+ * @param options.spaceId {string}   the unlock Space id
+ * @param options.capability {IZcap}   the delegated management zcap
+ * @returns {Promise<void>}
+ */
+export async function deleteUnlockSpaceWithCapability({ storageServerUrl, zcapClient, spaceId, capability }) {
+    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+    try {
+        await was.request({
+            capability,
+            path: `/space/${spaceId}`,
+            method: 'DELETE'
+        });
+    }
+    catch (err) {
+        if (errorStatus(err) === 404) {
+            return;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=unlockSpace.js.map

package/dist/keyring/unlockSpace.js.map

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

package/dist/keys/index.d.ts

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/keys` subpath: the per-user key (PUK) and its
+ * wrap-set roster -- recipient zero of every encrypted collection, and the one
+ * channel that delivers it to each enrolled wallet client.
+ *
+ * - `mintPuk` / `pukVaultKeys` -- minting the account's PUK and rebuilding the
+ *   vault key-agreement key + resolver from stored material.
+ * - `ensurePukRoster` / `addPukRosterRecipient` / `readPukRoster` /
+ *   `pukRosterRecipientResolver` -- the `key-map/puk.json` roster over the
+ *   was-client marker-store seam, with the three client-side guards a
+ *   resource-hosted marker needs (`epochsMac`, the latest-seen epoch pin, and
+ *   a recipient resolver backed by the locally verified did:webvh document).
+ * - `pukRosterMarkerStore` -- that marker store, built from a bare signing
+ *   client for the login-time direct read.
+ */
+export { mintPuk, pukVaultKeys } from './puk.js';
+export type { Puk } from './puk.js';
+export { addPukRosterRecipient, ensurePukRoster, PukRosterContinuityError, PukRosterIntegrityError, PukRosterUnwrapError, pukRosterRecipientResolver, readPukRoster } from './pukRoster.js';
+export type { PukRosterReadResult, RosterRecipientDocument } from './pukRoster.js';
+export { pukRosterMarkerStore } from './rosterStore.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAChD,YAAY,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAEnC,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,EACd,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/keys/index.js

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/keys` subpath: the per-user key (PUK) and its
+ * wrap-set roster -- recipient zero of every encrypted collection, and the one
+ * channel that delivers it to each enrolled wallet client.
+ *
+ * - `mintPuk` / `pukVaultKeys` -- minting the account's PUK and rebuilding the
+ *   vault key-agreement key + resolver from stored material.
+ * - `ensurePukRoster` / `addPukRosterRecipient` / `readPukRoster` /
+ *   `pukRosterRecipientResolver` -- the `key-map/puk.json` roster over the
+ *   was-client marker-store seam, with the three client-side guards a
+ *   resource-hosted marker needs (`epochsMac`, the latest-seen epoch pin, and
+ *   a recipient resolver backed by the locally verified did:webvh document).
+ * - `pukRosterMarkerStore` -- that marker store, built from a bare signing
+ *   client for the login-time direct read.
+ */
+export { mintPuk, pukVaultKeys } from './puk.js';
+export { addPukRosterRecipient, ensurePukRoster, PukRosterContinuityError, PukRosterIntegrityError, PukRosterUnwrapError, pukRosterRecipientResolver, readPukRoster } from './pukRoster.js';
+export { pukRosterMarkerStore } from './rosterStore.js';
+//# sourceMappingURL=index.js.map

package/dist/keys/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGhD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,EACd,MAAM,gBAAgB,CAAA;AAMvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/keys/puk.d.ts

@@ -0,0 +1,42 @@
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+/**
+ * The per-user key material: the X25519 key-agreement half as minted by the
+ * epoch construction (`id` is the key's own did:key; `secret` its raw 32-byte
+ * private key), plus the 32-byte seed of the PUK's Ed25519 signing pair.
+ * Random per account; held in memory for the life of a session and persisted
+ * only inside a wrapped client-key record. The signing seed is absent on a PUK
+ * adopted from a roster rotation -- the roster wraps the key-agreement secret
+ * alone, and the signing half has no consumer yet.
+ */
+export interface Puk {
+    id: string;
+    secret: Uint8Array;
+    signingSeed?: Uint8Array;
+}
+/**
+ * Mints a fresh PUK: the X25519 key-agreement pair via the was-client epoch
+ * construction (its did:key is the key id, its raw secret is what wraps), plus
+ * a random 32-byte Ed25519 signing seed -- a minted PUK is always a complete
+ * identity (only a rotation-adopted one lacks the signing half).
+ *
+ * @returns {Promise<Required<Puk>>}
+ */
+export declare function mintPuk(): Promise<Required<Puk>>;
+/**
+ * Reconstructs the PUK's key-agreement key and its single-key resolver from
+ * the stored material -- the vault-key pair a session supplies to the storage
+ * layer, making the PUK recipient zero of every encrypted collection. The key
+ * id is the self-describing `<did:key>#<fingerprint>` form, so grantee-side
+ * did:key recipient resolution routes it like any other roster entry.
+ *
+ * @param options {object}
+ * @param options.puk {Puk}
+ * @returns {{ keyAgreementKey: IKeyAgreementKey, keyResolver: IKeyResolver }}
+ */
+export declare function pukVaultKeys({ puk }: {
+    puk: Puk;
+}): {
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+};
+//# sourceMappingURL=puk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"puk.d.ts","sourceRoot":"","sources":["../../src/keys/puk.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AAIrC;;;;;;;;GAQG;AACH,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,UAAU,CAAA;IAClB,WAAW,CAAC,EAAE,UAAU,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAKtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IACnD,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,CAQA"}

package/dist/keys/puk.js

@@ -0,0 +1,56 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The per-user key (PUK): the user's single roster identity for encrypted
+ * collections, standing in as "recipient zero" of every key-epoch roster. It is
+ * minted at wallet provisioning -- random, client-side, never server-held, and
+ * never derivable from any passphrase or seed -- and delivered to each enrolled
+ * client through the wrap-set roster, which each client caches in its own local
+ * state under the unlock layer.
+ *
+ * The key-agreement half is exactly what `@interop/was-client`'s epoch
+ * construction mints: a fresh X25519 pair whose did:key is the key's id and
+ * whose raw 32-byte secret is what gets wrapped to recipients -- so the roster
+ * machinery consumes the PUK unchanged. The Ed25519 signing half is a second
+ * independent 32-byte seed, minted now so the PUK is a complete identity, with
+ * no consumer yet (the pair derives from the seed on demand once one lands).
+ */
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+import { epochKeyIdFor, mintEpoch } from '@interop/was-client/edv';
+import { singleKeyResolver } from '../identity/keyResolver.js';
+/**
+ * Mints a fresh PUK: the X25519 key-agreement pair via the was-client epoch
+ * construction (its did:key is the key id, its raw secret is what wraps), plus
+ * a random 32-byte Ed25519 signing seed -- a minted PUK is always a complete
+ * identity (only a rotation-adopted one lacks the signing half).
+ *
+ * @returns {Promise<Required<Puk>>}
+ */
+export async function mintPuk() {
+    const { epochId, secret } = await mintEpoch();
+    const signingSeed = new Uint8Array(32);
+    crypto.getRandomValues(signingSeed);
+    return { id: epochId, secret, signingSeed };
+}
+/**
+ * Reconstructs the PUK's key-agreement key and its single-key resolver from
+ * the stored material -- the vault-key pair a session supplies to the storage
+ * layer, making the PUK recipient zero of every encrypted collection. The key
+ * id is the self-describing `<did:key>#<fingerprint>` form, so grantee-side
+ * did:key recipient resolution routes it like any other roster entry.
+ *
+ * @param options {object}
+ * @param options.puk {Puk}
+ * @returns {{ keyAgreementKey: IKeyAgreementKey, keyResolver: IKeyResolver }}
+ */
+export function pukVaultKeys({ puk }) {
+    const keyAgreementKey = X25519KeyAgreementKey2020.fromRawSecret({
+        secret: puk.secret,
+        controller: puk.id,
+        id: epochKeyIdFor(puk.id)
+    });
+    const keyResolver = singleKeyResolver({ keyAgreementKey });
+    return { keyAgreementKey, keyResolver };
+}
+//# sourceMappingURL=puk.js.map

package/dist/keys/puk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"puk.js","sourceRoot":"","sources":["../../src/keys/puk.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAK7E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAiB9D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO;IAC3B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,EAAE,CAAA;IAC7C,MAAM,WAAW,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IACtC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,CAAA;IACnC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,GAAG,EAAgB;IAIhD,MAAM,eAAe,GAAG,yBAAyB,CAAC,aAAa,CAAC;QAC9D,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,GAAG,CAAC,EAAE;QAClB,EAAE,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;KAC1B,CAAqB,CAAA;IACtB,MAAM,WAAW,GAAG,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC,CAAA;IAC1D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,CAAA;AACzC,CAAC"}

package/dist/keys/pukRoster.d.ts

@@ -0,0 +1,210 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The PUK wrap set: the `key-map/puk.json` roster resource. Its body is a
+ * `CollectionEncryption` marker verbatim, whose current epoch IS the current
+ * per-user key -- the epoch id is the PUK's did:key and the wrapped secret is
+ * the PUK's raw 32-byte key, wrapped to each enrolled client's key-agreement
+ * key. The roster is the delivery channel for PUK rotation: each client keeps
+ * the PUK 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 marker-store seam (the
+ * plain-resource adapter): read-with-etag, compare-and-swap writes, and a
+ * guarded create for the initially-absent roster. No marker logic is
+ * reimplemented here.
+ *
+ * A resource-hosted marker gets NONE of the server-side epoch invariants a
+ * Collection Description enforces (append-only epochs, monotone
+ * `currentEpoch`), so three 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 (`PukRosterIntegrityError`).
+ * - **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
+ *   (`PukRosterContinuityError`) rather than followed. Stale-roster replay
+ *   thereby lands in the same accepted continuity class as a substituted
+ *   account pointer.
+ * - **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
+ *   remaining recipient's key is resolved from that document
+ *   (`pukRosterRecipientResolver`); a roster entry with no matching document
+ *   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.
+ */
+import type { IKeyAgreementKey } from '@interop/data-integrity-core';
+import type { CollectionEncryption } from '@interop/was-client';
+import { type MarkerStore, type RecipientPublicKey } from '@interop/was-client/edv';
+import type { Puk } from './puk.js';
+/**
+ * Thrown when a served roster fails its client-side authentication: a
+ * missing/unsupported/invalid `epochsMac`, or a marker 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 PukRosterIntegrityError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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.
+ */
+export declare class PukRosterContinuityError extends Error {
+    pinnedEpochId: string;
+    constructor({ pinnedEpochId }: {
+        pinnedEpochId: string;
+    });
+}
+/**
+ * Thrown when this client holds no usable wrap in the roster's current epoch
+ * (no recipient entry for its key-agreement key, or the entry fails to
+ * unwrap). The client cannot obtain the current PUK -- it may have been
+ * rotated off the roster.
+ */
+export declare class PukRosterUnwrapError extends Error {
+    constructor(message: string);
+}
+/**
+ * The subset of a resolved DID document the recipient resolver consumes: the
+ * `keyAgreement` relation (VM references or embedded VMs) and the
+ * `verificationMethod` list references resolve against.
+ */
+export interface RosterRecipientDocument {
+    keyAgreement?: Array<string | {
+        id?: string;
+        publicKeyMultibase?: string;
+    }>;
+    verificationMethod?: Array<{
+        id?: string;
+        publicKeyMultibase?: string;
+    }>;
+}
+/**
+ * Builds the recipient resolver for roster rotations, backed by a locally
+ * verified did:webvh document -- the enforcement point for "the roster
+ * delivers, never sources". Given a remaining recipient's `kid`, it answers
+ * with that recipient's public key ONLY when the document carries a matching
+ * `keyAgreement` verification method (matched on the public-key multibase, so
+ * a did:key-form kid matches its `<did:webvh>#<multibase>` VM); otherwise it
+ * resolves `null` -- the was-client skip contract -- so the entry is dropped
+ * from the fresh epoch and never receives a wrap.
+ *
+ * @param options {object}
+ * @param options.document {RosterRecipientDocument}   the locally verified
+ *   did:webvh document (never a server-supplied roster field)
+ * @returns {function}   a `resolveRecipientKey` for `removeRecipient`
+ */
+export declare function pukRosterRecipientResolver({ document }: {
+    document: RosterRecipientDocument;
+}): (kid: string) => Promise<RecipientPublicKey | null>;
+/**
+ * Ensures the roster exists, create-if-absent: an absent roster is
+ * initialized with the account's existing PUK installed as the first epoch,
+ * wrapped to this client's key-agreement key; an existing roster is returned
+ * as-is (authentication is the read path's job, and provisioning must never
+ * clobber an established roster). Idempotent -- losing the guarded-create
+ * race to a concurrent first init converges on the winner's roster.
+ *
+ * @param options {object}
+ * @param options.store {MarkerStore}   the roster's marker store
+ * @param options.puk {Puk}   the account's per-user key
+ * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
+ *   (identity) key-agreement key -- the roster recipient
+ * @returns {Promise<CollectionEncryption>}   the roster marker
+ */
+export declare function ensurePukRoster({ store, puk, clientKeyAgreementKey }: {
+    store: MarkerStore;
+    puk: Puk;
+    clientKeyAgreementKey: IKeyAgreementKey;
+}): Promise<CollectionEncryption>;
+/**
+ * Wraps the PUK to a client being enrolled -- the roster half of the
+ * enrollment ceremony, and deliberately its FIRST write (decryption material
+ * before authorization, the push order): the wrap lands before the did:webvh
+ * log entries, so no enrolled client is ever authorized but blind, and a tear
+ * right after this write leaves only an orphan wrap -- invisible to
+ * authorization, harmless, resumed by re-running the ceremony.
+ *
+ * Escrow semantics ride on was-client's `addRecipient`: the new client
+ * receives EVERY epoch's key, current and prior, so it decrypts
+ * pre-enrollment history. The recipient key arrives over the point-to-point
+ * enrollment channel and is verified there by the enrolling client (the
+ * document VM it writes next comes from the same exchange) -- never sourced
+ * from the roster. Idempotent: a wrap already standing in the current epoch
+ * is returned as-is.
+ *
+ * @param options {object}
+ * @param options.store {MarkerStore}   the roster's marker store
+ * @param options.recipient {RecipientPublicKey}   the enrollee's public
+ *   key-agreement key; `id` is the kid its own roster reads will look for
+ * @param options.ownerKeyAgreementKey {IKeyAgreementKey}   the enrolling
+ *   client's own (identity) key-agreement key, unwrapping each epoch for
+ *   re-wrapping
+ * @returns {Promise<CollectionEncryption>}   the refreshed roster marker
+ */
+export declare function addPukRosterRecipient({ store, recipient, ownerKeyAgreementKey }: {
+    store: MarkerStore;
+    recipient: RecipientPublicKey;
+    ownerKeyAgreementKey: IKeyAgreementKey;
+}): Promise<CollectionEncryption>;
+/**
+ * What a roster read resolves to: the authenticated marker, the current PUK
+ * (the cached one confirmed current, or a fresh one unwrapped from a rotated
+ * epoch -- `rotated` says which), and the epoch id the caller must pin as the
+ * new latest-seen.
+ */
+export interface PukRosterReadResult {
+    marker: CollectionEncryption;
+    puk: Puk;
+    rotated: boolean;
+    latestEpochId: string;
+}
+/**
+ * Reads and authenticates the roster -- the direct read at login and on epoch
+ * 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
+ *    epoch, and `currentEpoch` must not precede it in the append-only list
+ *    (`PukRosterContinuityError` -- the rollback/replay refusal).
+ * 2. **Possession**: `currentEpoch === puk.id` confirms the cached PUK
+ *    current; otherwise the current epoch was rotated by another client and
+ *    this client's wrap is unwrapped with its own key-agreement key
+ *    (`PukRosterUnwrapError` when it holds none).
+ * 3. **Authentication**: the marker's `epochsMac` is verified under the
+ *    current epoch's secret (`PukRosterIntegrityError` on any mismatch -- a
+ *    fabricated configuration).
+ *
+ * A rotated read returns the fresh PUK; its Ed25519 signing seed does not
+ * travel through the roster (the roster wraps the key-agreement secret
+ * alone), so the returned PUK carries none.
+ *
+ * A caller with no cached PUK at all -- a freshly enrolled client making its
+ * first post-enrollment read -- omits `puk` and always takes the unwrap path;
+ * the result's `rotated` is then true (the PUK was adopted from the roster).
+ *
+ * @param options {object}
+ * @param options.store {MarkerStore}   the roster's marker store
+ * @param [options.puk] {Puk}   this client's cached PUK, when it holds one
+ * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
+ *   (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
+ * @returns {Promise<PukRosterReadResult | null>}
+ */
+export declare function readPukRoster({ store, puk, clientKeyAgreementKey, pinnedEpochId }: {
+    store: MarkerStore;
+    puk?: Puk;
+    clientKeyAgreementKey: IKeyAgreementKey;
+    pinnedEpochId?: string | null;
+}): Promise<PukRosterReadResult | null>;
+//# sourceMappingURL=pukRoster.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pukRoster.d.ts","sourceRoot":"","sources":["../../src/keys/pukRoster.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAEnC;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,aAAa,EAAE,MAAM,CAAA;gBACT,EAAE,aAAa,EAAE,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE;CAQzD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3E,kBAAkB,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzE;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,QAAQ,EACT,EAAE;IACD,QAAQ,EAAE,uBAAuB,CAAA;CAClC,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAsCtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,EACpC,KAAK,EACL,GAAG,EACH,qBAAqB,EACtB,EAAE;IACD,KAAK,EAAE,WAAW,CAAA;IAClB,GAAG,EAAE,GAAG,CAAA;IACR,qBAAqB,EAAE,gBAAgB,CAAA;CACxC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAUhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,KAAK,EACL,SAAS,EACT,oBAAoB,EACrB,EAAE;IACD,KAAK,EAAE,WAAW,CAAA;IAClB,SAAS,EAAE,kBAAkB,CAAA;IAC7B,oBAAoB,EAAE,gBAAgB,CAAA;CACvC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA0BhC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,oBAAoB,CAAA;IAC5B,GAAG,EAAE,GAAG,CAAA;IACR,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,aAAa,CAAC,EAClC,KAAK,EACL,GAAG,EACH,qBAAqB,EACrB,aAAa,EACd,EAAE;IACD,KAAK,EAAE,WAAW,CAAA;IAClB,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAwEtC"}