@interop/wallet-core 0.5.0 → 0.6.0

package/dist/keyring/unlockSpace.d.ts

@@ -0,0 +1,101 @@
+import type { IZcap } from '@interop/data-integrity-core';
+import type { ZcapClient } from '@interop/ezcap';
+/**
+ * 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 declare const UNLOCK_SPACE_NAME = "Freewallet Keyring";
+/**
+ * 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 declare function ensureUnlockSpace({ storageServerUrl, zcapClient, spaceId, controller, name }: {
+    storageServerUrl: string;
+    zcapClient: ZcapClient;
+    spaceId: string;
+    controller: string;
+    name?: string;
+}): Promise<void>;
+/**
+ * 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 declare function getUnlockKeyring({ storageServerUrl, zcapClient, spaceId }: {
+    storageServerUrl: string;
+    zcapClient: ZcapClient;
+    spaceId: string;
+}): Promise<unknown | null>;
+/**
+ * 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 declare function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId, record }: {
+    storageServerUrl: string;
+    zcapClient: ZcapClient;
+    spaceId: string;
+    record: object;
+}): Promise<void>;
+/**
+ * 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 declare function deleteUnlockSpace({ storageServerUrl, zcapClient, spaceId }: {
+    storageServerUrl: string;
+    zcapClient: ZcapClient;
+    spaceId: string;
+}): Promise<void>;
+/**
+ * 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 declare function deleteUnlockSpaceWithCapability({ storageServerUrl, zcapClient, spaceId, capability }: {
+    storageServerUrl: string;
+    zcapClient: ZcapClient;
+    spaceId: string;
+    capability: IZcap;
+}): Promise<void>;
+//# sourceMappingURL=unlockSpace.d.ts.map

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"}