@moondeck/station 0.0.1 → 1.0.0

package/lib/obs.ts

@@ -0,0 +1,512 @@
+/**
+ * Host-agent crash reporting (ADR-071). Default-ON for installed hosts,
+ * with disclosure and a first-class opt-out — an installed product whose
+ * crash reporting requires hand-editing .env.local reports nothing from
+ * exactly the machines we need visibility into. The contract:
+ *
+ * - UAI_TELEMETRY_DISABLED=1  → nothing initializes, zero bytes leave the
+ *   machine. The one switch, documented everywhere the DSN default is.
+ * - UAI_SENTRY_DSN=…          → operator override (self-hosters pointing at
+ *   their own Sentry).
+ * - otherwise                 → DEFAULT_HOST_DSN below. DSNs are public by
+ *   design (every browser bundle ships one); this is errors-only crash
+ *   reporting, content-scrubbed, console breadcrumbs disabled.
+ *
+ * Every start with the default DSN logs a disclosure line naming the
+ * opt-out, and the default only ACTIVATES after the persisted disclosure
+ * marker exists (see the gate below).
+ *
+ * Captures uncaught exceptions / unhandled rejections (then the process
+ * exits as it does today; launchd/systemd restarts it), plus
+ * bridge-lifecycle breadcrumbs for context. Console breadcrumbs are
+ * disabled: host console output carries third-party process text
+ * (git/docker stderr, agent lifecycle lines) no scrubber can bound.
+ *
+ * Errors only — tracesSampleRate 0. The WSS heartbeat shares this event loop
+ * (agent-notes: never block it); we add no per-event work.
+ *
+ * The scrub rules MIRROR lib/obs/scrub.ts on the cloud side, duplicated by
+ * hand because the cloud may not import host internals and vice versa
+ * (eslint import guard). Every behavior here — key lists, string patterns,
+ * depth cap ("[max-depth]", never raw pass-through), hostile-proxy fencing —
+ * must match the cloud scrubber; obs.test.ts holds the parity regressions
+ * and docs/observability.md holds the shared table. The hooks are exported
+ * so tests exercise exactly what Sentry runs.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import * as Sentry from "@sentry/node";
+
+import { STATION } from "../src/station-identity";
+import { env } from "./env";
+import { redactActiveConnectionSecrets } from "./connection-secret-redaction";
+import { isDevelopmentLaunch } from "./launch-mode";
+
+/**
+ * The uai-host Sentry project's DSN, baked into the shipped package (npm +
+ * desktop-vendored copy). Public by design — a DSN can only ingest events,
+ * never read them. Activation is still gated: persisted disclosure marker,
+ * never in repo checkouts/dev/test, UAI_TELEMETRY_DISABLED=1 kills it,
+ * UAI_SENTRY_DSN overrides it.
+ */
+export const DEFAULT_HOST_DSN =
+  "https://f1b34b8b7df6f7ee519500fd06faa872@o4511765849178112.ingest.us.sentry.io/4511768446369792";
+
+export type HostDsnSource = "disabled" | "explicit" | "default" | "none";
+
+/**
+ * Pure resolution of the telemetry contract above — unit-tested. The baked
+ * DEFAULT applies only to INSTALLED hosts: a repo checkout
+ * (UAI_AGENT_FROM_REPO) or an explicit dev/test NODE_ENV never
+ * default-activates — the consent claim is "installed product telemetry",
+ * not "developing the repo phones home". An explicit UAI_SENTRY_DSN is
+ * always honored.
+ */
+export function resolveHostDsn(env: {
+  UAI_TELEMETRY_DISABLED?: string;
+  UAI_SENTRY_DSN?: string;
+  NODE_ENV?: string;
+  UAI_AGENT_FROM_REPO?: string;
+  UAI_LAUNCHED_FROM_REPO?: string;
+}): { dsn: string | null; source: HostDsnSource } {
+  if (env.UAI_TELEMETRY_DISABLED === "1") {
+    return { dsn: null, source: "disabled" };
+  }
+  if (env.UAI_SENTRY_DSN) {
+    return { dsn: env.UAI_SENTRY_DSN, source: "explicit" };
+  }
+  // UAI_LAUNCHED_FROM_REPO is stamped by src/load-env.ts from its own
+  // filesystem position (review finding: real dev launches — root
+  // `pnpm host-agent`, desktop non-packaged — set none of the explicit
+  // flags). The explicit flags remain as overrides/belt.
+  const repoOrDev = isDevelopmentLaunch(env);
+  if (DEFAULT_HOST_DSN && !repoOrDev) {
+    return { dsn: DEFAULT_HOST_DSN, source: "default" };
+  }
+  return { dsn: null, source: "none" };
+}
+
+/**
+ * The disclosure text, single-sourced: the service start log line and the
+ * `uai-host install` / `pair` / `setup` / `start` / `restart` stdout all
+ * print exactly this. Says what is TRUE, no more: crash reports carry a
+ * pseudonymous hostId tag ("anonymous" would overclaim), OS/runtime
+ * versions ride along, and error text is scrubbed for secret shapes but
+ * pattern scrubbing cannot recognize arbitrary prose — the residual-risk
+ * stance documented in docs/observability.md, mirrored here instead of a
+ * "never" the implementation can't fully guarantee.
+ */
+export const TELEMETRY_NOTICE =
+  "crash reporting is ON by default for installed hosts. Sent on a crash " +
+  "only: the error and stack trace (paths + secret-shaped strings " +
+  "redacted), recent bridge-connection breadcrumbs, OS/runtime versions, " +
+  "agent version, and a pseudonymous host id — no sessions, no usage " +
+  "pings, no request data, and telemetry is designed to exclude chat, " +
+  "prompts, env values, and repo content (error text is scrubbed, but " +
+  "redaction is pattern-based, not perfect). Disable any time: " +
+  "UAI_TELEMETRY_DISABLED=1 in the host's .env.local.";
+
+/**
+ * Persisted disclosure gate (review): the baked DEFAULT only activates
+ * after the notice has actually been SHOWN once on this machine — a service
+ * silently upgraded via reboot/KeepAlive never sees a terminal, so it stays
+ * off until the next interactive `uai-host` command (or the desktop
+ * first-run dialog, which writes the same marker) discloses and persists.
+ */
+export function telemetryDisclosureMarkerPath(home: string = env.uaiHome): string {
+  return join(home, ".telemetry-disclosed");
+}
+
+export function hasSeenTelemetryDisclosure(home: string = env.uaiHome): boolean {
+  try {
+    return existsSync(telemetryDisclosureMarkerPath(home));
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort persist; called by the surfaces that PRINT the notice. */
+export function persistTelemetryDisclosure(home: string = env.uaiHome): void {
+  try {
+    mkdirSync(home, { recursive: true });
+    writeFileSync(
+      telemetryDisclosureMarkerPath(home),
+      `${new Date().toISOString()}\n`,
+    );
+  } catch {
+    // Worst case: the notice prints again next time.
+  }
+}
+
+/** Pure gate — unit-tested: the default requires a persisted disclosure. */
+export function defaultActivationAllowed(
+  source: HostDsnSource,
+  disclosureSeen: boolean,
+): boolean {
+  return source !== "default" || disclosureSeen;
+}
+
+/** The notice CLI commands print, or null when the default isn't active. */
+export function telemetryNoticeIfActive(): string | null {
+  return resolveHostDsn(process.env).source === "default"
+    ? TELEMETRY_NOTICE
+    : null;
+}
+
+let initialized = false;
+
+const SUBSTRING_KEY =
+  /(token|secret|password|passwd|credential|authorization|cookie|apikey|api[-_]key|private[-_]?key)/i;
+const EXACT_KEY =
+  /^(prompt|initialprompt|globalcontext|defaultprompt|content|text|body|env|http\.query|url\.query|query|query_string|querystring|search|http\.fragment|url\.fragment|fragment|hash)$/i;
+
+function isSensitiveKey(key: string): boolean {
+  return EXACT_KEY.test(key) || SUBSTRING_KEY.test(key);
+}
+
+const URL_CREDENTIALS_RE = /(\/\/)[^/\s@:]+:[^/\s@]+@/g;
+// ?query OR #fragment tails (fragments carry OAuth implicit tokens) —
+// mirrors lib/obs/scrub.ts.
+const URL_TAIL_RE = /(https?:\/\/[^\s"'<>?#]+)([?#])[^\s"'<>]*/g;
+const RELATIVE_URL_TAIL_RE =
+  /(^|[\s"'`(=])(\/[A-Za-z0-9_\-./~%[\]]*)([?#])[^\s"'<>]*/g;
+const EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+const TOKEN_RES: RegExp[] = [
+  /\b(?:sk|rk)-[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{16,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[a-z]-[A-Za-z0-9-]{10,}\b/g,
+  /\bwhsec_[A-Za-z0-9]{8,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*\b/g,
+  /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi,
+];
+
+// Identity/repo-metadata rules beyond the cloud mirror — host strings carry
+// operator PATHS: the home dir embeds the username, and task worktree paths
+// embed project slugs (repo-identifying — "no repo data" must hold for
+// stack frames too).
+/**
+ * Separator-agnostic, case-insensitive home matcher (exported for injected-
+ * home tests): Sentry normalizes Windows ESM frame paths to FORWARD slashes,
+ * so an exact `C:\Users\Alice` match left `C:/Users/Alice` unredacted
+ * (review probe), and Windows paths are case-insensitive.
+ */
+export function buildHomePathRe(home: string): RegExp {
+  const pattern = home
+    .split(/[\\/]+/)
+    .filter((seg) => seg !== "")
+    .map((seg) => seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[\\\\/]+");
+  // A POSIX home is rooted — the leading separator must be part of the
+  // match, or "/home/op" replaces as "/~". Windows homes ("C:\…") aren't.
+  const lead = /^[\\/]/.test(home) ? "[\\\\/]+" : "";
+  return new RegExp(lead + pattern, "gi");
+}
+
+const HOME_RE = buildHomePathRe(homedir());
+// MCP gateway routes are BEARER-IN-PATH: /t/<token>/<connection-slug>
+// (mcp-gateway.ts). A crash near the gateway put both verbatim into event
+// strings (review receiver) — normalize the whole segment pair.
+const MCP_GATEWAY_PATH_RE = /(\/t\/)[^/\s"'?#]+(\/[^/\s"'?#]+)?/g;
+// Both separator styles: hosts run on Windows too, and a POSIX-only rule
+// left repo slugs intact in win32 paths (review probe).
+const TASK_WORKSPACE_SLUG_RE =
+  /([/\\]tasks[/\\][A-Za-z0-9_-]+[/\\]workspace[/\\])[^/\\\s"']+/g;
+
+export function scrubHostString(value: string): string {
+  let out = redactActiveConnectionSecrets(value);
+  out = out.replace(URL_CREDENTIALS_RE, "$1[redacted]@");
+  out = out.replace(URL_TAIL_RE, "$1$2[redacted]");
+  out = out.replace(RELATIVE_URL_TAIL_RE, "$1$2$3[redacted]");
+  for (const re of TOKEN_RES) out = out.replace(re, "[redacted]");
+  out = out.replace(EMAIL_RE, "[email]");
+  out = out.replace(HOME_RE, "~");
+  out = out.replace(TASK_WORKSPACE_SLUG_RE, "$1[project]");
+  out = out.replace(MCP_GATEWAY_PATH_RE, "$1[redacted]");
+  return out;
+}
+
+/** URL field sanitizer: drop ?query/#fragment wholesale, then string-scrub. */
+export function scrubHostUrl(url: string): string {
+  const q = url.indexOf("?");
+  const h = url.indexOf("#");
+  const cut = q === -1 ? h : h === -1 ? q : Math.min(q, h);
+  return scrubHostString(
+    cut === -1 ? url : `${url.slice(0, cut)}${url[cut]}[redacted]`,
+  );
+}
+
+/** Mirror of the cloud scrubValue: depth-capped, hostile-proxy-fenced. */
+export function scrubHostValue(value: unknown, depth = 0): unknown {
+  if (typeof value === "string") return scrubHostString(value);
+  if (value === null || typeof value !== "object") return value;
+  if (depth > 8) return "[max-depth]";
+  try {
+    if (Array.isArray(value)) {
+      return value.map((v) => {
+        try {
+          return scrubHostValue(v, depth + 1);
+        } catch {
+          return "[unreadable]";
+        }
+      });
+    }
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>)) {
+      if (isSensitiveKey(k)) {
+        out[k] = "[scrubbed]";
+        continue;
+      }
+      try {
+        out[k] = scrubHostValue((value as Record<string, unknown>)[k], depth + 1);
+      } catch {
+        out[k] = "[unreadable]";
+      }
+    }
+    return out;
+  } catch {
+    return "[unreadable]";
+  }
+}
+
+interface HostScrubbableBreadcrumb {
+  category?: string;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+
+interface HostScrubbableFrame {
+  filename?: string;
+  abs_path?: string;
+  module?: string;
+}
+
+interface HostScrubbableEvent {
+  message?: string;
+  server_name?: string;
+  transaction?: string;
+  request?: unknown;
+  exception?: {
+    values?: Array<{
+      type?: string;
+      value?: string;
+      stacktrace?: { frames?: HostScrubbableFrame[] };
+    }>;
+  };
+  extra?: Record<string, unknown>;
+  contexts?: Record<string, Record<string, unknown> | undefined>;
+  breadcrumbs?: HostScrubbableBreadcrumb[];
+}
+
+/** The exact beforeSend hook Sentry runs — exported for regression tests. */
+export function scrubHostEvent<T extends HostScrubbableEvent>(event: T): T {
+  // The SDK stamps os.hostname() ("Diogos-Mac-Studio.local") as server_name
+  // — identifying, and exactly what the pseudonymous hostId tag replaces.
+  delete event.server_name;
+  // MINIMAL CONTRACT (review): request context and transaction names are
+  // DROPPED wholesale, not sanitized. The MCP gateway is bearer-in-path
+  // (/t/<token>/<slug>), and per-field scrubbing left the token verbatim in
+  // both `transaction` and `request.url`, plus mcp-session-id in headers —
+  // the disclosed payload is the error, not the route that raised it.
+  delete event.request;
+  delete event.transaction;
+  if (typeof event.message === "string") {
+    event.message = scrubHostString(event.message);
+  }
+  if (event.exception?.values) {
+    for (const ex of event.exception.values) {
+      if (typeof ex.value === "string") ex.value = scrubHostString(ex.value);
+      // Stack frame paths ride the operator's home dir (username) and task
+      // worktree slugs (repo names) — string-scrub them frame by frame.
+      for (const frame of ex.stacktrace?.frames ?? []) {
+        if (typeof frame.filename === "string") {
+          frame.filename = scrubHostString(frame.filename);
+        }
+        if (typeof frame.abs_path === "string") {
+          frame.abs_path = scrubHostString(frame.abs_path);
+        }
+        if (typeof frame.module === "string") {
+          frame.module = scrubHostString(frame.module);
+        }
+      }
+    }
+  }
+  if (event.extra) {
+    event.extra = scrubHostValue(event.extra) as Record<string, unknown>;
+  }
+  if (event.contexts) {
+    // Allow-list, not scrub: the SDK's environment-derived system context
+    // (device, app, culture, cloud resource) exceeds the disclosed "error +
+    // stack trace + host id + version". Keep only what crash triage needs.
+    const pruned: NonNullable<HostScrubbableEvent["contexts"]> = {};
+    const os = event.contexts.os;
+    if (os) pruned.os = { name: os.name, version: os.version };
+    const runtime = event.contexts.runtime;
+    if (runtime) {
+      pruned.runtime = { name: runtime.name, version: runtime.version };
+    }
+    if (event.contexts.trace) {
+      pruned.trace = scrubHostValue(event.contexts.trace) as Record<
+        string,
+        unknown
+      >;
+    }
+    event.contexts = pruned as T["contexts"];
+  }
+  if (Array.isArray(event.breadcrumbs)) {
+    // Bridge-only is ENFORCED here too, not just at beforeBreadcrumb: any
+    // crumb already sitting on the event (added before init hooks, or by a
+    // future integration) is allow-listed away (review probe: a native
+    // `http` crumb carrying a private repo URL shipped unchanged).
+    event.breadcrumbs = event.breadcrumbs
+      .filter((crumb) => crumb?.category === "bridge")
+      .map((crumb) => scrubHostBreadcrumb(crumb))
+      .filter((crumb): crumb is NonNullable<typeof crumb> => crumb !== null);
+  }
+  return event;
+}
+
+/**
+ * The exact beforeBreadcrumb hook Sentry runs — exported for tests.
+ * FAIL-CLOSED allow-list (review): only the curated `bridge` category
+ * exists in this telemetry; anything else — whatever integration or code
+ * path produced it — is dropped, then the survivor is scrubbed.
+ */
+export function scrubHostBreadcrumb<T extends HostScrubbableBreadcrumb>(
+  crumb: T,
+): T | null {
+  if (crumb.category !== "bridge") return null;
+  if (typeof crumb.message === "string") {
+    crumb.message = scrubHostString(crumb.message);
+  }
+  if (crumb.data) {
+    crumb.data = scrubHostValue(crumb.data) as Record<string, unknown>;
+  }
+  return crumb;
+}
+
+/**
+ * The exact Sentry.init options — exported pure for tests, because "errors
+ * only" is a checkable claim, not a vibe: release-health sessions send an
+ * envelope AT INIT (review probe caught it) and client reports are another
+ * non-crash egress; both are off, so nothing leaves until a crash.
+ */
+export function buildHostInitOptions(args: {
+  dsn: string;
+  version?: string;
+}): Sentry.NodeOptions {
+  return {
+    dsn: args.dsn,
+    // A service install has no NODE_ENV — that's the PRODUCTION case for a
+    // host (review finding: installs were labelled "development"). Explicit
+    // dev/test envs still label themselves; SENTRY_ENVIRONMENT overrides.
+    environment:
+      process.env.SENTRY_ENVIRONMENT ||
+      (process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test"
+        ? process.env.NODE_ENV
+        : "production"),
+    release: args.version,
+    tracesSampleRate: 0,
+    sendDefaultPii: false,
+    sendClientReports: false,
+    // With tracing off the SDK still injects sentry-trace/baggage headers
+    // (public key, release, environment) into ORDINARY outbound HTTP —
+    // metadata third parties the host talks to shouldn't receive.
+    tracePropagationTargets: [],
+    // "strict" preserves today's semantics: an unhandled rejection still
+    // takes the process down (service manager restarts) — Sentry's default
+    // "warn" mode would silently keep a possibly-wedged host alive.
+    // Console breadcrumbs are DROPPED (header comment) — host console
+    // carries unboundable third-party output. ProcessSession is DROPPED —
+    // it is the init-time session envelope that falsified "errors only".
+    // Modules is DROPPED — the full dependency inventory is data the
+    // disclosure doesn't cover and debugging doesn't need. ContextLines is
+    // DROPPED — the disclosure promises "error and stack trace", and
+    // source-line excerpts exceed that.
+    // Http is REMOVED ENTIRELY, not reconfigured. Every retained slice of it
+    // broke the minimal contract in review probes: default incoming-session
+    // tracking sent a `sessions` envelope on a plain GET; outbound
+    // breadcrumbs shipped completed request URLs; and — unfixable by hooks —
+    // inbound `sentry-trace`/`baggage` TRACE CONTINUATION copies
+    // attacker-controlled public_key/release/environment/user_segment/
+    // transaction into the ENVELOPE HEADER, which beforeSend never sees.
+    // With request/transaction context already discarded, http
+    // instrumentation carries no payload value for crash-only reporting.
+    // NodeFetch goes with it for the same minimal contract: it adds fetch
+    // breadcrumbs (outbound request data) and is the undici half of trace
+    // propagation. No http-layer instrumentation remains on either module.
+    integrations: (defaults) => [
+      ...defaults.filter(
+        (i) =>
+          i.name !== "Console" &&
+          i.name !== "ProcessSession" &&
+          i.name !== "Modules" &&
+          i.name !== "ContextLines" &&
+          i.name !== "Http" &&
+          i.name !== "NodeFetch",
+      ),
+      Sentry.onUnhandledRejectionIntegration({ mode: "strict" }),
+    ],
+    beforeSend: (event) => scrubHostEvent(event),
+    beforeBreadcrumb: (crumb) => scrubHostBreadcrumb(crumb),
+  };
+}
+
+export function initHostObs(opts: { version?: string } = {}): void {
+  if (initialized) return;
+  const { dsn, source } = resolveHostDsn(process.env);
+  if (!dsn) return;
+  if (!defaultActivationAllowed(source, hasSeenTelemetryDisclosure())) {
+    console.log(
+      `[host-agent] crash reporting is pending disclosure — it stays OFF until the notice has been shown (\`${STATION.command} install\`/\`pair\`/\`setup\`/\`start\`/\`restart\`)`,
+    );
+    return;
+  }
+
+  Sentry.init(buildHostInitOptions({ dsn, version: opts.version }));
+  initialized = true;
+  if (source === "default") {
+    // The disclosure half of default-on: every start says what leaves the
+    // machine and how to turn it off (same text the install/pair CLIs print).
+    console.log(`[host-agent] ${TELEMETRY_NOTICE}`);
+  } else {
+    console.log("[host-agent] sentry crash reporting enabled (UAI_SENTRY_DSN)");
+  }
+}
+
+export function hostObsEnabled(): boolean {
+  return initialized;
+}
+
+/** Tag every future event with this host's id (safe to call repeatedly). */
+export function setHostObsTag(hostId: string): void {
+  if (!initialized) return;
+  Sentry.setTag("hostId", hostId);
+}
+
+/**
+ * Bridge-lifecycle context for the next crash. No-op when disabled. The
+ * category is NARROWED to the allow-listed literal — the hooks drop
+ * everything else, so a wider signature would only invite silent losses.
+ */
+export function addHostBreadcrumb(
+  category: "bridge",
+  message: string,
+  data?: Record<string, unknown>,
+): void {
+  if (!initialized) return;
+  Sentry.addBreadcrumb({ category, message, data, level: "info" });
+}
+
+/** Explicit capture for caught-but-fatal paths. No-op when disabled. */
+export function captureHostError(
+  err: unknown,
+  extra?: Record<string, unknown>,
+): void {
+  if (!initialized) return;
+  Sentry.captureException(err, extra ? { extra } : undefined);
+}