@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.1

package/src/utils/fs.ts

@@ -15,7 +15,7 @@ import { gzip as zlibGzip } from 'node:zlib'
 import { LRUCache } from '../cache/lru'
 // A cycle on paper (`core/context` imports this file for `getAppVersion`),
 // harmless in practice: neither module touches the other's bindings during
-// evaluation — `hostStore` is only read inside `isForbidden`, at request time.
+// evaluation. `hostStore` is only read inside `isForbidden`, at request time.
 import { hostStore } from '../core/context'
 import type { MixedPromise } from '../types'
 import { is, Try } from './common'
@@ -42,7 +42,7 @@ const gzipAsync = promisify(zlibGzip) as (
  *   1MB   |   5804us  |    6480us  |  14469us  |  17114us
  *   (32KB gzip: median of 5 x 200-iteration runs; single runs were noisy)
  *
- * At 32KB the sync cost crosses the dispatch overhead for zstd — the
+ * At 32KB the sync cost crosses the dispatch overhead for zstd, the
  * first-preference codec. gzip's raw-latency break-even sits nearer 64KB,
  * but the sync figure is a *stall* shared by every concurrent request while
  * the async figure is latency private to one caller, so the tie goes to
@@ -54,8 +54,8 @@ export const ASYNC_COMPRESSION_MIN = 32 * 1024
  * `compress` is the sync variant (blocks the event loop for the durations
  * above); `compressAsync` runs on a worker pool and only parks the caller.
  * zstd: `Bun.zstdCompress` (native async, Bun >= 1.1.21). gzip: Bun 1.3.14
- * has no async `Bun.gzip`, so `node:zlib`'s callback `gzip` — which runs on
- * the libuv pool — is promisified instead. Both async variants were verified
+ * has no async `Bun.gzip`, so `node:zlib`'s callback `gzip` (which runs on
+ * the libuv pool) is promisified instead. Both async variants were verified
  * byte-identical to their sync counterparts on this Bun, so either path
  * yields the same cached artifacts and the same response bodies.
  */
@@ -82,13 +82,13 @@ function toArray<T>(val?: MixedArray<T>): T[] {
 }
 
 /**
- * Memoised: `resolve` measures ~16-20us on Bun/Windows (see `isForbidden`) and
+ * Memoized: `resolve` measures ~16-20us on Bun/Windows (see `isForbidden`) and
  * a CPU profile of the request path put `safeResolve` + `path.resolve` at over
  * 40% of per-request self time. Caching is safe because the function is purely
- * lexical — `path.resolve` reads no filesystem state, only `process.cwd()`.
+ * lexical: `path.resolve` reads no filesystem state, only `process.cwd()`.
  * Relative arguments make entries cwd-dependent, and while nothing in the
  * runtime calls `chdir`, tests do (config.broken.test.ts boots from temp
- * fixture dirs) — so the cache is invalidated wholesale when cwd moves. The
+ * fixture dirs), so the cache is invalidated wholesale when cwd moves. The
  * check is one `process.cwd()` read per call, measured at 12ns in Bun (it is
  * cached natively), against the ~16us a resolve costs. The cache is an LRU,
  * not a Map, because arguments derive from request paths (convention 6);
@@ -238,7 +238,7 @@ export namespace Glob {
 }
 
 export namespace FileSystem {
-  // Naming, not constraint — `string & {}` is `string`. These document what a
+  // Naming, not constraint: `string & {}` is `string`. These document what a
   // parameter means at its declaration, which earns their keep. Four more
   // (`RequestPath`, `DirectoryPath`, `FileName`, `FileExtension`) documented
   // nothing, because nothing ever referenced them.
@@ -267,7 +267,7 @@ export namespace FileSystem {
 
   /**
    * Reads as UTF-8 text. Without the encoding this returns a Buffer, which
-   * every caller then hands to `JSON.parse` — legal at runtime because it
+   * every caller then hands to `JSON.parse`: legal at runtime because it
    * coerces, but a type error at each call site, papered over in one of them
    * with `as any`.
    */
@@ -281,9 +281,29 @@ export namespace FileSystem {
     return (await Try(() => Bun.file(path).stat()))?.isDirectory() || false
   }
 
+  /**
+   * Handed a `BunFile`, this used to take the path back off it and build a
+   * **second** one to stat. A `BunFile` caches its own stat, so the instance
+   * the caller already has is free to read and the fresh one is a syscall:
+   * one question about one file cost two stats and an allocation.
+   *
+   * It shows up wherever a caller asks both questions, which is the common
+   * shape - `validCache` below, `nm.ts`'s `exists(nmFile) ? nmFile.lastModified`,
+   * and both mtime comparisons in `image.ts`. Measured on this machine, four
+   * interleaved rounds against a CPU-bound control flat at 27-31 ms:
+   *
+   *     validCache, file present    33.0 us -> 17.3 us    1.9x
+   *     validCache, file absent     34.9 us -> 17.4 us    2.0x
+   *
+   * The predicate is unchanged, and the two clauses in it are not
+   * interchangeable. `lastModified` on a **missing** file answers roughly
+   * `Date.now()` rather than 0, which is what the `< Date.now()` guard is
+   * for; dropping it reports every absent file as present. The `size > 0`
+   * fallback then covers a file whose mtime is in the future, which clock
+   * skew on a network share produces.
+   */
   export function exists(path: string | Bun.BunFile): boolean {
-    path = typeof path === 'string' ? path : path.name || ''
-    const file = Bun.file(path)
+    const file = typeof path === 'string' ? Bun.file(path) : path
     const lastMod = file.lastModified
     return Boolean((lastMod && lastMod < Date.now()) || file.size > 0)
   }
@@ -293,7 +313,7 @@ export namespace FileSystem {
   }
 
   /**
-   * True only for an existing regular *file* — a directory answers false.
+   * True only for an existing regular *file*: a directory answers false.
    * Sync because `findDynamicRoute` (a sync hot-path scan) is a caller; one
    * stat, no BunFile allocation.
    */
@@ -302,12 +322,12 @@ export namespace FileSystem {
   }
 
   /**
-   * Parent directory of an **already-normalised** absolute path — the output
+   * Parent directory of an **already-normalized** absolute path: the output
    * shape `safeResolve` produces: forward slashes, no `.`/`..` segments, no
    * trailing slash except at a root.
    *
    * Only correct for that input shape, which is why it is not exported.
-   * `isForbidden` is the sole caller and it normalises before the first call.
+   * `isForbidden` is the sole caller and it normalizes before the first call.
    */
   function parentOf(path: string): string {
     const idx = path.lastIndexOf('/')
@@ -319,7 +339,7 @@ export namespace FileSystem {
     // Both of these branches are defensive rather than covered. `isForbidden`
     // stops as soon as the walk leaves `root`, and every root it is called
     // with is a real serve directory well below a filesystem root, so the walk
-    // never reaches one — dropping them both leaves the equivalence test in
+    // never reaches one: dropping them both leaves the equivalence test in
     // `fs.test.ts` green. They are kept so `parentOf` is correct as written
     // rather than correct only for its current caller.
     if (path.charCodeAt(idx - 1) === 58 /* ':' */) return path.slice(0, idx + 1)
@@ -330,7 +350,7 @@ export namespace FileSystem {
    * True when `pathToCheck`, or any directory between it and `root`, holds a
    * `.forbidden` marker.
    *
-   * This is a security guard, and it runs several times per request — from
+   * This is a security guard, and it runs several times per request, from
    * `router.ts` before anything else, then again from `getStatic`, `getRoute`
    * (once per level of a nested route) and the dynamic-route cache. Each call
    * walks every directory between the target and the serve root, so the
@@ -338,26 +358,26 @@ export namespace FileSystem {
    *
    * The walk used to call `safeResolve` twice per level, once to build
    * `<dir>/.forbidden` and once to step to the parent. Both are `node:path`
-   * `resolve`, which on Bun/Windows measures **~16-20us** — roughly 100x
+   * `resolve`, which on Bun/Windows measures **~16-20us**: roughly 100x
    * `path.dirname` (~0.2us), independent of the filesystem and of where the
    * cwd lives, and not explained by native-call overhead (`Bun.nanoseconds()`
    * is 0.045us). A depth-4 walk therefore paid ten `resolve` calls.
    *
-   * Since `curr` is normalised once on entry, every value it takes afterwards
+   * Since `curr` is normalized once on entry, every value it takes afterwards
    * is already in `resolve`'s own output shape, so both operations are exact
    * string edits. That takes a depth-4 walk from ten `resolve` calls to two
    * and leaves one `existsSync` per level as the only remaining syscall.
    * `fs.test.ts` pins the two implementations as equivalent.
    *
-   * The entry normalisation stays: `pathToCheck` reaches here straight from a
+   * The entry normalization stays: `pathToCheck` reaches here straight from a
    * URL pathname in `router.ts`, before any containment check, and collapsing
    * its dot segments is what makes the rest of the walk safe.
    *
-   * The remaining `existsSync` per level is deliberately **not** memoised
+   * The remaining `existsSync` per level is deliberately **not** memoized
    * *across requests*, which is the opposite call to the one `getMimeType`
-   * below makes. The difference is not the key — both are ultimately derived
+   * below makes. The difference is not the key: both are ultimately derived
    * from a request path and both would need an `LRUCache` to stay bounded
-   * under convention 6 — it is what a stale entry costs. A stale MIME type
+   * under convention 6: it is what a stale entry costs. A stale MIME type
    * serves the wrong `Content-Type`; a stale *negative* here serves a file an
    * operator has marked forbidden, which is the exact outcome the marker
    * exists to prevent.
@@ -367,7 +387,7 @@ export namespace FileSystem {
    * a cached "not forbidden" would persist for the life of the process; a TTL
    * would only bound that window, not close it, and an operator dropping a
    * `.forbidden` file to pull content offline has no way to learn how long the
-   * window is. The LRU also fails exactly when it would matter — a client
+   * window is. The LRU also fails exactly when it would matter: a client
    * requesting varied paths evicts the useful upper-level entries, so the
    * hit rate collapses under the load that motivated caching in the first
    * place. `fs.test.ts` has a regression test that fails if this is added.
@@ -376,8 +396,8 @@ export namespace FileSystem {
    * 4-6x per request over overlapping subtrees (router, `getStatic`, every
    * level of `getRoute`, the dynamic-route cache), each walk re-stating the
    * same directories at ~50us per miss on Bun/Windows. A marker dropped
-   * *mid-request* has no meaningful semantics — the operator's guarantee is
-   * "the next request sees it" — so the raw probe results live on the current
+   * *mid-request* has no meaningful semantics (the operator's guarantee is
+   * "the next request sees it"), so the raw probe results live on the current
    * `hostStore` value (`HostContext.forbiddenProbes`), which worker.ts creates
    * per request and never reuses. No store (tests, direct calls, startup)
    * means no caching, bit-for-bit today's behavior.
@@ -399,7 +419,7 @@ export namespace FileSystem {
     //
     // The walk below is bounded by `curr.startsWith(normalizedRoot)`, so an
     // out-of-root path skipped the loop body entirely and fell through to
-    // `return false` — "not forbidden". That is a guard failing *open* on the
+    // `return false`, "not forbidden". That is a guard failing *open* on the
     // one input it most needs to refuse, and it made every caller that relied
     // on this for containment (all of them: `constants.ts` said so in as many
     // words) incapable of catching an escape.
@@ -409,12 +429,12 @@ export namespace FileSystem {
     // read the pattern as drive-absolute, ignored `cwd`, and matched files at
     // `C:\`. `getRoute` resolved one, asked this function, was told "allowed",
     // and returned an `Info` pointing six levels above the serve root. The glob
-    // is fixed too, but the glob was only how it was reached — a resolved file
+    // is fixed too, but the glob was only how it was reached: a resolved file
     // outside the root has to be refused here whatever produced it.
     //
     // The separator suffix matters: a bare `startsWith` would also accept a
     // sibling directory whose name merely begins with the root's. A root that
-    // is already a filesystem root ends in `/` and must not gain a second one —
+    // is already a filesystem root ends in `/` and must not gain a second one:
     // `C://` matches nothing, which would make every path under `C:/` read as
     // an escape. `fs.test.ts` drives both through its root corpus.
     const rootPrefix = normalizedRoot.endsWith('/')
@@ -452,19 +472,53 @@ export namespace FileSystem {
     return false
   }
 
-  let probeForbidden: (path: string) => boolean = nodeExistsSync
+  /**
+   * `statSync` with ENOENT suppressed, not `existsSync`.
+   *
+   * Node's `existsSync` is a `stat` with a `try`/`catch` around it, and on
+   * Bun/Windows the throw-and-catch for a path that is not there is most of
+   * what it costs. Asking for the stat directly and reading `undefined` for a
+   * miss skips that. Measured on this machine, four interleaved rounds
+   * against a CPU-bound control that stayed flat at 27-30 ms:
+   *
+   *     existsSync 30.00 us    guarded statSync 17.52 us    1.71x
+   *
+   * A miss is the case that matters: almost no directory holds a `.forbidden`
+   * marker, so every level of every walk takes this path. At four unique
+   * levels per request that is 50 us, at six 75 us.
+   *
+   * The `catch` is load-bearing rather than defensive habit. `throwIfNoEntry:
+   * false` suppresses **ENOENT only**, so a directory the process cannot stat
+   * still throws EACCES or EPERM where `existsSync` answers false - and a
+   * throw here would escape through `isForbidden` into the request. Answering
+   * false matches the behavior this replaces exactly; the two forms agree on
+   * a missing marker, a present one, a marker that is a *directory*, a path
+   * several levels below anything that exists, a directory, and the empty
+   * string.
+   */
+  function statProbe(path: string): boolean {
+    try {
+      return nodeStatSync(path, { throwIfNoEntry: false }) !== undefined
+    } catch {
+      // See above: a stat that fails for any reason other than absence is
+      // reported as absent, which is what `existsSync` did.
+      return false
+    }
+  }
+
+  let probeForbidden: (path: string) => boolean = statProbe
 
   /**
    * Test seam (convention 9): lets `fs.test.ts` count the syscalls the
    * per-request dedup above is supposed to be saving, without module-mocking
-   * `node:fs` — which is process-global and never unwinds.
+   * `node:fs`, which is process-global and never unwinds.
    */
   export function __setForbiddenProbe(fn: (path: string) => boolean) {
     probeForbidden = fn
   }
 
   export function __resetForbiddenProbe() {
-    probeForbidden = nodeExistsSync
+    probeForbidden = statProbe
   }
 
   export async function mkdir(path: string) {
@@ -508,6 +562,10 @@ export namespace FileSystem {
     return compressable.has(cleanExt)
   }
 
+  /**
+   * Two reads of one `BunFile`, which is one stat: `exists` no longer
+   * re-wraps the instance, so the second read comes off the cached stat.
+   */
   function validCache(file: Bun.BunFile, sourceMtime: number | null): boolean {
     return exists(file) && (!sourceMtime || sourceMtime <= file.lastModified)
   }
@@ -521,11 +579,11 @@ export namespace FileSystem {
    * so N concurrent first-hits on a cold cache each saw "not cached", each ran
    * `compiler()`, and each wrote the same three paths. Measured: 8 concurrent
    * callers produced 8 compiler invocations. Every `.ts`/`.tsx`/`.vue` asset
-   * goes through here, so a traffic burst on a cold cache — or a cluster whose
-   * workers share one cache directory — paid the full transpile *plus* gzip
+   * goes through here, so a traffic burst on a cold cache (or a cluster whose
+   * workers share one cache directory) paid the full transpile *plus* gzip
    * *and* zstd once per concurrent request.
    *
-   * Same memoised-promise idiom as `initDB`, `setupPlugins` and
+   * Same memoized-promise idiom as `initDB`, `setupPlugins` and
    * `getTranspiler`, keyed rather than singular, and deleted in a `finally` so
    * a failed build is retried by the next caller rather than remembered. It is
    * bounded by construction (convention 6): an entry exists only while its own
@@ -533,7 +591,7 @@ export namespace FileSystem {
    *
    * The key is the path alone, not the path plus `sourceMtime`. A caller that
    * joins mid-build can therefore receive a build started for a marginally
-   * older mtime — a window only as wide as one compile, which the next request
+   * older mtime: a window only as wide as one compile, which the next request
    * re-validates and rebuilds. Including the mtime would close that window by
    * letting two builds of the same file race each other onto the same three
    * output paths, which is the worse trade.
@@ -590,7 +648,7 @@ export namespace FileSystem {
       if (content == null) return null
 
       // Only on the build path: a warm hit was paying this stat on every
-      // request for nothing — the directory necessarily exists if the cached
+      // request for nothing, the directory necessarily exists if the cached
       // file it holds just validated.
       await mkdir(cacheDir)
 
@@ -617,7 +675,7 @@ export namespace FileSystem {
 
     // The mirror of the compressed branch's check above. Without it a
     // non-compressible entry (a .woff2 from the gstatic proxy, say) was
-    // rebuilt — for fonts, re-fetched upstream — on every single request.
+    // rebuilt (for fonts, re-fetched upstream) on every single request.
     if (validCache(rawFile, sourceMtime)) return rawFile
 
     const content = await compiler()
@@ -629,8 +687,8 @@ export namespace FileSystem {
 
   /**
    * The extension→MIME mapping is static, but resolving it allocates a
-   * `Bun.BunFile` every call — ~1.4us, on the path of every static-file and
-   * compressed-asset response. Memoised behind an `LRUCache` rather than a
+   * `Bun.BunFile` every call, ~1.4us, on the path of every static-file and
+   * compressed-asset response. Memoized behind an `LRUCache` rather than a
    * plain Map because `ext` is ultimately derived from the request path, and
    * an unbounded map keyed on client-supplied input is exactly what
    * convention 6 forbids.

package/src/utils/http/authorize.ts

@@ -4,13 +4,13 @@
  * One implementation, deliberately in core, for the same reason
  * `credential.ts` is here: the dashboard, db-explorer and analytics plugins
  * each need this guard, and per-plugin copies of security code drift. These
- * three had already drifted — one coerced its predicate's return with
+ * three had already drifted: one coerced its predicate's return with
  * `Boolean`, one gated on `!DEV` where the others read `PROD`, one swallowed a
  * `getClientIp` throw into an empty string and carried on. Each divergence is
  * resolved below toward the fail-closed reading, and each is marked as a
  * decision rather than left to look like a style choice.
  *
- * It owns *only* the predicate — no logins, no sessions, no backoff. The shared
+ * It owns *only* the predicate: no logins, no sessions, no backoff. The shared
  * key path is `credential.ts`; a plugin that offers both doors composes them.
  *
  * `getClientIp` is imported from `./ip` directly, never through this
@@ -37,7 +37,7 @@ export type AuthorizeFn = (req: Request) => boolean | Promise<boolean>
  * `'localhost'` used to be a member, back when the request's *hostname* was
  * compared against this set as well. A peer address is never the string
  * `localhost`, and accepting it meant `X-Forwarded-For: localhost` counted as
- * loopback under `trustProxy` — and, worse, that `new URL(req.url).hostname`
+ * loopback under `trustProxy`, and, worse, that `new URL(req.url).hostname`
  * did too. Bun builds that from the client's own `Host` header and
  * `DEFAULT_HOST` is 0.0.0.0, so any peer on the LAN could send
  * `Host: localhost` and be handed a database browser.
@@ -51,7 +51,7 @@ export function isLoopback(req: Request): boolean {
   // DECISION (divergence 3): a throw returns `false` immediately rather than
   // falling through with `ip = ''`. `getClientIp` reads config and the live
   // server, either of which may be absent (tests, early boot). The two spell
-  // the same answer today, because `LOOPBACK.has('')` is false — but only by
+  // the same answer today, because `LOOPBACK.has('')` is false, but only by
   // coincidence, and the fall-through invites a later edit that adds a second
   // source of evidence below this line and silently consults it on the
   // indeterminate path. Returning here says the answer is settled: no address
@@ -71,31 +71,38 @@ export function isLoopback(req: Request): boolean {
  */
 export function defaultAuthorize(req: Request): boolean {
   // DECISION (divergence 2): gate on `PROD`, not `!DEV`, and read it at call
-  // time — the mode flags are accessors on `process.env` (`core/init.ts`), so
+  // time. The mode flags are accessors on `process.env` (`core/init.ts`), so
   // they are process state and tests flip them.
   //
   // The two spellings look interchangeable because `init.ts` derives them as
   // complements (`PROD = !isDev && !--dev-worker`). They are not, because they
   // are *independently settable* accessors and the test fixtures set them one
-  // at a time: `asDev` flips `DEV` alone and leaves the ambient `PROD` — which
-  // under `bun test` is `true` — in place. In that state `!DEV` admits a
+  // at a time: `asDev` flips `DEV` alone and leaves the ambient `PROD` (which
+  // under `bun test` is `true`) in place. In that state `!DEV` admits a
   // loopback caller and `PROD` denies, so `PROD` is both the fail-closed
   // reading and the one that literally names the condition it means, rather
   // than inferring production from the absence of development.
   //
-  // Hence `!== false` rather than a plain truthiness test, which is the one
-  // place a bare `PROD` gate would be *weaker* than `!DEV`. The flag does not
-  // exist until `core/init.ts` has run, and `if (undefined)` falls straight
-  // through to the loopback check — so an uninitialised process would open the
-  // door that an initialised production one keeps shut. `init.ts` defines
-  // `PROD` as a real boolean (`accessor(!isDev && !hasDevWorkerArg)`), so
-  // "explicitly false" is a statement only a booted development server can
-  // make. Unset is not evidence of development; it is no evidence at all.
+  // Hence a test for the *positive* development marker rather than a truthiness
+  // test on `PROD`, which is the one place a bare `PROD` gate would be weaker
+  // than `!DEV`. The flags do not exist until `core/init.ts` has run, and
+  // `if (undefined)` falls straight through to the loopback check, so an
+  // uninitialized process would open the door an initialized production one
+  // keeps shut. Unset is not evidence of development; it is no evidence at all.
+  //
+  // This read `PROD !== false` while the flags were real booleans. Bun 1.4
+  // rejects accessor descriptors on `process.env`, so they are `'1'`/`''`
+  // strings now (see `core/init.ts`), and `!== false` is true for *every*
+  // string, including the `''` a development server sets, so the gate would
+  // have denied on loopback in development while still looking correct.
+  // `DEV === '1'` is the same statement in the encoding that survives: only a
+  // booted development server sets it, and production (`''`) and never-booted
+  // (`undefined`) both fail it.
   //
   // `isLoopback` would very likely deny on its own there, having no config or
   // server to read an address from. That is a second line of defence, not this
   // one's excuse: a guard should not depend on another guard's failure mode.
-  if (import.meta.env.PROD !== false) return false
+  if (import.meta.env.DEV !== '1') return false
   return isLoopback(req)
 }
 
@@ -116,7 +123,7 @@ export async function isAuthorized(
   try {
     // DECISION (divergence 1): `=== true`, never `Boolean(...)`. The predicate
     // comes from application code and `AuthorizeFn`'s return type is only
-    // advice — an untyped, transpiled or `as any` predicate can hand back
+    // advice: an untyped, transpiled or `as any` predicate can hand back
     // anything. `Boolean` admits every truthy non-boolean, so a check that
     // answers with a status string denies on `""` and *grants* on `"no"`, and
     // one that answers with a count grants on any non-zero. Admission is the

package/src/utils/http/cors.ts

@@ -1,8 +1,8 @@
 /**
  * Cross-origin resource sharing.
  *
- * Bakery already ships the pieces of an API server — `ApiHandler`, sessions,
- * CSRF, rate limiting — and had no way to serve one to a browser on another
+ * Bakery already ships the pieces of an API server (`ApiHandler`, sessions,
+ * CSRF, rate limiting), and had no way to serve one to a browser on another
  * origin. This is that.
  *
  * Two halves, and both are needed: a preflight `OPTIONS` has to be answered
@@ -22,8 +22,8 @@ export interface CorsOptions {
   /**
    * Origins allowed to read responses.
    *
-   * `'*'` is honoured literally, and is refused in combination with
-   * `credentials` — see `resolveOrigin`. A function receives the request's
+   * `'*'` is honored literally, and is refused in combination with
+   * `credentials`. See `resolveOrigin`. A function receives the request's
    * `Origin` and returns the value to echo, or `null` to deny.
    */
   origin: string | string[] | ((origin: string) => string | null)
@@ -45,7 +45,7 @@ const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
  * The value for `Access-Control-Allow-Origin`, or `null` to send nothing.
  *
  * **`'*'` with credentials is refused rather than silently downgraded.** The
- * browser rejects that pairing anyway, so honouring it would produce a request
+ * browser rejects that pairing anyway, so honoring it would produce a request
  * that fails in the client with a CORS error and a server that believes it
  * allowed the call. Echoing the origin instead would be a *quiet widening* of
  * what the app asked for. Returning null makes the misconfiguration visible as
@@ -97,7 +97,7 @@ export function corsHeaders(
 /**
  * The response to a preflight, or `null` if this is not one.
  *
- * A preflight is `OPTIONS` *with* `Access-Control-Request-Method` — plain
+ * A preflight is `OPTIONS` *with* `Access-Control-Request-Method`: plain
  * `OPTIONS` is a normal request and must fall through to routing, or an app
  * with its own OPTIONS route would find it shadowed.
  *

package/src/utils/http/credential.ts

@@ -4,14 +4,14 @@
  *
  * One implementation, deliberately in core: the db-explorer and analytics
  * plugins each need it and per-plugin copies of security code drift. It owns
- * *only* the comparison — no logins, no sessions, no backoff.
+ * *only* the comparison: no logins, no sessions, no backoff.
  *
  * A credential is presented three ways, in this order of preference:
  *
  *   - `x-<name>` header (scriptable, never logged by default)
  *   - `Authorization: Bearer <credential>`
  *   - `?<name>=<credential>` query, for a human opening a URL in a browser
- *     who cannot set a header — the caller is expected to strip it from the
+ *     who cannot set a header. The caller is expected to strip it from the
  *     URL client-side; it *does* reach server logs, which is documented, and
  *     the header forms exist for anything automated.
  *
@@ -20,7 +20,7 @@
  * variable unset must mean "off", not "open".
  *
  * The compare is constant-time. A plain `===` on a secret is a timing oracle,
- * and `timingSafeEqual` costs one line — but it throws on length mismatch, so
+ * and `timingSafeEqual` costs one line, but it throws on length mismatch, so
  * the length is checked first (which leaks only the length, never the bytes).
  */
 
@@ -41,7 +41,7 @@ export function credentialMatches(
 /**
  * Pull a presented credential off a request: the `x-<name>` header, a Bearer
  * token, or the `<name>` query parameter, in that order. Returns `null` when
- * none is present. `name` is the header/query key — `db-key`, `analytics-key`.
+ * none is present. `name` is the header/query key: `db-key`, `analytics-key`.
  */
 export function readCredential(req: Request, name: string): string | null {
   const header = req.headers.get(`x-${name}`)

package/src/utils/http/csrf.ts

@@ -2,7 +2,7 @@
  * Cross-site request forgery guards.
  *
  * A `SameSite=Lax` cookie is still sent on top-level cross-site *navigations*,
- * so it is not on its own sufficient to protect a state-changing endpoint —
+ * so it is not on its own sufficient to protect a state-changing endpoint:
  * `<a href="/api/admin/delete?id=5">` or a cross-origin `<form>` POST both
  * arrive with the victim's session attached.
  */
@@ -17,7 +17,7 @@ const SAME_SITE_VALUES = new Set(['same-origin', 'same-site', 'none'])
 /**
  * Returns a reason string when the request looks cross-site, or `null` when it
  * is safe to process. Requests with neither `Origin` nor `Sec-Fetch-Site` (curl,
- * server-to-server, older clients) are allowed — browsers always send at least
+ * server-to-server, older clients) are allowed: browsers always send at least
  * one of them on a cross-origin request.
  */
 export function checkSameOrigin(req: Request, url: URL): string | null {
@@ -46,7 +46,7 @@ export function checkCsrf(req: Request, url: URL): string | null {
 /**
  * An attacker-supplied header value, made safe to put in a reason string.
  *
- * Reason strings are logged, and the logger renders one record per line — so
+ * Reason strings are logged, and the logger renders one record per line, so
  * an `Origin` carrying a newline could forge additional log entries. Anything
  * outside printable ASCII goes, and the result is capped: a rejection reason
  * is a diagnostic, not a transcript.
@@ -57,14 +57,13 @@ function safeEcho(value: string): string {
 }
 
 /**
- * Origin guard for WebSocket upgrades — deliberately stricter than
+ * Origin guard for WebSocket upgrades: deliberately stricter than
  * `checkSameOrigin`, and applied in `upgradeWebsocket` so every socket
  * inherits it rather than each handler having to remember.
  *
  * WebSockets are exempt from the same-origin policy. Any page the developer
  * visits can open `ws://localhost:3000/_livereload`, and until this existed
- * one `{"type":"subscribe_logger"}` bought a live feed of the server log —
- * failing SQL, table and column names, absolute source paths — plus the
+ * one `{"type":"subscribe_logger"}` bought a live feed of the server log ( * failing SQL, table and column names, absolute source paths) plus the
  * ability to reload every open browser. The only thing that separates the
  * app's own page from an attacker's is `Origin`, which the browser sets on
  * every handshake and page script cannot override.
@@ -89,7 +88,7 @@ function safeEcho(value: string): string {
  *
  * An **absent** `Origin` is allowed, and that is a decision rather than an
  * oversight. A browser never omits it on a handshake, so its absence means the
- * peer is not a browser — curl, a test, a CLI, a health check. Such a client
+ * peer is not a browser: curl, a test, a CLI, a health check. Such a client
  * can also set `Origin` to whatever it likes, so refusing the absent case buys
  * no security at all while breaking every non-browser client. This check is
  * worth exactly what a browser's inability to forge the header is worth, and

package/src/utils/http/dom.ts

@@ -7,7 +7,7 @@ import { Try } from '../common/try'
 import { fs } from '../fs'
 import { escapeScriptJson } from '../isomorphic/escape'
 
-// Keyed by hostname, which comes from the Host header — bounded so a client
+// Keyed by hostname, which comes from the Host header: bounded so a client
 // cannot grow it without limit by varying that header per request.
 const headBodyCache = new LRUCache<string, { head: string; body: string }>(64)
 
@@ -22,12 +22,12 @@ let depMap = ''
 const hostDepMaps = new Map<string, string>()
 
 /**
- * Normalise one import-map entry, for both the process-level map and the
+ * Normalize one import-map entry, for both the process-level map and the
  * per-host maps.
  *
  * One helper, two callers, deliberately: they used to be separate copies that
- * had drifted into testing different things — one switched on the entry key,
- * the other on the entry value — so the same input normalised two ways
+ * had drifted into testing different things (one switched on the entry key,
+ * the other on the entry value), so the same input normalized two ways
  * depending on which path saw it.
  *
  * `@client/utils` is keyed on the *key*: it is a live alias, the default
@@ -75,12 +75,12 @@ let installedCache: Promise<string[]> | null = null
  *
  * Read from `node_modules` rather than from `dependencies`, and the difference
  * is the whole point: a package can be installed and imported without being
- * declared — a transitive one, or a dependency someone forgot to add — and the
+ * declared (a transitive one, or a dependency someone forgot to add), and the
  * browser's failure for a specifier the map misses names its own rule rather
  * than the missing entry: *"Failed to resolve module specifier 'pkg'. Relative
  * references must start with either "/", "./", or "../"."*
  *
- * Cheap — one `readdir` per scope, no `package.json` reads — and memoised per
+ * Cheap: one `readdir` per scope, no `package.json` reads, and memoized per
  * process besides: the import map reads it at boot, `bundleModule` on every
  * bundle (as its `external` list), and a `readdir` sweep per bundle is pure
  * waste. A dev restart is a new process, so an install still shows up.
@@ -122,7 +122,7 @@ async function readInstalledPackages(): Promise<string[]> {
  *
  * **Resolution happens at the other end of the URL, and rewriting happens
  * nowhere.** An entry maps a package to `/_nm/<name>`; `NMHandler` hands that to
- * `Bun.build`, which applies real browser resolution — `exports` maps,
+ * `Bun.build`, which applies real browser resolution: `exports` maps,
  * conditions, the `browser` field. Naming an entry file here instead would mean
  * reimplementing all of that, badly.
  *
@@ -168,7 +168,7 @@ export namespace DOMTools {
 
     // Was a hand-rolled `JSON.stringify(...).replace(/</g, ...)`, which is the
     // same job `escapeScriptJson` already does for every other inline-script
-    // payload — its docstring even said "Mirrors utils/http/dom.ts". The two
+    // payload: its docstring even said "Mirrors utils/http/dom.ts". The two
     // had drifted: this copy never escaped U+2028/U+2029.
     return `<script>window.__PAGE_PARAMS__ = ${escapeScriptJson(newParams)}</script>`
   }
@@ -190,7 +190,7 @@ export namespace DOMTools {
   }
 
   /**
-   * ResponseInit carrying `data`'s status and headers, minus Content-Length —
+   * ResponseInit carrying `data`'s status and headers, minus Content-Length:
    * injection changes the body length, so a stale value must not survive into
    * the rebuilt Response. Shared by the buffered and streamed injection paths
    * so the two cannot drift on which headers survive.