keri-ts 0.2.3 → 0.3.0

package/esm/app/cli/command-definitions.js

@@ -1,22 +1,70 @@
 import { agentCommand } from "./agent.js";
 import { annotateCommand } from "./annotate.js";
+import { benchmarkCommand } from "./benchmark.js";
 import { dumpEvts } from "./db-dump.js";
+import { exportCommand } from "./export.js";
+import { inceptCommand } from "./incept.js";
 import { initCommand } from "./init.js";
 import { DISPLAY_VERSION } from "../version.js";
-export function createCoreCommandHandlers() {
+export function createCmdHandlers() {
     return new Map([
         ["init", (args) => initCommand(args)],
+        ["incept", (args) => inceptCommand(args)],
+        ["export", (args) => exportCommand(args)],
         ["agent", (args) => agentCommand(args)],
         ["annotate", (args) => annotateCommand(args)],
+        ["benchmark.cesr", (args) => benchmarkCommand(args)],
         ["db.dump", (args) => dumpEvts(args)],
+        ["interact", interactCommand],
+        ["witness", witnessCommand],
     ]);
 }
-export function registerCoreCommands(program, dispatch) {
+/**
+ * registers core commands with the program
+ */
+export function registerCmds(program, dispatch) {
+    // top level commands
+    regVersionCmd(program);
+    regInitCmd(program, dispatch);
+    regInceptCmd(program, dispatch);
+    regExportCmd(program, dispatch);
+    regAnnotateCmd(program, dispatch);
+    regAgentCmd(program, dispatch);
+    regBenchmarkSubCmd(program, dispatch);
+    // sub commands
+    regDbDumpSubCmd(program, dispatch);
+    regExperimentalSubCmd(program, dispatch);
+}
+/**
+ * Registers the version command with the program.
+ * Equivalent to `kli version` from KERIpy.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regVersionCmd(program) {
+    program
+        .command("version")
+        .description("Show tufa version")
+        .action(() => {
+        console.log(DISPLAY_VERSION);
+        return Promise.resolve();
+    });
+}
+/**
+ * Registers the init command with the program.
+ * Equivalent to `kli init` from KERIpy.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regInitCmd(program, dispatch) {
     program
         .command("init")
         .description("Create a database and keystore")
         .option("-n, --name <name>", "Keystore name and file location of KERI keystore (required)")
         .option("-b, --base <base>", "Additional optional prefix to file location of KERI keystore")
+        .option("--head-dir <dir>", "Directory override for database and keystore root (default fallback: ~/.tufa)")
         .option("-t, --temp", "Create a temporary keystore, used for testing")
         .option("-s, --salt <salt>", "Qualified base64 salt for creating key pairs")
         .option("-c, --config-dir <dir>", "Directory override for configuration data")
@@ -31,6 +79,7 @@ export function registerCoreCommands(program, dispatch) {
             args: {
                 name: options.name,
                 base: options.base,
+                headDirPath: options.headDir,
                 temp: options.temp || false,
                 salt: options.salt,
                 configDir: options.configDir,
@@ -43,6 +92,106 @@ export function registerCoreCommands(program, dispatch) {
         });
         return Promise.resolve();
     });
+}
+/**
+ * Registers the incept command with the program.
+ * Equivalent to `kli incept` from KERIpy.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regInceptCmd(program, dispatch) {
+    program
+        .command("incept")
+        .description("Initialize a prefix")
+        .requiredOption("-n, --name <name>", "Keystore name and file location of KERI keystore")
+        .option("-b, --base <base>", "Additional optional prefix to file location of KERI keystore")
+        .option("--head-dir <dir>", "Directory override for database and keystore root (default fallback: ~/.tufa)")
+        .option("-p, --passcode <passcode>", "Encryption passcode for keystore")
+        .requiredOption("-a, --alias <alias>", "Human readable alias for the new identifier prefix")
+        .option("-f, --file <file>", "Filename to use to create the identifier", "")
+        .option("-tf, --transferable", "Whether the prefix is transferable or non-transferable")
+        .option("-w, --wits <prefix>", "New set of witnesses, replaces all existing witnesses", (value, prev = []) => {
+        prev.push(value);
+        return prev;
+    }, [])
+        .option("-t, --toad <toad>", "Witness threshold (threshold of accountable duplicity)", (value) => Number(value))
+        .option("-ic, --icount <count>", "Incepting key count for number of keys used for inception", (value) => Number(value))
+        .option("-s, --isith <isith>", "Signing threshold for the inception event")
+        .option("-nc, --ncount <count>", "Next key count for number of next keys used on first rotation", (value) => Number(value))
+        .option("-x, --nsith <nsith>", "Signing threshold for the next rotation")
+        .option("-e, --est-only", "Only allow establishment events in KEL")
+        .option("-d, --data <data>", "Anchor data, '@' allowed", (value, prev = []) => {
+        prev.push(value);
+        return prev;
+    }, [])
+        .option("-di, --delpre <prefix>", "Delegator AID for delegated identifiers")
+        .action((options) => {
+        dispatch({
+            name: "incept",
+            args: {
+                name: options.name,
+                base: options.base,
+                headDirPath: options.headDir,
+                passcode: options.passcode,
+                alias: options.alias,
+                file: options.file,
+                transferable: options.transferable || false,
+                wits: options.wits || [],
+                toad: options.toad,
+                icount: options.icount,
+                isith: options.isith,
+                ncount: options.ncount,
+                nsith: options.nsith,
+                estOnly: options.estOnly || false,
+                data: options.data || [],
+                delpre: options.delpre,
+            },
+        });
+        return Promise.resolve();
+    });
+}
+/**
+ * Registers the export command with the program.
+ * Equivalent to `kli export` from KERIpy.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regExportCmd(program, dispatch) {
+    program
+        .command("export")
+        .description("Export key events in CESR stream format")
+        .requiredOption("-n, --name <name>", "Keystore name")
+        .requiredOption("-a, --alias <alias>", "Human readable alias for identifier to export")
+        .option("-b, --base <base>", "Optional base path prefix")
+        .option("--head-dir <dir>", "Directory override for database and keystore root (default fallback: ~/.tufa)")
+        .option("-p, --passcode <passcode>", "Encryption passcode for keystore")
+        .option("--files", "Export artifacts to individual files")
+        .option("--ends", "Export service end points")
+        .action((options) => {
+        dispatch({
+            name: "export",
+            args: {
+                name: options.name,
+                alias: options.alias,
+                base: options.base,
+                headDirPath: options.headDir,
+                passcode: options.passcode,
+                files: options.files || false,
+                ends: options.ends || false,
+            },
+        });
+        return Promise.resolve();
+    });
+}
+/**
+ * Registers the annotate command with the program.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regAnnotateCmd(program, dispatch) {
     program
         .command("annotate")
         .description("Annotate CESR stream from file or stdin")
@@ -62,6 +211,14 @@ export function registerCoreCommands(program, dispatch) {
         });
         return Promise.resolve();
     });
+}
+/**
+ * Registers the agent command with the program.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regAgentCmd(program, dispatch) {
     program
         .command("agent")
         .description("Start the KERI agent server")
@@ -76,7 +233,69 @@ export function registerCoreCommands(program, dispatch) {
         });
         return Promise.resolve();
     });
+}
+/**
+ * Registers benchmark subcommands with the program.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regBenchmarkSubCmd(program, dispatch) {
+    const benchmarkCommand = program.command("benchmark").description("Benchmark operations");
+    regBenchmarkCesrCmd(benchmarkCommand, dispatch);
+}
+/**
+ * Registers the CESR benchmark command.
+ *
+ * @param benchmarkCommand The benchmark sub-command instance
+ * @param dispatch The command dispatch function
+ */
+function regBenchmarkCesrCmd(benchmarkCommand, dispatch) {
+    benchmarkCommand
+        .command("cesr")
+        .description("Benchmark CESR parser from file or stdin")
+        .option("--in <path>", "Input file path (defaults to stdin)")
+        .option("--iterations <count>", "Measured benchmark iterations", (value) => Number(value), 50)
+        .option("--warmup <count>", "Warmup iterations before measurement", (value) => Number(value), 5)
+        .option("--chunk-size <bytes>", "Chunk size for simulated streaming input", (value) => Number(value), 0)
+        .option("--framed", "Use framed parser mode")
+        .option("--compat", "Use compat attachment dispatch mode")
+        .option("--allow-errors", "Do not fail benchmark if parse errors are emitted")
+        .option("--json", "Emit benchmark result as one JSON line")
+        .action((options) => {
+        dispatch({
+            name: "benchmark.cesr",
+            args: {
+                inPath: options.in,
+                iterations: options.iterations,
+                warmupIterations: options.warmup,
+                chunkSize: options.chunkSize,
+                framed: options.framed || false,
+                compat: options.compat || false,
+                allowErrors: options.allowErrors || false,
+                json: options.json || false,
+            },
+        });
+        return Promise.resolve();
+    });
+}
+/**
+ * Registers the db dump sub command with the program.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regDbDumpSubCmd(program, dispatch) {
     const dbCommand = program.command("db").description("Database operations");
+    regDbDumpCmd(dbCommand, dispatch);
+}
+/**
+ * Registers the db dump command with the program.
+ *
+ * @param dbCommand The db sub-command instance
+ * @param dispatch The command dispatch function
+ */
+function regDbDumpCmd(dbCommand, dispatch) {
     dbCommand
         .command("dump")
         .description("Dump database contents")
@@ -94,11 +313,44 @@ export function registerCoreCommands(program, dispatch) {
         });
         return Promise.resolve();
     });
-    program
-        .command("version")
-        .description("Show tufa version")
+}
+/**
+ * Registers the experimental sub command with the program.
+ * This is for commands not yet implemented, finished, or supported by tufa.
+ *
+ * @param program The tufa Commander program instance
+ * @param dispatch The command dispatch function
+ */
+function regExperimentalSubCmd(program, dispatch) {
+    const experimentalCommand = program
+        .command("experimental")
+        .description("Experimental or placeholder commands");
+    regInteractCmd(experimentalCommand, dispatch);
+    regWitnessCmd(experimentalCommand, dispatch);
+}
+function regInteractCmd(experimentalCommand, dispatch) {
+    experimentalCommand
+        .command("interact")
+        .description("Create an interaction event (placeholder)")
         .action(() => {
-        console.log(DISPLAY_VERSION);
+        dispatch({ name: "interact", args: {} });
         return Promise.resolve();
     });
 }
+function regWitnessCmd(experimentalCommand, dispatch) {
+    experimentalCommand
+        .command("witness")
+        .description("Start a witness server (placeholder)")
+        .action(() => {
+        dispatch({ name: "witness", args: {} });
+        return Promise.resolve();
+    });
+}
+// deno-lint-ignore require-yield
+function* interactCommand(_args) {
+    console.log("tufa experimental interact command - coming soon!");
+}
+// deno-lint-ignore require-yield
+function* witnessCommand(_args) {
+    console.log("tufa experimental witness command - coming soon!");
+}

package/esm/app/cli/common/existing.js

@@ -0,0 +1,40 @@
+import { createKeeper } from "../../../db/keeping.js";
+import { createHabery } from "../../habbing.js";
+export function* setupHby(name, base = "", bran, temp = false, headDirPath) {
+    const ks = yield* createKeeper({
+        name,
+        base,
+        temp,
+        headDirPath,
+        reopen: true,
+        readonly: true,
+    });
+    const aeid = ks.getGbls("aeid");
+    yield* ks.close();
+    if (aeid === null) {
+        throw new Error("Keystore must already exist, exiting");
+    }
+    let retries = 0;
+    let passcode = bran;
+    while (true) {
+        try {
+            retries += 1;
+            return yield* createHabery({
+                name,
+                base,
+                temp,
+                headDirPath,
+                bran: passcode?.replaceAll("-", ""),
+            });
+        }
+        catch (error) {
+            if (retries >= 3) {
+                throw new Error("too many attempts");
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            console.log(message);
+            console.log("Valid passcode required, try again...");
+            passcode = prompt("Passcode: ") ?? undefined;
+        }
+    }
+}

package/esm/app/cli/common/parsing.js

@@ -0,0 +1,20 @@
+import * as dntShim from "../../../_dnt.shims.js";
+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;
+}
+export function loadInceptFileOptions(path) {
+    const text = dntShim.Deno.readTextFileSync(path);
+    return JSON.parse(text);
+}

package/esm/app/cli/export.js

@@ -0,0 +1,51 @@
+import { createQueue, spawn } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { setupHby } from "./common/existing.js";
+/**
+ * Implements `tufa export`.
+ *
+ * Exports CESR-formatted KEL events for a named local AID.
+ */
+export function* exportCommand(args) {
+    const exportArgs = {
+        name: args.name,
+        base: args.base,
+        headDirPath: args.headDirPath,
+        passcode: args.passcode,
+        alias: args.alias,
+        files: args.files,
+        ends: args.ends,
+    };
+    if (!exportArgs.name) {
+        throw new ValidationError("Name is required and cannot be empty");
+    }
+    if (!exportArgs.alias) {
+        throw new ValidationError("Alias is required and cannot be empty");
+    }
+    const cues = createQueue();
+    const doer = yield* spawn(function* () {
+        const hby = yield* setupHby(exportArgs.name, exportArgs.base ?? "", exportArgs.passcode, false, exportArgs.headDirPath);
+        try {
+            const hab = hby.habByName(exportArgs.alias);
+            if (!hab || !hab.pre) {
+                throw new ValidationError(`No local AID found for alias ${exportArgs.alias}`);
+            }
+            const encoder = new TextEncoder();
+            const keyPrefix = encoder.encode(`${hab.pre}:`);
+            const decoder = new TextDecoder();
+            let count = 0;
+            for (const [, value] of hby.db.getAllEvtsIter(keyPrefix)) {
+                console.log(decoder.decode(value));
+                count += 1;
+            }
+            cues.add({ kin: "export", count, mode: "native" });
+        }
+        finally {
+            yield* hby.close();
+        }
+    });
+    yield* doer;
+    const cue = yield* cues.next();
+    if (cue.done)
+        return;
+}

package/esm/app/cli/incept.js

@@ -0,0 +1,106 @@
+import { createQueue, spawn } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { setupHby } from "./common/existing.js";
+import { loadInceptFileOptions, parseDataItems, } from "./common/parsing.js";
+/**
+ * Loads incept options from a file and overlays explicit CLI values.
+ */
+function mergeWithFile(args) {
+    let opts = {};
+    if (args.file && args.file !== "") {
+        opts = loadInceptFileOptions(args.file);
+    }
+    if (args.transferable !== undefined)
+        opts.transferable = args.transferable;
+    if (args.wits && args.wits.length > 0)
+        opts.wits = args.wits;
+    if (args.icount !== undefined)
+        opts.icount = Number(args.icount);
+    if (args.isith !== undefined)
+        opts.isith = args.isith;
+    if (args.ncount !== undefined)
+        opts.ncount = Number(args.ncount);
+    if (args.nsith !== undefined)
+        opts.nsith = args.nsith;
+    if (args.toad !== undefined)
+        opts.toad = Number(args.toad);
+    if (args.estOnly !== undefined)
+        opts.estOnly = args.estOnly;
+    if (args.delpre !== undefined)
+        opts.delpre = args.delpre;
+    if (args.data !== undefined)
+        opts.data = parseDataItems(args.data);
+    return opts;
+}
+/**
+ * Implements `tufa incept`.
+ *
+ * Creates a single-sig identifier locally.
+ */
+export function* inceptCommand(args) {
+    const inceptArgs = {
+        name: args.name,
+        base: args.base,
+        headDirPath: args.headDirPath,
+        temp: args.temp,
+        passcode: args.passcode,
+        alias: args.alias,
+        endpoint: args.endpoint,
+        proxy: args.proxy,
+        file: args.file,
+        transferable: args.transferable,
+        wits: args.wits,
+        toad: args.toad,
+        icount: args.icount,
+        isith: args.isith,
+        ncount: args.ncount,
+        nsith: args.nsith,
+        estOnly: args.estOnly,
+        data: args.data,
+        delpre: args.delpre,
+    };
+    if (!inceptArgs.name) {
+        throw new ValidationError("Name is required and cannot be empty");
+    }
+    if (!inceptArgs.alias) {
+        throw new ValidationError("Alias is required and cannot be empty");
+    }
+    if (inceptArgs.endpoint) {
+        throw new ValidationError("Witness endpoint receipting is not available in single-sig local phase");
+    }
+    if (inceptArgs.proxy) {
+        throw new ValidationError("Delegation proxy flow is not available in single-sig local phase");
+    }
+    const opts = mergeWithFile(inceptArgs);
+    const cues = createQueue();
+    const doer = yield* spawn(function* () {
+        const hby = yield* setupHby(inceptArgs.name, inceptArgs.base ?? "", inceptArgs.passcode, inceptArgs.temp ?? false, inceptArgs.headDirPath);
+        try {
+            const hab = hby.makeHab(inceptArgs.alias, undefined, {
+                transferable: opts.transferable ?? false,
+                wits: opts.wits ?? [],
+                toad: opts.toad ?? 0,
+                icount: opts.icount ?? 1,
+                isith: opts.isith,
+                ncount: opts.ncount ?? 1,
+                nsith: opts.nsith,
+                estOnly: opts.estOnly ?? false,
+                data: opts.data ?? [],
+                delpre: opts.delpre,
+            });
+            console.log(`Prefix  ${hab.pre}`);
+            for (const [idx, key] of (hab.kever?.verfers ?? []).entries()) {
+                console.log(`\tPublic key ${idx + 1}:  ${key}`);
+            }
+            console.log("");
+            cues.add({ kin: "incept", pre: hab.pre, mode: "native" });
+        }
+        finally {
+            yield* hby.close();
+        }
+    });
+    yield* doer;
+    const cue = yield* cues.next();
+    if (cue.done)
+        return;
+}

package/esm/app/cli/index.js

@@ -4,4 +4,6 @@
  * This module provides the KERI TypeScript CLI interface.
  */
 export { tufa } from "./cli.js";
+export { exportCommand } from "./export.js";
 export { initCommand } from "./init.js";
+export { inceptCommand } from "./incept.js";

package/esm/app/cli/init.js

@@ -1,36 +1,18 @@
-import { ValidationError } from "../../core/errors.js";
-function printInitHelp() {
-    console.log(`
-tufa init - Create a database and keystore
-
-Usage: tufa init [options]
-
-Options:
-  --name, -n <name>           Keystore name and file location of KERI keystore (required)
-  --base, -b <base>           Additional optional prefix to file location of KERI keystore
-  --temp, -t                  Create a temporary keystore, used for testing
-  --salt, -s <salt>           Qualified base64 salt for creating key pairs
-  --config-dir, -c <dir>      Directory override for configuration data
-  --config-file <file>        Configuration filename override
-  --passcode, -p <passcode>   22 character encryption passcode for keystore (is not saved)
-  --nopasscode                Create an unencrypted keystore
-  --aeid, -a <aeid>           Qualified base64 of non-transferable identifier prefix for authentication and encryption of secrets in keystore
-  --seed, -e <seed>           Qualified base64 private-signing key (seed) for the aeid from which the private decryption key may be derived
-  --help, -h                  Show this help message
-`);
-}
-// TODO remove this ignore once init is finished
-// deno-lint-ignore require-yield
+import { createQueue, spawn } from "effection";
+import { PathError, ValidationError } from "../../core/errors.js";
+import { createConfiger } from "../configing.js";
+import { createHabery } from "../habbing.js";
+/**
+ * Implements `tufa init`.
+ *
+ * Creates/open a habery keystore and database.
+ */
 export function* initCommand(args) {
-    // Check for help flag
-    if (args.help || args.h) {
-        printInitHelp();
-        return;
-    }
-    // Extract values from args (already parsed by Cliffy or test mocks)
+    // Extract values from args
     const initArgs = {
         name: args.name,
         base: args.base,
+        headDirPath: args.headDirPath,
         temp: args.temp,
         salt: args.salt,
         configDir: args.configDir,
@@ -46,10 +28,9 @@ export function* initCommand(args) {
         throw new ValidationError("Name is required and cannot be empty");
     }
     const base = initArgs.base || "";
+    const headDirPath = initArgs.headDirPath;
     const temp = initArgs.temp || false;
     let bran = initArgs.passcode;
-    const configFile = initArgs.configFile;
-    const configDir = initArgs.configDir;
     const nopasscode = initArgs.nopasscode || false;
     // Handle passcode input if not provided and not using nopasscode
     if (!nopasscode && !bran) {
@@ -63,14 +44,64 @@ export function* initCommand(args) {
         }
         bran = passcode || undefined;
     }
-    // TODO: Implement actual keystore and database creation
-    // This is a stub implementation that mirrors the KERIpy structure
-    console.log("KERI Keystore created at: [stub - keystore path]");
-    console.log("KERI Database created at: [stub - database path]");
-    console.log("KERI Credential Store created at: [stub - credential store path]");
-    if (initArgs.aeid) {
-        console.log("\taeid:", initArgs.aeid);
-    }
-    console.log("\nInitialization complete!");
-    console.log("Note: This is a stub implementation. Full keystore and database creation will be implemented in future versions.");
+    const cues = createQueue();
+    const doer = yield* spawn(function* () {
+        const cf = initArgs.configFile
+            ? (yield* createConfiger({
+                name: initArgs.configFile,
+                base: "",
+                temp: false,
+                headDirPath: initArgs.configDir,
+                reopen: true,
+                clear: false,
+            }))
+            : undefined;
+        let hby;
+        try {
+            hby = yield* createHabery({
+                name,
+                base,
+                headDirPath,
+                temp,
+                cf,
+                bran: bran ?? undefined,
+                aeid: initArgs.aeid,
+                seed: initArgs.seed,
+                salt: initArgs.salt,
+            });
+        }
+        catch (error) {
+            if (temp || !(error instanceof PathError)) {
+                throw error;
+            }
+            console.log("Persistent keystore path unavailable, retrying with temporary keystore mode.");
+            hby = yield* createHabery({
+                name,
+                base,
+                headDirPath,
+                temp: true,
+                cf,
+                bran: bran ?? undefined,
+                aeid: initArgs.aeid,
+                seed: initArgs.seed,
+                salt: initArgs.salt,
+            });
+        }
+        try {
+            console.log("KERI Keystore created at:", hby.ks.path);
+            console.log("KERI Database created at:", hby.db.path);
+            console.log("KERI Credential Store created at:", hby.db.path);
+            if (hby.mgr.aeid) {
+                console.log("\taeid:", hby.mgr.aeid);
+            }
+            cues.add({ kin: "init", mode: "native", name });
+        }
+        finally {
+            yield* hby.close();
+        }
+    });
+    yield* doer;
+    const cue = yield* cues.next();
+    if (cue.done)
+        return;
 }