@devxcrew/framework 0.1.8 → 0.1.10

package/README.md

@@ -1,139 +1,92 @@
-# framework
+# @devxcrew/framework
 
-Own reusable configuration validation and native HTTP primitives.
+Shared Node and TypeScript runtime for Codexsun apps. It provides module lifecycle, HTTP, validation, logging, health, security, and a browser API client. Business rules stay in each app module. Platform Core owns identity, roles, and tenancy.
 
-Use the sibling workspace layout. Shared framework and UI keep their existing public exports and
-build contracts.
+## Install
 
-## Run
-
-Use Node 26.10 or newer and the package manifest requirements. Clone the sibling tools and
-mcp-governance repositories along with this repository.
+Use Node 26.10 or newer.
 
 ```powershell
-npm install
-npm run check
+npm install @devxcrew/framework
 ```
 
-Cxsun runs npm run build:framework using its compiler to build this package.
+Import server exports from `@devxcrew/framework`. Import the browser client from `@devxcrew/framework/client`.
+
+## Owner modules and routes
+
+Each app module exposes a public provider contract. The app composition root connects providers and passes their routes to `createApiRouter`. Keep Zod schemas, controllers, services, and persistence inside the owner module.
+
+```ts
+import {
+  composeModules,
+  createApiRouter,
+  createApplicationServer,
+  createModuleToken,
+  defineModuleProvider,
+  type ApiRoute,
+} from "@devxcrew/framework";
+
+const statusToken = createModuleToken<{ routes: ApiRoute[] }>("status");
+const status = defineModuleProvider({
+  token: statusToken,
+  dependencies: [],
+  create: () => ({
+    routes: [
+      {
+        method: "GET",
+        path: "/api/v1/status",
+        handler(_request, response) {
+          response.setHeader("Content-Type", "application/json");
+          response.end(JSON.stringify({ data: { ready: true } }));
+        },
+      },
+    ],
+  }),
+});
+
+const modules = composeModules([status]);
+await modules.start();
+const server = createApplicationServer({
+  config: {
+    name: "example",
+    port: 3000,
+    url: "http://localhost:3000",
+    host: "localhost",
+    mode: "development",
+  },
+  frontendDirectory: "dist/web",
+  apiHandler: createApiRouter([modules.get(statusToken)]),
+});
+server.listen(3000);
+```
 
-## Repository records
+`createApiRouter` matches methods and paths. Static paths take priority over `:id` paths. Owners validate route IDs, query strings, and JSON bodies. The router does not implement CRUD or business rules.
 
-- `AGENTS.md`: repository instructions and ownership rules.
-- `agent/SKILLS.md`: repository capabilities.
-- `agent/TASK.md`: current task and status.
-- `agent/PLAN.md`: next steps.
-- `agent/CHANGELOG.md`: versioned changes and validation results.
+`composeModules` also supports the older string-based `ModuleProvider` contract. New modules can use tokens for typed dependencies and runtime token checks.
 
-## Shared guidance
+## HTTP and validation
 
-Retrieve shared documentation and rules only from `https://mcp.codexsun.com/mcp` using `npm run mcp:connect`.
-A successful authenticated connection is required before repository work. Stop and report connection failures.
-Do not use local guides or cached instructions as fallback. Instruction retrieval does not authorize actions.
+- `readJsonBody` limits bytes and returns `unknown`. Validate it with an owner Zod schema through `parseWithSchema`.
+- Validation failures return HTTP 422 with `message` and `errors`. The older `error.fields` shape remains during migration.
+- `parseListQuery` checks page size and allowed sort fields. Owner schemas check business filters.
+- Owners return resource data as `{ data }` and lists as `{ data, meta, links }`.
+- `createApiClient` reads JSON responses and safe field errors. It does not add authentication or retry writes.
 
-Retrieve shared documentation and rules only from `https://mcp.codexsun.com/mcp` using `npm run mcp:connect`.
-A successful authenticated connection is required before repository work. Stop and report connection failures.
-Do not use local guides or cached instructions as fallback. Instruction retrieval does not authorize actions.
+## Operations
 
-Configure these values with `.env.example`:
+- `createApplicationServer` sets basic security headers. Configure exact CORS origins, trusted proxy addresses, and rate limits for each app.
+- The built-in rate limiter is local to one process. Set `rateLimit.store` to an app-owned atomic shared store when deployment uses multiple instances. Store failures return 503.
+- Set `logger` for request logs. Set `onRequestComplete` to pass request data to a metrics or tracing adapter. Neither receives URL query values.
+- Set `readiness` to a sync or async check. The server bounds it with `readinessTimeoutMs`. `createAsyncHealthProvider` bounds named async dependency checks.
+- API handlers and module start and stop hooks have configurable deadlines. Owners must honor cancellation and release resources.
 
-- `MCP_SERVER_URL`
-- `MCP_SERVER_SECRET`
-- `APP_ID`
-- `APP_USER`
+## Work on this repository
 
-Keep the secret in ignored `.env` files.
+Connect to live governance before repository work. Stop if the authenticated connection fails. Do not use local or cached guidance as a fallback.
 
 ```powershell
 npm run mcp:connect
-npm run mcp:verify
-```
-
-Use `mcp:connect` to retrieve instructions. Use `mcp:verify` for a strict connection test.
-Connection failures do not block application work. Editor registration uses the central connection
-template and depends on the editor.
-
-## Maintenance
-
-```powershell
-npm run version-bump -- --dry-run
-npm run version-bump -- --title "Release title" --note "Change details"
-npm run check:versions
-npm run fix:line-endings
-npm run lines:check
-npm run github:now -- --dry-run
+npm run release:check
 ```
 
-Version bumps align `package.json`, `package-lock.json`, and `agent/CHANGELOG.md`. Record changes
-and validation before committing.
-
-Commit subjects use `#<patch> - <release title>`. For example:
-`#5 - Central governance and repository agent layout`.
-
-Review the changed files before an authorized `npm run github:now`. Do not bump again when the
-release version is already prepared.
-
-## Tools source and publication
-
-Workspace maintenance delegates to `shared/tools`. The installed npm package remains pinned at
-`0.1.3` until agent changelog support is published.
-
-GitHub source releases use `github:now`. Npm publication requires separate authorization.
-
-## npm package
-
-Framework publishes compiled ESM JavaScript and TypeScript declarations. Run npm run build before local development consumption.
-
-Run `npm run release:check`, then `npm publish --access public` from this repository.
-Only public exports are supported. App manifests use npm versions.
-
-## Public runtime contracts
-
-`composeModules` registers owner providers in dependency order. Factories receive only their declared dependencies.
-`start` runs lifecycle hooks. Failed startup calls stop hooks in reverse order, including the failed module.
-`stop` attempts every cleanup hook and reports cleanup failures together.
-
-`createApplicationServer` keeps the existing static and development behavior.
-Optional `apiHandler` receives the request, response, and request context for `/api` paths.
-The handler owns routing and independent Zod validation before service execution.
-Unexpected handler failures return a safe JSON error with a generated request ID.
-Optional `readiness` exposes `/health/ready`. Readiness reports the consumer's actual dependency state.
-Receive and header timeouts are configurable positive millisecond values. They do not bound handler execution.
-
-`readJsonBody` checks content type and limits bytes. Its result is unknown until the owner validates it.
-`parseListQuery` validates pagination and allowlisted sort fields. Owners validate domain filters independently.
-`HttpError` carries safe transport errors and optional field messages. Do not place secrets in these messages.
-`createRequestContext` supplies a server-generated request ID and an abort signal.
-Identity, tenant scope, transactions, and domain rules remain with their owner providers.
-
-Provider factories must only compose values. Acquire connections and other resources inside start hooks so failed startup can release them.
-Stop during startup is rejected. Concurrent stop calls share one cleanup operation.
-Oversized streamed JSON is drained without destroying the response socket, allowing a safe 413 response.
-
-## Handler and shutdown deadlines
-
-Set `handlerTimeoutMs` on `createApplicationServer` to bound API response time. The default is 30000 milliseconds.
-Request contexts expose `deadlineAt` and `signal`. At the deadline, the server aborts the signal.
-It returns a safe 504 before response headers or destroys an incomplete streamed response.
-Handlers must honor cancellation and check response state before writing late results.
-A deadline cannot stop synchronous JavaScript or forcibly cancel an uncooperative dependency.
-
-Set `shutdownTimeoutMs` in the second argument of `composeModules`. The default total budget is 30000 milliseconds.
-Stop attempts every hook in reverse dependency order. The budget bounds awaited asynchronous cleanup.
-A timed-out hook can continue running. State becomes `failed`, and stop rejects with cleanup failures.
-Consumers must report failed cleanup and apply their process termination policy.
-
-## Startup deadline
-
-Set startupTimeoutMs in composeModules options. The default total startup budget is 30000 milliseconds.
-Start hooks receive the owner provider and an AbortSignal. Timeout aborts the signal and rolls back started modules.
-An uncooperative hook can continue. Owners must honor cancellation before acquiring or retaining resources.
-
-## Consumer transaction and cancellation contract
-
-Framework owns request deadlines and cancellation signals. The module that owns a mutation owns its database transaction.
-A module validates authorization and input before persistence. It checks cancellation before a write and before committing.
-Cancellation after a successful commit does not roll back committed data. A client must reload before retrying an uncertain mutation.
-Existing identity updates use expectedVersion for stale-write detection. Token completion uses a single database claim.
-Do not retry POST mutations automatically. Add an idempotency key only when a real consumer requires repeatable retries.
-Synchronous identity operations need no generic event bus or queue. External delivery stays outside a database transaction.
+Keep secrets in ignored environment files. Commit and publish through the repository release workflow only when authorized.

package/dist/http/server.d.ts

@@ -1,12 +1,26 @@
 import { type RequestListener } from "node:http";
 import type { ApplicationConfig } from "../runtime/config.js";
 import { createRequestContext } from "../modules/http/http.provider.js";
+import { type HttpSecurityOptions } from "../modules/http/http-security.provider.js";
+import type { Logger } from "../modules/logger/logger.provider.js";
+export interface RequestCompletion {
+    requestId: string;
+    method: string;
+    path: string;
+    statusCode: number;
+    durationMs: number;
+    aborted: boolean;
+}
 export interface ApplicationServerOptions {
     config: ApplicationConfig;
     frontendDirectory: string;
     developmentHandler?: RequestListener;
     apiHandler?: (request: import("node:http").IncomingMessage, response: import("node:http").ServerResponse, context: ReturnType<typeof createRequestContext>) => void | Promise<void>;
-    readiness?: () => boolean;
+    readiness?: () => boolean | Promise<boolean>;
+    readinessTimeoutMs?: number;
+    security?: HttpSecurityOptions;
+    logger?: Logger;
+    onRequestComplete?: (event: RequestCompletion) => void;
     requestTimeoutMs?: number;
     headersTimeoutMs?: number;
     handlerTimeoutMs?: number;

package/dist/http/server.js

@@ -1,7 +1,8 @@
 import { createServer } from "node:http";
 import { readFile, realpath } from "node:fs/promises";
 import { extname, resolve, sep } from "node:path";
-import { createRequestContext, writeJsonError, HttpError } from "../modules/http/http.provider.js";
+import { createRequestContext, writeJsonError, HttpError, } from "../modules/http/http.provider.js";
+import { createHttpSecurityProvider, } from "../modules/http/http-security.provider.js";
 const contentTypes = {
     ".html": "text/html; charset=utf-8",
     ".js": "text/javascript; charset=utf-8",
@@ -14,52 +15,134 @@ const contentTypes = {
 };
 export function createApplicationServer(options) {
     const handlerTimeoutMs = positiveTimeout(options.handlerTimeoutMs ?? 30_000);
+    const readinessTimeoutMs = positiveTimeout(options.readinessTimeoutMs ?? 2_000);
+    const security = createHttpSecurityProvider(options.security);
     const server = createServer((request, response) => {
-        if (options.readiness && request.url === "/health/ready") {
-            if (request.method !== "GET" && request.method !== "HEAD") {
-                response.writeHead(405, { Allow: "GET, HEAD" });
-                response.end();
-                return;
-            }
-            let ready = false;
-            try {
-                ready = options.readiness();
-            }
-            catch {
-                ready = false;
-            }
-            response.writeHead(ready ? 200 : 503, { "Content-Type": "application/json", "Cache-Control": "no-store" });
-            response.end(request.method === "HEAD" ? undefined : JSON.stringify({ ready }));
-            return;
-        }
-        if (options.apiHandler && /^\/api(?:\/|\?|$)/.test(request.url ?? "")) {
-            const context = createRequestContext(request, Date.now() + handlerTimeoutMs);
-            const deadline = setTimeout(() => {
-                const error = new HttpError(504, "request_timeout", "Request deadline exceeded.");
-                context.abort(error);
-                if (!response.writableEnded && !response.destroyed)
-                    writeJsonError(response, error, context.requestId);
-            }, handlerTimeoutMs);
-            response.once("finish", () => clearTimeout(deadline));
-            response.once("close", () => clearTimeout(deadline));
-            response.setHeader("X-Request-ID", context.requestId);
-            response.once("close", () => { if (!response.writableFinished)
-                request.emit("aborted"); });
-            void Promise.resolve().then(() => options.apiHandler(request, response, context))
-                .catch((error) => {
-                if (!response.writableEnded && !response.destroyed)
-                    writeJsonError(response, error, context.requestId);
-            });
-            return;
-        }
-        if (options.developmentHandler)
-            return options.developmentHandler(request, response);
-        void serveFrontend(options.frontendDirectory, request.url || "/", request.method || "GET", response);
+        const isApi = /^\/api(?:\/|\?|$)/.test(request.url ?? "");
+        const context = createRequestContext(request);
+        response.setHeader("X-Request-ID", context.requestId);
+        reportRequest(request, response, context.requestId, options);
+        void security
+            .handleAsync(request, response)
+            .then((handled) => {
+            if (!handled && !response.destroyed)
+                serveRequest(request, response, context, isApi, options, handlerTimeoutMs, readinessTimeoutMs);
+        })
+            .catch(() => {
+            if (!response.writableEnded && !response.destroyed)
+                writeJsonError(response, new HttpError(503, "security_unavailable", "Request checks are unavailable."), context.requestId);
+        });
     });
     server.requestTimeout = positiveTimeout(options.requestTimeoutMs ?? 30_000);
     server.headersTimeout = positiveTimeout(options.headersTimeoutMs ?? 10_000);
     return server;
 }
+function serveRequest(request, response, context, isApi, options, handlerTimeoutMs, readinessTimeoutMs) {
+    if (options.readiness && request.url === "/health/ready") {
+        void serveReadiness(request, response, options.readiness, readinessTimeoutMs);
+        return;
+    }
+    if (options.apiHandler && isApi) {
+        context.deadlineAt = Date.now() + handlerTimeoutMs;
+        const deadline = setTimeout(() => {
+            const error = new HttpError(504, "request_timeout", "Request deadline exceeded.");
+            context.abort(error);
+            if (!response.writableEnded && !response.destroyed)
+                writeJsonError(response, error, context.requestId);
+        }, handlerTimeoutMs);
+        response.once("finish", () => clearTimeout(deadline));
+        response.once("close", () => clearTimeout(deadline));
+        response.once("close", () => {
+            if (!response.writableFinished)
+                request.emit("aborted");
+        });
+        void Promise.resolve()
+            .then(() => options.apiHandler(request, response, context))
+            .catch((error) => {
+            if (!response.writableEnded && !response.destroyed)
+                writeJsonError(response, error, context.requestId);
+        });
+        return;
+    }
+    if (options.developmentHandler) {
+        options.developmentHandler(request, response);
+        return;
+    }
+    void serveFrontend(options.frontendDirectory, request.url || "/", request.method || "GET", response);
+}
+async function serveReadiness(request, response, readiness, timeoutMs) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        response.writeHead(405, { Allow: "GET, HEAD" });
+        response.end();
+        return;
+    }
+    let timer;
+    let ready = false;
+    try {
+        ready = await Promise.race([
+            Promise.resolve().then(readiness),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        ready = false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.destroyed)
+        return;
+    response.writeHead(ready ? 200 : 503, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+    });
+    response.end(request.method === "HEAD" ? undefined : JSON.stringify({ ready }));
+}
+function reportRequest(request, response, requestId, options) {
+    if (!options.logger && !options.onRequestComplete)
+        return;
+    const startedAt = Date.now();
+    let reported = false;
+    const report = () => {
+        if (reported)
+            return;
+        reported = true;
+        const event = {
+            requestId,
+            method: request.method ?? "GET",
+            path: safePath(request.url),
+            statusCode: response.statusCode,
+            durationMs: Date.now() - startedAt,
+            aborted: !response.writableFinished,
+        };
+        try {
+            options.onRequestComplete?.(event);
+        }
+        catch {
+            /* A diagnostics sink must not affect the response. */
+        }
+        if (options.logger) {
+            const level = event.aborted || event.statusCode >= 500
+                ? "error"
+                : event.statusCode >= 400
+                    ? "warn"
+                    : "info";
+            options.logger[level]("HTTP request completed", { ...event });
+        }
+    };
+    response.once("finish", report);
+    response.once("close", report);
+}
+function safePath(url) {
+    try {
+        return new URL(url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        return "/";
+    }
+}
 function positiveTimeout(value) {
     if (!Number.isSafeInteger(value) || value < 1)
         throw new Error("Invalid HTTP timeout.");
@@ -95,8 +178,12 @@ async function serveFrontend(root, requestUrl, method, response) {
     }
     const target = extname(pathname) ? file : resolve(root, "index.html");
     try {
-        const [actualRoot, actualTarget] = await Promise.all([realpath(root), realpath(target)]);
-        if (actualTarget !== actualRoot && !actualTarget.startsWith(`${actualRoot}${sep}`)) {
+        const [actualRoot, actualTarget] = await Promise.all([
+            realpath(root),
+            realpath(target),
+        ]);
+        if (actualTarget !== actualRoot &&
+            !actualTarget.startsWith(`${actualRoot}${sep}`)) {
             response.writeHead(403);
             response.end("Forbidden");
             return;

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { readApplicationConfig, type ApplicationConfig, } from "./runtime/config.js";
-export { createApplicationServer, type ApplicationServerOptions, } from "./http/server.js";
-export { composeModules, type ModuleProvider } from "./modules/runtime/runtime.provider.js";
-export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody } from "./modules/http/http.provider.js";
+export { createApplicationServer, type ApplicationServerOptions, type RequestCompletion, } from "./http/server.js";
+export { composeModules, createModuleToken, defineModuleProvider, type ModuleProvider, type ModuleToken, type TypedModuleDefinition, } from "./modules/runtime/runtime.provider.js";
+export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody, createApiRouter, type ApiMethod, type ApiRoute, type ApiRouteProvider, } from "./modules/http/http.provider.js";
+export { createValidationProvider, parseWithSchema, type ValidationProvider, } from "./modules/validation/validation.provider.js";
+export { createLogger, type Logger, type LoggerOptions, type LogFields, type LogLevel, type LogRecord, } from "./modules/logger/logger.provider.js";
+export { createHttpSecurityProvider, type HttpSecurityOptions, type HttpSecurityProvider, type RateLimitOptions, type RateLimitStore, } from "./modules/http/http-security.provider.js";
+export { createHealthProvider, createAsyncHealthProvider, type HealthCheck, type HealthProvider, type HealthSnapshot, type AsyncHealthCheck, type AsyncHealthProvider, } from "./modules/health/health.provider.js";

package/dist/index.js

@@ -1,4 +1,8 @@
 export { readApplicationConfig, } from "./runtime/config.js";
 export { createApplicationServer, } from "./http/server.js";
-export { composeModules } from "./modules/runtime/runtime.provider.js";
-export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody } from "./modules/http/http.provider.js";
+export { composeModules, createModuleToken, defineModuleProvider, } from "./modules/runtime/runtime.provider.js";
+export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody, createApiRouter, } from "./modules/http/http.provider.js";
+export { createValidationProvider, parseWithSchema, } from "./modules/validation/validation.provider.js";
+export { createLogger, } from "./modules/logger/logger.provider.js";
+export { createHttpSecurityProvider, } from "./modules/http/http-security.provider.js";
+export { createHealthProvider, createAsyncHealthProvider, } from "./modules/health/health.provider.js";

package/dist/modules/api-client/api-client.provider.d.ts

@@ -0,0 +1,16 @@
+export interface ApiClientOptions {
+    baseUrl: string | URL;
+    headers?: HeadersInit;
+    fetch?: typeof fetch;
+}
+export interface ApiClient {
+    request<T>(path: string | URL, init?: RequestInit): Promise<T>;
+}
+export declare class ApiClientError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    readonly fields?: Record<string, string[]> | undefined;
+    constructor(message: string, status: number, code: string, requestId?: string | undefined, fields?: Record<string, string[]> | undefined);
+}
+export declare function createApiClient(options: ApiClientOptions): ApiClient;

package/dist/modules/api-client/api-client.provider.js

@@ -0,0 +1,79 @@
+export class ApiClientError extends Error {
+    status;
+    code;
+    requestId;
+    fields;
+    constructor(message, status, code, requestId, fields) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.fields = fields;
+        this.name = "ApiClientError";
+    }
+}
+export function createApiClient(options) {
+    const baseUrl = options.baseUrl instanceof URL ? options.baseUrl : new URL(options.baseUrl);
+    const fetcher = options.fetch ?? globalThis.fetch;
+    if (typeof fetcher !== "function")
+        throw new Error("A Fetch implementation is required.");
+    return {
+        async request(path, init = {}) {
+            const url = path instanceof URL ? path : new URL(path, baseUrl);
+            const headers = new Headers(options.headers);
+            new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+            const response = await fetcher(url, { ...init, headers });
+            if (response.status === 204 || init.method?.toUpperCase() === "HEAD")
+                return undefined;
+            const payload = await readPayload(response);
+            if (!response.ok)
+                throw toApiError(response, payload);
+            return payload;
+        },
+    };
+}
+async function readPayload(response) {
+    if (!/application\/(?:[a-z0-9.+-]+\+)?json/i.test(response.headers.get("content-type") ?? ""))
+        return undefined;
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+function toApiError(response, payload) {
+    const envelope = asRecord(payload);
+    const error = asRecord(envelope?.error);
+    const code = stringValue(error?.code) ??
+        (response.status === 422 ? "validation_failed" : "request_failed");
+    const message = stringValue(error?.message) ??
+        stringValue(envelope?.message) ??
+        "The request could not be completed.";
+    return new ApiClientError(message, response.status, code, stringValue(error?.requestId) ??
+        stringValue(envelope?.requestId) ??
+        response.headers.get("x-request-id") ??
+        undefined, readFields(error?.fields) ?? readFields(envelope?.errors));
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function readFields(value) {
+    const source = asRecord(value);
+    if (!source)
+        return undefined;
+    const fields = Object.create(null);
+    for (const [name, messages] of Object.entries(source)) {
+        if (Array.isArray(messages) &&
+            messages.every((message) => typeof message === "string"))
+            fields[name] = messages;
+    }
+    return Object.keys(fields).length
+        ? Object.fromEntries(Object.entries(fields))
+        : undefined;
+}

package/dist/modules/health/health.provider.d.ts

@@ -0,0 +1,13 @@
+export type HealthCheck = () => boolean;
+export type HealthSnapshot = Readonly<Record<string, boolean>>;
+export type AsyncHealthCheck = () => boolean | Promise<boolean>;
+export interface HealthProvider {
+    isReady(): boolean;
+    snapshot(): HealthSnapshot;
+}
+export interface AsyncHealthProvider {
+    isReady(): Promise<boolean>;
+    snapshot(): Promise<HealthSnapshot>;
+}
+export declare function createHealthProvider(checks: Readonly<Record<string, HealthCheck>>): HealthProvider;
+export declare function createAsyncHealthProvider(checks: Readonly<Record<string, AsyncHealthCheck>>, timeoutMs?: number): AsyncHealthProvider;

package/dist/modules/health/health.provider.js

@@ -0,0 +1,53 @@
+export function createHealthProvider(checks) {
+    const entries = Object.entries(checks);
+    if (entries.some(([name, check]) => !name.trim() || typeof check !== "function")) {
+        throw new Error("Health checks require a name and function.");
+    }
+    return {
+        isReady() {
+            return entries.every(([, check]) => runCheck(check));
+        },
+        snapshot() {
+            return Object.fromEntries(entries.map(([name, check]) => [name, runCheck(check)]));
+        },
+    };
+}
+export function createAsyncHealthProvider(checks, timeoutMs = 2_000) {
+    const entries = Object.entries(checks);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+        throw new Error("Invalid health timeout.");
+    if (entries.some(([name, check]) => !name.trim() || typeof check !== "function"))
+        throw new Error("Health checks require a name and function.");
+    const snapshot = async () => Object.fromEntries(await Promise.all(entries.map(async ([name, check]) => [name, await runAsyncCheck(check, timeoutMs)])));
+    return {
+        snapshot,
+        async isReady() {
+            return Object.values(await snapshot()).every(Boolean);
+        },
+    };
+}
+async function runAsyncCheck(check, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(check),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function runCheck(check) {
+    try {
+        return check();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/modules/http/http-rate-limit.d.ts

@@ -0,0 +1,3 @@
+import type { RateLimitOptions } from "./http-security.provider.js";
+export declare function createLimiter(options: RateLimitOptions): (address: string) => number;
+export declare function validateRateLimit(options: RateLimitOptions): void;