dsh-mini-utility-dock 0.1.1 → 0.1.3

package/CHANGELOG.en.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.3 - 2026-09-14
+
+- Add two host-side fragments. `dist/loopback.js` (`dsh-loopback-helpers`) exports `LOOPBACK_HOSTNAMES`, `normalizeHostValue`, `hostHostname`, `isLoopbackName` and `isLoopbackAddress`. `dist/guard.js` (`dsh-host-guard`) exports `portOf`, `GUARD_REASONS`, `DEFAULT_GUARD_POLICY` and an internal `bindGuard()` factory; a consumer passes its own error codes and wording as `policy`, so the enforcement does not fork per plugin.
+- `sync` / `check` now maintain **every** marked fragment in the target file, applied bottom-up in `FRAGMENTS` order, instead of requiring exactly one block. Single-block callers are unaffected.
+- Correct the READMEs and the package description: each host-side fragment's responsibility, the fixed order, and why `bindGuard` is not exported.
+- Add tests for multi-block sync and idempotent `check`, block order, the absence of `import`/`require` in either fragment, and `bindGuard` staying private with no duplicated predicates.
+
+## 0.1.2 - 2026-09-06
+
+- Fix the README `npm run dock:embed` examples: add the previously missing `dock:embed` script to `package.json` and switch the usage to `npm run dock:embed -- check|sync path/to/client.js` (npm argument passing needs the `--` separator, and the CLI takes `sync|check` subcommands, not `--check`). A new smoke test extracts the documented commands from both READMEs and runs them, preventing docs/script drift.
+
 ## 0.1.1 - 2026-09-04
 
 - Normalize `label` in `register()`: a missing, blank, or non-string label falls back to `id`, so no item renders `aria-label="undefined"`.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.3 - 2026-09-14
+
+- 新增两个 host 侧片段：`dist/loopback.js`（`dsh-loopback-helpers`）导出 `LOOPBACK_HOSTNAMES`、`normalizeHostValue`、`hostHostname`、`isLoopbackName`、`isLoopbackAddress`；`dist/guard.js`（`dsh-host-guard`）导出 `portOf`、`GUARD_REASONS`、`DEFAULT_GUARD_POLICY` 与内部的 `bindGuard()` 工厂。调用方以 `policy` 传入自己的错误码与文案，判定逻辑不随之分叉。
+- `sync` / `check` 改为处理目标文件中**所有**已标记的片段，按 `FRAGMENTS` 顺序自下而上应用，不再要求恰好一个块。单块调用方的行为不变。
+- 修正 README 与包描述：说明 host 侧两个片段各自的职责、固定顺序，以及 `bindGuard` 不导出的原因。
+- 新增测试：多块同步与幂等 `check`、块顺序、两个片段均不引入 `import`/`require`、`bindGuard` 不导出且判据不被重复声明。
+
+## 0.1.2 - 2026-09-06
+
+- 修正 README 的 `npm run dock:embed` 示例：补上 `package.json` 缺失的 `dock:embed` 脚本，用法改为 `npm run dock:embed -- check|sync path/to/client.js`（npm 传参需要 `--` 分隔符，CLI 接受 `sync|check` 子命令而非 `--check`）。新增从双语 README 提取命令逐条执行的 smoke test，防止文档与脚本漂移。
+
 ## 0.1.1 - 2026-09-04
 
 - 归一化 `register()` 的 `label`：缺省、空白或非字符串的 `label` 回退为 `id`，避免渲染出 `aria-label="undefined"`。

package/README.en.md

@@ -1,21 +1,53 @@
 # dsh-mini-utility-dock
 
-The shared DSH utility dock package. It provides a canonical, self-contained classic-script fragment and a build-time CLI for embedding it into a plugin `client.js`.
+Source fragments and an embedding CLI shared by the DSH plugins. Fragments are written into a consumer at build time, so a plugin publishes standalone with no dependency on this package.
 
-Put these markers in the client file:
+## Fragments
 
-```js
-  // <dsh-mini-utility-dock>
-  // </dsh-mini-utility-dock>
+Three fragments, each delimited by markers.
+
+| Fragment | Marker | Target file | Exports |
+| --- | --- | --- | --- |
+| dock bootstrap | `dsh-mini-utility-dock` | `lib/client.js` | — |
+| loopback predicates | `dsh-loopback-helpers` | `lib/shared.js` | `LOOPBACK_HOSTNAMES`, `normalizeHostValue`, `hostHostname`, `isLoopbackName`, `isLoopbackAddress` |
+| host request guard | `dsh-host-guard` | `lib/shared.js` | `portOf`, `GUARD_REASONS`, `DEFAULT_GUARD_POLICY` |
+
+`dsh-loopback-helpers` decides address locality; the Host-header path and the TCP-peer path share one decision. `dsh-host-guard` decides admission, and provides a `bindGuard()` factory internally.
+
+## Usage
+
+Write the markers into the target file, then run the CLI.
+
+```sh
+npx dsh-mini-utility-dock sync path/to/client.js
+npx dsh-mini-utility-dock check path/to/client.js
 ```
 
-Run `npx dsh-mini-utility-dock sync path/to/client.js` to embed the current fragment, or `... check ...` in CI. Marker indentation is preserved. The fragment deduplicates itself through the page-local global protocol v1.
+`sync` preserves the markers and their indentation and writes the fragment; `check` exits non-zero when the content no longer matches it. The CLI maintains every marked fragment in the target file, applied bottom-up in `FRAGMENTS` order. A file containing a single fragment is unaffected.
 
-You can also embed from this repo's own script (it never hard-codes a consumer path; the target is passed by the caller):
+This repository also exposes an equivalent entry point, with the target path passed by the caller:
 
 ```sh
-npm run dock:embed --check path/to/client.js   # verify only, non-zero on drift
-npm run dock:embed path/to/client.js           # write between the markers
+npm run dock:embed -- check path/to/client.js  # verify only, non-zero on drift
+npm run dock:embed -- sync path/to/client.js   # write between the markers
 ```
 
-When registering, a missing, blank, or non-string `label` falls back to `id` as the accessible name, avoiding `aria-label="undefined"`.
+Consumers invoke the same CLI as `loopback:sync` / `guard:sync`, with the target fixed to their own `lib/shared.js`; either command maintains both fragments in that file.
+
+## The two host-side fragments
+
+The two fragments in `lib/shared.js` have a fixed order, `dsh-loopback-helpers` first.
+
+The order is a functional requirement, not a style choice. Both fragments occupy one file, and `dsh-host-guard` uses the module-scope names the preceding fragment exports. It therefore neither redeclares those predicates nor imports a sibling module: redeclaring collides with the declaration in the same file, and importing would break the standalone-publication constraint. The `guard-parity` check fails when the order is reversed.
+
+`bindGuard` is not exported from the fragment. A consumer declares its own guard export in the same file (typically reusing an existing name such as `createGuard`), and exporting the same identifier would collide. Each plugin calls `bindGuard()` and passes its own error codes and wording through `policy`: the enforcement is shared, the error vocabulary stays with each plugin.
+
+## Development
+
+`dist/` is the single source for each fragment. Run `npm test` after a change; consumers that have already embedded a fragment must re-run the matching `sync` command.
+
+A fragment must not contain `import` or `require`: it shares a file with the consumer's own code, and the consumer must publish standalone. Tests assert this constraint.
+
+## Registration
+
+A missing, blank, or non-string `label` falls back to `id`, so no item renders `aria-label="undefined"`.

package/README.md

@@ -1,30 +1,53 @@
 # dsh-mini-utility-dock
 
-DSH 插件共享的 utility dock：提供一个 canonical classic-script 片段，并在构建时嵌入插件的 `client.js`。
+DSH 插件共享的源码片段与嵌入 CLI。片段在构建时写入消费插件，使插件无需依赖本包即可独立发布。
 
-## 使用
+## 片段
 
-在目标文件中放置标记：
+三个片段，均由标记界定。
 
-```js
-  // <dsh-mini-utility-dock>
-  // </dsh-mini-utility-dock>
-```
+| 片段 | 标记 | 目标文件 | 导出 |
+| --- | --- | --- | --- |
+| dock 引导 | `dsh-mini-utility-dock` | `lib/client.js` | — |
+| loopback 判定 | `dsh-loopback-helpers` | `lib/shared.js` | `LOOPBACK_HOSTNAMES`、`normalizeHostValue`、`hostHostname`、`isLoopbackName`、`isLoopbackAddress` |
+| host 请求守卫 | `dsh-host-guard` | `lib/shared.js` | `portOf`、`GUARD_REASONS`、`DEFAULT_GUARD_POLICY` |
 
-然后运行：
+`dsh-loopback-helpers` 定义地址的归属：Host 头与 TCP 对端两条路径共用同一判定。`dsh-host-guard` 定义准入策略，并在内部提供 `bindGuard()` 工厂。
+
+## 使用
+
+在目标文件中写入标记，然后运行 CLI。
 
 ```sh
 npx dsh-mini-utility-dock sync path/to/client.js
 npx dsh-mini-utility-dock check path/to/client.js
 ```
 
-`sync` 保留标记及其缩进；`check` 在内容漂移时以非零状态退出。内嵌脚本通过 global protocol v1 在页面内去重，插件仍可单独运行。
+`sync` 保留标记及其缩进并写入片段；`check` 在内容与片段不一致时以非零状态退出。CLI 处理目标文件中所有已标记的片段，按 `FRAGMENTS` 顺序自下而上应用。仅含单个片段的文件行为不变。
 
-也可用本仓库脚本同步（不硬编码任何消费仓路径，目标由调用方传入）：
+本仓库另提供等价入口，目标路径由调用方传入：
 
 ```sh
-npm run dock:embed --check path/to/client.js   # 仅校验，漂移时非零退出
-npm run dock:embed path/to/client.js           # 写入标记之间
+npm run dock:embed -- check path/to/client.js  # 仅校验，漂移时非零退出
+npm run dock:embed -- sync path/to/client.js   # 写入标记之间
 ```
 
-注册时若 `label` 缺省、空白或非字符串，会回退为 `id` 作为可访问名称，避免 `aria-label="undefined"`。
+消费插件以 `loopback:sync` / `guard:sync` 调用同一 CLI，目标固定为自身的 `lib/shared.js`；任一命令都会同步该文件中的两个片段。
+
+## host 侧两个片段的约定
+
+`lib/shared.js` 中的两个片段顺序固定，`dsh-loopback-helpers` 在前。
+
+顺序是功能要求，不是风格约定。两者位于同一文件，`dsh-host-guard` 直接使用前一片段导出的模块级名字，因此它既不重新声明这些判据，也不 import 兄弟模块：重新声明与 import 都会与同文件内的声明冲突，且 import 会破坏插件独立发布的约束。`guard-parity` 检查在该顺序被颠倒时失败。
+
+`bindGuard` 不从片段导出。消费插件在同一文件中声明自己的 guard 导出（通常沿用 `createGuard` 等既有名字），导出同名标识符会冲突。每个插件调用 `bindGuard()`，通过 `policy` 传入自身的错误码与文案；判定逻辑共用，错误词汇由各插件持有。
+
+## 开发
+
+片段的唯一来源是 `dist/`。修改后运行 `npm test`；已嵌入片段的消费插件需重新运行对应的 `sync` 命令。
+
+片段不得包含 `import` 或 `require`：它们与消费插件自身的代码位于同一文件，且消费插件必须独立发布。测试对此约束进行断言。
+
+## 注册
+
+`label` 缺省、空白或非字符串时回退为 `id`，避免渲染出 `aria-label="undefined"`。

package/bin/dsh-mini-utility-dock.js

@@ -1,15 +1,53 @@
 #!/usr/bin/env node
+// Embed a canonical fragment from this package into a consumer file.
+//
+// Two fragments are maintained the same way, because both have the same shape
+// of problem: the consumer must ship the code standalone (a browser classic
+// script cannot `import`, and a host half must not depend on the dock being
+// installed), so the code is embedded at build time and drift is a build error.
+//
+//   dsh-mini-utility-dock  -> <dsh-mini-utility-dock> ... </dsh-mini-utility-dock>
+//     the Mini Utility Dock bootstrap, embedded into a plugin's lib/client.js
+//
+//   dsh-loopback-helpers   -> <dsh-loopback-helpers> ... </dsh-loopback-helpers>
+//     the loopback predicates, embedded into a plugin's lib/shared.js
+//
+//   dsh-host-guard         -> <dsh-host-guard> ... </dsh-host-guard>
+//     the same-origin request guard, embedded into the same file
+//
+// The host half of a plugin embeds BOTH shared.js fragments, in the order above,
+// because the guard imports the predicates. Each is an independent block with its
+// own markers and its own check, so a plugin that only needs the predicates can
+// embed just those.
+//
+// The fragment is selected by the marker already present in the target file, so
+// one command serves either target. A consumer calls this through its own
+// `dock:sync` / `guard:sync` script; the paired `check` mode is what CI runs.
+
 import { readFile, writeFile, stat } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const START = '// <dsh-mini-utility-dock>'
-const END = '// </dsh-mini-utility-dock>'
+// Listed in dependency order: the guard fragment reads the predicates the
+// loopback fragment declares, so a consumer that wants the guard syncs both, in
+// this order, into the same file.
+const FRAGMENTS = [
+  { name: 'dsh-mini-utility-dock', source: 'bootstrap.js' },
+  { name: 'dsh-loopback-helpers', source: 'loopback.js' },
+  { name: 'dsh-host-guard', source: 'guard.js' }
+]
+
 const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
-const bootstrapPath = resolve(packageRoot, 'dist', 'bootstrap.js')
+const marker = (name, edge) => `// <${edge}${name}>`
 
 function usage() {
-  return 'Usage: dsh-mini-utility-dock <sync|check> <client-file>'
+  const fragments = FRAGMENTS.map((f) => `  ${marker(f.name, '')} -> dist/${f.source}`).join('\n')
+  return [
+    'Usage: dsh-mini-utility-dock <sync|check> <consumer-file>',
+    '',
+    'The fragment is chosen by the marker already present in <consumer-file>:',
+    fragments
+  ].join('\n')
 }
 
 function error(message) {
@@ -18,11 +56,11 @@ function error(message) {
 }
 
 async function loadTarget(fileName) {
-  if (!fileName || fileName.startsWith('-')) throw new Error('client-file is required')
+  if (!fileName || fileName.startsWith('-')) throw new Error('consumer-file is required')
   const target = resolve(fileName)
   const info = await stat(target).catch(() => null)
   if (!info) throw new Error(`file does not exist: ${target}`)
-  if (!info.isFile()) throw new Error(`client-file is not a regular file: ${target}`)
+  if (!info.isFile()) throw new Error(`consumer-file is not a regular file: ${target}`)
   return { target, source: await readFile(target, 'utf8') }
 }
 
@@ -30,43 +68,66 @@ function indentation(line) {
   return (/^[ \t]*/.exec(line) || [''])[0]
 }
 
+// Locate every marked block in the file, in fragment order. A host half embeds
+// both shared.js fragments, so one command must maintain both; processing them in
+// FRAGMENTS order also keeps the dependency order (the guard reads the predicates
+// declared by the loopback block above it).
 function locate(source) {
   const lines = source.split(/\r?\n/)
-  const starts = lines.reduce((found, line, index) => line.trim() === START ? [...found, index] : found, [])
-  const ends = lines.reduce((found, line, index) => line.trim() === END ? [...found, index] : found, [])
-  if (starts.length !== 1 || ends.length !== 1 || ends[0] <= starts[0]) {
-    throw new Error(`expected exactly one marked block (${START} ... ${END})`)
+  const candidates = FRAGMENTS.map((fragment) => {
+    const start = lines.reduce((hits, line, i) => line.trim() === marker(fragment.name, '') ? [...hits, i] : hits, [])
+    const end = lines.reduce((hits, line, i) => line.trim() === marker(fragment.name, '/') ? [...hits, i] : hits, [])
+    return { fragment, start, end }
+  }).filter((candidate) => candidate.start.length || candidate.end.length)
+
+  if (candidates.length === 0) {
+    throw new Error(`no fragment marker found; expected at least one marked block (${FRAGMENTS.map((f) => marker(f.name, '')).join(' or ')})`)
+  }
+  for (const { fragment, start, end } of candidates) {
+    if (start.length !== 1 || end.length !== 1 || end[0] <= start[0]) {
+      throw new Error(`expected exactly one marked block for ${fragment.name} (${marker(fragment.name, '')} ... ${marker(fragment.name, '/')})`)
+    }
   }
-  return { lines, start: starts[0], end: ends[0], indent: indentation(lines[starts[0]]) }
+  return { lines, blocks: candidates.map(({ fragment, start, end }) => ({ fragment, start: start[0], end: end[0] })) }
 }
 
-function rendered(source, bootstrap) {
-  const newline = source.includes('\r\n') ? '\r\n' : '\n'
-  const block = locate(source)
-  const body = bootstrap.replace(/\r?\n$/, '').split(/\r?\n/)
-    .map((line) => line ? block.indent + line : '')
-  const output = [...block.lines.slice(0, block.start + 1), ...body, ...block.lines.slice(block.end)]
-    .join(newline)
-  return { output, block }
+function rendered(lines, fragmentSource, block) {
+  const indent = indentation(lines[block.start])
+  const body = fragmentSource.replace(/\r?\n$/, '').split(/\r?\n/)
+    .map((line) => line ? indent + line : '')
+  return [...lines.slice(0, block.start + 1), ...body, ...lines.slice(block.end)]
 }
 
+// Applied from the LAST block to the first. Each pass replaces a line range, so
+// doing it bottom-up leaves every earlier block's line indices valid; going
+// top-down would shift them and a later pass would splice the wrong lines.
 async function main() {
   const [command, fileName, ...rest] = process.argv.slice(2)
   if (!['sync', 'check'].includes(command) || !fileName || rest.length) throw new Error(usage())
   const { target, source } = await loadTarget(fileName)
-  const bootstrap = await readFile(bootstrapPath, 'utf8')
-  const result = rendered(source, bootstrap)
+  const located = locate(source)
+
+  let lines = located.lines
+  const applied = []
+  for (const block of [...located.blocks].reverse()) {
+    const fragmentSource = await readFile(resolve(packageRoot, 'dist', block.fragment.source), 'utf8')
+    lines = rendered(lines, fragmentSource, block)
+    applied.unshift(block.fragment.name)
+  }
+  const output = lines.join(source.includes('\r\n') ? '\r\n' : '\n')
+
+  const names = applied.join(', ')
   if (command === 'check') {
-    if (source !== result.output) throw new Error(`marked block is out of date: ${target}`)
-    console.log(`ok: ${target}`)
+    if (output !== source) throw new Error(`marked block is out of date: ${target} (${names})`)
+    console.log(`ok: ${target} (${names})`)
     return
   }
-  if (source === result.output) {
-    console.log(`unchanged: ${target}`)
+  if (source === output) {
+    console.log(`unchanged: ${target} (${names})`)
     return
   }
-  await writeFile(target, result.output, 'utf8')
-  console.log(`synced: ${target}`)
+  await writeFile(target, output, 'utf8')
+  console.log(`synced: ${target} (${names})`)
 }
 
 main().catch((cause) => error(cause instanceof Error ? cause.message : String(cause)))

package/dist/guard.js

@@ -0,0 +1,167 @@
+// Host-side request guard shared by the DSH plugins.
+//
+// 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
+//   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 works with no sibling installed.
+//
+// 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
+// this module uses the predicates that block exports in the same file rather than
+// restating them: `hostHostname`, `isLoopbackName` and `isLoopbackAddress` are
+// module-scope names here, declared by the block above. That keeps one copy of
+// them in a consumer, and makes the dependency one-way and visible — `guard:sync`
+// needs `loopback:sync` to have produced a `lib/shared.js` that declares them.
+//
+// There is deliberately no `import` here. A consumer embeds both blocks into one
+// file, so an import of a sibling 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: the three plugins
+// each carried their own `createGuard`, and the copies diverged three times. 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.
+
+// 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.
+const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' }
+export const portOf = (url) => url.port || DEFAULT_PORTS[url.protocol] || ''
+
+// The reasons this guard can reject. Each is a stable, guard-owned name for one
+// decision; the *reason* is fixed here, while the machine-readable `code` a
+// 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.
+export const GUARD_REASONS = Object.freeze([
+  'non_loopback_peer',
+  'cross_site',
+  'unknown_peer',
+  'foreign_origin',
+  'non_loopback_host'
+])
+
+/** Default machine-readable codes and wording, in English, per reason. */
+export const DEFAULT_GUARD_POLICY = Object.freeze({
+  non_loopback_peer: { code: 'non_loopback_peer', error: 'non-loopback peer rejected' },
+  cross_site: { code: 'cross_site', error: 'cross-site request rejected' },
+  unknown_peer: { code: 'unknown_peer', error: 'peer address is not identifiable' },
+  foreign_origin: { code: 'foreign_origin', error: 'foreign origin rejected' },
+  non_loopback_host: { code: 'non_loopback_host', error: 'non-loopback host rejected' }
+})
+
+/**
+ * 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.
+ *
+ * Enforces, in order: Fetch Metadata, an unparseable Host, the TCP peer address,
+ * then the Host allowlist, then the Origin. Rejects by calling
+ * `respond(res, 403, { ok: false, code, error })` and returning false; returns
+ * true when the request may proceed.
+ *
+ * @param currentPort - the port this server listens on. A function is called per
+ *   request so an Origin check follows a server whose port changes; a plain
+ *   value is accepted for a fixed server.
+ * @param respond - rejection sink, normally the plugin's `sendJson`. Kept
+ *   injectable so tests can capture the rejection code instead of standing up a
+ *   real ServerResponse.
+ * @param allowRemoteHost - optional predicate. When it returns true, an
+ *   off-loopback peer AND an off-loopback Host are admitted, because the caller
+ *   has opted into verifying its own credential per request; the guard
+ *   deliberately knows nothing about tokens. The Origin check still applies, so
+ *   the exemption never widens the browser-facing boundary. A plugin that omits
+ *   the predicate keeps absolute peer and Host criteria.
+ * @param policy - optional per-reason `{ code, error }` overrides, keyed by
+ *   `GUARD_REASONS`. A partial override merges with the default, so a plugin
+ *   names only the reasons whose vocabulary differs. An unknown key throws: a
+ *   typo would otherwise silently leave the default in place, and the plugin
+ *   would expose a code no test expects.
+ */
+const bindGuard = ({ currentPort, respond, allowRemoteHost, policy } = {}) => {
+  const port = typeof currentPort === 'function' ? currentPort : () => currentPort
+  const overrides = policy || {}
+  for (const key of Object.keys(overrides)) {
+    if (!GUARD_REASONS.includes(key)) {
+      throw new Error(`bindGuard: unknown policy key ${JSON.stringify(key)}; expected one of ${GUARD_REASONS.join(', ')}`)
+    }
+  }
+  const say = Object.fromEntries(GUARD_REASONS.map((reason) => [
+    reason,
+    { ...DEFAULT_GUARD_POLICY[reason], ...(overrides[reason] || {}) }
+  ]))
+  const deny = (res, reason) => {
+    respond(res, 403, { ok: false, code: say[reason].code, error: say[reason].error })
+    return false
+  }
+  const fleetAllowed = () => typeof allowRemoteHost === 'function' && allowRemoteHost()
+
+  return function guard(req, res) {
+    const headers = (req && req.headers) || {}
+
+    const site = headers['sec-fetch-site']
+    if (site !== undefined && site !== 'same-origin' && site !== 'none') {
+      return deny(res, 'cross_site')
+    }
+
+    const host = headers.host || ''
+    const parsedHost = host ? hostHostname(host) : ''
+    // An empty parse is not permission. A Host header that carries no usable
+    // hostname — an unbracketed IPv6 literal such as `::1:3080`, which RFC 7230
+    // forbids but a client can still send — parses to '', and reading that as a
+    // pass would skip the allowlist. It is a Host problem, so it is reported as
+    // one. An ABSENT Host stays loopback so host-side callers keep working.
+    if (host && parsedHost === '') {
+      return deny(res, 'non_loopback_host')
+    }
+    const peerAddress = req.socket ? req.socket.remoteAddress : undefined
+    if (peerAddress == null || String(peerAddress).trim() === '') {
+      return deny(res, 'unknown_peer')
+    }
+    // `allowRemoteHost` buys exactly one thing: an off-loopback peer AND an
+    // off-loopback Host stop being admitted by this guard, because the caller has
+    // opted into verifying its own credential per request. Everything else still
+    // applies — the Origin check below rejects cross-site traffic in both modes,
+    // so the exemption never widens the browser-facing boundary. A plugin that
+    // does not pass the predicate never enters this mode, so for it the peer and
+    // Host criteria are absolute.
+    const remote = fleetAllowed()
+    if (!remote && !isLoopbackAddress(peerAddress)) {
+      return deny(res, 'non_loopback_peer')
+    }
+    const hostLoopback = host ? (parsedHost !== '' && isLoopbackName(parsedHost)) : true
+    if (!remote && !hostLoopback) {
+      return deny(res, 'non_loopback_host')
+    }
+
+    const origin = headers.origin
+    if (origin) {
+      let same = false
+      try {
+        const parsed = new URL(origin)
+        same = isLoopbackName(hostHostname(parsed.hostname)) &&
+          portOf(parsed) === String(port() || '')
+      } catch {
+        same = false
+      }
+      if (!same) return deny(res, 'foreign_origin')
+    }
+
+    return true
+  }
+}

package/dist/loopback.js

@@ -0,0 +1,99 @@
+// Loopback predicates shared by the host halves of the DSH plugins.
+//
+// This fragment has ONE source of truth: dsh-mini-utility-dock/dist/loopback.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
+//   npm run loopback:sync    (write it)
+//   npm run loopback: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 works with no sibling installed.
+//
+// Why it is shared at all: these predicates were copy-pasted per repo and
+// drifted twice. The first drift rejected IPv6 loopback in all three plugins;
+// the second made the three disagree on which Host spellings count as loopback
+// (see scripts/guard-parity.mjs, which compares this block across repos).
+//
+// "Loopback" is decided in exactly one place — LOOPBACK_HOSTNAMES plus the
+// IPv4-mapped IPv6 form of each entry — and both the name and the address
+// predicate route through it, so the Host path and the peer path cannot drift
+// apart again.
+//
+// Kept a separate fragment from the host guard on purpose: the predicates are
+// stable facts about what an address is, while the guard is a policy about who
+// may call an API. `dist/guard.js` imports this module, so the guard depends on
+// this block and never the other way round.
+
+// Hostnames a request to a loopback-bound API may legitimately arrive with.
+// Exact spellings only: `api.localhost` and `127.0.0.1.evil.example` must stay
+// rejected, which is what keeps DNS rebinding out of the API surface.
+export const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '::1']
+
+// Canonicalize a Host-like value. Trims both ends and lowercases, so the
+// allowlist match is case-insensitive and tolerates surrounding whitespace.
+export const normalizeHostValue = (value) => String(value == null ? '' : value).trim().toLowerCase()
+
+// Pull the hostname out of a Host header: "127.0.0.1:3080" -> "127.0.0.1",
+// "[::1]:3080" -> "::1". A bracketed IPv6 literal carries its colons inside the
+// brackets, so the brackets decide where the host ends, not the first colon.
+export const hostHostname = (host) => {
+  const value = normalizeHostValue(host)
+  const bracketed = /^\[([^\]]+)\]/.exec(value)
+  return bracketed ? bracketed[1] : value.split(':')[0]
+}
+
+// The IPv4 address inside an IPv4-mapped IPv6 literal, or null. Node reports a
+// v4 peer on a dual-stack socket in the mapped form, so this is a routine input,
+// not an exotic one. Two spellings reach us and both must work:
+//
+//   ::ffff:127.0.0.1   what Node puts in req.socket.remoteAddress, and what a
+//                      client may legally write in a Host header
+//   ::ffff:7f00:1      what the WHATWG URL parser normalises the above to, so
+//                      this is the shape a browser's Origin header produces
+//
+// The v4 part is validated as four decimal octets, so `::ffff:1.2.3` and
+// `::ffff:999.1.1.1` are not addresses and fail closed.
+const mappedIpv4 = (value) => {
+  if (!value.startsWith('::ffff:')) return null
+  const rest = value.slice(7)
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(rest)) {
+    return rest.split('.').every((octet) => Number(octet) <= 255) ? rest : null
+  }
+  // Hex form: ::ffff:7f00:1 -> 127.0.0.1. Exactly two groups, four hex digits
+  // each, as the URL parser emits.
+  const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(rest)
+  if (!hex) return null
+  const high = parseInt(hex[1], 16)
+  const low = parseInt(hex[2], 16)
+  return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`
+}
+
+/**
+ * True when `name` is a loopback hostname — the Host-header side of the guard.
+ * Accepts the documented spellings, the IPv4-mapped IPv6 form of 127.0.0.1, and
+ * folds case. Fails closed on everything else, including a missing name.
+ */
+export const isLoopbackName = (name) => {
+  const value = normalizeHostValue(name)
+  if (!value) return false
+  if (LOOPBACK_HOSTNAMES.indexOf(value) !== -1) return true
+  const ipv4 = mappedIpv4(value)
+  return ipv4 !== null && LOOPBACK_HOSTNAMES.indexOf(ipv4) !== -1
+}
+
+/**
+ * True when `address` is a real loopback TCP peer address.
+ * Headers cannot identify the network peer — a client sets `Host` freely — so
+ * the socket address is the only trustworthy signal. Fail closed on anything
+ * unrecognised, including a missing address.
+ */
+export const isLoopbackAddress = (address) => {
+  const value = normalizeHostValue(address)
+  if (!value) return false
+  if (value === '::1') return true
+  // IPv4-mapped IPv6 (`::ffff:127.0.0.1`) is how Node reports a v4 peer on a
+  // dual-stack socket; fold it back before the 127/8 test.
+  const mapped = mappedIpv4(value)
+  if (mapped !== null) return /^127\./.test(mapped)
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(value)
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mini-utility-dock",
-  "version": "0.1.1",
-  "description": "Shared classic-script utility dock protocol for DSH plugins.",
+  "version": "0.1.3",
+  "description": "Canonical fragments and a build-time embedding CLI shared by DSH plugins: the Mini Utility Dock bootstrap for client halves, and the loopback predicates plus the host request guard for host halves.",
   "type": "module",
   "bin": {
     "dsh-mini-utility-dock": "bin/dsh-mini-utility-dock.js"
@@ -16,6 +16,7 @@
     "CHANGELOG.en.md"
   ],
   "scripts": {
+    "dock:embed": "node bin/dsh-mini-utility-dock.js",
     "test": "node --test test/*.test.js"
   },
   "engines": {