@interop/did-cli 0.9.0 → 0.10.1

package/dist/commands/did.js

@@ -1,56 +1,19 @@
-import { Command } from 'commander';
-import { decodeSecretKeySeed, generateSecretKeySeed } from '@digitalcredentials/bnid';
-import { driver } from '@interop/did-method-key';
-import * as didWeb from '@interop/did-web-resolver';
-import { securityLoader } from '@interop/security-document-loader';
-import { Ed25519VerificationKey } from '@interop/ed25519-verification-key';
-import * as EcdsaMultikey from '@interop/ecdsa-multikey';
-import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
-import { listDids, loadDidDocument, loadDidKeys, loadDidMeta, removeDidFiles, saveDidMeta, saveToDids } from '../storage.js';
-import { recordKeyDidAssociation, removeKeyDidAssociation, resolveDidRef } from '../meta.js';
-import { renderTable } from '../table.js';
-import { normalizeEcdsaCurve, SUPPORTED_ECDSA_CURVES, warnIfNotVcIssuanceCapable } from '../keys/ecdsa.js';
 /**
- * Save the artifacts of a newly created DID: the DID document, its keys file,
- * a metadata sidecar (creation timestamp plus the handle and description when
- * given), and the key-to-DID association cache of any matching wallet keys.
- *
- * @param options {object}
- * @param options.method {string}
- * @param options.didDocument {object}
- * @param options.exportedKeys {object}
- * @param options.fingerprints {(string | undefined)[]}
- * @param [options.handle] {string}
- * @param [options.description] {string}
- * @returns {Promise<void>}
+ * `did` command wiring. Defines the commander surface (create, add-key,
+ * add-service, remove-service, get, show, list, meta, remove, and the webvh
+ * subcommand) and delegates each action to a `run*` function in the `did/`
+ * modules: create/add-key in `./did/create.js`, service edits in
+ * `./did/service.js`, read/manage operations in `./did/manage.js`, and the
+ * did:webvh update-key plumbing plus rotate-keys in `./did/webvh-update.js`.
  */
-async function saveDidArtifacts({ method, didDocument, exportedKeys, fingerprints, handle, description }) {
-    const did = didDocument.id;
-    const docPath = await saveToDids({ method, did, data: didDocument });
-    await saveToDids({ method, did, suffix: 'keys', data: exportedKeys });
-    const meta = { created: new Date().toISOString() };
-    if (handle) {
-        meta.handle = handle;
-    }
-    if (description) {
-        meta.description = description;
-    }
-    await saveDidMeta({ did, meta });
-    for (const fingerprint of fingerprints) {
-        if (fingerprint) {
-            await recordKeyDidAssociation({ publicKeyMultibase: fingerprint, did });
-        }
-    }
-    console.error(`DID saved to ${docPath}`);
-}
-/**
- * Document loader for DID / DID-URL resolution. A bare DID resolves to its DID
- * document; a `did#fragment` URL is dereferenced straight to its
- * verification-method node. Works for did:key (offline) and did:web (fetched).
- * Built once and reused. (Per project convention, DID/JSON-LD resolution goes
- * through `@interop/security-document-loader`, never a hand-rolled loader.)
- */
-const documentLoader = securityLoader().build();
+import { Command } from 'commander';
+import { SUPPORTED_ECDSA_CURVES } from '../keys/ecdsa.js';
+import { runAndExit } from './was/shared.js';
+import { DEFAULT_VERIFICATION_PURPOSES, runAddKey, runCreate } from './did/create.js';
+import { addServiceEntry, buildServiceEntry, dispatchServiceUpdate, normalizeServiceId, removeServiceEntry } from './did/service.js';
+import { runGet, runList, runMeta, runRemove, runShow } from './did/manage.js';
+import { runRotateKeys } from './did/webvh-update.js';
+export { parseDidLog } from './did/webvh-update.js';
 export function makeDidCommand() {
     const did = new Command('did').description('Manage DIDs');
     did
@@ -59,227 +22,24 @@ export function makeDidCommand() {
         .option('-t, --type <type>', 'key type (supported: ed25519, ecdsa)', 'ed25519')
         .option('--curve <curve>', `ECDSA curve for --type ecdsa (supported: ${SUPPORTED_ECDSA_CURVES})`, 'p256')
         .option('--url <url>', 'HTTPS url of the DID document (required for did:web)')
+        .option('--prerotation', 'arm did:webvh key pre-rotation: stage a next update key and commit ' +
+        'its hash (default)')
+        .option('--no-prerotation', 'create the did:webvh without key pre-rotation')
+        .option('--portable', 'create a portable did:webvh that can later be moved to a different ' +
+        'domain (default)')
+        .option('--no-portable', 'create a non-portable did:webvh (pinned to its domain)')
+        .option('--witness <did...>', 'declare a witness did:key DID authorized to co-sign did:webvh log ' +
+        'entries (repeatable; declaration only -- witness proof generation is ' +
+        'out of scope)')
+        .option('--witness-threshold <n>', 'number of did:webvh witness approvals required ' +
+        '(default: number of witnesses; requires --witness)')
+        .option('--watcher <url...>', 'declare a did:webvh watcher URL that monitors the DID log ' +
+        '(repeatable; https:// or http://localhost)')
         .option('--with-seed', 'include the secret key seed in output (generated if SECRET_KEY_SEED is not set)')
         .option('--save', 'save the DID document to local storage (~/.config/did-cli-wallet/dids/)')
         .option('--handle <handle>', 'short tag for the saved DID (requires --save)')
         .option('--description <description>', 'longer description of the saved DID (requires --save)')
-        .action(async (method = 'key', options) => {
-        if ((options.handle !== undefined || options.description !== undefined) &&
-            !options.save) {
-            console.error('--handle and --description require --save');
-            process.exit(1);
-            return;
-        }
-        switch (method) {
-            case 'key': {
-                switch (options.type) {
-                    case 'ed25519': {
-                        const envSeed = process.env.SECRET_KEY_SEED;
-                        const secretKeySeed = options.withSeed
-                            ? (envSeed ?? (await generateSecretKeySeed()))
-                            : envSeed;
-                        const seedBytes = secretKeySeed
-                            ? decodeSecretKeySeed({ secretKeySeed })
-                            : undefined;
-                        const keyPair = await Ed25519VerificationKey.generate({
-                            seed: seedBytes
-                        });
-                        const didDriver = driver();
-                        didDriver.use({ keyPairClass: Ed25519VerificationKey });
-                        const { didDocument } = await didDriver.fromKeyPair({
-                            verificationKeyPair: keyPair
-                        });
-                        if (options.save) {
-                            const exported = await keyPair.export({
-                                publicKey: true,
-                                secretKey: true
-                            });
-                            await saveDidArtifacts({
-                                method: 'key',
-                                didDocument,
-                                exportedKeys: exported,
-                                fingerprints: [
-                                    exported
-                                        .publicKeyMultibase
-                                ],
-                                handle: options.handle,
-                                description: options.description
-                            });
-                        }
-                        const output = { id: didDocument.id };
-                        if (options.withSeed) {
-                            output.secretKeySeed = secretKeySeed;
-                        }
-                        output.didDocument = didDocument;
-                        console.log(JSON.stringify(output, null, 2));
-                        break;
-                    }
-                    case 'ecdsa': {
-                        if (options.withSeed) {
-                            console.error('--with-seed is not supported for ecdsa keys; ECDSA key ' +
-                                'generation is non-deterministic and cannot be derived ' +
-                                'from a seed.');
-                            process.exit(1);
-                            return;
-                        }
-                        const curve = normalizeEcdsaCurve({ curve: options.curve });
-                        if (!curve) {
-                            console.error(`Unknown ecdsa curve: ${options.curve}. ` +
-                                `Supported: ${SUPPORTED_ECDSA_CURVES}`);
-                            process.exit(1);
-                            return;
-                        }
-                        warnIfNotVcIssuanceCapable({ curve });
-                        const keyPair = await EcdsaMultikey.generate({ curve });
-                        const didDriver = driver();
-                        const { didDocument } = await didDriver.fromKeyPair({
-                            verificationKeyPair: keyPair
-                        });
-                        if (options.save) {
-                            const exported = await keyPair.export({
-                                publicKey: true,
-                                secretKey: true
-                            });
-                            await saveDidArtifacts({
-                                method: 'key',
-                                didDocument,
-                                exportedKeys: exported,
-                                fingerprints: [
-                                    exported
-                                        .publicKeyMultibase
-                                ],
-                                handle: options.handle,
-                                description: options.description
-                            });
-                        }
-                        const output = { id: didDocument.id };
-                        output.didDocument = didDocument;
-                        console.log(JSON.stringify(output, null, 2));
-                        break;
-                    }
-                    default:
-                        console.error(`Unknown key type: ${options.type}. Supported: ed25519, ecdsa`);
-                        process.exit(1);
-                }
-                break;
-            }
-            case 'web': {
-                switch (options.type) {
-                    case 'ed25519': {
-                        if (!options.url) {
-                            console.error('did:web requires --url (e.g. --url https://example.com)');
-                            process.exit(1);
-                            return;
-                        }
-                        const envSeed = process.env.SECRET_KEY_SEED;
-                        const secretKeySeed = options.withSeed
-                            ? (envSeed ?? (await generateSecretKeySeed()))
-                            : envSeed;
-                        const seedBytes = secretKeySeed
-                            ? decodeSecretKeySeed({ secretKeySeed })
-                            : undefined;
-                        const didWebDriver = didWeb.driver();
-                        didWebDriver.use({ keyPairClass: Ed25519VerificationKey });
-                        const { didDocument, keyPairs } = await didWebDriver.generate({
-                            url: options.url,
-                            seed: seedBytes
-                        });
-                        if (options.save) {
-                            const exported = {};
-                            const fingerprints = [];
-                            for (const [methodId, keyPair] of keyPairs) {
-                                const exportedKey = (await keyPair.export({
-                                    publicKey: true,
-                                    secretKey: true
-                                }));
-                                exported[methodId] = exportedKey;
-                                fingerprints.push(exportedKey.publicKeyMultibase);
-                            }
-                            await saveDidArtifacts({
-                                method: 'web',
-                                didDocument,
-                                exportedKeys: exported,
-                                fingerprints,
-                                handle: options.handle,
-                                description: options.description
-                            });
-                        }
-                        const output = { id: didDocument.id };
-                        if (options.withSeed) {
-                            output.secretKeySeed = secretKeySeed;
-                        }
-                        output.didDocument = didDocument;
-                        console.log(JSON.stringify(output, null, 2));
-                        break;
-                    }
-                    case 'ecdsa': {
-                        if (!options.url) {
-                            console.error('did:web requires --url (e.g. --url https://example.com)');
-                            process.exit(1);
-                            return;
-                        }
-                        if (options.withSeed) {
-                            console.error('--with-seed is not supported for ecdsa keys; ECDSA key ' +
-                                'generation is non-deterministic and cannot be derived ' +
-                                'from a seed.');
-                            process.exit(1);
-                            return;
-                        }
-                        const curve = normalizeEcdsaCurve({ curve: options.curve });
-                        if (!curve) {
-                            console.error(`Unknown ecdsa curve: ${options.curve}. ` +
-                                `Supported: ${SUPPORTED_ECDSA_CURVES}`);
-                            process.exit(1);
-                            return;
-                        }
-                        warnIfNotVcIssuanceCapable({ curve });
-                        const keyPair = await EcdsaMultikey.generate({ curve });
-                        const didWebDriver = didWeb.driver();
-                        const { didDocument, keyPairs } = await didWebDriver.generate({
-                            url: options.url,
-                            verificationKeyPair: keyPair
-                        });
-                        if (options.save) {
-                            const exported = {};
-                            const fingerprints = [];
-                            for (const [methodId, savedKey] of keyPairs) {
-                                const exportedKey = (await savedKey.export({
-                                    publicKey: true,
-                                    secretKey: true
-                                }));
-                                exported[methodId] = exportedKey;
-                                fingerprints.push(exportedKey.publicKeyMultibase);
-                            }
-                            await saveDidArtifacts({
-                                method: 'web',
-                                didDocument,
-                                exportedKeys: exported,
-                                fingerprints,
-                                handle: options.handle,
-                                description: options.description
-                            });
-                        }
-                        const output = { id: didDocument.id };
-                        output.didDocument = didDocument;
-                        console.log(JSON.stringify(output, null, 2));
-                        break;
-                    }
-                    default:
-                        console.error(`Unknown key type: ${options.type}. ` +
-                            `Supported: ed25519, ecdsa`);
-                        process.exit(1);
-                }
-                break;
-            }
-            case 'webvh':
-                console.log(`Creating did:${method}...`);
-                // TODO: implement
-                break;
-            default:
-                console.error(`Unknown method: ${method}. Supported: key, web, webvh`);
-                process.exit(1);
-        }
-    });
+        .action((method = 'key', options) => runAndExit(runCreate({ method, ...options })));
     did
         .command('add-key <did>')
         .description('Add a verification key to an existing (locally stored) did:web')
@@ -287,367 +47,117 @@ export function makeDidCommand() {
         'into keyAgreement only', 'ed25519')
         .option('--curve <curve>', `ECDSA curve for --type ecdsa (supported: ${SUPPORTED_ECDSA_CURVES})`, 'p256')
         .option('--purpose <purpose...>', 'verification relationship(s) to wire the key into ' +
-        '(default: authentication, assertionMethod, capabilityDelegation, capabilityInvocation)')
+        `(default: ${DEFAULT_VERIFICATION_PURPOSES.join(', ')})`)
         .option('--with-seed', 'include the new secret key seed in output (generated if SECRET_KEY_SEED is not set)')
+        .action((did, options) => runAndExit(runAddKey({ did, ...options })));
+    did
+        .command('add-service <did>')
+        .description('Add a service entry to a locally stored did:web or did:webvh DID. The ' +
+        'DID may be given as a metadata handle. For did:webvh this appends a ' +
+        'log entry; if pre-rotation is armed the update key is advanced as ' +
+        'part of the change.')
+        .requiredOption('--id <id>', 'service id; a bare fragment (e.g. "files") is expanded to <did>#files')
+        .requiredOption('--type <type...>', 'service type(s), e.g. LinkedDomains (repeat for multiple)')
+        .option('--endpoint <endpoint...>', 'serviceEndpoint value(s); a single value stays a string, several ' +
+        'become an array (mutually exclusive with --endpoint-json)')
+        .option('--endpoint-json <json>', 'serviceEndpoint as a raw JSON value (mutually exclusive with --endpoint)')
+        .option('--keep-old-key', 'did:webvh pre-rotation only: retain the retired update key secret in ' +
+        'the sidecar (default: drop it)')
+        .option('-y, --yes', 'skip the did:webvh confirmation prompt')
         .action(async (did, options) => {
-        if (!did.startsWith('did:web:')) {
-            console.error('add-key is only supported for did:web DIDs');
-            process.exit(1);
-        }
-        if (options.type !== 'ed25519' &&
-            options.type !== 'ecdsa' &&
-            options.type !== 'x25519') {
-            console.error(`Unknown key type: ${options.type}. ` +
-                'Supported: ed25519, ecdsa, x25519');
-            process.exit(1);
-        }
-        // x25519 keys are key agreement keys; they can only be wired into the
-        // keyAgreement verification relationship.
-        let purposes = options.purpose;
-        if (options.type === 'x25519') {
-            if (purposes &&
-                purposes.some(purpose => purpose !== 'keyAgreement')) {
-                console.error('x25519 keys can only be added to the keyAgreement ' +
-                    'verification relationship');
-                process.exit(1);
-                return;
-            }
-            purposes = ['keyAgreement'];
-        }
-        let didDocument;
-        let exportedKeys;
-        try {
-            didDocument = await loadDidDocument(did);
-            exportedKeys = await loadDidKeys(did);
-        }
-        catch {
-            console.error(`No locally stored did:web found for ${did}`);
-            process.exit(1);
-        }
-        // ed25519 keys are derived from a seed; ecdsa and x25519 keys are
-        // generated non-deterministically and have no seed.
-        let secretKeySeed;
-        let keyPair;
-        const didWebDriver = didWeb.driver();
-        if (options.type === 'ed25519') {
-            const envSeed = process.env.SECRET_KEY_SEED;
-            secretKeySeed = options.withSeed
-                ? (envSeed ?? (await generateSecretKeySeed()))
-                : envSeed;
-            const seedBytes = secretKeySeed
-                ? decodeSecretKeySeed({ secretKeySeed })
-                : undefined;
-            keyPair = await Ed25519VerificationKey.generate({ seed: seedBytes });
-            didWebDriver.use({ keyPairClass: Ed25519VerificationKey });
-        }
-        else if (options.type === 'ecdsa') {
-            if (options.withSeed) {
-                console.error('--with-seed is not supported for ecdsa keys; ECDSA key ' +
-                    'generation is non-deterministic and cannot be derived ' +
-                    'from a seed.');
-                process.exit(1);
-                return;
-            }
-            const curve = normalizeEcdsaCurve({ curve: options.curve });
-            if (!curve) {
-                console.error(`Unknown ecdsa curve: ${options.curve}. ` +
-                    `Supported: ${SUPPORTED_ECDSA_CURVES}`);
-                process.exit(1);
-                return;
-            }
-            warnIfNotVcIssuanceCapable({ curve });
-            keyPair = await EcdsaMultikey.generate({ curve });
-        }
-        else {
-            if (options.withSeed) {
-                console.error('--with-seed is not supported for x25519 keys; X25519 key ' +
-                    'generation is non-deterministic and cannot be derived ' +
-                    'from a seed.');
-                process.exit(1);
-                return;
-            }
-            keyPair = await X25519KeyAgreementKey2020.generate();
-        }
-        const keyPairs = new Map();
-        try {
-            await didWebDriver.addVerificationMethod({
-                didDocument,
-                keyPairs,
-                keyPair,
-                purposes
+        const transform = (current, resolvedDid) => {
+            const entry = buildServiceEntry({
+                did: resolvedDid,
+                id: options.id,
+                type: options.type,
+                endpoint: options.endpoint,
+                endpointJson: options.endpointJson
             });
-        }
-        catch (err) {
-            console.error(err.message);
-            process.exit(1);
-        }
-        // Merge the new key into the stored keys file (keyed by VM id). X25519
-        // keys export their private half as `privateKeyMultibase`, the other
-        // suites as `secretKeyMultibase`.
-        const addedFingerprints = [];
-        for (const [methodId, addedKey] of keyPairs) {
-            const exportedKey = (await addedKey.export(options.type === 'x25519'
-                ? { publicKey: true, privateKey: true }
-                : { publicKey: true, secretKey: true }));
-            exportedKeys[methodId] = exportedKey;
-            addedFingerprints.push(exportedKey.publicKeyMultibase);
-        }
-        const docPath = await saveToDids({
-            method: 'web',
-            did,
-            data: didDocument
-        });
-        await saveToDids({
-            method: 'web',
-            did,
-            suffix: 'keys',
-            data: exportedKeys
+            return addServiceEntry({ current, entry, did: resolvedDid });
+        };
+        return runAndExit(dispatchServiceUpdate({
+            ref: did,
+            transform,
+            yes: options.yes,
+            keepOldKey: options.keepOldKey
+        }));
+    });
+    did
+        .command('remove-service <did>')
+        .description('Remove a service entry (by id) from a locally stored did:web or ' +
+        'did:webvh DID. The DID may be given as a metadata handle. For ' +
+        'did:webvh this appends a log entry; if pre-rotation is armed the ' +
+        'update key is advanced as part of the change.')
+        .requiredOption('--id <id>', 'id of the service to remove; a bare fragment (e.g. "files") is ' +
+        'expanded to <did>#files')
+        .option('--keep-old-key', 'did:webvh pre-rotation only: retain the retired update key secret in ' +
+        'the sidecar (default: drop it)')
+        .option('-y, --yes', 'skip the did:webvh confirmation prompt')
+        .action(async (did, options) => {
+        const transform = (current, resolvedDid) => removeServiceEntry({
+            current,
+            id: normalizeServiceId({ did: resolvedDid, id: options.id }),
+            did: resolvedDid
         });
-        // Update the key-to-DID cache of any matching wallet keys; the DID's
-        // own metadata sidecar is left untouched.
-        for (const fingerprint of addedFingerprints) {
-            if (fingerprint) {
-                await recordKeyDidAssociation({
-                    publicKeyMultibase: fingerprint,
-                    did
-                });
-            }
-        }
-        console.error(`DID saved to ${docPath}`);
-        const output = { id: didDocument.id };
-        if (options.withSeed) {
-            output.secretKeySeed = secretKeySeed;
-        }
-        output.didDocument = didDocument;
-        console.log(JSON.stringify(output, null, 2));
+        return runAndExit(dispatchServiceUpdate({
+            ref: did,
+            transform,
+            yes: options.yes,
+            keepOldKey: options.keepOldKey
+        }));
     });
     did
         .command('get <did>')
         .aliases(['resolve'])
         .description('Resolve a DID to its DID document, or a DID URL (a did#fragment key ' +
         'id) to its verification method, via the security document loader')
-        .action(async (didOrKeyId) => {
-        let document;
-        try {
-            ;
-            ({ document } = (await documentLoader(didOrKeyId)));
-        }
-        catch (err) {
-            console.error(`Could not resolve "${didOrKeyId}": ${err.message}`);
-            process.exit(1);
-            return;
-        }
-        console.log(JSON.stringify(document, null, 2));
-    });
+        .action((didOrKeyId) => runAndExit(runGet({ didOrKeyId })));
     did
         .command('show <did>')
         .aliases(['view', 'cat'])
         .description('Show a locally stored DID document (no secret key material) by DID ' +
-        'or handle')
+        'or handle. For did:webvh the document is resolved from its history ' +
+        'log -- the source of truth -- rather than the stored snapshot.')
         .option('--meta', 'show the DID metadata instead of the DID document')
         .option('--json', 'with --meta, output the metadata as JSON')
-        .action(async (didRef, options) => {
-        let did;
-        try {
-            did = await resolveDidRef({ ref: didRef });
-        }
-        catch (err) {
-            console.error(err.message);
-            process.exit(1);
-            return;
-        }
-        let didDocument;
-        try {
-            didDocument = await loadDidDocument(did ?? didRef);
-        }
-        catch {
-            console.error(`No locally stored DID found for ${didRef}`);
-            process.exit(1);
-            return;
-        }
-        if (options.meta) {
-            const docDid = didDocument.id;
-            const meta = await loadDidMeta({ did: docDid });
-            const keyCount = Array.isArray(didDocument.verificationMethod)
-                ? didDocument.verificationMethod.length
-                : 0;
-            if (options.json) {
-                const output = {
-                    did: docDid,
-                    method: docDid.split(':')[1],
-                    ...(meta?.created && { created: meta.created }),
-                    ...(meta?.handle && { handle: meta.handle }),
-                    ...(meta?.description && { description: meta.description }),
-                    keys: keyCount
-                };
-                console.log(JSON.stringify(output, null, 2));
-                return;
-            }
-            const rows = [
-                ['DID', docDid],
-                ['Method', docDid.split(':')[1]],
-                ['Handle', meta?.handle ?? ''],
-                ['Created', meta?.created ?? ''],
-                ['Description', meta?.description ?? ''],
-                ['Keys', String(keyCount)]
-            ];
-            console.log(renderTable({
-                columns: [{ header: 'FIELD' }, { header: 'VALUE' }],
-                rows
-            }));
-            return;
-        }
-        // The stored DID document holds no secret material -- signing keys live in
-        // the separate `<did>.keys.json` file -- so it is safe to print as-is.
-        console.log(JSON.stringify(didDocument, null, 2));
-    });
+        .action((didRef, options) => runAndExit(runShow({ didRef, ...options })));
     did
         .command('list')
         .description('List locally stored DIDs with their metadata')
         .option('--json', 'output the list as a JSON array of objects with metadata')
         .option('--plain', 'output one DID per line, sorted (no metadata)')
-        .action(async (options) => {
-        const dids = await listDids();
-        if (options.plain) {
-            for (const did of dids) {
-                console.log(did);
-            }
-            return;
-        }
-        const entries = [];
-        for (const did of dids) {
-            const meta = await loadDidMeta({ did });
-            entries.push({ did, method: did.split(':')[1], ...meta });
-        }
-        if (options.json) {
-            const output = entries.map(entry => ({
-                did: entry.did,
-                method: entry.method,
-                ...(entry.created && { created: entry.created }),
-                ...(entry.handle && { handle: entry.handle }),
-                ...(entry.description && { description: entry.description })
-            }));
-            console.log(JSON.stringify(output, null, 2));
-            return;
-        }
-        if (entries.length === 0) {
-            return;
-        }
-        const rows = entries.map(entry => [
-            entry.handle ?? '',
-            entry.method,
-            entry.created?.slice(0, 10) ?? '',
-            entry.did,
-            entry.description ?? ''
-        ]);
-        console.log(renderTable({
-            columns: [
-                { header: 'HANDLE', maxWidth: 16 },
-                { header: 'METHOD' },
-                { header: 'CREATED' },
-                { header: 'DID', maxWidth: 44 },
-                { header: 'DESCRIPTION', maxWidth: 40 }
-            ],
-            rows
-        }));
-    });
+        .action((options) => runAndExit(runList(options)));
     did
         .command('meta <did>')
         .description('Show or edit the metadata of a locally stored DID (by DID or handle); ' +
         'with no options, prints the current metadata')
         .option('--handle <handle>', 'set the handle (an empty string clears it)')
         .option('--description <description>', 'set the description (an empty string clears it)')
-        .action(async (didRef, options) => {
-        let did;
-        try {
-            did = await resolveDidRef({ ref: didRef });
-        }
-        catch (err) {
-            console.error(err.message);
-            process.exit(1);
-            return;
-        }
-        if (did) {
-            // Refuse to create metadata for DIDs that are not saved locally.
-            try {
-                await loadDidDocument(did);
-            }
-            catch {
-                did = undefined;
-            }
-        }
-        if (!did) {
-            console.error(`No locally stored DID found for ${didRef}`);
-            process.exit(1);
-            return;
-        }
-        const existing = await loadDidMeta({ did });
-        const hasEdits = options.handle !== undefined || options.description !== undefined;
-        if (!hasEdits) {
-            console.log(JSON.stringify(existing ?? {}, null, 2));
-            return;
-        }
-        const meta = { ...(existing ?? {}) };
-        if (options.handle !== undefined) {
-            if (options.handle === '') {
-                delete meta.handle;
-            }
-            else {
-                meta.handle = options.handle;
-            }
-        }
-        if (options.description !== undefined) {
-            if (options.description === '') {
-                delete meta.description;
-            }
-            else {
-                meta.description = options.description;
-            }
-        }
-        const filePath = await saveDidMeta({ did, meta });
-        console.error(`Metadata saved to ${filePath}`);
-        console.log(JSON.stringify(meta, null, 2));
-    });
+        .action((didRef, options) => runAndExit(runMeta({ didRef, ...options })));
     did
         .command('remove <did>')
         .aliases(['delete', 'rm'])
         .description('Remove a locally stored DID document, its keys file, and its ' +
         'metadata sidecar (by DID or handle)')
-        .action(async (didRef) => {
-        let did;
-        try {
-            did = await resolveDidRef({ ref: didRef });
-        }
-        catch (err) {
-            console.error(err.message);
-            process.exit(1);
-            return;
-        }
-        let didDocument;
-        try {
-            didDocument = await loadDidDocument(did ?? didRef);
-        }
-        catch {
-            console.error(`No locally stored DID found for ${didRef}`);
-            process.exit(1);
-            return;
-        }
-        const docDid = did ?? didRef;
-        // Scrub the cached key-to-DID associations of any matching wallet keys
-        // before the DID document (the source of truth) is deleted.
-        for (const method of didDocument.verificationMethod ?? []) {
-            if (method.publicKeyMultibase) {
-                await removeKeyDidAssociation({
-                    publicKeyMultibase: method.publicKeyMultibase,
-                    did: docDid
-                });
-            }
-        }
-        const removed = await removeDidFiles({ did: docDid });
-        for (const filePath of removed) {
-            console.error(`Removed ${filePath}`);
-        }
-    });
+        .action((didRef) => runAndExit(runRemove({ didRef })));
+    const webvh = new Command('webvh').description('Manage did:webvh DIDs: rotate update (authorization) keys');
+    webvh
+        .command('rotate-keys <did>')
+        .description('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.')
+        .option('--update-key <multibase...>', 'rotate to specific update key(s) by publicKeyMultibase instead of ' +
+        'generating a fresh one (ordinary mode only; rejected while ' +
+        'pre-rotation is armed, where the next keys are fixed by the prior ' +
+        'commitment)')
+        .option('--enable-prerotation', 'for a DID without pre-rotation, turn it on by staging a next key this ' +
+        'rotation (alone: stage only, leaving the active key unchanged)')
+        .option('--stop-prerotation', 'do not stage a next key; pre-rotation turns off after this rotation')
+        .option('--keep-old-key', 'retain the retired update key secret in the sidecar (default: drop it)')
+        .option('-y, --yes', 'skip the confirmation prompt')
+        .action((didRef, options) => runAndExit(runRotateKeys({ didRef, ...options })));
+    did.addCommand(webvh);
     return did;
 }
 //# sourceMappingURL=did.js.map