@interop/did-cli 0.9.0 → 0.10.1

package/dist/commands/did/service.js

@@ -0,0 +1,324 @@
+/**
+ * Service-entry management for did:web and did:webvh DIDs. Builds and edits the
+ * `service` array (add/remove by id, with id normalization) and routes a
+ * service-array transform to the right per-method runner: did:web is a direct
+ * document edit, did:webvh appends a sparse log entry (advancing the
+ * pre-rotation ratchet when one is armed). The webvh log machinery is reused
+ * from `./webvh-update.js`.
+ */
+import { updateDID } from '@interop/did-method-webvh';
+import { loadDidDocument, saveDidLog, saveToDids } from '../../storage.js';
+import { resolveDidRef } from '../../meta.js';
+import { webvhLogVerifier } from '../../documentLoader.js';
+import { generateStagedKey } from '../../keys/webvh-update.js';
+import { confirmAction, loadActiveSigner, loadStoredUpdateKeys, makeWebvhEntrySigner, persistUpdateKeysSidecar, resolveWebvhForUpdate, revealStagedSigner } from './webvh-update.js';
+/**
+ * Expand a service id to a full DID URL. A bare fragment (`files`) or a
+ * leading-`#` fragment (`#files`) is resolved against the DID; a value that is
+ * already a full DID URL, or any absolute URI carrying a fragment, is returned
+ * unchanged.
+ *
+ * @param options {object}
+ * @param options.did {string}
+ * @param options.id {string}
+ * @returns {string}
+ */
+export function normalizeServiceId({ did, id }) {
+    if (id.startsWith('#')) {
+        return `${did}${id}`;
+    }
+    if (id.startsWith('did:') || id.includes('#')) {
+        return id;
+    }
+    return `${did}#${id}`;
+}
+/**
+ * Build a service-endpoint entry from add-service options. Exactly one of
+ * `endpoint` (one or more endpoint values -- a single value stays a string,
+ * several become an array) or `endpointJson` (a raw JSON value) supplies the
+ * serviceEndpoint; a single `type` likewise stays a string.
+ *
+ * @param options {object}
+ * @param options.did {string}
+ * @param options.id {string}
+ * @param options.type {string[]}
+ * @param [options.endpoint] {string[]}
+ * @param [options.endpointJson] {string}
+ * @returns {ServiceEndpoint}
+ */
+export function buildServiceEntry({ did, id, type, endpoint, endpointJson }) {
+    const hasEndpoint = Boolean(endpoint?.length);
+    const hasEndpointJson = Boolean(endpointJson);
+    // True when both are supplied or neither is -- i.e. not exactly one.
+    if (hasEndpoint === hasEndpointJson) {
+        throw new Error('Provide exactly one of --endpoint or --endpoint-json.');
+    }
+    let serviceEndpoint;
+    if (endpointJson) {
+        try {
+            serviceEndpoint = JSON.parse(endpointJson);
+        }
+        catch {
+            throw new Error('--endpoint-json must be valid JSON.');
+        }
+    }
+    else {
+        serviceEndpoint = endpoint.length === 1 ? endpoint[0] : endpoint;
+    }
+    return {
+        id: normalizeServiceId({ did, id }),
+        type: type.length === 1 ? type[0] : type,
+        serviceEndpoint
+    };
+}
+/**
+ * Whether a stored service entry has the given (already-normalized, absolute)
+ * id. Service ids in a DID document may be relative (`#files`) or absolute, so
+ * the stored id is normalized against the DID before comparing.
+ *
+ * @param options {object}
+ * @param options.service {ServiceEndpoint}
+ * @param options.id {string} the normalized id to match.
+ * @param options.did {string}
+ * @returns {boolean}
+ */
+function serviceHasId({ service, id, did }) {
+    return (service.id !== undefined &&
+        normalizeServiceId({ did, id: service.id }) === id);
+}
+/**
+ * Append a service entry to the current array, rejecting a duplicate id.
+ *
+ * @param options {object}
+ * @param options.current {ServiceEndpoint[]}
+ * @param options.entry {ServiceEndpoint} its `id` is already normalized.
+ * @param options.did {string}
+ * @returns {ServiceEndpoint[]}
+ */
+export function addServiceEntry({ current, entry, did }) {
+    if (current.some(service => serviceHasId({ service, id: entry.id, did }))) {
+        throw new Error(`A service with id "${entry.id}" already exists.`);
+    }
+    return [...current, entry];
+}
+/**
+ * Remove the service entry with the given (normalized) id, rejecting a missing
+ * id.
+ *
+ * @param options {object}
+ * @param options.current {ServiceEndpoint[]}
+ * @param options.id {string} the normalized id to remove.
+ * @param options.did {string}
+ * @returns {ServiceEndpoint[]}
+ */
+export function removeServiceEntry({ current, id, did }) {
+    const next = current.filter(service => !serviceHasId({ service, id, did }));
+    if (next.length === current.length) {
+        throw new Error(`No service with id "${id}" found on the DID document.`);
+    }
+    return next;
+}
+/**
+ * Apply a service-array transform to a locally stored did:web document and
+ * re-save it. did:web has no history log, so this is a direct document edit;
+ * the `service` property is dropped entirely when the array empties out.
+ *
+ * @param options {object}
+ * @param options.did {string}
+ * @param options.transform {(current: ServiceEndpoint[], did: string) => ServiceEndpoint[]}
+ * @returns {Promise<number>} the process exit code
+ */
+async function runWebServiceUpdate({ did, transform }) {
+    let didDocument;
+    try {
+        didDocument = await loadDidDocument(did);
+    }
+    catch {
+        console.error(`No locally stored did:web found for ${did}`);
+        return 1;
+    }
+    const current = Array.isArray(didDocument.service)
+        ? didDocument.service
+        : [];
+    let next;
+    try {
+        next = transform(current, did);
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    if (next.length > 0) {
+        didDocument.service = next;
+    }
+    else {
+        delete didDocument.service;
+    }
+    const docPath = await saveToDids({ method: 'web', did, data: didDocument });
+    console.error(`DID saved to ${docPath}`);
+    console.log(JSON.stringify({ id: didDocument.id, didDocument }, null, 2));
+    return 0;
+}
+/**
+ * Apply a service-array transform to a locally stored did:webvh DID by
+ * appending a sparse log entry that overlays only the `service` array. Update
+ * keys and document verification methods are carried forward unchanged -- with
+ * one exception: a pre-rotation-armed DID cannot author a key-neutral update
+ * (the library requires the staged key to sign), so the update-key ratchet is
+ * advanced as part of the change -- the staged key is revealed to sign and a
+ * fresh next key is staged.
+ *
+ * @param options {object}
+ * @param options.targetDid {string} the resolved did:webvh DID.
+ * @param options.transform {(current: ServiceEndpoint[], did: string) => ServiceEndpoint[]}
+ * @param [options.yes] {boolean} skip the confirmation prompt.
+ * @param [options.keepOldKey] {boolean} retain the retired update key secret
+ *   (pre-rotation path only; default is to drop it).
+ * @returns {Promise<number>} the process exit code
+ */
+async function runWebvhServiceUpdate({ targetDid, transform, yes, keepOldKey }) {
+    let log;
+    let doc;
+    let meta;
+    try {
+        ;
+        ({ log, doc, meta } = await resolveWebvhForUpdate({
+            targetDid,
+            action: 'update services'
+        }));
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    // Compute the new service array from the current resolved document.
+    const current = Array.isArray(doc?.service) ? doc.service : [];
+    let services;
+    try {
+        services = transform(current, targetDid);
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    const stored = await loadStoredUpdateKeys(targetDid);
+    // Choose the signer and key parameters. A sparse update normally omits
+    // updateKeys/nextKeyHashes so the keys carry forward untouched; a
+    // pre-rotation DID instead must reveal its staged key (which signs) and stage
+    // a fresh one in the same entry.
+    let signerKeyPair;
+    let updateKeys;
+    let nextKeyHashes;
+    let newActive;
+    let newStaged;
+    let retiredActive;
+    try {
+        if (meta.prerotation) {
+            ;
+            ({ signerKeyPair, newActive, retiredActive } = await revealStagedSigner({
+                stored,
+                meta,
+                targetDid,
+                action: 'update services'
+            }));
+            newStaged = await generateStagedKey();
+            updateKeys = [newActive.publicKeyMultibase];
+            nextKeyHashes = [newStaged.nextKeyHash];
+        }
+        else {
+            ;
+            ({ signerKeyPair } = await loadActiveSigner({
+                stored,
+                meta,
+                targetDid,
+                action: 'update services'
+            }));
+        }
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    const confirmed = await confirmAction({
+        message: `Update the services of ${targetDid}? This appends a new log entry ` +
+            'and is hard to undo.',
+        yes
+    });
+    if (!confirmed) {
+        console.error('Aborted.');
+        return 0;
+    }
+    const signer = makeWebvhEntrySigner(signerKeyPair);
+    let result;
+    try {
+        result = await updateDID({
+            log,
+            signer,
+            verifier: webvhLogVerifier,
+            services,
+            ...(updateKeys ? { updateKeys } : {}),
+            ...(nextKeyHashes ? { nextKeyHashes } : {})
+        });
+    }
+    catch (err) {
+        console.error(`Service update failed: ${err.message}`);
+        return 1;
+    }
+    const logPath = await saveDidLog({ did: result.did, log: result.log });
+    const docPath = await saveToDids({
+        method: 'webvh',
+        did: result.did,
+        data: result.doc
+    });
+    // Persist the advanced ratchet only on the pre-rotation path; an ordinary
+    // service update leaves the update-keys sidecar untouched.
+    if (meta.prerotation && newActive) {
+        const updateKeysPath = await persistUpdateKeysSidecar({
+            did: result.did,
+            newActive,
+            newStaged,
+            retiredActive,
+            stored,
+            keepOldKey
+        });
+        console.error(`Update keys saved to ${updateKeysPath}`);
+        console.error('Pre-rotation: the update key was advanced as part of this change.');
+    }
+    console.error(`DID document saved to ${docPath}`);
+    console.error(`DID history log saved to ${logPath}`);
+    console.log(JSON.stringify({ id: result.did, didDocument: result.doc }, null, 2));
+    return 0;
+}
+/**
+ * Resolve a DID reference, then route a service-array transform to the right
+ * per-method runner and return its exit code. did:web is a direct document
+ * edit; did:webvh appends a log entry.
+ *
+ * @param options {object}
+ * @param options.ref {string} a DID or a local metadata handle.
+ * @param options.transform {(current: ServiceEndpoint[], did: string) => ServiceEndpoint[]}
+ * @param [options.yes] {boolean} skip the did:webvh confirmation prompt.
+ * @param [options.keepOldKey] {boolean} did:webvh pre-rotation path only.
+ * @returns {Promise<number>} the process exit code
+ */
+export async function dispatchServiceUpdate({ ref, transform, yes, keepOldKey }) {
+    let resolved;
+    try {
+        resolved = await resolveDidRef({ ref });
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+    const did = resolved ?? ref;
+    if (did.startsWith('did:web:')) {
+        return runWebServiceUpdate({ did, transform });
+    }
+    if (did.startsWith('did:webvh:')) {
+        return runWebvhServiceUpdate({ targetDid: did, transform, yes, keepOldKey });
+    }
+    console.error('add-service/remove-service are only supported for did:web and ' +
+        'did:webvh DIDs');
+    return 1;
+}
+//# sourceMappingURL=service.js.map

package/dist/commands/did/service.js.map

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

package/dist/commands/did/webvh-update.d.ts

@@ -0,0 +1,170 @@
+import { resolveDIDFromLog, type DIDLog } from '@interop/did-method-webvh';
+import { Ed25519VerificationKey } from '@interop/ed25519-verification-key';
+import { type WebvhUpdateKey, type WebvhUpdateKeys } from '../../storage.js';
+/**
+ * Parse a raw did:webvh history log (newline-delimited JSON) into the entry
+ * array the library's resolver/updater expect, ignoring blank lines.
+ *
+ * @param logText {string}
+ * @returns {DIDLog}
+ */
+export declare function parseDidLog(logText: string): DIDLog;
+/**
+ * Ask the user to confirm a hard-to-undo action. Returns true immediately when
+ * `--yes` was passed or when stdin is not an interactive TTY (so scripts and
+ * tests are not blocked); otherwise prompts and requires an explicit `y`.
+ *
+ * @param options {object}
+ * @param options.message {string}
+ * @param options.yes {boolean} the value of the `--yes` flag.
+ * @returns {Promise<boolean>}
+ */
+export declare function confirmAction({ message, yes }: {
+    message: string;
+    yes?: boolean;
+}): Promise<boolean>;
+/**
+ * Load and resolve a locally stored did:webvh history log in preparation for an
+ * update, asserting it is updatable. The log is the source of truth for a
+ * stored did:webvh, so its absence is what "not locally stored" means.
+ *
+ * @param options {object}
+ * @param options.targetDid {string} the resolved did:webvh DID.
+ * @param options.action {string} verb used in error messages (e.g.
+ *   `rotate keys`, `update services`).
+ * @returns {Promise<{ log, doc, meta }>}
+ * @throws {Error} with a user-facing message if the log is missing, fails to
+ *   resolve, or the DID is deactivated.
+ */
+export declare function resolveWebvhForUpdate({ targetDid, action }: {
+    targetDid: string;
+    action: string;
+}): Promise<{
+    log: DIDLog;
+    doc: Awaited<ReturnType<typeof resolveDIDFromLog>>['doc'];
+    meta: Awaited<ReturnType<typeof resolveDIDFromLog>>['meta'];
+}>;
+/**
+ * Resolve a locally stored did:webvh DID from its history log (`.jsonl`) -- the
+ * source of truth for the current document and its accumulated parameters.
+ * Unlike `resolveWebvhForUpdate` this does not reject a deactivated DID, since
+ * `show` should still display it; it returns `undefined` when no log is stored
+ * so the caller can fall back to the stored document snapshot.
+ *
+ * @param did {string} the resolved did:webvh DID.
+ * @returns {Promise<{ doc, meta } | undefined>}
+ * @throws {Error} if a log exists but fails to resolve/verify.
+ */
+export declare function resolveStoredWebvh(did: string): Promise<{
+    doc: Awaited<ReturnType<typeof resolveDIDFromLog>>['doc'];
+    meta: Awaited<ReturnType<typeof resolveDIDFromLog>>['meta'];
+} | undefined>;
+/**
+ * Load a did:webvh DID's update-keys sidecar, treating an absent file as
+ * `undefined` (no stored secrets) rather than an error.
+ *
+ * @param did {string}
+ * @returns {Promise<WebvhUpdateKeys | undefined>}
+ */
+export declare function loadStoredUpdateKeys(did: string): Promise<WebvhUpdateKeys | undefined>;
+/**
+ * Pre-rotation reveal: validate and load the staged (pre-committed) update key
+ * that must sign this entry, returning the signer key pair plus the records
+ * that make it the new active key and retire the current one.
+ *
+ * @param options {object}
+ * @param options.stored {WebvhUpdateKeys | undefined} the update-keys sidecar.
+ * @param options.meta {Awaited<ReturnType<typeof resolveDIDFromLog>>['meta']}
+ * @param options.targetDid {string}
+ * @param options.action {string} verb used in error messages.
+ * @returns {Promise<{ signerKeyPair, newActive, retiredActive }>}
+ * @throws {Error} if the staged secret is missing or has diverged from the
+ *   log's committed nextKeyHashes.
+ */
+export declare function revealStagedSigner({ stored, meta, targetDid, action }: {
+    stored: WebvhUpdateKeys | undefined;
+    meta: Awaited<ReturnType<typeof resolveDIDFromLog>>['meta'];
+    targetDid: string;
+    action: string;
+}): Promise<{
+    signerKeyPair: Ed25519VerificationKey;
+    newActive: WebvhUpdateKey;
+    retiredActive: WebvhUpdateKey;
+}>;
+/**
+ * Ordinary (non-pre-rotation) signer: the current active update key signs.
+ * Returns the signer key pair and the active record it was loaded from.
+ *
+ * @param options {object}
+ * @param options.stored {WebvhUpdateKeys | undefined} the update-keys sidecar.
+ * @param options.meta {Awaited<ReturnType<typeof resolveDIDFromLog>>['meta']}
+ * @param options.targetDid {string}
+ * @param options.action {string} verb used in error messages.
+ * @returns {Promise<{ signerKeyPair, activeRecord }>}
+ * @throws {Error} if the active secret is missing or no longer matches the
+ *   log's updateKeys.
+ */
+export declare function loadActiveSigner({ stored, meta, targetDid, action }: {
+    stored: WebvhUpdateKeys | undefined;
+    meta: Awaited<ReturnType<typeof resolveDIDFromLog>>['meta'];
+    targetDid: string;
+    action: string;
+}): Promise<{
+    signerKeyPair: Ed25519VerificationKey;
+    activeRecord: WebvhUpdateKey;
+}>;
+/**
+ * Build the entry signer for a did:webvh update from an update key pair.
+ *
+ * @param keyPair {Ed25519VerificationKey} mutated: its `id` is set in place.
+ * @returns the signer to pass to `updateDID`.
+ */
+export declare function makeWebvhEntrySigner(keyPair: Ed25519VerificationKey): import("@interop/did-method-webvh").Signer<import("@interop/did-method-webvh").SignableDocument> & import("@interop/did-method-webvh").Verifier;
+/**
+ * Write the update-keys sidecar: the active key, the staged next key (or
+ * none), and any retired secrets. At creation there is no prior sidecar; after
+ * an advance/rotation the superseded active key is appended to `retired` only
+ * when `keepOldKey` asks to preserve it.
+ *
+ * @param options {object}
+ * @param options.did {string}
+ * @param options.newActive {WebvhUpdateKey}
+ * @param [options.newStaged] {WebvhUpdateKey & { nextKeyHash: string }}
+ * @param [options.retiredActive] {WebvhUpdateKey} the superseded active key.
+ * @param [options.stored] {WebvhUpdateKeys} the prior sidecar, if any.
+ * @param [options.keepOldKey] {boolean} retain the retired secret.
+ * @returns {Promise<string>} the saved sidecar path.
+ */
+export declare function persistUpdateKeysSidecar({ did, newActive, newStaged, retiredActive, stored, keepOldKey }: {
+    did: string;
+    newActive: WebvhUpdateKey;
+    newStaged?: WebvhUpdateKey & {
+        nextKeyHash: string;
+    };
+    retiredActive?: WebvhUpdateKey;
+    stored?: WebvhUpdateKeys;
+    keepOldKey?: boolean;
+}): Promise<string>;
+/**
+ * Rotate the update (authorization) key of a locally stored did:webvh DID. By
+ * default advances key pre-rotation -- reveals the staged next key and stages a
+ * fresh one -- and never touches the document verification methods.
+ *
+ * @param options {object}
+ * @param options.didRef {string}   The DID or metadata handle.
+ * @param [options.updateKey] {string[]}   Rotate to specific update key(s).
+ * @param [options.enablePrerotation] {boolean}   Turn pre-rotation on.
+ * @param [options.stopPrerotation] {boolean}   Turn pre-rotation off.
+ * @param [options.keepOldKey] {boolean}   Retain the retired update key secret.
+ * @param [options.yes] {boolean}   Skip the confirmation prompt.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export declare function runRotateKeys(options: {
+    didRef: string;
+    updateKey?: string[];
+    enablePrerotation?: boolean;
+    stopPrerotation?: boolean;
+    keepOldKey?: boolean;
+    yes?: boolean;
+}): Promise<number>;
+//# sourceMappingURL=webvh-update.d.ts.map

package/dist/commands/did/webvh-update.d.ts.map

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