@keri-ts/hosting 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,31 @@
+import { type AgentRuntime, type Hab } from "keri-ts/runtime";
+import type { OobiRouteRequest, ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Parse one OOBI-style request path into its route semantics. */
+export declare function parseOobiRouteRequest(pathname: string): OobiRouteRequest | null;
+/** Classify OOBI requests after mailbox-admin and witness-specific routes. */
+export declare function classifyOobiRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/** Serve one OOBI request from local accepted habitat state. */
+export declare function handleOobiRoute(context: ProtocolRequestContext, request: OobiRouteRequest): Response;
+/**
+ * Pick the default local AID whose Hab should answer a blind OOBI request when
+ * the request omits an AID.
+ */
+export declare function defaultOobiAid(runtime: AgentRuntime, serviceHab?: Hab, hostedPrefixes?: readonly string[]): string | undefined;
+/**
+ * Choose which local Hab should answer an OOBI request and return that Hab's
+ * AID.
+ *
+ * Preference order:
+ * - the requested AID itself when locally controlled
+ * - the explicit endpoint AID when it is locally controlled
+ * - the hosted endpoint matched from the request path
+ */
+export declare function selectResponderHab(runtime: AgentRuntime, hosted: {
+    kind: "none" | "one" | "ambiguous";
+    endpoint: {
+        eid: string;
+        url: string;
+        basePath: string;
+    } | null;
+}, aid: string, eid?: string, hostedPrefixes?: readonly string[]): string | undefined;
+//# sourceMappingURL=oobi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oobi.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/oobi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAuC,KAAK,GAAG,EAAuB,MAAM,iBAAiB,CAAC;AAExH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3F,kEAAkE;AAClE,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GACf,gBAAgB,GAAG,IAAI,CAoCzB;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAWtB;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,gBAAgB,GACxB,QAAQ,CA0DV;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,GAAG,EAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GACjC,MAAM,GAAG,SAAS,CAcpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;IACN,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,WAAW,CAAC;IACnC,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjE,EACD,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GACjC,MAAM,GAAG,SAAS,CAqDpB"}

package/types/src/http/protocol/endpoints/witness-http.d.ts

@@ -0,0 +1,13 @@
+import { type AgentRuntime, type Hab, type WitnessReceiptPostOptions } from "keri-ts/runtime";
+import type { ProtocolRequestContext, ProtocolRoute } from "../types.js";
+/** Classify witness-only `/receipts` and `/query` routes ahead of generic ingress. */
+export declare function classifyWitnessHttpRoute(context: ProtocolRequestContext): ProtocolRoute | null;
+/** Handle one witness `/receipts` POST request; `options.local` follows the core receipt policy. */
+export declare function handleWitnessReceiptPost(runtime: AgentRuntime, req: Request, witnessHab: Hab, options?: WitnessReceiptPostOptions): Promise<Response>;
+/** Handle one witness `/receipts` GET request. */
+export declare function handleWitnessReceiptGet(context: ProtocolRequestContext, witnessHab: Hab): Response;
+/** Handle one witness `/query` GET request. */
+export declare function handleWitnessQueryGet(context: ProtocolRequestContext, witnessHab: Hab): Response;
+/** Serve the signed witness state-notice contract with explicit destination selection. */
+export declare function handleWitnessKeyStateGet(context: ProtocolRequestContext, witnessHab: Hab): Response;
+//# sourceMappingURL=witness-http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"witness-http.d.ts","sourceRoot":"","sources":["../../../../../src/src/http/protocol/endpoints/witness-http.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,GAAG,EAMR,KAAK,yBAAyB,EAC/B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzE,sFAAsF;AACtF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,GAAG,IAAI,CAkCtB;AAED,oGAAoG;AACpG,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,GAAG,EACf,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,QAAQ,CAAC,CAmBnB;AAED,kDAAkD;AAClD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,EAC/B,UAAU,EAAE,GAAG,GACd,QAAQ,CAYV;AAED,+CAA+C;AAC/C,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,UAAU,EAAE,GAAG,GACd,QAAQ,CAgBV;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,GAAG,GAAG,QAAQ,CAQnG"}

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

@@ -0,0 +1,7 @@
+/** Return one CESR response body with the expected content type. */
+export declare function cesrResponse(body: Uint8Array, status: number): Response;
+/** Return one plain-text response. */
+export declare function textResponse(message: string, status: number): Response;
+/** Return the ordinary no-content JSON response used by ingress routes. */
+export declare function jsonNoContentResponse(): Response;
+//# sourceMappingURL=responses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../../src/src/http/protocol/responses.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAKvE;AAED,sCAAsC;AACtC,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAKtE;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,IAAI,QAAQ,CAKhD"}

package/types/src/http/protocol/runtime-bridge.d.ts

@@ -0,0 +1,13 @@
+import { type Operation } from "effection";
+import { type AgentCue, type AgentRuntime, type Deck, type Hab } 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 declare function drainRuntimeCues(runtime: AgentRuntime, serviceHab: Hab | undefined, cues: Deck<AgentCue>): Operation<void>;
+//# sourceMappingURL=runtime-bridge.d.ts.map

package/types/src/http/protocol/runtime-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-bridge.d.ts","sourceRoot":"","sources":["../../../../src/src/http/protocol/runtime-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,IAAI,EAAE,KAAK,GAAG,EAAmB,MAAM,iBAAiB,CAAC;AAEzG;;;;;;;;GAQG;AACH,wBAAiB,gBAAgB,CAC/B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,GAAG,GAAG,SAAS,EAC3B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GACnB,SAAS,CAAC,IAAI,CAAC,CAIjB"}

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

@@ -0,0 +1,78 @@
+import type { AgentRuntime, Hab, HostedRouteResolution, ProtocolHostPolicy } from "keri-ts/runtime";
+/** Shared request handler contract consumed by both Deno and Node hosts. */
+export type ProtocolHandler = ((req: Request) => Promise<Response>) & {
+    /** Owned handlers close file responses before host drain; injected handlers may own no files. */
+    close?: () => Promise<void>;
+};
+/** One parsed OOBI route request. */
+export interface OobiRouteRequest {
+    kind: "wellKnown" | "oobi";
+    aid: string | null;
+    said?: string;
+    role?: string;
+    eid?: string;
+}
+/** One request snapshot used by path-first route classification. */
+export interface ProtocolRequestContext {
+    readonly req: Request;
+    readonly url: URL;
+    readonly pathname: string;
+    readonly method: string;
+    readonly runtime?: AgentRuntime;
+    readonly policy: ProtocolHostPolicy;
+    readonly hosted: HostedRouteResolution | null;
+    readonly mailboxAdmin: HostedRouteResolution | null;
+    readonly genericIngress: HostedRouteResolution | null;
+    readonly oobi: OobiRouteRequest | null;
+}
+/** Path-level route decision before any request body is read. */
+export type ProtocolRoute = {
+    kind: "health";
+} | {
+    kind: "didResolution";
+    did: string;
+} | {
+    kind: "dwsArtifact";
+    aid: string;
+    artifact: "did.json" | "keri.cesr";
+} | {
+    kind: "mailboxAdmin";
+    mailboxAid: string;
+} | {
+    kind: "witnessReceiptsPost";
+    witnessHab: Hab;
+} | {
+    kind: "witnessReceiptsGet";
+    witnessHab: Hab;
+} | {
+    kind: "witnessQueryGet";
+    witnessHab: Hab;
+} | {
+    kind: "witnessKeyStateGet";
+    witnessHab: Hab;
+} | {
+    kind: "oobi";
+    request: OobiRouteRequest;
+} | {
+    kind: "genericCesrIngress";
+    hosted: HostedRouteResolution;
+} | {
+    kind: "ambiguousHostedPath";
+    message: string;
+} | {
+    kind: "notFound";
+};
+/** Body-aware ingress decision for one already-inspected CESR request. */
+export type CesrIngressRoute = {
+    kind: "witnessLocalIngress";
+    witnessHab: Hab;
+} | {
+    kind: "runtimeIngress";
+    mailboxAid: string | null;
+} | {
+    kind: "mailboxQueryStream";
+    mailboxAid: string | null;
+    pre: string | null;
+    topics: unknown;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/src/http/protocol/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEpG,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG;IACpE,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B,CAAC;AAEF,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACxC;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzB,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACrD;IACA,IAAI,EAAE,oBAAoB,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC"}

package/types/src/http/protocol-handler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared protocol-route composition for HTTP hosts.
+ *
+ * This module intentionally stays small: it builds request context, applies
+ * explicit route precedence, and dispatches to endpoint modules. Transport
+ * setup lives under `hosting/src/host`, while endpoint-specific HTTP semantics
+ * live under `hosting/src/http/protocol`.
+ */
+import { type AgentRuntime, type ProtocolHostPolicy } from "keri-ts/runtime";
+import type { ProtocolHandler, ProtocolRequestContext, ProtocolRoute } from "./protocol/types.js";
+export { buildProtocolRequestContext } from "./protocol/context.js";
+export { classifyCesrIngressRoute } from "./protocol/endpoints/generic-cesr-ingress.js";
+export { parseOobiRouteRequest } from "./protocol/endpoints/oobi.js";
+export type { CesrIngressRoute, OobiRouteRequest, ProtocolHandler, ProtocolRequestContext, ProtocolRoute, } from "./protocol/types.js";
+/** Build the shared protocol handler used by the Deno and Node HTTP hosts. */
+export declare function createProtocolHandler(runtime?: AgentRuntime, policy?: ProtocolHostPolicy): ProtocolHandler;
+/** Classify one request by explicit endpoint precedence. */
+export declare function classifyProtocolRoute(context: ProtocolRequestContext): ProtocolRoute;
+//# sourceMappingURL=protocol-handler.d.ts.map

package/types/src/http/protocol-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-handler.d.ts","sourceRoot":"","sources":["../../../src/src/http/protocol-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAoB7E,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAElG,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,8EAA8E;AAC9E,wBAAgB,qBAAqB,CACnC,OAAO,CAAC,EAAE,YAAY,EACtB,MAAM,GAAE,kBAAuB,GAC9B,eAAe,CAQjB;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,CASf"}

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

@@ -0,0 +1,25 @@
+/** One configured HTTPS response source; TLS supplies source identity, never issuer authority. */
+import { type Operation } from "effection";
+import { type HttpResponse } from "keri-ts/runtime";
+import { Buffer } from "node:buffer";
+/** An optional CA bundle augments operator trust; an IP URL may explicitly name a DNS certificate identity. */
+export interface SourceConfig {
+    url: string;
+    caFile?: string;
+    certName?: string;
+}
+/** Validated fixed source data; URL identity is retained exactly, not derived from a response. */
+export declare class SourceTrust {
+    readonly url: string;
+    readonly caFile?: string;
+    readonly certName?: string;
+    readonly hostname: string;
+    readonly ca?: Buffer;
+    constructor({ url, caFile, certName }: SourceConfig);
+}
+/**
+ * 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 declare function sourceRequest(source: SourceTrust, body: Uint8Array, timeoutMs: number): Operation<HttpResponse>;
+//# sourceMappingURL=source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/src/http/source.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,OAAO,EAAQ,KAAK,SAAS,EAAoB,MAAM,WAAW,CAAC;AACnE,OAAO,EAAgB,KAAK,YAAY,EAAmC,MAAM,iBAAiB,CAAC;AACnG,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC,+GAA+G;AAC/G,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,kGAAkG;AAClG,qBAAa,WAAW;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;gBACT,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,YAAY;CAwBpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,CAgD/G"}