@keri-ts/hosting 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,21 @@
+/** Return one CESR response body with the expected content type. */
+export function cesrResponse(body, status) {
+    return new Response(body.slice().buffer, {
+        status,
+        headers: { "Content-Type": "application/cesr" },
+    });
+}
+/** Return one plain-text response. */
+export function textResponse(message, status) {
+    return new Response(message, {
+        status,
+        headers: { "Content-Type": "text/plain" },
+    });
+}
+/** Return the ordinary no-content JSON response used by ingress routes. */
+export function jsonNoContentResponse() {
+    return new Response(null, {
+        status: 204,
+        headers: { "Content-Type": "application/json" },
+    });
+}

package/esm/hosting/npm/src/src/http/protocol/runtime-bridge.js

@@ -0,0 +1,16 @@
+import { processCuesOnce } from "keri-ts/runtime";
+/**
+ * Route HTTP cues and finish the existing query-delivery pass.
+ * Poster work is only admitted here; its independent worker owns network delivery.
+ * Request-owned direct replies remain with the HTTP request lifetime.
+ *
+ * @param runtime Borrowed composed runtime; caller owns its worker and store lifetime.
+ * @param serviceHab Optional hosted signer for cue production.
+ * @param cues Exact runtime source Deck; foreign Decks are rejected.
+ */
+export function* drainRuntimeCues(runtime, serviceHab, cues) {
+    if (cues !== runtime.cues)
+        throw new RangeError("HTTP cue drain requires the runtime source deck");
+    yield* processCuesOnce(runtime, { hab: serviceHab });
+    yield* runtime.querying.deliverOnce();
+}

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

@@ -0,0 +1 @@
+export {};

package/esm/hosting/npm/src/src/http/protocol-handler.js

@@ -0,0 +1,68 @@
+import { ArtifactFiles } from "./protocol/artifact-files.js";
+import { buildProtocolRequestContext } from "./protocol/context.js";
+import { classifyDidResolutionRoute, handleDidResolutionRoute } from "./protocol/endpoints/did-resolution.js";
+import { classifyDwsArtifactRoute, handleDwsArtifactRoute } from "./protocol/endpoints/dws-artifacts.js";
+import { classifyGenericCesrIngressRoute, handleGenericCesrIngress, } from "./protocol/endpoints/generic-cesr-ingress.js";
+import { classifyHealthRoute, handleHealthRoute } from "./protocol/endpoints/health.js";
+import { classifyMailboxAdminRoute, handleMailboxAdmin } from "./protocol/endpoints/mailbox-admin.js";
+import { classifyOobiRoute, handleOobiRoute } from "./protocol/endpoints/oobi.js";
+import { classifyWitnessHttpRoute, handleWitnessKeyStateGet, handleWitnessQueryGet, handleWitnessReceiptGet, handleWitnessReceiptPost, } from "./protocol/endpoints/witness-http.js";
+export { buildProtocolRequestContext } from "./protocol/context.js";
+export { classifyCesrIngressRoute } from "./protocol/endpoints/generic-cesr-ingress.js";
+export { parseOobiRouteRequest } from "./protocol/endpoints/oobi.js";
+/** Build the shared protocol handler used by the Deno and Node HTTP hosts. */
+export function createProtocolHandler(runtime, policy = {}) {
+    const files = new ArtifactFiles();
+    const handle = async (req) => {
+        const context = buildProtocolRequestContext(req, runtime, policy);
+        const route = classifyProtocolRoute(context);
+        return await dispatchProtocolRoute(context, route, files);
+    };
+    return Object.assign(handle, { close: () => files.close() });
+}
+/** Classify one request by explicit endpoint precedence. */
+export function classifyProtocolRoute(context) {
+    return classifyHealthRoute(context)
+        ?? classifyDidResolutionRoute(context)
+        ?? classifyDwsArtifactRoute(context)
+        ?? classifyMailboxAdminRoute(context)
+        ?? classifyWitnessHttpRoute(context)
+        ?? classifyOobiRoute(context)
+        ?? classifyGenericCesrIngressRoute(context)
+        ?? { kind: "notFound" };
+}
+/** Dispatch one already-classified route to its concrete response. */
+async function dispatchProtocolRoute(context, route, files) {
+    switch (route.kind) {
+        case "health":
+            return handleHealthRoute();
+        case "didResolution":
+            return await handleDidResolutionRoute(context, route.did);
+        case "dwsArtifact":
+            return await handleDwsArtifactRoute(context, route, files);
+        case "ambiguousHostedPath":
+            return new Response(route.message, {
+                status: 409,
+                headers: { "Content-Type": "text/plain" },
+            });
+        case "mailboxAdmin":
+            return await handleMailboxAdmin(context.runtime, context.req, route.mailboxAid, context.policy.serviceHab);
+        case "witnessReceiptsPost":
+            return await handleWitnessReceiptPost(context.runtime, context.req, route.witnessHab);
+        case "witnessReceiptsGet":
+            return handleWitnessReceiptGet(context, route.witnessHab);
+        case "witnessKeyStateGet":
+            return handleWitnessKeyStateGet(context, route.witnessHab);
+        case "witnessQueryGet":
+            return handleWitnessQueryGet(context, route.witnessHab);
+        case "oobi":
+            return handleOobiRoute(context, route.request);
+        case "genericCesrIngress":
+            return await handleGenericCesrIngress(context, route.hosted);
+        case "notFound":
+            return new Response("Not Found", {
+                status: 404,
+                headers: { "Content-Type": "text/plain" },
+            });
+    }
+}

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

@@ -0,0 +1,118 @@
+/** One configured HTTPS response source; TLS supplies source identity, never issuer authority. */
+import { call, resource, scoped } from "effection";
+import { collectBytes, TransportError, ValidationError } from "keri-ts/runtime";
+import { Buffer } from "node:buffer";
+import { readFileSync } from "node:fs";
+import { request } from "node:https";
+import { isIP } from "node:net";
+import { isAbsolute } from "node:path";
+import { checkServerIdentity } from "node:tls";
+/** Validated fixed source data; URL identity is retained exactly, not derived from a response. */
+export class SourceTrust {
+    constructor({ url, caFile, certName }) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "caFile", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "certName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "hostname", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ca", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (typeof url !== "string" || !url.trim())
+            throw new ValidationError("Source URL is required.");
+        const target = new URL(url.trim());
+        if (target.protocol !== "https:" || target.username || target.password || target.search || target.hash) {
+            throw new ValidationError("Source must be HTTPS without credentials, query or fragment.");
+        }
+        const host = target.hostname.replace(/^\[|\]$/g, "");
+        if (certName !== undefined && (!isIP(host) || typeof certName !== "string" || !certName
+            || isIP(certName) || !certName.split(".").every(label => /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label)))) {
+            throw new ValidationError("Separate certificate DNS name requires an IP source URL.");
+        }
+        if (caFile !== undefined && (typeof caFile !== "string" || !isAbsolute(caFile))) {
+            throw new ValidationError("Source CA must be an absolute file path.");
+        }
+        this.url = url.trim();
+        this.caFile = caFile;
+        this.certName = certName;
+        this.hostname = certName ?? host;
+        this.ca = caFile ? readFileSync(caFile) : undefined;
+    }
+}
+/**
+ * Own one finite POST, absolute deadline, body reader and joined socket close.
+ * Node's TLS verifier checks CA plus the configured URL/name; request never follows redirects.
+ */
+export function sourceRequest(source, body, timeoutMs) {
+    return scoped(function* () {
+        return yield* resource(function* (provide) {
+            const host = new URL(source.url).hostname.replace(/^\[|\]$/g, "");
+            let closed;
+            const joined = new Promise(resolve => closed = resolve);
+            let succeed, fail;
+            const pending = new Promise((resolve, reject) => {
+                succeed = resolve;
+                fail = cause => reject(new TransportError("HTTPS registrar source failed", { cause }));
+            });
+            const req = request(source.url, {
+                method: "POST",
+                agent: false,
+                ca: source.ca,
+                rejectUnauthorized: true,
+                servername: isIP(host) ? source.certName : host,
+                checkServerIdentity: (_hostname, certificate) => checkServerIdentity(source.hostname, certificate),
+                headers: { "Content-Type": "application/cesr" },
+            }, response => {
+                const headers = new Headers();
+                for (const [key, value] of Object.entries(response.headers)) {
+                    if (Array.isArray(value))
+                        value.forEach(item => headers.append(key, item));
+                    else if (value !== undefined)
+                        headers.set(key, value);
+                }
+                void collectBytes(response).then(bytes => succeed({
+                    status: response.statusCode ?? 0,
+                    ok: (response.statusCode ?? 0) >= 200 && (response.statusCode ?? 0) < 300,
+                    headers,
+                    body: bytes,
+                }), fail);
+            });
+            req.on("error", fail);
+            req.once("close", closed);
+            req.end(Buffer.from(body));
+            // Cancellation may finish the operation before the native promise rejects.
+            void pending.catch(() => { });
+            const timer = setTimeout(() => req.destroy(new Error("Registrar source deadline expired")), timeoutMs);
+            try {
+                yield* provide(yield* call(() => pending));
+            }
+            finally {
+                clearTimeout(timer);
+                req.destroy();
+                yield* call(() => joined);
+            }
+        });
+    });
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@keri-ts/hosting",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "HTTP host lifecycle, application middleware and protocol route composition",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kentbull/keri-ts.git",
+    "directory": "packages/hosting"
+  },
+  "license": "Apache-2.0",
+  "main": "./esm/hosting/npm/src/mod.js",
+  "module": "./esm/hosting/npm/src/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/mod.d.ts",
+      "import": "./esm/hosting/npm/src/mod.js"
+    }
+  },
+  "scripts": {
+    "test": "node --version"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "esm",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.3"
+  },
+  "dependencies": {
+    "cesr-ts": "2.0.0",
+    "effection": "^3.6.0",
+    "hono": "^4.7.11",
+    "keri-ts": "2.0.0",
+    "@deno/shim-deno": "~0.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/types/_dnt.shims.d.ts

@@ -0,0 +1,6 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+export declare const dntGlobalThis: Omit<typeof globalThis, "Deno"> & {
+    Deno: typeof Deno;
+};
+//# sourceMappingURL=_dnt.shims.d.ts.map

package/types/_dnt.shims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAKvC,eAAO,MAAM,aAAa;;CAA2C,CAAC"}

package/types/mod.d.ts

@@ -0,0 +1,9 @@
+/** HTTP hosting package entrypoint. */
+export { type RuntimeHttpHostOptions, startServer } from "./src/host/http-server.js";
+export { type HostKernelHttpSpec, type HostKernelSpec, type HostTaskFactory, type HttpListenAddress, runHostKernel, } from "./src/host/kernel.js";
+export { createTufaApp, type CreateTufaAppOptions } from "./src/http/app.js";
+export type { TufaCorsPolicy, TufaHttpAppOptions, TufaHttpAppPolicy } from "./src/http/policy.js";
+export { createProtocolHandler, type ProtocolHandler } from "./src/http/protocol-handler.js";
+export { handleWitnessReceiptPost } from "./src/http/protocol/endpoints/witness-http.js";
+export { type SourceConfig, sourceRequest, SourceTrust } from "./src/http/source.js";
+//# sourceMappingURL=mod.d.ts.map

package/types/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,OAAO,EAAE,KAAK,sBAAsB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAClG,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAC7F,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AACzF,OAAO,EAAE,KAAK,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/types/src/host/http-server.d.ts

@@ -0,0 +1,46 @@
+import { type Operation } from "effection";
+import { type AgentRuntime, type Logger, type ProtocolHostPolicy } from "keri-ts/runtime";
+import type { ProtocolHandler } from "../http/protocol/types.js";
+interface RunningServer {
+    readonly finished: Promise<void>;
+}
+interface ServerHost {
+    readonly server: RunningServer;
+    close(): void | Promise<void>;
+}
+interface ServerOptions {
+    tls?: {
+        key: string;
+        cert: string;
+    };
+    port: number;
+    hostname: string;
+    signal: AbortSignal;
+    onListen: (address: {
+        port: number;
+    }) => void;
+    onError: (error: unknown) => Response;
+}
+/** HTTP host options. */
+export interface RuntimeHttpHostOptions extends ProtocolHostPolicy {
+    /** Explicit PEM identity for HTTPS; selected TLS never falls back to a plaintext listener. */
+    tls?: {
+        key: string;
+        cert: string;
+    };
+    /** A concrete service may own routing across independent runtimes; it also owns handler cleanup. */
+    protocolHandler?: ProtocolHandler;
+    hostname?: string;
+    onListen?: (address: {
+        port: number;
+        hostname: string;
+    }) => void;
+}
+/** Open the native Deno HTTP host and join request cleanup after its listener closes. */
+export declare function openDenoServerHost(options: ServerOptions, handler: (req: Request) => Promise<Response>): ServerHost;
+/** Open the Node fallback host; completion joins every admitted request after the listener closes. */
+export declare function openNodeServerHost(options: ServerOptions, handler: (req: Request) => Promise<Response>): ServerHost;
+/** Start the Tufa HTTP host for one shared `AgentRuntime`. */
+export declare function startServer(port?: number, logger?: Logger, runtime?: AgentRuntime, options?: RuntimeHttpHostOptions, beforeDrain?: () => Operation<void>): Operation<void>;
+export {};
+//# sourceMappingURL=http-server.d.ts.map

package/types/src/host/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../../src/src/host/http-server.ts"],"names":[],"mappings":"AASA,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,KAAK,YAAY,EAAiB,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAMzG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,UAAU,aAAa;IACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,UAAU,UAAU;IAClB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAMD,UAAU,aAAa;IACrB,GAAG,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9C,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,QAAQ,CAAC;CACvC;AAED,yBAAyB;AACzB,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,8FAA8F;IAC9F,GAAG,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,oGAAoG;IACpG,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAClE;AA4CD,yFAAyF;AACzF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAC3C,UAAU,CAoBZ;AAyHD,sGAAsG;AACtG,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAC3C,UAAU,CA+CZ;AAyFD,8DAA8D;AAC9D,wBAAiB,WAAW,CAC1B,IAAI,GAAE,MAAa,EACnB,MAAM,GAAE,MAAsB,EAC9B,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,GAAE,sBAA2B,EACpC,WAAW,CAAC,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,GAClC,SAAS,CAAC,IAAI,CAAC,CAgBjB"}

package/types/src/host/kernel.d.ts

@@ -0,0 +1,37 @@
+import { type Operation } from "effection";
+import { type AgentRuntime, type Hab, type Habery, type KramConfig, type ProtocolHostPolicy } from "keri-ts/runtime";
+/** Resolved listen callback address for one HTTP host. */
+export interface HttpListenAddress {
+    port: number;
+    hostname: string;
+}
+/** Actual companion listener work, supervised alongside the runtime and HTTP server. */
+export type HostTaskFactory = (runtime: AgentRuntime) => Operation<void>;
+/** HTTP listener spec owned by the shared host kernel. */
+export interface HostKernelHttpSpec {
+    port: number;
+    hostname?: string;
+    onListen?: (address: HttpListenAddress) => void;
+}
+/** Concrete host-kernel configuration for one long-lived role host. */
+export interface HostKernelSpec {
+    /** Whether this host constructs provider mailbox storage. */
+    enableMailboxStore: boolean;
+    /** Explicit receiver policy selected by this host's composition root; omission leaves KRAM disabled. */
+    kram?: KramConfig;
+    serviceHab: Hab;
+    hostedPrefixes?: readonly string[];
+    http: HostKernelHttpSpec;
+    protocolPolicy: Omit<ProtocolHostPolicy, "serviceHab" | "hostedPrefixes">;
+    companionHosts?: readonly HostTaskFactory[];
+}
+/**
+ * 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 declare function runHostKernel(hby: Habery, spec: HostKernelSpec): Operation<void>;
+//# sourceMappingURL=kernel.d.ts.map

package/types/src/host/kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../../src/src/host/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAoB,MAAM,WAAW,CAAC;AAG7D,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,GAAG,EACR,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAGzB,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wFAAwF;AACxF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;AAEzE,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACjD;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,kBAAkB,EAAE,OAAO,CAAC;IAC5B,wGAAwG;IACxG,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,GAAG,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,cAAc,EAAE,IAAI,CAAC,kBAAkB,EAAE,YAAY,GAAG,gBAAgB,CAAC,CAAC;IAC1E,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAiB,aAAa,CAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,cAAc,GACnB,SAAS,CAAC,IAAI,CAAC,CA6EjB"}

package/types/src/http/app.d.ts

@@ -0,0 +1,22 @@
+import type { AgentRuntime, ProtocolHostPolicy } from "keri-ts/runtime";
+import { Hono } from "hono";
+import { type TufaHttpAppOptions } from "./policy.js";
+import type { ProtocolHandler } from "./protocol/types.js";
+/** Construction options for the Stage 4 Tufa HTTP app edge. */
+export interface CreateTufaAppOptions {
+    readonly runtime?: AgentRuntime;
+    readonly protocolPolicy?: ProtocolHostPolicy;
+    readonly app?: TufaHttpAppOptions;
+    readonly protocolHandler?: ProtocolHandler;
+}
+/**
+ * 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 declare function createTufaApp(options?: CreateTufaAppOptions): Hono & {
+    close(): Promise<void>;
+};
+//# sourceMappingURL=app.d.ts.map

package/types/src/http/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/src/http/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAmD,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,GAAE,oBAAyB,GACjC,IAAI,GAAG;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAuBnC"}

package/types/src/http/error-mapping.d.ts

@@ -0,0 +1,7 @@
+import type { Hono } from "hono";
+import type { TufaHttpAppPolicy } from "./policy.js";
+/** Map one unhandled edge error into the Stage 4 HTTP response contract. */
+export declare function mapTufaHttpError(error: unknown, policy: TufaHttpAppPolicy): Response;
+/** Install the centralized Stage 4 app-level error mapping. */
+export declare function installTufaHttpErrorHandling(app: Hono, policy: TufaHttpAppPolicy): void;
+//# sourceMappingURL=error-mapping.d.ts.map

package/types/src/http/error-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapping.d.ts","sourceRoot":"","sources":["../../../src/src/http/error-mapping.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,iBAAiB,GACxB,QAAQ,CAOV;AAED,+DAA+D;AAC/D,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,iBAAiB,GACxB,IAAI,CAMN"}

package/types/src/http/policy.d.ts

@@ -0,0 +1,27 @@
+import { type Logger } from "keri-ts/runtime";
+import type { Hono } from "hono";
+/** Fixed CORS policy owned by the Stage 4 Tufa HTTP edge. */
+export interface TufaCorsPolicy {
+    readonly allowOrigin: string;
+    readonly allowMethods: readonly string[];
+    readonly allowHeaders: readonly string[];
+    readonly exposeHeaders: readonly string[];
+}
+/** App-level Stage 4 policy for the Hono middleware envelope. */
+export interface TufaHttpAppPolicy {
+    readonly logger: Logger;
+    readonly cors: TufaCorsPolicy;
+}
+/** Call-site options used to resolve the concrete app policy. */
+export interface TufaHttpAppOptions {
+    readonly logger?: Logger;
+    readonly cors?: Partial<TufaCorsPolicy>;
+}
+export declare const DEFAULT_TUFA_CORS_POLICY: TufaCorsPolicy;
+/** Resolve one app policy with Stage 4 defaults. */
+export declare function resolveTufaHttpAppPolicy(options?: TufaHttpAppOptions): TufaHttpAppPolicy;
+/** Install the Stage 4 middleware envelope onto one Hono app. */
+export declare function installTufaHttpPolicy(app: Hono, policy: TufaHttpAppPolicy): void;
+/** Apply the resolved Stage 4 CORS policy to one response header set. */
+export declare function applyTufaCorsHeaders(headers: Headers, policy: TufaCorsPolicy): void;
+//# sourceMappingURL=policy.d.ts.map

package/types/src/http/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/src/http/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,IAAI,EAAqB,MAAM,MAAM,CAAC;AAGpD,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACzC;AAED,eAAO,MAAM,wBAAwB,EAAE,cAcrC,CAAC;AAEH,oDAAoD;AACpD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAcnB;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,iBAAiB,GACxB,IAAI,CAEN;AAiCD,yEAAyE;AACzE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GACrB,IAAI,CAcN"}

package/types/src/http/protocol/artifact-files.d.ts

@@ -0,0 +1,11 @@
+/** Own one host's open file responses, including bodies that have not been consumed. */
+export declare class ArtifactFiles {
+    private readonly owners;
+    private stopping;
+    private closing?;
+    /** Open the regular file and capture its extent without reading data. */
+    response(path: string, contentType: string, signal: AbortSignal): Promise<Response>;
+    /** Close every file, including pending acquisitions, before the HTTP host finishes shutdown. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=artifact-files.d.ts.map

package/types/src/http/protocol/artifact-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-files.d.ts","sourceRoot":"","sources":["../../../../src/src/http/protocol/artifact-files.ts"],"names":[],"mappings":"AAMA,wFAAwF;AACxF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;IACzE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAC,CAAgB;IAEhC,yEAAyE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAyGzF,gGAAgG;IAChG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAUvB"}

package/types/src/http/protocol/context.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { type AgentRuntime, type ProtocolHostPolicy } from "keri-ts/runtime";
+import type { ProtocolRequestContext } from "./types.js";
+/** Snapshot one request into the path-first routing context. */
+export declare function buildProtocolRequestContext(req: Request, runtime?: AgentRuntime, policy?: ProtocolHostPolicy): ProtocolRequestContext;
+/** Normalize incoming request paths into the comparison form used by routing. */
+export declare function normalizeProtocolPath(pathname: string): string;
+//# sourceMappingURL=context.d.ts.map

package/types/src/http/protocol/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/src/http/protocol/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAA6B,MAAM,iBAAiB,CAAC;AAExG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,gEAAgE;AAChE,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,YAAY,EACtB,MAAM,GAAE,kBAAuB,GAC9B,sBAAsB,CA4CxB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO9D"}

package/types/src/http/protocol/endpoints/did-resolution.d.ts

@@ -0,0 +1,12 @@
+import type { ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Classify `/1.0/identifiers/{did}` requests. */
+export declare function classifyDidResolutionRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/**
+ * 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 declare function handleDidResolutionRoute(context: ProtocolRequestContext, did: string): Promise<Response>;
+//# sourceMappingURL=did-resolution.d.ts.map

package/types/src/http/protocol/endpoints/did-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-resolution.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/did-resolution.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIzE,kDAAkD;AAClD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAStB;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,sBAAsB,EAC/B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,QAAQ,CAAC,CAuDnB"}

package/types/src/http/protocol/endpoints/dws-artifacts.d.ts

@@ -0,0 +1,9 @@
+import type { ArtifactFiles } from "../artifact-files.js";
+import type { ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Classify configured `did.json` and `keri.cesr` artifact routes. */
+export declare function classifyDwsArtifactRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/** Serve one configured artifact route from dynamic state or static files. */
+export declare function handleDwsArtifactRoute(context: ProtocolRequestContext, route: Extract<ProtocolRoute, {
+    kind: "dwsArtifact";
+}>, files: ArtifactFiles): Promise<Response>;
+//# sourceMappingURL=dws-artifacts.d.ts.map

package/types/src/http/protocol/endpoints/dws-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dws-artifacts.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/dws-artifacts.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzE,sEAAsE;AACtE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAqBtB;AAED,8EAA8E;AAC9E,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,EACtD,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,QAAQ,CAAC,CAWnB"}

package/types/src/http/protocol/endpoints/generic-cesr-ingress.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generic CESR POST/PUT ingress for the Tufa HTTP edge.
+ *
+ * Explicit routes are classified before this module runs. This handler owns
+ * the remaining raw CESR traffic and decides whether it belongs to local
+ * witness ingestion, mailbox SSE query streaming, or normal runtime ingress.
+ */
+import { type SerderKERI } from "cesr-ts";
+import { type HostedRouteResolution } from "keri-ts/runtime";
+import type { CesrIngressRoute, ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Classify generic POST/PUT CESR ingress after all explicit HTTP routes. */
+export declare function classifyGenericCesrIngressRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/**
+ * Decide how one inspected CESR request should be ingested.
+ *
+ * This is the explicit replacement for the old inline witness-root boolean.
+ */
+export declare function classifyCesrIngressRoute(context: ProtocolRequestContext, hosted: HostedRouteResolution, serder: Pick<SerderKERI, "ilk" | "route" | "ked">): CesrIngressRoute;
+/** Run one request in a single owned Effection task and join it on disconnect. */
+export declare function handleGenericCesrIngress(context: ProtocolRequestContext, hosted: HostedRouteResolution): Promise<Response>;
+//# sourceMappingURL=generic-cesr-ingress.d.ts.map

package/types/src/http/protocol/endpoints/generic-cesr-ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-cesr-ingress.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/generic-cesr-ingress.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpE,OAAO,EAEL,KAAK,qBAAqB,EAK3B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAS3F,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAgBtB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC,GAChD,gBAAgB,CA8BlB;AAsBD,kFAAkF;AAClF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAwEnB"}

package/types/src/http/protocol/endpoints/health.d.ts

@@ -0,0 +1,6 @@
+import type { ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Classify `/health` before any runtime-aware routing. */
+export declare function classifyHealthRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/** Return the fixed health response. */
+export declare function handleHealthRoute(): Response;
+//# sourceMappingURL=health.d.ts.map

package/types/src/http/protocol/endpoints/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/health.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzE,2DAA2D;AAC3D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAEtB;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,IAAI,QAAQ,CAE5C"}

package/types/src/http/protocol/endpoints/mailbox-admin.d.ts

@@ -0,0 +1,26 @@
+import { type Operation } from "effection";
+import { type AgentRuntime, type CesrStreamInspection, type Hab } from "keri-ts/runtime";
+import type { ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Classify mailbox-admin requests before witness or generic ingress routing. */
+export declare function classifyMailboxAdminRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/**
+ * Handle mailbox add/remove authorization requests for one hosted mailbox AID.
+ *
+ * Contract:
+ * - request body is either one `application/cesr` stream or one
+ *   `multipart/form-data` request carrying `kel`, optional `delkel`, and `rpy`
+ * - both request shapes normalize to one mailbox authorization CESR stream
+ * - that stream ends in the mailbox authorization `rpy`
+ */
+export declare function handleMailboxAdmin(runtime: AgentRuntime, req: Request, mailboxAid: string, serviceHab?: Hab): Promise<Response>;
+/** Validate the terminal mailbox authorization reply before local acceptance checks. */
+export declare function validateMailboxAuthorizationReply(inspection: CesrStreamInspection, mailboxAid: string): Response | {
+    cid: string;
+    role: string;
+    expected: boolean;
+};
+/** Confirm that mailbox authorization state was accepted locally. */
+export declare function confirmMailboxAuthorization(runtime: AgentRuntime, cid: string, mailboxAid: string, expected: boolean): Response | null;
+/** Settle mailbox-admin CESR ingress without responder-side cue forwarding. */
+export declare function settleMailboxAdminIngress(runtime: AgentRuntime, bytes: Uint8Array, mailboxAid: string, signal?: AbortSignal): Operation<void>;
+//# sourceMappingURL=mailbox-admin.d.ts.map

package/types/src/http/protocol/endpoints/mailbox-admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-admin.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/mailbox-admin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAO,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EAEzB,KAAK,GAAG,EAIT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzE,iFAAiF;AACjF,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAiBtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,GAAG,GACf,OAAO,CAAC,QAAQ,CAAC,CA+DnB;AAED,wFAAwF;AACxF,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,oBAAoB,EAChC,UAAU,EAAE,MAAM,GACjB,QAAQ,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAqC7D;AAED,qEAAqE;AACrE,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,GAChB,QAAQ,GAAG,IAAI,CAOjB;AAED,+EAA+E;AAC/E,wBAAiB,yBAAyB,CACxC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,SAAS,CAAC,IAAI,CAAC,CAMjB"}