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/audit.ts

@@ -0,0 +1,90 @@
+/**
+ * Append-only, bounded, redacted security audit (PAP-17050 verdict req #6).
+ *
+ * Every allow/deny and mutation outcome emits one event. Lease handles,
+ * bearer/session material, full environments, and raw unbounded CLI output are
+ * NEVER logged. All string fields are control-character-sanitized and length
+ * bounded to defeat log forging.
+ */
+import { appendFileSync } from "node:fs";
+import type { BrokerErrorCode, PeerCredentials } from "./types.js";
+
+const MAX_FIELD_LEN = 256;
+
+export interface AuditEvent {
+  timestampIso: string;
+  peer: PeerCredentials | null;
+  op: string;
+  runtimeId: string | null;
+  ports: number[];
+  requestId: string | null;
+  decision: "allow" | "deny";
+  reasonCode: BrokerErrorCode | "ok";
+  reason: string;
+  beforeDigest?: string;
+  afterDigest?: string;
+  cliExitCategory?: "ok" | "error" | "timeout" | "none";
+  recovery?: "none" | "quarantine" | "cleanup";
+}
+
+/** Strip control chars (defeats newline/log-forging) and bound length. */
+export function sanitizeField(value: string): string {
+  // eslint-disable-next-line no-control-regex
+  const stripped = value.replace(/[\x00-\x1f\x7f]/g, " ");
+  return stripped.length > MAX_FIELD_LEN ? `${stripped.slice(0, MAX_FIELD_LEN)}…` : stripped;
+}
+
+export function formatAuditLine(event: AuditEvent): string {
+  const safe = {
+    ts: event.timestampIso,
+    uid: event.peer?.uid ?? null,
+    gid: event.peer?.gid ?? null,
+    pid: event.peer?.pid ?? null,
+    op: sanitizeField(event.op),
+    runtimeId: event.runtimeId ? sanitizeField(event.runtimeId) : null,
+    ports: event.ports.filter((p) => Number.isInteger(p)).slice(0, 8),
+    requestId: event.requestId ? sanitizeField(event.requestId) : null,
+    decision: event.decision,
+    reasonCode: event.reasonCode,
+    reason: sanitizeField(event.reason),
+    beforeDigest: event.beforeDigest ? sanitizeField(event.beforeDigest) : undefined,
+    afterDigest: event.afterDigest ? sanitizeField(event.afterDigest) : undefined,
+    cliExitCategory: event.cliExitCategory,
+    recovery: event.recovery,
+  };
+  return JSON.stringify(safe);
+}
+
+export interface AuditSink {
+  write(event: AuditEvent): void;
+}
+
+/**
+ * Durable file audit sink. If the recommended `blockOnFailure` is set, a write
+ * failure throws so the caller can fail the mutation closed rather than mutate
+ * without a durable record.
+ */
+export class FileAuditSink implements AuditSink {
+  constructor(
+    private readonly path: string,
+    private readonly blockOnFailure = true,
+  ) {}
+
+  write(event: AuditEvent): void {
+    try {
+      appendFileSync(this.path, `${formatAuditLine(event)}\n`, { mode: 0o600 });
+    } catch (error) {
+      if (this.blockOnFailure) {
+        throw new Error(`audit sink write failed: ${(error as Error).message}`);
+      }
+    }
+  }
+}
+
+/** In-memory sink for tests. */
+export class MemoryAuditSink implements AuditSink {
+  readonly events: AuditEvent[] = [];
+  write(event: AuditEvent): void {
+    this.events.push(event);
+  }
+}