@devxcrew/framework 0.1.8 → 0.1.10

package/dist/modules/http/http-rate-limit.js

@@ -0,0 +1,32 @@
+export function createLimiter(options) {
+    const maxEntries = options.maxEntries ?? 10_000;
+    const clients = new Map();
+    return (address) => {
+        const now = Date.now();
+        for (const [key, record] of clients)
+            if (record.resetAt <= now)
+                clients.delete(key);
+        let record = clients.get(address);
+        if (!record) {
+            if (clients.size >= maxEntries)
+                return Math.ceil(options.windowMs / 1000);
+            record = { count: 0, resetAt: now + options.windowMs };
+            clients.set(address, record);
+        }
+        if (record.count >= options.limit)
+            return Math.max(1, Math.ceil((record.resetAt - now) / 1000));
+        record.count++;
+        return 0;
+    };
+}
+export function validateRateLimit(options) {
+    const maxEntries = options.maxEntries ?? 10_000;
+    if (!Number.isSafeInteger(options.limit) ||
+        options.limit < 1 ||
+        !Number.isSafeInteger(options.windowMs) ||
+        options.windowMs < 1 ||
+        !Number.isSafeInteger(maxEntries) ||
+        maxEntries < 1 ||
+        maxEntries > 100_000)
+        throw new Error("Invalid rate limit.");
+}

package/dist/modules/http/http-security.provider.d.ts

@@ -0,0 +1,28 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+export interface RateLimitOptions {
+    limit: number;
+    windowMs: number;
+    maxEntries?: number;
+    store?: RateLimitStore;
+    storeTimeoutMs?: number;
+}
+export interface RateLimitStore {
+    consume(address: string, limit: number, windowMs: number): Promise<number>;
+}
+export interface HttpSecurityOptions {
+    allowedOrigins?: readonly string[];
+    allowedMethods?: readonly string[];
+    allowedHeaders?: readonly string[];
+    exposedHeaders?: readonly string[];
+    allowCredentials?: boolean;
+    preflightMaxAgeSeconds?: number;
+    headers?: Readonly<Record<string, string>>;
+    trustedProxyAddresses?: readonly string[];
+    rateLimit?: RateLimitOptions;
+}
+export interface HttpSecurityProvider {
+    handle(request: IncomingMessage, response: ServerResponse): boolean;
+    handleAsync(request: IncomingMessage, response: ServerResponse): Promise<boolean>;
+    clientAddress(request: IncomingMessage): string;
+}
+export declare function createHttpSecurityProvider(options?: HttpSecurityOptions): HttpSecurityProvider;

package/dist/modules/http/http-security.provider.js

@@ -0,0 +1,188 @@
+import { isIP } from "node:net";
+import { validateHeaderName, validateHeaderValue, } from "node:http";
+import { createLimiter, validateRateLimit } from "./http-rate-limit.js";
+const defaultMethods = [
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+];
+const defaultHeaders = ["Content-Type", "Authorization", "X-Request-ID"];
+export function createHttpSecurityProvider(options = {}) {
+    const origins = new Set((options.allowedOrigins ?? []).map(validateOrigin));
+    const methods = validateTokens(options.allowedMethods ?? defaultMethods, "method", true);
+    const headers = validateTokens(options.allowedHeaders ?? defaultHeaders, "header");
+    const exposedHeaders = validateTokens(options.exposedHeaders ?? [], "header");
+    const trustedProxies = new Set((options.trustedProxyAddresses ?? []).map(validateAddress));
+    const maxAge = options.preflightMaxAgeSeconds ?? 600;
+    if (!Number.isSafeInteger(maxAge) || maxAge < 0 || maxAge > 86_400)
+        throw new Error("Invalid CORS max age.");
+    if (options.allowCredentials && origins.size === 0)
+        throw new Error("Credentialed CORS requires allowed origins.");
+    const customHeaders = Object.entries(options.headers ?? {});
+    for (const [name, value] of customHeaders) {
+        validateHeaderName(name);
+        validateHeaderValue(name, value);
+    }
+    const rateLimit = options.rateLimit;
+    if (rateLimit)
+        validateRateLimit(rateLimit);
+    const limiter = rateLimit && !rateLimit.store ? createLimiter(rateLimit) : undefined;
+    const storeTimeoutMs = rateLimit?.storeTimeoutMs ?? 2_000;
+    if (!Number.isSafeInteger(storeTimeoutMs) || storeTimeoutMs < 1)
+        throw new Error("Invalid rate limit store timeout.");
+    const clientAddress = (request) => resolveClientAddress(request, trustedProxies);
+    const applyHeaders = (response) => {
+        response.setHeader("X-Content-Type-Options", "nosniff");
+        response.setHeader("X-Frame-Options", "DENY");
+        response.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+        for (const [name, value] of customHeaders)
+            response.setHeader(name, value);
+    };
+    const processRequest = (request, response, retryAfter) => {
+        applyHeaders(response);
+        if (retryAfter > 0) {
+            response.writeHead(429, {
+                "Content-Type": "application/json; charset=utf-8",
+                "Cache-Control": "no-store",
+                "Retry-After": String(retryAfter),
+            });
+            response.end(JSON.stringify({
+                error: { code: "rate_limit_exceeded", message: "Too many requests." },
+            }));
+            return true;
+        }
+        const origin = request.headers.origin;
+        if (!origins.size || !origin)
+            return false;
+        response.setHeader("Vary", appendVary(response.getHeader("Vary"), "Origin"));
+        if (!origins.has(origin)) {
+            response.writeHead(403, { "Cache-Control": "no-store" });
+            response.end();
+            return true;
+        }
+        response.setHeader("Access-Control-Allow-Origin", origin);
+        if (options.allowCredentials)
+            response.setHeader("Access-Control-Allow-Credentials", "true");
+        if (exposedHeaders.length)
+            response.setHeader("Access-Control-Expose-Headers", exposedHeaders.join(", "));
+        const requestedMethod = request.headers["access-control-request-method"];
+        if (request.method === "OPTIONS" && requestedMethod) {
+            response.setHeader("Vary", appendVary(appendVary(response.getHeader("Vary"), "Access-Control-Request-Method"), "Access-Control-Request-Headers"));
+            const requestedHeaders = (request.headers["access-control-request-headers"] ?? "")
+                .split(",")
+                .map((value) => value.trim())
+                .filter(Boolean);
+            if (!methods.includes(requestedMethod) ||
+                requestedHeaders.some((name) => !headers.some((allowed) => allowed.toLowerCase() === name.toLowerCase()))) {
+                response.writeHead(403, { "Cache-Control": "no-store" });
+                response.end();
+                return true;
+            }
+            response.setHeader("Access-Control-Allow-Methods", methods.join(", "));
+            if (requestedHeaders.length)
+                response.setHeader("Access-Control-Allow-Headers", requestedHeaders.join(", "));
+            response.setHeader("Access-Control-Max-Age", String(maxAge));
+            response.writeHead(204);
+            response.end();
+            return true;
+        }
+        if (!methods.includes(request.method ?? "GET")) {
+            response.writeHead(405, { Allow: methods.join(", ") });
+            response.end();
+            return true;
+        }
+        return false;
+    };
+    const handle = (request, response) => {
+        if (rateLimit?.store)
+            throw new Error("A shared rate limit store requires handleAsync.");
+        return processRequest(request, response, limiter?.(clientAddress(request)) ?? 0);
+    };
+    return {
+        handle,
+        async handleAsync(request, response) {
+            if (!rateLimit?.store)
+                return handle(request, response);
+            applyHeaders(response);
+            let timer;
+            try {
+                const retryAfter = await Promise.race([
+                    Promise.resolve().then(() => rateLimit.store.consume(clientAddress(request), rateLimit.limit, rateLimit.windowMs)),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("Rate limit store timed out.")), storeTimeoutMs);
+                    }),
+                ]);
+                if (!Number.isSafeInteger(retryAfter) || retryAfter < 0)
+                    throw new Error("Invalid rate limit store result.");
+                return processRequest(request, response, retryAfter);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        clientAddress,
+    };
+}
+function resolveClientAddress(request, trustedProxies) {
+    const peer = normalizeAddress(request.socket.remoteAddress ?? "");
+    if (!peer || !trustedProxies.has(peer))
+        return peer || "unknown";
+    const forwarded = request.headers["x-forwarded-for"];
+    if (typeof forwarded !== "string")
+        return peer;
+    const chain = forwarded
+        .split(",")
+        .map((value) => normalizeAddress(value.trim()));
+    if (!chain.length || chain.some((value) => !value))
+        return peer;
+    for (const candidate of chain.reverse()) {
+        if (!trustedProxies.has(candidate))
+            return candidate;
+    }
+    return peer;
+}
+function validateOrigin(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("Invalid allowed origin.");
+    }
+    if (!(["http:", "https:"].includes(parsed.protocol) && parsed.origin === value))
+        throw new Error("Allowed origins must be exact HTTP origins.");
+    return value;
+}
+function validateTokens(values, kind, uppercase = false) {
+    for (const value of values) {
+        if (!value ||
+            (uppercase
+                ? !/^[A-Z]+$/.test(value)
+                : !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(value)))
+            throw new Error(`Invalid CORS ${kind}.`);
+    }
+    return [...new Set(values)];
+}
+function validateAddress(value) {
+    const address = normalizeAddress(value);
+    if (!address)
+        throw new Error("Trusted proxies must use IP addresses.");
+    return address;
+}
+function normalizeAddress(value) {
+    const address = value.toLowerCase().replace(/^::ffff:/, "");
+    return isIP(address) ? address : "";
+}
+function appendVary(existing, value) {
+    const values = (Array.isArray(existing) ? existing.join(",") : String(existing ?? ""))
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (!values.some((item) => item.toLowerCase() === value.toLowerCase()))
+        values.push(value);
+    return values.join(", ");
+}

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

@@ -12,6 +12,16 @@ export declare function createRequestContext(request: IncomingMessage, deadlineA
     abort: (reason?: unknown) => void;
 };
 export declare function writeJsonError(response: ServerResponse, error: unknown, requestId: string): void;
+export type ApiMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ApiRoute {
+    method: ApiMethod;
+    path: string;
+    handler(request: IncomingMessage, response: ServerResponse, context: ReturnType<typeof createRequestContext>, params: Readonly<Record<string, string>>): void | Promise<void>;
+}
+export interface ApiRouteProvider {
+    routes: readonly ApiRoute[];
+}
+export declare function createApiRouter(providers: readonly ApiRouteProvider[]): (request: IncomingMessage, response: ServerResponse, context: ReturnType<typeof createRequestContext>) => void | Promise<void>;
 export declare function parseListQuery(search: URLSearchParams, allowedSorts: readonly string[], defaults?: {
     perPage: number;
     maxPerPage: number;

package/dist/modules/http/http.provider.js

@@ -16,8 +16,12 @@ export class HttpError extends Error {
 export function createRequestContext(request, deadlineAt) {
     const controller = new AbortController();
     request.once("aborted", () => controller.abort());
-    return { requestId: randomUUID(), signal: controller.signal, deadlineAt,
-        abort: (reason) => controller.abort(reason) };
+    return {
+        requestId: randomUUID(),
+        signal: controller.signal,
+        deadlineAt,
+        abort: (reason) => controller.abort(reason),
+    };
 }
 export function writeJsonError(response, error, requestId) {
     if (response.headersSent) {
@@ -26,14 +30,95 @@ export function writeJsonError(response, error, requestId) {
     }
     const known = error instanceof HttpError;
     response.writeHead(known ? error.status : 500, {
-        "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store",
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
         "X-Request-ID": requestId,
     });
-    response.end(JSON.stringify({ error: {
+    response.end(JSON.stringify({
+        error: {
             code: known ? error.code : "internal_error",
             message: known ? error.message : "Unable to complete the request.",
             ...(known && error.fields ? { fields: error.fields } : {}),
-        }, requestId }));
+        },
+        requestId,
+        ...(known && error.status === 422 && error.fields
+            ? { message: error.message, errors: error.fields }
+            : {}),
+    }));
+}
+export function createApiRouter(providers) {
+    const registered = providers
+        .flatMap((provider) => provider.routes)
+        .map(registerRoute);
+    const keys = new Set();
+    for (const entry of registered) {
+        const key = `${entry.route.method} ${entry.segments.map((part) => (part.startsWith(":") ? ":" : part)).join("/")}`;
+        if (keys.has(key))
+            throw new Error(`Duplicate API route: ${entry.route.path}`);
+        keys.add(key);
+    }
+    registered.sort((left, right) => right.staticCount - left.staticCount);
+    return (request, response, context) => {
+        let segments;
+        try {
+            const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+            segments = pathname.split("/").filter(Boolean).map(decodeURIComponent);
+            if (segments.some((part) => part.includes("/") || part.includes("\\")))
+                throw new Error("Encoded path separator.");
+        }
+        catch {
+            throw new HttpError(400, "invalid_url", "Invalid URL.");
+        }
+        const matching = registered
+            .map((entry) => ({ entry, params: matchRoute(entry.segments, segments) }))
+            .filter(({ params }) => params !== undefined);
+        const mostSpecific = matching.filter(({ entry }) => entry.staticCount === matching[0]?.entry.staticCount);
+        const selected = mostSpecific.find(({ entry }) => entry.route.method === request.method);
+        if (selected)
+            return selected.entry.route.handler(request, response, context, selected.params);
+        if (mostSpecific.length) {
+            response.setHeader("Allow", [...new Set(mostSpecific.map(({ entry }) => entry.route.method))].join(", "));
+            throw new HttpError(405, "method_not_allowed", "Method not allowed.");
+        }
+        throw new HttpError(404, "not_found", "Resource not found.");
+    };
+}
+function registerRoute(route) {
+    if (!["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"].includes(route.method) ||
+        typeof route.handler !== "function")
+        throw new Error(`Invalid API route: ${route.path}`);
+    if (!route.path.startsWith("/api/v1/") ||
+        route.path.endsWith("/") ||
+        route.path.includes("?"))
+        throw new Error(`Invalid API route: ${route.path}`);
+    const segments = route.path.split("/").filter(Boolean);
+    for (const part of segments) {
+        if (part.startsWith(":")) {
+            if (!/^:[A-Za-z_][A-Za-z0-9_]*$/.test(part))
+                throw new Error(`Invalid API route: ${route.path}`);
+        }
+        else if (!/^[A-Za-z0-9_-]+$/.test(part)) {
+            throw new Error(`Invalid API route: ${route.path}`);
+        }
+    }
+    return {
+        route,
+        segments,
+        staticCount: segments.filter((part) => !part.startsWith(":")).length,
+    };
+}
+function matchRoute(pattern, path) {
+    if (pattern.length !== path.length)
+        return undefined;
+    const params = Object.create(null);
+    for (let index = 0; index < pattern.length; index++) {
+        const part = pattern[index];
+        if (part.startsWith(":"))
+            params[part.slice(1)] = path[index];
+        else if (part !== path[index])
+            return undefined;
+    }
+    return params;
 }
 export function parseListQuery(search, allowedSorts, defaults = { perPage: 20, maxPerPage: 100 }) {
     const integer = (key, fallback, max) => {
@@ -47,12 +132,19 @@ export function parseListQuery(search, allowedSorts, defaults = { perPage: 20, m
     };
     const sort = search.get("sort") ?? allowedSorts[0];
     const direction = search.get("direction") ?? "asc";
-    if ((sort !== undefined && !allowedSorts.includes(sort)) || !["asc", "desc"].includes(direction)) {
+    if ((sort !== undefined && !allowedSorts.includes(sort)) ||
+        !["asc", "desc"].includes(direction)) {
         throw new HttpError(422, "invalid_query", "Invalid sorting.");
     }
     const page = integer("page", 1, 1_000_000);
     const perPage = integer("per_page", defaults.perPage, defaults.maxPerPage);
-    return { page, perPage, offset: (page - 1) * perPage, sort, direction: direction };
+    return {
+        page,
+        perPage,
+        offset: (page - 1) * perPage,
+        sort,
+        direction: direction,
+    };
 }
 export async function readJsonBody(request, maxBytes = 1_048_576) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)

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

@@ -0,0 +1,22 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogFields = Readonly<Record<string, unknown>>;
+export interface LogRecord {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    requestId?: string;
+    [key: string]: unknown;
+}
+export interface Logger {
+    child(fields: LogFields): Logger;
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+export interface LoggerOptions {
+    level?: LogLevel;
+    sink?: (record: LogRecord) => void;
+    context?: LogFields;
+}
+export declare function createLogger(options?: LoggerOptions): Logger;

package/dist/modules/logger/logger.provider.js

@@ -0,0 +1,88 @@
+const priorities = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const secretField = /(?:secret|password|passwd|token|authorization|cookie|credential|api[-_]?key|private[-_]?key)/i;
+const secretQuery = /([?&](?:access[-_]?token|refresh[-_]?token|client[-_]?secret|token|secret|password|api[-_]?key)=)[^&#\s]*/gi;
+const bearer = /\bBearer\s+[^\s,;]+/gi;
+const urlCredentials = /(\b[a-z][a-z\d+.-]*:\/\/)[^/@\s]+@/gi;
+export function createLogger(options = {}) {
+    const level = options.level ?? "info";
+    if (!(level in priorities))
+        throw new Error("Invalid log level.");
+    const sink = options.sink ?? writeConsoleRecord;
+    return makeLogger(level, sink, options.context ?? {});
+}
+function makeLogger(level, sink, context) {
+    const write = (entryLevel, message, fields = {}) => {
+        if (priorities[entryLevel] < priorities[level])
+            return;
+        const record = redact({
+            ...context,
+            ...fields,
+            timestamp: new Date().toISOString(),
+            level: entryLevel,
+            message,
+        });
+        try {
+            sink(record);
+        }
+        catch {
+            /* Logging failures must not break application work. */
+        }
+    };
+    return {
+        child(fields) {
+            return makeLogger(level, sink, { ...context, ...fields });
+        },
+        debug(message, fields) {
+            write("debug", message, fields);
+        },
+        info(message, fields) {
+            write("info", message, fields);
+        },
+        warn(message, fields) {
+            write("warn", message, fields);
+        },
+        error(message, fields) {
+            write("error", message, fields);
+        },
+    };
+}
+function writeConsoleRecord(record) {
+    const output = JSON.stringify(record);
+    if (record.level === "error")
+        console.error(output);
+    else if (record.level === "warn")
+        console.warn(output);
+    else if (record.level === "debug")
+        console.debug(output);
+    else
+        console.info(output);
+}
+function redact(value, parentKey = "", seen = new WeakSet()) {
+    if (secretField.test(parentKey))
+        return "[REDACTED]";
+    if (typeof value === "string") {
+        return value
+            .replace(bearer, "Bearer [REDACTED]")
+            .replace(urlCredentials, "$1[REDACTED]@")
+            .replace(secretQuery, "$1[REDACTED]");
+    }
+    if (value instanceof Error)
+        return { name: value.name, message: redact(value.message) };
+    if (value instanceof URL)
+        return redact(value.toString());
+    if (typeof value === "bigint")
+        return value.toString();
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[Circular]";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => redact(item, "", seen));
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item, key, seen)]));
+}

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

@@ -1,16 +1,39 @@
 export interface ModuleProvider<T = unknown> {
     name: string;
     dependencies?: readonly string[];
+    token?: ModuleToken<T>;
+    dependencyTokens?: readonly ModuleToken<any>[];
     create(providers: ReadonlyMap<string, unknown>): T;
     start?(provider: T, signal: AbortSignal): void | Promise<void>;
     stop?(provider: T): void | Promise<void>;
 }
+export interface ModuleToken<T> {
+    readonly name: string;
+    readonly key: symbol;
+    readonly valueType?: (value: T) => T;
+}
+type ModuleValues<Tokens extends readonly ModuleToken<any>[]> = {
+    [Index in keyof Tokens]: Tokens[Index] extends ModuleToken<infer Value> ? Value : never;
+};
+export interface TypedModuleDefinition<T, Tokens extends readonly ModuleToken<any>[]> {
+    token: ModuleToken<T>;
+    dependencies: Tokens;
+    create(...providers: ModuleValues<Tokens>): T;
+    start?(provider: T, signal: AbortSignal): void | Promise<void>;
+    stop?(provider: T): void | Promise<void>;
+}
+export declare function createModuleToken<T>(name: string): ModuleToken<T>;
+export declare function defineModuleProvider<T, const Tokens extends readonly ModuleToken<any>[]>(definition: TypedModuleDefinition<T, Tokens>): ModuleProvider<T>;
 export declare function composeModules(modules: readonly ModuleProvider<any>[], options?: {
     startupTimeoutMs?: number;
     shutdownTimeoutMs?: number;
 }): {
     readonly state: "created" | "starting" | "ready" | "stopping" | "stopped" | "failed";
-    get<T>(name: string): T;
+    get: {
+        <T>(token: ModuleToken<T>): T;
+        <T>(name: string): T;
+    };
     start(): Promise<void>;
     stop(): Promise<void>;
 };
+export {};

package/dist/modules/runtime/runtime.provider.js

@@ -1,3 +1,22 @@
+export function createModuleToken(name) {
+    if (!name.trim())
+        throw new Error("A module token needs a name.");
+    return { name, key: Symbol(name) };
+}
+export function defineModuleProvider(definition) {
+    return {
+        name: definition.token.name,
+        token: definition.token,
+        dependencyTokens: definition.dependencies,
+        dependencies: definition.dependencies.map((token) => token.name),
+        create(providers) {
+            const values = definition.dependencies.map((token) => providers.get(token.name));
+            return definition.create(...values);
+        },
+        start: definition.start,
+        stop: definition.stop,
+    };
+}
 export function composeModules(modules, options = {}) {
     const startupTimeoutMs = options.startupTimeoutMs ?? 30_000;
     if (!Number.isSafeInteger(startupTimeoutMs) || startupTimeoutMs < 1)
@@ -9,19 +28,34 @@ export function composeModules(modules, options = {}) {
     if (pending.size !== modules.length)
         throw new Error("Duplicate module name.");
     const providers = new Map();
+    const tokens = new Map();
     const ordered = [];
     while (pending.size) {
         const ready = [...pending.values()].find((module) => (module.dependencies ?? []).every((name) => providers.has(name)));
         if (!ready)
             throw new Error("Missing or cyclic module dependencies.");
+        for (const token of ready.dependencyTokens ?? []) {
+            if (tokens.get(token.name) !== token)
+                throw new Error(`Module contract mismatch: ${token.name}`);
+        }
         const dependencies = new Map((ready.dependencies ?? []).map((name) => [name, providers.get(name)]));
         providers.set(ready.name, ready.create(dependencies));
+        if (ready.token)
+            tokens.set(ready.name, ready.token);
         ordered.push(ready);
         pending.delete(ready.name);
     }
     const started = [];
     let state = "created";
     let cleanupPromise;
+    function get(key) {
+        const name = typeof key === "string" ? key : key.name;
+        if (!providers.has(name))
+            throw new Error(`Unknown module: ${name}`);
+        if (typeof key !== "string" && tokens.get(name) !== key)
+            throw new Error(`Module contract mismatch: ${name}`);
+        return providers.get(name);
+    }
     async function cleanup() {
         state = "stopping";
         const failures = [];
@@ -45,12 +79,10 @@ export function composeModules(modules, options = {}) {
             throw new AggregateError(failures, "Module cleanup failed.");
     }
     return {
-        get state() { return state; },
-        get(name) {
-            if (!providers.has(name))
-                throw new Error(`Unknown module: ${name}`);
-            return providers.get(name);
+        get state() {
+            return state;
         },
+        get,
         async start() {
             if (state !== "created")
                 throw new Error("Modules can only start once.");
@@ -92,9 +124,12 @@ export function composeModules(modules, options = {}) {
 async function withinDeadline(work, milliseconds, name, phase = "shutdown") {
     let timer;
     try {
-        await Promise.race([work, new Promise((_, reject) => {
+        await Promise.race([
+            work,
+            new Promise((_, reject) => {
                 timer = setTimeout(() => reject(new Error(`Module ${phase} deadline exceeded: ${name}`)), milliseconds);
-            })]);
+            }),
+        ]);
     }
     finally {
         clearTimeout(timer);

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

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export interface ValidationProvider {
+    parse<T extends z.ZodType>(schema: T, input: unknown): z.output<T>;
+}
+export declare function createValidationProvider(): ValidationProvider;
+export declare function parseWithSchema<T extends z.ZodType>(schema: T, input: unknown): z.output<T>;

package/dist/modules/validation/validation.provider.js

@@ -0,0 +1,18 @@
+import { HttpError } from "../http/http.provider.js";
+export function createValidationProvider() {
+    return { parse: parseWithSchema };
+}
+export function parseWithSchema(schema, input) {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        const fields = Object.create(null);
+        for (const issue of result.error.issues) {
+            const path = issue.path.length
+                ? issue.path.map(String).join(".")
+                : "_form";
+            (fields[path] ??= []).push(issue.message);
+        }
+        throw new HttpError(422, "validation_failed", "Validation failed", Object.fromEntries(Object.entries(fields)));
+    }
+    return result.data;
+}