keri-ts 0.1.0

package/esm/app/cli/cli.js

@@ -0,0 +1,195 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { Command } from "commander";
+import { action } from "effection";
+import { agentCommand } from "./agent.js";
+import { dumpEvts } from "./db-dump.js";
+import { initCommand } from "./init.js";
+/**
+ * Promise to Structured Concurrency Helper: Convert Promise to Effection Operation
+ * This allows us to integrate promise-based APIs (like Commander) into Effection's structured concurrency
+ */
+function* toOp(promise) {
+    return yield* action((resolve, reject) => {
+        promise.then(resolve, reject);
+        return () => { }; // Cleanup function (can add abort logic if needed)
+    });
+}
+/**
+ * Create the CLI program with action handlers that signal command execution
+ */
+function createCLIProgram(context) {
+    const program = new Command();
+    program.name("kli").version("0.0.2").description("KERI TypeScript CLI");
+    // Prevent Commander from exiting automatically so we can run Effection operations
+    program.exitOverride();
+    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("-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")
+        .option("--config-file <file>", "Configuration filename override")
+        .option("-p, --passcode <passcode>", "22 character encryption passcode for keystore (is not saved)")
+        .option("--nopasscode", "Create an unencrypted keystore")
+        .option("-a, --aeid <aeid>", "Qualified base64 of non-transferable identifier prefix for authentication and encryption of secrets in keystore")
+        .option("-e, --seed <seed>", "Qualified base64 private-signing key (seed) for the aeid from which the private decryption key may be derived")
+        .action((options) => {
+        // Store command info in context for execution within Effection
+        context.command = "init";
+        context.args = {
+            name: options.name,
+            base: options.base,
+            temp: options.temp || false,
+            salt: options.salt,
+            configDir: options.configDir,
+            configFile: options.configFile,
+            passcode: options.passcode,
+            nopasscode: options.nopasscode || false,
+            aeid: options.aeid,
+            seed: options.seed,
+        };
+        // Return immediately - actual execution happens in kli operation
+        return Promise.resolve();
+    });
+    program
+        .command("agent")
+        .description("Start the KERI agent server")
+        .option("-p, --port <port>", "Port number for the server (default: 8000)", "8000")
+        .action(function () {
+        const options = this.opts();
+        context.command = "agent";
+        context.args = {
+            port: options.port ? Number(options.port) : 8000,
+        };
+        return Promise.resolve();
+    });
+    program
+        .command("incept")
+        .description("Create a new identifier")
+        .action(() => {
+        context.command = "incept";
+        context.args = {};
+        return Promise.resolve();
+    });
+    program
+        .command("rotate")
+        .description("Rotate keys for an identifier")
+        .action(() => {
+        context.command = "rotate";
+        context.args = {};
+        return Promise.resolve();
+    });
+    program
+        .command("interact")
+        .description("Create an interaction event")
+        .action(() => {
+        context.command = "interact";
+        context.args = {};
+        return Promise.resolve();
+    });
+    program
+        .command("witness")
+        .description("Start a witness server")
+        .action(() => {
+        context.command = "witness";
+        context.args = {};
+        return Promise.resolve();
+    });
+    // Create db command with dump subcommand using chained .command() pattern
+    const dbCommand = program.command("db").description("Database operations");
+    dbCommand
+        .command("dump")
+        .description("Dump database contents")
+        .requiredOption("-n, --name <name>", "Database name")
+        .option("-b, --base <base>", "Additional optional prefix to database path")
+        .option("-t, --temp", "Use temporary database")
+        .action((options) => {
+        context.command = "db.dump";
+        context.args = {
+            name: options.name,
+            base: options.base,
+            temp: options.temp || false,
+        };
+        return Promise.resolve();
+    });
+    return program;
+}
+/**
+ * Stub command operations (to be implemented)
+ * These are placeholder operations that will be fully implemented later
+ */
+// deno-lint-ignore require-yield
+function* inceptCommand(_args) {
+    console.log("kli incept command - coming soon!");
+}
+// deno-lint-ignore require-yield
+function* rotateCommand(_args) {
+    console.log("kli rotate command - coming soon!");
+}
+// deno-lint-ignore require-yield
+function* interactCommand(_args) {
+    console.log("kli interact command - coming soon!");
+}
+// deno-lint-ignore require-yield
+function* witnessCommand(_args) {
+    console.log("kli witness command - coming soon!");
+}
+/**
+ * Command handler registry - maps command names to Effection operations
+ */
+const commandHandlers = new Map([
+    ["init", (args) => initCommand(args)],
+    ["agent", (args) => agentCommand(args)],
+    ["incept", (args) => inceptCommand(args)],
+    ["rotate", (args) => rotateCommand(args)],
+    ["interact", (args) => interactCommand(args)],
+    ["witness", (args) => witnessCommand(args)],
+    ["db.dump", (args) => dumpEvts(args)],
+]);
+/**
+ * Main CLI operation - runs within Effection's structured concurrency
+ * This is the outermost runtime, not JavaScript's event loop
+ */
+export function* kli(args = []) {
+    // Create a context for command execution
+    const context = {};
+    // Use Commander.js for all command parsing
+    const program = createCLIProgram(context);
+    try {
+        // Parse arguments - Commander expects full argv or args array
+        // In Deno, Deno.args gives us the arguments without the executable info
+        const argsToParse = args.length > 0 ? args : dntShim.Deno.args;
+        program.parse(argsToParse, { from: "user" });
+    }
+    catch (error) {
+        // Handle Commander-specific errors
+        if (error && typeof error === "object" && "code" in error) {
+            const commanderError = error;
+            // Help was requested - Commander already printed it, just return
+            if (commanderError.code === "commander.help" ||
+                commanderError.code === "commander.helpDisplayed") {
+                return;
+            }
+            // Unknown command or other parsing errors - Commander already printed the error
+            if (commanderError.code === "commander.unknownCommand" ||
+                commanderError.code === "commander.missingArgument") {
+                // Commander already printed the error message, just exit gracefully
+                return;
+            }
+        }
+        // For other errors, log and rethrow
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        throw error;
+    }
+    // Execute the appropriate command operation based on context
+    if (context.command && context.args) {
+        const handler = commandHandlers.get(context.command);
+        if (handler) {
+            // Execute the command operation within Effection's structured concurrency
+            yield* handler(context.args);
+        }
+    }
+}

package/esm/app/cli/db-dump.js

@@ -0,0 +1,68 @@
+/**
+ * Database dump command for CLI
+ *
+ * Dumps the contents of Baser.evts sub-database to console in prettified table format
+ */
+import { displayStr } from "../../core/bytes.js";
+import { createBaser } from "../../db/basing.js";
+/**
+ * Dump the evts sub-database to console
+ */
+export function* dumpEvts(args) {
+    const name = args.name;
+    const base = args.base;
+    const temp = args.temp;
+    const readonly = true; // Always open readonly for dump
+    if (!name) {
+        console.error("Error: --name is required");
+        return;
+    }
+    console.log(`Dumping database ${name} from ${base} in temp mode: ${temp}`);
+    const options = {
+        name,
+        base,
+        temp,
+        reopen: true,
+        readonly,
+        dupsort: false,
+    };
+    const baser = yield* createBaser(options);
+    try {
+        // get database version
+        const version = baser.getVer();
+        console.log(`Database version: ${version}`);
+        // Get count
+        const count = baser.cntEvts();
+        console.log(`\nBaser.evts sub-database dump (${count} entries)\n`);
+        console.log("=".repeat(137));
+        // Print header
+        console.log(`${"Key".padEnd(89)} | ${"Value (UTF-8)".padEnd(45)}`);
+        console.log("-".repeat(137));
+        // Iterate and print entries (empty top = all items)
+        const iter = baser.getAllEvtsIter(new Uint8Array(0));
+        let entryCount = 0;
+        let keyColSize = 50;
+        let valColSize = 50;
+        for (const [keyBytes, valBytes] of iter) {
+            entryCount++;
+            const keyStr = displayStr(keyBytes);
+            if (keyStr.length > keyColSize) {
+                keyColSize = keyStr.length;
+            }
+            const valStr = displayStr(valBytes, 45);
+            if (valStr.length > valColSize) {
+                valColSize = valStr.length;
+            }
+            console.log(`${keyStr.padEnd(50)} | ${valStr.padEnd(45)}`);
+        }
+        console.log("=".repeat(137));
+        console.log(`\nTotal entries: ${entryCount}`);
+    }
+    catch (error) {
+        console.error(`Error dumping database: ${error}`);
+        throw error;
+    }
+    finally {
+        yield* baser.close();
+    }
+}

package/esm/app/cli/init.js

@@ -0,0 +1,75 @@
+function printInitHelp() {
+    console.log(`
+kli init - Create a database and keystore
+
+Usage: kli 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
+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)
+    const initArgs = {
+        name: args.name,
+        base: args.base,
+        temp: args.temp,
+        salt: args.salt,
+        configDir: args.configDir,
+        configFile: args.configFile,
+        passcode: args.passcode,
+        nopasscode: args.nopasscode,
+        aeid: args.aeid,
+        seed: args.seed,
+    };
+    // Validate required name
+    const name = initArgs.name;
+    if (!name || name === "") {
+        throw new Error("Name is required and cannot be empty");
+    }
+    const base = initArgs.base || "";
+    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) {
+        console.log("Creating encrypted keystore, please enter your 22 character passcode:");
+        // For now, we'll use a simple prompt since Deno doesn't have getpass equivalent
+        // In a real implementation, you'd want to use a proper password input library
+        const passcode = prompt("Passcode: ");
+        const retry = prompt("Re-enter passcode: ");
+        if (passcode !== retry) {
+            throw new Error("Passcodes do not match");
+        }
+        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.");
+}

package/esm/app/server.js

@@ -0,0 +1,77 @@
+import * as dntShim from "../_dnt.shims.js";
+import { action } from "effection";
+import { openDB, readValue, writeValue } from "../db/core/db.js";
+/**
+ * Start HTTP server with Effection as the outermost runtime.
+ * Each request is spawned as a separate Effection task, ensuring
+ * proper structured concurrency and cleanup.
+ */
+export function* startServer(port = 8000) {
+    // openDB is synchronous, so call it directly
+    let db;
+    try {
+        db = openDB();
+    }
+    catch (error) {
+        console.error("Error opening database:", error);
+        throw error;
+    }
+    // Use Deno.serve
+    return yield* action((resolve, reject) => {
+        const controller = new AbortController();
+        const { signal } = controller;
+        const server = dntShim.Deno.serve({
+            port,
+            hostname: "127.0.0.1",
+            signal,
+            onListen: ({ port }) => console.log(`Server running on http://localhost:${port}`),
+            onError: (error) => {
+                console.error("Server error:", error);
+                return new Response("Internal Server Error", { status: 500 });
+            },
+        }, (req) => {
+            try {
+                const url = new URL(req.url);
+                if (url.pathname.startsWith("/echo/")) {
+                    // Extract value from path (everything after "/echo/")
+                    let val = url.pathname.slice(6); // Trim '/echo/'
+                    // If no value in path, read from database
+                    if (!val) {
+                        const oldVal = readValue(db, "echo");
+                        val = oldVal ? oldVal : "initial echo";
+                    }
+                    // Write the value to database (persist it)
+                    writeValue(db, "echo", val);
+                    return new Response(val, {
+                        status: 200,
+                        headers: { "Content-Type": "text/plain" },
+                    });
+                }
+                else {
+                    return new Response("Not Found", {
+                        status: 404,
+                        headers: { "Content-Type": "text/plain" },
+                    });
+                }
+            }
+            catch (error) {
+                return new Response(String(error), { status: 500 });
+            }
+        });
+        // Wait for server to finish
+        server.finished.then(resolve).catch(reject);
+        // Graceful shutdown logic using signals
+        const shutdown = () => {
+            console.log("Shutting down server...");
+            controller.abort();
+        };
+        // Deno signal listeners
+        dntShim.Deno.addSignalListener("SIGINT", shutdown);
+        dntShim.Deno.addSignalListener("SIGTERM", shutdown);
+        return () => {
+            dntShim.Deno.removeSignalListener("SIGINT", shutdown);
+            dntShim.Deno.removeSignalListener("SIGTERM", shutdown);
+            controller.abort();
+        };
+    });
+}

package/esm/core/bytes.js

@@ -0,0 +1,39 @@
+/**
+ * Check if keyBytes starts with prefixBytes
+ */
+export function startsWith(keyBytes, prefixBytes) {
+    if (prefixBytes.length === 0) {
+        return true; // Empty prefix matches everything
+    }
+    if (keyBytes.length < prefixBytes.length) {
+        return false;
+    }
+    return prefixBytes.every((byte, i) => keyBytes[i] === byte);
+}
+/**
+ * Convert bytes to a displayable string for terminal output.
+ *
+ * Decodes bytes as UTF-8 and replaces non-printable control characters
+ * with '.' for readable terminal display. UTF-8 can represent control
+ * characters (like \x00, \x09, \x0A) which are valid but not printable.
+ *
+ * @param bytes - Bytes to convert to display string
+ * @param maxLength - Optional maximum length; if exceeded, truncates and adds "..."
+ * @returns Displayable string with control characters replaced
+ */
+export function displayStr(bytes, maxLength) {
+    try {
+        const decoder = new TextDecoder("utf-8", { fatal: false });
+        let str = decoder.decode(bytes);
+        // Replace control characters (non-printable) for readable terminal output
+        str = str.replace(/[\x00-\x1F\x7F-\x9F]/g, ".");
+        // Truncate if maxLength is specified
+        if (maxLength !== undefined && str.length > maxLength) {
+            str = str.substring(0, maxLength - 3) + "...";
+        }
+        return str;
+    }
+    catch {
+        return `[${bytes.length} bytes]`;
+    }
+}

package/esm/core/errors.js

@@ -0,0 +1,26 @@
+export class AppError extends Error {
+    constructor(message, context) {
+        super(message);
+        Object.defineProperty(this, "context", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: context
+        });
+        this.name = globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).name;
+    }
+}
+export class ValidationError extends AppError {
+}
+export class PathError extends AppError {
+}
+export class InvalidPathNameError extends ValidationError {
+}
+export class DatabaseError extends AppError {
+}
+export class DatabaseNotOpenError extends DatabaseError {
+}
+export class DatabaseKeyError extends DatabaseError {
+}
+export class DatabaseOperationError extends DatabaseError {
+}

package/esm/core/index.js

@@ -0,0 +1,7 @@
+/**
+ * Core module - public API
+ *
+ * This module will contain core KERI types (future).
+ */
+export * from "./bytes.js";
+export * from "./errors.js";

package/esm/db/basing.js

@@ -0,0 +1,168 @@
+/**
+ * Baser - KERI Event Log Database
+ *
+ * Manages KEL events and related data using composition with LMDBer.
+ * Sets up named sub-databases for key event logs.
+ */
+import { DatabaseNotOpenError, DatabaseOperationError, } from "../core/errors.js";
+import { LMDBer } from "./core/lmdber.js";
+/**
+ * Baser manages KERI event logs
+ * Uses composition with LMDBer instead of inheritance
+ */
+export class Baser {
+    constructor(options = {}) {
+        Object.defineProperty(this, "lmdber", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Named sub-databases
+        Object.defineProperty(this, "evts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        }); // Events sub-database (dgKey: serialized KEL events)
+        // Create LMDBer with composition
+        this.lmdber = new LMDBer(options, {
+            tailDirPath: Baser.TailDirPath,
+            altTailDirPath: Baser.AltTailDirPath,
+            tempPrefix: Baser.TempPrefix,
+            maxNamedDBs: Baser.MaxNamedDBs,
+        });
+    }
+    get name() {
+        return this.lmdber.name;
+    }
+    get base() {
+        return this.lmdber.base;
+    }
+    get opened() {
+        return this.lmdber.opened;
+    }
+    get temp() {
+        return this.lmdber.temp;
+    }
+    get path() {
+        return this.lmdber.path;
+    }
+    get env() {
+        return this.lmdber.env;
+    }
+    /**
+     * Reopen the database and initialize sub-databases
+     */
+    *reopen(options = {}) {
+        const opened = yield* this.lmdber.reopen(options);
+        if (!opened) {
+            return false;
+        }
+        // Open named sub-databases
+        // Names end with "." to avoid namespace collisions with Base64 identifier prefixes
+        try {
+            this.evts = this.lmdber.openDB("evts.", false);
+            return this.opened;
+        }
+        catch (error) {
+            console.error(`Failed to open Baser sub-databases: ${error}`);
+            throw new DatabaseOperationError("Failed to open Baser sub-databases", { cause: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /**
+     * Close the database
+     */
+    *close(clear = false) {
+        return yield* this.lmdber.close(clear);
+    }
+    /**
+     * Get version
+     */
+    getVer() {
+        return this.lmdber.getVer();
+    }
+    /**
+     * Set version
+     */
+    setVer(val) {
+        this.lmdber.setVer(val);
+    }
+    /**
+     * Count entries in evts sub-database
+     */
+    cntEvts() {
+        return this.lmdber.cnt(this.evts);
+    }
+    /**
+     * Put value in evts sub-database
+     */
+    putEvt(key, val) {
+        return this.lmdber.putVal(this.evts, key, val);
+    }
+    /**
+     * Set value in evts sub-database
+     */
+    setEvt(key, val) {
+        return this.lmdber.setVal(this.evts, key, val);
+    }
+    /**
+     * Get value from evts sub-database
+     */
+    getEvt(key) {
+        return this.lmdber.getVal(this.evts, key);
+    }
+    /**
+     * Delete value from evts sub-database
+     */
+    delEvt(key) {
+        return this.lmdber.delVal(this.evts, key);
+    }
+    /**
+     * Get iterator over items in evts sub-database
+     *
+     * @param top - Key prefix to filter by (empty to get all items)
+     * @returns Generator yielding (key, val) tuples
+     */
+    *getAllEvtsIter(top = new Uint8Array(0)) {
+        yield* this.lmdber.getTopItemIter(this.evts, top);
+    }
+}
+// Class constants
+Object.defineProperty(Baser, "TailDirPath", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: "keri/db"
+});
+Object.defineProperty(Baser, "AltTailDirPath", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: ".keri/db"
+});
+Object.defineProperty(Baser, "TempPrefix", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: "keri_db_"
+});
+Object.defineProperty(Baser, "MaxNamedDBs", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 96
+});
+/**
+ * Create and open a Baser instance.
+ *
+ * Constructors cannot be async, so call this factory where an opened Baser is required.
+ */
+export function* createBaser(options = {}) {
+    const baser = new Baser(options);
+    const opened = yield* baser.reopen(options);
+    if (!opened) {
+        throw new DatabaseNotOpenError("Failed to open Baser");
+    }
+    return baser;
+}

package/esm/db/core/db.js

@@ -0,0 +1,19 @@
+import { open } from "lmdb";
+// Singleton db-lazy open - not thread safe
+let db = null;
+export function openDB(path = "./data.mdb") {
+    if (!db) {
+        db = open({ path, mapSize: 2e9 }); // 2GB map; tune for KERI events.
+    }
+    return db;
+}
+export function readValue(db, key) {
+    // sync get
+    return db.get(key) ?? null;
+}
+export function writeValue(db, key, value) {
+    // sync write
+    db.transactionSync(() => {
+        db.putSync(key, value);
+    });
+}