feat(runtime-exposure): least-privilege Tailscale HTTPS broker + shared contract (PAP-17051)

Foundation for opt-in `tailscale_https` exposure of managed branch runtimes,
implementing the PAP-17049 plan under the PAP-17050 threat-model verdict.

Broker (packages/tailscale-https-broker): root/dedicated-account host broker
exposing only idempotent list/expose/remove over a Unix socket. Implements the
six required verdict controls: SO_PEERCRED + UID/GID allowlist + unguessable
broker-issued lease handles (req #1); dedicated port allowlist + /proc listener
ownership/loopback proof before mutation (req #2); per-mutation transaction
(strict-parse serve JSON -> verify absence/exact-lease -> verify :443 -> one
fixed per-port op -> reread -> require only-intended-changed + :443 identical
-> atomic root-owned registry commit, quarantine-on-ambiguity) (req #3);
execve/shell=false argv built only from canonical integers + fixed tokens,
pinned CLI schema (req #4); versioned length-bounded strict-JSON protocol
(req #5); bounded append-only audit events (req #6). Deny-by-default for
Funnel/cert/Services/reset/set-config/path-handlers/:443/reserved ports.

Shared contract (packages/shared): single source of truth for exposure config,
lifecycle state (pending/ready/failed/cleanup_pending/removed), listener
ownership, and status, with strict zod validators and deterministic
app/HMR port-pair + URL derivation so DB/server/UI/runtime cannot drift.

Tests: broker 57/57, shared runtime-exposure 13/13, both typecheck clean.
Server/DB/UI lifecycle integration + docs land in follow-on commits.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/tailscale-https-broker/src/config.ts

@@ -0,0 +1,54 @@
+/**
+ * Environment-driven configuration for the broker host service. All values are
+ * validated; unsafe or missing required values make the broker refuse to start
+ * (fail closed).
+ */
+import { registryPathUnsafeReason } from "./registry.js";
+
+export interface BrokerHostConfig {
+  socketPath: string;
+  registryPath: string;
+  auditPath: string;
+  tailscaleBinPath: string;
+  nodeIdentity: string;
+  serviceUid: number;
+  serviceGid: number;
+  runtimeUid: number;
+  trustSocketPermissions: boolean;
+}
+
+function requireEnv(env: NodeJS.ProcessEnv, key: string): string {
+  const value = env[key];
+  if (!value || value.trim().length === 0) {
+    throw new Error(`missing required env: ${key}`);
+  }
+  return value;
+}
+
+function requireUid(env: NodeJS.ProcessEnv, key: string): number {
+  const raw = requireEnv(env, key);
+  if (!/^[0-9]+$/.test(raw)) throw new Error(`${key} must be a non-negative integer`);
+  return Number(raw);
+}
+
+export function loadHostConfig(env: NodeJS.ProcessEnv): BrokerHostConfig {
+  const config: BrokerHostConfig = {
+    socketPath: env.BROKER_SOCKET_PATH ?? "/run/paperclip-tailscale-broker/broker.sock",
+    registryPath: env.BROKER_REGISTRY_PATH ?? "/var/lib/paperclip-tailscale-broker/registry.json",
+    auditPath: env.BROKER_AUDIT_PATH ?? "/var/log/paperclip-tailscale-broker/audit.log",
+    tailscaleBinPath: env.BROKER_TAILSCALE_BIN ?? "/usr/bin/tailscale",
+    nodeIdentity: requireEnv(env, "BROKER_NODE_IDENTITY"),
+    serviceUid: requireUid(env, "BROKER_SERVICE_UID"),
+    serviceGid: requireUid(env, "BROKER_SERVICE_GID"),
+    runtimeUid: requireUid(env, "BROKER_RUNTIME_UID"),
+    trustSocketPermissions: env.BROKER_TRUST_SOCKET_PERMISSIONS === "true",
+  };
+  if (!config.tailscaleBinPath.startsWith("/")) {
+    throw new Error("BROKER_TAILSCALE_BIN must be an absolute path");
+  }
+  const unsafe = registryPathUnsafeReason(config.registryPath);
+  if (unsafe) {
+    throw new Error(`refusing to start: ${unsafe} (${config.registryPath})`);
+  }
+  return config;
+}