@interop/wallet-core 0.5.0 → 0.6.0

package/dist/space/collections.js

@@ -62,4 +62,52 @@ export const WALLET_SPACE_COLLECTION_SPECS = [
     PUBLIC_CREDENTIALS_COLLECTION_SPEC,
     WALLET_ACTIVITY_COLLECTION_SPEC
 ];
+/**
+ * The system collections and resource names that carry an account's identity
+ * and key material. They sit deliberately OUTSIDE the synced collection specs
+ * above: none of them gets a local replica or background replication, and each
+ * is read and written directly.
+ *
+ * - `id` -- world-readable (a collection-level public-read policy): the
+ *   published DID document (`did.json`) and the did:webvh history log
+ *   (`did.jsonl`). The path segments name the collection that holds the
+ *   document, so the did:web id is `did:web:<host>:space:<spaceId>:id` and
+ *   resolves to `https://<host>/space/<spaceId>/id/did.json`.
+ * - `key-map` -- private and capability-gated: the key-id map (`keys.json`)
+ *   and the PUK wrap-set roster (`puk.json`). Kept separate from `id` exactly
+ *   so `id` can be made world-readable without ever exposing key material.
+ * - `keyring` -- the unlock Space's single collection, holding the one
+ *   keyring record (`keyring.json`). It lives in the minimal unlock Space
+ *   controlled by an unlock identity, never in the wallet data Space.
+ */
+export const ID_COLLECTION = { id: 'id', name: 'Identity' };
+export const KEY_MAP_COLLECTION = { id: 'key-map', name: 'Key Map' };
+export const KEYRING_COLLECTION = { id: 'keyring', name: 'Keyring' };
+/** The world-readable DID document, served as `application/did+json`. */
+export const DID_DOCUMENT_RESOURCE = 'did.json';
+/**
+ * The world-readable did:webvh history log, a raw JSON-Lines string served as
+ * `text/jsonl`: one log entry per line, each a full DID-document snapshot in a
+ * hash chain. Sibling of `did.json` in the same `id` collection;
+ * `did:webvh:<scid>:<host>:space:<spaceId>:id` resolves to
+ * `https://<host>/space/<spaceId>/id/did.jsonl`.
+ */
+export const DID_LOG_RESOURCE = 'did.jsonl';
+/**
+ * The (non-public) key-id map: verification method to KMS key id. Lives in the
+ * `key-map` collection. The recovery anchor -- written before `did.json` so a
+ * torn provisioning resumes from it.
+ */
+export const DID_KEYS_RESOURCE = 'keys.json';
+/**
+ * The per-user-key (PUK) wrap-set roster, sibling of `keys.json` in the same
+ * private `key-map` collection: a `CollectionEncryption` marker stored
+ * verbatim as the resource body, whose current epoch IS the current PUK (the
+ * epoch id is the PUK's did:key; the wrapped secret is the PUK's raw key,
+ * wrapped to each enrolled client's key-agreement key). Read directly with a
+ * compare-and-swap etag -- never replicated.
+ */
+export const PUK_ROSTER_RESOURCE = 'puk.json';
+/** The keyring record: the encrypted account pointer, in the unlock Space. */
+export const KEYRING_RESOURCE = 'keyring.json';
 //# sourceMappingURL=collections.js.map

package/dist/space/collections.js.map

@@ -1 +1 @@
-{"version":3,"file":"collections.js","sourceRoot":"","sources":["../../src/space/collections.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAA;AACnE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAA;AACjE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAAiB,CAAA;AAyB3D;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAwB;IACtE,YAAY,EAAE,8BAA8B;IAC5C,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAwB;IACrE,YAAY,EAAE,6BAA6B;IAC3C,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,WAAW;IACvB,QAAQ,EAAE,IAAI;CACf,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAwB;IAClE,YAAY,EAAE,0BAA0B;IACxC,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,6BAA6B,GAA0B;IAClE,mCAAmC;IACnC,kCAAkC;IAClC,+BAA+B;CAChC,CAAA"}
+{"version":3,"file":"collections.js","sourceRoot":"","sources":["../../src/space/collections.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAA;AACnE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAA;AACjE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAAiB,CAAA;AAyB3D;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAwB;IACtE,YAAY,EAAE,8BAA8B;IAC5C,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAwB;IACrE,YAAY,EAAE,6BAA6B;IAC3C,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,WAAW;IACvB,QAAQ,EAAE,IAAI;CACf,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAwB;IAClE,YAAY,EAAE,0BAA0B;IACxC,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,6BAA6B,GAA0B;IAClE,mCAAmC;IACnC,kCAAkC;IAClC,+BAA+B;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;AAC3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;AACpE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;AAEpE,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAA;AAC/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAA;AAC3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAC5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAA;AAC7C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAA"}

package/dist/space/index.d.ts

@@ -8,6 +8,9 @@
  * - The shared collection ids and descriptive specs (`private-credentials`,
  *   `public-credentials`, `wallet-activity`). The contacts collections stay in
  *   `@interop/social-core`.
+ * - The system collections and resource names that carry identity and key
+ *   material (`id`, `key-map`, `keyring`; `did.json`, `did.jsonl`, `keys.json`,
+ *   `puk.json`, `keyring.json`) -- outside the synced set, never replicated.
  * - The `wallet-activity` wire shape (`WalletActivity`) and the pure
  *   `addHistory*` payload builders.
  * - `publicCredentialUrl`, the world-readable shared-credential URL both
@@ -16,6 +19,7 @@
  *   `parseWasLinkPayload` / `encodeWasLinkSecret`).
  */
 export { PRIVATE_CREDENTIALS_COLLECTION, PUBLIC_CREDENTIALS_COLLECTION, WALLET_ACTIVITY_COLLECTION, PRIVATE_CREDENTIALS_COLLECTION_SPEC, PUBLIC_CREDENTIALS_COLLECTION_SPEC, WALLET_ACTIVITY_COLLECTION_SPEC, WALLET_SPACE_COLLECTION_SPECS } from './collections.js';
+export { ID_COLLECTION, KEY_MAP_COLLECTION, KEYRING_COLLECTION, DID_DOCUMENT_RESOURCE, DID_LOG_RESOURCE, DID_KEYS_RESOURCE, PUK_ROSTER_RESOURCE, KEYRING_RESOURCE } from './collections.js';
 export type { SpaceCollectionSpec } from './collections.js';
 export { ACTIVITY_TYPE, addHistoryNewAccount, addHistorySpaceCreated, addHistoryCredentialCreated, addHistoryCredentialDeleted, addHistoryCredentialShared, addHistoryCredentialUnshared, addHistoryLogin, addHistoryAppRevoke } from './activity.js';
 export type { WalletActivity, ActivityGrant } from './activity.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/space/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,mCAAmC,EACnC,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/space/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,mCAAmC,EACnC,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/space/index.js

@@ -8,6 +8,9 @@
  * - The shared collection ids and descriptive specs (`private-credentials`,
  *   `public-credentials`, `wallet-activity`). The contacts collections stay in
  *   `@interop/social-core`.
+ * - The system collections and resource names that carry identity and key
+ *   material (`id`, `key-map`, `keyring`; `did.json`, `did.jsonl`, `keys.json`,
+ *   `puk.json`, `keyring.json`) -- outside the synced set, never replicated.
  * - The `wallet-activity` wire shape (`WalletActivity`) and the pure
  *   `addHistory*` payload builders.
  * - `publicCredentialUrl`, the world-readable shared-credential URL both
@@ -16,6 +19,7 @@
  *   `parseWasLinkPayload` / `encodeWasLinkSecret`).
  */
 export { PRIVATE_CREDENTIALS_COLLECTION, PUBLIC_CREDENTIALS_COLLECTION, WALLET_ACTIVITY_COLLECTION, PRIVATE_CREDENTIALS_COLLECTION_SPEC, PUBLIC_CREDENTIALS_COLLECTION_SPEC, WALLET_ACTIVITY_COLLECTION_SPEC, WALLET_SPACE_COLLECTION_SPECS } from './collections.js';
+export { ID_COLLECTION, KEY_MAP_COLLECTION, KEYRING_COLLECTION, DID_DOCUMENT_RESOURCE, DID_LOG_RESOURCE, DID_KEYS_RESOURCE, PUK_ROSTER_RESOURCE, KEYRING_RESOURCE } from './collections.js';
 export { ACTIVITY_TYPE, addHistoryNewAccount, addHistorySpaceCreated, addHistoryCredentialCreated, addHistoryCredentialDeleted, addHistoryCredentialShared, addHistoryCredentialUnshared, addHistoryLogin, addHistoryAppRevoke } from './activity.js';
 export { publicCredentialUrl } from './publicLink.js';
 export { encodeWasLinkSecret, buildWasLinkPayload, parseWasLinkPayload } from './wasLink.js';

package/dist/space/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/space/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,mCAAmC,EACnC,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/space/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,mCAAmC,EACnC,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/webvh/didWeb.d.ts

@@ -0,0 +1,41 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The did:web relationship map the did:webvh module round-trips: the durable
+ * `keys.json` binding from DID relationship to KMS key, plus the fragment
+ * helper both documents' verification-method ids are read through. A KMS key's
+ * public alias expands `{publicKeyMultibase}` at generate time, so a
+ * verification-method id already carries the key's `publicKeyMultibase` and no
+ * separate key-description fetch is ever needed.
+ */
+/**
+ * One verification method's durable binding: the verification-method id (the
+ * did:web `#fragment` URL, which is also the KMS key's publicAlias) and the
+ * KMS key id used to invoke signing.
+ */
+export interface DidWebKey {
+    vmId: string;
+    kmsKeyId: string;
+}
+/**
+ * The key-id map persisted as `keys.json` in the private `key-map` collection:
+ * the durable mapping from DID relationship to KMS key, since the KMS protocol
+ * has no list-keys endpoint and key ids are server-generated.
+ */
+export interface DidWebKeyMap {
+    authentication: DidWebKey;
+    assertionMethod: DidWebKey;
+    keyAgreement: DidWebKey;
+}
+/**
+ * The bare `publicKeyMultibase` a KMS key alias or verification-method id
+ * carries in its fragment. The KMS expanded `#{publicKeyMultibase}` at generate
+ * time, so the fragment IS the multibase key (no separate key-description fetch
+ * needed).
+ *
+ * @param id {string}
+ * @returns {string}
+ */
+export declare function multibaseOf(id: string): string;
+//# sourceMappingURL=didWeb.d.ts.map

package/dist/webvh/didWeb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"didWeb.d.ts","sourceRoot":"","sources":["../../src/webvh/didWeb.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,SAAS,CAAA;IACzB,eAAe,EAAE,SAAS,CAAA;IAC1B,YAAY,EAAE,SAAS,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/webvh/didWeb.js

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The did:web relationship map the did:webvh module round-trips: the durable
+ * `keys.json` binding from DID relationship to KMS key, plus the fragment
+ * helper both documents' verification-method ids are read through. A KMS key's
+ * public alias expands `{publicKeyMultibase}` at generate time, so a
+ * verification-method id already carries the key's `publicKeyMultibase` and no
+ * separate key-description fetch is ever needed.
+ */
+/**
+ * The bare `publicKeyMultibase` a KMS key alias or verification-method id
+ * carries in its fragment. The KMS expanded `#{publicKeyMultibase}` at generate
+ * time, so the fragment IS the multibase key (no separate key-description fetch
+ * needed).
+ *
+ * @param id {string}
+ * @returns {string}
+ */
+export function multibaseOf(id) {
+    return id.slice(id.lastIndexOf('#') + 1);
+}
+//# sourceMappingURL=didWeb.js.map

package/dist/webvh/didWeb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"didWeb.js","sourceRoot":"","sources":["../../src/webvh/didWeb.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;GAOG;AAuBH;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;AAC1C,CAAC"}

package/dist/webvh/didWebvh.d.ts

@@ -0,0 +1,251 @@
+import type { KeystoreAgent } from '@interop/webkms-client';
+import type { DidWebKeyMap } from './didWeb.js';
+/**
+ * The Space-side seam this module reads and writes through: the world-readable
+ * `id` collection (the DID log and document) and the private `key-map`
+ * collection's `keys.json`. A wallet app's own remote-store class satisfies
+ * the shape structurally -- no adapter needed.
+ */
+export interface WebvhIdStore {
+    /**
+     * The raw text body of an `id` collection resource (the JSON-Lines log), or
+     * `undefined` when it is not published.
+     */
+    getIdResourceRaw(options: {
+        resourceId: string;
+    }): Promise<string | undefined>;
+    /**
+     * The parsed JSON body of an `id` collection resource (the DID document), or
+     * `undefined` when it is not published.
+     */
+    getIdResource(options: {
+        resourceId: string;
+    }): Promise<unknown>;
+    /**
+     * Writes (upserts) an `id` collection resource.
+     */
+    putIdResource(options: {
+        resourceId: string;
+        content: object | string;
+        contentType?: string;
+    }): Promise<void>;
+    /**
+     * Writes (upserts) `keys.json` in the private `key-map` collection.
+     */
+    putKeyMap(options: {
+        content: object;
+    }): Promise<void>;
+}
+/**
+ * The client-held did:webvh update-key material: 32-byte Ed25519 seeds.
+ * `pendingStagedSeed` is present only mid-rotation (minted and persisted
+ * before the log entry publishes, promoted to `stagedSeed` after).
+ */
+export interface ClientWebvhUpdateKeys {
+    updateSeed: Uint8Array;
+    stagedSeed: Uint8Array;
+    pendingStagedSeed?: Uint8Array;
+}
+/**
+ * The public halves of one enrolled client's key set, as they appear in the
+ * document: the Ed25519 signing key (`z6Mk...`) and its X25519 key-agreement
+ * twin (`z6LS...`).
+ */
+export interface WebvhClientKeys {
+    signingKeyMultibase: string;
+    keyAgreementKeyMultibase: string;
+}
+/**
+ * The `webvh` block added to `keys.json` v2, a sibling of the did:web
+ * relationship map. Absent block = a record written before did:webvh hosting;
+ * everything degrades to did:web behavior, no format-version bump (additive
+ * convention). It carries only the published DID: the update keys are
+ * client-held seeds, never recorded in a Space-hosted resource.
+ */
+export interface DidWebvhBlock {
+    did?: string;
+}
+/**
+ * `keys.json` v2: the did:web key map plus the optional `webvh` block. The
+ * did:web parse/guard tolerates and preserves the block, so a round-trip
+ * through the did:web provisioning never strips it.
+ */
+export type DidWebKeyMapV2 = DidWebKeyMap & {
+    webvh?: DidWebvhBlock;
+};
+/**
+ * The `did:webvh:{SCID}:<host>:space:<spaceId>:id` controller template, with
+ * the literal `{SCID}` placeholder the library replaces at creation. The host
+ * segment percent-encodes a port (`localhost:8080` becomes `localhost%3A8080`),
+ * matching the library's `toDidDomainComponent`.
+ *
+ * @param options {object}
+ * @param options.wasServerUrl {string}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export declare function didWebvhControllerTemplate({ wasServerUrl, spaceId }: {
+    wasServerUrl: string;
+    spaceId: string;
+}): string;
+/**
+ * Mints a fresh pair of client-held update-key seeds (active + staged) for a
+ * brand-new did:webvh log. The caller owns persistence: these seeds are the
+ * only update authority the log will ever accept, so they must be durable
+ * before {@link ensureDidWebvh} publishes anything.
+ *
+ * @returns {Promise<ClientWebvhUpdateKeys>}
+ */
+export declare function mintClientWebvhUpdateKeys(): Promise<ClientWebvhUpdateKeys>;
+/**
+ * The `publicKeyMultibase` of the Ed25519 update key a seed derives, as it
+ * appears in the log's `parameters.updateKeys`.
+ *
+ * @param options {object}
+ * @param options.seed {Uint8Array}   a 32-byte Ed25519 seed
+ * @returns {Promise<string>}
+ */
+export declare function updateKeyMultibase({ seed }: {
+    seed: Uint8Array;
+}): Promise<string>;
+/**
+ * Idempotently provisions and publishes the user's did:webvh DID log, run
+ * directly after the did:web provisioning (non-fatal). The durable anchor is
+ * the caller-persisted update-key seeds, so the flow is a simple probe:
+ *
+ * - `did.jsonl` published: sanity-check that the log's authorized `updateKeys`
+ *   still name one of this client's seeds (active, staged, or pending -- a
+ *   rotation in flight finalizes separately), adopt the resolved DID, and
+ *   write the `keys.json` webvh block if it is missing or stale.
+ * - `did.jsonl` absent: create the log with the active update key, prerotation
+ *   committed to the staged key, publish log + `did.json`, then record the DID
+ *   in `keys.json`.
+ *
+ * A published log whose `updateKeys` match none of the seeds is fatal: with
+ * client-held update keys a lost seed is lost update authority, and no KMS
+ * repair path exists by design.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.wasServerUrl {string}
+ * @param options.spaceId {string}
+ * @param options.didWebKeys {DidWebKeyMapV2}   the parsed keys.json (with any
+ *   webvh block) returned by the did:web provisioning.
+ * @param options.clientKeys {WebvhClientKeys}   this client's published keys
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   already durably persisted
+ * @returns {Promise<{ did: string }>}
+ */
+export declare function ensureDidWebvh({ idStore, wasServerUrl, spaceId, didWebKeys, clientKeys, updateKeys }: {
+    idStore: WebvhIdStore;
+    wasServerUrl: string;
+    spaceId: string;
+    didWebKeys: DidWebKeyMapV2;
+    clientKeys: WebvhClientKeys;
+    updateKeys: ClientWebvhUpdateKeys;
+}): Promise<{
+    did: string;
+}>;
+/**
+ * Rotates this client's did:webvh update key (the user-triggered ceremony on
+ * the wallet's settings screen). The staged key is revealed to sign its own
+ * activation and become the sole active update key, a freshly minted staged
+ * key is committed as the new `nextKeyHashes`, and the caller's persisted
+ * seeds roll forward. No KMS and no `keys.json` involvement: the update keys
+ * are client-held, and the published DID does not change.
+ *
+ * The persist-before-publish invariant is load-bearing: the new staged seed is
+ * handed to `persistUpdateKeys` (as `pendingStagedSeed`) and awaited BEFORE the
+ * log entry committing it is published, so no published log can ever depend on
+ * a seed that is not durable. A crash between publish and finalize is
+ * recovered on the next run: the log already sits at the staged (or pending)
+ * key, and the seeds are simply rolled forward locally without touching it.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   the current seeds
+ * @param options.persistUpdateKeys {Function}   awaited before every publish
+ *   that changes the log's authorized update keys
+ * @returns {Promise<{ did: string }>}
+ */
+export declare function rotateWebvhUpdateKey({ idStore, updateKeys, persistUpdateKeys }: {
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    persistUpdateKeys: (next: ClientWebvhUpdateKeys) => Promise<void>;
+}): Promise<{
+    did: string;
+}>;
+/**
+ * The public halves of a client being enrolled: its published key set (the
+ * Ed25519 signing key and X25519 key-agreement twin that become document
+ * verification methods) plus its update-key pair -- the active key that joins
+ * `updateKeys` and the staged key whose hash is committed so the new client
+ * can later self-rotate. All four are `publicKeyMultibase` strings; the seeds
+ * behind them never leave the client being enrolled.
+ */
+export interface WebvhEnrollmentKeys extends WebvhClientKeys {
+    updateKeyMultibase: string;
+    stagedUpdateKeyMultibase: string;
+}
+/**
+ * Enrolls a second wallet client into the published did:webvh document -- the
+ * log half of the enrollment ceremony (the PUK roster wrap happens first,
+ * outside this module). Two entries, forced by prerotation (a new update key
+ * must hash into the PREVIOUS entry's `nextKeyHashes`):
+ *
+ * 1. **Commit**: a sparse entry extending `nextKeyHashes` with the new
+ *    client's update-key and staged-key hashes (document and `updateKeys`
+ *    untouched).
+ * 2. **Add**: an entry adding the new client's verification methods (its
+ *    Ed25519 key under the four signing relationships, its X25519 twin under
+ *    `keyAgreement`) and its update key to `updateKeys`.
+ *
+ * Both entries are signed by THIS client's active update key (quorum-of-one:
+ * any single enrolled client can enroll). The ceremony is resumable from
+ * durable state alone: a tear after the commit is detected by its hashes
+ * already standing in `nextKeyHashes` (skip to the add entry), and a
+ * completed enrollment is detected by the update key already being authorized
+ * (no-op). Re-running with the same key set converges without forking the
+ * log.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   THIS client's seeds
+ * @param options.newClient {WebvhEnrollmentKeys}   the enrollee's public halves
+ * @returns {Promise<{ did: string }>}
+ */
+export declare function enrollWebvhClient({ idStore, updateKeys, newClient }: {
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    newClient: WebvhEnrollmentKeys;
+}): Promise<{
+    did: string;
+}>;
+/**
+ * Rebuilds `keys.json` from the published artifacts plus a WebKMS key listing
+ * -- the recovery path for a lost or rolled-back `keys.json`. List Keys is
+ * authorized as `read` against the keystore controller, which only the
+ * root-controlled keystore agent can invoke.
+ *
+ * KMS key local ids are server-generated random and appear in no published
+ * artifact, so the bindings are rediscovered by public key material instead.
+ * List the keystore once -- each listed description carries `keyUrl`, the
+ * key's canonical invocation URL (the signable handle its alias-overridden
+ * `id` erases) -- then match `did.json`'s three relationship verification
+ * methods by `publicKeyMultibase` and rewrite `keys.json` from what matched.
+ * When `did.jsonl` is published, its resolved DID is recorded in the `webvh`
+ * block; there is nothing else to repair there, since the log's update keys are
+ * client-held seeds that no keystore listing could recover.
+ *
+ * An unmatchable binding is unrepairable and throws: a published artifact
+ * depends on a key the keystore no longer lists.
+ *
+ * @param options {object}
+ * @param options.keystoreAgent {KeystoreAgent}
+ * @param options.idStore {WebvhIdStore}
+ * @returns {Promise<DidWebKeyMapV2>}   the rebuilt, persisted keys.json
+ */
+export declare function repairKeyBindings({ keystoreAgent, idStore }: {
+    keystoreAgent: KeystoreAgent;
+    idStore: WebvhIdStore;
+}): Promise<DidWebKeyMapV2>;
+//# sourceMappingURL=didWebvh.d.ts.map

package/dist/webvh/didWebvh.d.ts.map

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