@interop/wallet-core 0.5.0 → 0.7.0

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,330 @@
+import type { DIDDoc, DIDLog, Signer } from '@interop/did-method-webvh';
+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 Multikey verification-method type the did:webvh data model uses for both
+ * the Ed25519 (authentication/assertionMethod/capability*) and X25519
+ * (keyAgreement) keys. The same key material and multibase are carried as by
+ * the 2020 suite types, only `type` and `@context` change, and credential
+ * verifiers verify `Ed25519Signature2020` / `eddsa-rdfc-2022` proofs against
+ * it.
+ */
+export declare const MULTIKEY_VM_TYPE = "Multikey";
+/**
+ * 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>;
+/**
+ * Bridges a client-held update-key seed to the did:webvh `Signer` interface via
+ * the library's `signerFromExternalKey`. The only wallet-side seam is the shape
+ * adapter: the key pair's `signer().sign({ data })` matches the factory's
+ * `sign({ data })` bridge exactly, so the proof-value multibase encoding and
+ * the load-bearing `did:key:<pkm>#<pkm>` verification-method id (which the
+ * resolver matches against the entry's authorized `updateKeys`) are owned by
+ * the library, not duplicated here.
+ *
+ * @param options {object}
+ * @param options.seed {Uint8Array}   the 32-byte update-key seed
+ * @returns {Promise<Signer>}
+ */
+export declare function updateKeySigner({ seed }: {
+    seed: Uint8Array;
+}): Promise<Signer>;
+/**
+ * Publishes an already-created log: PUT `did.jsonl` (`text/jsonl`) then PUT
+ * `did.json` from `webDoc` (`application/did+json`, adopting the webvh
+ * projection). Both land in the `id` collection, whose collection-level
+ * `PublicCanRead` policy (set at provisioning) makes them world-readable, so
+ * the publish tail no longer sets per-resource policies. The shared publish
+ * tail of the create and rotate paths.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.log {DIDLog}
+ * @param options.webDoc {object}
+ * @returns {Promise<void>}
+ */
+export declare function publishWebvhLog({ idStore, log, webDoc }: {
+    idStore: WebvhIdStore;
+    log: DIDLog;
+    webDoc: object;
+}): Promise<void>;
+/**
+ * The verified state of the published log: the log itself, the resolved DID
+ * and document, and the effective update-key parameters (the authorized
+ * `updateKeys` and the standing `nextKeyHashes` commitments).
+ */
+export interface PublishedWebvhLog {
+    log: DIDLog;
+    did: string;
+    doc: DIDDoc;
+    updateKeys: string[];
+    nextKeyHashes: string[];
+}
+/**
+ * Reads and resolves the published `did.jsonl`, or returns `undefined` when
+ * the log is not published. A log that exists but fails to resolve throws --
+ * a published-but-broken log is never silently re-created over.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @returns {Promise<PublishedWebvhLog | undefined>}
+ */
+export declare function readPublishedLog({ idStore }: {
+    idStore: WebvhIdStore;
+}): Promise<PublishedWebvhLog | undefined>;
+/**
+ * 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;
+}
+/**
+ * The relationship references of a resolved document as verification-method
+ * ids, tolerating embedded objects beside string references.
+ *
+ * @param relation {Array}   the relationship array, when present
+ * @returns {string[]}
+ */
+export declare function relationIds(relation: Array<string | {
+    id?: string;
+}> | undefined): 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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"}