@catheadowl/ukp 0.2.5 → 0.3.0

package/src/server.ts

@@ -1,5 +1,6 @@
 import { dirname, join } from "node:path";
 import { readFileSync, writeFileSync, fstatSync, constants as fsConstants } from "node:fs";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer as netCreateServer, connect as netConnect, type Server as NetServer } from "node:net";
 import { ENDPOINT_NAME, loadManifest, type LoadedManifest } from "./config/manifest.ts";
 import { localPathOf, readRegistry } from "./registry.ts";
@@ -12,7 +13,8 @@ import {
   proposeEnvelope,
   proposeUpsert,
 } from "./capabilities/propose.ts";
-import { certSanOf, ensureSelfSignedTlsFiles, spkiPinOf } from "./capabilities/tls-identity.ts";
+import { certSanOf, ensureSelfSignedTlsFiles, migrateLegacyServiceTlsDir, spkiPinOf } from "./capabilities/tls-identity.ts";
+import { retireTlsIgnoreLine } from "./commands/init.ts";
 import {
   buildInlineReferences,
   projectSearchEnvelope,
@@ -40,22 +42,39 @@ import {
   type ParsedRg,
 } from "./capabilities/rg.ts";
 import { KitUsageError } from "./commands/kit.ts";
+import {
+  authenticateBearerKey,
+  loadTokenFile,
+  parseTokenFileText,
+  scopeAllows,
+  type ScopeAccess,
+  type TokenFileEntry,
+} from "./plumbing/token-file.ts";
 
 /** ukp-remote wire v1 server core (ADR-REM-001/002/003, ukp_remote W1/W7):
  * two serving shapes over one wire. Single-endpoint mode exposes ONE
  * registered endpoint; door mode (`endpointName` absent, ADR-REM-004) serves
- * every local binding in the registry, routed by name at `/e/<name>/…` with
+ * local bindings in the registry, routed by name at `/e/<name>/…` with
  * a `scope:"host"` door document — the registry is read fresh per request so
- * the door grows without restart. Both shapes expose a discovery document
- * (manifest projection + protocol version + instance identity) plus the
- * read-side capability routes (search/read since W1, nav/rg since W6); the
- * per-endpoint documents are byte-identical across modes, so client-side
- * TOFU and name-assertion paths are shared. The capability layer runs
- * unchanged behind the routes (provider/transport axes stay orthogonal):
- * search via `runSearch` with a single-endpoint scope, read via `runRead`,
- * nav via `runNav`, rg via `runRg`. There is no session, no streaming, and
- * no server-side artifact: responses inline the reference data (RQ-07) and
- * generate a serve-scoped run id. */
+ * the door grows without restart. Door mode comes in two widths
+ * (ADR-REM-010): every local binding, or the `select` whitelist subset. To
+ * anyone the subset excludes, the door pretends those endpoints do not
+ * exist — roster, routes, per-endpoint documents, and 404 rosters all see
+ * the same effective set (select ∩ current registry). Both shapes expose a
+ * discovery document (manifest projection + protocol version + instance
+ * identity) plus the read-side capability routes (search/read since W1,
+ * nav/rg since W6); the per-endpoint documents are byte-identical across
+ * modes, so client-side TOFU and name-assertion paths are shared. The
+ * capability layer runs unchanged behind the routes (provider/transport
+ * axes stay orthogonal): search via `runSearch` with a single-endpoint
+ * scope, read via `runRead`, nav via `runNav`, rg via `runRg`. The bearer
+ * gate has two sources (W13 / RQ-16c): env tokens — the full-power
+ * shortcut, original RQ-16 semantics — or the labeled token file, read
+ * fresh per request so deleting a line revokes without a restart; a file
+ * key's scopes narrow the door's rosters exactly like `--select` does
+ * (ADR-REM-010 mechanism reuse, no 403 class). There is no
+ * session, no streaming, and no server-side artifact: responses inline the
+ * reference data (RQ-07) and generate a serve-scoped run id. */
 
 export const PROTOCOL_NAME = "ukp-remote";
 export const PROTOCOL_VERSION = "1";
@@ -66,11 +85,20 @@ export const DISCOVERY_PATH = "/.well-known/ukp.json";
 export const PROPOSE_BODY_LIMIT_BYTES = 1024 * 1024;
 
 export interface ServeConfig {
-  /** Absent = host door mode (ADR-REM-004 / O-2): serve EVERY local binding
-   * in the registry over one listener, routed by name at `/e/<name>/…`, with
-   * a `scope:"host"` door document at the well-known path. Present = the
+  /** Absent = host door mode (ADR-REM-004 / O-2): serve local bindings in
+   * the registry over one listener, routed by name at `/e/<name>/…`, with a
+   * `scope:"host"` door document at the well-known path. Present = the
    * original single-endpoint mode (N=1 retreat stays legal long-term). */
   endpointName?: string;
+  /** Subset door (ADR-REM-010 / O-020 ruling D): a declarative name
+   * whitelist next to an ABSENT endpointName — the door serves only the
+   * selected local bindings, and to anyone the list excludes the door
+   * pretends those endpoints do not exist (roster, routes, per-endpoint
+   * documents, 404 rosters all carry the same effective set). The server
+   * layer does NOT validate the names at startup — the command layer's
+   * eager check (usage error with the roster) is the admission; here the
+   * set just intersects with the per-request registry read. */
+  select?: readonly string[];
   currentDirectory: string;
   registryPath: string;
   qmdCommand?: readonly string[];
@@ -83,9 +111,24 @@ export interface ServeConfig {
    * readable without it). In door mode the same gate covers all
    * `/e/<name>/v1/*` routes (door-level auth, O-2). */
   tokens?: readonly string[];
+  /** W13 / RQ-16c: the labeled token file (`~/.ukp/tokens`). When `tokens`
+   * is absent, the gate arms from this file instead: it is read FRESH on
+   * every request (revocation = deleting the line, no restart), a presented
+   * `ukp_<label>_<id>_<secret>` key is verified against the row's SHA-256,
+   * and the matched row's scopes decide which endpoints the key may touch
+   * (`name:ro|rw`, Docker-registry grammar, required per row). When
+   * `tokens` IS set, env wins outright and the file is not consulted —
+   * env is the full-power shortcut form of the same gate (AWS/gh/kubectl
+   * chain order). Scope enforcement reuses the ADR-REM-010 roster
+   * mechanism: an out-of-scope name shares the roster 404 with an unknown
+   * one, byte-identical, and the roster a scoped 404 carries is the key's
+   * own effective set — no new 403 class exists. */
+  tokenFilePath?: string;
   /** TLS transport (W5' / D-079): `self-signed` generates and persists an
-   * identity under the Service folder (`.ukp/tls/`) — in door mode under the
-   * registry's directory, since a door has no single Service folder;
+   * identity in the machine home beside the registry — `~/.ukp/tls/<name>/`
+   * in endpoint mode, the flat `~/.ukp/tls/` in door mode (a door has no
+   * single Service folder; endpoint mode converged on the same home
+   * 2026-11-01 because the identity is machine-scoped material);
    * `certificates` serves operator-provided PEM files (Let's Encrypt IP
    * certs, mkcert, private CA). `sanEntries` (the `--tls-san` flag, already
    * normalized `IP:x`/`DNS:y`) merges extra coverage into the self-signed
@@ -144,21 +187,29 @@ export interface ServeInfo {
   folder?: string;
   instanceUid?: string;
   /** Door mode fields (present iff mode === "door"): the startup snapshot of
-   * servable endpoint names (the door itself grows without restart), plus
-   * the snapshot of write-capable (propose-declaring) names — the banner's
-   * "you opened a write face" line (ADR-REM-005 verdict C). */
-  door?: { endpoints: string[]; write: string[] };
+   * servable endpoint names (the door itself grows without restart), the
+   * snapshot of write-capable (propose-declaring) names — the banner's
+   * "you opened a write face" line (ADR-REM-005 verdict C) — and, on a
+   * subset door (ADR-REM-010), the declared select whitelist itself (the
+   * banner's `select:` line: what was asked for, next to what is being
+   * served). */
+  door?: { endpoints: string[]; write: string[]; select?: string[] };
   url: string;
   host: string;
   port: number;
   authRequired: boolean;
+  /** Present when the gate armed from the token file instead of env
+   * (W13 / RQ-16c) — feeds the banner's operator line. `keys` is a startup
+   * snapshot for visibility only; the live truth is the per-request fresh
+   * read (delete a line, next request 401s). */
+  tokenFile?: { keys: number };
   /** ripgrep availability probed once at startup IN THE DOOR'S OWN PROCESS
    * (2026-09-20, liku feedback): /v1/rg serves every endpoint and a missing
    * binary degrades per-endpoint on the wire by design — but that truth is
    * consumer-channel only. The banner line is the operator channel, and the
    * probe environment is by construction the one that matters (ukp diagnose
    * measures the invoking shell instead, which can differ from the door's
-   * schtasks / wake environment). */
+   * Task Scheduler / wake environment). */
   rg: "ok" | "missing";
   /** TLS identity summary (W5' / D-079) when serving over HTTPS; the pin is
    * what remote clients TOFU-pin at registration. `source` "re-signed" marks
@@ -279,21 +330,32 @@ export function buildDiscoveryDocument(
   };
 }
 
-/** Servable endpoints of a door (O-2): every LOCAL binding in the registry,
- * read fresh by the caller per request (new endpoints appear without a
- * restart). Remote bindings are not servable and never make the roster. */
-function listDoorEndpoints(registryPath: string): Array<{ name: string; folder: string }> {
+/** Servable endpoints of a door (O-2): the LOCAL bindings in the registry
+ * the door's width admits — every one of them, or the `select` whitelist's
+ * members (ADR-REM-010) — read fresh by the caller per request (new
+ * endpoints appear without a restart). Remote bindings are not servable and
+ * never make the roster. W13 adds the per-key narrowing axis: `admit` is
+ * the matched file key's scope predicate for the route's access level, so
+ * the roster a scoped caller can ever see is scope ∩ select ∩ registry. */
+function listDoorEndpoints(
+  registryPath: string,
+  select?: readonly string[],
+  admit?: (name: string) => boolean,
+): Array<{ name: string; folder: string }> {
   return readRegistry(registryPath)
     .filter((binding) => binding.kind !== "remote")
+    .filter((binding) => select === undefined || select.includes(binding.name))
+    .filter((binding) => admit === undefined || admit(binding.name))
     .map((binding) => ({ name: binding.name, folder: binding.path! }));
 }
 
 /** Startup snapshot of write-capable (propose-declaring) door endpoints —
  * the banner line that makes the opened write face visible (ADR-REM-005
- * verdict C). Unreadable/name-drifted Services drop out silently here;
- * they are already reported by the roster/discovery paths. */
-function listWriteEndpoints(registryPath: string): string[] {
-  return listDoorEndpoints(registryPath).flatMap((endpoint) => {
+ * verdict C). Subset doors narrow it to the select set (ADR-REM-010).
+ * Unreadable/name-drifted Services drop out silently here; they are already
+ * reported by the roster/discovery paths. */
+function listWriteEndpoints(registryPath: string, select?: readonly string[]): string[] {
+  return listDoorEndpoints(registryPath, select).flatMap((endpoint) => {
     try {
       const loaded = loadManifest(endpoint.folder);
       return loaded.effectiveName === endpoint.name
@@ -693,8 +755,10 @@ function startServeListener(
 
 /** TLS material resolution (W5' / D-079), shared by both serve modes: a
  * self-signed identity is generated/re-signed/persisted under `identityDir`
- * (the Service folder's `.ukp/tls/` in endpoint mode, the registry directory
- * in door mode — a door has no single Service folder), explicit certificates
+ * (the machine home beside the registry: `~/.ukp/tls/<name>/` in endpoint
+ * mode, the home's flat root in door mode — a door has no single Service
+ * folder, and endpoint mode converged on the same home 2026-11-01 because
+ * the identity is machine-scoped material), explicit certificates
  * are read from the operator's paths. Bun.serve takes PEM contents
  * (path-string handling is platform-dependent). Every failure — unreadable
  * operator files, an unusable persisted identity, openssl unable to sign —
@@ -739,29 +803,113 @@ function resolveTlsMaterial(
   }
 }
 
+/** CHK-01 ruling (D-100 / ADR 0027): the bearer check hashes both sides
+ * with SHA-256 and compares the fixed 32-byte digests via
+ * `crypto.timingSafeEqual`. Hashing first makes the comparison
+ * length-uniform — operator-chosen tokens (`UKP_SERVE_TOKEN`, arbitrary
+ * length — not fixed-length hex) and attacker-chosen header values can
+ * never reach the raw API's equal-length requirement, and no early exit
+ * (length mismatch, first differing byte) shapes the failure timing.
+ * Every failure class — missing header, non-Bearer scheme, wrong value —
+ * runs this one path and then the single 401 below, so responses stay
+ * byte-identical across classes (CHK-02, CWE-204 family: the gate is
+ * not a credential oracle). */
+export function timingSafeBearerMatch(
+  authorization: string | null,
+  tokens: readonly string[],
+): boolean {
+  const presented = createHash("sha256").update(authorization ?? "").digest();
+  return tokens.some((token) =>
+    timingSafeEqual(createHash("sha256").update(`Bearer ${token}`).digest(), presented)
+  );
+}
+
+/** What the gate established about the caller (W13 / RQ-16c): an env token
+ * is the full-power shortcut form (its scope is the whole door, original
+ * RQ-16 semantics); a file key carries its row's scopes into authorization.
+ * `undefined` = no gate armed (loopback anonymous serving) — not a failure.
+ * The two never mix: env present means the file is not consulted at all. */
+type GateCredential =
+  | { kind: "env" }
+  | { kind: "file"; entry: TokenFileEntry };
+
+/** The single 401 every gate failure class emits (CHK-02 / CWE-204 family:
+ * the gate is not a credential oracle) — missing header, wrong scheme,
+ * unknown key, wrong secret, out-of-scope key on a single-endpoint gate. */
+function authFailureResponse(): Response {
+  return jsonResponse(
+    errorBody("auth-failure", "missing or invalid bearer token (Authorization: Bearer <token>)"),
+    401,
+  );
+}
+
+/** W13 / RQ-16c: whether ANY auth source is configured — env tokens or the
+ * token file. Drives `authRequired` (banner, discovery security.schemes)
+ * and the gate itself; with neither, serving is anonymous (the command
+ * layer's deny-by-default admission, RQ-18, is what prevents reaching here
+ * unarmed on non-loopback binds). */
+function gateArmed(config: ServeConfig): boolean {
+  return (config.tokens?.length ?? 0) > 0 || config.tokenFilePath !== undefined;
+}
+
+/** The door gate, both sources (W13): env tokens compare through the
+ * CHK-01 digest path unchanged; a token file is fresh-read per request
+ * (missing/unreadable/unparseable file ⇒ no key can pass — fail closed)
+ * and the presented key is verified against exactly its (label, keyId) row
+ * with a timing-safe digest compare inside the plumbing module. */
 function bearerGate(
   request: Request,
-  tokens: readonly string[] | undefined,
-): Response | undefined {
-  if ((tokens?.length ?? 0) === 0) return undefined;
-  const authorization = request.headers.get("authorization");
-  if (!tokens!.some((token) => authorization === `Bearer ${token}`)) {
-    return jsonResponse(
-      errorBody("auth-failure", "missing or invalid bearer token (Authorization: Bearer <token>)"),
-      401,
-    );
+  config: ServeConfig,
+): { credential: GateCredential | undefined } | { response: Response } {
+  if (!gateArmed(config)) return { credential: undefined };
+  if ((config.tokens?.length ?? 0) > 0) {
+    return timingSafeBearerMatch(request.headers.get("authorization"), config.tokens!)
+      ? { credential: { kind: "env" } }
+      : { response: authFailureResponse() };
   }
-  return undefined;
+  const loaded = loadTokenFile(config.tokenFilePath!);
+  if (!("text" in loaded)) return { response: authFailureResponse() };
+  const parsed = parseTokenFileText(loaded.text);
+  if ("error" in parsed) return { response: authFailureResponse() };
+  const authorization = request.headers.get("authorization");
+  // Scheme shape is part of the uniform failure path: a non-Bearer header
+  // fails exactly like a missing one (single 401, no early distinctions).
+  const match = /^Bearer (.+)$/.exec(authorization ?? "");
+  if (match === null) return { response: authFailureResponse() };
+  const entry = authenticateBearerKey(match[1]!, parsed.entries);
+  return entry !== undefined ? { credential: { kind: "file", entry } } : { response: authFailureResponse() };
+}
+
+/** Per-request roster admission from the matched key's scopes (rehearsal
+ * point E): read routes demand `ro`, the propose route demands `rw`. A
+ * `ro`-scoped endpoint is therefore absent from the write face's effective
+ * set the same way an unselected name is absent from a subset door — same
+ * roster-404 shape, no new refusal class. Env credentials and anonymous
+ * serving return undefined (the door's own width applies). */
+function scopeAdmit(
+  credential: GateCredential | undefined,
+  access: ScopeAccess,
+): ((name: string) => boolean) | undefined {
+  if (credential?.kind !== "file") return undefined;
+  return (name: string) => scopeAllows(credential.entry.scopes, name, access);
 }
 
 /** Per-request endpoint resolution for door routing (O-2): the registry is
  * read fresh, the name segment has already passed ENDPOINT_NAME (injection
  * unreachable), unknown and non-servable names get the roster 404, and the
  * RQ-14 binding↔manifest identity check runs per request like the
- * single-mode discovery fetch does. */
+ * single-mode discovery fetch does. A subset door (ADR-REM-010) routes an
+ * excluded name into the SAME roster-404 branch as an unknown one — the
+ * response is byte-identical either way, so the roster is the only name
+ * list any response ever carries. W13 scopes ride the same branch: an
+ * out-of-scope name for the matched key is indistinguishable from an
+ * unknown one, and the roster it sees is the key's own effective set
+ * (`admit` = scope ∩ select ∩ registry), never the wider door. */
 function resolveDoorRoute(
   registryPath: string,
   name: string,
+  select?: readonly string[],
+  admit?: (name: string) => boolean,
 ): { folder: string } | { response: Response } {
   let binding;
   try {
@@ -770,8 +918,13 @@ function resolveDoorRoute(
     const reason = error instanceof Error ? error.message : String(error);
     return { response: jsonResponse(errorBody("provider-unavailable", `Host Registry is not readable: ${reason}`), 503) };
   }
-  if (binding === undefined || binding.kind === "remote") {
-    const roster = listDoorEndpoints(registryPath).map((endpoint) => endpoint.name).join(", ");
+  if (
+    binding === undefined
+    || binding.kind === "remote"
+    || (select !== undefined && !select.includes(name))
+    || (admit !== undefined && !admit(name))
+  ) {
+    const roster = listDoorEndpoints(registryPath, select, admit).map((endpoint) => endpoint.name).join(", ");
     return {
       response: jsonResponse(
         errorBody("not-found", `no such endpoint '${name}' on this host door (available: ${roster})`),
@@ -808,10 +961,19 @@ function resolveDoorRoute(
 
 /** Door-mode routing table (ADR-REM-004 / O-2). The door document and the
  * per-endpoint documents stay public (ADR-REM-003 declaration/capability
- * divide); every `/e/<name>/v1/*` route passes the door-level bearer gate. */
-function doorNotFound(name: string | undefined, registryPath: string): Response {
+ * divide); every `/e/<name>/v1/*` route passes the door-level bearer gate.
+ * The roster a 404 carries is the door's effective set — on a subset door
+ * (ADR-REM-010) that is the select ∩ registry intersection, never the full
+ * registry; on an authenticated scoped route (W13) it further intersects
+ * with the matched key's scopes via `admit`. */
+function doorNotFound(
+  name: string | undefined,
+  registryPath: string,
+  select?: readonly string[],
+  admit?: (name: string) => boolean,
+): Response {
   if (name !== undefined) {
-    const roster = listDoorEndpoints(registryPath).map((endpoint) => endpoint.name).join(", ");
+    const roster = listDoorEndpoints(registryPath, select, admit).map((endpoint) => endpoint.name).join(", ");
     return jsonResponse(
       errorBody("not-found", `no such endpoint '${name}' on this host door (available: ${roster})`),
       404,
@@ -827,6 +989,11 @@ function doorNotFound(name: string | undefined, registryPath: string): Response
 }
 
 function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnType<typeof resolveTlsMaterial>): StartedServe {
+  // The door's width (ADR-REM-010): undefined = the whole registry, a name
+  // list = the subset whitelist. One variable feeds every surface below —
+  // door document, per-request routes, 404 rosters — so the subset cannot
+  // drift between them.
+  const select = config.select;
   const handler = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
 
@@ -835,7 +1002,9 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         return jsonResponse(errorBody("method-not-allowed", `the discovery document is a GET resource`), 405);
       }
       try {
-        return jsonResponse(buildDoorDocument(listDoorEndpoints(config.registryPath), (config.tokens?.length ?? 0) > 0));
+        // Public door document (ADR-REM-003): no key presented, no scope
+        // narrowing — the door's own width is what the roster declares.
+        return jsonResponse(buildDoorDocument(listDoorEndpoints(config.registryPath, select), gateArmed(config)));
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
         return jsonResponse(errorBody("provider-unavailable", `Host Registry is not readable: ${reason}`), 503);
@@ -849,18 +1018,18 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
       const name = routeMatch[1]!;
       const rest = routeMatch[2] ?? "/";
       if (!ENDPOINT_NAME.test(name)) {
-        return doorNotFound(name, config.registryPath);
+        return doorNotFound(name, config.registryPath, select);
       }
       if (rest === DISCOVERY_PATH) {
         if (request.method !== "GET") {
           return jsonResponse(errorBody("method-not-allowed", `the discovery document is a GET resource`), 405);
         }
-        const resolved = resolveDoorRoute(config.registryPath, name);
+        const resolved = resolveDoorRoute(config.registryPath, name, select);
         if ("response" in resolved) return resolved.response;
         try {
           const loaded = loadManifest(resolved.folder);
           return jsonResponse(
-            buildDiscoveryDocument(loaded, readInstanceUid(resolved.folder), (config.tokens?.length ?? 0) > 0),
+            buildDiscoveryDocument(loaded, readInstanceUid(resolved.folder), gateArmed(config)),
           );
         } catch (error) {
           const reason = error instanceof Error ? error.message : String(error);
@@ -868,18 +1037,22 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         }
       }
       if (rest.startsWith("/v1/propose/")) {
-        const denied = bearerGate(request, config.tokens);
-        if (denied !== undefined) return denied;
+        const gate = bearerGate(request, config);
+        if ("response" in gate) return gate.response;
+        // The write face demands the rw bit: a ro-scoped endpoint is not in
+        // this key's effective write roster (rehearsal point E).
+        const admit = scopeAdmit(gate.credential, "rw");
         const id = rest.slice("/v1/propose/".length);
-        if (id.includes("/")) return doorNotFound(undefined, config.registryPath);
-        const resolved = resolveDoorRoute(config.registryPath, name);
+        if (id.includes("/")) return doorNotFound(undefined, config.registryPath, select, admit);
+        const resolved = resolveDoorRoute(config.registryPath, name, select, admit);
         if ("response" in resolved) return resolved.response;
         return await handlePropose(request, config, name, resolved.folder, id);
       }
       if (rest === "/v1/search" || rest === "/v1/read" || rest === "/v1/nav" || rest === "/v1/rg") {
-        const denied = bearerGate(request, config.tokens);
-        if (denied !== undefined) return denied;
-        const resolved = resolveDoorRoute(config.registryPath, name);
+        const gate = bearerGate(request, config);
+        if ("response" in gate) return gate.response;
+        const admit = scopeAdmit(gate.credential, "ro");
+        const resolved = resolveDoorRoute(config.registryPath, name, select, admit);
         if ("response" in resolved) return resolved.response;
         if (rest === "/v1/search") {
           return await handleSearch(request, config, name, resolved.folder);
@@ -888,14 +1061,14 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
           return handleRead(url, request, config, name);
         }
         if (rest === "/v1/nav") {
-          return handleNav(url, request, config, name);
+          return await handleNav(url, request, config, name);
         }
         return handleRg(url, request, config, name);
       }
-      return doorNotFound(undefined, config.registryPath);
+      return doorNotFound(undefined, config.registryPath, select);
     }
 
-    return doorNotFound(undefined, config.registryPath);
+    return doorNotFound(undefined, config.registryPath, select);
   };
 
   const listener = startServeListener(handler, {
@@ -906,17 +1079,20 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
     ...(config.systemdSocket === true ? { systemdSocket: true } : {}),
   });
   const { server } = listener;
+  const tokenFile = tokenFileSnapshot(config);
 
   const info: ServeInfo = {
     mode: "door",
     door: {
-      endpoints: listDoorEndpoints(config.registryPath).map((endpoint) => endpoint.name),
-      write: listWriteEndpoints(config.registryPath),
+      endpoints: listDoorEndpoints(config.registryPath, select).map((endpoint) => endpoint.name),
+      write: listWriteEndpoints(config.registryPath, select),
+      ...(select !== undefined ? { select: [...select] } : {}),
     },
     url: listener.publicUrl,
     host,
     port: listener.port,
-    authRequired: (config.tokens?.length ?? 0) > 0,
+    authRequired: gateArmed(config),
+    ...(tokenFile !== undefined ? { tokenFile } : {}),
     rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
@@ -926,6 +1102,19 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
   return { server, info, stopAll: listener.stopAll };
 }
 
+/** Startup snapshot of the token file for the banner's operator line
+ * (W13): the live gate re-reads per request; this count is visibility, not
+ * truth. A parse failure here is cosmetic-zero — the command layer's
+ * admission already refused a malformed file, and the gate itself fails
+ * closed on any read/parse problem. */
+function tokenFileSnapshot(config: ServeConfig): { keys: number } | undefined {
+  if (config.tokenFilePath === undefined || (config.tokens?.length ?? 0) > 0) return undefined;
+  const loaded = loadTokenFile(config.tokenFilePath);
+  if (!("text" in loaded)) return { keys: 0 };
+  const parsed = parseTokenFileText(loaded.text);
+  return "error" in parsed ? { keys: 0 } : { keys: parsed.entries.length };
+}
+
 export function startUkpServer(config: ServeConfig): StartedServe {
   const host = config.host ?? "127.0.0.1";
 
@@ -955,7 +1144,21 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     );
   }
 
-  const tlsMaterial = resolveTlsMaterial(config, join(serviceFolder, ".ukp", "tls"));
+  // The self-signed identity is machine-scoped material (its SAN coverage
+  // names THIS host's interfaces) and lives in the machine home beside the
+  // registry — `~/.ukp/tls/<endpoint>/` here, the same home's flat root in
+  // door mode (adjudication 2026-11-01, inbox service-dir-layering item 2;
+  // endpoint mode converged on the home door mode already used). Keyed by
+  // the manifest's effective name: the registry namespace holds one
+  // endpoint per name, so a re-cloned folder re-attaches to its pinned
+  // identity instead of orphaning every client (INV-04). A pre-2026-11-01
+  // `.ukp/tls/` moves in once, keypair untouched; the retired `/tls/`
+  // ignore rule swaps out in the same gesture.
+  const identityDir = join(dirname(config.registryPath), "tls", startupManifest.effectiveName);
+  if (migrateLegacyServiceTlsDir(serviceFolder, identityDir) === "moved") {
+    retireTlsIgnoreLine(join(serviceFolder, ".ukp"));
+  }
+  const tlsMaterial = resolveTlsMaterial(config, identityDir);
 
   const handler = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
@@ -978,7 +1181,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
           );
         }
         return jsonResponse(
-          buildDiscoveryDocument(loaded, readInstanceUid(serviceFolder), (config.tokens?.length ?? 0) > 0),
+          buildDiscoveryDocument(loaded, readInstanceUid(serviceFolder), gateArmed(config)),
         );
       } catch (error) {
         return jsonResponse(
@@ -989,8 +1192,15 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     }
 
     if (url.pathname.startsWith("/v1/propose/")) {
-      const denied = bearerGate(request, config.tokens);
-      if (denied !== undefined) return denied;
+      const gate = bearerGate(request, config);
+      if ("response" in gate) return gate.response;
+      // Single-endpoint gates have no roster to hide behind: a key that
+      // does not carry this endpoint at rw is simply not valid for this
+      // gate's write face — the same uniform 401, no new refusal class.
+      if (gate.credential?.kind === "file"
+        && !scopeAllows(gate.credential.entry.scopes, binding.name, "rw")) {
+        return authFailureResponse();
+      }
       const id = url.pathname.slice("/v1/propose/".length);
       if (id.includes("/")) {
         return jsonResponse(
@@ -1010,8 +1220,12 @@ export function startUkpServer(config: ServeConfig): StartedServe {
       || url.pathname === "/v1/nav"
       || url.pathname === "/v1/rg"
     ) {
-      const denied = bearerGate(request, config.tokens);
-      if (denied !== undefined) return denied;
+      const gate = bearerGate(request, config);
+      if ("response" in gate) return gate.response;
+      if (gate.credential?.kind === "file"
+        && !scopeAllows(gate.credential.entry.scopes, binding.name, "ro")) {
+        return authFailureResponse();
+      }
       if (url.pathname === "/v1/search") {
         return await handleSearch(request, config, binding.name, serviceFolder);
       }
@@ -1019,7 +1233,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
         return handleRead(url, request, config, binding.name);
       }
       if (url.pathname === "/v1/nav") {
-        return handleNav(url, request, config, binding.name);
+        return await handleNav(url, request, config, binding.name);
       }
       return handleRg(url, request, config, binding.name);
     }
@@ -1041,6 +1255,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     ...(config.systemdSocket === true ? { systemdSocket: true } : {}),
   });
   const { server } = listener;
+  const tokenFile = tokenFileSnapshot(config);
 
   const info: ServeInfo = {
     mode: "endpoint",
@@ -1050,7 +1265,8 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     url: listener.publicUrl,
     host,
     port: listener.port,
-    authRequired: (config.tokens?.length ?? 0) > 0,
+    authRequired: gateArmed(config),
+    ...(tokenFile !== undefined ? { tokenFile } : {}),
     rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
@@ -1149,7 +1365,7 @@ function handleRead(url: URL, request: Request, config: ServeConfig, endpointNam
 /** GET /v1/nav?path=&depth= → the nav envelope IS the response (W6): the
  * client renders it through the same renderNavHuman/renderNavJson path as a
  * local run. Failures use the transport error shape with nav's classes. */
-function handleNav(url: URL, request: Request, config: ServeConfig, endpointName: string): Response {
+async function handleNav(url: URL, request: Request, config: ServeConfig, endpointName: string): Promise<Response> {
   if (request.method !== "GET") {
     return jsonResponse(errorBody("method-not-allowed", "/v1/nav is a GET route"), 405);
   }
@@ -1157,7 +1373,7 @@ function handleNav(url: URL, request: Request, config: ServeConfig, endpointName
   if ("error" in parsed) {
     return jsonResponse(errorBody("usage-error", parsed.error), 400);
   }
-  const outcome = runNav(parsed.request, {
+  const outcome = await runNav(parsed.request, {
     currentDirectory: config.currentDirectory,
     registryPath: config.registryPath,
   });

package/src/spawn-relay.ts

@@ -36,12 +36,30 @@ function psSingleQuoted(arg: string): string {
 
 /** The relay script. `notFoundGuard` adds a Get-Command pre-check that exits
  * TOOL_NOT_FOUND_EXIT when argv[0] does not resolve — for callers that must
- * distinguish a missing tool from a tool's own failure exit. */
+ * distinguish a missing tool from a tool's own failure exit.
+ *
+ * The leading $ProgressPreference suppression is load-bearing for the stderr
+ * contract (2026-10-09 finding, TODO rg-clixml-pattern-failure-windows): the
+ * guard's Get-Command is the script's first cmdlet, which makes the engine
+ * emit its one-time "Preparing modules for first use" progress record, and
+ * with a redirected stderr powershell.exe serializes that record as a
+ * `#< CLIXML` stream ahead of the tool's own stderr — the consumer then
+ * surfaces `status: failed: #< CLIXML` instead of the real tool error.
+ * Suppressing progress keeps the channel tool-stderr-only; native stderr
+ * itself passes through byte-clean, exit code included (verified live:
+ * rg's regex parse error arrives readable; UTF-8 match text unaffected). */
 export function toolRelayScript(argv: readonly string[], options: { notFoundGuard?: boolean } = {}): string {
+  // The guard resolves via -Name, never -LiteralName: PS 5.1's Get-Command
+  // has no -LiteralName parameter, and an unknown parameter on it is not a
+  // binding error — the argument is silently swallowed and the call returns
+  // EVERY command, so a -LiteralName guard is vacuous (a missing tool then
+  // falls through to `&` and its CommandNotFoundException exits 0 with a
+  // CLIXML leak; live-verified 2026-10-09 review). -Name globs, but tool
+  // names ("rg", "ssh") contain no glob characters.
   const guard = options.notFoundGuard === true
-    ? " if (-not (Get-Command -LiteralName $a[0] -ErrorAction SilentlyContinue)) { exit 127 };"
+    ? " if (-not (Get-Command -Name $a[0] -ErrorAction SilentlyContinue)) { exit 127 };"
     : "";
-  return `$a = @(${argv.map(psSingleQuoted).join(",")});${guard} & $a[0] $a[1..($a.Count-1)]; exit $LASTEXITCODE`;
+  return `$ProgressPreference = 'SilentlyContinue'; $a = @(${argv.map(psSingleQuoted).join(",")});${guard} & $a[0] $a[1..($a.Count-1)]; exit $LASTEXITCODE`;
 }
 
 /** The powershell carrier argv for a tool invocation: spawn THIS instead of