@stacksjs/router 0.70.88 → 0.70.90

package/dist/middleware.js

@@ -0,0 +1,23 @@
+export class Middleware {
+  name;
+  priority;
+  handle;
+  constructor(config) {
+    this.name = config.name;
+    this.priority = config.priority ?? 10;
+    this.handle = config.handle;
+  }
+  toRouterHandler() {
+    const handle = this.handle.bind(this);
+    return async (req, next) => {
+      try {
+        await handle(req);
+      } catch (thrown) {
+        if (thrown instanceof Response)
+          return thrown;
+        throw thrown;
+      }
+      return next();
+    };
+  }
+}

package/dist/path-sanitize.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Validate and return a path parameter, throwing if it's unsafe to use
+ * in filesystem interpolation.
+ *
+ * The default contract is single-segment: no `/`, no `\`, no `..`, no
+ * absolute path, no null bytes, no control characters, length ≤ 255.
+ * Pass `allowSlashes: true` for a multi-segment path (still rejects
+ * the rest).
+ *
+ * @throws {PathParamError} when the value fails any check.
+ */
+export declare function sanitizePathParam(value: unknown, options?: SanitizePathParamOptions): string;
+/**
+ * Non-throwing variant. Returns the sanitized value or `null` if any
+ * check failed. Use when you want a fast yes/no in a conditional
+ * without a try/catch around the throw site.
+ */
+export declare function safePathParam(value: unknown, options?: SanitizePathParamOptions): string | null;
+export declare interface SanitizePathParamOptions {
+  context?: string
+  maxLength?: number
+  allowSlashes?: boolean
+}
+/**
+ * Path-parameter sanitization helpers.
+ *
+ * Route params arrive from the URL as untyped strings and are merged
+ * directly into `req.params`. Actions that interpolate those values
+ * into filesystem paths or shell commands without first scrubbing
+ * them are vulnerable to `..`-traversal, absolute-path takeovers, and
+ * null-byte truncation attacks.
+ *
+ * The router itself can't auto-sanitize every param (some are
+ * deliberately path-shaped — file servers, asset proxies, etc.). What
+ * we ship instead is a single canonical helper that callers reach for
+ * at the boundary where the param meets the filesystem.
+ *
+ * See stacksjs/stacks#1870 R-12.
+ *
+ * @example
+ * ```ts
+ * import { sanitizePathParam } from '@stacksjs/router'
+ *
+ * const filename = sanitizePathParam(req.params.filename, {
+ *   context: 'avatar download',
+ * })
+ * return new Response(Bun.file(path.appPath(`avatars/${filename}`)))
+ * ```
+ */
+/**
+ * Reasons {@link sanitizePathParam} rejects a value. Surfaced via the
+ * thrown error so callers can log or branch.
+ */
+export type PathParamRejection = | 'empty'
+  | 'not-string'
+  | 'absolute-path'
+  | 'traversal'
+  | 'null-byte'
+  | 'control-char'
+  | 'too-long';
+export declare class PathParamError extends Error {
+  readonly reason: PathParamRejection;
+  constructor(reason: PathParamRejection, value: unknown, context?: string);
+}

package/dist/path-sanitize.js

@@ -0,0 +1,37 @@
+export class PathParamError extends Error {
+  reason;
+  constructor(reason, value, context) {
+    const ctx = context ? ` in ${context}` : "";
+    super(`[router] Refusing to use ${JSON.stringify(value)} as a path parameter${ctx} \u2014 ${reason}`);
+    this.name = "PathParamError";
+    this.reason = reason;
+  }
+}
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/;
+export function sanitizePathParam(value, options = {}) {
+  if (typeof value !== "string")
+    throw new PathParamError("not-string", value, options.context);
+  if (value.length === 0)
+    throw new PathParamError("empty", value, options.context);
+  const maxLength = options.maxLength ?? 255;
+  if (value.length > maxLength)
+    throw new PathParamError("too-long", value, options.context);
+  if (value.includes("\x00"))
+    throw new PathParamError("null-byte", value, options.context);
+  if (CONTROL_CHARS.test(value))
+    throw new PathParamError("control-char", value, options.context);
+  if (value.startsWith("/") || /^[A-Z]:[\\/]/i.test(value))
+    throw new PathParamError("absolute-path", value, options.context);
+  if (/(^|[\\/])\.\.([\\/]|$)/.test(value))
+    throw new PathParamError("traversal", value, options.context);
+  if (!options.allowSlashes && /[\\/]/.test(value))
+    throw new PathParamError("traversal", value, options.context);
+  return value;
+}
+export function safePathParam(value, options = {}) {
+  try {
+    return sanitizePathParam(value, options);
+  } catch {
+    return null;
+  }
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Check + consume a rate-limit slot for the current scope.
+ *
+ * @example
+ * ```ts
+ * await rateLimit('create-post', 10).per('hour')
+ * await rateLimit('login-attempts', 5, { identity: email }).per('minute')
+ * await rateLimit('expensive-job', 3).over(900) // custom 15-minute ttl
+ * ```
+ */
+export declare function rateLimit(key: string, max: number, options?: { identity?: string }): {
+    /** Run with a string period name (`'minute'`, `'hour'`, …). */
+    per: (period: Period) => Promise<void>
+    /** Run with a numeric ttl in seconds. */
+    over: (ttlSeconds: number) => Promise<void>
+  };
+/**
+ * Read the current bucket state without consuming a slot. Useful for
+ * "you have N attempts remaining" hints in dashboards and pre-flight
+ * checks. Returns `null` if the limiter's storage doesn't expose
+ * `getCount` (the default memory storage does; redis storage may not).
+ */
+export declare function rateLimitStatus(key: string, max: number, windowSeconds: number, options?: { identity?: string }): Promise<{ count: number, limit: number, remaining: number } | null>;
+/**
+ * Drop the bucket for the given key (e.g. after a successful login,
+ * the failed-attempt counter should reset).
+ */
+export declare function clearRateLimit(key: string, max: number, windowSeconds: number, options?: { identity?: string }): Promise<void>;
+declare const PERIOD_SECONDS: {
+  second: 1;
+  minute: 60;
+  hour: 3600;
+  day: unknown
+};
+declare type Period = keyof typeof PERIOD_SECONDS;

package/dist/rate-limit.js

@@ -0,0 +1,73 @@
+import { HttpError } from "@stacksjs/error-handling";
+import { RateLimitError, RateLimiter, defaultIdentity } from "ts-rate-limiter";
+import { getCurrentRequest } from "./request-context";
+const PERIOD_SECONDS = {
+  second: 1,
+  minute: 60,
+  hour: 3600,
+  day: 86400
+}, limiterCache = new Map;
+function getLimiter(max, windowMs) {
+  const cacheKey = `${windowMs}:${max}`;
+  let limiter = limiterCache.get(cacheKey);
+  if (!limiter) {
+    limiter = new RateLimiter({
+      windowMs,
+      maxRequests: max,
+      algorithm: "fixed-window",
+      standardHeaders: !1,
+      legacyHeaders: !1
+    });
+    limiterCache.set(cacheKey, limiter);
+  }
+  return limiter;
+}
+function resolveIdentity(explicit) {
+  if (explicit !== void 0)
+    return explicit;
+  const req = getCurrentRequest();
+  return req ? defaultIdentity(req) : "anon";
+}
+export function rateLimit(key, max, options = {}) {
+  const id = resolveIdentity(options.identity), bucketKey = `${key}:${id}`, run = async (windowMs) => {
+    const limiter = getLimiter(max, windowMs);
+    try {
+      await limiter.enforce(bucketKey);
+    } catch (err) {
+      if (err instanceof RateLimitError)
+        throw Object.assign(new HttpError(429, "Too many requests", {
+          key,
+          max,
+          retryAfter: err.retryAfter
+        }), { headers: err.toHeaders() });
+      throw err;
+    }
+  };
+  return {
+    async per(period) {
+      const seconds = PERIOD_SECONDS[period];
+      if (!seconds)
+        throw Error(`rateLimit().per: unknown period '${period}'`);
+      await run(seconds * 1000);
+    },
+    async over(ttlSeconds) {
+      if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
+        throw Error(`rateLimit().over: ttl must be a positive number, got ${ttlSeconds}`);
+      await run(ttlSeconds * 1000);
+    }
+  };
+}
+export async function rateLimitStatus(key, max, windowSeconds, options = {}) {
+  const id = resolveIdentity(options.identity), bucketKey = `${key}:${id}`, result = await getLimiter(max, windowSeconds * 1000).peek(bucketKey);
+  if (!result)
+    return null;
+  return {
+    count: result.current,
+    limit: result.limit,
+    remaining: Math.max(0, result.limit - result.current)
+  };
+}
+export async function clearRateLimit(key, max, windowSeconds, options = {}) {
+  const id = resolveIdentity(options.identity), bucketKey = `${key}:${id}`;
+  await getLimiter(max, windowSeconds * 1000).reset(bucketKey);
+}

package/dist/request-augmentation.d.ts

@@ -0,0 +1,71 @@
+import type { FileInfo } from '@stacksjs/bun-router';
+/**
+ * Stacks-specific marker fields attached to the request by the
+ * router itself and the framework's default middleware.
+ *
+ * Markers are deliberately prefixed with `_` so they can't collide
+ * with userland keys on the request, and their lifetimes are bounded
+ * by the request's lifetime — they're never persisted.
+ */
+export declare interface StacksRequestMarkers {
+  _corsConfig?: unknown
+  _forceJson?: boolean
+  _skipCsrf?: boolean
+  _compress?: boolean
+  _middlewareParams?: Record<string, string>
+  _requestId?: string
+  _startNs?: bigint
+  _authenticatedUser?: unknown
+  _currentAccessToken?: unknown
+  _bodyParsed?: boolean
+}
+/**
+ * Laravel-style request-input macros that Stacks attaches in
+ * `enhanceRequest` (router/src/stacks-router.ts). These shadow some
+ * of bun-router's `RequestMacroMethods` with Stacks-specific
+ * implementations (more permissive `T = any` generics so action
+ * callers don't have to specify the return type for every read).
+ *
+ * Listed here as part of the augmentation so call sites like
+ * `request.input(key)` type-check without `as any`.
+ */
+export declare interface StacksRequestMacros {
+  input?: <T = unknown>(key: string, defaultValue?: T) => T
+  get?: <T = unknown>(key: string, defaultValue?: T) => T
+  all?: () => Record<string, unknown>
+  only?: <T extends Record<string, unknown>>(keys: string[]) => T
+  except?: <T extends Record<string, unknown>>(keys: string[]) => T
+  has?: (key: string | string[]) => boolean
+  hasAny?: (keys: string[]) => boolean
+  missing?: (key: string) => boolean
+  filled?: (key: string) => boolean
+  integer?: (key: string, defaultValue?: number) => number
+  float?: (key: string, defaultValue?: number) => number
+  boolean?: (key: string, defaultValue?: boolean) => boolean
+  string?: (key: string, defaultValue?: string) => string
+  array?: <T = unknown>(key: string, defaultValue?: T[]) => T[]
+  file?: (key: string) => FileInfo | null
+  files?: (key: string) => FileInfo[]
+  hasFile?: (key: string) => boolean
+  allFiles?: () => Record<string, FileInfo | FileInfo[]>
+  getFiles?: () => Record<string, FileInfo | FileInfo[]>
+  user?: () => Promise<unknown>
+  userToken?: () => Promise<unknown>
+  tokenCan?: (ability: string) => Promise<boolean>
+  tokenCant?: (ability: string) => Promise<boolean>
+  can?: (ability: string, ...args: unknown[]) => Promise<boolean>
+  cannot?: (ability: string, ...args: unknown[]) => Promise<boolean>
+  authorize?: (ability: string, ...args: unknown[]) => Promise<void>
+}
+/**
+ * Union of Stacks markers + macros — useful as a single type alias for
+ * places that previously cast to `any`.
+ */
+export type StacksRequestExtensions = StacksRequestMarkers & StacksRequestMacros;
+declare module '@stacksjs/bun-router' {
+  interface EnhancedRequestextends StacksRequestMarkers  {
+  allFiles?: StacksRequestMacros['allFiles']
+  tokenCan?: StacksRequestMacros['tokenCan']
+  can?: StacksRequestMacros['can']
+}
+}

package/dist/request-context.d.ts

@@ -0,0 +1,82 @@
+import type { EnhancedRequest } from '@stacksjs/bun-router';
+import type { RequestInstance } from '@stacksjs/types';
+/**
+ * Read the active trace id, or `undefined` outside any traced scope.
+ *
+ * Falls back to the request's `_requestId` if no explicit trace was
+ * set so the helper is always useful from an HTTP handler — the router
+ * sets `_requestId` per request, and that value is the implicit trace
+ * for downstream calls until something more specific is configured.
+ */
+export declare function getTraceId(): string | undefined;
+/**
+ * Run `fn` under a fresh trace scope. Used by queue workers and cron
+ * triggers to associate background work with the originating request
+ * (or a synthetic id when there's no parent).
+ *
+ * @example
+ * ```ts
+ * await withTraceId(genId(), async () => {
+ *   await job.handle()
+ * })
+ * ```
+ */
+export declare function withTraceId<T>(id: string, fn: () => T): T;
+/**
+ * Run `fetcher()` once per `key` per request. Subsequent callers within
+ * the same request lifecycle await the cached Promise.
+ *
+ * @example
+ * ```ts
+ * const user = await cacheRequestQuery(`User.find:${id}`, () => User.find(id))
+ * ```
+ */
+export declare function cacheRequestQuery<T>(key: string, fetcher: () => T | Promise<T>): Promise<T>;
+/**
+ * Set the current request context
+ * Called by middleware/router when handling a request
+ */
+export declare function setCurrentRequest(req: EnhancedRequest): void;
+/**
+ * Clear the current request context.
+ *
+ * `setCurrentRequest` uses `AsyncLocalStorage.enterWith`, which mutates the
+ * caller's async scope and never restores it. Call this in test teardown
+ * (`afterEach`) whenever a test body calls `setCurrentRequest`, so the leaked
+ * frame doesn't poison subsequently-collected test files (bun's runner
+ * mis-registers tests when collected on a foreign async frame).
+ */
+export declare function clearCurrentRequest(): void;
+/**
+ * Run a function with a request context
+ * All code executed within the callback will have access to the request
+ */
+export declare function runWithRequest<T>(req: EnhancedRequest, fn: () => T): T;
+/**
+ * Get the current request from context
+ */
+export declare function getCurrentRequest(): EnhancedRequest | undefined;
+/**
+ * Request proxy that provides access to the current request
+ * (Laravel's `request()` helper, but typed).
+ *
+ * The proxy is statically typed as {@link RequestInstance} —
+ * the canonical Stacks-side action-request surface
+ * (stacksjs/stacks#1851 Phase 1). All the macros action handlers
+ * reach for (`all`, `get`, `input`, `cookies`, `param`, `validate`,
+ * `user`, `bearerToken`, …) resolve to their declared types instead
+ * of `any`, eliminating most `(request as any)` casts in action code.
+ *
+ * Runtime is unchanged — the proxy still delegates to whichever
+ * `EnhancedRequest` is in the AsyncLocalStorage slot. The type swap
+ * is API-compatible: every method action code uses on `request`
+ * existed on either type already, but only `RequestInstance` carries
+ * the model-aware / path-aware narrowing.
+ *
+ * Methods worth knowing about:
+ * - `bearerToken()` — Authorization header
+ * - `user()` — authenticated user (async)
+ * - `userToken()` — current access token (async)
+ * - `tokenCan(ability)` / `tokenCant(ability)` — async ability checks
+ */
+export declare const request: RequestInstance;

package/dist/request-context.js

@@ -0,0 +1,78 @@
+import process from "node:process";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { log } from "@stacksjs/logging";
+const REQUEST_STORAGE_KEY = Symbol.for("stacks.router.requestStorage"), requestStorage = globalThis[REQUEST_STORAGE_KEY] ??= new AsyncLocalStorage, TRACE_STORAGE_KEY = Symbol.for("stacks.router.traceStorage"), traceStorage = globalThis[TRACE_STORAGE_KEY] ??= new AsyncLocalStorage;
+export function getTraceId() {
+  const explicit = traceStorage.getStore();
+  if (explicit)
+    return explicit;
+  return requestStorage.getStore()?._requestId;
+}
+export function withTraceId(id, fn) {
+  return traceStorage.run(id, fn);
+}
+const REQUEST_QUERY_CACHE_KEY = Symbol.for("stacks.requestQueryCache");
+function getRequestCache() {
+  const req = requestStorage.getStore();
+  if (!req)
+    return;
+  let cache = req[REQUEST_QUERY_CACHE_KEY];
+  if (!cache) {
+    cache = { map: new Map };
+    req[REQUEST_QUERY_CACHE_KEY] = cache;
+  }
+  return cache;
+}
+export async function cacheRequestQuery(key, fetcher) {
+  const cache = getRequestCache();
+  if (!cache)
+    return fetcher();
+  const existing = cache.map.get(key);
+  if (existing)
+    return existing;
+  const promise = Promise.resolve().then(() => fetcher());
+  cache.map.set(key, promise);
+  promise.catch(() => cache.map.delete(key));
+  return promise;
+}
+export function setCurrentRequest(req) {
+  log.debug(`[request] ${req.method} ${new URL(req.url).pathname}`);
+  requestStorage.enterWith(req);
+}
+export function clearCurrentRequest() {
+  requestStorage.disable();
+}
+export function runWithRequest(req, fn) {
+  return requestStorage.run(req, fn);
+}
+export function getCurrentRequest() {
+  return requestStorage.getStore();
+}
+export const request = new Proxy({}, {
+  get(_target, prop) {
+    const currentRequest = getCurrentRequest();
+    if (!currentRequest) {
+      if (process.env.NODE_ENV !== "production")
+        console.warn(`[RequestContext] Accessing request.${String(prop)} outside of request context`);
+      if (prop === "bearerToken")
+        return () => null;
+      if (prop === "user" || prop === "userToken")
+        return async () => {
+          return;
+        };
+      if (prop === "tokenCan" || prop === "tokenCant")
+        return async () => !1;
+      if (prop === "headers")
+        return new Headers;
+      if (prop === "url")
+        return "";
+      if (prop === "method")
+        return "GET";
+      return;
+    }
+    const value = currentRequest[prop];
+    if (typeof value === "function")
+      return value.bind(currentRequest);
+    return value;
+  }
+});

package/dist/response.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The `response` factory is re-exported from `@stacksjs/bun-router` —
+ * see `./index.ts`'s `export * from '@stacksjs/bun-router'` line. Look
+ * there (or at the bun-router source) for the canonical shape:
+ *
+ *     response.json(data, options?)
+ *     response.text(content, status?, headers?)
+ *     response.xml(content, status?, headers?)
+ *     response.html(content, status?, headers?)
+ *     response.redirect(url, status?)
+ *     response.notFound(message?)
+ *     response.unauthorized(message?)
+ *     response.forbidden(message?)
+ *     response.tooManyRequests(message?, retryAfter?)
+ *     response.success(data?, message?, status?)
+ *     response.error(message, status?, errors?)
+ *     response.paginate(data, { page, perPage, total, path })
+ *     response.download(filePath, filename?, headers?)
+ *     response.streamDownload(generator, filename, options?)
+ *     ...
+ *
+ * Note that bun-router uses *positional* args for status/headers on
+ * `text`/`xml`/`html`/`view` (`text(content, status, headers)`) — NOT
+ * options-object. There used to be a competing `response` defined here
+ * in stacks/router with an options-object shape (`text(content, { status, headers })`).
+ * It was dead code (nothing imported it) but its existence misled
+ * readers and produced runtime crashes when a caller copy-pasted the
+ * wrong shape (e.g. the `response.send()` ghost method). Removed —
+ * use the bun-router factory directly.
+ */
+export {};

package/dist/response.js

@@ -0,0 +1 @@
+export {};

package/dist/route-loader.d.ts

@@ -0,0 +1,5 @@
+import type { RouteRegistry } from './route-types';
+/**
+ * Load all routes from the registry
+ */
+export declare function loadRoutes(registry: RouteRegistry): Promise<void>;

package/dist/route-loader.js

@@ -0,0 +1,72 @@
+import { log } from "@stacksjs/logging";
+import { route } from "./stacks-router";
+const NO_PREFIX_KEYS = ["web"];
+export async function loadRoutes(registry) {
+  for (const [key, definition] of Object.entries(registry)) {
+    const config = normalizeDefinition(definition), prefix = config.prefix !== void 0 ? config.prefix ? config.prefix.startsWith("/") ? config.prefix : `/${config.prefix}` : void 0 : NO_PREFIX_KEYS.includes(key) ? void 0 : `/${key}`, middleware = normalizeMiddleware(config.middleware);
+    log.debug(`[route-loader] Loading: ${config.path} prefix=${prefix || "/"} middleware=[${middleware.join(", ")}]`);
+    try {
+      if (prefix || middleware.length > 0)
+        await route.group({
+          prefix,
+          middleware: middleware.length > 0 ? middleware : void 0
+        }, async () => {
+          await importRouteFile(config.path);
+        });
+      else
+        await importRouteFile(config.path);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`[Routes] Failed to load route file '${config.path}': ${message}`);
+      throw Error(`Route loading failed for '${config.path}': ${message}`);
+    }
+  }
+  await loadFrameworkRoutes();
+}
+async function loadFrameworkRoutes() {
+  if (process.env.STACKS_SKIP_DEFAULT_ROUTES === "1")
+    return;
+  try {
+    const { frameworkPath } = await import("@stacksjs/path"), bootstrapPath = frameworkPath("defaults/bootstrap.ts");
+    if (await Bun.file(bootstrapPath).exists())
+      await import(bootstrapPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("Cannot find module") && !message.includes("MODULE_NOT_FOUND"))
+      console.error(`[Routes] Failed to load framework bootstrap: ${message}`);
+  }
+}
+function assertSafeRouteName(routeName) {
+  if (typeof routeName !== "string" || routeName.length === 0)
+    throw Error("[route-loader] Invalid route path: empty or non-string");
+  if (routeName.includes("\x00"))
+    throw Error("[route-loader] Invalid route path: null byte");
+  let decoded;
+  try {
+    decoded = decodeURIComponent(routeName);
+  } catch {
+    throw Error("[route-loader] Invalid route path: malformed URL encoding");
+  }
+  const cleanPath = decoded.replace(/\.ts$/, "");
+  if (cleanPath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(cleanPath))
+    throw Error(`[route-loader] Invalid route path: absolute paths not allowed (${cleanPath})`);
+  if (cleanPath.split(/[/\\]/).some((s) => s === ".."))
+    throw Error(`[route-loader] Invalid route path: '..' segment not allowed (${cleanPath})`);
+  return cleanPath;
+}
+async function importRouteFile(routeName) {
+  const cleanPath = assertSafeRouteName(routeName), { projectPath } = await import("@stacksjs/path");
+  await import(projectPath(`routes/${cleanPath}`));
+}
+function normalizeDefinition(def) {
+  if (typeof def === "string")
+    return { path: def };
+  return def;
+}
+function normalizeMiddleware(middleware) {
+  if (!middleware)
+    return [];
+  if (typeof middleware === "string")
+    return [middleware];
+  return middleware;
+}

package/dist/route-types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Route registry types — owned by `@stacksjs/router` because the router
+ * consumes them. `app/Routes.ts` (the project-level route map) imports
+ * these via the public package name rather than a relative reach into
+ * the framework defaults tree (stacksjs/stacks#1863, T-10).
+ */
+export declare interface RouteDefinition {
+  path: string
+  prefix?: string
+  middleware?: string | string[]
+}
+export type RouteRegistry = Record<string, string | RouteDefinition>;

package/dist/security-headers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Apply the default security headers to a Headers instance in-place.
+ *
+ * Headers applied unconditionally (cheap, no compat risk):
+ * - `X-Content-Type-Options: nosniff` — blocks MIME-sniff XSS
+ * - `X-Frame-Options: SAMEORIGIN` — clickjacking protection (CSP
+ *   `frame-ancestors` is the modern equivalent but XFO still ships)
+ * - `Referrer-Policy: strict-origin-when-cross-origin` — modern default
+ *
+ * Production-only:
+ * - `Strict-Transport-Security: max-age=31536000; includeSubDomains` —
+ *   tells browsers to commit to HTTPS for a year. Omits `preload` since
+ *   that's an irreversible commitment to the browser preload list.
+ *
+ * Skips overwriting any header that's already set — explicit userland
+ * config wins. Skips entirely when `STACKS_SECURITY_HEADERS_DISABLE=true`.
+ */
+export declare function applySecurityHeaders(headers: Headers): void;
+/** Test helper — reset the cached env-derived flags. */
+export declare function __resetSecurityHeadersCache(): void;

package/dist/security-headers.js

@@ -0,0 +1,46 @@
+import process from "node:process";
+let _isProductionCache, _isDisabledCache, _cspCache;
+function isProduction() {
+  if (_isProductionCache !== void 0)
+    return _isProductionCache;
+  _isProductionCache = (process.env.APP_ENV ?? process.env.NODE_ENV ?? "").toLowerCase() === "production";
+  return _isProductionCache;
+}
+function isDisabled() {
+  if (_isDisabledCache !== void 0)
+    return _isDisabledCache;
+  _isDisabledCache = process.env.STACKS_SECURITY_HEADERS_DISABLE === "true";
+  return _isDisabledCache;
+}
+function resolveCsp() {
+  if (_cspCache !== void 0)
+    return _cspCache;
+  const enforce = process.env.STACKS_CSP, report = process.env.STACKS_CSP_REPORT_ONLY;
+  if (enforce)
+    _cspCache = { header: "Content-Security-Policy", value: enforce };
+  else if (report)
+    _cspCache = { header: "Content-Security-Policy-Report-Only", value: report };
+  else
+    _cspCache = null;
+  return _cspCache;
+}
+export function applySecurityHeaders(headers) {
+  if (isDisabled())
+    return;
+  if (!headers.has("X-Content-Type-Options"))
+    headers.set("X-Content-Type-Options", "nosniff");
+  if (!headers.has("X-Frame-Options"))
+    headers.set("X-Frame-Options", "SAMEORIGIN");
+  if (!headers.has("Referrer-Policy"))
+    headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+  if (isProduction() && !headers.has("Strict-Transport-Security"))
+    headers.set("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  const csp = resolveCsp();
+  if (csp && !headers.has(csp.header))
+    headers.set(csp.header, csp.value);
+}
+export function __resetSecurityHeadersCache() {
+  _isProductionCache = void 0;
+  _isDisabledCache = void 0;
+  _cspCache = void 0;
+}