keri-ts 1.0.0 → 2.0.0

package/esm/keri/npm/src/app/runtime/runtime-clock.js

@@ -0,0 +1,6 @@
+/** Production clock; application composition supplies it to its consumers. */
+export const systemClock = Object.freeze({
+    now: () => Date.now(),
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (timer) => clearTimeout(timer),
+});

package/esm/keri/npm/src/app/{byte-source.js → transport/byte-source.js}

@@ -1,7 +1,13 @@
 /** Transport readers. Each operation owns its reader and joins cancellation. */
 /** Cancellation and chunk size for byte-array and file sources. */
-import * as dntShim from "../_dnt.shims.js";
-/** Adapt an already resident finite value into independent bounded parser chunks. */
+import * as dntShim from "../../_dnt.shims.js";
+/**
+ * Adapt an already resident finite value into independent bounded parser chunks.
+ *
+ * @param bytes Borrowed resident input; each yielded chunk is a copy independent of subsequent producer mutation.
+ * @param options Optional signal and positive integer chunk size in bytes; defaults to 65536.
+ * @yields Copied byte chunks in input order; this does not parse message boundaries.
+ */
 export async function* chunkBytes(bytes, { signal, maxChunkBytes = 64 * 1024 } = {}) {
     checkLimit(maxChunkBytes);
     signal?.throwIfAborted();
@@ -11,7 +17,14 @@ export async function* chunkBytes(bytes, { signal, maxChunkBytes = 64 * 1024 } =
         yield bytes.slice(offset, offset + maxChunkBytes);
     }
 }
-/** Read a Fetch stream on demand and cancel its reader when parsing stops. */
+/**
+ * Read a Fetch stream on demand and cancel its reader when parsing stops.
+ *
+ * @param stream Borrowed Web stream to read exclusively; null yields no bytes.
+ * @param options Optional signal that cancels the pending read.
+ * @yields Nonempty chunks supplied by the underlying stream.
+ * @throws Read/cancel/unlock failures, combined when distinct failures occur.
+ */
 export async function* streamBytes(stream, { signal } = {}) {
     signal?.throwIfAborted();
     if (!stream)
@@ -68,7 +81,14 @@ export async function* streamBytes(stream, { signal } = {}) {
             throw errors[0];
     }
 }
-/** Stream a local file with fixed-size owned buffers and close it on break or abort. */
+/**
+ * Stream a local file with fixed-size owned buffers and close it on break or abort.
+ *
+ * @param path Local filesystem path opened read-only for this iteration.
+ * @param options Optional cancellation and positive read buffer size in bytes; defaults to 65536.
+ * @yields Owned buffers up to the selected chunk size until file EOF.
+ * @throws Open/read failures or cancellation; the file closes on EOF, break or failure.
+ */
 export async function* fileBytes(path, { signal, maxChunkBytes = 64 * 1024 } = {}) {
     checkLimit(maxChunkBytes);
     signal?.throwIfAborted();
@@ -99,7 +119,12 @@ export async function* fileBytes(path, { signal, maxChunkBytes = 64 * 1024 } = {
         close();
     }
 }
-/** Collect an explicitly finite operation; bulk ingress should consume its source directly. */
+/**
+ * Collect an explicitly finite operation; bulk ingress should consume its source directly.
+ *
+ * @param source Finite byte source whose iteration errors propagate; do not pass an unbounded mailbox stream.
+ * @returns A contiguous owned array containing all chunks in order.
+ */
 export async function collectBytes(source) {
     let bytes = new Uint8Array(0);
     let size = 0;
@@ -116,7 +141,12 @@ export async function collectBytes(source) {
     }
     return bytes.subarray(0, size);
 }
-/** Reject invalid chunk sizes before allocation or opening a file. */
+/**
+ * Reject invalid chunk sizes before allocation or opening a file.
+ *
+ * @param limit Requested per-chunk byte count.
+ * @throws RangeError unless the count is a positive safe integer.
+ */
 function checkLimit(limit) {
     if (!Number.isSafeInteger(limit) || limit < 1)
         throw new RangeError("Chunk size must be a positive safe integer");

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

@@ -0,0 +1,317 @@
+/**
+ * CESR framing and bounded media negotiation over explicitly owned HTTP attempts.
+ * Ordinary send helpers finish response EOF/cleanup and return delivery facts.
+ * requestFrame instead lends a live response from an Effection resource: its
+ * caller consumes that body before leaving the enclosing scope. Neither path
+ * implicitly feeds successful response bytes into protocol processing.
+ *
+ * Match KERIpy's detached-attachment POST contract while retaining the exact
+ * signed body. Only the known pre-intake Falcon media refusal permits a second
+ * request; authentication/application failures and network errors are not retries.
+ */
+import { attachmentPayload, byteString, collectPayload, parse, } from "cesr-ts";
+import { call, ensure, race, resource, scoped } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { abortable, cleanupFailures, throwOnAbort } from "../runtime/abortable.js";
+import { CESR_ATTACHMENT_HEADER, CESR_CONTENT_TYPE, CESR_DESTINATION_HEADER, KERIPY_CESR_JSON_CONTENT_TYPE, } from "./cesr-http.js";
+/** Positive remote HTTP refusal, distinct from source, transport, storage and cleanup failure. */
+export class CesrHttpRefusal extends ValidationError {
+    /**
+     * Describe a completed HTTP refusal without classifying it as a network failure.
+     *
+     * @param message Endpoint/status detail for the observed peer refusal.
+     * @param status Actual non-success HTTP status returned by the peer.
+     */
+    constructor(message, status) {
+        super(message);
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: status
+        });
+    }
+}
+/**
+ * Drain successful response bytes; retain refusal text for reporting and media negotiation.
+ *
+ * @param response Borrowed response; this function consumes its body once to EOF.
+ * @param signal Cancels the pending body read through its HTTP owner.
+ * @returns Decoded refusal text, or an empty string after draining a successful body.
+ * @throws Body-read or cancellation errors propagate; an HTTP status alone does not throw.
+ */
+export async function readResponseDetail(response, signal) {
+    const decoder = response.ok ? undefined : new TextDecoder();
+    const text = [];
+    for await (const chunk of response.body(signal)) {
+        if (decoder)
+            text.push(decoder.decode(chunk, { stream: true }));
+    }
+    if (decoder)
+        text.push(decoder.decode());
+    return text.join("");
+}
+/**
+ * Open one frame response for a caller that needs to consume its bytes.
+ * The caller must keep its scope alive while reading; returning this handle from
+ * a closing scope does not transfer response ownership. Media fallback closes the
+ * rejected attempt before opening the legacy header-media attempt.
+ * The handle travels directly as this generator's return value: yield* requestFrame
+ * resumes with HttpStreamResponse while its resource remains provided to the
+ * enclosing scope. This is borrowing, not a detached response or a consume callback.
+ *
+ * @param url HTTP(S) endpoint to receive the framed POST; redirect handling is manual.
+ * @param frame Parsed signed body and attachments; framing preserves the signed body bytes.
+ * @param http Borrowed HTTP implementation supplied by composition; owns native request/body I/O.
+ * @param options Destination, extra headers and optional cancellation for ordinary signed-message POSTs.
+ * @returns A successful response borrowed until the enclosing Effection scope ends.
+ * @throws CesrHttpRefusal for a completed refusal; request, transport and cleanup failures propagate.
+ */
+export function* requestFrame(url, frame, http, options = {}) {
+    const result = yield* openFrameResponse(url, frame, http, options);
+    if (result.kind === "refuse")
+        throw result.error;
+    return result.response;
+}
+/**
+ * Own the response scope for one frame and the existing header-media fallback.
+ * A successful response stays live while the borrowing consumer runs. A refused
+ * response is drained for its detail, and its scope closes before another attempt.
+ *
+ * @param url HTTP(S) endpoint to receive the framed POST; redirect handling is manual.
+ * @param frame Parsed signed body and attachments; framing preserves the signed body bytes.
+ * @param http Borrowed HTTP implementation supplied by composition; owns native request/body I/O.
+ * @param options Destination, extra headers and optional cancellation for ordinary signed-message POSTs.
+ * @returns A scoped successful response or completed refusal, after any permitted media fallback.
+ */
+function openFrameResponse(url, frame, http, options) {
+    return resource(function* (provide) {
+        for (const request of yield* frameRequests(frame, options)) {
+            const retry = yield* scoped(function* () {
+                const response = yield* http.open(url, request);
+                if (response.ok) {
+                    // Keep this request scope live throughout the borrowing consumer's response processing.
+                    yield* provide({ kind: "response", response });
+                    return false;
+                }
+                const detail = yield* abortable((signal) => readResponseDetail(response, signal), options.signal);
+                if (isLegacyCesrMediaRejection(request, response.status, detail))
+                    return true;
+                yield* provide({
+                    kind: "refuse",
+                    error: new CesrHttpRefusal(`CESR delivery to ${url} failed with HTTP ${response.status}: ${detail}`, response.status),
+                });
+                return false;
+            });
+            if (!retry)
+                return;
+        }
+    });
+}
+/**
+ * Prepare finite request bytes before opening any network attempt.
+ * Ordinary POSTs put normalized text attachments in CESR-ATTACHMENT and send the
+ * original body. CESR-Genus retains the observed counter context when stream framing is removed.
+ * Requests retain
+ * caller authentication headers; sender-owned framing/destination headers replace
+ * conflicting caller values. The fallback shares the prepared bytes.
+ *
+ * @param frame Parsed signed body and attachments; framing preserves the signed body bytes.
+ * @param options Destination, extra headers and optional cancellation for ordinary signed-message POSTs.
+ * @returns Current and legacy media choices sharing the same signed body.
+ */
+function* frameRequests(frame, options) {
+    const header = byteString(yield* abortable((signal) => collectPayload(attachmentPayload(frame, { domain: "txt" }), signal), options.signal));
+    const body = frame.body.raw;
+    const types = [CESR_CONTENT_TYPE, KERIPY_CESR_JSON_CONTENT_TYPE];
+    const prepared = body.slice().buffer;
+    return types.map((contentType) => {
+        const headers = new Headers(options.headers);
+        headers.set("Content-Type", contentType);
+        headers.delete(CESR_DESTINATION_HEADER);
+        headers.delete(CESR_ATTACHMENT_HEADER);
+        headers.delete("CESR-Genus");
+        if (frame.gvrsn)
+            headers.set("CESR-Genus", String(frame.gvrsn.major));
+        if (options.destination)
+            headers.set(CESR_DESTINATION_HEADER, options.destination);
+        headers.set(CESR_ATTACHMENT_HEADER, header);
+        return {
+            method: "POST",
+            redirect: "manual",
+            headers,
+            signal: options.signal,
+            body: prepared,
+        };
+    });
+}
+/**
+ * Recognize KERIpy v1's exact preprocessing media refusal, before protocol intake.
+ * Attachment framing and the current media type are required. Authentication,
+ * KRAM and application refusals cannot trigger a second submission merely by
+ * mentioning content type in their diagnostic text.
+ *
+ * @param request Exact prepared request whose response is being classified.
+ * @param status Observed peer HTTP status.
+ * @param detail Fully consumed refusal body decoded as text.
+ * @returns True only for the pinned Falcon content-type error representation.
+ */
+export function isLegacyCesrMediaRejection(request, status, detail) {
+    const headers = new Headers(request.headers);
+    if (!headers.has(CESR_ATTACHMENT_HEADER) || status !== 406 || headers.get("Content-Type") !== CESR_CONTENT_TYPE) {
+        return false;
+    }
+    let refusal;
+    try {
+        refusal = JSON.parse(detail);
+    }
+    catch {
+        return false;
+    }
+    return typeof refusal === "object" && refusal !== null
+        && "title" in refusal && refusal.title === "Content type error"
+        && "description" in refusal && refusal.description === "Unacceptable content type.";
+}
+/**
+ * Send a frame whose caller needs delivery status rather than response content.
+ * HttpClient.request has consumed the entire response before returning. Successful
+ * bytes are intentionally discarded here; callers needing protocol intake use the
+ * scoped response path. Completion proves HTTP delivery, not protocol acceptance.
+ *
+ * @param url HTTP(S) endpoint to receive the framed POST; redirect handling is manual.
+ * @param frame Parsed signed body and attachments; framing preserves the signed body bytes.
+ * @param http Borrowed HTTP implementation supplied by composition; owns native request/body I/O.
+ * @param options Destination, extra headers and optional cancellation for ordinary signed-message POSTs.
+ * @returns Complete after finite response consumption/cleanup, or a typed peer refusal.
+ * @throws Construction, native transport and cleanup failures propagate.
+ */
+function* sendFrame(url, frame, http, options) {
+    for (const request of yield* frameRequests(frame, options)) {
+        const response = yield* http.request(url, request);
+        if (response.ok)
+            return { kind: "complete" };
+        const detail = new TextDecoder().decode(response.body);
+        if (isLegacyCesrMediaRejection(request, response.status, detail))
+            continue;
+        return {
+            kind: "refuse",
+            error: new CesrHttpRefusal(`CESR delivery to ${url} failed with HTTP ${response.status}: ${detail}`, response.status),
+        };
+    }
+    throw new Error("CESR media negotiation exhausted its request choices");
+}
+/**
+ * Send a CESR source and throw on a completed peer refusal.
+ * One parsed frame becomes one POST, and its request scope closes before the next
+ * source pull. A refusal stops the sequence; prior frames may already be delivered.
+ * Cancellation aborts active work, joins any pending source pull and returns the
+ * parser iterator before leaving. There is no automatic retry beyond media fallback.
+ * A pending asynchronous source pull can finish after cancellation is requested;
+ * abort it first, then join that pull and return the iterator. Genuine late
+ * cleanup failures are retained alongside the primary failure rather than
+ * misreported as harmless cancellation.
+ *
+ * @param url HTTP(S) endpoint to receive the framed POST; redirect handling is manual.
+ * @param source Creates the CESR byte source for this invocation; it must observe the supplied abort signal.
+ * @param http Borrowed HTTP implementation supplied by composition; owns native request/body I/O.
+ * @param options Destination, extra headers and optional cancellation for ordinary signed-message POSTs.
+ * @throws Source/parser, transport and cleanup failures propagate without becoming peer refusals. A completed refusal throws CesrHttpRefusal.
+ */
+export function* postCesr(url, source, http, options = {}) {
+    const result = yield* attemptPostCesr(url, source, http, options);
+    if (result.kind === "refuse")
+        throw result.error;
+}
+/**
+ * Send frames sequentially and return a completed peer refusal as data.
+ * One parsed frame becomes one POST, and its request scope closes before the next
+ * source pull. A refusal stops the sequence; prior frames may already be delivered.
+ * Cancellation aborts active work, joins any pending source pull and returns the
+ * parser iterator before leaving. There is no automatic retry beyond media fallback.
+ *
+ * @param url HTTP(S) endpoint to receive the framed POST; redirect handling is manual.
+ * @param source Creates the CESR byte source for this invocation; it must observe the supplied abort signal.
+ * @param http Borrowed HTTP implementation supplied by composition; owns native request/body I/O.
+ * @param options Destination, extra headers and optional cancellation for ordinary signed-message POSTs.
+ * @returns The attempt result after all frames or the first refusal, with source/request cleanup joined.
+ * @throws Source/parser, transport and cleanup failures propagate without becoming peer refusals.
+ */
+export function attemptPostCesr(url, source, http, options = {}) {
+    // Isolate joining cleanup so a halt cannot resume a delegated caller after payload disposal.
+    const posting = call(function* () {
+        const controller = new AbortController();
+        const signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+        let failure;
+        try {
+            signal.throwIfAborted();
+            const frames = parse(source(signal));
+            let pending;
+            // The earlier resource joins the read after processing children stop.
+            yield* ensure(function* () {
+                const cleanup = [];
+                /**
+                 * Retain distinct late failures without duplicating the primary rejection.
+                 * @param error Rejection from joining a pending pull or returning the parser.
+                 */
+                const noteCleanup = (error) => {
+                    for (const remaining of cleanupFailures(error, signal)) {
+                        if (!(failure && remaining === failure.error) && !cleanup.includes(remaining))
+                            cleanup.push(remaining);
+                    }
+                };
+                if (pending) {
+                    try {
+                        yield* call(() => pending);
+                    }
+                    catch (error) {
+                        noteCleanup(error);
+                    }
+                }
+                try {
+                    yield* call(() => frames.return());
+                }
+                catch (error) {
+                    noteCleanup(error);
+                }
+                if (cleanup.length) {
+                    const errors = failure && failure.error !== signal.reason ? [failure.error, ...cleanup] : cleanup;
+                    if (errors.length === 1)
+                        throw errors[0];
+                    throw new AggregateError(errors, "CESR delivery and source cleanup failed", { cause: errors[0] });
+                }
+            });
+            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* sendFrame(url, frame, http, { ...options, signal });
+                if (posted.kind === "refuse")
+                    return posted;
+            }
+        }
+        catch (error) {
+            failure = { error };
+            throw error;
+        }
+        finally {
+            controller.abort();
+        }
+        return { kind: "complete" };
+    });
+    if (!options.signal)
+        return posting;
+    return race([posting, throwOnAbort(options.signal)]);
+}

package/esm/keri/npm/src/app/{cesr-http.js → transport/cesr-http.js}

@@ -6,17 +6,10 @@
  * 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 { parseBytes, parseSerder, requireFlatFrame, SerderKERI, smell } from "cesr-ts";
-import { ValidationError } from "../core/errors.js";
+import { Counter, parseBytes, parseSerder, requireFlatFrame, SerderKERI, smell } from "cesr-ts";
+import { ValidationError } from "../../core/errors.js";
 import { collectBytes, streamBytes } from "./byte-source.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. */
@@ -39,51 +32,15 @@ export function isCesrContentType(value) {
 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) {
+/** Build ordinary signed-message POST framing, preserving the signed body bytes. */
+export function buildCesrRequest(message, { contentType = CESR_CONTENT_TYPE, destination } = {}) {
+    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)),
-    };
+    return { headers, body: arrayBufferFromBytes(message.slice(0, serder.size)) };
 }
 /**
  * Build one raw CESR-body HTTP request.
@@ -106,15 +63,24 @@ export function buildCesrStreamRequest(bytes, { destination } = {}) {
 /**
  * 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.
+ * Header mode restores the declared `CESR-Genus` before the unchanged body and
+ * appends `CESR-ATTACHMENT`; body protocol version does not select that context.
  */
 export function requestBytes(req, options = {}) {
     return read();
     /** Acquire the body lazily, then append detached attachments in their original order. */
     async function* read() {
+        const cesr = isCesrContentType(req.headers.get("content-type"));
+        const genus = cesr ? req.headers.get("CESR-Genus") : null;
+        if (genus !== null) {
+            if (genus !== "1" && genus !== "2") {
+                throw new ValidationError("CESR-Genus must be 1 or 2");
+            }
+            (options.signal ?? req.signal).throwIfAborted();
+            yield Counter.makeGVC({ major: genus === "1" ? 1 : 2, minor: 0 });
+        }
         const attachment = req.headers.get(CESR_ATTACHMENT_HEADER);
-        const tail = attachment && isCesrContentType(req.headers.get("content-type"))
+        const tail = attachment && cesr
             ? textEncoder.encode(attachment)
             : null;
         yield* streamBytes(req.body, { signal: req.signal, ...options });
@@ -196,8 +162,7 @@ export async function readMailboxAdminRequest(req) {
 /** 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);
+        const serder = parseBytes(bytes)[0]?.body;
         return serder instanceof SerderKERI ? serder : null;
     }
     catch {