keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/cli/common/parsing.js

@@ -0,0 +1,279 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { Tholder, Vrsn_1_0, Vrsn_2_0 } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
+/** Keep omission and explicit empty strings distinct; command policy handles emptiness. */
+export function parseStringOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ValidationError(`${flag} must be a string`);
+    return value;
+}
+/** Preserve an omitted flag until command/file precedence and defaults are applied. */
+export function parseBooleanOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new ValidationError(`${flag} must be a boolean`);
+    return value;
+}
+/** Preserve optional decimal quantities while rejecting coercion of booleans, blanks or nonfinite values. */
+export function parseNumberOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) {
+            throw new ValidationError(`${flag} must be a decimal number`);
+        }
+        value = Number(value);
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new ValidationError(`${flag} must be finite`);
+    }
+    return value;
+}
+/** Validate a whole decimal count without collapsing omission or zero. */
+export function parseIntegerOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        if (!/^-?\d+$/.test(value))
+            throw new ValidationError(`${flag} must be a decimal integer`);
+        value = Number(value);
+    }
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new ValidationError(`${flag} must be a safe integer`);
+    }
+    return value;
+}
+/** Validate every list member; an explicit empty list remains an override. */
+export function parseStringListOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new ValidationError(`${flag} must be an array of strings`);
+    }
+    return [...value];
+}
+/** Parse a KLI-style `--version` KERI protocol selection (`1.0` or `2.0`); omission stays undefined. */
+export function parseKeriVersionOption(value, flag = "version") {
+    if (value === undefined)
+        return undefined;
+    if (value === "1.0")
+        return Vrsn_1_0;
+    if (value === "2.0")
+        return Vrsn_2_0;
+    throw new ValidationError(`${flag} must be 1.0 or 2.0`);
+}
+/** Require nonnegative whole counts for key and witness options. */
+export function parseCountOption(value, flag) {
+    const count = parseIntegerOption(value, flag);
+    if (count !== undefined && count < 0)
+        throw new ValidationError(`${flag} must not be negative`);
+    return count;
+}
+/**
+ * Normalize one threshold input from CLI/file JSON into the internal
+ * `ThresholdSith` representation.
+ *
+ * Accepted forms intentionally match the operator-facing KLI shapes:
+ * numeric, hex-string, weighted JSON-array string, or structured array data.
+ */
+export function parseThresholdOption(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new ValidationError("Threshold must be a nonnegative safe integer");
+        }
+        return new Tholder({ sith: value }).sith;
+    }
+    if (typeof value !== "string" && !Array.isArray(value)) {
+        throw new ValidationError("Threshold must be a hex string, number or weighted array");
+    }
+    // Tholder owns weighted syntax, semantic validation and its configurable caps.
+    // JSON is the existing input boundary for arrays, avoiding an unchecked cast.
+    return new Tholder({ sith: typeof value === "string" ? value : JSON.stringify(value) }).sith;
+}
+/**
+ * Parse inline JSON values or `@file` references used by CLI `--data` flags.
+ *
+ * KLI correspondence:
+ * - each `--data` value is interpreted independently
+ * - `@file` values must contain JSON that is inserted as one committed item
+ */
+export function parseDataItems(items) {
+    if (!items || items.length === 0)
+        return [];
+    const out = [];
+    for (const item of items) {
+        if (item.startsWith("@")) {
+            const file = item.slice(1);
+            const text = dntShim.Deno.readTextFileSync(file);
+            out.push(JSON.parse(text));
+            continue;
+        }
+        out.push(JSON.parse(item));
+    }
+    return out;
+}
+/** Load and parse one JSON document from disk without extra schema coercion. */
+function loadJson(path) {
+    return JSON.parse(dntShim.Deno.readTextFileSync(path));
+}
+/** Return true when a string can be losslessly treated as a JSON number literal. */
+function isNumber(value) {
+    if (value.trim().length === 0) {
+        return false;
+    }
+    return !Number.isNaN(Number(value));
+}
+/**
+ * Coerce one EXN `key=value` right-hand side like KERIpy's CLI.
+ *
+ * Plain strings stay strings, while obvious JSON scalars/containers are parsed
+ * into structured values when possible.
+ */
+function coerceExnDataValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")
+        || trimmed === "true" || trimmed === "false" || trimmed === "null"
+        || isNumber(trimmed)) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+/**
+ * Parse KERIpy-style repeatable EXN `--data` items into one payload object.
+ *
+ * Accepted item shapes:
+ * - `@file.json` containing one JSON object
+ * - one inline JSON object string
+ * - repeatable `key=value` items whose values coerce like KERIpy
+ */
+export function parseExnDataItems(items) {
+    if (!items || items.length === 0) {
+        return {};
+    }
+    const data = {};
+    for (const item of items) {
+        if (item === undefined || item === null) {
+            continue;
+        }
+        const trimmed = item.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        if (trimmed.startsWith("@")) {
+            const loaded = loadJson(trimmed.slice(1));
+            if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) {
+                throw new Error("@file must contain a JSON object");
+            }
+            Object.assign(data, loaded);
+            continue;
+        }
+        if (trimmed.startsWith("{")) {
+            const loaded = JSON.parse(trimmed);
+            if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) {
+                throw new Error("JSON must be an object");
+            }
+            Object.assign(data, loaded);
+            continue;
+        }
+        if (!trimmed.includes("=")) {
+            throw new Error(`invalid item '${trimmed}', expected key=value, JSON object, or @file.json`);
+        }
+        const [rawKey, ...rest] = trimmed.split("=");
+        const key = rawKey?.trim() ?? "";
+        if (key.length === 0) {
+            throw new Error(`invalid item '${trimmed}', empty key`);
+        }
+        data[key] = coerceExnDataValue(rest.join("="));
+    }
+    return data;
+}
+/**
+ * Load one JSON file of inception options using the CLI file-input contract.
+ *
+ * Threshold fields are normalized during load so later merge code can operate
+ * on one representation regardless of whether the value came from a file or a
+ * direct CLI flag.
+ */
+export function loadInceptFileOptions(path) {
+    const loaded = loadOptionObject(path);
+    return {
+        transferable: parseBooleanOption(loaded.transferable, "transferable"),
+        wits: parseStringListOption(loaded.wits, "wits"),
+        icount: parseCountOption(loaded.icount, "icount"),
+        isith: parseThresholdOption(loaded.isith),
+        ncount: parseCountOption(loaded.ncount, "ncount"),
+        nsith: parseThresholdOption(loaded.nsith),
+        toad: parseCountOption(loaded.toad, "toad"),
+        estOnly: parseBooleanOption(loaded.estOnly, "estOnly"),
+        data: parseFileData(loaded.data),
+        delpre: parseStringOption(loaded.delpre, "delpre"),
+    };
+}
+/** Load known rotation fields, rejecting malformed values rather than filtering them. */
+export function loadRotateFileOptions(path) {
+    const loaded = loadOptionObject(path);
+    return {
+        isith: parseThresholdOption(loaded.isith),
+        nsith: parseThresholdOption(loaded.nsith),
+        ncount: parseCountOption(loaded.ncount, "ncount"),
+        toad: parseCountOption(loaded.toad, "toad"),
+        wits: parseStringListOption(loaded.wits, "wits"),
+        witsCut: parseStringListOption(loaded.witsCut, "witsCut"),
+        witsAdd: parseStringListOption(loaded.witsAdd, "witsAdd"),
+        data: parseFileData(loaded.data),
+    };
+}
+/** JSON option files are objects; individual command fields are validated by their loaders. */
+export function loadOptionObject(path) {
+    const value = loadJson(path);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ValidationError("Option file must contain a JSON object");
+    }
+    return value;
+}
+/** Anchored JSON data is application-defined, but its outer collection must be an array. */
+export function parseFileData(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new ValidationError("data must be an array");
+    return value;
+}
+/**
+ * Load one required CLI text argument or `@file` reference as UTF-8 bytes.
+ *
+ * This preserves the KLI convention used by `sign` and `verify`: operator
+ * input is always interpreted as text, never raw binary.
+ */
+export function loadTextArgument(text) {
+    const source = text.startsWith("@")
+        ? dntShim.Deno.readTextFileSync(text.slice(1))
+        : text;
+    return new TextEncoder().encode(source);
+}
+/** Require a non-empty string argument (for name, alias, etc.). */
+export function requireText(value, label) {
+    if (!value) {
+        throw new ValidationError(`${label} is required and cannot be empty`);
+    }
+    return value;
+}
+/** Require a non-empty value (void-throwing variant used in several commands). */
+export function requireNonEmpty(value, label) {
+    if (!value) {
+        throw new ValidationError(`${label} is required and cannot be empty.`);
+    }
+}

package/esm/keri/npm/src/cli/common/passcode.js

@@ -0,0 +1,66 @@
+import process from "node:process";
+import password from "@inquirer/password";
+import { abortable } from "../../app/runtime/abortable.js";
+import { ValidationError } from "../../core/errors.js";
+/**
+ * Read one hidden passcode on a real terminal and join prompt teardown.
+ * Noninteractive callers must provide explicit credentials. Ctrl-D and stream
+ * EOF cancel the prompt rather than leaving readline waiting for an answer.
+ */
+export function* readPasscode(message) {
+    if (!process.stdin.isTTY) {
+        throw new ValidationError("Noninteractive input requires --passcode, --aeid with --seed, or --nopasscode");
+    }
+    try {
+        return yield* abortable(async (signal) => {
+            const inputAbort = new AbortController();
+            const input = process.stdin;
+            const wasRaw = input.isRaw ?? false;
+            const promptSignal = AbortSignal.any([signal, inputAbort.signal]);
+            const onEnd = () => inputAbort.abort(new ValidationError("Passcode input ended before submission"));
+            const onKey = (_text, key) => {
+                if (!key.ctrl)
+                    return;
+                if (key.name === "d")
+                    onEnd();
+                if (key.name === "c")
+                    inputAbort.abort(new ValidationError("Passcode input cancelled"));
+            };
+            input.once("end", onEnd);
+            input.once("close", onEnd);
+            input.on("keypress", onKey);
+            try {
+                if (input.readableEnded || input.destroyed)
+                    onEnd();
+                promptSignal.throwIfAborted();
+                return await password({ message, mask: false }, {
+                    output: process.stderr,
+                    signal: promptSignal,
+                    clearPromptOnDone: true,
+                });
+            }
+            catch (error) {
+                // The prompt wraps cancellation; preserve the exact owned reason for
+                // abortable's joined-cleanup filtering. Foreign teardown faults survive.
+                if (promptSignal.aborted && error instanceof Error && error.name === "AbortPromptError"
+                    && error.cause === promptSignal.reason) {
+                    throw promptSignal.reason;
+                }
+                throw error;
+            }
+            finally {
+                input.removeListener("end", onEnd);
+                input.removeListener("close", onEnd);
+                input.removeListener("keypress", onKey);
+                if (input.isTTY && input.isRaw !== wasRaw)
+                    input.setRawMode(wasRaw);
+            }
+        });
+    }
+    catch (cause) {
+        if (cause instanceof Error && cause.name === "ExitPromptError") {
+            throw new ValidationError("Passcode input cancelled", { cause });
+        }
+        throw cause;
+    }
+}

package/esm/keri/npm/src/cli/common/tel-completion.js

@@ -0,0 +1,24 @@
+/** Finite CLI observations over the publication owner's durable facts; host workers make progress. */
+import { sleep } from "effection";
+/** Observe one exact TEL coordinate until completion or an epoch-millisecond deadline; never drive workers here. */
+export function* waitForTelPublication(publication, pre, sn, deadline) {
+    while (!publication.complete(pre, sn)) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        yield* sleep(Math.min(50, remaining));
+    }
+    return true;
+}
+/** Issuance additionally needs saved credential evidence; publication alone is not verifier acceptance. */
+export function* waitForIssuedCredential(publication, said, deadline) {
+    if (!(yield* waitForTelPublication(publication, said, 0, deadline)))
+        return false;
+    while (publication.reger.saved.get(said) === null) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        yield* sleep(Math.min(50, remaining));
+    }
+    return true;
+}

package/esm/keri/npm/src/{app/cli → cli}/common/witness-auth.js

@@ -1,5 +1,5 @@
-import { ValidationError } from "../../../core/errors.js";
-import { makeNowIso8601 } from "../../../time/mod.js";
+import { ValidationError } from "../../core/errors.js";
+import { makeNowIso8601 } from "../../time/mod.js";
 /** Build witness auth payloads from CLI `<witness>:<code>` inputs. */
 export function resolveWitnessAuths(witnesses, codes, options = {}) {
     const now = options.now ?? makeNowIso8601;