@decohere/http 0.0.1-dev.116

package/es6/src/testing/sse-reader.js

@@ -0,0 +1,91 @@
+/** Incremental parser for the `text/event-stream` format. */ class SseParser {
+    buffer = "";
+    data = [];
+    current = {
+        data: ""
+    };
+    hasFields = false;
+    events = [];
+    comments = [];
+    push(chunk) {
+        this.buffer += chunk;
+        let newline;
+        while((newline = this.buffer.search(/\r\n|\r|\n/)) !== -1){
+            const line = this.buffer.slice(0, newline);
+            const eol = this.buffer.slice(newline).startsWith("\r\n") ? 2 : 1;
+            this.buffer = this.buffer.slice(newline + eol);
+            this.line(line);
+        }
+    }
+    line(line) {
+        if (line === "") {
+            if (this.hasFields) {
+                this.events.push({
+                    ...this.current,
+                    data: this.data.join("\n")
+                });
+            }
+            this.data = [];
+            this.current = {
+                data: ""
+            };
+            this.hasFields = false;
+            return;
+        }
+        if (line.startsWith(":")) {
+            this.comments.push(line.slice(1).trim());
+            return;
+        }
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" ")) value = value.slice(1);
+        this.hasFields = true;
+        if (field === "data") this.data.push(value);
+        else if (field === "event") this.current.event = value;
+        else if (field === "id") this.current.id = value;
+        else if (field === "retry") this.current.retry = Number(value);
+    }
+}
+/**
+ * GET `url` as an `EventSource` would and collect events until `count` have arrived or the
+ * server ends the stream. A non-200 answer (401, 403, ...) returns at once with no events.
+ */ export async function readEventStream(url, options = {}) {
+    const count = options.count ?? 1;
+    const abort = new AbortController();
+    const timer = setTimeout(()=>abort.abort(new Error(`No ${count} events from ${url} in time`)), options.timeoutMs ?? 5000);
+    try {
+        const response = await fetch(url, {
+            headers: {
+                accept: "text/event-stream",
+                ...options.headers
+            },
+            signal: abort.signal
+        });
+        const parser = new SseParser();
+        let ended = false;
+        if (response.status === 200 && response.body != null) {
+            const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+            while(parser.events.length < count){
+                const { done, value } = await reader.read();
+                if (done) {
+                    ended = true;
+                    break;
+                }
+                parser.push(value);
+            }
+            await reader.cancel();
+        } else {
+            await response.body?.cancel();
+        }
+        return {
+            status: response.status,
+            headers: response.headers,
+            events: parser.events.slice(0, count),
+            comments: parser.comments,
+            ended
+        };
+    } finally{
+        clearTimeout(timer);
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@decohere/http",
+  "version": "0.0.1-dev.116",
+  "description": "Web API and microservice platform built on Fastify with decorator-based routing",
+  "keywords": [
+    "typescript",
+    "http",
+    "fastify",
+    "rest",
+    "api",
+    "microservice",
+    "decorators",
+    "decohere"
+  ],
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/src/index.d.ts",
+      "import": "./es6/src/index.js",
+      "require": "./commonjs/src/index.js"
+    },
+    "./providers": {
+      "types": "./types/src/providers/index.d.ts",
+      "import": "./es6/src/providers/index.js",
+      "require": "./commonjs/src/providers/index.js"
+    },
+    "./auth": {
+      "types": "./types/src/auth/auth.extensions.d.ts",
+      "import": "./es6/src/auth/auth.extensions.js",
+      "require": "./commonjs/src/auth/auth.extensions.js"
+    },
+    "./testing": {
+      "types": "./types/src/testing/index.d.ts",
+      "import": "./es6/src/testing/index.js",
+      "require": "./commonjs/src/testing/index.js"
+    },
+    "./http": {
+      "types": "./types/src/http/index.d.ts",
+      "import": "./es6/src/http/index.js",
+      "require": "./commonjs/src/http/index.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@casl/ability": "^6.8.1",
+    "@decohere/core": "0.0.1-dev.116",
+    "@decohere/crucible": "0.0.1-dev.116",
+    "@decohere/scribe": "0.0.1-dev.116",
+    "@fastify/compress": "^9.2.1",
+    "@fastify/cors": "^11.3.0",
+    "@fastify/helmet": "^13.1.0",
+    "@fastify/rate-limit": "^11.2.0",
+    "@fastify/static": "^10.1.6",
+    "ajv": "^8.18.0",
+    "fastify": "^5.8.5",
+    "jose": "^6.2.3",
+    "picomatch": "^4.0.4"
+  },
+  "devDependencies": {}
+}

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

@@ -0,0 +1,41 @@
+import { type LifetimeScope } from "@decohere/crucible";
+import { type IConfigurationService } from "@decohere/core/configuration";
+import type { HostedServiceHost } from "../hosting/hosted-service-host.js";
+import type { HttpProvider, StartResponse } from "../routing/anvil.types.js";
+export declare class ApiConfiguration {
+    port: number;
+}
+export type StartOptions = {
+    port: number;
+    host?: string;
+    /**
+     * Signals that stop the app gracefully: stop accepting connections, let in-flight
+     * requests finish, stop hosted services, then dispose services. Default SIGTERM and SIGINT; `false` to
+     * handle signals yourself.
+     */
+    shutdownSignals?: readonly NodeJS.Signals[] | false;
+    /** How long a signalled shutdown may take before the process exits with code 1. Default 10s. */
+    shutdownTimeoutMs?: number;
+};
+export declare class App {
+    private readonly container;
+    private configurationService?;
+    private httpProvider?;
+    private hostedServices?;
+    private _addresses;
+    private logger;
+    private disposing;
+    private disposingContainer;
+    private signalHandler;
+    private shutdownSignals;
+    constructor(container: LifetimeScope, configurationService?: IConfigurationService, httpProvider?: HttpProvider, hostedServices?: HostedServiceHost);
+    get addresses(): readonly string[];
+    start(options?: StartOptions): Promise<StartResponse>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Stop the app. Calling it again (or from a signal) returns the same shutdown. */
+    dispose(): Promise<void>;
+    private stop;
+    private stopOnSignals;
+    private removeSignalHandlers;
+    private getPort;
+}

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

@@ -0,0 +1,2 @@
+export * from "./app.js";
+export * from "./module.js";

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

@@ -0,0 +1,15 @@
+import type { ContainerBuilder } from "@decohere/crucible";
+import type { Constructable } from "@decohere/core/reflection";
+export type ModuleDefinition = {
+    name: string;
+    entities?: Constructable[];
+    repositories?: Constructable[];
+    registerServices?(containerBuilder: ContainerBuilder): void;
+};
+export declare abstract class Module {
+    abstract name: string;
+    constructor(data: Partial<Module>);
+    readonly entities?: readonly Constructable[];
+    readonly repositories?: readonly Constructable[];
+    abstract registerServices?(containerBuilder: ContainerBuilder): void;
+}

package/types/src/auth/ability.d.ts

@@ -0,0 +1,19 @@
+import type { Principal } from "./auth.types.js";
+/** Root role — expands to CASL `manage`/`all` (covers every future ability). */
+export declare const ADMIN_ROLE = "admin";
+/**
+ * Default CASL ability factory.
+ *
+ * - `admin` role → `manage` / `all` (wildcard)
+ * - otherwise map `principal.scopes` of the form `"action:Subject"` to CASL rules
+ *
+ * Pass a custom factory to `withAuth()` (or override the app stub) for product-specific rules.
+ */
+export declare function defineAbilitiesFor(principal: Principal): import("@casl/ability").MongoAbility<import("@casl/ability").AbilityTuple, import("@casl/ability").MongoQuery>;
+/**
+ * Map a raw JWT payload → {@link Principal}.
+ *
+ * Merges OAuth `scope` / `scopes` with an IdP `permissions` claim (e.g. Auth0 API permissions).
+ * Override via `withAuth(..., { principalMapper })` when claims differ.
+ */
+export declare function createPrincipalFromPayload(payload: Record<string, unknown>): Principal;

package/types/src/auth/auth.config.d.ts

@@ -0,0 +1,28 @@
+import type { Principal } from "./auth.types.js";
+/**
+ * Configuration for the TokenService, read from the `auth` section of the
+ * application config file. Exactly one of the discriminant fields must be set.
+ *
+ * Production  → use `jwksUrl`, `publicKey`, or `secret`.
+ * Development → use `devStatic` (only works when NODE_ENV=development).
+ */
+export declare class AuthConfig {
+    /** OIDC discovery URL — the issuer base URL, e.g. https://accounts.google.com.
+     *  The framework appends `/.well-known/openid-configuration` automatically.
+     *  Use this instead of `jwksUrl` for any standard OIDC-compliant IdP.
+     */
+    discoveryUrl?: string;
+    /** JWKS endpoint URL (RS256 / ES256 via remote key set). */
+    jwksUrl?: string;
+    /** PEM-encoded public key or JWK JSON string (RS256 / ES256 static key). */
+    publicKey?: string;
+    algorithms?: string[];
+    /** Shared secret for HS256. */
+    secret?: string;
+    /** Issuer claim to validate (all non-devStatic variants). */
+    issuer?: string;
+    /** Audience claim to validate (all non-devStatic variants). */
+    audience?: string;
+    /** Static principal injected for every request (development only). */
+    devStatic?: Principal;
+}

package/types/src/auth/auth.extensions.d.ts

@@ -0,0 +1,53 @@
+import { Builder } from "../builder/builder.js";
+import type { PrincipalMapper } from "./auth.types.js";
+import type { AbilityFactory } from "./casl-authorization.service.js";
+export { ADMIN_ROLE, createPrincipalFromPayload, defineAbilitiesFor } from "./ability.js";
+export type WithAuthOptions = {
+    /**
+     * Override the default JWT payload → Principal mapping.
+     * Use this when your IdP stores roles or scopes in non-standard claims.
+     *
+     * @example Keycloak realm roles:
+     * ```ts
+     * builder.withAuth(factory, {
+     *   principalMapper: (p) => ({
+     *     sub: p.sub as string,
+     *     scopes: (p.realm_access as any)?.roles?.map((r: string) => `manage:${r}`) ?? [],
+     *   }),
+     * });
+     * ```
+     */
+    principalMapper?: PrincipalMapper;
+};
+declare module "@decohere/http" {
+    interface Builder {
+        /**
+         * Configure JWT authentication from the `auth` config section and wire
+         * up a CASL authorization service.
+         *
+         * By default, `defineAbilitiesFor` grants `manage`/`all` for the `admin`
+         * role and maps `principal.scopes` of the form `"action:Subject"` to CASL
+         * rules. Pass a custom `abilityFactory` to override that behaviour.
+         *
+         * Requires `.withConfiguration(...)` to be called on the builder.
+         *
+         * @example Default (scope-based, no boilerplate):
+         * ```ts
+         * builder.withConfiguration(YamlDataSource).withAuth();
+         * ```
+         *
+         * @example Custom override:
+         * ```ts
+         * builder.withAuth((principal) => {
+         *   const { can, build } = new AbilityBuilder(createMongoAbility);
+         *   // custom logic ...
+         *   return build();
+         * });
+         * ```
+         */
+        withAuth(abilityFactory?: AbilityFactory, options?: WithAuthOptions): Builder;
+    }
+}
+export declare class BuilderExtensions {
+    static withAuth(builder: Builder, abilityFactory?: AbilityFactory, options?: WithAuthOptions): Builder<import("@decohere/http").App>;
+}

package/types/src/auth/auth.types.d.ts

@@ -0,0 +1,73 @@
+export type Principal = {
+    sub: string;
+    roles?: string[];
+    scopes?: string[];
+    [key: string]: unknown;
+};
+/** Maps a raw JWT payload to a Principal. Override the default via withAuth() options. */
+export type PrincipalMapper = (payload: Record<string, unknown>) => Principal;
+export type JwksConfig = {
+    jwksUrl: string;
+    issuer?: string;
+    /** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+    audience: string;
+};
+export type PublicKeyConfig = {
+    publicKey: string;
+    algorithms?: string[];
+    issuer?: string;
+    /** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+    audience: string;
+};
+export type SecretConfig = {
+    secret: string;
+    issuer?: string;
+    /** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+    audience: string;
+};
+export type DevStaticConfig = {
+    devStatic: Principal;
+};
+/**
+ * Resolve IdP configuration automatically from an OIDC discovery endpoint
+ * (`{discoveryUrl}/.well-known/openid-configuration`). The `discoveryUrl` is
+ * also used as the expected `iss` claim unless the discovery document provides
+ * a different value.
+ */
+export type DiscoveryConfig = {
+    discoveryUrl: string;
+    /** Required — empty/undefined disables jose `aud` checks (cross-API token accept). */
+    audience: string;
+};
+/**
+ * Framework-agnostic authorization service. Implement this interface (e.g.
+ * via CaslAuthorizationService) and register it under AuthorizationServiceToken.
+ * Throw ForbiddenError to deny access.
+ */
+export interface IAuthorizationService {
+    authorizeRequest(request: import("../routing/anvil.types.js").HttpRequest, action: string, subject: string): Promise<Principal>;
+    /**
+     * Verify the request has a valid principal without checking a CASL ability.
+     * Used when auth is enabled but the route has no `@Authorize` metadata.
+     */
+    authenticateRequest(request: import("../routing/anvil.types.js").HttpRequest): Promise<Principal>;
+    authorize(principal: Principal, action: string, subject: string): Promise<void>;
+}
+export type TokenServiceConfig = JwksConfig | PublicKeyConfig | SecretConfig | DevStaticConfig | DiscoveryConfig;
+export declare function isDiscoveryConfig(config: TokenServiceConfig): config is DiscoveryConfig;
+export declare function isDevStaticConfig(config: TokenServiceConfig): config is DevStaticConfig;
+export declare function isJwksConfig(config: TokenServiceConfig): config is JwksConfig;
+export declare function isPublicKeyConfig(config: TokenServiceConfig): config is PublicKeyConfig;
+export declare function isSecretConfig(config: TokenServiceConfig): config is SecretConfig;
+/** `devStatic` is only valid for local development NODE_ENV values. */
+export declare function isDevelopmentNodeEnv(nodeEnv?: string): boolean;
+/**
+ * Refuse `devStatic` outside development — otherwise any Bearer string is
+ * accepted as the configured principal (auth bypass in production).
+ */
+export declare function assertDevStaticAllowed(nodeEnv?: string): void;
+/**
+ * jose skips `aud` validation when `audience` is undefined or "". Require a
+ * non-empty audience for every non-devStatic verification strategy.
+ */
+export declare function assertNonEmptyAudience(audience: string | undefined): asserts audience is string;

package/types/src/auth/casl-authorization.service.d.ts

@@ -0,0 +1,28 @@
+import type { AnyAbility } from "@casl/ability";
+import type { HttpRequest } from "../routing/anvil.types.js";
+import type { IAuthorizationService, Principal } from "./auth.types.js";
+import type { TokenService } from "./token-service.js";
+export type AbilityFactory = (principal: Principal) => AnyAbility;
+/**
+ * IAuthorizationService implementation backed by CASL.
+ *
+ * Register it under AuthorizationServiceToken:
+ * ```ts
+ * builder.withServices((c) =>
+ *   c.registerSingleton(AuthorizationServiceToken, new CaslAuthorizationService((principal) => {
+ *     const { can, build } = new AbilityBuilder(createMongoAbility);
+ *     if (principal.roles?.includes("admin")) can("manage", "all");
+ *     else can("read", "Post");
+ *     return build();
+ *   }))
+ * );
+ * ```
+ */
+export declare class CaslAuthorizationService implements IAuthorizationService {
+    private readonly factory;
+    private readonly tokenService?;
+    constructor(factory: AbilityFactory, tokenService?: TokenService);
+    authorizeRequest(request: HttpRequest, action: string, subject: string): Promise<Principal>;
+    authenticateRequest(request: HttpRequest): Promise<Principal>;
+    authorize(principal: Principal, action: string, subject: string): Promise<void>;
+}

package/types/src/auth/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./ability.js";
+export * from "./auth.config.js";
+export * from "./auth.types.js";
+export * from "./casl-authorization.service.js";
+export * from "./principal-provider.js";
+export * from "./token-service.js";

package/types/src/auth/principal-provider.d.ts

@@ -0,0 +1,20 @@
+import type { Principal } from "./auth.types.js";
+/**
+ * Read-only view of the authenticated principal for the current request.
+ * Inject this interface (via IPrincipalProviderToken) in any request-scoped
+ * service to access the verified identity without coupling to the routing layer.
+ */
+export interface IPrincipalProvider {
+    readonly currentPrincipal: Principal | undefined;
+}
+/**
+ * Concrete, request-scoped implementation. The Router sets the principal
+ * after JWT verification; downstream services consume it via IPrincipalProvider.
+ *
+ * @internal — framework use only. Inject IPrincipalProvider, not this class.
+ */
+export declare class PrincipalProvider implements IPrincipalProvider {
+    private _principal;
+    get currentPrincipal(): Principal | undefined;
+    setPrincipal(principal: Principal | undefined): void;
+}

package/types/src/auth/safe-outbound-url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validate URLs used for OIDC discovery / JWKS fetches to reduce SSRF risk.
+ *
+ * - http(s) only; https required except loopback (local IdP tests)
+ * - no credentials in the URL
+ * - hostname must not resolve to private, link-local, or metadata ranges
+ *   (loopback allowed only when NODE_ENV is development/dev/test)
+ */
+export declare function assertSafeOutboundUrl(raw: string, label: string): Promise<URL>;

package/types/src/auth/token-service.d.ts

@@ -0,0 +1,31 @@
+import { type JWTPayload } from "jose";
+import type { HttpRequest } from "../routing/anvil.types.js";
+import type { Principal, PrincipalMapper, TokenServiceConfig } from "./auth.types.js";
+export declare class TokenService {
+    private readonly config;
+    private readonly principalMapper?;
+    /** Lazily resolved JWKS set when using OIDC discovery. */
+    private discoveryJwks?;
+    private discoveryIssuer?;
+    /** Remote key set for `jwksUrl` mode, created once so jose can cache the keys (#499). */
+    private configuredJwks?;
+    constructor(config: TokenServiceConfig, principalMapper?: PrincipalMapper);
+    verifyRequest(request: HttpRequest): Promise<Principal>;
+    verify(credentials: string): Promise<Principal>;
+    /**
+     * Resolve how to verify tokens for the configured strategy:
+     * - OIDC discovery → fetch JWKS + issuer from `/.well-known/openid-configuration`
+     * - explicit JWKS URL → remote key set + configured issuer/audience
+     * - public key / shared secret → static key material + configured issuer/audience
+     */
+    private resolveVerificationContext;
+    private resolveOidcDiscovery;
+    /**
+     * Sign a payload and return a JWT string.
+     * Only available when configured with a SecretConfig (HS256).
+     * For RS256/ES256 issuance, the caller is responsible for key management.
+     */
+    sign(payload: Omit<JWTPayload, "iss" | "aud"> & Record<string, unknown>, expiresIn?: string): Promise<string>;
+    private getStaticKey;
+    private mapPrincipal;
+}

package/types/src/builder/builder.d.ts

@@ -0,0 +1,36 @@
+import { type ContainerBuilder, ServiceContainerBuilder, type IContainer } from "@decohere/crucible";
+import { type IConfigurationService } from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { App } from "../app/app.js";
+import type { HostedService } from "../hosting/hosted-service.js";
+export type BuilderOptions = {
+    containerBuilder?: ServiceContainerBuilder;
+    applicationName?: string;
+};
+export declare class Builder<T extends App = App> {
+    static create<T extends App = App>(options?: BuilderOptions): Builder<T>;
+    readonly containerBuilder: ServiceContainerBuilder;
+    readonly applicationName?: string;
+    private readonly logger;
+    private userServices;
+    private preBuildSteps;
+    private postBuildSteps;
+    private readonly hostedServices;
+    constructor(options?: BuilderOptions);
+    withServices(userServices: (containerBuilder: ContainerBuilder) => void): Builder<T>;
+    /**
+     * Run {@link HostedService}s for the life of the app: started in this order before the HTTP
+     * server listens, stopped in reverse when the app stops (including SIGTERM and Flux reboots).
+     * Each is registered as a singleton, so other services can inject it by its class.
+     */
+    withHostedService(...types: Constructable<HostedService>[]): Builder<T>;
+    registerPreBuildStep(step: (config: IConfigurationService, containerBuilder: ContainerBuilder) => Promise<void> | void): void;
+    registerPostBuildStep(step: (container: IContainer) => Promise<void> | void): void;
+    buildAndStart<T extends App>(type?: Constructable<T>): Promise<T | App>;
+    build<T extends App = App>(type?: Constructable<T>): Promise<T | App>;
+    private configureUserServices;
+    private runPreBuildSteps;
+    private runPostBuildSteps;
+    private configureApp;
+    private resolveApp;
+}

package/types/src/builder/index.d.ts

@@ -0,0 +1 @@
+export * from "./builder.js";

package/types/src/const.d.ts

@@ -0,0 +1,32 @@
+export declare const RouteRegistryToken: unique symbol;
+export declare const HttpProviderToken: unique symbol;
+export declare const RouterToken: unique symbol;
+export declare const PrincipalToken: unique symbol;
+export declare const IPrincipalProviderToken: unique symbol;
+export declare const TokenServiceToken: unique symbol;
+export declare const AuthorizationServiceToken: unique symbol;
+export declare const HttpOptionsToken: unique symbol;
+export declare const ExceptionFilterHostToken: unique symbol;
+export declare const ReadinessCheckToken: unique symbol;
+export declare const ReadinessServiceToken: unique symbol;
+export declare const HostedServiceHostToken: unique symbol;
+export type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+export declare const HTTPMethods: {
+    GET: "GET";
+    PUT: "PUT";
+    POST: "POST";
+    PATCH: "PATCH";
+    DELETE: "DELETE";
+};
+export declare const MetadataKeys: {
+    controller: string;
+    route: string;
+    parameter: string;
+    fieldMap: string;
+    authorize: string;
+    allowAnonymous: string;
+    httpCode: string;
+    headers: string;
+    catch: string;
+    sse: string;
+};

package/types/src/health/health.controller.d.ts

@@ -0,0 +1,16 @@
+import { ReadinessService } from "./readiness.service.js";
+/**
+ * Liveness (`/health`) and readiness (`/ready`) probes.
+ * Both are anonymous so orchestration can scrape them with auth enabled, and stay at the root
+ * under a global prefix, where platforms look for them.
+ */
+export declare class HealthController {
+    private readonly readiness;
+    constructor(readiness: ReadinessService);
+    health(): {
+        status: string;
+    };
+    ready(): Promise<{
+        status: string;
+    }>;
+}

package/types/src/health/health.extensions.d.ts

@@ -0,0 +1,31 @@
+import { Builder } from "../builder/builder.js";
+import "../http/http.extensions.js";
+import type { IReadinessCheck } from "./readiness.types.js";
+export type WithHealthOptions = {
+    /** Extra readiness probes (e.g. custom dependency checks). */
+    checks?: IReadinessCheck[];
+    /**
+     * Serve the probes under the global prefix (`/api/health`) instead of at the root. Default
+     * `false`: Cloud Run, Kubernetes and most load balancers probe the root.
+     */
+    underGlobalPrefix?: boolean;
+};
+declare module "@decohere/http" {
+    interface Builder {
+        /**
+         * Register anonymous `/health` (liveness) and `/ready` (readiness) routes.
+         *
+         * Readiness runs every {@link IReadinessCheck} registered under
+         * {@link ReadinessCheckToken} (TypeORM registers one per datasource when
+         * `.withTypeOrm()` is used). Pass `checks` for app-specific probes.
+         *
+         * The probes stay at the root under `withGlobalPrefix`, unless `underGlobalPrefix` is set.
+         *
+         * Requires `.withHttpProvider(...)` (or `@decohere/http/http` side-effect).
+         */
+        withHealth(options?: WithHealthOptions): Builder;
+    }
+}
+export declare class BuilderExtensions {
+    static withHealth(builder: Builder, options?: WithHealthOptions): Builder<import("@decohere/http").App>;
+}

package/types/src/health/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./health.controller.js";
+export * from "./health.extensions.js";
+export * from "./readiness.service.js";
+export * from "./readiness.types.js";

package/types/src/health/readiness.service.d.ts

@@ -0,0 +1,9 @@
+import type { HostedServiceHost } from "../hosting/hosted-service-host.js";
+import type { IReadinessCheck, ReadinessResult } from "./readiness.types.js";
+export declare class ReadinessService {
+    private readonly hostedServices?;
+    private readonly checks;
+    constructor(checks?: IReadinessCheck[], hostedServices?: HostedServiceHost);
+    /** Registered checks, then each started hosted service that has a `check()` (still warming up). */
+    checkAll(): Promise<ReadinessResult>;
+}

package/types/src/health/readiness.types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A dependency probe run by `GET /ready`.
+ * Register instances under {@link ReadinessCheckToken} (multi-inject).
+ */
+export interface IReadinessCheck {
+    readonly name: string;
+    check(): Promise<void>;
+}
+export type ReadinessResult = {
+    ok: true;
+} | {
+    ok: false;
+    failures: string[];
+};