@did-btcr2/cli 0.21.0 → 0.23.0

package/src/commands/identifier.ts

@@ -0,0 +1,134 @@
+import type { IdentifierReport } from '@did-btcr2/api';
+import { Identifier } from '@did-btcr2/api';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import type { Command } from 'commander';
+import type { ApiFactory } from '../config.js';
+import { CLIError } from '../error.js';
+import { readGenesisDocumentFile } from '../genesis-document-file.js';
+import { formatResult } from '../output.js';
+import type { CommandResult, GlobalOptions, IdentifierDecodeData } from '../types.js';
+
+/**
+ * Registers the `identifier` command group. `decode` prints the components of
+ * a did:btcr2 identifier. `validate` checks that an identifier conforms to the
+ * specification and prints a report. Both commands are offline and
+ * keystore-free: they use the api with no Bitcoin connection, no CAS, and no
+ * key material.
+ */
+export function registerIdentifierCommand(
+  program : Command,
+  factory : ApiFactory,
+  globals : () => GlobalOptions,
+): void {
+  const identifier = program
+    .command('identifier')
+    .description('Decode and validate did:btcr2 identifiers (offline).');
+  const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
+
+  identifier
+    .command('decode <did>')
+    .description('Print the components of a did:btcr2 identifier.')
+    .option(
+      '--initial-document',
+      'Add the initial DID document. An external identifier (x) needs --genesis-document.',
+      false,
+    )
+    .option(
+      '--genesis-document <path>',
+      'Path to the JSON genesis document of an external identifier (x). Requires --initial-document.',
+    )
+    .action(async (did: string, options: { initialDocument?: boolean; genesisDocument?: string }) => {
+      if (options.genesisDocument !== undefined && !options.initialDocument) {
+        throw new CLIError('--genesis-document requires --initial-document.', 'INVALID_ARGUMENT_ERROR');
+      }
+      assertValidIdentifier(did);
+      const api = factory();
+      const components = api.did.decode(did);
+      if (options.genesisDocument !== undefined && components.hrp === 'k') {
+        throw new CLIError(
+          '--genesis-document applies only to external identifiers (x).',
+          'INVALID_ARGUMENT_ERROR',
+          { did },
+        );
+      }
+      const data: IdentifierDecodeData = {
+        did,
+        idType       : components.idType,
+        hrp          : components.hrp,
+        version      : components.version,
+        network      : components.network,
+        genesisBytes : bytesToHex(components.genesisBytes),
+      };
+      if (options.initialDocument) {
+        if (components.hrp === 'x' && options.genesisDocument === undefined) {
+          throw new CLIError(
+            'An external identifier (x) needs --genesis-document <path> for --initial-document.',
+            'INVALID_ARGUMENT_ERROR',
+            { did },
+          );
+        }
+        const genesisDocument = options.genesisDocument === undefined
+          ? undefined
+          : await readGenesisDocumentFile(options.genesisDocument);
+        data.initialDocument = api.btcr2.getInitialDocument(did, genesisDocument);
+      }
+      print({ action: 'identifier-decode', data });
+    });
+
+  identifier
+    .command('validate <did>')
+    .description('Check that a did:btcr2 identifier conforms to the specification. Exit code 1 if it does not.')
+    .option(
+      '-b, --bytes <hex>',
+      'Genesis bytes as a hex string that the identifier must encode: the 33-byte public key (k) '
+      + 'or the 32-byte genesis document hash (x). Adds the genesisBytesMatch check.',
+    )
+    .option(
+      '--genesis-document <path>',
+      'Path to the JSON genesis document of an external identifier (x). Adds the genesisDocument check.',
+    )
+    .action(async (did: string, options: { bytes?: string; genesisDocument?: string }) => {
+      const genesisBytes = options.bytes === undefined ? undefined : parseHexBytes(options.bytes);
+      let genesisDocument: object | undefined;
+      if (options.genesisDocument !== undefined) {
+        // Refuse the flag for a KEY identifier before the file read. An invalid
+        // identifier passes through: the report names its failed check.
+        if (Identifier.isValid(did) && Identifier.decode(did).hrp === 'k') {
+          throw new CLIError(
+            '--genesis-document applies only to external identifiers (x).',
+            'INVALID_ARGUMENT_ERROR',
+            { did },
+          );
+        }
+        genesisDocument = await readGenesisDocumentFile(options.genesisDocument);
+      }
+      const report: IdentifierReport = factory().did.validate(did, { genesisBytes, genesisDocument });
+      print({ action: 'identifier-validate', data: report });
+      if (!report.valid) process.exitCode = 1;
+    });
+}
+
+/**
+ * Throws a `CLIError` that names the failed check if the identifier is not
+ * valid. The Bech32m decoder alone throws a raw error with a stack; this
+ * guard gives `decode` one message shape for every failure.
+ */
+function assertValidIdentifier(did: string): void {
+  const report = Identifier.validate(did);
+  if (report.valid) return;
+  const failed = report.checks[report.checks.length - 1];
+  throw new CLIError(
+    `Invalid identifier (${failed.name} check): ${failed.detail ?? 'failed'}`,
+    'INVALID_ARGUMENT_ERROR',
+    { did, check: failed.name },
+  );
+}
+
+/** Parses the `--bytes` hex string. The length is a validation result, not an argument error. */
+function parseHexBytes(value: string): Uint8Array {
+  try {
+    return hexToBytes(value.trim());
+  } catch {
+    throw new CLIError('Invalid bytes: not valid hex.', 'INVALID_ARGUMENT_ERROR', { bytes: value });
+  }
+}

package/src/commands/index.ts

@@ -4,6 +4,8 @@ export { registerCreateCommand } from './create.js';
 export { registerResolveCommand } from './resolve.js';
 export { registerUpdateCommand } from './update.js';
 export { registerDeactivateCommand } from './deactivate.js';
+export { registerIdentifierCommand } from './identifier.js';
+export { registerGenesisCommand } from './genesis.js';
 export { registerKeyCommand } from './key.js';
 export { registerKeystoreCommand } from './keystore.js';
 export { registerConfigCommand } from './config.js';

package/src/commands/resolve.ts

@@ -1,6 +1,8 @@
 import { Identifier } from '@did-btcr2/api';
 import type { Command } from 'commander';
 import { deriveNetwork, type ApiFactory } from '../config.js';
+import { CLIError } from '../error.js';
+import { GENESIS_DOCUMENT_HELP } from '../genesis-document-file.js';
 import { formatResult } from '../output.js';
 import { MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
 import type { GlobalOptions, ResolveCommandOptions } from '../types.js';
@@ -18,6 +20,7 @@ export function registerResolveCommand(
     .option('-r, --resolution-options <json>', 'JSON string containing resolution options')
     .option('-p, --resolution-options-path <path>', 'Path to a JSON file containing resolution options')
     .option('--min-conf <n>', MIN_CONF_HELP, parseMinConf)
+    .option('--genesis-document <path>', GENESIS_DOCUMENT_HELP)
     .action(async (options: { identifier: string } & ResolutionOptionFlags) => {
       const parsed = await validateResolveOptions(options);
       const network = deriveNetwork(parsed.identifier);
@@ -32,7 +35,23 @@ async function validateResolveOptions(
   options: { identifier: string } & ResolutionOptionFlags,
 ): Promise<ResolveCommandOptions> {
   // Validate identifier format early
-  Identifier.decode(options.identifier);
+  const components = Identifier.decode(options.identifier);
+  assertGenesisDocumentApplies(options, components.hrp);
   const resolutionOptions = await readResolutionOptions(options);
   return { identifier: options.identifier, options: resolutionOptions };
 }
+
+/**
+ * Refuses `--genesis-document` for a KEY identifier before the file is read.
+ * A KEY identifier has no genesis document; the resolver would ignore the
+ * file in silence. `resolve`, `update`, and `deactivate` share the check.
+ */
+export function assertGenesisDocumentApplies(flags: ResolutionOptionFlags, hrp: string): void {
+  if (flags.genesisDocument !== undefined && hrp === 'k') {
+    throw new CLIError(
+      '--genesis-document applies only to external identifiers (x).',
+      'INVALID_ARGUMENT_ERROR',
+      { genesisDocument: flags.genesisDocument },
+    );
+  }
+}

package/src/commands/write.ts

@@ -8,10 +8,13 @@ import {
   resolveSigningKeyRef,
   type ApiFactory,
 } from '../config.js';
+import { Identifier } from '@did-btcr2/api';
 import { CLIError } from '../error.js';
+import { GENESIS_DOCUMENT_HELP } from '../genesis-document-file.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
-import { MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
+import { hasResolutionFlags, MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
 import type { GlobalOptions, NetworkOption, UpdateCommandOptions } from '../types.js';
+import { assertGenesisDocumentApplies } from './resolve.js';
 
 /** The parsed flags that `update` and `deactivate` share. */
 export type WriteFlags = ResolutionOptionFlags & {
@@ -62,6 +65,7 @@ export function registerWriteOptions(command: Command): Command {
       'Path to a JSON file with resolution options, for the resolution of the source document',
     )
     .option('--min-conf <n>', MIN_CONF_HELP, parseMinConf)
+    .option('--genesis-document <path>', `${GENESIS_DOCUMENT_HELP}, for the resolution of the source document`)
     .option(
       '--publish-to-cas <mode>',
       'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
@@ -93,7 +97,8 @@ export function registerWriteOptions(command: Command): Command {
  * 3. The resolution flags come only without the source pair. The api ignores
  *    `resolutionOptions` when the pair is supplied (ADR 098). A silent ignore
  *    of `--min-conf` would mislead.
- * 4. A mainnet write is refused with an unencrypted dev keystore (ADR 080).
+ * 4. `--genesis-document` comes only with an external (x) identifier.
+ * 5. A mainnet write is refused with an unencrypted dev keystore (ADR 080).
  */
 export async function prepareWrite(
   options : WriteFlags,
@@ -112,17 +117,15 @@ export async function prepareWrite(
       { did },
     );
   }
-  const hasResolutionFlags = options.resolutionOptions !== undefined
-    || options.resolutionOptionsPath !== undefined
-    || options.minConf !== undefined;
-  if (hasDocument && hasResolutionFlags) {
+  if (hasDocument && hasResolutionFlags(options)) {
     throw new CLIError(
-      '--resolution-options, --resolution-options-path, and --min-conf apply only when '
+      '--resolution-options, --resolution-options-path, --min-conf, and --genesis-document apply only when '
         + '--source-document and --source-version-id are omitted. A supplied source pair skips resolution.',
       'INVALID_ARGUMENT_ERROR',
       { did },
     );
   }
+  assertGenesisDocumentApplies(options, Identifier.decode(did).hrp);
   assertKeystoreAllowedForNetwork(network, g);
   const resolutionOptions = await readResolutionOptions(options);
   const api = factory(network, g);

package/src/genesis-document-file.ts

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { CLIError } from './error.js';
+
+/** The help text of `--genesis-document`. `resolve`, `update`, and `deactivate` share it. */
+export const GENESIS_DOCUMENT_HELP =
+  'Path to the JSON genesis document of an external identifier (x). '
+  + 'Fills sidecar.genesisDocument of the resolution options';
+
+/**
+ * Reads and parses a genesis document file. The content must be a JSON
+ * object. The shape of the document is checked by the api, not here.
+ * @param path The path of the JSON file.
+ * @returns The parsed object.
+ * @throws {CLIError} If the file is unreadable, not JSON, or not an object.
+ */
+export async function readGenesisDocumentFile(path: string): Promise<object> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf-8'));
+  } catch {
+    throw new CLIError(
+      'Invalid genesis document path. Must be a valid path to a JSON file.',
+      'INVALID_ARGUMENT_ERROR',
+      { genesisDocument: path },
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new CLIError(
+      'Invalid genesis document. The file must contain a JSON object.',
+      'INVALID_ARGUMENT_ERROR',
+      { genesisDocument: path },
+    );
+  }
+  return parsed;
+}

package/src/genesis-spec.ts

@@ -0,0 +1,149 @@
+import type {
+  BeaconAddressType,
+  BeaconType,
+  GenesisBeaconSpec,
+  GenesisDocumentSpec,
+  GenesisVerificationMethodSpec,
+  VerificationRelationship
+} from '@did-btcr2/api';
+import { hexToBytes } from '@noble/hashes/utils.js';
+import type { DidService } from '@web5/dids';
+import { CLIError } from './error.js';
+import type { NetworkOption } from './types.js';
+
+/**
+ * One verification method of a genesis spec file. `key` is a keystore
+ * reference (URN, name, or fingerprint prefix); `publicKey` is a 33-byte
+ * compressed public key as hex. Exactly one of the two.
+ */
+export interface GenesisSpecVerificationMethod {
+  key?           : string;
+  publicKey?     : string;
+  relationships? : string[];
+  fragment?      : string;
+}
+
+/**
+ * One beacon of a genesis spec file. `key` or `publicKey` derives the beacon
+ * address from a key; `address` uses a Bitcoin address as given. At most one
+ * of the three; the api requires one.
+ */
+export interface GenesisSpecBeacon {
+  type          : string;
+  key?          : string;
+  publicKey?    : string;
+  addressType?  : string;
+  address?      : string;
+  fragment?     : string;
+}
+
+/** One other service of a genesis spec file. */
+export interface GenesisSpecService {
+  id?             : string;
+  type            : string;
+  serviceEndpoint : unknown;
+}
+
+/**
+ * The genesis spec file that `btcr2 genesis build --spec <path>` reads, and
+ * that the wizard collects. The network comes from `-n` or the configuration,
+ * not from the file.
+ */
+export interface GenesisSpecFile {
+  verificationMethods : GenesisSpecVerificationMethod[];
+  beacons?            : GenesisSpecBeacon[];
+  services?           : GenesisSpecService[];
+}
+
+/** Resolves a keystore key reference to the 33-byte public key. */
+export type ResolvePublicKey = (ref: string) => Uint8Array;
+
+/**
+ * Checks the shape of a parsed genesis spec file. The values (relationship
+ * names, beacon types, addresses) are checked by the api when it builds the
+ * document; this function checks only what the api cannot see: that each
+ * verification method names exactly one key source, and that each beacon
+ * names at most one.
+ * @param value The parsed JSON value.
+ * @param source The file path, for the error data.
+ * @returns The spec.
+ * @throws {CLIError} If the shape is not valid.
+ */
+export function parseGenesisSpec(value: unknown, source: string): GenesisSpecFile {
+  const fail = (message: string): never => {
+    throw new CLIError(`Invalid genesis spec: ${message}`, 'INVALID_ARGUMENT_ERROR', { spec: source });
+  };
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return fail('the file must contain a JSON object.');
+  }
+  const spec = value as Record<string, unknown>;
+  if (!Array.isArray(spec.verificationMethods) || spec.verificationMethods.length === 0) {
+    return fail('"verificationMethods" must be a non-empty array.');
+  }
+  spec.verificationMethods.forEach((vm, index) => {
+    if (vm === null || typeof vm !== 'object') return fail(`verificationMethods[${index}] must be an object.`);
+    const hasKey = typeof vm.key === 'string' && vm.key.length > 0;
+    const hasPublicKey = typeof vm.publicKey === 'string' && vm.publicKey.length > 0;
+    if (hasKey === hasPublicKey) {
+      return fail(`verificationMethods[${index}] needs exactly one of "key" (a keystore reference) or "publicKey" (hex).`);
+    }
+  });
+  if (spec.beacons !== undefined) {
+    if (!Array.isArray(spec.beacons)) return fail('"beacons" must be an array.');
+    spec.beacons.forEach((beacon, index) => {
+      if (beacon === null || typeof beacon !== 'object') return fail(`beacons[${index}] must be an object.`);
+      const sources = ['key', 'publicKey', 'address'].filter(name => beacon[name] !== undefined);
+      if (sources.length > 1) {
+        return fail(`beacons[${index}] names ${sources.join(' and ')}. Give only one of "key", "publicKey", or "address".`);
+      }
+    });
+  }
+  if (spec.services !== undefined && !Array.isArray(spec.services)) {
+    return fail('"services" must be an array.');
+  }
+  return spec as unknown as GenesisSpecFile;
+}
+
+/**
+ * Converts a genesis spec file to the api spec: resolves each keystore
+ * reference to its public key, parses each hex public key, and passes the
+ * other values through for the api to check.
+ * @param spec The spec file.
+ * @param network The network of the beacon addresses.
+ * @param resolvePublicKey Resolves a keystore reference to the public key.
+ * @returns The api spec.
+ * @throws {CLIError} If a hex public key is not hex.
+ */
+export function toApiSpec(spec: GenesisSpecFile, network: NetworkOption, resolvePublicKey: ResolvePublicKey): GenesisDocumentSpec {
+  const keyBytes = (entry: { key?: string; publicKey?: string }, label: string): Uint8Array =>
+    entry.key !== undefined ? resolvePublicKey(entry.key) : parseHexPublicKey(entry.publicKey as string, label);
+  const verificationMethods: GenesisVerificationMethodSpec[] = spec.verificationMethods.map((vm, index) => ({
+    publicKey     : keyBytes(vm, `verificationMethods[${index}].publicKey`),
+    relationships : vm.relationships as VerificationRelationship[] | undefined,
+    fragment      : vm.fragment,
+  }));
+  const beacons: GenesisBeaconSpec[] | undefined = spec.beacons?.map((beacon, index) => ({
+    type        : beacon.type as BeaconType,
+    publicKey   : beacon.key !== undefined || beacon.publicKey !== undefined
+      ? keyBytes(beacon, `beacons[${index}].publicKey`)
+      : undefined,
+    addressType : beacon.addressType as BeaconAddressType | undefined,
+    address     : beacon.address,
+    fragment    : beacon.fragment,
+  }));
+  return {
+    network,
+    verificationMethods,
+    beacons,
+    services : spec.services as DidService[] | undefined,
+  };
+}
+
+/** Parses a hex public key. The length and the curve check belong to the api. */
+export function parseHexPublicKey(hex: string, label: string): Uint8Array {
+  try {
+    return hexToBytes(hex.trim());
+  } catch {
+    throw new CLIError(`Invalid ${label}: not valid hex.`, 'INVALID_ARGUMENT_ERROR', { publicKey: hex });
+  }
+}

package/src/genesis-wizard.ts

@@ -0,0 +1,163 @@
+import { BEACON_ADDRESS_TYPES, BEACON_TYPES, DEFAULT_BEACON_ADDRESS_TYPE, VERIFICATION_RELATIONSHIPS } from '@did-btcr2/api';
+import type { GenesisSpecBeacon, GenesisSpecFile, GenesisSpecService, GenesisSpecVerificationMethod } from './genesis-spec.js';
+
+/** Asks one question and returns the answer line. */
+export type Ask = (question: string) => Promise<string>;
+
+/** One keystore key as the wizard lists it. */
+export interface WizardKey {
+  keyId       : string;
+  fingerprint : string;
+  name?       : string;
+  active      : boolean;
+}
+
+/** What the wizard needs from the command: output, the key list, and key resolution. */
+export interface WizardContext {
+  /** Prints one line to the operator. */
+  say: (line: string) => void;
+  /** The keys of the keystore, for the list and the default. */
+  keys: WizardKey[];
+  /** Resolves a key reference to its id, or throws with a message. */
+  resolveKey: (ref: string) => string;
+}
+
+/** A 33-byte compressed public key as hex. */
+const PUBLIC_KEY_HEX = /^0[23][0-9a-fA-F]{64}$/;
+
+/**
+ * Collects a genesis spec through questions: the verification methods with
+ * their relationships, the beacons, and the other services. The answers are
+ * not checked against the network here; the api checks them when it builds
+ * the document, and the command reports the failure.
+ * @param ask Asks one question.
+ * @param ctx The output, the key list, and the key resolver.
+ * @returns The spec.
+ */
+export async function collectGenesisSpec(ask: Ask, ctx: WizardContext): Promise<GenesisSpecFile> {
+  const verificationMethods = await collectVerificationMethods(ask, ctx);
+  const beacons = await collectBeacons(ask, ctx, verificationMethods[0]);
+  const services = await collectServices(ask, ctx);
+  return { verificationMethods, beacons, ...(services.length > 0 && { services }) };
+}
+
+/** Asks for the verification methods. The first one defaults to the active key. */
+async function collectVerificationMethods(ask: Ask, ctx: WizardContext): Promise<GenesisSpecVerificationMethod[]> {
+  if (ctx.keys.length === 0) {
+    ctx.say('The keystore has no keys. Enter each key as a 33-byte compressed public key in hex.');
+  } else {
+    ctx.say('Keys in the keystore:');
+    for (const key of ctx.keys) {
+      ctx.say(`  ${key.fingerprint}${key.name ? `  ${key.name}` : ''}${key.active ? '  (active)' : ''}`);
+    }
+  }
+  const active = ctx.keys.find(key => key.active);
+  const methods: GenesisSpecVerificationMethod[] = [];
+  for (let n = 1; ; n++) {
+    const defaultRef = n === 1 && active ? (active.name ?? active.fingerprint) : undefined;
+    const source = await askKeySource(ask, ctx, `Verification method ${n}: key reference or public key hex`, defaultRef);
+    const relationships = await askRelationships(ask, ctx, n);
+    methods.push({ ...source, ...(relationships && { relationships }) });
+    if (!(await askYesNo(ask, 'Add another verification method?'))) break;
+  }
+  return methods;
+}
+
+/** Asks for the beacons. The first one defaults to a Singleton beacon on the first key. */
+async function collectBeacons(ask: Ask, ctx: WizardContext, firstMethod: GenesisSpecVerificationMethod): Promise<GenesisSpecBeacon[]> {
+  const beacons: GenesisSpecBeacon[] = [];
+  for (let n = 1; ; n++) {
+    const type = await askChoice(ask, ctx, `Beacon ${n} type`, BEACON_TYPES, 'SingletonBeacon');
+    const address = (await ask(`Beacon ${n} address (blank: derive the address from the key of method 1): `)).trim();
+    if (address.length === 0) {
+      const addressType = await askChoice(ask, ctx, `Beacon ${n} address type`, BEACON_ADDRESS_TYPES, DEFAULT_BEACON_ADDRESS_TYPE);
+      const keySource = firstMethod.key !== undefined ? { key: firstMethod.key } : { publicKey: firstMethod.publicKey };
+      beacons.push({ type, ...keySource, addressType });
+    } else {
+      beacons.push({ type, address });
+    }
+    if (!(await askYesNo(ask, 'Add another beacon?'))) break;
+  }
+  return beacons;
+}
+
+/** Asks for the other services, if any. */
+async function collectServices(ask: Ask, ctx: WizardContext): Promise<GenesisSpecService[]> {
+  const services: GenesisSpecService[] = [];
+  while (await askYesNo(ask, 'Add a service?')) {
+    const n = services.length + 1;
+    const fragment = (await ask(`Service ${n} id fragment (blank: service-<position>): `)).trim();
+    const type = await askRequired(ask, ctx, `Service ${n} type`);
+    const serviceEndpoint = await askRequired(ask, ctx, `Service ${n} endpoint`);
+    services.push({ ...(fragment.length > 0 && { id: `#${fragment.replace(/^#/, '')}` }), type, serviceEndpoint });
+  }
+  return services;
+}
+
+/** Asks for a key reference or a public key hex, until the answer resolves. */
+async function askKeySource(
+  ask        : Ask,
+  ctx        : WizardContext,
+  question   : string,
+  defaultRef : string | undefined,
+): Promise<{ key: string } | { publicKey: string }> {
+  for (;;) {
+    const raw = (await ask(`${question}${defaultRef ? ` [${defaultRef}]` : ''}: `)).trim();
+    const answer = raw.length > 0 ? raw : defaultRef;
+    if (answer === undefined) {
+      ctx.say('A key is required.');
+      continue;
+    }
+    if (PUBLIC_KEY_HEX.test(answer)) return { publicKey: answer.toLowerCase() };
+    try {
+      ctx.resolveKey(answer);
+      return { key: answer };
+    } catch (error) {
+      ctx.say((error as Error).message);
+    }
+  }
+}
+
+/** Asks for the relationships of a method. Blank means all four (the api default). */
+async function askRelationships(ask: Ask, ctx: WizardContext, n: number): Promise<string[] | undefined> {
+  const names = VERIFICATION_RELATIONSHIPS.join(', ');
+  for (;;) {
+    const raw = (await ask(`Relationships of method ${n} (comma-separated: ${names}) [all]: `)).trim();
+    if (raw.length === 0) return undefined;
+    const chosen = raw.split(',').map(s => s.trim()).filter(s => s.length > 0);
+    const unknown = chosen.filter(name => !(VERIFICATION_RELATIONSHIPS as readonly string[]).includes(name));
+    if (unknown.length === 0) return chosen;
+    ctx.say(`Unknown relationship: ${unknown.join(', ')}. Expected one of ${names}.`);
+  }
+}
+
+/** Asks for one value of a list, with a default. */
+async function askChoice<T extends string>(
+  ask          : Ask,
+  ctx          : WizardContext,
+  question     : string,
+  choices      : readonly T[],
+  defaultValue : T,
+): Promise<T> {
+  for (;;) {
+    const raw = (await ask(`${question} (${choices.join(', ')}) [${defaultValue}]: `)).trim();
+    if (raw.length === 0) return defaultValue;
+    if ((choices as readonly string[]).includes(raw)) return raw as T;
+    ctx.say(`Unknown value "${raw}". Expected one of ${choices.join(', ')}.`);
+  }
+}
+
+/** Asks for a non-empty value. */
+async function askRequired(ask: Ask, ctx: WizardContext, question: string): Promise<string> {
+  for (;;) {
+    const raw = (await ask(`${question}: `)).trim();
+    if (raw.length > 0) return raw;
+    ctx.say('A value is required.');
+  }
+}
+
+/** Asks a yes/no question. Blank means no. */
+async function askYesNo(ask: Ask, question: string): Promise<boolean> {
+  const raw = (await ask(`${question} [y/N]: `)).trim();
+  return /^y(es)?$/i.test(raw);
+}

package/src/hints.ts

@@ -20,8 +20,6 @@ import type { GlobalOptions, NetworkOption } from './types.js';
  */
 export function printCreateFundingHint(g: GlobalOptions, network: NetworkOption, did: string): void {
   if (g.quiet || g.output === 'json') return;
-  const faucet = faucetUrl(network);
-  if (!faucet) return;
   let beaconAddress: string;
   try {
     const { serviceEndpoint } = BeaconUtils.createBeaconService(did, 'p2wpkh', 'SingletonBeacon');
@@ -29,6 +27,19 @@ export function printCreateFundingHint(g: GlobalOptions, network: NetworkOption,
   } catch {
     return;
   }
+  printBeaconFundingHint(g, network, beaconAddress);
+}
+
+/**
+ * Prints a funding hint for a beacon address on a network with a public
+ * faucet: the address next to the faucet and explorer links. A no-op on a
+ * network without a faucet (regtest/mainnet). `create -t x --document` and
+ * `genesis build` use it for the first beacon of the genesis document.
+ */
+export function printBeaconFundingHint(g: GlobalOptions, network: NetworkOption, beaconAddress: string): void {
+  if (g.quiet || g.output === 'json') return;
+  const faucet = faucetUrl(network);
+  if (!faucet) return;
   const explorer = explorerAddressUrl(network, beaconAddress);
   const lines = [
     'Fund the initial beacon to anchor updates:',

package/src/network-option.ts

@@ -0,0 +1,50 @@
+import type { ConnectionOverrides } from './config.js';
+import { profileNetworkMismatch, resolveDefaultNetwork } from './config.js';
+import { CLIError } from './error.js';
+import type { GlobalOptions, NetworkOption } from './types.js';
+import { SUPPORTED_NETWORKS } from './types.js';
+
+/** The help text of `-n, --network` on the offline creation commands. */
+export const NETWORK_OPTION_HELP =
+  'Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest> '
+  + '(default: config defaults.network, else regtest)';
+
+/** Builds the keystore- and config-resolution overrides from the global flags. */
+export function overridesFromGlobals(g: GlobalOptions): ConnectionOverrides {
+  return {
+    home           : g.home,
+    config         : g.config,
+    profile        : g.profile,
+    keystore       : g.keystore,
+    passphraseFile : g.passphraseFile,
+  };
+}
+
+/** Validates an explicit `--network`, or resolves the default from configuration. */
+export function resolveNetworkOption(explicit: string | undefined, overrides: ConnectionOverrides): NetworkOption {
+  if (!explicit) return resolveDefaultNetwork(overrides);
+  if (!SUPPORTED_NETWORKS.includes(explicit as NetworkOption)) {
+    throw new CLIError(
+      'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
+      'INVALID_ARGUMENT_ERROR',
+      { network: explicit },
+    );
+  }
+  return explicit as NetworkOption;
+}
+
+/**
+ * Warns on stderr, and never blocks, when the network of a new identifier
+ * disagrees with the network that the active profile declares. A `production`
+ * profile that holds mainnet endpoints must not mint a regtest DID in silence.
+ */
+export function warnProfileNetworkMismatch(g: GlobalOptions, network: NetworkOption, overrides: ConnectionOverrides): void {
+  const mismatch = profileNetworkMismatch(network, overrides);
+  if (mismatch && !g.quiet) {
+    process.stderr.write(
+      `Warning: creating a "${network}" identifier while the active profile `
+      + `"${mismatch.profile}" declares network "${mismatch.declared}". The `
+      + 'identifier\'s network and the profile\'s endpoints may not match.\n'
+    );
+  }
+}