keri-ts 0.11.0 → 2.0.0

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

@@ -1,308 +0,0 @@
-/** Scoped CESR HTTP output: bounded metadata, streamed payloads, and joined cancellation. */
-import { attachmentPayload, byteString, collectPayload, discardFrame, framePayload, ResourceAdmissionError, } from "cesr-ts";
-import { toEffectionFrames } from "cesr-ts/effection";
-import { call, each, resource, scoped } from "effection";
-import { ValidationError } from "../core/errors.js";
-import { CESR_ATTACHMENT_HEADER, CESR_CONTENT_TYPE, CESR_DESTINATION_HEADER, KERIPY_CESR_JSON_CONTENT_TYPE, } from "./cesr-http.js";
-import { cesrOutputMetadataBytes } from "./cesr-output.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 an already admitted 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 only a finite failed-response prefix and cancel any unread tail. */
-async function errorText(response, limit, signal) {
-    if (!response.body)
-        return "";
-    // Diagnostics are metadata, not a reason to buffer an arbitrary peer response.
-    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();
-    // A finite byte budget applies before text decoding can expand the diagnostic representation.
-    const bytes = new Uint8Array(limit);
-    // Only the initialized prefix is decoded when the peer ends early.
-    let size = 0;
-    try {
-        while (size < limit) {
-            // A peer stream may end before the finite diagnostic budget is exhausted.
-            const result = await reader.read();
-            if (result.done)
-                break;
-            const part = result.value.subarray(0, limit - size);
-            bytes.set(part, size);
-            size += part.length;
-        }
-        return new TextDecoder().decode(bytes.subarray(0, size));
-    }
-    finally {
-        signal.removeEventListener("abort", cancel);
-        try {
-            await close();
-        }
-        finally {
-            reader.releaseLock();
-        }
-    }
-}
-/** Reject invalid budgets before allocating buffers or opening a remote connection. */
-function byteLimit(value, name) {
-    if (!Number.isSafeInteger(value) || value < 0)
-        throw new RangeError(`${name} must be a non-negative safe integer`);
-    return value;
-}
-/**
- * Open one frame response as an Effection resource owned by the caller's scope.
- *
- * The caller supplies an already admitted frame tree. Body mode streams a complete frame; header mode explicitly caps text-qualified
- * attachments. Scope exit aborts fetch and its body iterator, joins pending I/O,
- * and closes the response. The caller retains ownership of frame.essr.
- */
-export function requestFrame(url, frame, options = {}) {
-    return openFrameResponse(url, frame, options, 1);
-}
-/** Source-driven output already owns its stream slot; direct frame requests acquire one here. */
-function openFrameResponse(url, frame, options, streams) {
-    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";
-        // Validate both finite metadata budgets before creating any network or payload reader.
-        const headerLimit = byteLimit(options.maxHeaderBytes ?? 64 * 1024, "maxHeaderBytes");
-        const errorLimit = byteLimit(options.maxErrorBytes ?? 16 * 1024, "maxErrorBytes");
-        // Retain conservative qualification/header/diagnostic copies plus bounded serializer reader/output backing.
-        const bytes = 8 * cesrOutputMetadataBytes(frame) + 6 * headerLimit + 4 * errorLimit + 2 * 1024 ** 2;
-        const credit = services.resources.reserve({ streams, bytes });
-        if (credit.kind === "refuse") {
-            const refusal = new ResourceAdmissionError(`HTTP output ${credit.resource} admission refused: ${credit.reason}`, credit.reason);
-            options.onAdmissionRefusal?.(refusal);
-            throw refusal;
-        }
-        // 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;
-        // Aborting fetch is followed by joining it, including a concurrently completed response.
-        let fetching;
-        // Diagnostic reads are separate Promise leaves and must also finish before scope exit.
-        let reading;
-        try {
-            signal.throwIfAborted();
-            // Detached attachments are always legal text, even if the admitted frame was binary.
-            const attachments = mode === "header"
-                ? attachmentPayload(frame, {
-                    domain: "txt",
-                    enclosingGvrsn: frame.body.gvrsn ?? frame.body.pvrsn,
-                })
-                : undefined;
-            preparing = attachments ? collectPayload(attachments, headerLimit, signal) : undefined;
-            // Only detached-header mode collects attachments, under its explicit finite limit.
-            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" } : {}),
-                };
-                fetching = services.http.fetch(url, init);
-                response = yield* call(() => fetching);
-                if (response.ok) {
-                    yield* provide(response);
-                    return;
-                }
-                // Only failed response text is read here; successful bodies remain available to the caller.
-                reading = errorText(response, errorLimit, signal);
-                // The retained prefix 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);
-                options.onHttpRefusal?.(refusal);
-                throw refusal;
-            }
-        }
-        finally {
-            try {
-                // Abort first so blocked fetch/payload reads can settle before their owners are joined.
-                controller.abort();
-                try {
-                    if (fetching) {
-                        yield* call(async () => {
-                            // A late successful response still has an owned body that must be closed.
-                            const completed = await fetching.catch(() => undefined);
-                            if (completed?.body && !completed.body.locked) {
-                                try {
-                                    await completed.body.cancel();
-                                }
-                                catch (error) {
-                                    // Native fetch may error an unread body with this exact intentional teardown reason.
-                                    if (error !== controller.signal.reason)
-                                        throw error;
-                                }
-                            }
-                        });
-                    }
-                }
-                finally {
-                    if (preparing)
-                        yield* call(() => preparing.then(() => { }, () => { }));
-                    if (reading)
-                        yield* call(() => reading.then(() => { }, () => { }));
-                    if (body)
-                        yield* call(() => body.close());
-                }
-            }
-            finally {
-                credit.reservation.release();
-            }
-        }
-    });
-}
-/** Post one complete frame at a time, joining its optional response consumer before advancing input. */
-export function postCesr(url, source, options = {}, consume) {
-    // Isolate joining cleanup so a halt cannot resume a delegated caller after payload disposal.
-    return call(function* () {
-        const services = options.services ?? defaultRuntimeServices;
-        const limits = {
-            ...options.parse,
-            maxChunkBytes: options.parse?.maxChunkBytes ?? 1024 ** 2,
-            maxBufferedBytes: options.parse?.maxBufferedBytes ?? 8 * 1024 ** 2,
-        };
-        for (const limit of [limits.maxChunkBytes, limits.maxBufferedBytes]) {
-            if (!Number.isSafeInteger(limit) || limit < 1)
-                throw new RangeError("Invalid output input limit");
-        }
-        if (limits.maxChunkBytes > limits.maxBufferedBytes)
-            throw new RangeError("Chunk limit exceeds buffer limit");
-        if (limits.resources && limits.resources !== services.resources) {
-            throw new RangeError("Output parser must share its HTTP resource policy");
-        }
-        // Registered before parsing: its stream/cursor/producer credit outlives all parser and source cleanup.
-        yield* resource(function* (provide) {
-            const credit = services.resources.reserve({
-                streams: 1,
-                bytes: limits.maxChunkBytes + limits.maxBufferedBytes,
-            });
-            if (credit.kind === "refuse") {
-                const refusal = new ResourceAdmissionError(`Output source admission refused: ${credit.reason}`, credit.reason);
-                options.onAdmissionRefusal?.(refusal);
-                throw refusal;
-            }
-            try {
-                yield* provide();
-            }
-            finally {
-                credit.reservation.release();
-            }
-        });
-        // Either caller-facing signal cancels both parsing and the request already consuming a frame.
-        const signals = [options.signal, options.parse?.signal].filter((value) => value !== undefined);
-        const signal = signals.length ? AbortSignal.any(signals) : undefined;
-        // The adapter owns input cancellation and leaves each delivered ESSR payload with this loop.
-        const channel = yield* toEffectionFrames(source, {
-            ...limits,
-            resources: services.resources,
-            signal,
-            onAdmissionRefusal(error) {
-                options.parse?.onAdmissionRefusal?.(error);
-                options.onAdmissionRefusal?.(error);
-            },
-        });
-        for (const frame of yield* each(channel.frames)) {
-            try {
-                // Each request is closed before another frame or request can become resident.
-                yield* scoped(function* () {
-                    const response = yield* openFrameResponse(url, frame, { ...options, services, signal }, 0);
-                    if (consume)
-                        yield* consume(response);
-                });
-            }
-            finally {
-                yield* call(() => discardFrame(frame));
-            }
-            yield* each.next();
-        }
-    });
-}

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

@@ -1,12 +0,0 @@
-/** Count finite ordinary metadata without qualifying bytes or opening any ESSR owner. */
-export function cesrOutputMetadataBytes(root) {
-    let size = root.body.raw.length;
-    for (const group of root.attachments)
-        size += group.raw.length;
-    for (const child of root.nests ?? [])
-        size += cesrOutputMetadataBytes(child);
-    if (!Number.isSafeInteger(size) || size < 0) {
-        throw new RangeError("output metadata bytes must be a non-negative safe integer");
-    }
-    return size;
-}

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

@@ -1,24 +0,0 @@
-import * as dntShim from "../../_dnt.shims.js";
-import { annotate, ANNOTATION_LIMIT } from "cesr-ts";
-import { abortable } from "../abortable.js";
-import { collectBytes, fileBytes, streamBytes } from "../byte-source.js";
-import { colorizeAnnotatedOutput } from "./annotate-color.js";
-import { writeStdout } from "./output.js";
-/** Annotate bounded file/stdin input with every I/O leaf owned by this operation. */
-export function* annotateCommand(args) {
-    const options = args;
-    const limit = options.maxBytes ?? ANNOTATION_LIMIT;
-    const bytes = yield* abortable((signal) => collectBytes(options.inPath ? fileBytes(options.inPath, { signal }) : streamBytes(dntShim.Deno.stdin.readable, { signal }), limit));
-    const text = yield* abortable((signal) => annotate(bytes, {
-        pretty: options.pretty,
-        maxBytes: limit,
-        signal,
-    }));
-    if (options.outPath) {
-        yield* abortable((signal) => dntShim.Deno.writeTextFile(options.outPath, text, { signal }));
-    }
-    else {
-        const output = options.colored ? colorizeAnnotatedOutput(text) : text;
-        yield* abortable((signal) => writeStdout(`${output}\n`, signal));
-    }
-}

package/esm/keri/npm/src/app/cli/challenge.js

@@ -1,168 +0,0 @@
-import { action } from "effection";
-import { ValidationError } from "../../core/errors.js";
-import { processMailboxTurn } from "../agent-runtime.js";
-import { normalizeCesrBodyMode } from "../cesr-http.js";
-import { findVerifiedChallengeResponse, formatChallengeWords, generateChallengeWords, markChallengeVerified, parseChallengeWords, } from "../challenging.js";
-import { sendExchangeMessage } from "../forwarding.js";
-import { Organizer } from "../organizing.js";
-import { withAgentRuntime, withExistingHab } from "./common/context.js";
-/** Implement `tufa challenge generate`. */
-export function* challengeGenerateCommand(args) {
-    const commandArgs = {
-        strength: args.strength ? Number(args.strength) : 128,
-        out: args.out,
-    };
-    const out = normalizeOutput(commandArgs.out);
-    const words = generateChallengeWords(commandArgs.strength ?? 128);
-    console.log(formatChallengeWords(words, out));
-}
-/** Implement `tufa challenge respond` by sending a signed `/challenge/response` exchange message. */
-export function* challengeRespondCommand(args) {
-    const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        alias: args.alias,
-        recipient: args.recipient,
-        words: args.words,
-        transport: args.transport,
-        compat: args.compat,
-        outboxer: args.outboxer,
-        cesrBodyMode: normalizeCesrBodyMode(args.cesrBodyMode),
-    };
-    if (!commandArgs.name) {
-        throw new ValidationError("Name is required and cannot be empty");
-    }
-    if (!commandArgs.alias) {
-        throw new ValidationError("Alias is required and cannot be empty");
-    }
-    if (!commandArgs.recipient) {
-        throw new ValidationError("Recipient prefix is required.");
-    }
-    if (!commandArgs.words) {
-        throw new ValidationError("Challenge words are required.");
-    }
-    const words = parseChallengeWords(commandArgs.words);
-    if (words.length === 0) {
-        throw new ValidationError("Challenge words must not be empty.");
-    }
-    const recipient = commandArgs.recipient;
-    yield* withExistingHab(commandArgs, commandArgs.alias, {
-        compat: commandArgs.compat ?? false,
-        readonly: false,
-        skipConfig: false,
-        skipSignator: false,
-        outboxer: commandArgs.outboxer ?? false,
-        cesrBodyMode: commandArgs.cesrBodyMode,
-    }, function* ({ hby, hab }) {
-        const { serder } = yield* sendExchangeMessage(hby, hab, {
-            recipient,
-            route: "/challenge/response",
-            topic: "challenge",
-            payload: { i: hab.pre, words },
-            delivery: normalizeTransport(commandArgs.transport),
-        });
-        console.log("Sent EXN message");
-        console.log(serder.pretty());
-    });
-}
-/** Implement `tufa challenge verify` by matching accepted challenge responses in local exchange state. */
-export function* challengeVerifyCommand(args) {
-    const commandArgs = {
-        name: args.name,
-        base: args.base,
-        headDirPath: args.headDirPath,
-        passcode: args.passcode,
-        signer: args.signer,
-        words: args.words,
-        generate: args.generate,
-        strength: args.strength ? Number(args.strength) : undefined,
-        out: args.out,
-        timeout: args.timeout ? Number(args.timeout) : 10,
-        compat: args.compat,
-        outboxer: args.outboxer,
-        cesrBodyMode: normalizeCesrBodyMode(args.cesrBodyMode),
-        pollDelayMs: args.pollDelayMs ? Number(args.pollDelayMs) : undefined,
-    };
-    if (!commandArgs.name) {
-        throw new ValidationError("Name is required and cannot be empty");
-    }
-    if (!commandArgs.signer) {
-        throw new ValidationError("Signer identifier or contact alias is required.");
-    }
-    if (!commandArgs.generate && !commandArgs.words) {
-        throw new ValidationError("Challenge words are required.");
-    }
-    const words = commandArgs.generate
-        ? generateChallengeWords(commandArgs.strength ?? 128)
-        : parseChallengeWords(commandArgs.words);
-    if (words.length === 0) {
-        throw new ValidationError("Challenge words must not be empty.");
-    }
-    const signerInput = commandArgs.signer;
-    yield* withAgentRuntime(commandArgs, {
-        compat: commandArgs.compat ?? false,
-        readonly: false,
-        skipConfig: false,
-        skipSignator: true,
-        outboxer: commandArgs.outboxer ?? false,
-        cesrBodyMode: commandArgs.cesrBodyMode,
-    }, function* ({ hby, runtime }) {
-        const signer = resolveSigner(hby, signerInput);
-        if (commandArgs.generate) {
-            console.log(formatChallengeWords(words, normalizeOutput(commandArgs.out)));
-        }
-        runtime.mailboxDirector.topics.clear();
-        runtime.mailboxDirector.registerTopic("/challenge");
-        const timeoutMs = Math.max(1, commandArgs.timeout ?? 10) * 1000;
-        const pollDelayMs = Math.max(1, commandArgs.pollDelayMs ?? 250);
-        const deadline = Date.now() + timeoutMs;
-        let match = findVerifiedChallengeResponse(hby.db, signer, words);
-        while (!match && Date.now() < deadline) {
-            yield* processMailboxTurn(runtime);
-            match = findVerifiedChallengeResponse(hby.db, signer, words);
-            if (!match && Date.now() < deadline) {
-                yield* sleep(pollDelayMs);
-            }
-        }
-        if (!match) {
-            throw new ValidationError(`No challenge response from ${signerInput} matched the provided words.`);
-        }
-        markChallengeVerified(hby.db, signer, match);
-        console.log(`${signer} ${match.said}`);
-    });
-}
-function resolveSigner(hby, signer) {
-    if (hby.db.getKever(signer)) {
-        return signer;
-    }
-    const matches = new Organizer(hby).findExact("alias", signer);
-    if (matches.length === 0) {
-        throw new ValidationError(`no contact found with alias '${signer}'`);
-    }
-    if (matches.length > 1) {
-        throw new ValidationError(`multiple contacts match alias '${signer}', use prefix instead`);
-    }
-    return matches[0].id;
-}
-function normalizeOutput(input) {
-    const out = input ?? "json";
-    if (out === "json" || out === "string" || out === "words") {
-        return out;
-    }
-    throw new ValidationError(`Unsupported challenge output ${String(input)}.`);
-}
-function normalizeTransport(input) {
-    const value = input ?? "auto";
-    if (value === "auto" || value === "direct" || value === "indirect") {
-        return value;
-    }
-    throw new ValidationError(`Unsupported exchange transport ${String(input)}.`);
-}
-function* sleep(ms) {
-    yield* action((resolve) => {
-        const timeoutId = setTimeout(() => resolve(undefined), ms);
-        return () => clearTimeout(timeoutId);
-    });
-}

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("");
-}