SSH anywhere: Milestone 2 - sealed agent relay + destination upgrade

.changeset/ssh-relay-milestone-2.md

@@ -0,0 +1,17 @@
+---
+"@internal/server": major
+"@internal/node": major
+"@internal/subshell-protocol": major
+"@internal/pane-runtime": major
+"@internal/server-web": major
+"@internal/node-web": major
+"@internal/node-admin": major
+"@internal/backend-errors": major
+"@internal/mobile": major
+---
+
+SSH sealed agent relay (milestone 2): a machine that holds no keys can open an SSH-terminal pane anywhere its operator's key home can reach. The connecting machine's node binds a per-pane ssh-agent proxy socket (the pane's scoped `SSH_AUTH_SOCK`, unbound at teardown); every agent request is sealed machine-to-machine over the plane, which brokers the pairing and routes opaque envelopes by a routing ref and nothing else. The key home's responder probes the live agent's numbering (OpenSSH classic vs RFC 9987, learned per session, never assumed), forwards only `REQUEST_IDENTITIES` and `SIGN_REQUEST`, and scopes both to the grant's selected fingerprints. Origin rides an ES256 signature inside the sealed envelope; endpoint-contributed nonces and a monotonic per-direction sequence make every relayed byte replay-inert. Grants (`ssh_key_grants`) bind a key home to a destination selector; the first use of a new pair asks the key home's owner to approve (a durable `ssh_grant_requests` row plus an owner notification, a loud fail-fast refusal, never a hung pane), the approval records the chosen public fingerprints and captures the destination's host-key pin from the key home's own `known_hosts`, and revocation is instant both ways. Panes verify D against a per-session pinned `known_hosts` delivered on the signed relay-open (`StrictHostKeyChecking yes`, system-wide file disabled); a changed destination host key is a hard block and delete-plus-fresh-capture is the operator's TOFU recovery. Machine identity: every agent node carries an ES256 signing keypair reported at enroll, peers pin each other's signing AND encryption halves byte-equal in a store separate from channel pins, and the node's loopback dashboard and the machine trust card show the fingerprints for the out-of-band comparison. "Set up Subshell here" turns an open pane's destination into an enrolled node by driving the ordinary install one-liner over a separate non-interactive ssh exec, so the minted setup key never reaches the pane screen or its log; an installer line carrying a key is redacted twice over. The grants screen, the destination trust screen, and the launcher's key-home picker complete the surface.
+
+Deployment: update the server before the nodes. The link gate is exact-match at protocol 18, so an agent that has not crossed the bump is held and takes no relay traffic. Migrations 0049 through 0052 add the signing-key slots, the grants, the pending-approval rows, the host-key pins, and the pane's key-home column; never run them against a live database without a full archive. Nothing changes for anyone until a node's SSH gate is enabled and a launch names a key home.
+
+Proof: e2e spec 23 (the crown jewel) drives the whole path against a real `ssh-agent`, a real `sshd`, real node daemons, and the real broker, with a plane-side capture asserting only opaque envelopes cross, and the 10.x numbering, the fingerprint scope, the revoke cut, the lifetime cap, the setup-key redaction, and the changed-host-key block plus TOFU recovery all asserted end to end.

.claude/rules/security-context.md

@@ -164,7 +164,7 @@ Per-app mechanics (command lists and shapes, assistant screens, the reset path,
 
 Read via `GET /api/audit?limit=50` (admin). Rules: auth-family metadata carries method and ids, NEVER tokens/emails/IPs/UAs; the user-management family names its subject by email by convention (§3). Sign-in rows are SUCCESS only (failures write nothing so the trail can't be spam-DoSed); `auth.sign_out` is one row per session ended; trusted-origin probes write no row.
 
-Auth `auth.sign_in` / `auth.sign_out` · users/keys `user.create|role_change|password_reset|disabled_change|approve|reject`, `system-key.create|enable|disable|delete`, `emergency_login.rewrite_credential`, `setup_key.create` (no metadata) / `setup_key.revoke`, `settings.update` · auth providers `auth_provider.create|update|delete` (fields + issuer, never the secret) · subshells `subshell.create|terminate|restart|preset_switch|delete` · transfers `transfer.create|complete` (node ids, paths, byte and entry counts, sync flag, outcome; never contents) · nodes `node.enroll|delete|rename|key_rotate|reregister_key|reregister|allowed_dirs.update|config.update|maintenance.update|ssh_enabled.update|logging.update|update|update.unknown|shares_set|local_share_changed|service`, and the SSH launcher's `ssh.launch` `{nodeId, destination, subshellId}` (success only, written after the pane spawned; the canonical `host:port`, never config or key material; saved-host CRUD unaudited, the prompts precedent) · server `server.config.update|restart|logging.update|autostart.update|update|supervision.request` · plugins/networks/installers `plugin.install|enable|disable|uninstall|unpublish`, `network.configure|install|join|publish|unpublish|leave`, `agent.install`, `tmux.install`. Per-event metadata detail: §10.
+Auth `auth.sign_in` / `auth.sign_out` · users/keys `user.create|role_change|password_reset|disabled_change|approve|reject`, `system-key.create|enable|disable|delete`, `emergency_login.rewrite_credential`, `setup_key.create` (no metadata) / `setup_key.revoke`, `settings.update` · auth providers `auth_provider.create|update|delete` (fields + issuer, never the secret) · subshells `subshell.create|terminate|restart|preset_switch|delete` · transfers `transfer.create|complete` (node ids, paths, byte and entry counts, sync flag, outcome; never contents) · nodes `node.enroll|delete|rename|key_rotate|reregister_key|reregister|allowed_dirs.update|config.update|maintenance.update|ssh_enabled.update|ssh_identity.register (signing-key bootstrap over the link, ids + via only, never the key)|ssh_grant.request|ssh_grant.create (via first-use|manual; approve/create name the CHOSEN fingerprint VALUES + destination per spec §10 - the approve row is the only durable record of the operator's selection, and a fingerprint appears in NO log line or notification body)|ssh_grant.update|ssh_grant.delete (relaysClosed; the revoke also cuts live relays via closeForGrant "grant-revoked")|ssh_grant.approve|ssh_grant.deny (audit-only; grant-request expiry writes nothing)|ssh_relay.open|ssh_relay.close (plane rows, actorUserId null, named reason word, fingerprint COUNT only)|ssh_upgrade.run (the "Set up Subshell here" act, Task 14: pane/B/A/grant ids, canonical destination, exec id, outcome + service-chosen stage word; the minted setup key and ALL installer output appear in NO row and NO refusal copy)|logging.update|update|update.unknown|shares_set|local_share_changed|service`, and the SSH launcher's `ssh.launch` `{nodeId, destination, subshellId, grantId on a relay launch}` (success only, written after the pane spawned; the canonical `host:port`, never config or key material; saved-host CRUD unaudited, the prompts precedent) · server `server.config.update|restart|logging.update|autostart.update|update|supervision.request` · plugins/networks/installers `plugin.install|enable|disable|uninstall|unpublish`, `network.configure|install|join|publish|unpublish|leave`, `agent.install`, `tmux.install`. Per-event metadata detail: §10.
 
 ## Deliberate non-validation & accepted risks
 

apps/client/mobile/src/__tests__/push-routing.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "bun:test";
+import { decidePushAction, SETTINGS_HREF } from "../lib/push-routing";
+
+/**
+ * The tap/action decision behind a push (PR #338 review, Important 1): a
+ * `grant_approval` push carries the grant REQUEST uuid as `sid`, so the old
+ * blind push to `/subshell/<sid>` was a 404 dead-end and its Silence bell
+ * PATCHed a nonexistent subshell. `push-bridge` keeps the side effects; this
+ * pure helper owns the choice, which is all the regression needs pinning.
+ */
+describe("decidePushAction", () => {
+  it("grant_approval tap routes to the settings tab, never a phantom pane", () => {
+    const a = decidePushAction({ sid: "req-uuid", kind: "grant_approval", origin: "https://a" }, undefined);
+    expect(a).toEqual({ action: "route", href: SETTINGS_HREF });
+    expect(JSON.stringify(a)).not.toContain("/subshell/");
+    // The settings tab must be the spelled group route the app itself uses.
+    expect(SETTINGS_HREF).toBe("/(tabs)/settings");
+  });
+
+  it("grant_approval silence is ignored: no PATCH intent against a request id", () => {
+    const a = decidePushAction({ sid: "req-uuid", kind: "grant_approval", origin: "https://a" }, "silence");
+    expect(a).toEqual({ action: "ignore" });
+  });
+
+  it("pane kinds tap to /subshell/<sid>, encoded, unchanged", () => {
+    const a = decidePushAction({ sid: "sess-1", kind: "turn_complete", origin: "https://a" }, undefined);
+    expect(a).toEqual({ action: "route", href: "/subshell/sess-1" });
+    expect(decidePushAction({ sid: "a b", kind: "needs_attention" }, "open")).toEqual({
+      action: "route",
+      href: "/subshell/a%20b",
+    });
+  });
+
+  it("pane kinds silence asks for the bell PATCH with the sid", () => {
+    expect(decidePushAction({ sid: "sess-1", kind: "needs_attention" }, "silence")).toEqual({
+      action: "silence",
+      sid: "sess-1",
+    });
+  });
+
+  it("a pane payload with no sid is ignored (the pre-existing guard)", () => {
+    expect(decidePushAction({ kind: "turn_complete", origin: "https://a" }, undefined)).toEqual({
+      action: "ignore",
+    });
+    expect(decidePushAction({ kind: "exited" }, "silence")).toEqual({ action: "ignore" });
+  });
+});

apps/client/mobile/src/lib/notif-data.ts

@@ -4,10 +4,17 @@
  * handler share a shape.
  */
 export interface SubshellNotifData {
-  /** Subshell uuid — the only identifier that crosses the relay */
+  /** Subshell uuid (a `grant_approval` push carries the grant REQUEST uuid) */
   sid?: string;
-  /** Event class driving the generic body copy */
-  kind?: "turn_complete" | "needs_attention" | "exited" | "crashed" | "crashed_final";
+  /** Event class driving the generic body copy and the tap's destination (the server's NotifyKind, spelled here) */
+  kind?:
+    | "turn_complete"
+    | "needs_attention"
+    | "exited"
+    | "crashed"
+    | "crashed_final"
+    | "maintenance"
+    | "grant_approval";
   /** Origin that sent it — future multi-instance routing hint */
   origin?: string;
 }

apps/client/mobile/src/lib/push-routing.ts

@@ -0,0 +1,38 @@
+import type { SubshellNotifData } from "@/lib/notif-data";
+
+/**
+ * The tap/action decision behind a push response, kept pure so the routing
+ * rule is testable without the native listener (push-bridge owns the side
+ * effects: origin switching, the PATCH, the navigation).
+ */
+
+/** The settings tab, spelled like the app spells its group routes (`/(tabs)`). */
+export const SETTINGS_HREF = "/(tabs)/settings";
+
+/** What the app should DO about a push, decided from the opaque payload. */
+export type PushAction =
+  /** Navigate to `href` (after any instance switch push-bridge performs). */
+  | { action: "route"; href: string }
+  /** The lock-screen Silence bell: one `setNotify(sid, false)` PATCH. */
+  | { action: "silence"; sid: string }
+  /** Do nothing at all: no navigation, no request. */
+  | { action: "ignore" };
+
+/**
+ * `grant_approval` pushes name the grant REQUEST uuid in `sid`, not a pane:
+ * their tap lands on the settings tab (the real surface) and their silence
+ * action is ignored (there is no subshell bell to PATCH). Every other kind
+ * behaves exactly as it always has: tap to `/subshell/<sid>`, silence to the
+ * PATCH (PR 338 review, Important 1).
+ * @param data - The opaque payload (sid + kind + origin)
+ * @param actionIdentifier - The response's action id; only "silence" acts
+ */
+export function decidePushAction(data: SubshellNotifData, actionIdentifier?: string): PushAction {
+  const silence = actionIdentifier === "silence";
+  if (data.kind === "grant_approval") {
+    return silence ? { action: "ignore" } : { action: "route", href: SETTINGS_HREF };
+  }
+  if (!data.sid) return { action: "ignore" };
+  if (silence) return { action: "silence", sid: data.sid };
+  return { action: "route", href: `/subshell/${encodeURIComponent(data.sid)}` };
+}

apps/client/mobile/src/native/push.ts

@@ -51,6 +51,17 @@ export function configureNotifications(): void {
       options: { opensAppToForeground: false, isAuthenticationRequired: true },
     },
   ]);
+  // The action-free twin, named by `grant_approval` payloads server-side: a
+  // remote push surfaces actions only for a REGISTERED category, and that
+  // kind's sid is a grant REQUEST id, so the Silence bell has nothing to
+  // PATCH (PR 338 review, Important 1). Plain Open only.
+  void Notifications.setNotificationCategoryAsync("subshell-plain", [
+    {
+      identifier: "open",
+      buttonTitle: "Open",
+      options: { opensAppToForeground: true, isAuthenticationRequired: true },
+    },
+  ]);
 }
 
 /**

apps/client/mobile/src/providers/push-bridge.tsx

@@ -6,6 +6,7 @@ import { SUBSHELLS_KEY } from "@/hooks/query-keys";
 import { useIconBadge } from "@/hooks/use-icon-badge";
 import { useApp } from "@/lib/app-state";
 import type { SubshellNotifData } from "@/lib/notif-data";
+import { decidePushAction } from "@/lib/push-routing";
 import { configureNotifications, enrollPush } from "@/native/push";
 import { clientForOrigin } from "@/native/subshell-client-factory";
 import { useSubshell } from "@/providers/subshell-provider";
@@ -24,7 +25,10 @@ import { useSubshell } from "@/providers/subshell-provider";
  *   route itself is the biometric gate, §Security notes), "Silence bell" →
  *   one PATCH against the ORIGIN's client + list refresh, without
  *   foregrounding. An origin this phone no longer knows (forgotten instance)
- *   is ignored rather than opened on the wrong server.
+ *   is ignored rather than opened on the wrong server. A `grant_approval`
+ *   push switches instances the same way but lands on the settings tab, and
+ *   its Silence action is ignored (its sid names a grant request, not a pane;
+ *   PR 338 review, Important 1).
  *
  * The response listener mounts ONCE and reads the registry via
  * `useApp.getState()` at call time: an earlier version kept activeId/instances
@@ -53,21 +57,26 @@ export function PushBridge() {
       const { activeId, instances, setActive } = useApp.getState();
       const origin = data.origin && data.origin !== activeId ? data.origin : null;
       if (origin && !instances.some((i) => i.id === origin)) return; // unknown/forgotten instance
+      // The helper decides (pure, pinned in src/lib/push-routing.ts); this
+      // closure only performs. A `grant_approval` push routes to settings and
+      // ignores the Silence bell: its sid is a grant request, not a pane.
+      const action = decidePushAction(data, response.actionIdentifier);
+      if (action.action === "ignore") return;
       // The action belongs to the ORIGIN's instance, whatever is active now.
       const actor = origin ? clientForOrigin(origin) : client;
-      if (response.actionIdentifier === "silence") {
+      if (action.action === "silence") {
         // Background action: one quick PATCH; the app never opens.
         if (!actor) return;
         try {
-          await actor.setNotify(data.sid, false);
+          await actor.setNotify(action.sid, false);
           await qc.invalidateQueries({ queryKey: SUBSHELLS_KEY });
         } catch {
           /* signed-out mid-flight: the bell state re-converges on next open */
         }
         return;
       }
       if (origin) setActive(origin); // provider clears the query cache on switch
-      router.push(`/subshell/${encodeURIComponent(data.sid)}`);
+      router.push(action.href);
     };
     const sub = Notifications.addNotificationResponseReceivedListener((r) => void respond(r));
     // Cold start from a notification tap must route too, not just live taps.