keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/{app/cli → cli/endpoints}/ends.js

@@ -1,8 +1,10 @@
+import { call, spawn } from "effection";
+import { endpointRoleAccepted, isLocalGroupHab, proposeGroupEndpointRole, } from "../../app/identity/endpoint-roleing.js";
+import { settleRuntimeIngress } from "../../app/runtime/agent-runtime.js";
 import { ValidationError } from "../../core/errors.js";
 import { isEndpointRole } from "../../core/roles.js";
-import { ingestKeriBytes, processRuntimeTurn } from "../agent-runtime.js";
-import { endpointRoleAccepted, isLocalGroupHab, proposeGroupEndpointRole } from "../endpoint-roleing.js";
-import { withHabAndAgentRuntime } from "./common/context.js";
+import { withHabAndAgentRuntime } from "../common/context.js";
+import { parseBooleanOption, parseStringOption } from "../common/parsing.js";
 /**
  * Implement `tufa ends add` on top of the shared local runtime.
  *
@@ -14,18 +16,20 @@ import { withHabAndAgentRuntime } from "./common/context.js";
  *
  * This command mutates local state only through normal KERI reply processing,
  * not through a side-channel direct DB write.
+ *
+ * @param args Parsed command flags and positionals; required identifiers and policy values are validated before effects.
  */
 export function* endsAddCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        role: args.role,
-        eid: args.eid,
-        multisigMode: parseMultisigMode(args.multisigMode),
-        compat: args.compat,
+        name: parseStringOption(args.name, "--name"),
+        base: parseStringOption(args.base, "--base"),
+        headDirPath: parseStringOption(args.headDirPath, "--head-dir"),
+        passcode: parseStringOption(args.passcode, "--passcode"),
+        alias: parseStringOption(args.alias, "--alias"),
+        role: parseStringOption(args.role, "--role"),
+        eid: parseStringOption(args.eid, "--eid"),
+        multisigMode: parseMultisigMode(parseStringOption(args.multisigMode, "--multisig-mode")),
+        compat: parseBooleanOption(args.compat, "--compat"),
     };
     if (!commandArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");
@@ -41,7 +45,7 @@ export function* endsAddCommand(args) {
     }
     const eid = commandArgs.eid;
     const role = commandArgs.role;
-    yield* withHabAndAgentRuntime(commandArgs, commandArgs.alias, {
+    return yield* withHabAndAgentRuntime(commandArgs, commandArgs.alias, {
         compat: commandArgs.compat ?? false,
         readonly: false,
         skipConfig: false,
@@ -52,37 +56,36 @@ export function* endsAddCommand(args) {
                 throw new ValidationError("Group endpoint role authorization requires --multisig-mode propose or --multisig-mode complete.");
             }
             if (commandArgs.multisigMode === "propose") {
-                const result = yield* proposeGroupEndpointRole(runtime, hab, {
-                    eid,
-                    role,
-                    allow: true,
+                const result = yield* call(function* () {
+                    const postman = runtime.postman;
+                    const worker = yield* spawn(() => postman.deliverDo());
+                    try {
+                        return yield* proposeGroupEndpointRole(hby, runtime.protocol, postman, hab, {
+                            eid,
+                            role,
+                            allow: true,
+                        });
+                    }
+                    finally {
+                        yield* worker.halt();
+                    }
                 });
-                console.log(JSON.stringify({
-                    route: result.route,
-                    said: result.said,
-                    group: result.group,
-                    accepted: result.accepted,
-                    deliveries: result.deliveries,
-                    attachmentBytes: result.attachmentBytes,
-                }));
-                return;
+                return result;
             }
             if (!endpointRoleAccepted(hby, hab.pre, role, eid)) {
                 throw new ValidationError(`Endpoint role ${role} for ${eid} is not yet approved for group ${hab.pre}.`);
             }
-            console.log(`${role} ${eid}`);
-            return;
+            return { role, eid };
         }
         if (commandArgs.multisigMode) {
             throw new ValidationError("--multisig-mode is only valid for local group aliases.");
         }
-        ingestKeriBytes(runtime, hab.makeEndRole(eid, role, true));
-        yield* processRuntimeTurn(runtime, { hab, pollMailbox: false });
+        yield* settleRuntimeIngress(runtime, [hab.makeEndRole(eid, role, true)]);
         const end = hby.db.ends.get([hab.pre, role, eid]);
         if (!end?.allowed) {
             throw new ValidationError(`Endpoint role ${role} for ${eid} was not accepted into local state.`);
         }
-        console.log(`${role} ${eid}`);
+        return { role, eid };
     });
 }
 function parseMultisigMode(value) {

package/esm/keri/npm/src/{app/cli → cli/endpoints}/loc.js

@@ -1,6 +1,8 @@
+import { isLocalGroupHab } from "../../app/multisig/group-members.js";
+import { settleRuntimeIngress } from "../../app/runtime/agent-runtime.js";
 import { ValidationError } from "../../core/errors.js";
-import { ingestKeriBytes, processRuntimeTurn } from "../agent-runtime.js";
-import { withHabAndAgentRuntime } from "./common/context.js";
+import { withHabAndAgentRuntime } from "../common/context.js";
+import { parseBooleanOption, parseStringOption } from "../common/parsing.js";
 /**
  * Implement `tufa loc add` through the shared local runtime.
  *
@@ -12,15 +14,15 @@ import { withHabAndAgentRuntime } from "./common/context.js";
  */
 export function* locAddCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        url: args.url,
-        eid: args.eid,
-        time: args.time,
-        compat: args.compat,
+        name: parseStringOption(args.name, "--name"),
+        base: parseStringOption(args.base, "--base"),
+        headDirPath: parseStringOption(args.headDirPath, "--head-dir"),
+        passcode: parseStringOption(args.passcode, "--passcode"),
+        alias: parseStringOption(args.alias, "--alias"),
+        url: parseStringOption(args.url, "--url"),
+        eid: parseStringOption(args.eid, "--eid"),
+        time: parseStringOption(args.time, "--time"),
+        compat: parseBooleanOption(args.compat, "--compat"),
     };
     if (!commandArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");
@@ -49,16 +51,16 @@ export function* locAddCommand(args) {
         skipConfig: false,
         skipSignator: false,
     }, function* ({ hby, hab, runtime }) {
+        if (isLocalGroupHab(hby, hab)) {
+            throw new ValidationError("Location replies require an endpoint-owner alias. Use multisig endpoint-role approval to authorize that endpoint for a group.");
+        }
         const eid = commandArgs.eid ?? hab.pre;
-        ingestKeriBytes(runtime, hab.makeLocScheme(url, eid, scheme, commandArgs.time));
-        for (let i = 0; i < 4; i += 1) {
-            yield* processRuntimeTurn(runtime, { hab, pollMailbox: false });
-            if (hby.db.locs.get([eid, scheme])?.url === url
-                && !!hby.db.lans.get([eid, scheme])
-                && hab.loadLocScheme(eid, scheme).length > 0) {
-                console.log(`Location ${url} added for aid ${eid} with scheme ${scheme}`);
-                return;
-            }
+        yield* settleRuntimeIngress(runtime, [hab.makeLocScheme(url, eid, scheme, commandArgs.time)]);
+        if (hby.db.locs.get([eid, scheme])?.url === url
+            && !!hby.db.lans.get([eid, scheme])
+            && hab.loadLocScheme(eid, scheme).length > 0) {
+            console.log(`Location ${url} added for aid ${eid} with scheme ${scheme}`);
+            return;
         }
         throw new ValidationError(`Location ${url} for ${eid} was not accepted into local state.`);
     });

package/esm/keri/npm/src/cli/endpoints/oobi-clean.js

@@ -0,0 +1,134 @@
+/** Offline, exact-key maintenance of the existing pending-OOBI table. */
+import * as dntShim from "../../_dnt.shims.js";
+import { call } from "effection";
+import { DatabaseOperationError, ValidationError } from "../../core/errors.js";
+import { baserDefaults } from "../../db/baser-defaults.js";
+import { createBaser } from "../../db/basing.js";
+import { PathManager } from "../../db/core/path-manager.js";
+import { parseBooleanOption, parseStringOption } from "../common/parsing.js";
+import { writeJsonLine } from "../common/rendering.js";
+/** Read a nonempty JSON list, preserving exact keys and first-seen order. */
+function* loadKeys(path) {
+    let value;
+    try {
+        value = JSON.parse(yield* call(() => dntShim.Deno.readTextFile(path)));
+    }
+    catch (cause) {
+        throw new ValidationError(`Unable to read the JSON key file: ${path}`, { cause });
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new ValidationError("Key file must contain a nonempty JSON array of exact string keys");
+    }
+    const keys = new Set();
+    for (const [index, key] of value.entries()) {
+        if (typeof key !== "string" || key.length === 0) {
+            throw new ValidationError(`Key file entry ${index} must be a nonempty string`);
+        }
+        // UTF-8 encoding replaces lone surrogates; never select a different stored
+        // key by silently repairing an ill-formed JSON string.
+        if (/[\uD800-\uDFFF]/u.test(key)) {
+            throw new ValidationError(`Key file entry ${index} must be a well-formed Unicode string`);
+        }
+        keys.add(key);
+    }
+    return [...keys];
+}
+/**
+ * Preview by default; apply only after every requested pending key is present.
+ * Publish the actual completed/remaining selection even on a deletion failure.
+ * The operator stops and backs up the service before invoking this command.
+ */
+export function* oobiCleanCommand(args) {
+    if (typeof args.name !== "string" || args.name.trim().length === 0) {
+        throw new ValidationError("Name is required and cannot be empty");
+    }
+    if (typeof args.keyFile !== "string" || args.keyFile.length === 0) {
+        throw new ValidationError("A JSON --key-file is required");
+    }
+    const name = args.name;
+    const apply = parseBooleanOption(args.apply, "apply") ?? false;
+    const options = {
+        name,
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        compat: parseBooleanOption(args.compat, "compat") ?? false,
+    };
+    const keys = yield* loadKeys(args.keyFile);
+    // Resolve through ordinary path preparation before Baser can create data.mdb.
+    // Empty directories are ordinary startup effects; missing databases still fail.
+    const paths = new PathManager(options, baserDefaults(options.compat));
+    paths.name = name;
+    yield* paths.reopen();
+    const path = paths.path;
+    yield* paths.close();
+    if (!(yield* paths.statFileOp(`${path}/data.mdb`)).isFile) {
+        throw new DatabaseOperationError(`Existing database not found at ${path}`);
+    }
+    let report;
+    try {
+        // This boundary joins resource shutdown before reporting command completion.
+        yield* call(function* () {
+            const db = yield* createBaser(options);
+            let operationFailure;
+            try {
+                const entries = keys.map((key) => ({ key, present: db.oobis.get(key) !== null }));
+                const missing = entries.filter((entry) => !entry.present).map((entry) => entry.key);
+                const deleted = [];
+                report = {
+                    path,
+                    mode: apply ? "apply" : "preview",
+                    selectedCount: keys.length,
+                    entries,
+                    missing,
+                    deletedCount: 0,
+                    deleted,
+                    remaining: [...keys],
+                };
+                if (missing.length > 0) {
+                    throw new ValidationError(`Pending OOBI keys not found: ${JSON.stringify(missing)}`);
+                }
+                if (apply) {
+                    for (const key of keys) {
+                        try {
+                            if (!db.oobis.rem(key)) {
+                                throw new DatabaseOperationError(`Pending OOBI removal returned false for ${key}`);
+                            }
+                        }
+                        catch (cause) {
+                            throw new DatabaseOperationError(`OOBI cleanup stopped after deleting ${deleted.length} of ${keys.length} selected entries`, { cause });
+                        }
+                        deleted.push(key);
+                        report.deletedCount = deleted.length;
+                        report.remaining = keys.slice(deleted.length);
+                    }
+                }
+            }
+            catch (error) {
+                operationFailure = { error };
+                throw error;
+            }
+            finally {
+                try {
+                    yield* db.close();
+                }
+                catch (error) {
+                    if (operationFailure) {
+                        // deno-lint-ignore no-unsafe-finally -- Preserve completed row failure and shutdown failure.
+                        throw new AggregateError([operationFailure.error, error], "OOBI cleanup and database close failed", {
+                            cause: operationFailure.error,
+                        });
+                    }
+                    // deno-lint-ignore no-unsafe-finally -- Final command success requires closure.
+                    throw error;
+                }
+            }
+        });
+    }
+    catch (error) {
+        if (report)
+            writeJsonLine({ ...report, status: "failed" });
+        throw error;
+    }
+    if (report)
+        writeJsonLine({ ...report, status: "complete" });
+}

package/esm/keri/npm/src/{app/cli → cli/endpoints}/oobi.js

@@ -1,10 +1,13 @@
+import { oobiTerminalState } from "../../app/bootstrap/oobiery.js";
+import { OOBI_MAILBOX_TOPIC, OOBI_REQUEST_ROUTE, oobiRequestExn } from "../../app/bootstrap/oobiery.js";
+import { sendExchangeMessage } from "../../app/exchanges/exchange-messaging.js";
+import { enqueueOobi, runAgentRuntimeUntil, runtimeOobiConverged } from "../../app/runtime/agent-runtime.js";
+import { systemClock } from "../../app/runtime/runtime-clock.js";
+import { FetchHttpClient } from "../../app/transport/http-client.js";
 import { ValidationError } from "../../core/errors.js";
 import { EndpointRoles, isEndpointRole } from "../../core/roles.js";
-import { enqueueOobi, processRuntimeUntil, runtimeOobiConverged, runtimeOobiTerminalState } from "../agent-runtime.js";
-import { normalizeCesrBodyMode } from "../cesr-http.js";
-import { sendExchangeMessage } from "../forwarding.js";
-import { OOBI_MAILBOX_TOPIC, OOBI_REQUEST_ROUTE, oobiRequestExn } from "../oobiery.js";
-import { withAgentRuntime, withExistingHab } from "./common/context.js";
+import { parseBooleanOption, parseStringOption } from "../common/parsing.js";
+import { withAgentRuntime, withExistingHab } from "../common/context.js";
 /**
  * Choose one preferred URL from a scheme-keyed location map.
  *
@@ -32,13 +35,13 @@ function canonicalOobiOrigin(url) {
  */
 export function* oobiGenerateCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        role: args.role,
-        compat: args.compat,
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        role: parseStringOption(args.role, "role"),
+        compat: parseBooleanOption(args.compat, "compat"),
     };
     if (!commandArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");
@@ -102,19 +105,19 @@ export function* oobiGenerateCommand(args) {
 /**
  * Implement `tufa oobi resolve` using a command-local shared runtime host.
  *
- * The command queues one OOBI job, runs one runtime turn, and succeeds only if
+ * The command queues one OOBI job, runs the shared workers, and succeeds only if
  * the URL lands in `roobi.`. Any reply/event material fetched from the OOBI is
  * forced through the same parser/routing path used by the long-lived host.
  */
 export function* oobiResolveCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        url: args.url,
-        oobiAlias: args.oobiAlias,
-        compat: args.compat,
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        url: parseStringOption(args.url, "url"),
+        oobiAlias: parseStringOption(args.oobiAlias, "oobiAlias"),
+        compat: parseBooleanOption(args.compat, "compat"),
     };
     if (!commandArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");
@@ -133,8 +136,8 @@ export function* oobiResolveCommand(args) {
             url,
             alias: commandArgs.oobiAlias,
         });
-        yield* processRuntimeUntil(runtime, () => runtimeOobiConverged(runtime, url), { maxTurns: 128, pollMailbox: false });
-        const terminal = runtimeOobiTerminalState(runtime, url);
+        yield* runAgentRuntimeUntil(runtime, () => runtimeOobiConverged(runtime, url), { timeoutMs: 30_000, pollMailbox: false });
+        const terminal = oobiTerminalState(runtime.hby.db, url);
         if (terminal.status === "failed") {
             throw new ValidationError(`OOBI ${url} failed: ${terminal.record?.state ?? "failed"}`);
         }
@@ -149,19 +152,19 @@ export function* oobiResolveCommand(args) {
  *
  * This mirrors KERIpy's `"/oobis"` route while keeping the CLI and transport
  * ownership aligned with other outbound messaging commands.
+ *
+ * @param args Parsed command flags and positionals; required identifiers and policy values are validated before effects.
  */
 export function* oobiRequestCommand(args) {
     const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        recipient: args.recipient,
-        url: args.url,
-        compat: args.compat,
-        outboxer: args.outboxer,
-        cesrBodyMode: normalizeCesrBodyMode(args.cesrBodyMode),
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        recipient: parseStringOption(args.recipient, "recipient"),
+        url: parseStringOption(args.url, "url"),
+        compat: parseBooleanOption(args.compat, "compat"),
     };
     if (!commandArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");
@@ -186,12 +189,10 @@ export function* oobiRequestCommand(args) {
         readonly: false,
         skipConfig: false,
         skipSignator: false,
-        outboxer: commandArgs.outboxer ?? false,
-        cesrBodyMode: commandArgs.cesrBodyMode,
     }, function* ({ hby, hab }) {
         const exn = oobiRequestExn(hab, recipient, url);
-        const { serder } = yield* sendExchangeMessage(hby, hab, {
-            recipient,
+        const { serder } = yield* sendExchangeMessage(hby, hab, new FetchHttpClient(), systemClock, {
+            dest: recipient,
             route: OOBI_REQUEST_ROUTE,
             topic: OOBI_MAILBOX_TOPIC,
             payload: exn.ked?.a ?? {

package/esm/keri/npm/src/{app/cli → cli/identity}/aid.js

@@ -1,14 +1,15 @@
 import { ValidationError } from "../../core/errors.js";
-import { withExistingHab } from "./common/context.js";
+import { withExistingHab } from "../common/context.js";
+import { parseBooleanOption, parseStringOption } from "../common/parsing.js";
 /** Implements `tufa aid`. */
 export function* aidCommand(args) {
     const aidArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        compat: args.compat,
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        compat: parseBooleanOption(args.compat, "compat"),
     };
     if (!aidArgs.name) {
         throw new ValidationError("Name is required and cannot be empty");

package/esm/keri/npm/src/cli/identity/challenge.js

@@ -0,0 +1,181 @@
+import { action, spawn } from "effection";
+import { sendExchangeMessage } from "../../app/exchanges/exchange-messaging.js";
+import { CHALLENGE_RESPONSE_ROUTE, findVerifiedChallengeResponse, formatChallengeWords, generateChallengeWords, markChallengeVerified, parseChallengeWords, } from "../../app/identity/challenging.js";
+import { Organizer } from "../../app/identity/organizing.js";
+import { isLocalGroupHab } from "../../app/multisig/group-members.js";
+import { runAgentRuntime } from "../../app/runtime/agent-runtime.js";
+import { systemClock } from "../../app/runtime/runtime-clock.js";
+import { FetchHttpClient } from "../../app/transport/http-client.js";
+import { ValidationError } from "../../core/errors.js";
+import { parseBooleanOption, parseIntegerOption, parseNumberOption, parseStringOption } from "../common/parsing.js";
+import { withAgentRuntime, withExistingHab } from "../common/context.js";
+/** Implement `tufa challenge generate`. */
+export function* challengeGenerateCommand(args) {
+    const commandArgs = {
+        strength: parseStrength(args.strength),
+        out: parseStringOption(args.out, "out"),
+    };
+    const out = normalizeOutput(commandArgs.out);
+    const words = generateChallengeWords(commandArgs.strength ?? 128);
+    console.log(formatChallengeWords(words, out));
+}
+/**
+ * Implement `tufa challenge respond` by sending a signed `/challenge/response` exchange message.
+ *
+ * @param args Parsed command flags and positionals; required identifiers and policy values are validated before effects.
+ */
+export function* challengeRespondCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        alias: parseStringOption(args.alias, "alias"),
+        recipient: parseStringOption(args.recipient, "recipient"),
+        words: parseStringOption(args.words, "words"),
+        compat: parseBooleanOption(args.compat, "compat"),
+    };
+    if (!commandArgs.name) {
+        throw new ValidationError("Name is required and cannot be empty");
+    }
+    if (!commandArgs.alias) {
+        throw new ValidationError("Alias is required and cannot be empty");
+    }
+    if (!commandArgs.recipient) {
+        throw new ValidationError("Recipient prefix is required.");
+    }
+    if (!commandArgs.words) {
+        throw new ValidationError("Challenge words are required.");
+    }
+    const words = parseChallengeWords(commandArgs.words);
+    if (words.length === 0) {
+        throw new ValidationError("Challenge words must not be empty.");
+    }
+    const recipient = commandArgs.recipient;
+    yield* withExistingHab(commandArgs, commandArgs.alias, {
+        compat: commandArgs.compat ?? false,
+        readonly: false,
+        skipConfig: false,
+        skipSignator: false,
+    }, function* ({ hby, hab }) {
+        if (isLocalGroupHab(hby, hab)) {
+            throw new ValidationError("Challenge respond does not coordinate group approval. Select the responding member alias.");
+        }
+        const payload = { words };
+        const { serder } = yield* sendExchangeMessage(hby, hab, new FetchHttpClient(), systemClock, {
+            dest: recipient,
+            route: CHALLENGE_RESPONSE_ROUTE,
+            topic: "challenge",
+            payload: { i: hab.pre, ...payload },
+        });
+        console.log("Sent EXN message");
+        console.log(serder.pretty());
+    });
+}
+/** Implement `tufa challenge verify` by matching accepted challenge responses in local exchange state. */
+export function* challengeVerifyCommand(args) {
+    const commandArgs = {
+        name: parseStringOption(args.name, "name"),
+        base: parseStringOption(args.base, "base"),
+        headDirPath: parseStringOption(args.headDirPath, "headDirPath"),
+        passcode: parseStringOption(args.passcode, "passcode"),
+        signer: parseStringOption(args.signer, "signer"),
+        words: parseStringOption(args.words, "words"),
+        generate: parseBooleanOption(args.generate, "generate"),
+        strength: parseStrength(args.strength),
+        out: parseStringOption(args.out, "out"),
+        timeout: parseNumberOption(args.timeout, "timeout") ?? 10,
+        compat: parseBooleanOption(args.compat, "compat"),
+        pollDelayMs: parseNumberOption(args.pollDelayMs, "pollDelayMs") ?? 250,
+    };
+    if (!commandArgs.name) {
+        throw new ValidationError("Name is required and cannot be empty");
+    }
+    if (commandArgs.timeout < 0 || !Number.isFinite(commandArgs.timeout * 1000)) {
+        throw new ValidationError("timeout must be finite and nonnegative seconds.");
+    }
+    if (commandArgs.pollDelayMs <= 0) {
+        throw new ValidationError("pollDelayMs must be positive.");
+    }
+    const out = normalizeOutput(commandArgs.out);
+    if (!commandArgs.signer) {
+        throw new ValidationError("Signer identifier or contact alias is required.");
+    }
+    if (!commandArgs.generate && !commandArgs.words) {
+        throw new ValidationError("Challenge words are required.");
+    }
+    const words = commandArgs.generate
+        ? generateChallengeWords(commandArgs.strength ?? 128)
+        : parseChallengeWords(commandArgs.words);
+    if (words.length === 0) {
+        throw new ValidationError("Challenge words must not be empty.");
+    }
+    const signerInput = commandArgs.signer;
+    yield* withAgentRuntime(commandArgs, {
+        compat: commandArgs.compat ?? false,
+        readonly: false,
+        skipConfig: false,
+        skipSignator: true,
+    }, function* ({ hby, runtime }) {
+        const signer = resolveSigner(hby, signerInput);
+        if (commandArgs.generate) {
+            console.log(formatChallengeWords(words, out));
+        }
+        runtime.mailboxDirector.topics.clear();
+        runtime.mailboxDirector.registerTopic("/challenge");
+        const timeoutMs = commandArgs.timeout * 1000;
+        const pollDelayMs = commandArgs.pollDelayMs;
+        const deadline = Date.now() + timeoutMs;
+        let match = findVerifiedChallengeResponse(hby.db, signer, words);
+        if (!match && timeoutMs > 0) {
+            const worker = yield* spawn(() => runAgentRuntime(runtime));
+            try {
+                while (!match && Date.now() < deadline) {
+                    yield* sleep(Math.min(pollDelayMs, Math.max(0, deadline - Date.now())));
+                    match = findVerifiedChallengeResponse(hby.db, signer, words);
+                }
+            }
+            finally {
+                yield* worker.halt();
+            }
+        }
+        if (!match) {
+            throw new ValidationError(`No challenge response from ${signerInput} matched the provided words.`);
+        }
+        markChallengeVerified(hby.db, signer, match);
+        console.log(`${signer} ${match.said}`);
+    });
+}
+function resolveSigner(hby, signer) {
+    if (hby.db.getKever(signer)) {
+        return signer;
+    }
+    const matches = new Organizer(hby.db, hby.signator).findExact("alias", signer);
+    if (matches.length === 0) {
+        throw new ValidationError(`no contact found with alias '${signer}'`);
+    }
+    if (matches.length > 1) {
+        throw new ValidationError(`multiple contacts match alias '${signer}', use prefix instead`);
+    }
+    return matches[0].id;
+}
+function normalizeOutput(input) {
+    const out = input ?? "json";
+    if (out === "json" || out === "string" || out === "words") {
+        return out;
+    }
+    throw new ValidationError(`Unsupported challenge output ${String(input)}.`);
+}
+function* sleep(ms) {
+    yield* action((resolve) => {
+        const timeoutId = setTimeout(() => resolve(undefined), ms);
+        return () => clearTimeout(timeoutId);
+    });
+}
+/** Challenge entropy is a positive whole bit count; omission selects the command default. */
+function parseStrength(value) {
+    const strength = parseIntegerOption(value, "strength") ?? 128;
+    if (strength <= 0)
+        throw new ValidationError("strength must be positive.");
+    return strength;
+}