keri-ts 1.0.0 → 2.0.1

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

@@ -1,294 +0,0 @@
-/** Scoped CESR HTTP output with streamed payloads and joined cancellation. */
-import { attachmentPayload, byteString, collectPayload, framePayload, parse, } from "cesr-ts";
-import { call, ensure, on, race, resource, scoped } from "effection";
-import { ValidationError } from "../core/errors.js";
-import { rethrowCleanupFailure } from "./abortable.js";
-import { CESR_ATTACHMENT_HEADER, CESR_CONTENT_TYPE, CESR_DESTINATION_HEADER, KERIPY_CESR_JSON_CONTENT_TYPE, } from "./cesr-http.js";
-import { ownHttpResponse } from "./httping.js";
-import { defaultRuntimeServices } from "./runtime-services.js";
-/** Positive remote HTTP refusal, distinct from source, transport, storage and cleanup failure. */
-export class CesrHttpRefusal extends ValidationError {
-    constructor(message, status) {
-        super(message);
-        Object.defineProperty(this, "status", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: status
-        });
-    }
-}
-/** Adapt a payload to the platform fetch boundary without collecting it. */
-function requestBody(payload, upstream) {
-    // Fetch can cancel the upload independently of the surrounding response scope.
-    const controller = new AbortController();
-    const signal = AbortSignal.any([upstream, controller.signal]);
-    // The iterator borrows the frame's payload owner until this request scope exits.
-    const iterator = payload.open(signal)[Symbol.asyncIterator]();
-    // Joining includes the source's active next(), even if fetch stops waiting for the upload.
-    let pending;
-    // Repeated transport/scope cancellation shares one cleanup operation.
-    let closed;
-    /** Returning after the pending read prevents concurrent next/return calls into a sink reader. */
-    function close() {
-        controller.abort();
-        return closed ??= (async () => {
-            await pending?.catch(() => undefined);
-            await iterator.return?.();
-        })();
-    }
-    return {
-        stream: new ReadableStream({
-            /** A zero high-water mark leaves demand entirely with fetch's reader. */
-            async pull(controller) {
-                signal.throwIfAborted();
-                pending = iterator.next();
-                try {
-                    // Fetch receives one bounded owned chunk, never a view pinning a whole envelope.
-                    const result = await pending;
-                    if (result.done)
-                        controller.close();
-                    else
-                        controller.enqueue(result.value);
-                }
-                finally {
-                    pending = undefined;
-                }
-            },
-            /** Fetch cancellation releases the source; scope cancellation also aborts its signal. */
-            cancel: close,
-        }, { highWaterMark: 0 }),
-        close,
-    };
-}
-/** Read a failed response while keeping cancellation and reader cleanup with the request. */
-async function errorText(response, signal) {
-    if (!response.body)
-        return "";
-    const reader = response.body.getReader();
-    let closing;
-    /** Repeated cancel calls do not join the first underlying stream cancellation. */
-    const close = () => closing ??= reader.cancel(signal.reason);
-    /** Cancellation wakes a blocked read even for an injected response disconnected from fetch. */
-    const cancel = () => {
-        void close().catch(() => undefined);
-    };
-    signal.addEventListener("abort", cancel, { once: true });
-    if (signal.aborted)
-        cancel();
-    const decoder = new TextDecoder();
-    const text = [];
-    try {
-        while (true) {
-            const result = await reader.read();
-            if (result.done)
-                break;
-            text.push(decoder.decode(result.value, { stream: true }));
-        }
-        text.push(decoder.decode());
-        return text.join("");
-    }
-    finally {
-        signal.removeEventListener("abort", cancel);
-        try {
-            await close();
-        }
-        finally {
-            reader.releaseLock();
-        }
-    }
-}
-/**
- * Open one frame response as an Effection resource owned by the caller's scope.
- *
- * The caller supplies a complete frame tree. Body mode streams the frame; header mode qualifies
- * attachments as text. Scope exit aborts fetch and its body iterator, joins pending I/O,
- * and closes the response. The frame contains ordinary ESSR evidence.
- */
-export function* requestFrame(url, frame, options = {}) {
-    const result = yield* openFrameResponse(url, frame, options);
-    if (result.kind === "refuse")
-        throw result.error;
-    return result.response;
-}
-/** Each actual HTTP request owns its transport scope independently of source parsing. */
-function openFrameResponse(url, frame, options) {
-    return resource(function* (provide) {
-        // One controller owns fetch, payload reads, and the response body until the resource closes.
-        const controller = new AbortController();
-        // External abort and structured cancellation share the same transport signal.
-        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-        // The runtime chooses the HTTP implementation; the resource still owns its lifetime.
-        const services = options.services ?? defaultRuntimeServices;
-        // Header mode is the KERIpy default, and bulk body mode is explicit.
-        const mode = options.bodyMode ?? "header";
-        // Each Promise leaf remains tracked until cancellation has joined its cleanup.
-        let preparing;
-        // Upload cleanup is independent of whether fetch has already returned response headers.
-        let body;
-        // The most recent response belongs to this resource until provide() completes.
-        let response;
-        // Diagnostic reads are separate Promise leaves and must also finish before scope exit.
-        let reading;
-        let deliveredFailure;
-        try {
-            signal.throwIfAborted();
-            // Detached attachments are always legal text, even if the input frame was binary.
-            // Counter context belongs to the selected frame genus, never the JSON body's protocol version.
-            const attachments = mode === "header" ? attachmentPayload(frame, { domain: "txt" }) : undefined;
-            preparing = attachments ? collectPayload(attachments, signal) : undefined;
-            // Detached-header mode materializes text attachments; body mode streams them.
-            const header = preparing ? byteString(yield* call(() => preparing)) : undefined;
-            // Retry only the established KERIpy media-type negotiation, using the same reopenable frame.
-            const types = mode === "header" ? [CESR_CONTENT_TYPE, KERIPY_CESR_JSON_CONTENT_TYPE] : [CESR_CONTENT_TYPE];
-            for (const contentType of types) {
-                // Reopening supplies fresh request bytes for a media-type retry without retaining the first upload.
-                const headers = new Headers(options.headers);
-                headers.set("Content-Type", contentType);
-                headers.delete(CESR_DESTINATION_HEADER);
-                headers.delete(CESR_ATTACHMENT_HEADER);
-                if (options.destination)
-                    headers.set(CESR_DESTINATION_HEADER, options.destination);
-                if (header !== undefined)
-                    headers.set(CESR_ATTACHMENT_HEADER, header);
-                if (mode === "body")
-                    body = requestBody(framePayload(frame), signal);
-                // Node requires duplex for streaming uploads; Deno accepts the same standard fetch body.
-                const init = {
-                    method: "POST",
-                    headers,
-                    signal,
-                    body: body?.stream ?? frame.body.raw.slice().buffer,
-                    ...(body ? { duplex: "half" } : {}),
-                };
-                const owner = yield* ownHttpResponse(() => services.http.fetch(url, init), controller);
-                response = yield* owner.response();
-                if (response.ok) {
-                    yield* provide({ kind: "response", response });
-                    return;
-                }
-                // Only failed response text is read here; successful bodies remain available to the caller.
-                reading = errorText(response, signal);
-                // The response detail determines whether the historical media-type retry applies.
-                const detail = yield* call(() => reading);
-                if (mode === "header" && response.status === 406 && contentType === CESR_CONTENT_TYPE
-                    && detail.toLowerCase().includes("content type"))
-                    continue;
-                const refusal = new CesrHttpRefusal(`CESR delivery to ${url} failed with HTTP ${response.status}: ${detail}`, response.status);
-                yield* provide({ kind: "refuse", error: refusal });
-                return;
-            }
-        }
-        catch (error) {
-            deliveredFailure = { error };
-            throw error;
-        }
-        finally {
-            // Shared response owners join fetches; this owner separately joins preparation, diagnostics, and upload.
-            controller.abort();
-            const join = async (pending) => {
-                try {
-                    await pending;
-                }
-                catch (error) {
-                    if (error !== controller.signal.reason && error !== deliveredFailure?.error)
-                        throw error;
-                }
-            };
-            try {
-                if (preparing)
-                    yield* call(() => join(preparing));
-            }
-            finally {
-                try {
-                    if (reading)
-                        yield* call(() => join(reading));
-                }
-                finally {
-                    if (body)
-                        yield* call(() => body.close());
-                }
-            }
-        }
-    });
-}
-/** Strict source sender; callers wanting retry/refusal policy use the joined attempt result. */
-export function* postCesr(url, source, options = {}, consume) {
-    const result = yield* attemptPostCesr(url, source, options, consume);
-    if (result.kind === "refuse")
-        throw result.error;
-}
-/** Post through the same lifetime owner, returning only this invocation's expected refusal after joined cleanup. */
-export function attemptPostCesr(url, source, options = {}, consume) {
-    // Isolate joining cleanup so a halt cannot resume a delegated caller after payload disposal.
-    const posting = call(function* () {
-        const services = options.services ?? defaultRuntimeServices;
-        const controller = new AbortController();
-        const signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
-        try {
-            signal.throwIfAborted();
-            const frames = parse(source(signal));
-            let pending;
-            // The earlier resource joins the read after processing children stop.
-            yield* ensure(function* () {
-                try {
-                    if (pending) {
-                        try {
-                            yield* call(() => pending);
-                        }
-                        catch (error) {
-                            rethrowCleanupFailure(error, signal);
-                        }
-                    }
-                }
-                finally {
-                    yield* call(() => frames.return());
-                }
-            });
-            while (true) {
-                signal.throwIfAborted();
-                pending = frames.next();
-                let result;
-                try {
-                    result = yield* call(() => pending);
-                }
-                catch (error) {
-                    pending = undefined;
-                    throw error;
-                }
-                pending = undefined;
-                signal.throwIfAborted();
-                if (result.done)
-                    break;
-                const frame = result.value;
-                // Each request closes before the next input frame; it owns its separate HTTP cancellation.
-                const posted = yield* scoped(function* () {
-                    const response = yield* openFrameResponse(url, frame, { ...options, services });
-                    if (response.kind === "refuse")
-                        return response;
-                    if (consume)
-                        yield* consume(response.response);
-                    return { kind: "complete" };
-                });
-                if (posted.kind === "refuse")
-                    return posted;
-            }
-        }
-        finally {
-            controller.abort();
-        }
-        return { kind: "complete" };
-    });
-    if (!options.signal)
-        return posting;
-    const signal = options.signal;
-    return race([
-        posting,
-        call(function* () {
-            const abort = yield* on(signal, "abort");
-            signal.throwIfAborted();
-            yield* abort.next();
-            throw signal.reason;
-        }),
-    ]);
-}

package/esm/keri/npm/src/app/cli/common/displaying.js

@@ -1,43 +0,0 @@
-import { ValidationError } from "../../../core/errors.js";
-import { dgKey } from "../../../db/core/keys.js";
-/** Render one threshold bigint in the KLI-style decimal display form. */
-function decimalThreshold(value) {
-    return value.toString();
-}
-/**
- * Print KLI-style external key-state output for one known identifier.
- *
- * Maintainer note:
- * - this is intentionally presentation-oriented and should not be reused as a
- *   structured state API
- * - `query` relies on this exact mental model to show "best local view of
- *   external state after bounded convergence work"
- */
-export function printExternal(hby, pre, label = "Identifier") {
-    const kever = hby.db.getKever(pre);
-    if (!kever) {
-        throw new ValidationError(`No known key state for prefix ${pre}.`);
-    }
-    const estSaid = kever.lastEst.d || kever.said;
-    const witnessReceipts = estSaid
-        ? hby.db.wigs.get(dgKey(pre, estSaid)).length
-        : 0;
-    console.log(`${label}: ${pre}`);
-    console.log(`Seq No:\t${kever.sner.num.toString()}`);
-    if (kever.delegated) {
-        console.log("Delegated Identifier");
-        console.log(`    Delegator:  ${kever.delpre ?? ""}`);
-        console.log("");
-    }
-    console.log("");
-    console.log("Witnesses:");
-    console.log(`Count:\t\t${kever.wits.length}`);
-    console.log(`Receipts:\t${witnessReceipts}`);
-    console.log(`Threshold:\t${decimalThreshold(kever.toader.num)}`);
-    console.log("");
-    console.log("Public Keys:\t");
-    for (const [idx, verfer] of kever.verfers.entries()) {
-        console.log(`\t${idx + 1}. ${verfer.qb64}`);
-    }
-    console.log("");
-}

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

@@ -1,215 +0,0 @@
-import * as dntShim from "../../../_dnt.shims.js";
-import { ValidationError } from "../../../core/index.js";
-/**
- * Normalize one threshold input from CLI/file JSON into the internal
- * `ThresholdSith` representation.
- *
- * Accepted forms intentionally match the operator-facing KLI shapes:
- * numeric, hex-string, weighted JSON-array string, or structured array data.
- */
-function normalizeThresholdOption(value) {
-    if (value === undefined || value === null) {
-        return undefined;
-    }
-    if (typeof value === "number") {
-        if (!Number.isInteger(value) || value < 0) {
-            throw new Error(`Invalid numeric threshold ${value}`);
-        }
-        return value.toString(16);
-    }
-    if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (trimmed.length === 0) {
-            return undefined;
-        }
-        if (trimmed.startsWith("[")) {
-            return JSON.parse(trimmed);
-        }
-        return trimmed;
-    }
-    if (Array.isArray(value)) {
-        return structuredClone(value);
-    }
-    throw new Error(`Unsupported threshold option type ${typeof value}`);
-}
-/**
- * Parse one CLI/file threshold input into semantic numeric or weighted form.
- *
- * This is a thin public seam over `normalizeThresholdOption(...)` so command
- * modules do not duplicate threshold coercion rules.
- */
-export function parseThresholdOption(value) {
-    return normalizeThresholdOption(value);
-}
-/**
- * Parse inline JSON values or `@file` references used by CLI `--data` flags.
- *
- * KLI correspondence:
- * - each `--data` value is interpreted independently
- * - `@file` values must contain JSON that is inserted as one committed item
- */
-export function parseDataItems(items) {
-    if (!items || items.length === 0)
-        return [];
-    const out = [];
-    for (const item of items) {
-        if (item.startsWith("@")) {
-            const file = item.slice(1);
-            const text = dntShim.Deno.readTextFileSync(file);
-            out.push(JSON.parse(text));
-            continue;
-        }
-        out.push(JSON.parse(item));
-    }
-    return out;
-}
-/** Load and parse one JSON document from disk without extra schema coercion. */
-function loadJson(path) {
-    return JSON.parse(dntShim.Deno.readTextFileSync(path));
-}
-/** Return true when a string can be losslessly treated as a JSON number literal. */
-function isNumber(value) {
-    if (value.trim().length === 0) {
-        return false;
-    }
-    return !Number.isNaN(Number(value));
-}
-/**
- * Coerce one EXN `key=value` right-hand side like KERIpy's CLI.
- *
- * Plain strings stay strings, while obvious JSON scalars/containers are parsed
- * into structured values when possible.
- */
-function coerceExnDataValue(value) {
-    const trimmed = value.trim();
-    if (trimmed.length === 0) {
-        return "";
-    }
-    if (trimmed.startsWith("{") || trimmed.startsWith("[")
-        || trimmed === "true" || trimmed === "false" || trimmed === "null"
-        || isNumber(trimmed)) {
-        try {
-            return JSON.parse(trimmed);
-        }
-        catch {
-            return value;
-        }
-    }
-    return value;
-}
-/**
- * Parse KERIpy-style repeatable EXN `--data` items into one payload object.
- *
- * Accepted item shapes:
- * - `@file.json` containing one JSON object
- * - one inline JSON object string
- * - repeatable `key=value` items whose values coerce like KERIpy
- */
-export function parseExnDataItems(items) {
-    if (!items || items.length === 0) {
-        return {};
-    }
-    const data = {};
-    for (const item of items) {
-        if (item === undefined || item === null) {
-            continue;
-        }
-        const trimmed = item.trim();
-        if (trimmed.length === 0) {
-            continue;
-        }
-        if (trimmed.startsWith("@")) {
-            const loaded = loadJson(trimmed.slice(1));
-            if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) {
-                throw new Error("@file must contain a JSON object");
-            }
-            Object.assign(data, loaded);
-            continue;
-        }
-        if (trimmed.startsWith("{")) {
-            const loaded = JSON.parse(trimmed);
-            if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) {
-                throw new Error("JSON must be an object");
-            }
-            Object.assign(data, loaded);
-            continue;
-        }
-        if (!trimmed.includes("=")) {
-            throw new Error(`invalid item '${trimmed}', expected key=value, JSON object, or @file.json`);
-        }
-        const [rawKey, ...rest] = trimmed.split("=");
-        const key = rawKey?.trim() ?? "";
-        if (key.length === 0) {
-            throw new Error(`invalid item '${trimmed}', empty key`);
-        }
-        data[key] = coerceExnDataValue(rest.join("="));
-    }
-    return data;
-}
-/**
- * Load one JSON file of inception options using the CLI file-input contract.
- *
- * Threshold fields are normalized during load so later merge code can operate
- * on one representation regardless of whether the value came from a file or a
- * direct CLI flag.
- */
-export function loadInceptFileOptions(path) {
-    const text = dntShim.Deno.readTextFileSync(path);
-    const loaded = JSON.parse(text);
-    return {
-        ...loaded,
-        isith: normalizeThresholdOption(loaded.isith),
-        nsith: normalizeThresholdOption(loaded.nsith),
-    };
-}
-/**
- * Load one JSON file of rotation options using the CLI file-input contract.
- *
- * KLI compatibility notes:
- * - threshold fields are normalized immediately
- * - witness collections are filtered down to strings so malformed JSON does
- *   not propagate surprising non-string values into witness math
- */
-export function loadRotateFileOptions(path) {
-    const text = dntShim.Deno.readTextFileSync(path);
-    const loaded = JSON.parse(text);
-    return {
-        ...loaded,
-        isith: normalizeThresholdOption(loaded.isith),
-        nsith: normalizeThresholdOption(loaded.nsith),
-        wits: Array.isArray(loaded.wits)
-            ? loaded.wits.filter((value) => typeof value === "string")
-            : loaded.wits,
-        witsCut: Array.isArray(loaded.witsCut)
-            ? loaded.witsCut.filter((value) => typeof value === "string")
-            : loaded.witsCut,
-        witsAdd: Array.isArray(loaded.witsAdd)
-            ? loaded.witsAdd.filter((value) => typeof value === "string")
-            : loaded.witsAdd,
-    };
-}
-/**
- * Load one required CLI text argument or `@file` reference as UTF-8 bytes.
- *
- * This preserves the KLI convention used by `sign` and `verify`: operator
- * input is always interpreted as text, never raw binary.
- */
-export function loadTextArgument(text) {
-    const source = text.startsWith("@")
-        ? dntShim.Deno.readTextFileSync(text.slice(1))
-        : text;
-    return new TextEncoder().encode(source);
-}
-/** Require a non-empty string argument (for name, alias, etc.). */
-export function requireText(value, label) {
-    if (!value) {
-        throw new ValidationError(`${label} is required and cannot be empty`);
-    }
-    return value;
-}
-/** Require a non-empty value (void-throwing variant used in several commands). */
-export function requireNonEmpty(value, label) {
-    if (!value) {
-        throw new ValidationError(`${label} is required and cannot be empty.`);
-    }
-}