@keri-ts/hosting 0.0.0-stage → 2.0.1

package/esm/hosting/npm/src/src/host/kernel.js

@@ -0,0 +1,83 @@
+import { spawn } from "effection";
+import { systemClock } from "keri-ts/runtime";
+import { FetchHttpClient } from "keri-ts/runtime";
+import { consoleLogger, createAgentRuntime, runAgentRuntime, } from "keri-ts/runtime";
+import { startServer } from "./http-server.js";
+/**
+ * Compose and run the long-lived host over one borrowed Habery.
+ * Select HTTP/clock/polling implementations at this root, acquire runtime/listener
+ * resources in scope, and join dependent workers before owned store teardown.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param spec Explicit hosted identities, listener settings, protocol handlers and host policy.
+ */
+export function* runHostKernel(hby, spec) {
+    const runtime = yield* createAgentRuntime(hby, new FetchHttpClient(), systemClock, {
+        enableMailboxStore: spec.enableMailboxStore,
+        kram: spec.kram,
+    });
+    const hostedPrefixes = spec.hostedPrefixes ?? [spec.serviceHab.pre];
+    const protocolPolicy = {
+        ...spec.protocolPolicy,
+        serviceHab: spec.serviceHab,
+        hostedPrefixes,
+    };
+    /** Runtime worker starts only after HTTP listener acquisition; absent if startup fails earlier. */
+    let runtimeTask;
+    const companionTasks = [];
+    let closed = false;
+    /** Join companions, then runtime workers and owned stores; retain the first failure while attempting every close. */
+    const closeKernel = function* () {
+        if (closed) {
+            return;
+        }
+        let failed = false;
+        let failure;
+        for (const task of companionTasks.slice().reverse()) {
+            try {
+                yield* task.halt();
+            }
+            catch (error) {
+                failed = true;
+                failure ??= error;
+            }
+        }
+        try {
+            if (runtimeTask)
+                yield* runtimeTask.halt();
+        }
+        catch (error) {
+            failed = true;
+            failure ??= error;
+        }
+        try {
+            yield* runtime.close();
+        }
+        catch (error) {
+            failed = true;
+            failure ??= error;
+        }
+        closed = true;
+        if (failed) {
+            throw failure;
+        }
+    };
+    try {
+        for (const companion of spec.companionHosts ?? []) {
+            companionTasks.push(yield* spawn(function* () {
+                yield* companion(runtime);
+            }));
+        }
+        // Acquire the listener before consumers can poll a locally hosted provider.
+        const serverTask = yield* spawn(() => startServer(spec.http.port, consoleLogger, runtime, {
+            hostname: spec.http.hostname,
+            onListen: spec.http.onListen,
+            ...protocolPolicy,
+        }, closeKernel));
+        runtimeTask = yield* spawn(() => runAgentRuntime(runtime, { hab: spec.serviceHab }));
+        yield* serverTask;
+    }
+    finally {
+        yield* closeKernel();
+    }
+}

package/esm/hosting/npm/src/src/http/app.js

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import { installTufaHttpErrorHandling } from "./error-mapping.js";
+import { installTufaHttpPolicy, resolveTufaHttpAppPolicy } from "./policy.js";
+import { createProtocolHandler } from "./protocol-handler.js";
+/**
+ * Build the Stage 4 Hono shell for the Tufa HTTP edge.
+ *
+ * Stage 4 keeps route semantics inside the protocol handler while moving
+ * cross-cutting HTTP policy into explicit hosting-owned middleware and error
+ * mapping.
+ */
+export function createTufaApp(options = {}) {
+    const app = new Hono();
+    const policy = resolveTufaHttpAppPolicy(options.app);
+    let handler = options.protocolHandler;
+    let ownsHandler = false;
+    if (!handler) {
+        handler = createProtocolHandler(options.runtime, options.protocolPolicy ?? {});
+        ownsHandler = true;
+    }
+    installTufaHttpPolicy(app, policy);
+    installTufaHttpErrorHandling(app, policy);
+    app.all("*", async (context) => {
+        return await handler(context.req.raw);
+    });
+    return Object.assign(app, {
+        /** Join the default protocol handler's file responses; injected handlers stay caller-owned. */
+        async close() {
+            if (ownsHandler)
+                await handler.close?.();
+        },
+    });
+}

package/esm/hosting/npm/src/src/http/error-mapping.js

@@ -0,0 +1,19 @@
+import { ValidationError } from "keri-ts/runtime";
+import { applyTufaCorsHeaders } from "./policy.js";
+import { textResponse } from "./protocol/responses.js";
+/** Map one unhandled edge error into the Stage 4 HTTP response contract. */
+export function mapTufaHttpError(error, policy) {
+    if (error instanceof ValidationError) {
+        return textResponse(error.message, 400);
+    }
+    policy.logger.error("Unhandled HTTP app error", error);
+    return textResponse("Internal Server Error", 500);
+}
+/** Install the centralized Stage 4 app-level error mapping. */
+export function installTufaHttpErrorHandling(app, policy) {
+    app.onError((error, _context) => {
+        const response = mapTufaHttpError(error, policy);
+        applyTufaCorsHeaders(response.headers, policy.cors);
+        return response;
+    });
+}

package/esm/hosting/npm/src/src/http/policy.js

@@ -0,0 +1,63 @@
+import { consoleLogger } from "keri-ts/runtime";
+import { normalizeProtocolPath } from "./protocol/context.js";
+export const DEFAULT_TUFA_CORS_POLICY = Object.freeze({
+    allowOrigin: "*",
+    allowMethods: Object.freeze(["GET", "POST", "PUT", "OPTIONS"]),
+    allowHeaders: Object.freeze([
+        "Content-Type",
+        "CESR-ATTACHMENT",
+        "CESR-DESTINATION",
+        "Oobi-Aid",
+    ]),
+    exposeHeaders: Object.freeze([
+        "Content-Type",
+        "KERI-AID",
+        "Oobi-Aid",
+    ]),
+});
+/** Resolve one app policy with Stage 4 defaults. */
+export function resolveTufaHttpAppPolicy(options = {}) {
+    return {
+        logger: options.logger ?? consoleLogger,
+        cors: {
+            allowOrigin: options.cors?.allowOrigin
+                ?? DEFAULT_TUFA_CORS_POLICY.allowOrigin,
+            allowMethods: options.cors?.allowMethods
+                ?? DEFAULT_TUFA_CORS_POLICY.allowMethods,
+            allowHeaders: options.cors?.allowHeaders
+                ?? DEFAULT_TUFA_CORS_POLICY.allowHeaders,
+            exposeHeaders: options.cors?.exposeHeaders
+                ?? DEFAULT_TUFA_CORS_POLICY.exposeHeaders,
+        },
+    };
+}
+/** Install the Stage 4 middleware envelope onto one Hono app. */
+export function installTufaHttpPolicy(app, policy) {
+    app.use("*", createTufaHttpPolicyMiddleware(policy));
+}
+function createTufaHttpPolicyMiddleware(policy) {
+    return async (context, next) => {
+        const startedAt = performance.now();
+        if (context.req.method === "OPTIONS") {
+            const response = new Response(null, { status: 204 });
+            applyTufaCorsHeaders(response.headers, policy.cors);
+            logRequest(policy.logger, context.req.url, context.req.method, 204, startedAt);
+            return response;
+        }
+        await next();
+        applyTufaCorsHeaders(context.res.headers, policy.cors);
+        logRequest(policy.logger, context.req.url, context.req.method, context.res.status, startedAt);
+    };
+}
+/** Apply the resolved Stage 4 CORS policy to one response header set. */
+export function applyTufaCorsHeaders(headers, policy) {
+    headers.set("Access-Control-Allow-Origin", policy.allowOrigin);
+    headers.set("Access-Control-Allow-Methods", policy.allowMethods.join(", "));
+    headers.set("Access-Control-Allow-Headers", policy.allowHeaders.join(", "));
+    headers.set("Access-Control-Expose-Headers", policy.exposeHeaders.join(", "));
+}
+function logRequest(logger, rawUrl, method, status, startedAt) {
+    const pathname = normalizeProtocolPath(new URL(rawUrl).pathname);
+    const durationMs = Math.max(0, performance.now() - startedAt).toFixed(1);
+    logger.info(`${method} ${pathname} -> ${status} ${durationMs}ms`);
+}

package/esm/hosting/npm/src/src/http/protocol/artifact-files.js

@@ -0,0 +1,164 @@
+/** Demand-driven static artifact responses; the host owns open files through joined response cleanup. */
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+const CHUNK = 64 * 1024;
+/** Own one host's open file responses, including bodies that have not been consumed. */
+export class ArtifactFiles {
+    constructor() {
+        Object.defineProperty(this, "owners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "stopping", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "closing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+    }
+    /** Open the regular file and capture its extent without reading data. */
+    async response(path, contentType, signal) {
+        signal.throwIfAborted();
+        if (this.stopping)
+            throw new DOMException("Artifact host closed", "AbortError");
+        let file, reading;
+        let controller;
+        let ended = false, closing;
+        // Nonblocking open lets the regular-file check reject pipes without hanging acquisition/shutdown.
+        const opening = Promise.resolve().then(() => open(path, constants.O_RDONLY | constants.O_NONBLOCK));
+        /** Stop new reads and join acquisition, the current read and file close. */
+        const close = (reason) => {
+            if (closing)
+                return closing;
+            ended = true;
+            closing = (async () => {
+                const failures = [];
+                try {
+                    try {
+                        if (reason !== undefined)
+                            controller?.error(reason);
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    const acquired = await opening.catch(() => undefined);
+                    try {
+                        await reading;
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    try {
+                        await acquired?.close();
+                    }
+                    catch (error) {
+                        if (!failures.includes(error))
+                            failures.push(error);
+                    }
+                }
+                finally {
+                    this.owners.delete(close);
+                }
+                if (failures.length === 1)
+                    throw failures[0];
+                if (failures.length)
+                    throw new AggregateError(failures, "Artifact read and cleanup failed");
+            })();
+            return closing;
+        };
+        this.owners.add(close);
+        try {
+            file = await opening;
+            const stat = await file.stat();
+            signal.throwIfAborted(); // The request signal owns acquisition, never the returned response lifetime.
+            if (ended)
+                throw new DOMException("Artifact host closed", "AbortError");
+            if (!stat.isFile()) {
+                await close();
+                return new Response("Not Found", { status: 404 });
+            }
+            if (!Number.isSafeInteger(stat.size) || stat.size < 0)
+                throw new RangeError("Invalid artifact extent");
+            if (stat.size === 0) {
+                await close();
+                return new Response(null, { headers: { "Content-Type": contentType, "Content-Length": "0" } });
+            }
+            let remaining = stat.size;
+            const body = new ReadableStream({
+                start(value) {
+                    controller = value;
+                },
+                pull: async (output) => {
+                    if (ended)
+                        return;
+                    try {
+                        if (remaining === 0) {
+                            await close();
+                            output.close();
+                            return;
+                        }
+                        const chunk = new Uint8Array(Math.min(CHUNK, remaining));
+                        // The positional overload requires an explicit extent for this typed buffer.
+                        reading = file.read(chunk, 0, chunk.byteLength, null);
+                        const { bytesRead } = await reading;
+                        reading = undefined;
+                        if (ended)
+                            return;
+                        if (bytesRead === 0)
+                            throw new Error("Artifact truncated during response");
+                        remaining -= bytesRead;
+                        output.enqueue(chunk.subarray(0, bytesRead));
+                    }
+                    catch (error) {
+                        reading = undefined; // This read has settled; close must still join any concurrently started cleanup.
+                        let failure = error;
+                        try {
+                            await close();
+                        }
+                        catch (cleanup) {
+                            const failures = cleanup instanceof AggregateError ? cleanup.errors : [cleanup];
+                            failure = failures.includes(error)
+                                ? cleanup
+                                : new AggregateError([error, ...failures], "Artifact read and cleanup failed");
+                        }
+                        output.error(failure);
+                    }
+                },
+                cancel: () => close(),
+            }, { highWaterMark: 0 });
+            return new Response(body, {
+                headers: { "Content-Type": contentType, "Content-Length": String(stat.size) },
+            });
+        }
+        catch (error) {
+            try {
+                await close();
+            }
+            catch (cleanup) {
+                throw new AggregateError([error, cleanup], "Artifact acquisition and cleanup failed");
+            }
+            throw error;
+        }
+    }
+    /** Close every file, including pending acquisitions, before the HTTP host finishes shutdown. */
+    close() {
+        this.stopping = true;
+        return this.closing ??= (async () => {
+            const reason = new DOMException("Artifact host closed", "AbortError");
+            const results = await Promise.allSettled([...this.owners].map(async (close) => await close(reason)));
+            const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length)
+                throw new AggregateError(failures, "Artifact host cleanup failed");
+        })();
+    }
+}

package/esm/hosting/npm/src/src/http/protocol/context.js

@@ -0,0 +1,48 @@
+/**
+ * Request-context construction for Tufa protocol routing.
+ *
+ * The router is path-first: every endpoint classifier receives the same
+ * normalized path plus hosted-prefix projections, so mailbox admin, OOBI, and
+ * generic CESR ingress cannot disagree about which local AID a URL addresses.
+ */
+import { resolveHostedEndpointPath } from "keri-ts/runtime";
+import { parseOobiRouteRequest } from "./endpoints/oobi.js";
+/** Snapshot one request into the path-first routing context. */
+export function buildProtocolRequestContext(req, runtime, policy = {}) {
+    const url = new URL(req.url);
+    const pathname = normalizeProtocolPath(url.pathname);
+    // Resolve the same normalized path against the three hosted path shapes used
+    // by the HTTP edge: plain hosted endpoints, mailbox admin endpoints, and
+    // generic root-relative CESR ingress.
+    const hosted = runtime
+        ? resolveHostedEndpointPath(runtime.hby, pathname, "", policy.hostedPrefixes)
+        : null;
+    const mailboxAdmin = runtime
+        ? resolveHostedEndpointPath(runtime.hby, pathname, "/mailboxes", policy.hostedPrefixes)
+        : null;
+    const genericIngress = runtime
+        ? resolveHostedEndpointPath(runtime.hby, pathname, "/", policy.hostedPrefixes)
+        : null;
+    const oobiPath = hosted?.relativePath ?? pathname;
+    return {
+        req,
+        url,
+        pathname,
+        method: req.method,
+        runtime,
+        policy,
+        hosted,
+        mailboxAdmin,
+        genericIngress,
+        oobi: parseOobiRouteRequest(oobiPath),
+    };
+}
+/** Normalize incoming request paths into the comparison form used by routing. */
+export function normalizeProtocolPath(pathname) {
+    const trimmed = pathname.trim();
+    if (trimmed.length === 0 || trimmed === "/") {
+        return "/";
+    }
+    const normalized = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return normalized.replace(/\/+$/, "") || "/";
+}

package/esm/hosting/npm/src/src/http/protocol/endpoints/did-resolution.js

@@ -0,0 +1,90 @@
+/** Universal Resolver compatible DID route. */
+import { run } from "effection";
+import { didResolutionError, parseDidKeriIdentifier, resolveDidKeri, resolveDidWebs, runtimeOobiConverged, } from "keri-ts/runtime";
+const IDENTIFIERS_PREFIX = "/1.0/identifiers/";
+/** Classify `/1.0/identifiers/{did}` requests. */
+export function classifyDidResolutionRoute(context) {
+    if (context.method !== "GET" || !context.pathname.startsWith(IDENTIFIERS_PREFIX)) {
+        return null;
+    }
+    const encoded = context.pathname.slice(IDENTIFIERS_PREFIX.length);
+    if (encoded.length === 0) {
+        return null;
+    }
+    return { kind: "didResolution", did: decodeDidIdentifierPath(encoded) };
+}
+/**
+ * Handle one Universal Resolver request.
+ *
+ * @param context Request-owned host context with the configured runtime/registry.
+ * @param did Requested DID to resolve and verify.
+ * @returns HTTP resolution response based on accepted KERI/VDR state.
+ */
+export async function handleDidResolutionRoute(context, did) {
+    const meta = wantsResolutionResult(context.req, context.url);
+    if (!context.runtime) {
+        return jsonResponse(didResolutionError("internalError", "DID resolver runtime is not available."), 500);
+    }
+    try {
+        const oobis = context.url.searchParams.getAll("oobi");
+        let result = null;
+        if (did.startsWith("did:webs:") || did.startsWith("did:web:")) {
+            const rgy = context.runtime.vdr;
+            if (!rgy)
+                throw new Error("Legacy credential registry is unavailable in this runtime.");
+            result = await run(() => resolveDidWebs(rgy, context.runtime.reactor, context.runtime.http, {
+                did,
+                metadata: meta,
+                insecureHttp: context.policy.dwsInsecureHttp ?? false,
+            }));
+        }
+        else if (did.startsWith("did:keri:")) {
+            const canonical = parseDidKeriIdentifier(did).canonical;
+            const rgy = context.runtime.vdr;
+            if (!rgy)
+                throw new Error("Legacy credential registry is unavailable in this runtime.");
+            // The host owns workers. This request only queues introductions and observes state.
+            for (const oobi of oobis)
+                context.runtime.oobiery.resolve(oobi);
+            const deadline = Date.now() + 30_000;
+            while (!oobis.every((url) => runtimeOobiConverged(context.runtime, url))) {
+                context.req.signal.throwIfAborted();
+                if (Date.now() >= deadline)
+                    throw new Error("DID introductions did not converge within 30000ms.");
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            result = resolveDidKeri(context.runtime.hby, rgy, canonical);
+        }
+        if (!result) {
+            return jsonResponse(didResolutionError("methodNotSupported", `Unsupported DID method for ${did}.`), meta ? 200 : 400);
+        }
+        return jsonResponse(meta ? result.resolution : result.document, 200, meta ? "application/did-resolution+json" : "application/did+json");
+    }
+    catch (error) {
+        return jsonResponse(didResolutionError("notFound", error instanceof Error ? error.message : String(error)), meta ? 200 : 404);
+    }
+}
+function wantsResolutionResult(req, url) {
+    if (url.searchParams.get("meta") === "true") {
+        return true;
+    }
+    return (req.headers.get("accept") ?? "").toLowerCase().includes("application/did-resolution");
+}
+function decodeDidIdentifierPath(encoded) {
+    if (encoded.startsWith("did:")) {
+        return encoded;
+    }
+    try {
+        const decoded = decodeURIComponent(encoded);
+        return decoded.startsWith("did:") ? decoded : encoded;
+    }
+    catch {
+        return encoded;
+    }
+}
+function jsonResponse(body, status = 200, contentType = "application/did+json") {
+    return new Response(`${JSON.stringify(body, null, 2)}\n`, {
+        status,
+        headers: { "Content-Type": contentType },
+    });
+}

package/esm/hosting/npm/src/src/http/protocol/endpoints/dws-artifacts.js

@@ -0,0 +1,112 @@
+/** Static and dynamic `did:webs` artifact routes. */
+import { didWebsFromArtifactRequest, generateDidWebsArtifacts, generateDidWebsJson, ValidationError, } from "keri-ts/runtime";
+/** Classify configured `did.json` and `keri.cesr` artifact routes. */
+export function classifyDwsArtifactRoute(context) {
+    if (context.method !== "GET") {
+        return null;
+    }
+    if (!context.policy.dwsDynamic && !context.policy.dwsStaticFilesDir) {
+        return null;
+    }
+    const segments = context.pathname.split("/").filter((part) => part.length > 0);
+    const configuredPath = didPathSegments(context.policy.dwsDidPath);
+    if (!pathPrefixMatches(segments, configuredPath)) {
+        return null;
+    }
+    const remaining = segments.slice(configuredPath.length);
+    if (remaining.length !== 2) {
+        return null;
+    }
+    const [aid, artifact] = remaining;
+    if (artifact !== "did.json" && artifact !== "keri.cesr") {
+        return null;
+    }
+    return { kind: "dwsArtifact", aid, artifact };
+}
+/** Serve one configured artifact route from dynamic state or static files. */
+export async function handleDwsArtifactRoute(context, route, files) {
+    if (context.policy.dwsDynamic && context.runtime && dynamicAidAllowed(context, route.aid)) {
+        return dynamicArtifactResponse(context, route);
+    }
+    if (context.policy.dwsStaticFilesDir) {
+        return await staticArtifactResponse(context, route, files);
+    }
+    return new Response("Not Found", {
+        status: 404,
+        headers: { "Content-Type": "text/plain" },
+    });
+}
+function dynamicArtifactResponse(context, route) {
+    try {
+        const did = didWebsFromArtifactRequest({
+            host: context.req.headers.get("host") ?? context.url.host,
+            didPath: didPathSegments(context.policy.dwsDidPath),
+            aid: route.aid,
+        });
+        const rgy = context.runtime?.vdr;
+        if (!rgy)
+            throw new ValidationError("Legacy credential registry is unavailable in this runtime.");
+        const bytes = route.artifact === "did.json"
+            ? generateDidWebsJson(rgy, { did }).didJson
+            : generateDidWebsArtifacts(rgy, { did }).keriCesr;
+        return new Response(bodyBuffer(bytes), {
+            headers: {
+                "Content-Type": route.artifact === "did.json" ? "application/did+json" : "application/cesr",
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return new Response(message, {
+            status: error instanceof ValidationError ? 400 : 500,
+            headers: { "Content-Type": "text/plain" },
+        });
+    }
+}
+async function staticArtifactResponse(context, route, files) {
+    const root = context.policy.dwsStaticFilesDir;
+    try {
+        const path = staticArtifactPath(root, context.policy.dwsDidPath, route.aid, route.artifact);
+        return await files.response(path, route.artifact === "did.json" ? "application/did+json" : "application/cesr", context.req.signal);
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            return new Response(error.message, {
+                status: 400,
+                headers: { "Content-Type": "text/plain" },
+            });
+        }
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return new Response("Not Found", { status: 404, headers: { "Content-Type": "text/plain" } });
+        }
+        throw error;
+    }
+}
+function bodyBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function dynamicAidAllowed(context, aid) {
+    const hosted = context.policy.hostedPrefixes ?? [];
+    return hosted.includes(aid);
+}
+function staticArtifactPath(root, didPath, aid, artifact) {
+    const normalizedRoot = root.replace(/\/+$/u, "");
+    const prefix = didPathSegments(didPath).map(safeSegment).join("/");
+    const parts = [normalizedRoot, prefix, safeSegment(aid), artifact].filter((part) => part.length > 0);
+    return parts.join("/");
+}
+function didPathSegments(path) {
+    return (path ?? "").split("/").filter((part) => part.length > 0);
+}
+function pathPrefixMatches(segments, prefix) {
+    if (segments.length < prefix.length) {
+        return false;
+    }
+    return prefix.every((part, index) => segments[index] === part);
+}
+function safeSegment(segment) {
+    if (segment.includes("/") || segment === ".." || segment.includes("\0")) {
+        throw new ValidationError(`Unsafe path segment ${segment}.`);
+    }
+    return segment;
+}