dsh-mini-utility-dock 0.5.0 → 0.6.0

package/bin/dsh-plugin-parity.js

@@ -1,38 +1,44 @@
 // Cross-repo drift check for the shared host fragments.
 //
-// Why this exists: each member repository ships its own copy of the loopback
-// predicates and the request guard, because each package has to stand alone.
-// Those copies drifted repeatedly, and every drift was security-relevant:
+// Why this exists: every member repository embeds its own copy of the loopback
+// predicates and the request guard, because every package has to stand alone, and
+// hand-copied enforcement code drifts in ways that are always
+// security-relevant — an IPv6 loopback that reads as foreign and locks a
+// legitimate browser out of its own API, Host spellings two copies disagree on,
+// a Host that parses to no hostname skipping the allowlist in one copy while
+// another denies it.
 //
-//   1. every copy rejected IPv6 loopback (`::1`) — a legitimate browser was
-//      locked out of its own API;
-//   2. the copies disagreed on which Host spellings count as loopback, leaving
-//      one of them with an allowlist entry its Origin path could never reach;
-//   3. a Host that parsed to no hostname silently skipped the allowlist in one
-//      copy and was denied in the others.
+// The copies are no longer hand-written: they are embedded blocks generated from
+// dsh-mini-utility-dock by the dock CLI — `dist/loopback.js` (the predicates),
+// `dist/guard.js` (the enforcement policy) and `dist/host-http.js` (the response
+// glue: JSON replies, the POST gate, the browser authorizer). So this checker
+// asserts three things a generator alone cannot:
 //
-// The copies are no longer hand-written: they are two embedded blocks generated
-// from dsh-mini-utility-dock by the dock CLI — `dist/loopback.js` (the predicates)
-// and `dist/guard.js` (the enforcement policy). So this checker asserts three
-// things a generator alone cannot:
-//
-//   * both embedded blocks are byte-identical in every member (a hand edit to
-//     one copy, or a repo that never re-ran `loopback:sync` / `guard:sync`, fails
-//     here), and they appear in dependency order — the guard uses the predicates
-//     the loopback block declares in the same file;
+//   * every embedded block is byte-identical in every member (a hand edit to
+//     one copy, or a repo that never re-ran `loopback:sync` / `guard:sync` /
+//     `http:sync`, fails here), and they appear in dependency order — the guard
+//     uses the predicates the loopback block declares in the same file;
 //   * no repo keeps a private copy of an enforcement decision beside them — that
-//     is how drifts 1-3 happened, and embedding the blocks is worthless if a repo
-//     also branches on its own version;
+//     is how the drifts above happened, and embedding the blocks is worthless if
+//     a repo also branches on its own version;
 //   * the members AGREE ON EVERY DECISION. Error codes and wording deliberately
 //     differ (each plugin's published API vocabulary), so the comparison is on
 //     the allow/deny outcome only. This is the assertion that survives a policy
 //     change: byte equality implies it, but only this proves each consumer
 //     actually routes through the blocks.
 //
+// The host-HTTP block is in the compared set for the same reason the guard is:
+// what it carries is policy. A response header that keeps live port and session
+// data out of caches, and the reply for "browser authorization is unavailable",
+// are exactly the lines a hand-copied glue function loses on one repo.
+//
 // Usage:
 //   dsh-plugin-parity --root <dir> --member <repo>:<export> [--member ...]
+//   dsh-plugin-parity --root <dir> --member ... --fleet <repo>
+//     # `--fleet` names the one member that opts into fleet mode, so the check
+//     # that the relaxation stays bounded runs against its guard alone
 //   dsh-plugin-parity --root <dir>       # static checks for every member found
-//   dsh-plugin-parity --self-test        # exercises the extractor alone
+//   dsh-plugin-parity --self-test        # exercises the block extractor and the block-dropping step
 //
 // `--member` names one participating repository and the guard factory it
 // exports. That name is per-repository by design — the shared block is not
@@ -44,11 +50,12 @@
 // markers is checked statically, and the decision comparison is skipped.
 //
 // This is a LOCAL DIAGNOSTIC, deliberately not a CI gate. Per-repo CI already
-// proves the stronger local property — `loopback:check` / `guard:check` compare
-// each repo's embedded blocks against the `dist/` of the exact dock version it
-// pins, and that version is immutable on npm. Members pinning one version
-// therefore hold byte-identical blocks by construction, which is why this script
-// is redundant as a gate and was removed from the compat workflow.
+// proves the stronger local property — `loopback:check` / `guard:check` /
+// `http:check` compare each repo's embedded blocks against the `dist/` of the
+// exact dock version it pins, and that version is immutable on npm. Members
+// pinning one version therefore hold byte-identical blocks by construction,
+// which is why this script is redundant as a CI gate and stays a manual
+// diagnostic instead.
 //
 // The property it asserts is inherently cross-repository and cannot hold at an
 // arbitrary moment: on a `dev` push the peer checkouts resolve to their default
@@ -99,25 +106,42 @@ const discovered = () => readdirSync(root, { withFileTypes: true })
 const repos = members.length ? members : discovered().map((name) => [name, name, null])
 const tags = repos.map(([, tag]) => tag).join('/')
 
-// Dependency order: the guard block uses the predicates the loopback block
-// declares, so it must come second.
+// The order the blocks sit in `lib/shared.js`: the guard block uses the
+// predicates the loopback block declares in the same file, so the predicates must
+// come first, and the host-HTTP block lands below the guard, where a consumer's
+// own glue has always lived. `FRAGMENTS` in the dock CLI lists the same order, so
+// `dropBlocks` and the position check below can treat this table as the file's
+// true layout.
 const BLOCKS = [
   { name: 'dsh-loopback-helpers', label: 'loopback predicates' },
-  { name: 'dsh-host-guard', label: 'host guard' }
+  { name: 'dsh-host-guard', label: 'host guard' },
+  { name: 'dsh-host-http', label: 'host HTTP glue' }
 ]
 
 const marks = (name) => ({ start: `// <${name}>`, end: `// </${name}>` })
 
 // Pull a generated block out of a consumer's lib/shared.js. Everything between
-// the markers is generator output, so it must match byte for byte; the consumer
-// indents it, which is stripped before comparing.
+// the markers is generator output, so it must match once re-indented. A consumer
+// re-indents the whole block to its marker's own indentation, and the dock's
+// `sync` preserves that indentation, so two repos that indent their markers
+// differently still hold the same block. Stripping the block's shared leading
+// whitespace — not a fixed 2 spaces — is what makes them compare equal.
 const extractBlock = (src, name) => {
   const { start, end } = marks(name)
   const lines = src.split(/\r?\n/)
   const starts = lines.reduce((hits, line, i) => line.trim() === start ? [...hits, i] : hits, [])
   const ends = lines.reduce((hits, line, i) => line.trim() === end ? [...hits, i] : hits, [])
   if (starts.length !== 1 || ends.length !== 1 || ends[0] <= starts[0]) return null
-  return lines.slice(starts[0] + 1, ends[0]).map((line) => line.replace(/^\s{2}/, '')).join('\n').trim()
+  const body = lines.slice(starts[0] + 1, ends[0])
+  // The least-indented non-blank line carries exactly the block's indentation, so
+  // removing that many leading whitespace characters from every line restores the
+  // fragment's own relative indentation, whether the marker used 2 spaces, 4, or a
+  // tab. A fragment always has top-level (column-0) lines, so the minimum is its
+  // indent, not a deeper body line.
+  const indent = body.reduce((min, line) => line.trim() === '' ? min
+    : Math.min(min, (/^[ \t]*/.exec(line) || [''])[0].length), Infinity)
+  const strip = Number.isFinite(indent) ? indent : 0
+  return body.map((line) => line.trim() === '' ? '' : line.slice(strip)).join('\n').trim()
 }
 
 const read = (repo) => readFileSync(join(root, repo, 'lib', 'shared.js'), 'utf8')
@@ -153,12 +177,19 @@ const dockPinOf = (repo) => {
 if (process.argv.includes('--self-test')) {
   const good = [
     marks('dsh-loopback-helpers').start, 'const a = 1', marks('dsh-loopback-helpers').end,
-    marks('dsh-host-guard').start, 'const b = 2', marks('dsh-host-guard').end
+    marks('dsh-host-guard').start, 'const b = 2', marks('dsh-host-guard').end,
+    marks('dsh-host-http').start, 'const c = 3', marks('dsh-host-http').end,
+    // The plugin's own code, which `dropBlocks` must leave behind.
+    'export const pluginLine = 7'
   ].join('\n')
   const cases = [
     ['first block extracted', 'dsh-loopback-helpers', good, 'const a = 1'],
     ['second block extracted', 'dsh-host-guard', good, 'const b = 2'],
+    ['third block extracted', 'dsh-host-http', good, 'const c = 3'],
     ['indent is stripped', 'dsh-loopback-helpers', [marks('dsh-loopback-helpers').start, '  const a = 1', marks('dsh-loopback-helpers').end].join('\n'), 'const a = 1'],
+    ['four-space indent is stripped', 'dsh-loopback-helpers', [marks('dsh-loopback-helpers').start, '    const a = 1', marks('dsh-loopback-helpers').end].join('\n'), 'const a = 1'],
+    ['tab indent is stripped', 'dsh-loopback-helpers', [marks('dsh-loopback-helpers').start, '\tconst a = 1', marks('dsh-loopback-helpers').end].join('\n'), 'const a = 1'],
+    ['relative indent is kept', 'dsh-host-guard', [marks('dsh-host-guard').start, '    const b = 2', '      inner', marks('dsh-host-guard').end].join('\n'), 'const b = 2\n  inner'],
     ['missing end marker returns null', 'dsh-loopback-helpers', [marks('dsh-loopback-helpers').start, 'const a = 1'].join('\n'), null],
     ['absent block returns null', 'dsh-host-guard', good.replace(/dsh-host-guard/g, 'other'), null]
   ]
@@ -170,17 +201,19 @@ if (process.argv.includes('--self-test')) {
     else console.log(`self-test ok   ${label}`)
     if (!ok) bad++
   }
-  // Dropping both blocks must leave only the plugin's own code.
+  // Dropping every block must remove the generated bodies and leave the plugin's
+  // own code intact. A leftover body would read as a private enforcement decision;
+  // a dropped plugin line would mean the splices overreached.
   const residual = dropBlocks(good)
-  const dropOk = !/const a = 1|const b = 2/.test(residual)
-  console.log(dropOk ? 'self-test ok   both blocks dropped' : `self-test FAIL both blocks dropped: ${JSON.stringify(residual)}`)
+  const dropOk = !/const a = 1|const b = 2|const c = 3/.test(residual) && /export const pluginLine = 7/.test(residual)
+  console.log(dropOk ? 'self-test ok   every block dropped, plugin code kept' : `self-test FAIL block dropping: ${JSON.stringify(residual)}`)
   if (!dropOk) bad++
   process.exit(bad ? 1 : 0)
 }
 
 let failures = 0
 
-// 1. Both generated blocks must be present, byte-identical everywhere, and in
+// 1. Every generated block must be present, byte-identical everywhere, and in
 //    dependency order.
 for (const block of BLOCKS) {
   const copies = repos.map(([repo, tag]) => ({ repo, tag, body: extractBlock(read(repo), block.name) }))
@@ -207,7 +240,7 @@ for (const block of BLOCKS) {
 // 2. Every repo must embed from the same dock version. A skew here is the one
 //    cross-repo cause of divergence that per-repo checks cannot see: each repo's
 //    own `guard:check` passes against whatever it pins, so a repo left on an older
-//    dock stays green while its blocks differ from its siblings'.
+//    dock stays green while its blocks differ from the other members'.
 {
   const pins = repos.map(([repo, tag]) => ({ tag, pin: dockPinOf(repo) }))
   const unset = pins.filter((p) => p.pin === null)
@@ -219,7 +252,7 @@ for (const block of BLOCKS) {
     console.log(`FAIL dock pin: versions differ — ${pins.map((p) => `${p.tag}=${p.pin}`).join(' ')}`)
     failures++
   } else {
-    // An exact pin is what makes the sibling repos hold identical blocks: a range
+    // An exact pin is what makes every member hold identical blocks: a range
     // could resolve to different builds under one declared value.
     const exact = /^\d+\.\d+\.\d+$/.test(distinct[0])
     if (!exact) {
@@ -232,45 +265,50 @@ for (const block of BLOCKS) {
 }
 
 // The guard block reads what the loopback block declares in the same file, so the
-// order is load-bearing, not cosmetic.
+// order is load-bearing, not cosmetic. `FRAGMENTS` in the dock CLI documents one
+// order and every consumer writes that one, so a member whose blocks sit any
+// other way has either hand-moved a block or embedded from a different dock —
+// both of which make its `check` results harder to read than this line makes them.
 {
   let orderBad = 0
   for (const [repo, tag] of repos) {
     const src = read(repo)
-    const loop = spanOf(src, 'dsh-loopback-helpers')
-    const guard = spanOf(src, 'dsh-host-guard')
-    if (!loop || !guard) continue
-    if (loop.from > guard.from) {
-      console.log(`FAIL ${tag}: the host guard block precedes the loopback predicates`)
-      orderBad++
+    const placed = BLOCKS
+      .map((block) => ({ block, span: spanOf(src, block.name) }))
+      .filter((entry) => entry.span !== null)
+    for (let i = 1; i < placed.length; i++) {
+      if (placed[i - 1].span.from > placed[i].span.from) {
+        console.log(`FAIL ${tag}: the ${placed[i].block.label} block precedes the ${placed[i - 1].block.label} block`)
+        orderBad++
+      }
     }
   }
   if (orderBad) failures += orderBad
-  else console.log('ok   block order: the loopback predicates precede the host guard everywhere')
+  else console.log('ok   block order: loopback predicates, then host guard, then host HTTP glue, everywhere')
 }
 
 // 3. Embedding the blocks is worthless if a repo also keeps its own enforcement
 //    beside them. Policy is expected outside the blocks; decisions are not.
 //
-//    `remoteAddress` is deliberately NOT listed on its own: a plugin may keep a
-//    second helper that applies the same criterion for a different gate
-//    (dsh-instance-manager's `requestNeedsBearer` does exactly that, so the API
-//    route and the guard cannot drift apart). A private criterion only matters
-//    when the repo also owns a private guard, which the factory check catches.
+//    Every pattern here matches a CODE SHAPE, not a word. These files are scanned
+//    as text with the generated blocks dropped, so a bare keyword also matches
+//    prose: a doc comment explaining why a private helper is NOT a second guard
+//    used to fail the very repository that documented its reasoning. An
+//    explanation is not enforcement; reading a header or declaring a function is.
 const ENFORCEMENT = [
-  [/LOOPBACK_HOSTNAMES\s*=/, 'redefines LOOPBACK_HOSTNAMES'],
+  [/LOOPBACK_HOSTNAMES\s*=(?!=)/, 'redefines LOOPBACK_HOSTNAMES'],
   [/(?:const|function|let)\s+isLoopbackName\b/, 'defines a private isLoopbackName'],
   [/(?:const|function|let)\s+isLoopbackAddress\b/, 'defines a private isLoopbackAddress'],
   [/(?:const|function|let)\s+hostHostname\b/, 'defines a private hostHostname'],
   [/(?:const|function|let)\s+bindGuard\b/, 'defines a private guard factory'],
-  [/sec-fetch-site/, 'branches on Fetch Metadata outside the blocks']
+  [/\[\s*['"]sec-fetch-site['"]\s*\]/, 'reads Fetch Metadata outside the blocks'],
+  [/\{[^}]*['"]sec-fetch-site['"]\s*[,:}]/, 'reads Fetch Metadata outside the blocks']
 ]
 for (const [repo, tag] of repos) {
   const outside = dropBlocks(read(repo))
-  const problems = ENFORCEMENT.filter(([re]) => re.test(outside)).map(([, why]) => why)
-  if (/remoteAddress/.test(outside) && /function\s+guard\s*\(|=>\s*\{\s*$/.test(outside)) {
-    problems.push('looks like a private guard reading the socket peer')
-  }
+  // The bracket read and the destructuring read share one reason, so collapse the
+  // two patterns' matches into a single report line.
+  const problems = [...new Set(ENFORCEMENT.filter(([re]) => re.test(outside)).map(([, why]) => why))]
   if (problems.length) {
     console.log(`FAIL ${tag}: ${problems.join('; ')}`)
     failures++
@@ -398,7 +436,8 @@ else console.log(`ok   decisions: ${cases.length} cases agree across ${tags}`)
 //    member named by `--fleet` opts in. Assert the relaxation stays bounded: a
 //    fleet guard still rejects a cross-site request, a foreign Origin, and a
 //    missing peer.
-const fleetMember = members.find(([repo]) => repo === flagOf('--fleet')) || null
+const fleetFlag = flagOf('--fleet')
+const fleetMember = fleetFlag ? members.find(([repo]) => repo === fleetFlag) : null
 const fleetCases = [
   ['fleet admits a peer host', { host: 'box.lan:3080' }, 'allow'],
   ['fleet admits a remote peer', { host: '127.0.0.1:3080', peer: '203.0.113.7' }, 'allow'],
@@ -406,8 +445,14 @@ const fleetCases = [
   ['fleet still rejects foreign Origin', { host: 'box.lan:3080', origin: 'https://evil.example' }, 'deny'],
   ['fleet still rejects a missing peer', { host: 'box.lan:3080', peer: null }, 'deny']
 ]
-if (!fleetMember) {
+if (!fleetFlag) {
   console.log('ok   fleet bounds: skipped (pass --fleet <repo> to check the member that opts in)')
+} else if (!fleetMember) {
+  // Passing `--fleet` asks for the relaxation boundary to be tested; a name that
+  // matches no member means that test never ran, so say FAIL rather than let the
+  // "skipped" line read as a pass for a check that was requested but not performed.
+  console.log(`FAIL fleet bounds: --fleet ${fleetFlag} is not one of the --member repositories (${members.map(([, tag]) => tag).join(', ')})`)
+  failures++
 } else {
   const fleetVerdict = (req) => verdict(fleetMember[0], fleetMember[2], { ...req, fleet: true })
   let fleetBad = 0

package/dist/guard.js

@@ -1,13 +1,14 @@
-// Host-side request guard shared by the DSH plugins.
+// Host-side same-origin request guard, for a plugin's host half that binds an
+// API to loopback.
 //
 // This fragment has ONE source of truth: dsh-mini-utility-dock/dist/guard.js.
-// DSH plugin host halves are plain Node ESM that each package ships standalone,
-// so the fragment is embedded into `lib/shared.js` at build time by
+// A host half is plain Node ESM that its package ships standalone, so the
+// fragment is embedded into `lib/shared.js` at build time by
 //   npm run guard:sync    (write it)
 //   npm run guard:check   (fail on drift)
 // instead of being imported: a bare `import 'dsh-mini-utility-dock/...'` would
-// put a runtime dependency on the dock into every plugin, and the whole point of
-// the dock is that a plugin ships standalone, with nothing else required.
+// put a runtime dependency on this package into the file that embeds it, and an
+// embedding plugin ships standalone, with nothing else required.
 //
 // This file is the POLICY half. What counts as loopback is a separate fragment
 // (`dist/loopback.js`, embedded under the `dsh-loopback-helpers` marker), and
@@ -21,18 +22,15 @@
 // file, so an import of another module would both break the standalone promise
 // and collide with the exports the block above already declares.
 //
-// Why the guard is shared rather than reimplemented per plugin: each consumer
-// carried its own `createGuard`, and the copies diverged repeatedly. The
-// parts that differed were never the *decisions* — they were the error codes and
-// message strings welded into the same function, which forced every repo to keep
-// its own copy and made drift possible. Here the enforcement order and every
-// decision are fixed, and the wording is supplied as data by the caller
-// (`policy`), so a plugin customizes its vocabulary without forking the logic.
+// The enforcement order and every decision are fixed here, and the wording is
+// supplied as data by the caller (`policy`): a plugin customizes the codes and
+// messages its own API publishes without forking the checks. Keeping the
+// vocabulary out of the decisions is what makes one copy of them enough.
 
 // Default ports each scheme normalises away, so an Origin carrying no explicit
 // port (for example `http://127.0.0.1`) compares equal to a server on 80/443.
-// `new URL('http://127.0.0.1:80').port` is '', which compared unequal to "80"
-// and turned a legitimate same-origin request into a rejection.
+// `new URL('http://127.0.0.1:80').port` is '', which would read as unequal to
+// `80` and reject a legitimate same-origin request.
 const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' }
 export const portOf = (url) => url.port || DEFAULT_PORTS[url.protocol] || ''
 
@@ -41,10 +39,9 @@ export const portOf = (url) => url.port || DEFAULT_PORTS[url.protocol] || ''
 // plugin's API exposes and the human wording are policy.
 //
 // An unidentifiable peer and an off-loopback peer are deliberately distinct
-// decisions. Two plugins answer `non_loopback_peer` for both; one distinguishes
-// them. Both distinctions are correct for their own API, and a plugin that
-// collapses them names the same `code` for each — nothing widens either way,
-// because every reason rejects.
+// decisions, because they are distinct facts about the request. A caller may map
+// both to the same `code`: that is a vocabulary choice about its published API,
+// and nothing widens either way, because every reason rejects.
 export const GUARD_REASONS = Object.freeze([
   'non_loopback_peer',
   'cross_site',
@@ -66,9 +63,9 @@ export const DEFAULT_GUARD_POLICY = Object.freeze({
  * Build the same-origin request guard for a loopback-bound API route.
  *
  * Not exported under a plugin-facing name: each plugin publishes its own guard
- * bound to its own error vocabulary, so the name it exports — usually
- * `createGuard`, matching its previous API — is its own to declare. This is the
- * one factory every plugin calls.
+ * bound to its own error vocabulary, so the name it exports — `createGuard` is
+ * the conventional one — is the plugin's own to declare. This is the one factory
+ * every plugin that embeds this block calls.
  *
  * Enforces, in order: Fetch Metadata, an unparseable Host, the TCP peer address,
  * then the Host allowlist, then the Origin. Rejects by calling

package/dist/host-http.js

@@ -0,0 +1,207 @@
+// Host-side HTTP glue, for a plugin's host half that answers its own API.
+//
+// This fragment has ONE source of truth: dsh-mini-utility-dock/dist/host-http.js.
+// A host half is plain Node ESM that its package ships standalone, so the
+// fragment is embedded into `lib/shared.js` at build time by
+//   npm run http:sync    (write it)
+//   npm run http:check   (fail on drift)
+// instead of being imported: a bare `import 'dsh-mini-utility-dock/...'` would
+// put a runtime dependency on this package into the file that embeds it, and an
+// embedding plugin ships standalone, with nothing else required.
+//
+// There is deliberately no `import` here. The block sits BELOW `dsh-host-guard`
+// in the consumer's `lib/shared.js` and declares nothing the blocks above it
+// already declared, so the three host-side blocks coexist in one file and a
+// plugin that needs only this one can embed only this one.
+//
+// These lines are the response policy, so they are stated once here: every JSON
+// reply carries `cache-control: no-store`, because a body naming instance ports,
+// pids or session ids must never be servable from an intermediary cache — that
+// header is a security posture, not cosmetics. The "browser authorization is
+// unavailable" reply and the POST gate each have one definition, so a change to
+// one reaches every file that embeds this block at the same time.
+//
+// What legitimately differs between plugins — a machine-readable `code`, the
+// human wording, whether the rejected `action` is echoed — is supplied as data
+// (`policy`), exactly the way `dist/guard.js` separates enforcement from
+// vocabulary.
+
+/**
+ * Send a JSON reply and end the response.
+ *
+ * `cache-control: no-store` is part of this function rather than of each call
+ * site: a route that reports live host facts (ports, pids, session data) must
+ * not be servable from an intermediary cache, and a two-line helper that each
+ * call site restates is where such a header goes missing.
+ */
+export function sendJson(res, status, body) {
+  const text = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store'
+  })
+  res.end(text)
+}
+
+/**
+ * The one reply for "browser authorization is unavailable right now". Exported
+ * as data so a call site that cannot go through `connectionUnavailable()` — a
+ * test, or a route that composes its own body — still states it once.
+ */
+export const CONNECTION_UNAVAILABLE = Object.freeze({
+  ok: false,
+  code: 'connection_unavailable',
+  error: 'browser authentication unavailable'
+})
+
+/**
+ * Answer `res` with 503 and the shared `connection_unavailable` payload, and
+ * return false so a caller can hand its own verdict back in one statement.
+ * `respond` has the same injectable sink shape as the guard block's `bindGuard`
+ * — `(res, status, body)` — and it defaults to this block's `sendJson`, so the
+ * no-store policy is not something a call site can drop.
+ */
+export const connectionUnavailable = (res, respond = sendJson) => {
+  respond(res, 503, { ...CONNECTION_UNAVAILABLE })
+  return false
+}
+
+/**
+ * The reasons the POST gate can reject. One today; the table exists so the
+ * wording is overridable by key and a typo in that key is an error rather than a
+ * silent no-op — the same contract the guard block's `GUARD_REASONS` offers.
+ */
+export const REQUIRE_POST_REASONS = Object.freeze(['method_not_allowed'])
+
+/** Default code and wording. `{action}` in `error` is substituted per call. */
+export const DEFAULT_REQUIRE_POST_POLICY = Object.freeze({
+  method_not_allowed: { code: 'method', error: 'action "{action}" requires POST' }
+})
+
+/**
+ * Build the POST-only gate for a mutating action.
+ *
+ * Behavior is fixed: the method is read case-insensitively (an absent method
+ * reads as `GET`, which is not POST), POST passes, anything else is answered
+ * 405 and returns false. What a plugin publishes — the `code`, the language of
+ * `error`, and whether the rejected `action` is echoed in the body — is policy:
+ *
+ *   createRequirePost()                                          // `{ code: 'method' }`
+ *   createRequirePost({ policy: { method_not_allowed: {          // an established API keeps its shape
+ *     code: 'need_post', error: '{action} 需要 POST 请求', includeAction: true
+ *   } } })
+ *
+ * @param respond - rejection sink, defaults to this block's `sendJson`, so the
+ *   `no-store` header is not a thing a caller can forget to pass.
+ * @param policy - optional per-reason `{ code, error, includeAction }` overrides
+ *   keyed by `REQUIRE_POST_REASONS`; a partial override merges with the default,
+ *   and an unknown key throws.
+ */
+export const createRequirePost = ({ respond = sendJson, policy } = {}) => {
+  const overrides = policy || {}
+  for (const key of Object.keys(overrides)) {
+    if (!REQUIRE_POST_REASONS.includes(key)) {
+      throw new Error(`createRequirePost: unknown policy key ${JSON.stringify(key)}; expected one of ${REQUIRE_POST_REASONS.join(', ')}`)
+    }
+  }
+  const say = Object.fromEntries(REQUIRE_POST_REASONS.map((reason) => [
+    reason,
+    { ...DEFAULT_REQUIRE_POST_POLICY[reason], ...(overrides[reason] || {}) }
+  ]))
+  const render = (template, action) => String(template).replace(/\{action\}/g, action == null ? '' : String(action))
+
+  return function requirePost(req, res, action) {
+    if (String((req && req.method) || 'GET').toUpperCase() === 'POST') return true
+    const words = say.method_not_allowed
+    respond(res, 405, {
+      ok: false,
+      code: words.code,
+      error: render(words.error, action),
+      ...(words.includeAction ? { action } : {})
+    })
+    return false
+  }
+}
+
+/**
+ * Build the browser authorizer for a route that is guarded by RC1's Connection
+ * when the host provides one, and by the plugin's own same-origin guard when it
+ * does not.
+ *
+ * @param getConnection - `() => connection`, an ACCESSOR, never the value. A host
+ *   half keeps its Connection in a closure variable that service unload/reload
+ *   reassigns to `null` and later back to a new instance; a captured value would
+ *   keep authorizing against a disposed Connection forever.
+ * @param getConnectionSeen - `() => connectionSeen`, an accessor for the latch
+ *   that records "this host has had an RC1 Connection at least once". Same
+ *   reason, same consequence: read it per request.
+ * @param guard - the plugin's bound request guard, used only on a host that has
+ *   never had a Connection (older hosts, where the guard IS the boundary).
+ * @param respond - rejection sink, defaults to this block's `sendJson`.
+ * @returns `(req, res) => boolean`, true when the request may proceed.
+ *
+ * The decision order is the security property, so it is fixed here:
+ *
+ *   1. A Connection that throws is not a Connection that permits. The request is
+ *      rejected 503 and must never fall through to the route handler.
+ *   2. A rejection code from the Connection is final: the status is that code,
+ *      401 reads as `unauthorized`, anything else as `forbidden`.
+ *   3. No Connection but a seen one: 503, and deliberately NOT the guard. Once
+ *      the host has had an RC1 Connection, an unload gap must not reopen the
+ *      route through the weaker loopback fence — a local socket peer is not the
+ *      same statement as an authorized browser.
+ *   4. No Connection and none ever seen: this is a pre-RC1 host, and the
+ *      plugin's own guard is the whole boundary, so it decides.
+ *
+ * These two codes and their wording state the decision itself rather than a
+ * plugin's published vocabulary, so they are not policy and are not injectable;
+ * only wording that legitimately differs between plugins belongs in a table.
+ */
+export const createBrowserAuthorizer = ({ getConnection, getConnectionSeen, guard, respond = sendJson }) => {
+  if (typeof getConnection !== 'function') {
+    throw new Error('createBrowserAuthorizer: getConnection must be an accessor (`() => connection`); a Connection captured here is stale the first time the service reloads')
+  }
+  if (typeof getConnectionSeen !== 'function') {
+    throw new Error('createBrowserAuthorizer: getConnectionSeen must be an accessor (`() => connectionSeen`); the latch is set once an RC1 Connection exists and must never be read from a captured copy')
+  }
+  if (typeof guard !== 'function') {
+    throw new Error('createBrowserAuthorizer: guard is required; a host without an RC1 Connection falls back to the plugin request guard')
+  }
+
+  return function authorizeBrowser(req, res) {
+    const connection = getConnection()
+    if (connection) {
+      let rejection
+      try {
+        rejection = connection.requestRejection(req)
+      } catch {
+        return connectionUnavailable(res, respond)
+      }
+      if (rejection !== undefined) {
+        respond(res, rejection, {
+          ok: false,
+          code: rejection === 401 ? 'unauthorized' : 'forbidden',
+          error: rejection === 401 ? 'browser authentication required' : 'request rejected'
+        })
+        return false
+      }
+      return true
+    }
+    // Once an RC1 Connection has existed, a reload gap answers 503 — it does not
+    // downgrade to the guard fence.
+    if (getConnectionSeen()) return connectionUnavailable(res, respond)
+    return guard(req, res)
+  }
+}
+
+/**
+ * Accept only a bounded, plausible session id from query or body input.
+ * Returns the trimmed value or null; `null` is the caller's "missing/invalid"
+ * signal, so an empty string never reaches a lookup.
+ */
+export function optionalSessionId(value) {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (!trimmed || trimmed.length > 512) return null
+  return trimmed
+}