bazis 0.96.1

package/core/http/Middleware/accessLog.ts

@@ -0,0 +1,90 @@
+import { REQUEST_ID_STATE_KEY, type Logger } from "../../kernel";
+import type { HttpContext } from "../HttpContext/HttpContext";
+import type { HttpMiddleware } from "./types";
+import { redactSensitive } from "../../../library/redaction";
+
+export interface AccessLogEntry {
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+  /** Wall-clock time spent in the pipeline, in milliseconds. */
+  readonly durationMs: number;
+  /** Correlation id from {@link createCorrelationIdMiddleware}, if present. */
+  readonly requestId?: string;
+}
+
+export interface AccessLogOptions {
+  /** Sink for entries (highest precedence). Default: structured `logger`, else stdout. */
+  readonly log?: (entry: AccessLogEntry) => void;
+  /** Structured sink: `logger.info` per request. Used when `log` is absent. */
+  readonly logger?: Logger;
+  /** Return `true` to skip logging a request (e.g. noisy probes). */
+  readonly skip?: (ctx: HttpContext) => boolean;
+}
+
+function defaultLog(entry: AccessLogEntry): void {
+  const requestId = entry.requestId ? ` ${entry.requestId}` : "";
+  console.log(`[http] ${entry.method} ${entry.path} ${entry.status} ${entry.durationMs.toFixed(1)}ms${requestId}`);
+}
+
+function resolveSink(options: AccessLogOptions): (entry: AccessLogEntry) => void {
+  if (options.log) {
+    return options.log;
+  }
+  const logger = options.logger;
+  if (logger) {
+    return (entry) =>
+      logger.info(
+        `${entry.method} ${entry.path} ${entry.status} ${entry.durationMs.toFixed(1)}ms`,
+        {
+          method: entry.method,
+          path: entry.path,
+          status: entry.status,
+          durationMs: entry.durationMs,
+          ...(entry.requestId !== undefined ? { requestId: entry.requestId } : {}),
+        },
+      );
+  }
+  return defaultLog;
+}
+
+/**
+ * Access log middleware: records method, path, final status and duration for
+ * every request. The correlation id is read from `ctx.state` (set by
+ * {@link createCorrelationIdMiddleware}), so it is captured regardless of the
+ * order relative to the correlation middleware.
+ *
+ * Install it outermost (the server does this automatically for
+ * `httpModule({ accessLog })`) so it measures the whole pipeline and observes
+ * the final status, including errors mapped by the error boundary.
+ */
+export function accessLog(options: AccessLogOptions = {}): HttpMiddleware {
+  const log = resolveSink(options);
+  const skip = options.skip;
+  return async (ctx, next) => {
+    const startedAt = performance.now();
+    try {
+      await next();
+    } finally {
+      try {
+        if (!skip?.(ctx)) {
+          const requestId = ctx.state.get(REQUEST_ID_STATE_KEY);
+          log({
+            method: ctx.method,
+            path: ctx.path,
+            status: ctx.response?.status ?? 0,
+            durationMs: performance.now() - startedAt,
+            ...(typeof requestId === "string" ? { requestId } : {}),
+          });
+        }
+      } catch (error) {
+        // Observability must never replace an application response.
+        try {
+          console.error("[http] access log sink failed:", redactSensitive(error));
+        } catch {
+          // Even the fallback console may be replaced by application code.
+        }
+      }
+    }
+  };
+}

package/core/http/Middleware/cors.ts

@@ -0,0 +1,160 @@
+import type { HttpMiddleware } from "./types";
+import { HttpSetupError } from "../Errors/HttpError";
+import { redactSensitive } from "../../../library/redaction";
+
+export interface CorsOptions {
+  /**
+   * Allowed origins: exact string, list, predicate, or "*" (default).
+   * `credentials: true` requires an explicit allow-list or predicate.
+   */
+  origin?: string | readonly string[] | ((origin: string) => boolean);
+  /** Allowed methods for preflight (default: common verbs). */
+  methods?: readonly string[];
+  /** Allowed request headers for preflight (default: echo requested headers). */
+  allowedHeaders?: readonly string[];
+  /** Headers exposed to the browser. */
+  exposedHeaders?: readonly string[];
+  /** Allow cookies/credentials. */
+  credentials?: boolean;
+  /** Preflight cache time (Access-Control-Max-Age). */
+  maxAgeSeconds?: number;
+}
+
+const DEFAULT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"] as const;
+
+function assertSafeCorsOptions(options: CorsOptions): void {
+  if (!options.credentials) {
+    return;
+  }
+  const { origin } = options;
+  const allowsWildcard = origin === undefined || origin === "*" || (Array.isArray(origin) && origin.includes("*"));
+  if (allowsWildcard) {
+    throw new HttpSetupError(
+      "CORS credentials require an explicit origin allow-list or predicate. " +
+        "Do not combine credentials: true with omitted origin or '*'.",
+    );
+  }
+}
+
+function resolveOrigin(options: CorsOptions, requestOrigin: string): string | undefined {
+  const { origin } = options;
+  if (origin === undefined || origin === "*") {
+    return options.credentials ? requestOrigin : "*";
+  }
+  if (typeof origin === "string") {
+    return origin === requestOrigin ? requestOrigin : undefined;
+  }
+  if (typeof origin === "function") {
+    return origin(requestOrigin) ? requestOrigin : undefined;
+  }
+  if (origin.includes("*")) {
+    return "*";
+  }
+  return origin.includes(requestOrigin) ? requestOrigin : undefined;
+}
+
+function variesByOrigin(options: CorsOptions): boolean {
+  const origin = options.origin;
+  return origin !== undefined && origin !== "*" && !(Array.isArray(origin) && origin.includes("*"));
+}
+
+function applyCommonHeaders(headers: Headers, options: CorsOptions, allowedOrigin: string): void {
+  headers.set("access-control-allow-origin", allowedOrigin);
+  if (allowedOrigin !== "*") {
+    appendVaryOrigin(headers);
+  }
+  if (options.credentials) {
+    headers.set("access-control-allow-credentials", "true");
+  }
+  if (options.exposedHeaders?.length) {
+    headers.set("access-control-expose-headers", options.exposedHeaders.join(", "));
+  }
+}
+
+function appendVaryOrigin(headers: Headers): void {
+  const vary = headers.get("vary");
+  if (vary === null) {
+    headers.set("vary", "Origin");
+    return;
+  }
+  if (!vary.toLowerCase().split(",").map((item) => item.trim()).includes("origin")) {
+    headers.append("vary", "Origin");
+  }
+}
+
+/**
+ * Is this request a CORS preflight (OPTIONS + Access-Control-Request-Method)?
+ * Preflights are answered by the server before routing, so they work even
+ * for routes that do not declare an OPTIONS handler.
+ */
+export function isPreflight(request: Request): boolean {
+  return request.method === "OPTIONS" && request.headers.has("access-control-request-method");
+}
+
+/** Builds the preflight response (204 with the negotiated CORS headers). */
+export function preflightResponse(options: CorsOptions, request: Request): Response {
+  assertSafeCorsOptions(options);
+  const requestOrigin = request.headers.get("origin");
+  const headers = new Headers();
+  if (variesByOrigin(options)) {
+    appendVaryOrigin(headers);
+  }
+  if (requestOrigin) {
+    const allowedOrigin = resolveOrigin(options, requestOrigin);
+    if (allowedOrigin) {
+      applyCommonHeaders(headers, options, allowedOrigin);
+      headers.set("access-control-allow-methods", (options.methods ?? DEFAULT_METHODS).join(", "));
+      const requestedHeaders = request.headers.get("access-control-request-headers");
+      const allowHeaders = options.allowedHeaders?.join(", ") ?? requestedHeaders;
+      if (allowHeaders) {
+        headers.set("access-control-allow-headers", allowHeaders);
+      }
+      if (options.maxAgeSeconds !== undefined) {
+        headers.set("access-control-max-age", String(options.maxAgeSeconds));
+      }
+    }
+  }
+  return new Response(null, { status: 204, headers });
+}
+
+/**
+ * CORS middleware: adds response headers for cross-origin requests.
+ * Use globally via `httpModule({ cors })` (which also answers preflights)
+ * or per controller/route via `@Middleware(cors({...}))`.
+ */
+export function cors(options: CorsOptions = {}): HttpMiddleware {
+  assertSafeCorsOptions(options);
+  return async (ctx, next) => {
+    await next();
+    const requestOrigin = ctx.header("origin");
+    if (!ctx.response) {
+      return;
+    }
+    try {
+      // The representation depends on Origin even when this particular origin
+      // is absent or denied, so shared caches must always vary on it.
+      const varies = variesByOrigin(options);
+      if (varies) {
+        appendVaryOrigin(ctx.response.headers);
+      }
+      if (!requestOrigin && varies) {
+        return;
+      }
+      // A wildcard policy is truly invariant: emit its headers even without
+      // Origin, so a cached same-origin response also works for a CORS caller.
+      const allowedOrigin = requestOrigin ? resolveOrigin(options, requestOrigin) : "*";
+      if (allowedOrigin) {
+        applyCommonHeaders(ctx.response.headers, options, allowedOrigin);
+      }
+    } catch (error) {
+      // CORS is response decoration, not authorization. A buggy predicate or
+      // immutable raw response must not expose Bun's development error page or
+      // replace an otherwise valid response.
+      try {
+        console.error("[http] CORS evaluation failed:", redactSensitive(error));
+      } catch {
+        // Best-effort diagnostics only.
+      }
+    }
+  };
+}

package/core/http/Middleware/errorHandler.ts

@@ -0,0 +1,100 @@
+import { redactSensitive } from "../../../library/redaction";
+import type { HttpContext } from "../HttpContext/HttpContext";
+import { HttpError } from "../Errors/HttpError";
+import type { HttpMiddleware } from "./types";
+
+export interface ErrorHandlerOptions {
+  /**
+   * Include the error message and stack in 500 responses (development only —
+   * never enable in production).
+   */
+  exposeDetails?: boolean;
+  /** Called for non-{@link HttpError} failures (self-wired via `HTTP_ERROR_HOOK`, e.g. the logging module). */
+  onUnexpectedError?: (ctx: HttpContext, error: unknown) => void;
+  /** Fallback when {@link onUnexpectedError} is omitted or does not handle the error. */
+  logError?: (error: unknown) => void;
+}
+
+function jsonResponse(status: number, body: unknown, extraHeaders?: readonly [string, string][]): Response {
+  const headers = new Headers({ "content-type": "application/json; charset=utf-8" });
+  if (extraHeaders) {
+    for (const [name, value] of extraHeaders) {
+      headers.set(name, value);
+    }
+  }
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+function safeJsonResponse(status: number, body: unknown, extraHeaders?: readonly [string, string][]): Response {
+  try {
+    return jsonResponse(status, body, extraHeaders);
+  } catch {
+    return jsonResponse(500, { error: "Internal Server Error" });
+  }
+}
+
+function safelyReportUnexpected(
+  options: ErrorHandlerOptions,
+  fallback: (error: unknown) => void,
+  ctx: HttpContext,
+  error: unknown,
+): void {
+  try {
+    options.onUnexpectedError?.(ctx, error);
+  } catch (hookError) {
+    try {
+      fallback(hookError);
+    } catch {
+      // Logging hooks are best-effort; response safety is primary.
+    }
+  }
+  try {
+    fallback(error);
+  } catch {
+    // A broken sink must not escape the HTTP error boundary.
+  }
+}
+
+/**
+ * Built-in error boundary (always installed by the server). `HttpError` maps
+ * to its status with a safe JSON payload; anything
+ * else becomes 500 Internal Server Error.
+ */
+export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware {
+  const fallback = options.logError ?? ((error: unknown) => console.error("[http] unhandled error:", redactSensitive(error)));
+  return async (ctx, next) => {
+    try {
+      await next();
+    } catch (error) {
+      if (error instanceof HttpError) {
+        const extra: [string, string][] = [];
+        const allow = (error as { allow?: readonly string[] }).allow;
+        if (allow) {
+          extra.push(["allow", allow.join(", ")]);
+        }
+        const retryAfter = (error as { retryAfterSeconds?: number }).retryAfterSeconds;
+        if (retryAfter !== undefined) {
+          extra.push(["retry-after", String(retryAfter)]);
+        }
+        const challenge = (error as { challenge?: string }).challenge;
+        if (challenge !== undefined) {
+          extra.push(["www-authenticate", challenge]);
+        }
+        ctx.response = safeJsonResponse(
+          error.status,
+          error.details === undefined ? { error: error.message } : { error: error.message, details: error.details },
+          extra,
+        );
+        return;
+      }
+      safelyReportUnexpected(options, fallback, ctx, error);
+      ctx.response = options.exposeDetails
+        ? safeJsonResponse(500, {
+            error: "Internal Server Error",
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+          })
+        : safeJsonResponse(500, { error: "Internal Server Error" });
+    }
+  };
+}

package/core/http/Middleware/pipeline.ts

@@ -0,0 +1,21 @@
+import type { HttpContext } from "../HttpContext/HttpContext";
+import type { HttpMiddleware } from "./types";
+
+/**
+ * Runs a precompiled middleware chain. The chain array is built once per
+ * route at startup; per request we only allocate the dispatch closure.
+ */
+export function runPipeline(chain: readonly HttpMiddleware[], ctx: HttpContext): Promise<void> {
+  let lastIndex = -1;
+  const dispatch = async (index: number): Promise<void> => {
+    if (index <= lastIndex) {
+      throw new Error("next() called multiple times in the same middleware");
+    }
+    lastIndex = index;
+    const middleware = chain[index];
+    if (middleware) {
+      await middleware(ctx, () => dispatch(index + 1));
+    }
+  };
+  return dispatch(0);
+}

package/core/http/Middleware/rateLimit.ts

@@ -0,0 +1,104 @@
+import { TooManyRequestsError } from "../Errors/HttpError";
+import type { HttpContext } from "../HttpContext/HttpContext";
+import type { HttpMiddleware } from "./types";
+import { HttpSetupError } from "../Errors/HttpError";
+
+export interface RateLimitOptions {
+  /** Window size in milliseconds. */
+  windowMs: number;
+  /** Max requests per key per window. */
+  max: number;
+  /**
+   * Request key (default: Bun's direct peer IP, falling back to a single shared
+   * bucket when unavailable). Plug your own: user id, API key, etc.
+   */
+  keyOf?: (ctx: HttpContext) => string;
+  /** Trust the first `X-Forwarded-For` hop. Off by default. */
+  trustProxy?: boolean;
+  /** Forwarded client-address header used when `trustProxy` is true. */
+  proxyHeader?: string;
+  /** Hard cap for in-process buckets. New keys receive 429 when full. Default: 10,000. */
+  maxBuckets?: number;
+}
+
+interface Bucket {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * Fixed-window in-memory rate limiter. Per-process state (no external
+ * store) — suitable for a single binary; swap `keyOf` or wrap your own
+ * middleware for distributed setups. Exceeding the limit throws 429 with
+ * Retry-After. At capacity, new keys are rejected until a bucket expires;
+ * existing keys retain their quota and live buckets are never evicted.
+ */
+export function rateLimit(options: RateLimitOptions): HttpMiddleware {
+  assertRateLimitOptions(options);
+  const buckets = new Map<string, Bucket>();
+  const maxBuckets = Math.floor(options.maxBuckets ?? 10_000);
+  let nextExpiry = Number.POSITIVE_INFINITY;
+  const proxyHeader = options.proxyHeader ?? "x-forwarded-for";
+  const keyOf = options.keyOf ?? ((ctx: HttpContext) => {
+    if (options.trustProxy) {
+      const forwarded = ctx.header(proxyHeader)?.split(",", 1)[0]?.trim();
+      if (forwarded) {
+        return forwarded;
+      }
+    }
+    return ctx.clientIp ?? "*";
+  });
+
+  return async (ctx, next) => {
+    const now = Date.now();
+    const key = keyOf(ctx);
+    let bucket = buckets.get(key);
+    if (bucket && bucket.resetAt <= now) {
+      buckets.delete(key);
+      bucket = undefined;
+    }
+    if (!bucket) {
+      // Avoid scanning a full table for every unknown key under saturation.
+      // This lower bound may be stale after a known key renews its own window;
+      // a single scan refreshes it without discarding any active quota.
+      if (buckets.size >= maxBuckets && now >= nextExpiry) {
+        nextExpiry = purgeExpired(buckets, now);
+      }
+      if (buckets.size >= maxBuckets) {
+        throw new TooManyRequestsError(Math.ceil((nextExpiry - now) / 1000));
+      }
+      bucket = { count: 0, resetAt: now + options.windowMs };
+      buckets.set(key, bucket);
+      nextExpiry = Math.min(nextExpiry, bucket.resetAt);
+    }
+    if (bucket.count >= options.max) {
+      throw new TooManyRequestsError(Math.ceil((bucket.resetAt - now) / 1000));
+    }
+    bucket.count += 1;
+    await next();
+  };
+}
+
+function assertRateLimitOptions(options: RateLimitOptions): void {
+  if (!Number.isFinite(options.windowMs) || options.windowMs <= 0) {
+    throw new HttpSetupError("rateLimit windowMs must be a positive finite number.");
+  }
+  if (!Number.isSafeInteger(options.max) || options.max <= 0) {
+    throw new HttpSetupError("rateLimit max must be a positive integer.");
+  }
+  if (options.maxBuckets !== undefined && (!Number.isSafeInteger(options.maxBuckets) || options.maxBuckets <= 0)) {
+    throw new HttpSetupError("rateLimit maxBuckets must be a positive integer.");
+  }
+}
+
+function purgeExpired(buckets: Map<string, Bucket>, now: number): number {
+  let nextExpiry = Number.POSITIVE_INFINITY;
+  for (const [key, bucket] of buckets) {
+    if (bucket.resetAt <= now) {
+      buckets.delete(key);
+    } else {
+      nextExpiry = Math.min(nextExpiry, bucket.resetAt);
+    }
+  }
+  return nextExpiry;
+}

package/core/http/Middleware/securityHeaders.ts

@@ -0,0 +1,118 @@
+import type { HttpMiddleware } from "./types";
+import { redactSensitive } from "../../../library/redaction";
+
+/** `Strict-Transport-Security` tuning (only meaningful over HTTPS). */
+export interface HstsOptions {
+  /** max-age in seconds. Default: 15552000 (180 days). */
+  readonly maxAgeSeconds?: number;
+  /** Append `includeSubDomains`. Default: true. */
+  readonly includeSubDomains?: boolean;
+  /** Append `preload`. Default: false. */
+  readonly preload?: boolean;
+}
+
+export interface SecurityHeadersOptions {
+  /** `X-Content-Type-Options: nosniff`. Default: true. */
+  readonly contentTypeOptions?: boolean;
+  /** `X-Frame-Options`. Default: "DENY". `false` omits it. */
+  readonly frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  /** `Referrer-Policy`. Default: "no-referrer". `false` omits it. */
+  readonly referrerPolicy?: string | false;
+  /** `X-DNS-Prefetch-Control`. Default: "off". `false` omits it. */
+  readonly dnsPrefetchControl?: "off" | "on" | false;
+  /**
+   * `Strict-Transport-Security`. Default: off (apps are often behind TLS
+   * terminators and dev runs on HTTP). Pass `true` for sane defaults or an
+   * object to tune. Never sent unless explicitly enabled.
+   */
+  readonly hsts?: HstsOptions | boolean;
+  /**
+   * `Content-Security-Policy`. Default: off (a wrong CSP breaks apps). Provide
+   * a policy string to enable.
+   */
+  readonly contentSecurityPolicy?: string;
+  /** Extra headers to set (set-if-absent), e.g. a custom `Permissions-Policy`. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+function buildHeaders(options: SecurityHeadersOptions): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  if (options.contentTypeOptions !== false) {
+    headers["x-content-type-options"] = "nosniff";
+  }
+  if (options.frameOptions !== false) {
+    headers["x-frame-options"] = options.frameOptions ?? "DENY";
+  }
+  if (options.referrerPolicy !== false) {
+    headers["referrer-policy"] = options.referrerPolicy ?? "no-referrer";
+  }
+  if (options.dnsPrefetchControl !== false) {
+    headers["x-dns-prefetch-control"] = options.dnsPrefetchControl ?? "off";
+  }
+  if (options.hsts) {
+    const hsts: HstsOptions = options.hsts === true ? {} : options.hsts;
+    const parts = [`max-age=${hsts.maxAgeSeconds ?? 15_552_000}`];
+    if (hsts.includeSubDomains !== false) {
+      parts.push("includeSubDomains");
+    }
+    if (hsts.preload) {
+      parts.push("preload");
+    }
+    headers["strict-transport-security"] = parts.join("; ");
+  }
+  if (options.contentSecurityPolicy) {
+    headers["content-security-policy"] = options.contentSecurityPolicy;
+  }
+  if (options.headers) {
+    for (const [name, value] of Object.entries(options.headers)) {
+      headers[name.toLowerCase()] = value;
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * Sets conservative security response headers (secure-by-default): `nosniff`,
+ * `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, DNS-prefetch off.
+ * HSTS and CSP are opt-in (a wrong value breaks real apps). Headers are written
+ * set-if-absent, so a route that sets its own value wins.
+ *
+ * Installed automatically by `httpModule` unless `securityHeaders: false`.
+ */
+export function securityHeaders(options: SecurityHeadersOptions = {}): HttpMiddleware {
+  const headers = buildHeaders(options);
+  return async (ctx, next) => {
+    await next();
+    const response = ctx.response;
+    if (!response) {
+      return;
+    }
+    applySecurityHeaders(response, options, headers);
+  };
+}
+
+/** Applies the configured defaults to a response without throwing. */
+export function applySecurityHeaders(
+  response: Response,
+  options: SecurityHeadersOptions = {},
+  prepared: Record<string, string> = buildHeaders(options),
+): Response {
+  try {
+    for (const [name, value] of Object.entries(prepared)) {
+      if (!response.headers.has(name)) {
+        response.headers.set(name, value);
+      }
+    }
+  } catch (error) {
+    // A raw/foreign Response may expose immutable headers. Keep the original
+    // response rather than allowing response decoration to become a bare 500.
+    try {
+      console.error("[http] security header decoration failed:", redactSensitive(error));
+    } catch {
+      // Best-effort diagnostics only.
+    }
+  }
+  return response;
+}

package/core/http/Middleware/types.ts

@@ -0,0 +1,19 @@
+import type { HttpContext } from "../HttpContext/HttpContext";
+
+/**
+ * Middleware signature (Koa/ASP.NET Core style): do work, call `next()` to
+ * pass control down the pipeline, optionally short-circuit by setting
+ * `ctx.response` without calling `next`.
+ */
+export type HttpMiddleware = (ctx: HttpContext, next: () => Promise<void>) => void | Promise<void>;
+
+/**
+ * Action filter (`@ActionFilter`): `before` is an action-boundary policy and
+ * therefore also runs before a short-circuiting output cache hit. `after`
+ * wraps an actual action invocation and may replace its result by returning a
+ * non-undefined value.
+ */
+export interface ActionFilterHooks {
+  before?(ctx: HttpContext): void | Promise<void>;
+  after?(ctx: HttpContext, result: unknown): unknown | Promise<unknown>;
+}