keri-ts 0.2.3 → 0.3.0

package/esm/app/configing.js

@@ -0,0 +1,261 @@
+import * as dntShim from "../_dnt.shims.js";
+import { basename, dirname, join } from "../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { ValidationError } from "../core/errors.js";
+import { PathManager, } from "../db/core/path-manager.js";
+const CONFIGER_DEFAULTS = {
+    tailDirPath: "keri/cf",
+    cleanTailDirPath: "keri/clean/cf",
+    altTailDirPath: ".tufa/cf",
+    altCleanTailDirPath: ".tufa/clean/cf",
+    tempPrefix: "keri_cf_",
+    fext: "json",
+};
+/**
+ * Habitat Config File.
+ *
+ * This TypeScript implementation intentionally uses stateless file I/O for reads
+ * and an atomic-write strategy for updates (temp file + sync + rename).
+ * That differs from KERIpy's handle-oriented Configer, which keeps an open file
+ * handle and uses seek/truncate/write/flush on that handle.
+ *
+ * We keep the public API simple (`get`/`put`) while hardening writes against
+ * partial-file outcomes during unexpected process exits.
+ *
+ * Supports only JSON at the moment.
+ */
+export class Configer {
+    /** Create a config manager bound to a PathManager-backed directory. */
+    constructor(options = {}) {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "base", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "temp", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fext", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pathManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "path", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.name = options.name || "conf";
+        this.base = options.base || "";
+        this.temp = options.temp || false;
+        this.fext = options.fext || CONFIGER_DEFAULTS.fext;
+        this.pathManager = new PathManager({
+            ...options,
+            name: this.name,
+            base: this.base,
+            temp: this.temp,
+        }, {
+            tailDirPath: CONFIGER_DEFAULTS.tailDirPath,
+            cleanTailDirPath: CONFIGER_DEFAULTS.cleanTailDirPath,
+            altTailDirPath: CONFIGER_DEFAULTS.altTailDirPath,
+            altCleanTailDirPath: CONFIGER_DEFAULTS.altCleanTailDirPath,
+            tempPrefix: CONFIGER_DEFAULTS.tempPrefix,
+        });
+    }
+    get opened() {
+        return this.path !== null;
+    }
+    /** Resolve and validate the config filename and extension. */
+    resolvedFileName() {
+        if (this.name.endsWith(`.${this.fext}`)) {
+            return this.name;
+        }
+        const hasExt = this.name.includes(".");
+        if (hasExt) {
+            throw new ValidationError(`Unsupported config extension for '${this.name}'. Only .${this.fext} is supported.`);
+        }
+        return `${this.name}.${this.fext}`;
+    }
+    ensureOpenPath() {
+        if (!this.path) {
+            throw new ValidationError("Config file is not opened");
+        }
+        return this.path;
+    }
+    /** Flush parent directory metadata when the platform supports it. */
+    syncDirBestEffort(dirPath) {
+        try {
+            const dir = dntShim.Deno.openSync(dirPath, { read: true });
+            try {
+                dir.syncSync();
+            }
+            finally {
+                dir.close();
+            }
+        }
+        catch {
+            // Best effort: some platforms/filesystems may not allow directory sync.
+        }
+    }
+    /** Rename temp file into place with a Windows compatibility fallback. */
+    renameIntoPlace(tempPath, path) {
+        try {
+            dntShim.Deno.renameSync(tempPath, path);
+            return;
+        }
+        catch (error) {
+            if (dntShim.Deno.build.os !== "windows") {
+                throw error;
+            }
+            // On Windows, rename may fail when target already exists.
+            if (!(error instanceof dntShim.Deno.errors.AlreadyExists) &&
+                !(error instanceof dntShim.Deno.errors.PermissionDenied)) {
+                throw error;
+            }
+            // Best-effort replacement fallback for Windows. This is not fully atomic,
+            // but keeps behavior consistent across platforms when overwrite-on-rename is blocked.
+            try {
+                dntShim.Deno.removeSync(path);
+            }
+            catch (removeError) {
+                if (!(removeError instanceof dntShim.Deno.errors.NotFound)) {
+                    throw removeError;
+                }
+            }
+            dntShim.Deno.renameSync(tempPath, path);
+        }
+    }
+    /**
+     * Atomically persist config content using temp-file + sync + rename.
+     *
+     * Why this shape:
+     * - writing directly to the target can leave a truncated/partial file on crash
+     * - rename gives us an atomic switch from old file to new file
+     * - syncing the parent directory makes the rename metadata more durable
+     *   if a crash happens immediately after rename returns
+     */
+    writeAtomic(path, content) {
+        const dirPath = dirname(path);
+        const baseName = basename(path);
+        const tempPath = join(dirPath, `.${baseName}.tmp-${crypto.randomUUID()}`);
+        const encoder = new TextEncoder();
+        let written = false;
+        try {
+            const tempFile = dntShim.Deno.openSync(tempPath, {
+                write: true,
+                create: true,
+                truncate: true,
+                mode: 0o600,
+            });
+            try {
+                tempFile.writeSync(encoder.encode(content));
+                tempFile.syncSync();
+            }
+            finally {
+                tempFile.close();
+            }
+            this.renameIntoPlace(tempPath, path);
+            written = true;
+            this.syncDirBestEffort(dirPath);
+        }
+        finally {
+            if (!written) {
+                try {
+                    dntShim.Deno.removeSync(tempPath);
+                }
+                catch (error) {
+                    if (!(error instanceof dntShim.Deno.errors.NotFound)) {
+                        throw error;
+                    }
+                }
+            }
+        }
+    }
+    /** Open or create the config file in the resolved Configer directory. */
+    *reopen(options = {}) {
+        const opened = yield* this.pathManager.reopen({
+            ...options,
+            name: this.name,
+            base: this.base,
+            temp: this.temp,
+        });
+        if (!opened || !this.pathManager.path) {
+            return false;
+        }
+        const fileName = this.resolvedFileName();
+        this.path = join(this.pathManager.path, fileName);
+        try {
+            dntShim.Deno.statSync(this.path);
+        }
+        catch (error) {
+            if (error instanceof dntShim.Deno.errors.NotFound) {
+                this.writeAtomic(this.path, "{}\n");
+            }
+            else {
+                throw error;
+            }
+        }
+        return true;
+    }
+    /** Close the config manager and optionally remove files. */
+    *close(clear = false) {
+        if (clear && this.path) {
+            try {
+                dntShim.Deno.removeSync(this.path);
+            }
+            catch (error) {
+                if (!(error instanceof dntShim.Deno.errors.NotFound)) {
+                    throw error;
+                }
+            }
+        }
+        this.path = null;
+        yield* this.pathManager.close(clear);
+        return true;
+    }
+    /** Read and parse JSON config from disk. */
+    get() {
+        const path = this.ensureOpenPath();
+        const raw = dntShim.Deno.readTextFileSync(path).trim();
+        if (!raw) {
+            return {};
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            throw new ValidationError(`Invalid JSON configuration at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Serialize and persist JSON config to disk. */
+    put(data) {
+        const path = this.ensureOpenPath();
+        this.writeAtomic(path, `${JSON.stringify(data, null, 2)}\n`);
+        return true;
+    }
+}
+export function* createConfiger(options = {}) {
+    const configer = new Configer(options);
+    const opened = yield* configer.reopen(options);
+    if (!opened) {
+        throw new ValidationError("Failed to open config file");
+    }
+    return configer;
+}

package/esm/app/habbing.js

@@ -0,0 +1,386 @@
+import { createConfiger } from "./configing.js";
+import { createBaser } from "../db/basing.js";
+import { createKeeper } from "../db/keeping.js";
+import { branToSaltQb64, encodeCounterV1, encodeDateTimeToDater, encodeHugeNumber, makeSaider, Manager, normalizeSaltQb64, saltySigner, } from "./keeping.js";
+export const SIGNER = "__signatory__";
+function versifyV1(size) {
+    return `KERI10JSON${size.toString(16).padStart(6, "0")}_`;
+}
+function serializeKed(ked) {
+    return new TextEncoder().encode(JSON.stringify(ked));
+}
+function makeNowIso8601() {
+    const now = new Date();
+    const y = now.getUTCFullYear().toString().padStart(4, "0");
+    const m = (now.getUTCMonth() + 1).toString().padStart(2, "0");
+    const d = now.getUTCDate().toString().padStart(2, "0");
+    const hh = now.getUTCHours().toString().padStart(2, "0");
+    const mm = now.getUTCMinutes().toString().padStart(2, "0");
+    const ss = now.getUTCSeconds().toString().padStart(2, "0");
+    const micros = (now.getUTCMilliseconds() * 1000).toString().padStart(6, "0");
+    return `${y}-${m}-${d}T${hh}:${mm}:${ss}.${micros}+00:00`;
+}
+function defaultThreshold(count, min) {
+    return `${Math.max(min, Math.ceil(count / 2)).toString(16)}`;
+}
+function makeInceptRaw(keys, ndigs, args) {
+    const ilk = args.delpre ? "dip" : "icp";
+    const kt = args.isith ?? defaultThreshold(keys.length, 1);
+    const nt = args.nsith ?? defaultThreshold(ndigs.length, 0);
+    const saidDummy = "#".repeat(44);
+    const ked = {
+        v: versifyV1(0),
+        t: ilk,
+        d: saidDummy,
+        i: args.code === "E" ? saidDummy : keys[0],
+        s: "0",
+        kt,
+        k: keys,
+        nt,
+        n: ndigs,
+        bt: `${args.toad.toString(16)}`,
+        b: args.wits,
+        c: args.cnfg,
+        a: args.data,
+    };
+    if (args.delpre)
+        ked.di = args.delpre;
+    ked.v = versifyV1(serializeKed(ked).length);
+    const sizedDummied = serializeKed(ked);
+    const said = makeSaider(sizedDummied);
+    ked.d = said;
+    if (args.code === "E")
+        ked.i = said;
+    const raw = serializeKed(ked);
+    return { raw, pre: ked.i };
+}
+/** Represents a local identifier habitat and its current key state. */
+export class Hab {
+    constructor(name, db, ks, mgr, ns, pre = "") {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ns", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "mgr", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+        Object.defineProperty(this, "kever", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.name = name;
+        this.db = db;
+        this.ks = ks;
+        this.mgr = mgr;
+        this.ns = ns;
+        this.pre = pre;
+    }
+    /** Incepts this habitat and persists its inception event and habitat record. */
+    make(args = {}) {
+        const { code = "E", transferable = true, isith = undefined, icount = 1, nsith = undefined, ncount = undefined, toad = 0, wits = [], delpre = undefined, estOnly = false, DnD = false, hidden = false, data = [], algo = undefined, salt = undefined, tier = undefined, } = args;
+        let nextCount = ncount ?? icount;
+        let nextSith = nsith ?? isith;
+        let prefixCode = code;
+        if (!transferable) {
+            nextCount = 0;
+            nextSith = "0";
+            prefixCode = "B";
+        }
+        const [verfers, digers] = this.mgr.incept({
+            icount,
+            ncount: nextCount,
+            stem: this.ns ? `${this.ns}${this.name}` : this.name,
+            transferable,
+            algo,
+            salt,
+            tier,
+        });
+        const keys = verfers.map((v) => v.qb64);
+        const ndigs = digers.map((d) => d.qb64);
+        const cnfg = [...(estOnly ? ["EO"] : []), ...(DnD ? ["DND"] : [])];
+        const { raw, pre } = makeInceptRaw(keys, ndigs, {
+            code: prefixCode,
+            isith,
+            nsith: nextSith,
+            toad,
+            wits,
+            cnfg,
+            data,
+            delpre,
+        });
+        const opre = verfers[0].qb64;
+        this.mgr.move(opre, pre);
+        this.pre = pre;
+        const sigs = this.mgr.sign(raw, keys, true);
+        let atc = "";
+        atc += encodeCounterV1("-A", sigs.length);
+        for (const sig of sigs)
+            atc += sig;
+        atc += encodeCounterV1("-E", 1);
+        atc += encodeHugeNumber(0);
+        atc += encodeDateTimeToDater(makeNowIso8601());
+        if (atc.length % 4 !== 0) {
+            throw new Error("Invalid attachment size, nonintegral quadlets.");
+        }
+        const msg = new TextEncoder().encode(`${new TextDecoder().decode(raw)}${encodeCounterV1("-V", atc.length / 4)}${atc}`);
+        this.db.putEvt(new TextEncoder().encode(`${pre}:0`), msg);
+        this.kever = {
+            pre,
+            verfers: keys,
+            digers: ndigs,
+            sn: 0,
+            delpre,
+            wits,
+        };
+        if (!hidden) {
+            const habord = {
+                hid: pre,
+                name: this.name,
+                domain: this.ns,
+            };
+            this.db.pinHab(pre, { ...habord, sigs });
+            this.db.pinName(this.ns ?? "", this.name, pre);
+        }
+    }
+    /** Produces signatures with this habitat's current signing keys. */
+    sign(ser, indexed = false) {
+        const pubs = this.kever?.verfers ?? [];
+        return this.mgr.sign(ser, pubs, indexed);
+    }
+}
+/** Local signatory wrapper for `__signatory__` signing used by habery internals. */
+export class Signator {
+    constructor(db, habery) {
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "hab", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pre", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.db = db;
+        const spre = this.db.getHby(SIGNER);
+        if (!spre) {
+            const hab = new Hab(SIGNER, habery.db, habery.ks, habery.mgr);
+            hab.make({ transferable: false, hidden: true });
+            this.hab = hab;
+            this.pre = hab.pre;
+            this.db.pinHby(SIGNER, this.pre);
+        }
+        else {
+            const hab = new Hab(SIGNER, habery.db, habery.ks, habery.mgr, undefined, spre);
+            this.hab = hab;
+            this.pre = spre;
+        }
+    }
+    /** Signs arbitrary serialized bytes with the signatory habitat. */
+    sign(ser) {
+        const sig = this.hab.sign(ser, false)[0];
+        if (!sig)
+            throw new Error("Unable to sign");
+        return sig;
+    }
+    /** Verifies by recomputing the expected deterministic signature. */
+    verify(ser, cigar) {
+        const expected = this.sign(ser);
+        return expected === cigar;
+    }
+}
+/** Top-level container for database, keystore, manager, and habitats. */
+export class Habery {
+    constructor(name, base, temp, db, ks, mgr, cf, config = {}) {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "base", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "temp", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "mgr", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "cf", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "habs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "signator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = name;
+        this.base = base;
+        this.temp = temp;
+        this.db = db;
+        this.ks = ks;
+        this.mgr = mgr;
+        this.cf = cf;
+        this.config = config;
+        this.signator = new Signator(this.db, this);
+    }
+    /** Creates and caches a new habitat under this habery. */
+    makeHab(name, ns, args = {}) {
+        const hab = new Hab(name, this.db, this.ks, this.mgr, ns);
+        hab.make(args);
+        if (!hab.pre)
+            throw new Error("Hab creation failed");
+        this.habs.set(hab.pre, hab);
+        return hab;
+    }
+    /** Resolves a habitat by alias (and optional namespace). */
+    habByName(name, ns) {
+        const pre = this.db.getName(ns ?? "", name);
+        if (!pre)
+            return null;
+        if (this.habs.has(pre))
+            return this.habs.get(pre);
+        const rec = this.db.getHab(pre);
+        if (!rec)
+            return null;
+        const hab = new Hab(name, this.db, this.ks, this.mgr, ns, pre);
+        this.habs.set(pre, hab);
+        return hab;
+    }
+    /** Closes backing databases and optionally clears temp storage. */
+    *close(clear = false) {
+        yield* this.db.close(clear);
+        yield* this.ks.close(clear);
+        if (this.cf) {
+            yield* this.cf.close(clear && this.temp);
+        }
+    }
+}
+/** Derives deterministic seed/aeid values from passcode material exactly as KERIpy bran flow. */
+export function branToSeedAeid(bran) {
+    const branSalt = branToSaltQb64(bran);
+    const signer = saltySigner(branSalt, "", false, "low", false);
+    return { seed: signer.seedQb64, aeid: signer.verferQb64 };
+}
+/** Creates a habery with opened database/keystore and initialized manager state. */
+export function* createHabery(args) {
+    const { name, base = "", temp = false, headDirPath, cf: providedCf, bran, seed, aeid, salt, algo, } = args;
+    const db = yield* createBaser({
+        name,
+        base,
+        temp,
+        headDirPath,
+        reopen: true,
+        readonly: false,
+    });
+    const ks = yield* createKeeper({
+        name,
+        base,
+        temp,
+        headDirPath,
+        reopen: true,
+        readonly: false,
+    });
+    const cf = providedCf ?? (yield* createConfiger({
+        name,
+        base,
+        temp,
+        headDirPath,
+        reopen: true,
+        clear: false,
+    }));
+    const config = cf ? cf.get() : {};
+    let usedSeed = seed ?? "";
+    let usedAeid = aeid ?? "";
+    if (bran && !seed) {
+        const derived = branToSeedAeid(bran);
+        usedSeed = derived.seed;
+        if (!usedAeid)
+            usedAeid = derived.aeid;
+    }
+    const mgr = new Manager({
+        ks,
+        seed: usedSeed,
+        aeid: usedAeid,
+        algo,
+        salt: normalizeSaltQb64(salt),
+    });
+    return new Habery(name, base, temp, db, ks, mgr, cf, config);
+}

package/esm/app/index.js

@@ -5,3 +5,6 @@
  */
 export * from "./cli/index.js";
 export { startServer } from "./server.js";
+export * from "./habbing.js";
+export * from "./keeping.js";
+export * from "./configing.js";