@zerotal/core 1.6.2 → 1.7.0

package/src/middleware/SecureHeadersMiddleware.ts

@@ -94,34 +94,65 @@ export class SecureHeadersMiddleware extends BaseMiddleware<SecureHeadersOptions
   async handle(_ctx: HttpContext, next: NextFn): Promise<Response | void> {
     const response = await next();
     if (!response) return;
+    return withHeaders(response, securityHeaders(this.options));
+  }
+}
 
-    const secure: Record<string, string> = {
-      // Always-on security headers
-      "X-Content-Type-Options": "nosniff",
-      "Referrer-Policy": this.options.referrerPolicy ?? "strict-origin-when-cross-origin",
-    };
+/**
+ * The headers this middleware adds, as a plain object.
+ *
+ * Separated from `handle()` because the middleware is not the only thing that
+ * has to send them. Static files are registered with Bun as native
+ * `Response(Bun.file)` routes and are answered without ever entering JavaScript,
+ * so the pipeline — and therefore this middleware — never runs for them. That
+ * left `/css/app.css` served with no `X-Content-Type-Options: nosniff`, which is
+ * precisely the kind of response sniffing protection exists for, while the
+ * framework advertised the header as automatic. {@link Router.static} calls this
+ * so the same set is attached at registration time and Bun still serves the file
+ * natively.
+ *
+ * @param options - Resolved secure-header options, usually `app.secureHeaders`.
+ * @returns Header name → value. Never includes HSTS unless `secure` is set.
+ */
+export function securityHeaders(options: SecureHeadersOptions): Record<string, string> {
+  const secure: Record<string, string> = {
+    // Always-on security headers
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": options.referrerPolicy ?? "strict-origin-when-cross-origin",
+  };
 
-    const frameOptions = this.options.frameOptions ?? "SAMEORIGIN";
-    if (frameOptions) secure["X-Frame-Options"] = frameOptions;
+  const frameOptions = options.frameOptions ?? "SAMEORIGIN";
+  if (frameOptions) secure["X-Frame-Options"] = frameOptions;
 
-    const permissionsPolicy = this.options.permissionsPolicy ?? DEFAULT_PERMISSIONS_POLICY;
-    if (permissionsPolicy) secure["Permissions-Policy"] = permissionsPolicy;
+  const permissionsPolicy = options.permissionsPolicy ?? DEFAULT_PERMISSIONS_POLICY;
+  if (permissionsPolicy) secure["Permissions-Policy"] = permissionsPolicy;
 
-    if (this.options.contentSecurityPolicy) {
-      secure["Content-Security-Policy"] = this.options.contentSecurityPolicy;
-    }
+  if (options.contentSecurityPolicy) {
+    secure["Content-Security-Policy"] = options.contentSecurityPolicy;
+  }
 
-    // HSTS only over HTTPS — emitting it on HTTP can lock users out
-    if (this.options.secure) {
-      const maxAge = this.options.hstsMaxAge ?? 31_536_000;
-      if (maxAge > 0) {
-        const parts = [`max-age=${maxAge}`];
-        if (this.options.hstsIncludeSubDomains !== false) parts.push("includeSubDomains");
-        if (this.options.hstsPreload) parts.push("preload");
-        secure["Strict-Transport-Security"] = parts.join("; ");
-      }
+  // HSTS only over HTTPS — emitting it on HTTP can lock users out
+  if (options.secure) {
+    const maxAge = options.hstsMaxAge ?? 31_536_000;
+    if (maxAge > 0) {
+      const parts = [`max-age=${maxAge}`];
+      if (options.hstsIncludeSubDomains !== false) parts.push("includeSubDomains");
+      if (options.hstsPreload) parts.push("preload");
+      secure["Strict-Transport-Security"] = parts.join("; ");
     }
-
-    return withHeaders(response, secure);
   }
+
+  return secure;
+}
+
+/**
+ * The security headers a static file should carry, read from `app.secureHeaders`.
+ *
+ * A separate entry point from {@link securityHeaders} so the caller does not
+ * have to reach for the config facade itself, and so the fallback is stated in
+ * one place: an app with no `app.secureHeaders` block still gets the baseline,
+ * which is the whole point of the defaults.
+ */
+export function staticSecurityHeaders(): Record<string, string> {
+  return securityHeaders(config.safe("app.secureHeaders", {} as SecureHeadersOptions));
 }

package/src/provider/StorageProvider.ts

@@ -32,7 +32,10 @@ export class StorageProvider extends ServiceProvider {
   }
 
   override async onBooting(): Promise<void> {
-    const storage = await this.app.container.make("storage");
+    // Named explicitly: `make()` infers its type parameter from the token, and a
+    // plain string token infers nothing — so this used to arrive as `unknown`
+    // and reach `StorageFilesMiddleware.with({ storage })` unchecked.
+    const storage = await this.app.container.make<StorageManager>("storage");
 
     const config = this.app.container.makeSync("config") as ConfigManager;
     const storageCfg = config.get<ReturnType<typeof StorageConfig>>("storage", StorageConfig());

package/src/router/RouteHandler.ts

@@ -172,6 +172,11 @@ export async function dispatchRequest(
             durationMs,
             failure instanceof Error ? failure.message : String(failure),
             response!.status,
+            // The class name and the stack alongside the message. A subscriber
+            // rendering a failure has nothing to show without them, and by the
+            // time the event is emitted the error is the only place they exist.
+            failure instanceof Error ? failure.name : undefined,
+            failure instanceof Error ? failure.stack : undefined,
           ),
         );
       } else {

package/src/router/Router.ts

@@ -30,6 +30,7 @@ import { compileDomain, matchDomain, setRequestSubdomains } from "./domain.ts";
 import type { ProviderHooks } from "./RouteHandler.ts";
 import { tryCurrentApp } from "../application/currentApp.ts";
 import { frameworkLog } from "../logger/frameworkLog.ts";
+import { staticSecurityHeaders } from "../middleware/SecureHeadersMiddleware.ts";
 import {
   markdownExtractTitle,
   markdownPage,
@@ -1026,14 +1027,19 @@ export class Router {
         continue;
       }
       const basePrefix = prefix.replace(/\/$/, "");
+      // Static files are handed to Bun as native `Response(Bun.file)` routes and
+      // answered without entering JavaScript, so `SecureHeadersMiddleware` — and
+      // the whole pipeline — never runs for them. The headers are therefore
+      // baked in here instead. Anything the dir declared wins: a caller who set
+      // an explicit `X-Frame-Options` for one mount meant it.
+      const headers = { ...staticSecurityHeaders(), ...options?.headers };
       let registered = 0;
       for (const relativePath of files) {
         const urlPath = `${basePrefix}/${relativePath.replace(/\\/g, "/")}`.replace(/\/+/g, "/");
         if (compiled[urlPath]) continue;
-        const headers = options?.headers;
         compiled[urlPath] = new Response(
           Bun.file(`${rootDir}/${relativePath}`) as unknown as BodyInit,
-          headers ? { headers } : undefined,
+          { headers },
         );
         registered++;
       }

package/src/security/index.ts

@@ -26,3 +26,9 @@ export type { HashAlgorithm } from "../hash/Hash.ts";
 // signing with no secret to manage, `Url.sign` / `Url.verify` on the http subpath is the
 // higher-level option.
 export { URLSigner } from "../crypt/URLSigner.ts";
+// The redaction walk every recorder needs and each had written for itself. Not a
+// policy — callers bring their own markers and their own sensitivity predicate,
+// because an adapter implementing a published protocol does not get to choose
+// its markers and a debug panel does.
+export { redactGraph } from "./redactGraph.ts";
+export type { RedactGraphOptions } from "./redactGraph.ts";

package/src/security/redactGraph.ts

@@ -0,0 +1,98 @@
+/**
+ * One object-graph redaction walk, shared by everything that records a value it
+ * did not choose.
+ *
+ * Several packages need the same thing: copy a value, replace what a key name
+ * says is a secret, and come back with something `JSON.stringify` survives. Each
+ * had written its own — and each had to solve the same three hazards, which are
+ * the parts that are easy to get subtly wrong:
+ *
+ * - **Cycles.** A model holding a back-reference to its parent is ordinary, and
+ *   `JSON.stringify` throws on it. The ancestor set is released on the way back
+ *   *up*, so a value that legitimately appears twice as a sibling is rendered
+ *   twice rather than reported as a cycle the second time.
+ * - **Depth.** Recording happens on the request path, so a pathological graph
+ *   must not stall it.
+ * - **Values that read better flat than walked.** A `Date`, a `File`, an `Error`
+ *   — `Object.entries` on any of them produces something worse than useless.
+ *
+ * What it deliberately does *not* fix is the vocabulary. Callers bring their own
+ * markers and their own sensitivity predicate, because those are not
+ * interchangeable: a devtools panel's `‹redacted›` is a display choice, while an
+ * adapter implementing a published wire protocol has its markers specified for
+ * it. Sharing the walk does not mean agreeing on the words.
+ */
+
+/** How one caller wants the graph walked. */
+export interface RedactGraphOptions {
+  /** Whether the value under this key should be withheld. */
+  sensitive: (key: string) => boolean;
+  /** What a withheld value is replaced with. */
+  mask: string;
+  /** What a reference back to an ancestor is replaced with. */
+  circular: string;
+  /** What a value at or below the depth limit is replaced with. */
+  tooDeep: string;
+  /**
+   * The depth at which the walk stops. The root is depth 0, so `6` renders five
+   * levels of nesting and replaces the sixth.
+   */
+  maxDepth: number;
+  /**
+   * Render a value instead of walking into it — a `Date` as an ISO string, a
+   * `File` as a summary. Return `undefined` to walk it normally.
+   *
+   * Called for every non-null value, before the cycle and depth checks, so a
+   * flattened value is never reported as either — and so a caller can also name
+   * things that are not objects at all. A function is the case worth having:
+   * `JSON.stringify` drops the key it sits under, and a debugging tool that
+   * silently omits a field is worse than one that says `‹fn›`.
+   */
+  flatten?: (value: unknown) => string | undefined;
+}
+
+/**
+ * Copy `value`, masking every field whose name `options.sensitive` rejects.
+ *
+ * A primitive is returned unchanged — there is no key to judge it by, and
+ * inspecting a string's *contents* for things that look like secrets is a
+ * different, guessier job this does not attempt.
+ *
+ * @param value - Anything. Not modified.
+ * @param options - Markers, limits, and the sensitivity predicate.
+ * @returns A new value, safe to serialise.
+ */
+export function redactGraph(value: unknown, options: RedactGraphOptions): unknown {
+  return _walk(value, options, 0, new WeakSet());
+}
+
+function _walk(
+  value: unknown,
+  options: RedactGraphOptions,
+  depth: number,
+  seen: WeakSet<object>,
+): unknown {
+  if (value === null) return null;
+
+  const flat = options.flatten?.(value);
+  if (flat !== undefined) return flat;
+  if (typeof value !== "object") return value;
+
+  const object = value as object;
+  if (seen.has(object)) return options.circular;
+  if (depth >= options.maxDepth) return options.tooDeep;
+
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) {
+      return object.map((item) => _walk(item, options, depth + 1, seen));
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(object as Record<string, unknown>)) {
+      out[key] = options.sensitive(key) ? options.mask : _walk(item, options, depth + 1, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(object);
+  }
+}

package/src/support/deepMerge.ts

@@ -44,6 +44,46 @@
 /** Keys that must never be copied across — they can pollute `Object.prototype`. */
 const _UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+/**
+ * Values {@link deepMerge} treats as atomic: replaced wholesale, never recursed
+ * into. Kept in step with `_isPlainObject` below — a type that recursed into an
+ * array would ask callers for `{ 0?: string }` where the function wants
+ * `string[]`.
+ */
+type _Atomic =
+  | readonly unknown[]
+  | Date
+  | RegExp
+  | Map<unknown, unknown>
+  | Set<unknown>
+  | ((...args: never[]) => unknown);
+
+/**
+ * Every key optional, all the way down — the shape {@link deepMerge} actually
+ * accepts.
+ *
+ * `Partial<T>` only makes the *top* level optional, so
+ * `{ drivers: { anthropic: { apiKey } } }` — the single most common thing anyone
+ * writes in a config file — was a type error against a shape whose `anthropic`
+ * has other keys, even though the merge handles it perfectly. `@zerotal/ai` hit
+ * this first and defined its own copy; this is that type, promoted so nothing
+ * has to define it again.
+ *
+ * The explicit `| undefined` is deliberate under `exactOptionalPropertyTypes`:
+ * `deepMerge` documents that an `undefined` override is skipped rather than
+ * blanking a default, so passing one explicitly has a defined meaning and
+ * should type-check.
+ */
+export type DeepPartial<T> = {
+  [K in keyof T]?:
+    | (NonNullable<T[K]> extends _Atomic
+        ? T[K]
+        : NonNullable<T[K]> extends object
+          ? DeepPartial<NonNullable<T[K]>>
+          : T[K])
+    | undefined;
+};
+
 /**
  * A *plain* object: a `{}`-style record whose prototype is `Object.prototype` or
  * `null`. Class instances, arrays, Dates, Maps, etc. are intentionally excluded so
@@ -96,7 +136,7 @@ function _clone<T>(value: T): T {
  * deepMerge({ tags: ["a", "b"] }, { tags: ["c"] });
  * // → { tags: ["c"] }
  */
-export function deepMerge<T extends object>(base: T, override: Partial<T>): T {
+export function deepMerge<T extends object>(base: T, override: DeepPartial<T>): T {
   const result = _clone(base) as T;
   for (const key in override) {
     if (!Object.prototype.hasOwnProperty.call(override, key)) continue;
@@ -107,7 +147,7 @@ export function deepMerge<T extends object>(base: T, override: Partial<T>): T {
     if (_isPlainObject(overrideValue) && _isPlainObject(baseValue)) {
       (result as Record<string, unknown>)[key] = deepMerge(
         baseValue,
-        overrideValue as Partial<typeof baseValue>,
+        overrideValue as DeepPartial<typeof baseValue>,
       );
     } else {
       (result as Record<string, unknown>)[key] = _clone(overrideValue);

package/src/support/version.ts

@@ -0,0 +1,39 @@
+/**
+ * The framework version this build of `@zerotal/core` is.
+ *
+ * Read from the manifest rather than written down, for the reason `@zerotal/monitor`
+ * already learned: a hardcoded version is correct until the next release, and three
+ * separate literals across the monorepo once claimed a version that had never been
+ * published. The monorepo releases in lockstep, so this package's manifest carries
+ * the framework version, and it ships inside the tarball.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+
+const pkg: { version: string } = JSON.parse(
+  readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+) as { version: string };
+
+/** Full version of the running framework, e.g. `1.6.2`. */
+export const ZEROTAL_VERSION: string = pkg.version;
+
+/**
+ * The version of `@zerotal/core` currently installed in a project, which is not
+ * necessarily {@link ZEROTAL_VERSION} — a long-running process holds the code it
+ * booted with, so an upgrade lands on disk without reaching it.
+ *
+ * @param cwd - Project root to look under.
+ * @returns The installed version, or `null` when there is nothing to read — a
+ *   workspace checkout, a hoisted layout, a partial install. Absence is not a
+ *   finding, so callers stay quiet on `null` rather than guessing.
+ */
+export function installedCoreVersion(cwd: string): string | null {
+  try {
+    const raw = readFileSync(`${cwd}/node_modules/@zerotal/core/package.json`, "utf8");
+    const { version } = JSON.parse(raw) as { version?: string };
+    return version ?? null;
+  } catch {
+    return null;
+  }
+}