feat(runtime-exposure): least-privilege Tailscale HTTPS broker, shared contract, and persisted exposure state (#11524)

<!-- Simplified Technical English (ASD-STE100). -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip starts and supervises managed runtime services for a
project's execution workspaces, so an agent's branch can be previewed
while it works
> - Those services only listen on plain loopback HTTP. A person on
another device, or on a phone, cannot open the preview
> - A Tailscale HTTPS mapping solves this, but `tailscale serve` needs
host privileges that the Paperclip server process must not hold
> - This pull request adds the foundation only: a separate
least-privilege host broker, the shared exposure contract, and the
database columns that hold exposure state
> - Nothing calls the broker yet, so there is no behavior change. The
benefit is that the privileged surface is small, reviewable, and
isolated before any lifecycle code depends on it

## Linked Issues or Issue Description

No public GitHub issue exists. The change follows the feature request
template.

**Subsystem affected**

Managed workspace runtime services, the shared type and validator
package, and the database schema.

**Problem or motivation**

A managed runtime service binds to loopback only. There is no supported
way to reach that preview from another device. Adding HTTPS directly to
the server would mean the server process runs `tailscale serve`, which
needs privileges far wider than the task requires. A compromised or
buggy server could then map any port to the tailnet.

**Proposed solution**

Split the privileged work into a separate broker process with a narrow
protocol, and define one shared contract that the server, the UI, the
runtime, and the broker all read. Land this foundation first, with no
caller, so the privileged code can be reviewed on its own.

**Alternatives considered**

- Call `tailscale serve` from the server process. This was rejected
because it gives the server unrestricted mapping authority.
- Use `sudo` for single `tailscale` commands. This was rejected because
the argument list is the only guard, and it is easy to widen by
accident.
- Use a generic reverse proxy. This was rejected because it does not
remove the need for a privileged Tailscale mapping step.

**Roadmap alignment**

This supports the existing managed workspace runtime capability. It adds
no new product surface on its own.

**Additional context**

The broker is the security boundary of the feature, so it is
deliberately the first slice. Three later pull requests build on it: the
server exposure lifecycle, the runtime lease and recovery integration,
and the leased-port mediator.

## What Changed

- Add the `@paperclipai/tailscale-https-broker` workspace package. The
broker listens on a unix socket, authorizes each peer with
`SO_PEERCRED`, and answers a small request protocol.
- Restrict what the broker will map. It accepts only same-number
HTTPS-to-loopback pairs inside the Paperclip port range, refuses
protected ports, and confirms that the loopback port belongs to a
Paperclip-owned listener.
- Parse every request with a strict JSON reader that rejects duplicate
keys, prototype keys, and unknown fields.
- Write an append-only audit record for each broker decision.
- Add the shared exposure contract in `@paperclipai/shared`: the
`RuntimeExposureConfig`, `RuntimeExposureState`, and
`RuntimeExposureStatus` types, their zod validators, the app and HMR
port rules, and the loopback-bind helpers.
- Persist exposure state on `workspace_runtime_services` with the new
`exposure` column, plus the server-private `exposure_handle` and
`backend_url` columns that are never serialized to API clients.
- Add the `execution_workspace_runtime_leases` table that the later
lease slice uses.
- Extend the runtime read-model test fixture for the three new columns.

## Verification

Focused checks, all run on this branch:

- `pnpm --filter @paperclipai/tailscale-https-broker test` — 12 files,
82 tests pass. This covers peer credentials, port policy, protected
ports, the serve config writer, the strict JSON reader, argv parsing,
and the socket server.
- `pnpm --filter @paperclipai/tailscale-https-broker typecheck` — clean.
- `npx vitest run --root packages/shared src/runtime-exposure
src/validators/runtime-exposure.test.ts` — 3 files, 40 tests pass.
- `pnpm --filter @paperclipai/db typecheck` — runs `check:migrations`
first. Migration numbering and migration safety both pass.
- `pnpm --filter @paperclipai/shared typecheck` — clean.
- `pnpm --filter @paperclipai/ui typecheck` — clean.
- `npx vitest run --root server
src/services/workspace-runtime-read-model.test.ts` — 3 tests pass.
- `npx tsc --noEmit -p server/tsconfig.json` — 139 errors, which is
exactly the count on `master` before this branch. All 139 come from the
unbuilt `@paperclipai/plugin-sdk` package.

To confirm the exposure state is inert, start a managed runtime service
as usual. The new columns stay null and the service behaves as it does
today.

## Risks

- Migration risk is low. Both migrations only add a table and three
nullable columns. No column is backfilled and no existing column
changes. The migration safety check passes.
- Behavior risk is low. No code path calls the broker in this pull
request, and the shared exposure fields are optional.
- The broker is privileged, so it is the real risk surface. It is
mitigated by peer-credential authorization, a fixed port range, a
protected-port deny list, same-number pair enforcement,
listener-ownership checks, strict JSON parsing, and an audit trail.
Reviewers should read
`packages/tailscale-https-broker/src/authorization.ts` and
`src/port-policy.ts` closely.
- The broker requires a `tailscale` version floor, which its README
records. An older host CLI makes the broker refuse to start rather than
map incorrectly.
- `pnpm-lock.yaml` changes because a new workspace package is added. The
diff is the new importer block, plus one duplicate `tinyexec` entry that
pnpm removed.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR.

## Model Used

Claude Opus 5 (`claude-opus-5`), 1M context window, extended thinking,
with tool use and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

packages/tailscale-https-broker/src/socket-server.ts

@@ -0,0 +1,218 @@
+/**
+ * Unix-socket transport for the broker. Enforces the resource-consumption and
+ * protocol controls from PAP-17050 verdict requirement #5: length-prefixed
+ * frames with a hard byte cap, per-connection read/write/idle deadlines, a
+ * maximum concurrent-client bound, a per-UID client bound, reserved capacity
+ * for the Paperclip service UID, and bounded single-frame responses. All
+ * security decisions are delegated to the tested `BrokerCore`; this layer
+ * frames bytes, resolves peer identity, and bounds transport resource usage.
+ */
+import { createServer, type Server, type Socket } from "node:net";
+import { chmodSync, existsSync, unlinkSync } from "node:fs";
+import type { BrokerCore } from "./broker-core.js";
+import { ProtocolError, decodeRequest, MAX_REQUEST_BYTES } from "./protocol.js";
+import type { PeerCredentials } from "./types.js";
+
+const LENGTH_PREFIX_BYTES = 4;
+const MAX_RESPONSE_BYTES = 16 * 1024;
+const DEFAULT_MAX_CLIENTS = 32;
+const DEFAULT_MAX_CLIENTS_PER_UID = 8;
+const DEFAULT_RESERVED_SERVICE_CLIENTS = 4;
+
+export interface SocketServerConfig {
+  socketPath: string;
+  core: BrokerCore;
+  resolvePeer: (socket: Socket) => PeerCredentials;
+  serviceUid: number;
+  maxClients?: number;
+  maxClientsPerUid?: number;
+  reservedServiceClients?: number;
+  connectionDeadlineMs?: number;
+}
+
+export interface ClientAdmissionConfig {
+  maxClients: number;
+  maxClientsPerUid: number;
+  serviceUid: number;
+  reservedServiceClients: number;
+}
+
+/**
+ * Tracks admitted sockets by resolved UID. Non-service peers cannot consume
+ * the service reservation, and no UID can monopolize the global pool.
+ */
+export class ClientAdmissionController {
+  private active = 0;
+  private readonly activeByUid = new Map<number, number>();
+
+  constructor(private readonly config: ClientAdmissionConfig) {
+    assertPositiveInteger(config.maxClients, "maxClients");
+    assertPositiveInteger(config.maxClientsPerUid, "maxClientsPerUid");
+    assertNonNegativeInteger(config.serviceUid, "serviceUid");
+    assertNonNegativeInteger(config.reservedServiceClients, "reservedServiceClients");
+    if (config.maxClientsPerUid > config.maxClients) {
+      throw new Error("maxClientsPerUid must not exceed maxClients");
+    }
+    if (config.reservedServiceClients >= config.maxClients) {
+      throw new Error("reservedServiceClients must be less than maxClients");
+    }
+  }
+
+  tryAcquire(uid: number): boolean {
+    if (!Number.isInteger(uid) || uid < 0) return false;
+    const activeForUid = this.activeByUid.get(uid) ?? 0;
+    if (activeForUid >= this.config.maxClientsPerUid || this.active >= this.config.maxClients) {
+      return false;
+    }
+    const nonServiceLimit = this.config.maxClients - this.config.reservedServiceClients;
+    if (uid !== this.config.serviceUid && this.active >= nonServiceLimit) {
+      return false;
+    }
+    this.active += 1;
+    this.activeByUid.set(uid, activeForUid + 1);
+    return true;
+  }
+
+  release(uid: number): void {
+    const activeForUid = this.activeByUid.get(uid) ?? 0;
+    if (activeForUid <= 0) return;
+    this.active -= 1;
+    if (activeForUid === 1) {
+      this.activeByUid.delete(uid);
+    } else {
+      this.activeByUid.set(uid, activeForUid - 1);
+    }
+  }
+}
+
+export function startSocketServer(config: SocketServerConfig): Server {
+  const maxClients = config.maxClients ?? DEFAULT_MAX_CLIENTS;
+  const admission = new ClientAdmissionController({
+    maxClients,
+    maxClientsPerUid: config.maxClientsPerUid ?? Math.min(DEFAULT_MAX_CLIENTS_PER_UID, maxClients),
+    serviceUid: config.serviceUid,
+    reservedServiceClients:
+      config.reservedServiceClients ?? Math.min(DEFAULT_RESERVED_SERVICE_CLIENTS, maxClients - 1),
+  });
+  const deadlineMs = config.connectionDeadlineMs ?? 5_000;
+
+  if (existsSync(config.socketPath)) {
+    unlinkSync(config.socketPath);
+  }
+
+  const server = createServer((socket) => {
+    let peer: PeerCredentials;
+    try {
+      peer = config.resolvePeer(socket);
+    } catch {
+      socket.destroy();
+      return;
+    }
+    if (!admission.tryAcquire(peer.uid)) {
+      socket.destroy();
+      return;
+    }
+
+    let expected = -1;
+    const chunks: Buffer[] = [];
+    let received = 0;
+    let done = false;
+    let released = false;
+
+    const timer = setTimeout(() => socket.destroy(), deadlineMs);
+    timer.unref?.();
+
+    const release = (): void => {
+      if (released) return;
+      released = true;
+      clearTimeout(timer);
+      admission.release(peer.uid);
+    };
+
+    // Keep the admission slot until the kernel reports the socket closed. An
+    // error can precede `close`, so releasing here would briefly undercount
+    // live descriptors during an error storm.
+    socket.on("error", () => socket.destroy());
+    socket.on("close", release);
+
+    socket.on("data", (chunk: Buffer) => {
+      if (done) return;
+      received += chunk.byteLength;
+      if (received > LENGTH_PREFIX_BYTES + MAX_REQUEST_BYTES) {
+        socket.destroy();
+        return;
+      }
+      chunks.push(chunk);
+      const buf = Buffer.concat(chunks);
+      if (expected < 0) {
+        if (buf.byteLength < LENGTH_PREFIX_BYTES) return;
+        expected = buf.readUInt32BE(0);
+        if (expected > MAX_REQUEST_BYTES) {
+          socket.destroy();
+          return;
+        }
+      }
+      if (buf.byteLength < LENGTH_PREFIX_BYTES + expected) return;
+      const body = buf.subarray(LENGTH_PREFIX_BYTES, LENGTH_PREFIX_BYTES + expected);
+      void handleFrame(body);
+    });
+
+    const handleFrame = async (body: Buffer): Promise<void> => {
+      // Claim the connection before awaiting BrokerCore so trailing data cannot
+      // dispatch the same frame more than once.
+      done = true;
+      let response: unknown;
+      try {
+        const request = decodeRequest(body);
+        response = await config.core.handle(request, peer);
+      } catch (error) {
+        response =
+          error instanceof ProtocolError
+            ? { ok: false, requestId: error.requestId, code: error.code, message: error.code }
+            : { ok: false, requestId: null, code: "malformed_request", message: "malformed_request" };
+      }
+      writeResponse(socket, response);
+    };
+  });
+
+  server.listen(config.socketPath, () => {
+    // Socket file itself is restricted to the dedicated group; the parent
+    // directory ownership/mode is enforced by the installer.
+    try {
+      chmodSync(config.socketPath, 0o660);
+    } catch {
+      /* best effort; installer verifies */
+    }
+  });
+
+  server.maxConnections = maxClients;
+  return server;
+}
+
+function assertPositiveInteger(value: number, name: string): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function assertNonNegativeInteger(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+}
+
+function writeResponse(socket: Socket, response: unknown): void {
+  let json = JSON.stringify(response);
+  if (Buffer.byteLength(json, "utf8") > MAX_RESPONSE_BYTES) {
+    json = JSON.stringify({ ok: false, requestId: null, code: "internal_error", message: "internal_error" });
+  }
+  const body = Buffer.from(json, "utf8");
+  const frame = Buffer.allocUnsafe(LENGTH_PREFIX_BYTES + body.byteLength);
+  frame.writeUInt32BE(body.byteLength, 0);
+  body.copy(frame, LENGTH_PREFIX_BYTES);
+  try {
+    socket.end(frame);
+  } catch {
+    socket.destroy();
+  }
+}