keri-ts 0.10.1 → 0.10.2

package/esm/keri/npm/src/app/cesr-http.js

@@ -0,0 +1,281 @@
+/**
+ * CESR-over-HTTP request helpers.
+ *
+ * Mailbox and exchange interop depends on getting this boundary right.
+ *
+ * KERIpy correspondence:
+ * - default behavior is one CESR message per HTTP request with the message body
+ *   in the request body and attachments in `CESR-ATTACHMENT`
+ *
+ * Current `keri-ts` difference:
+ * - `keri-ts` supports an optional `"body"` mode for mailbox operations where the
+ *   full CESR payload is sent in the body instead of splitting attachments into
+ *   the header
+ */
+import { concatBytes, createParser, parseSerder, SerderKERI, smell, } from "cesr-ts";
+import { ValidationError } from "../core/errors.js";
+/** Default interop mode matching KERIpy mailbox behavior. */
+export const DEFAULT_CESR_BODY_MODE = "header";
+/** CESR HTTP content type used by mailbox and exchange endpoints. */
+export const CESR_CONTENT_TYPE = "application/cesr";
+/** KERIpy's legacy-but-authoritative CESR HTTP media type. */
+export const KERIPY_CESR_JSON_CONTENT_TYPE = "application/cesr+json";
+/** Multipart form content type retained for mailbox-admin compatibility. */
+export const MULTIPART_CONTENT_TYPE = "multipart/form-data";
+/** Header that carries detached CESR attachments in header mode. */
+export const CESR_ATTACHMENT_HEADER = "CESR-ATTACHMENT";
+/** Header naming the intended recipient endpoint AID when needed. */
+export const CESR_DESTINATION_HEADER = "CESR-DESTINATION";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/** Return true when one HTTP content type names CESR payload framing. */
+export function isCesrContentType(value) {
+    const normalized = value?.split(";")[0]?.trim()?.toLowerCase();
+    return normalized === CESR_CONTENT_TYPE
+        || normalized === KERIPY_CESR_JSON_CONTENT_TYPE;
+}
+/** Return true when one HTTP content type names multipart form media. */
+export function isMultipartFormContentType(value) {
+    return value?.split(";")[0]?.trim()?.toLowerCase() === MULTIPART_CONTENT_TYPE;
+}
+/** Normalize CLI or config input into one supported CESR body mode. */
+export function normalizeCesrBodyMode(value, fallback = DEFAULT_CESR_BODY_MODE) {
+    if (value === undefined || value === null || value === "") {
+        return fallback;
+    }
+    if (value === "header" || value === "body") {
+        return value;
+    }
+    throw new ValidationError(`Invalid cesr body mode "${String(value)}". Expected "header" or "body".`);
+}
+/** Normalize a global config string into one supported CESR body mode. */
+export function cesrBodyModeFromGlobal(value) {
+    return normalizeCesrBodyMode(value ?? undefined);
+}
+/**
+ * Build one HTTP request payload for a CESR message.
+ *
+ * Header mode:
+ * - HTTP body carries the message body only
+ * - `CESR-ATTACHMENT` carries the detached attachments
+ *
+ * Body mode:
+ * - the full payload is sent in the HTTP body
+ */
+export function buildCesrRequest(message, { bodyMode = DEFAULT_CESR_BODY_MODE, contentType = CESR_CONTENT_TYPE, destination, } = {}) {
+    const mode = normalizeCesrBodyMode(bodyMode);
+    const headers = {
+        "Content-Type": contentType,
+    };
+    if (destination) {
+        headers[CESR_DESTINATION_HEADER] = destination;
+    }
+    if (mode === "body") {
+        return {
+            headers,
+            body: arrayBufferFromBytes(message),
+        };
+    }
+    const { smellage } = smell(message);
+    const serder = parseSerder(message.slice(0, smellage.size), smellage);
+    headers[CESR_ATTACHMENT_HEADER] = textDecoder.decode(message.slice(serder.size));
+    return {
+        headers,
+        body: arrayBufferFromBytes(message.slice(0, serder.size)),
+    };
+}
+/**
+ * Build one raw CESR-body HTTP request.
+ *
+ * This is the right helper for endpoints that accept an already assembled CESR
+ * payload or a multi-message CESR stream in the body.
+ */
+export function buildCesrStreamRequest(bytes, { destination, } = {}) {
+    const headers = {
+        "Content-Type": CESR_CONTENT_TYPE,
+    };
+    if (destination) {
+        headers[CESR_DESTINATION_HEADER] = destination;
+    }
+    return {
+        headers,
+        body: arrayBufferFromBytes(bytes),
+    };
+}
+/**
+ * Split one CESR JSON message stream into individual request-ready messages.
+ *
+ * KERIpy correspondence:
+ * - mirrors `streamCESRRequests(...)`, which posts one message body plus its
+ *   attachments per HTTP request instead of shoving a whole multi-message
+ *   stream behind one `CESR-ATTACHMENT` header
+ */
+export function splitCesrStream(message) {
+    if (message.length === 0) {
+        return [];
+    }
+    const parser = createParser({
+        framed: false,
+        attachmentDispatchMode: "compat",
+    });
+    const frames = [...parser.feed(message), ...parser.flush()];
+    const parts = [];
+    for (const frame of frames) {
+        if (frame.type === "error") {
+            throw frame.error;
+        }
+        parts.push(concatBytes(frame.frame.body.raw, ...frame.frame.attachments.map((attachment) => attachment.raw)));
+    }
+    return parts;
+}
+/**
+ * Reconstruct one logical CESR payload from an incoming HTTP request.
+ *
+ * In header mode this reattaches `CESR-ATTACHMENT` bytes to the parsed message
+ * body so downstream parsing always sees the canonical CESR byte stream.
+ */
+export async function readCesrRequestBytes(req) {
+    const body = new Uint8Array(await req.arrayBuffer());
+    const contentType = req.headers.get("content-type")
+        ?.split(";")[0]
+        ?.trim()
+        ?.toLowerCase();
+    const attachment = req.headers.get(CESR_ATTACHMENT_HEADER);
+    if (contentType === CESR_CONTENT_TYPE
+        && attachment
+        && attachment.length > 0) {
+        return new Uint8Array([...body, ...textEncoder.encode(attachment)]);
+    }
+    return body;
+}
+/**
+ * Read one direct signed-KERI ingress request.
+ *
+ * Endpoints that accept existing signed KERI material should use this helper
+ * instead of hand-rolling JSON or form-data wrappers around CESR bytes.
+ *
+ * Returns `null` when the request is not CESR-framed at all.
+ */
+export async function readRequiredCesrRequestBytes(req) {
+    if (!isCesrContentType(req.headers.get("content-type"))) {
+        return null;
+    }
+    return await readCesrRequestBytes(req);
+}
+/**
+ * Read one mailbox-admin request from either raw CESR or multipart fields.
+ *
+ * Multipart compatibility contract:
+ * - `kel`: required controller replay
+ * - `delkel`: optional delegation replay
+ * - `rpy`: required mailbox authorization reply
+ */
+export async function readMailboxAdminRequest(req) {
+    const contentType = req.headers.get("content-type");
+    if (isCesrContentType(contentType)) {
+        const bytes = new Uint8Array(await readCesrRequestBytes(req));
+        return {
+            bytes,
+            inspection: inspectMailboxAdminCesrStream(new Uint8Array(bytes)),
+        };
+    }
+    if (isMultipartFormContentType(contentType)) {
+        const form = await req.formData();
+        const kel = readRequiredMailboxAdminField(form, "kel");
+        const rpy = readRequiredMailboxAdminField(form, "rpy");
+        const delkel = readOptionalMailboxAdminField(form, "delkel");
+        const bytes = textEncoder.encode(`${delkel ?? ""}${kel}${rpy}`);
+        return {
+            bytes,
+            inspection: inspectMailboxAdminReply(textEncoder.encode(rpy)),
+        };
+    }
+    return null;
+}
+/** Parse and return the first CESR message in one request body. */
+export function inspectCesrRequest(bytes) {
+    try {
+        const { smellage } = smell(bytes);
+        const serder = parseSerder(bytes.slice(0, smellage.size), smellage);
+        return serder instanceof SerderKERI ? serder : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse and return the final CESR message in one request body. */
+export function inspectCesrTerminalMessage(bytes) {
+    return inspectCesrStream(bytes).terminal;
+}
+/** Parse one entire CESR request body and return every message plus the last. */
+export function inspectCesrStream(bytes) {
+    const parser = createParser({
+        framed: false,
+        attachmentDispatchMode: "compat",
+    });
+    const messages = [];
+    const frames = parser.feed(bytes);
+    for (const frame of frames) {
+        if (frame.type === "error") {
+            throw frame.error;
+        }
+        messages.push(parseSerder(frame.frame.body.raw, smellageFromMessage(frame.frame)));
+    }
+    return {
+        messages,
+        terminal: messages.at(-1) ?? null,
+    };
+}
+/** Copy a byte view into a standalone `ArrayBuffer` for Fetch request bodies. */
+function arrayBufferFromBytes(bytes) {
+    return new Uint8Array(bytes).buffer;
+}
+function smellageFromMessage(message) {
+    return {
+        proto: message.body.proto,
+        pvrsn: message.body.pvrsn,
+        kind: message.body.kind,
+        size: message.body.size,
+        gvrsn: message.body.gvrsn,
+    };
+}
+function readRequiredMailboxAdminField(form, name) {
+    const value = readOptionalMailboxAdminField(form, name);
+    if (!value) {
+        throw new ValidationError(`Mailbox authorization request is missing ${name}`);
+    }
+    return value;
+}
+function readOptionalMailboxAdminField(form, name) {
+    const value = form.get(name);
+    if (value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new ValidationError(`Mailbox authorization field ${name} must be text`);
+    }
+    return value;
+}
+function inspectMailboxAdminCesrStream(bytes) {
+    try {
+        return inspectCesrStream(bytes);
+    }
+    catch (error) {
+        throw new ValidationError(`Invalid mailbox authorization stream: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function inspectMailboxAdminReply(bytes) {
+    try {
+        const inspection = inspectCesrStream(bytes);
+        if (inspection.messages.length !== 1) {
+            throw new ValidationError("Mailbox authorization reply field must contain exactly one CESR message");
+        }
+        return inspection;
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            throw error;
+        }
+        throw new ValidationError(`Invalid mailbox authorization reply: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/esm/keri/npm/src/app/challenging.js

@@ -0,0 +1,163 @@
+import { Diger } from "cesr-ts";
+const CHALLENGE_CONSONANTS = [
+    "b",
+    "c",
+    "d",
+    "f",
+    "g",
+    "h",
+    "j",
+    "k",
+    "l",
+    "m",
+    "n",
+    "p",
+    "r",
+    "s",
+    "t",
+    "v",
+];
+const CHALLENGE_VOWELS = ["a", "e", "i", "o"];
+const BITS_PER_WORD = 12;
+/**
+ * Register the built-in challenge-response route handler on one exchanger.
+ *
+ * This keeps runtime creation explicit: the `Exchanger` owns exchange routing,
+ * while the challenge module owns the `/challenge/response` application
+ * behavior layered on top of it.
+ */
+export function loadChallengeHandlers(db, exchanger) {
+    exchanger.addHandler(new ChallengeHandler(db));
+}
+/**
+ * Accepted `/challenge/response` handler.
+ *
+ * Responsibilities:
+ * - validate the route payload shape enough for durable storage
+ * - record successful signed responses in `reps.`
+ *
+ * Verification of the expected challenge words remains a verifier-side policy
+ * decision in `challenge verify`, so this handler stores all accepted
+ * responses rather than only one caller's currently expected phrase.
+ */
+export class ChallengeHandler {
+    constructor(db) {
+        Object.defineProperty(this, "resource", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ChallengeHandler.resource
+        });
+        Object.defineProperty(this, "db", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.db = db;
+    }
+    verify(args) {
+        const payload = args.serder.ked?.a;
+        return challengeWordsFromPayload(payload) !== null
+            && args.attachments.length === 0;
+    }
+    handle(args) {
+        const signer = args.serder.pre;
+        const said = args.serder.said;
+        if (!signer || !said) {
+            return;
+        }
+        this.db.reps.add([signer], new Diger({ qb64: said }));
+    }
+}
+Object.defineProperty(ChallengeHandler, "resource", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: "/challenge/response"
+});
+/** Return one accepted challenge-response exchange message whose words match `expected`. */
+export function findVerifiedChallengeResponse(db, signer, expected) {
+    for (const diger of db.reps.get([signer])) {
+        const exn = db.exns.get([diger.qb64]);
+        if (!exn) {
+            continue;
+        }
+        const words = challengeWordsFromPayload(exn.ked?.a);
+        if (words && challengeWordsEqual(words, expected)) {
+            return exn;
+        }
+    }
+    return null;
+}
+/** Persist one verifier-confirmed challenge response in `chas.`. */
+export function markChallengeVerified(db, signer, serder) {
+    if (!serder.said) {
+        return;
+    }
+    db.chas.add([signer], new Diger({ qb64: serder.said }));
+}
+/** Parse CLI input into challenge words from JSON-array or whitespace-separated text. */
+export function parseChallengeWords(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith("[")) {
+        const parsed = JSON.parse(trimmed);
+        if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+            throw new Error("Challenge words JSON must be an array of strings.");
+        }
+        return parsed.map((item) => item.trim()).filter((item) => item.length > 0);
+    }
+    return trimmed.split(/\s+/).filter((item) => item.length > 0);
+}
+/** Format one challenge-word list using the requested CLI output mode. */
+export function formatChallengeWords(words, out) {
+    switch (out) {
+        case "string":
+            return words.join(" ");
+        case "words":
+            return words.join("\n");
+        case "json":
+        default:
+            return JSON.stringify(words);
+    }
+}
+/**
+ * Generate a cryptographically random challenge phrase.
+ *
+ * The generator intentionally avoids a bundled external wordlist dependency by
+ * deriving pronounceable four-letter pseudo-words from 12 random bits each.
+ * That keeps the command self-contained while still giving human-friendly
+ * tokens suitable for challenge/response workflows.
+ */
+export function generateChallengeWords(strength = 128) {
+    const normalized = Number.isFinite(strength) && strength > 0
+        ? Math.trunc(strength)
+        : 128;
+    const count = Math.max(1, Math.ceil(normalized / BITS_PER_WORD));
+    const words = [];
+    const random = new Uint8Array(count * 2);
+    crypto.getRandomValues(random);
+    for (let i = 0; i < count; i += 1) {
+        const value = ((random[i * 2] << 8) | random[(i * 2) + 1]) & 0x0fff;
+        words.push(challengeWordFromValue(value));
+    }
+    return words;
+}
+function challengeWordFromValue(value) {
+    const c1 = CHALLENGE_CONSONANTS[(value >> 8) & 0x0f];
+    const v1 = CHALLENGE_VOWELS[(value >> 6) & 0x03];
+    const c2 = CHALLENGE_CONSONANTS[(value >> 2) & 0x0f];
+    const v2 = CHALLENGE_VOWELS[value & 0x03];
+    return `${c1}${v1}${c2}${v2}`;
+}
+function challengeWordsEqual(actual, expected) {
+    return actual.length === expected.length
+        && actual.every((word, index) => word === expected[index]);
+}
+function challengeWordsFromPayload(payload) {
+    const words = payload?.words;
+    if (!Array.isArray(words) || words.some((item) => typeof item !== "string")) {
+        return null;
+    }
+    return words;
+}

package/esm/keri/npm/src/app/cli/annotate-color.js

@@ -0,0 +1,215 @@
+import * as dntShim from "../../_dnt.shims.js";
+const ANSI_CODES = {
+    black: "\x1b[30m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+    brightBlack: "\x1b[90m",
+    brightRed: "\x1b[91m",
+    brightGreen: "\x1b[92m",
+    brightYellow: "\x1b[93m",
+    brightBlue: "\x1b[94m",
+    brightMagenta: "\x1b[95m",
+    brightCyan: "\x1b[96m",
+    brightWhite: "\x1b[97m",
+};
+const RESET = "\x1b[0m";
+const COLOR_KEYS = [
+    "counter",
+    "group",
+    "body",
+    "signature",
+    "said",
+    "opaque",
+    "comment",
+];
+const DEFAULT_COLORS = {
+    counter: "cyan",
+    group: "magenta",
+    body: "green",
+    signature: "yellow",
+    said: "brightBlue",
+    opaque: "brightRed",
+    comment: "brightBlack",
+};
+const SAID_CAPTURE = /(said=)(\S+)/g;
+const COMMENT_DELIM = " # ";
+function isColorName(value) {
+    return typeof value === "string" && value in ANSI_CODES;
+}
+function parseColorConfig(raw) {
+    const parsed = {};
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const match = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.+?)\s*$/.exec(trimmed);
+        if (!match)
+            return null;
+        const key = match[1];
+        let value = match[2];
+        if ((value.startsWith("\"") && value.endsWith("\""))
+            || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        parsed[key] = value;
+    }
+    const config = {};
+    for (const key of COLOR_KEYS) {
+        const value = parsed[key];
+        if (value === undefined)
+            continue;
+        if (!isColorName(value))
+            return null;
+        config[key] = value;
+    }
+    return config;
+}
+function resolveConfigPath(homeDir) {
+    const basePath = `${homeDir}/.tufa`;
+    const yamlPath = `${basePath}/annot-color.yaml`;
+    const ymlPath = `${basePath}/annot-color.yml`;
+    try {
+        const stat = dntShim.Deno.statSync(yamlPath);
+        if (stat.isFile)
+            return yamlPath;
+    }
+    catch {
+        // Continue to .yml fallback
+    }
+    try {
+        const stat = dntShim.Deno.statSync(ymlPath);
+        if (stat.isFile)
+            return ymlPath;
+    }
+    catch {
+        // No config file, use defaults
+    }
+    return null;
+}
+function readUserColorConfig() {
+    const homeDir = dntShim.Deno.env.get("HOME");
+    if (!homeDir)
+        return null;
+    const configPath = resolveConfigPath(homeDir);
+    if (!configPath)
+        return null;
+    try {
+        return parseColorConfig(dntShim.Deno.readTextFileSync(configPath));
+    }
+    catch {
+        return null;
+    }
+}
+function toAnsiColors(userConfig) {
+    const names = { ...DEFAULT_COLORS };
+    if (userConfig) {
+        for (const key of COLOR_KEYS) {
+            const value = userConfig[key];
+            if (value)
+                names[key] = value;
+        }
+    }
+    return {
+        counter: ANSI_CODES[names.counter],
+        group: ANSI_CODES[names.group],
+        body: ANSI_CODES[names.body],
+        signature: ANSI_CODES[names.signature],
+        said: ANSI_CODES[names.said],
+        opaque: ANSI_CODES[names.opaque],
+        comment: ANSI_CODES[names.comment],
+    };
+}
+function color(text, ansiCode) {
+    if (!text)
+        return text;
+    return `${ansiCode}${text}${RESET}`;
+}
+function colorizeComment(comment, colors) {
+    const saidTinted = comment.replace(SAID_CAPTURE, (_whole, prefix, said) => `${prefix}${color(said, colors.said)}`);
+    return color(saidTinted, colors.comment);
+}
+function colorizeValue(value, comment, colors) {
+    const text = value.trim();
+    if (!text)
+        return value;
+    if (comment && /opaque/i.test(comment)) {
+        return color(value, colors.opaque);
+    }
+    if (comment && /(Indexer|Sig|Sigs|Signature)/.test(comment)) {
+        return color(value, colors.signature);
+    }
+    if (comment && /(Group|count=|counter)/.test(comment)) {
+        return color(value, colors.group);
+    }
+    if (comment && /SERDER/.test(comment)) {
+        return color(value, colors.body);
+    }
+    if (/^[\[{]/.test(text)) {
+        return color(value, colors.body);
+    }
+    if (/^-[A-Za-z0-9_-]+$/.test(text)) {
+        return color(value, colors.counter);
+    }
+    return value;
+}
+function colorizeLine(line, colors) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("#")) {
+        return color(line, colors.comment);
+    }
+    const idx = line.indexOf(COMMENT_DELIM);
+    if (idx === -1) {
+        return colorizeValue(line, null, colors);
+    }
+    const value = line.slice(0, idx);
+    const comment = line.slice(idx + COMMENT_DELIM.length);
+    const valueTinted = colorizeValue(value, comment, colors);
+    const commentTinted = colorizeComment(comment, colors);
+    return `${valueTinted}${COMMENT_DELIM}${commentTinted}`;
+}
+/**
+ * Apply ANSI styling for CLI-only CESR annotation display.
+ * This is intentionally presentation-only and must not alter persisted output.
+ */
+export function colorizeAnnotatedOutput(annotated) {
+    const colors = toAnsiColors(readUserColorConfig());
+    const lines = annotated.split("\n");
+    const out = [];
+    let inPrettyJsonBody = false;
+    // support colorizing lines even with --pretty arg
+    for (const line of lines) {
+        const idx = line.indexOf(COMMENT_DELIM);
+        const value = idx === -1 ? line : line.slice(0, idx);
+        const comment = idx === -1 ? null : line.slice(idx + COMMENT_DELIM.length);
+        const trimmed = value.trim();
+        if (comment && /SERDER/.test(comment)) {
+            if (trimmed === "}" || trimmed === "]") {
+                const valueTinted = color(value, colors.body);
+                const commentTinted = colorizeComment(comment, colors);
+                out.push(`${valueTinted}${COMMENT_DELIM}${commentTinted}`);
+                inPrettyJsonBody = false;
+                continue;
+            }
+            out.push(colorizeLine(line, colors));
+            inPrettyJsonBody = false;
+            continue;
+        }
+        if (inPrettyJsonBody && idx === -1) {
+            out.push(color(line, colors.body));
+            continue;
+        }
+        if (idx === -1 && (trimmed === "{" || trimmed === "[")) {
+            inPrettyJsonBody = true;
+            out.push(color(line, colors.body));
+            continue;
+        }
+        out.push(colorizeLine(line, colors));
+    }
+    return out.join("\n");
+}