feat(gateway): separate admin sock from bootstrap sock with ACL guarantee (#389)

Phase 3's admin facet was reachable through `bootstrap.getAdmin()`,
which collapsed registration authority (anyone with the bootstrap
sock) and admin authority onto a single capability path. Any local
user daemon that connects to the bootstrap sock to call `register`
could call `getAdmin` on the same exo and reach the administrator
facet.

Split the two authorities onto separate socks:

  - `bootstrap.sock` (existing) carries the `GatewayBootstrap` exo
    only. Its `getAdmin` method is removed; the `GatewayAdmin`
    typedef no longer flows through the bootstrap module's import
    graph.
  - `admin.sock` (new) is a sibling sock, distinct file path,
    mode 0600. Deployment is responsible for placing it under a
    parent directory mode 0700 so only the administrator OS
    account can `connect(2)`. The listener for both socks lands in
    a follow-on PR; the path resolver and the surface contract
    land here.

Surface changes:

  - `src/sock-paths.js`: factor the resolution rules into a shared
    helper; export `resolveAdminSocketPath` alongside
    `resolveBootstrapSocketPath`. `ADMIN_SOCKET_BASENAME` is the
    `admin.sock` constant; `ENDO_GATEWAY_ADMIN_SOCK` is the
    operator override for the admin sock (mirroring the existing
    `ENDO_GATEWAY_BOOTSTRAP_SOCK`).
  - `src/bootstrap.js`: drop `getAdmin` from `GatewayBootstrap`'s
    interface, exo body, deps, typedef, and the GatewayAdmin
    `@import`. The bootstrap module no longer references the admin
    module.
  - `index.js`: wire the admin facet directly from `makeGateway`
    against the bootstrap's in-process backplane (or an empty
    backplane when `sockBootstrap` is off). The `gateway.getAdmin`
    in-process accessor is preserved; the previous "admin requires
    sockBootstrap" cross-toggle dependency is removed.
  - `src/config.js`: drop the `adminDaemon depends on sockBootstrap`
    validator. The two features have independent toggles; a
    deployment may serve admin reads without exposing the
    registration channel and vice versa.
  - `src/admin.js`: docstring reflects the new architecture
    (admin sock, not bootstrap sock; independent toggles).

Tests:

  - `test/sock-paths.test.js`: admin sock system / user / darwin
    resolutions; `ENDO_GATEWAY_ADMIN_SOCK` override; regression-
    evidence saboteur verifying the admin resolver does **not**
    pick up the bootstrap-override env var; cross-source invariant
    that bootstrap and admin paths are always distinct files; the
    two basenames are distinct constants.
  - `test/admin.test.js`: `bootstrap.getAdmin` is replaced with a
    `__getMethodNames__` enumeration that pins the absence of the
    method; the prior cross-toggle "throws when sockBootstrap is
    disabled" test is rewritten to verify the admin facet works
    standalone and reports an empty registration view; the
    "reachable only via gateway.getAdmin and bootstrap.getAdmin"
    contract becomes "reachable only via gateway.getAdmin", with
    zero admin-shaped methods on the bootstrap.
  - `test/config.test.js`: the rejection test for
    `adminDaemon=true` + `sockBootstrap=false` is rewritten to
    verify the combination is now accepted; the merged config
    reflects the requested toggles.

Linux/Mac scope (per #388): the new admin sock paths use the same
platform-bound resolution as the bootstrap sock (Linux primary,
macOS secondary, no Windows-flavored paths).

Author: endolinbot

packages/gateway/README.md

@@ -27,10 +27,12 @@ This is the **phase-3 slice**, building on phase 2's sock bootstrap
 registrar (Feature 4) and the phase-1 skeleton's package shape.
 Phase 3 adds Feature 7 (admin daemon: the `GatewayAdmin` exo).
 The admin facet is reachable only via the in-process accessor
-(`gateway.getAdmin()`) and the sock bootstrap
-(`bootstrap.getAdmin()`); it is **never** exposed on the public
-HTTP / WS surface, keeping admin authority off the network per the
-design.
+(`gateway.getAdmin()`) and a separate local sock (`admin.sock`,
+distinct from the bootstrap sock); it is **never** exposed on the
+public HTTP / WS surface, and is **never** reached through the
+bootstrap sock. The split keeps registration authority (anyone with
+the bootstrap sock) and admin authority (only the OS account that
+owns the admin sock) on independent capability paths.
 
 Implemented:
 
@@ -43,27 +45,32 @@ Implemented:
   `lookup` (phase 1, Feature 2).
 - Per-feature configuration toggles validated at `make` time.
 - `GatewayBootstrap` exo with `challenge`, `register`,
-  `registerRelay`, `getBindAddress`, `getApps`, `getAdmin`;
+  `registerRelay`, `getBindAddress`, `getApps`;
   `Registration` handle with `publishWeblet`, `unpublishWeblet`,
   `addPublicKey`, `deregister`, `listWeblets`, `listPublicKeys`
-  (phase 2, Feature 4; phase 3 added `getAdmin`).
+  (phase 2, Feature 4).
 - `GatewayAdmin` exo (phase 3, Feature 7) with `listRegistrations`,
   `deregisterRelay`, `listVirtualHosts`, `getResourceBalances`,
-  `getCounters`. Reachable only over the sock bootstrap or the
-  in-process accessor; refused when `adminDaemon` is off; the
-  config validator already rejects `adminDaemon=true` with
-  `sockBootstrap=false`.
+  `getCounters`. Reachable only via the in-process accessor and
+  the admin sock; refused when `adminDaemon` is off. The admin
+  daemon's toggle is independent of `sockBootstrap`; a deployment
+  may offer admin reads without exposing the bootstrap sock and
+  vice versa.
 - Proof-of-possession nonce registry with domain-separated
   challenge hashing (`endo-gateway:registrar:nonce`), 30-second
   TTL, single-use semantics, constant-time signature comparison
   helper, and a Node-backed `CryptoPowers` adapter
   (`src/node-crypto-powers.js`).
-- Bootstrap sock path resolver
+- Bootstrap and admin sock path resolvers
   (`src/sock-paths.js`) covering `/run/endo-gateway/bootstrap.sock`
-  (system service), `${XDG_RUNTIME_DIR}/endo-gateway/...` (user
-  Linux), the macOS `Library/Application Support` variant, the
-  `${TMPDIR}/...` fallback, and `ENDO_GATEWAY_BOOTSTRAP_SOCK`
-  operator override.
+  and `/run/endo-gateway/admin.sock` (system service),
+  `${XDG_RUNTIME_DIR}/endo-gateway/...` (user Linux), the macOS
+  `Library/Application Support` variant, the `${TMPDIR}/...`
+  fallback, and the `ENDO_GATEWAY_BOOTSTRAP_SOCK` /
+  `ENDO_GATEWAY_ADMIN_SOCK` operator overrides. The two socks are
+  always distinct file paths; deployment is responsible for the
+  admin sock's stricter parent-directory mode (`0700`) so only the
+  administrator OS account can `connect(2)` to it.
 
 Deferred to follow-on PRs:
 
@@ -169,14 +176,16 @@ inventory. The phase-1 through phase-3 slices expose:
   `getConfig`, `getBootstrap`, `getAdmin`.
 - `AppsNameHub`: `bind`, `unbind`, `list`, `lookup`, `has`.
 - `GatewayBootstrap`: `challenge`, `register`, `registerRelay`,
-  `getBindAddress`, `getApps`, `getAdmin`.
+  `getBindAddress`, `getApps`. The bootstrap channel carries the
+  registrar exo only; it does **not** expose the admin facet.
 - `Registration`: `publishWeblet`, `unpublishWeblet`,
   `addPublicKey`, `deregister`, `listWeblets`, `listPublicKeys`.
 - `GatewayAdmin`: `listRegistrations`, `deregisterRelay`,
   `listVirtualHosts`, `getResourceBalances`, `getCounters`. The
   admin facet is reachable only via `gateway.getAdmin()`
-  in-process and `bootstrap.getAdmin()` over the sock; the public
-  HTTP / WS surface does not expose it.
+  in-process and over the admin sock (`admin.sock`); the public
+  HTTP / WS surface does not expose it, and the bootstrap sock
+  does not expose it.
 
 ### Bootstrap challenge-response
 

packages/gateway/index.js

@@ -59,7 +59,9 @@ export { makeGatewayAdmin } from './src/admin.js';
 
 export {
   resolveBootstrapSocketPath,
+  resolveAdminSocketPath,
   BOOTSTRAP_SOCKET_BASENAME,
+  ADMIN_SOCKET_BASENAME,
   SYSTEM_RUNTIME_DIR_LINUX,
   USER_RUNTIME_SUBDIR,
 } from './src/sock-paths.js';
@@ -119,15 +121,15 @@ const GatewayInterface = M.interface('Gateway', {
  *   embedding the gateway in-realm calls `getBootstrap` directly.
  * @property {() => Promise<GatewayAdmin>} getAdmin Returns the
  *   `GatewayAdmin` exo (Feature 7). Throws when the `adminDaemon`
- *   feature toggle is off, or when `sockBootstrap` is off (admin
- *   depends on the sock bootstrap for its access channel, and the
- *   config validator already rejects `adminDaemon=true` with
- *   `sockBootstrap=false`; the in-process accessor mirrors the
- *   surface contract: there is no admin authority without a sock
- *   bootstrap to gate it). The admin facet is **never** served on
- *   the gateway's public HTTP / WS surface; it is reachable only
- *   in-process (this method) and through the sock bootstrap's
- *   `getAdmin`.
+ *   feature toggle is off. The admin facet is **never** served on
+ *   the gateway's public HTTP / WS surface, and is **never**
+ *   reached through the bootstrap sock; it is reachable only
+ *   in-process (this method) and over a separate admin sock
+ *   (`admin.sock`) whose listener lands in a follow-on PR alongside
+ *   the bootstrap sock's listener. The two socks are distinct file
+ *   paths and the admin sock's deployment is responsible for
+ *   placing it under a non-world-traversable parent directory so
+ *   only the administrator OS account can `connect(2)`.
  */
 
 /**
@@ -165,6 +167,19 @@ export const makeGateway = ({ powers = {}, config: configIn = {} } = {}) => {
   // are the platform-bound primitives. A toggle-on but no-powers
   // configuration is treated as a startup error because it would
   // otherwise silently behave like toggle-off.
+  //
+  // The admin facet (Feature 7) is wired in iff the adminDaemon
+  // toggle is on. The admin facet uses the bootstrap's
+  // registration table as its read source, so when both toggles
+  // are on it shares the bootstrap's in-process backplane; when
+  // only `adminDaemon` is on (`sockBootstrap` off), the admin
+  // facet wires against a self-contained empty backplane and
+  // serves the in-process accessor with a documented empty
+  // registration view. The admin's access channel is its own sock
+  // (`admin.sock`), not the bootstrap sock; the two have
+  // independent toggles so that a deployment can offer
+  // administrator access without exposing the bootstrap sock and
+  // vice versa.
   /** @type {ReturnType<typeof makeGatewayBootstrap> | undefined} */
   let bootstrapHandle;
   /** @type {GatewayAdmin | undefined} */
@@ -180,42 +195,37 @@ export const makeGateway = ({ powers = {}, config: configIn = {} } = {}) => {
         X`sockBootstrap requires powers.clock; supply a ClockPowers adapter or disable the feature toggle`,
       );
     }
-    // The admin facet (Feature 7) is wired in iff both the
-    // sockBootstrap and adminDaemon toggles are on; the config
-    // validator already rejects `adminDaemon=true` with
-    // `sockBootstrap=false`, so the only path here that creates an
-    // admin facet is the both-on path. We pass a forward-reference
-    // `getAdmin` thunk to the bootstrap because the bootstrap is
-    // the holder for the in-process admin backplane (the second
-    // return value); the admin facet itself is constructed below
-    // with that backplane in hand.
     bootstrapHandle = makeGatewayBootstrap({
       crypto: powers.crypto,
       clock: powers.clock,
       apps,
       getBindAddress: renderBindAddress,
-      getAdmin: mergedConfig.enableFeatures.adminDaemon
-        ? () => {
-            // adminFacet is assigned immediately below; the thunk
-            // is only ever invoked after `makeGateway` returns.
-            if (adminFacet === undefined) {
-              throw makeError(X`Admin facet was not constructed`);
-            }
-            return adminFacet;
+    });
+  }
+  if (mergedConfig.enableFeatures.adminDaemon) {
+    // When the bootstrap is also on, the admin reads the same
+    // registration table. When the bootstrap is off, the admin
+    // facet still exists but sees an empty table; that path is
+    // useful for an embedder that wants admin reads of virtual
+    // hosts and the resource ledger without exposing the
+    // registration channel at all.
+    const backplane =
+      bootstrapHandle !== undefined
+        ? {
+            listRegisteredPeers: bootstrapHandle.listRegisteredPeers,
+            deregisterByPublicKey: bootstrapHandle.deregisterByPublicKey,
+            pendingNonces: bootstrapHandle.pendingNonces,
           }
-        : undefined,
+        : {
+            listRegisteredPeers: () => harden([]),
+            deregisterByPublicKey: () => false,
+            pendingNonces: () => 0,
+          };
+    adminFacet = makeGatewayAdmin({
+      backplane,
+      apps,
+      resourceLedger: powers.resourceLedger,
     });
-    if (mergedConfig.enableFeatures.adminDaemon) {
-      adminFacet = makeGatewayAdmin({
-        backplane: {
-          listRegisteredPeers: bootstrapHandle.listRegisteredPeers,
-          deregisterByPublicKey: bootstrapHandle.deregisterByPublicKey,
-          pendingNonces: bootstrapHandle.pendingNonces,
-        },
-        apps,
-        resourceLedger: powers.resourceLedger,
-      });
-    }
   }
 
   const exo = makeExo(
@@ -267,27 +277,19 @@ export const makeGateway = ({ powers = {}, config: configIn = {} } = {}) => {
       },
       async getAdmin() {
         // Per Feature 7: admin authority is reachable in-process
-        // and over the sock bootstrap, never over the network. The
-        // two `disabled` errors below preserve that contract by
-        // refusing to hand out the facet when either toggle is
-        // off; a refactor that quietly relaxed this would put
-        // admin authority on the public surface.
+        // and over the admin sock, never over the network and
+        // never through the bootstrap sock. The disabled error
+        // below preserves that contract by refusing to hand out
+        // the facet when the toggle is off; a refactor that
+        // quietly relaxed this would put admin authority on the
+        // public surface.
         if (!mergedConfig.enableFeatures.adminDaemon) {
           throw makeError(
             X`Gateway admin is disabled (set enableFeatures.adminDaemon=true)`,
           );
         }
-        if (!mergedConfig.enableFeatures.sockBootstrap) {
-          // The config validator rejects this combination, so
-          // reaching this branch implies a refactor that loosened
-          // the validator. We keep the local check as
-          // defense-in-depth.
-          throw makeError(
-            X`Gateway admin requires sockBootstrap; set enableFeatures.sockBootstrap=true`,
-          );
-        }
         if (adminFacet === undefined) {
-          // Unreachable in normal use; both toggles are on yet
+          // Unreachable in normal use; the toggle is on yet
           // construction did not produce a facet. We surface the
           // wiring bug loudly rather than returning undefined.
           throw makeError(X`Gateway admin facet is not wired`);

packages/gateway/src/admin.js

@@ -4,32 +4,37 @@
  * @file `GatewayAdmin` exo for the gateway's local administrator
  *   surface (design Feature 7).
  *
- * The administrator's handle is the sock bootstrap from Feature 4
- * extended with a `GatewayAdmin` facet. A process that can connect
- * to the gateway's bootstrap sock holds the administrator's
- * authority: it can inspect the registration table, inspect the
- * virtual-host bindings, force-deregister a relay by public key,
- * and read per-account resource balances via an injected
- * `ResourceLedger` (Feature 1, deferred).
+ * The administrator's handle is a separate local sock (`admin.sock`,
+ * see `sock-paths.js`) gated by ACL such that only the administrator
+ * OS account may connect. A process that can connect to the admin
+ * sock holds the administrator's authority: it can inspect the
+ * registration table, inspect the virtual-host bindings,
+ * force-deregister a relay by public key, and read per-account
+ * resource balances via an injected `ResourceLedger` (Feature 1,
+ * deferred).
  *
  * `GatewayAdmin` is reachable in exactly two ways:
  *
  *   1. In-process, via `gateway.getAdmin()`. Embedders that already
  *      speak CapTP hold the exo directly.
- *   2. Over the local sock bootstrap, via
- *      `E(bootstrap).getAdmin()`. The filesystem permissions on the
- *      sock gate who-may-call.
+ *   2. Over the local admin sock. The admin sock is mode `0600` and
+ *      its parent directory is mode `0700` (deployment-enforced),
+ *      so only the administrator OS account can `connect(2)` to it.
+ *      The admin sock is **distinct** from the bootstrap sock
+ *      (which any local user daemon may use to register itself);
+ *      the two channels exist precisely so that registration
+ *      authority does not double as admin authority.
  *
  * The exo is **never** served on the gateway's public HTTP / WS
- * surface. The "admin authority off the network" rule lives in the
- * surface: the only entry capabilities are the in-process API and
- * the sock bootstrap. The HTTP / WS surface (which lands in later
- * phases) does not expose `GatewayAdmin`; the gateway's
- * `getBootstrap` throws when `sockBootstrap` is disabled, and
- * `getAdmin` throws when `adminDaemon` is disabled or when
- * `sockBootstrap` is disabled (the admin daemon depends on the sock
- * bootstrap for its access channel; the dependency is validated in
- * `mergeGatewayConfig`).
+ * surface, and is **never** reached through the bootstrap sock. The
+ * "admin authority off the network" rule lives in the surface: the
+ * only entry capabilities are the in-process API and the admin sock.
+ * The HTTP / WS surface (which lands in later phases) does not
+ * expose `GatewayAdmin`; the gateway's `getBootstrap` throws when
+ * `sockBootstrap` is disabled, and `getAdmin` throws when
+ * `adminDaemon` is disabled. The admin daemon does **not** depend on
+ * the bootstrap sock; the two are independent features with their
+ * own toggles and their own access channels.
  *
  * Wire shape: byte fields (public keys) follow the `@endo/bytes`
  * convention: immutable `ArrayBuffer` on the wire, `Uint8Array`

packages/gateway/src/bootstrap.js

@@ -42,7 +42,6 @@ import { makeNonceRegistry, NONCE_BYTE_LENGTH } from './proof-of-possession.js';
 
 /** @import { AppsNameHub } from './vhost.js' */
 /** @import { CryptoPowers, ClockPowers, ChallengeIssued } from './proof-of-possession.js' */
-/** @import { GatewayAdmin } from './admin.js' */
 
 /**
  * Expected raw Ed25519 public key length in bytes. The bootstrap
@@ -74,7 +73,6 @@ const GatewayBootstrapInterface = M.interface('GatewayBootstrap', {
   registerRelay: M.call(M.any()).returns(M.promise()),
   getBindAddress: M.call().returns(M.promise()),
   getApps: M.call().returns(M.promise()),
-  getAdmin: M.call().returns(M.promise()),
 });
 
 /**
@@ -274,18 +272,22 @@ const publicKeyToHex = bytes => {
 /**
  * @typedef {object} GatewayBootstrap CapTP-facing exo. Methods are
  *   `async` so they cross the wire as eventual sends.
+ *
+ * The bootstrap channel carries the registrar exo only: any local
+ * user daemon that can connect to the bootstrap sock may register
+ * itself, but **none** of these daemons have administrator
+ * authority. The `GatewayAdmin` exo (Feature 7) is **not**
+ * reachable through this bootstrap; it lives on a separate sock
+ * (`admin.sock`, see `sock-paths.js` and the gateway's
+ * `getAdmin` in-process accessor) gated by a stricter access
+ * control. The split keeps registration authority and admin
+ * authority on independent capability paths.
+ *
  * @property {() => Promise<ChallengePayload>} challenge
  * @property {(args: RegistrationArgs) => Promise<Registration>} register
  * @property {(args: RelayRegistrationArgs) => Promise<Registration>} registerRelay
  * @property {() => Promise<string>} getBindAddress
  * @property {() => Promise<AppsNameHub>} getApps
- * @property {() => Promise<GatewayAdmin>} getAdmin
- *   Returns the `GatewayAdmin` exo (Feature 7). The admin facet is
- *   reachable only over the sock bootstrap (this method) and via
- *   the in-process `gateway.getAdmin()` accessor; never over the
- *   network. Throws when the gateway's `adminDaemon` feature
- *   toggle is off, surfacing a clear error rather than silently
- *   returning a no-op.
  */
 
 /**
@@ -312,14 +314,6 @@ const publicKeyToHex = bytes => {
  *   from the configured value after `start()`).
  * @property {number} [ttlMs] Nonce TTL; defaults to the registry's
  *   own default (30s).
- * @property {() => GatewayAdmin} [getAdmin]
- *   Returns the `GatewayAdmin` exo (Feature 7). Injected from the
- *   gateway proper so the bootstrap and the gateway share a single
- *   admin facet. When unset, the bootstrap's `getAdmin` method
- *   throws "admin daemon is disabled"; the gateway proper supplies
- *   this only when both `sockBootstrap` and `adminDaemon` toggles
- *   are on. Keeping the admin wiring outside the bootstrap module
- *   avoids a circular import between `bootstrap.js` and `admin.js`.
  */
 
 /**
@@ -353,7 +347,6 @@ export const makeGatewayBootstrap = ({
   apps,
   getBindAddress,
   ttlMs,
-  getAdmin,
 }) => {
   if (crypto === undefined) {
     throw makeError(X`makeGatewayBootstrap requires crypto powers`);
@@ -550,14 +543,6 @@ export const makeGatewayBootstrap = ({
       async getApps() {
         return apps;
       },
-      async getAdmin() {
-        if (getAdmin === undefined) {
-          throw makeError(
-            X`Admin daemon is disabled (set enableFeatures.adminDaemon=true)`,
-          );
-        }
-        return getAdmin();
-      },
     }),
   );
 

packages/gateway/src/config.js

@@ -200,11 +200,6 @@ const validateFeatureDependencies = features => {
       X`captpRelay depends on sockBootstrap for registration; both must be enabled`,
     );
   }
-  if (features.adminDaemon && !features.sockBootstrap) {
-    throw makeError(
-      X`adminDaemon depends on sockBootstrap for its access channel; both must be enabled`,
-    );
-  }
   if (features.chatHosting && !features.virtualHosting) {
     throw makeError(
       X`chatHosting depends on virtualHosting for the Chat weblet's bind; both must be enabled`,