@twinsearth/w2m-dsh-plugin 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.23.0] — 2026-10-15
+
+**The gate is on the dispatch path. "分权限" now executes, and a machine that has not opted in behaves exactly as before.**
+
+`src/plugin/tools.mjs` calls `gateDispatch()` immediately after the write-scope check — placed there so the
+thing being graded is already known to be well-formed — and refuses the dispatch when the verdict is not
+`allow`.
+
+### `actorAuthorityLevel`, and why it is not shared config
+
+Read from the plugin config, or `W2M_ACTOR_AUTHORITY` so a machine can be pointed at a level without editing a
+profile. **Deliberately not part of `shared.values`**: this is a local statement about who is typing, and a
+fleet-wide value would let one machine's level speak for another's operator.
+
+**`null` is not `0`.** An unset level means there is no actor to judge, and the gate reports `enforced: false`
+and changes nothing — which is why adding this cannot alter the behaviour of any machine that has not opted
+in. A refusal for everyone who never configured a level would have been the easy implementation and the wrong
+one.
+
+### What a refusal looks like
+
+Two distinct codes, because they need different responses:
+
+| Code | When | What it means |
+|---|---|---|
+| `W2M_PERMISSION_DENIED` | verdict `deny` | the level is more than one band short, or the capability is undeclared |
+| `W2M_PERMISSION_NEEDS_APPROVAL` | verdict `needs_approval` | the level is exactly one band short |
+
+The `needs_approval` refusal **carries the approval request** that `approvalRequestFor()` built — subject
+level, required level, capability, `auto_settleable` — and says plainly that it is refused rather than queued
+**because no approval queue is wired to this call yet.** Refusing and saying why is honest; queueing a request
+nothing reads would not be.
+
+### A defect I introduced while wiring it, and how it surfaced
+
+The first edit **corrupted the file**: the anchor for the config field matched only the first line of a
+multi-line expression, so it cut `allowedCommands` off from its own `.filter().map().filter()` chain and left
+the orphan chained onto my insertion. A second attempt then wrote literal backslashes into the source by
+escaping backticks that did not need escaping.
+
+Both were caught by `node --check` immediately, which is the argument for running it after every write rather
+than after the batch. Neither reached a commit.
+
+**120 tests across the tools, permission and entrypoint suites, 0 failures.**
+
+## [0.22.0] — 2026-10-15
+
+**The gate now grades a real dispatch, and connects to the approval queue.**
+
+0.21.0 built the gate and admitted it had no caller. This release gives it one: `gateDispatch()` reads a
+dispatch's **own** facts — `write` and a non-empty `write_scope`, both already in the payload — and grades it,
+rather than asking the caller to name a capability. That distinction is the whole design: **a caller who must
+name their own capability is a caller who can name the cheap one.**
+
+### The unset level, which is the honest part
+
+`tools.mjs` states plainly that **no parameter of any tool can widen what a machine will run**, and that there
+is no way for a caller to set anything authority-shaped. So a plugin with no configured actor level has no
+actor to judge. Two answers were available:
+
+* treat an unset level as `0` — which would **refuse every writing dispatch on every machine that has not opted
+  in**, breaking a working fleet to enforce a policy nobody asked for;
+* treat it as **unenforced, and say so**.
+
+This does the second, and `enforced` is the whole point: **a gate that reports `ALLOW` and a gate that reports
+"not checked" must never look alike, because the first is a decision and the second is the absence of one.**
+A test asserts exactly that — same verdict, different `enforced`, different `reason_code`.
+
+### The escalation reaches the queue it was built for
+
+`approvalRequestFor()` returns `null` for anything that is not `NEEDS_APPROVAL`, and otherwise produces a
+request shaped for the cross-session approval index built in 0.10.0 — **the two features finally meet**, which
+is the point: a permission gate and an approval queue that do not connect are two things that each look
+finished and jointly do nothing.
+
+The request carries the **subject level recorded now**, not left to be re-derived later, for the reason
+0.10.0's index already states: an approver who could supply the subject level could lower it. A destructive
+request is marked `auto_settleable: false` explicitly, rather than leaving the queue to infer it from a
+capability name.
+
+### A `write` with no scope is graded as the dearer capability
+
+The dispatch path refuses that combination separately. Grading it cheap here would mean that if that check
+ever moved, a request intending to write would be handed the read-only permission.
+
+### A test of mine was wrong, again in the same direction
+
+`gateDispatch({write: true}, 0)` was asserted to be `deny`; it is `needs_approval`, **because an ordinary
+actor is exactly one band below captain and that is the documented behaviour.** The implementation was right.
+This is the fourth time in this project that a failing test was the test's fault — and it is the argument for
+testing refusals rather than only the happy path, because a wrong refusal fails loudly enough to be told apart
+from a wrong acceptance.
+
+**11 new tests, 0 failures.**
+
 ## [0.21.0] — 2026-10-15
 
 **The capability table has a gate now, so it is a policy rather than a description of one.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "DSH: Windows2MacOS — drive the same project on online Windows and macOS machines from one DeepSeek account, across networks and regions. P2P hole punching is the default path (relay + shared server as rendezvous, ledger and fallback), with a bundled STUN responder, Tailscale/public-VPS/tunnel shapes, Rabbit relay + per-machine Localside + eight DSH tools (replicate / split), nine aggregate verdicts and signed requests.",
   "type": "module",
   "main": "lib/index.js",

package/src/agent/authority.mjs

@@ -38,9 +38,69 @@ export const AUTHORITY_BANDS = Object.freeze([
   { name: 'system_admin', min: 90, max: null, may: 'create global goals, configure across organisations, override any lower constraint' },
 ]);
 
+/**
+ * The band floors, as named constants, for callers that want a level rather than a range.
+ *
+ * `AUTHORITY_BANDS` above is the model — ranges with prose about what each band may do. This is the lookup a
+ * caller reaches for when it wants "the captain floor" as a number, and it exists here rather than in
+ * `scripts/layer-model.mjs` because it is a view of the same table and the two must not be able to drift.
+ *
+ * Derived from `AUTHORITY_BANDS` rather than written out, so adding a band cannot leave this behind.
+ */
+export const AUTHORITY_BAND_FLOORS = Object.freeze(
+  Object.fromEntries(AUTHORITY_BANDS.map((b) => [b.name.toUpperCase(), b.min])),
+);
+
 /** The highest level this model will accept. Above it, a level is a mistake rather than a promotion. */
 export const AUTHORITY_MAX = 100;
 
+/**
+ * What each operational capability costs in authority.
+ *
+ * ## Why this lives here and not in `scripts/`
+ *
+ * It was declared in `scripts/layer-model.mjs` from v0.12.0, and `src/agent/permission.mjs` imported it from
+ * there — which read cleanly and **broke the published package**: `scripts/` is not in `package.json#files`,
+ * so an installed copy could not resolve the import at all. The packed-tarball check caught it, and the check
+ * was right.
+ *
+ * The layering says the same thing: `scripts/` sits *above* `src/`, so a `src/` module reaching up into it
+ * inverts the dependency. The authority model already owns the bands, so the capability table belongs beside
+ * them; `scripts/layer-model.mjs` now imports and re-exports it, keeping that module's public surface intact
+ * for the suites that assert on it.
+ *
+ * ## Why a table and not a set of branches
+ *
+ * `AUTHORITY_BANDS` above says what a band *may* do in prose. This says what each concrete operation *costs*,
+ * as data, so a reader can enumerate it and a test can audit it. The two must not drift, which is why they sit
+ * in one file.
+ */
+export const CAPABILITIES = Object.freeze([
+  { name: 'read_fleet_state', min_authority: 0, destructive: false, note: 'listing machines and tasks changes nothing' },
+  { name: 'dispatch_readonly', min_authority: 0, destructive: false, note: 'a task that may not write' },
+  { name: 'dispatch_writing', min_authority: 50, destructive: false, note: 'a task that may write inside a declared scope' },
+  { name: 'publish_release', min_authority: 70, destructive: true, note: 'a published version cannot be unpublished from here' },
+  { name: 'delete_permanent', min_authority: 90, destructive: true, note: 'overrides the storage tier refusal; forced removal only' },
+  { name: 'amend_law', min_authority: 70, destructive: false, note: 'amendment keeps the chain, so it is not a destruction' },
+  { name: 'write_config', min_authority: 90, destructive: true, note: 'allowedCommands and the relay URL live here' },
+]);
+
+/**
+ * The minimum authority for a capability, or `null` when it is not declared.
+ *
+ * `null` rather than a permissive default: a capability the table has not heard of must not be granted, and
+ * the gate in `permission.mjs` refuses on `null` rather than treating it as free.
+ */
+export function permissionFor(name) {
+  return CAPABILITIES.find((c) => c.name === name)?.min_authority ?? null;
+}
+
+/** Whether a capability is declared destructive. An unknown capability is not assumed safe. */
+export function isDestructive(name) {
+  const found = CAPABILITIES.find((c) => c.name === name);
+  return found === undefined ? null : found.destructive;
+}
+
 /** Verdicts an authority check can reach. */
 export const AUTHORITY_VERDICT = Object.freeze({
   ALLOW: 'allow',

package/src/agent/permission.mjs

@@ -30,8 +30,19 @@
  * table grant whatever is added next, and answering `NEEDS_APPROVAL` makes it requestable. Both are worse than
  * a refusal, because both hide the omission.
  */
-import { CAPABILITIES, permissionFor, isDestructive } from '../../scripts/layer-model.mjs';
-import { AUTHORITY_BANDS, AUTHORITY_MAX, AUTHORITY_VERDICT, bandOf, isAuthorityLevel } from './authority.mjs';
+// v0.23.0: imported from `authority.mjs`, which owns the bands and therefore the costs. It used to come
+// from `scripts/layer-model.mjs`, and that broke the published package -- `scripts/` is not in the `files`
+// list, so an installed copy could not resolve it. A `src/` module must not reach above itself either.
+import {
+  AUTHORITY_BANDS,
+  AUTHORITY_MAX,
+  AUTHORITY_VERDICT,
+  bandOf,
+  isAuthorityLevel,
+  CAPABILITIES,
+  permissionFor,
+  isDestructive,
+} from './authority.mjs';
 
 export { AUTHORITY_VERDICT };
 
@@ -146,6 +157,104 @@ export function decide(capability, level) {
   };
 }
 
+/**
+ * Which capability a dispatch costs, decided from the dispatch's own facts.
+ *
+ * A dispatch that may write costs more than one that may not, and the fact is already in the payload
+ * (`write` plus a non-empty `write_scope`), so this reads it rather than asking the caller to declare a
+ * capability. That matters because a caller who must name their own capability is a caller who can name the
+ * cheap one.
+ *
+ * @param {{write?: boolean, write_scope?: string[]}} args
+ * @returns {{capability: string, detail: string}}
+ */
+export function capabilityForDispatch(args) {
+  const writes = args?.write === true;
+  const scope = Array.isArray(args?.write_scope) ? args.write_scope.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+  if (!writes) return { capability: 'dispatch_readonly', detail: 'write is not true, so the machines cannot write' };
+  if (scope.length === 0) {
+    // A write with no scope is refused upstream by the dispatch path itself. Reporting it as the writing
+    // capability rather than the read-only one is the conservative direction: if that upstream check ever
+    // moved, this would not silently hand out the cheaper permission.
+    return { capability: 'dispatch_writing', detail: 'write is true with an empty scope, which the dispatch path refuses separately' };
+  }
+  return { capability: 'dispatch_writing', detail: `write is true inside ${scope.length} declared scope prefix(es)` };
+}
+
+/**
+ * The gate a dispatch passes through.
+ *
+ * ## Why an unset level is not the same as a low one
+ *
+ * `tools.mjs` states plainly that **no parameter of any tool can widen what a machine will run**, and that
+ * there is no way for a caller to set anything authority-shaped. So a plugin that has not been configured
+ * with an actor level has no actor to judge. Two answers were available and only one is honest:
+ *
+ *   * treat an unset level as `0` — which would refuse every writing dispatch on every machine that has not
+ *     opted in, breaking a working fleet to enforce a policy nobody asked for;
+ *   * treat it as **unenforced**, and say so in the verdict, so the caller can tell "allowed" from "not
+ *     checked".
+ *
+ * The second is what this does, and the `enforced` flag is the whole point: a gate that reports `ALLOW` and a
+ * gate that reports `not checked` must never look alike, because the first is a decision and the second is an
+ * absence of one.
+ *
+ * @param {{write?: boolean, write_scope?: string[]}} args
+ * @param {number|null|undefined} actorLevel
+ * @returns {{decision: object, enforced: boolean, capability: string, detail: string}}
+ */
+export function gateDispatch(args, actorLevel) {
+  const { capability, detail } = capabilityForDispatch(args);
+  if (actorLevel === null || actorLevel === undefined) {
+    return {
+      decision: {
+        verdict: AUTHORITY_VERDICT.ALLOW,
+        capability,
+        level: null,
+        required: permissionFor(capability),
+        shortfall: null,
+        destructive: isDestructive(capability),
+        reason_code: 'GATE_NOT_ENFORCED',
+        detail: 'no authority level is configured, so this dispatch was not checked',
+      },
+      enforced: false,
+      capability,
+      detail: `not enforced: ${detail}; no actor level is configured`,
+    };
+  }
+  return { decision: decide(capability, actorLevel), enforced: true, capability, detail };
+}
+
+/**
+ * Build the approval request for a dispatch that needs one, or `null` when it does not.
+ *
+ * Shaped to hand straight to the cross-session approval index, which is the point: a permission gate and an
+ * approval queue that do not meet are two features that each look finished and jointly do nothing.
+ *
+ * @param {object} decision from {@link decide}
+ * @param {{taskId?: string, machineId?: string, requestedBy?: string}} context
+ */
+export function approvalRequestFor(decision, context = {}) {
+  if (decision === null || typeof decision !== 'object' || decision.verdict !== AUTHORITY_VERDICT.NEEDS_APPROVAL) {
+    return null;
+  }
+  return {
+    // The subject level travels WITH the request, recorded now, because it is a fact about who asked and must
+    // not be re-derived later from a caller who might be the approver.
+    subject_level: decision.level,
+    required_level: decision.required,
+    capability: decision.capability,
+    task_id: context.taskId ?? null,
+    machine_id: context.machineId ?? null,
+    requested_by: context.requestedBy ?? null,
+    destructive: decision.destructive === true,
+    // A destructive request is never auto-settleable, so it is marked here rather than left for the queue to
+    // infer from the capability name.
+    auto_settleable: mayAutoSettle(decision).auto,
+    detail: decision.detail,
+  };
+}
+
 /**
  * Whether a decision may be settled automatically.
  *

package/src/plugin/tools.mjs

@@ -122,6 +122,11 @@ import {
 // another's, so a second implementation of the formula that drifted by one input would make every
 // reverse dial time out while both ends insisted they were sending.
 import { mintPunchId, punchSession } from '../agent/p2p.mjs';
+// v0.22.0: the permission gate. Imported rather than reimplemented for the same reason as everything else
+// here -- a second copy of the escalation rule is a second chance to disagree with the first about how far
+// below a requirement an actor may still ask.
+import { gateDispatch, approvalRequestFor } from '../agent/permission.mjs';
+import { isAuthorityLevel } from '../agent/authority.mjs';
 // v0.6.0: the device keypair and the offer's key distribution (`docs/P2P-CRYPTO.md` §4). Imported
 // rather than reimplemented: the dispatcher and the executor have to derive the *same* keys, and two
 // implementations of a handshake are two chances to disagree about it.
@@ -185,7 +190,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.21.0';
+const PLUGIN_VERSION = '0.23.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -680,6 +685,21 @@ function readConfig(config = {}) {
       .filter((entry) => typeof entry === 'string')
       .map((entry) => entry.trim())
       .filter(Boolean),
+    /**
+     * v0.22.0: the authority level this machine dispatches AS, or null when nobody configured one.
+     *
+     * Not part of the shared config, deliberately: this is a local statement about who is typing, and a
+     * fleet-wide value would let one machine's level speak for another's operator. `W2M_ACTOR_AUTHORITY`
+     * is accepted so a machine can be pointed at a level without editing a profile.
+     *
+     * null is not 0. An unset level means there is no actor to judge, and the gate reports that as
+     * unenforced rather than refusing every writing dispatch on a machine that never opted in.
+     */
+    actorAuthorityLevel: isAuthorityLevel(config.actorAuthorityLevel)
+      ? config.actorAuthorityLevel
+      : (Number.isInteger(Number(process.env.W2M_ACTOR_AUTHORITY)) && isAuthorityLevel(Number(process.env.W2M_ACTOR_AUTHORITY))
+        ? Number(process.env.W2M_ACTOR_AUTHORITY)
+        : null),
     defaultTimeoutMs: shared.values.defaultTimeoutMs,
     sharedConfig: shared,
     pairingCode: typeof config.pairingCode === 'string' && config.pairingCode.trim() !== ''
@@ -3687,6 +3707,40 @@ export async function apply(ctx, config = {}) {
         );
       }
 
+      /**
+       * v0.22.0: the permission gate, placed AFTER the write-scope check so the thing being graded is
+       * already known to be well-formed.
+       *
+       * It grades the dispatch from its own facts rather than from a capability the caller names, and with
+       * no configured level it reports `enforced: false` and changes nothing -- which is why adding it
+       * cannot alter the behaviour of any machine that has not opted in.
+       */
+      const gate = gateDispatch({ write, write_scope: writeScope }, cfg.actorAuthorityLevel);
+      if (gate.enforced) {
+        if (gate.decision.verdict === 'deny') {
+          throw new W2MError(
+            'W2M_PERMISSION_DENIED',
+            'W2M_PERMISSION_DENIED: ' + gate.decision.detail,
+            { hint: "raise this machine's actorAuthorityLevel, or use a capability its level reaches" },
+          );
+        }
+        if (gate.decision.verdict === 'needs_approval') {
+          const request = approvalRequestFor(gate.decision, {
+            taskId: null,
+            machineId: null,
+            requestedBy: cfg.machineName,
+          });
+          throw new W2MError(
+            'W2M_PERMISSION_NEEDS_APPROVAL',
+            'W2M_PERMISSION_NEEDS_APPROVAL: ' + gate.decision.detail,
+            {
+              hint: 'this dispatch needs an approver; it is refused rather than queued because no approval queue is wired to this call yet',
+              request,
+            },
+          );
+        }
+      }
+
       // §5: dispatching a task is the operator's privilege, not the device's. The operator token is
       // required and there is no device-token fallbac - see requireOperatorToken.
       const token = requireOperatorToken(cfg);