@app-vitals/agent-lib 0.0.0-stage → 0.1.0

package/request-context.unit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { callerLabel } from "./request-context.ts";
+
+describe("callerLabel — defined caller", () => {
+  test("formats an admin caller (scope '*')", () => {
+    expect(callerLabel({ name: "bodhi", scope: "*" })).toBe("bodhi (*)");
+  });
+
+  test("formats a caller scoped to a clientId", () => {
+    expect(callerLabel({ name: "sully", scope: "client-xyz" })).toBe(
+      "sully (client-xyz)",
+    );
+  });
+
+  test("formats a caller scoped to an agentId", () => {
+    expect(callerLabel({ name: "agent-123", scope: "agent-456" })).toBe(
+      "agent-123 (agent-456)",
+    );
+  });
+
+  test("is stable across repeated calls with the same input", () => {
+    const caller = { name: "bodhi", scope: "*" };
+    expect(callerLabel(caller)).toBe(callerLabel(caller));
+  });
+});
+
+describe("callerLabel — undefined caller", () => {
+  test("returns a distinct, readable label for undefined", () => {
+    const label = callerLabel(undefined);
+    expect(label).toBe("anonymous");
+  });
+
+  test("returns the same label when called with no argument", () => {
+    expect(callerLabel()).toBe("anonymous");
+  });
+
+  test("undefined label never collides with a defined caller's label", () => {
+    const anonymousLabel = callerLabel(undefined);
+    expect(callerLabel({ name: "anonymous", scope: "*" })).not.toBe(
+      anonymousLabel,
+    );
+  });
+});
+
+describe("callerLabel — scope kind", () => {
+  test("appends the scope kind when given", () => {
+    expect(
+      callerLabel({ name: "svc", scope: "platform.read" }, "platform-read"),
+    ).toBe("svc (platform.read) [platform-read]");
+  });
+});

package/secret-env-vars.ts

@@ -0,0 +1,41 @@
+/**
+ * lib/secret-env-vars.ts
+ * Canonical list of well-known secret-shaped env var names used by the
+ * shipwright-agent framework. Shared by Sentry log/event scrubbing
+ * (lib/sentry.ts) and by admin's agent env storage (marks these keys as
+ * `secret` so they're masked in GET /agents/:id/envs responses).
+ */
+
+/** Secret-shaped env var names, redacted/masked wherever their value is currently set. */
+export const SECRET_ENV_VARS = [
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "GH_APP_PRIVATE_KEY",
+  "GH_APP_CLIENT_SECRET",
+  "GH_TOKEN",
+  "SLACK_BOT_TOKEN",
+  "SLACK_APP_TOKEN",
+  "SLACK_SIGNING_SECRET",
+  "SLACK_CLIENT_SECRET",
+  "SLACK_ADMIN_TOKEN",
+  "SHIPWRIGHT_AGENT_API_KEY",
+  "SHIPWRIGHT_TASK_STORE_TOKEN",
+  "SHIPWRIGHT_TASK_STORE_ADMIN_TOKEN",
+  "SHIPWRIGHT_CHAT_SERVICE_TOKEN",
+  "SHIPWRIGHT_CHAT_SERVICE_ADMIN_TOKEN",
+  "SHIPWRIGHT_ADMIN_API_KEYS",
+  "SHIPWRIGHT_SESSION_SECRET",
+  "SHIPWRIGHT_ENCRYPTION_KEY",
+  // VAPID private key for Web Push (RFC 8292). The PUBLIC key is NOT secret —
+  // it's sent to the browser — so only the private key is listed here.
+  "SHIPWRIGHT_ADMIN_VAPID_PRIVATE_KEY",
+  // Shared token the chat service presents to admin's push-notify webhook so
+  // an unauthenticated caller can't trigger notifications.
+  "SHIPWRIGHT_ADMIN_PUSH_WEBHOOK_TOKEN",
+  // Bearer token the chat service presents to admin's push-notify webhook
+  // when firing outbound reply notifications. Same shared-secret value as
+  // SHIPWRIGHT_ADMIN_PUSH_WEBHOOK_TOKEN in deployment, but a distinct env
+  // var name (chat-side vs. admin-side).
+  "SHIPWRIGHT_CHAT_PUSH_WEBHOOK_TOKEN",
+  "GOOGLE_CLIENT_SECRET",
+] as const;

package/secret-env-vars.unit.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { SECRET_ENV_VARS } from "./secret-env-vars.ts";
+
+describe("SECRET_ENV_VARS", () => {
+  test("is a non-empty array", () => {
+    expect(Array.isArray(SECRET_ENV_VARS)).toBe(true);
+    expect(SECRET_ENV_VARS.length).toBeGreaterThan(0);
+  });
+
+  test("contains expected well-known secret env var names", () => {
+    const expectedEntries = [
+      "ANTHROPIC_API_KEY",
+      "CLAUDE_CODE_OAUTH_TOKEN",
+      "GH_APP_PRIVATE_KEY",
+      "GH_APP_CLIENT_SECRET",
+      "GH_TOKEN",
+      "SLACK_BOT_TOKEN",
+      "SLACK_APP_TOKEN",
+      "SLACK_SIGNING_SECRET",
+      "SLACK_CLIENT_SECRET",
+      "SLACK_ADMIN_TOKEN",
+      "SHIPWRIGHT_AGENT_API_KEY",
+      "SHIPWRIGHT_TASK_STORE_TOKEN",
+      "SHIPWRIGHT_TASK_STORE_ADMIN_TOKEN",
+      "SHIPWRIGHT_CHAT_SERVICE_TOKEN",
+      "SHIPWRIGHT_CHAT_SERVICE_ADMIN_TOKEN",
+      "SHIPWRIGHT_ADMIN_API_KEYS",
+      "SHIPWRIGHT_SESSION_SECRET",
+      "SHIPWRIGHT_ENCRYPTION_KEY",
+      "SHIPWRIGHT_ADMIN_VAPID_PRIVATE_KEY",
+      "SHIPWRIGHT_ADMIN_PUSH_WEBHOOK_TOKEN",
+      "SHIPWRIGHT_CHAT_PUSH_WEBHOOK_TOKEN",
+      "GOOGLE_CLIENT_SECRET",
+    ];
+
+    for (const entry of expectedEntries) {
+      expect(SECRET_ENV_VARS as readonly string[]).toContain(entry);
+    }
+  });
+
+  test("has exactly the expected number of entries (catches accidental additions/removals)", () => {
+    expect(SECRET_ENV_VARS.length).toBe(22);
+  });
+
+  test("every entry is a non-empty string", () => {
+    for (const entry of SECRET_ENV_VARS) {
+      expect(typeof entry).toBe("string");
+      expect(entry.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("every entry looks like an env var name (uppercase snake case)", () => {
+    for (const entry of SECRET_ENV_VARS) {
+      expect(entry).toMatch(/^[A-Z][A-Z0-9_]*$/);
+    }
+  });
+
+  test("has no duplicate entries", () => {
+    const uniqueEntries = new Set(SECRET_ENV_VARS);
+    expect(uniqueEntries.size).toBe(SECRET_ENV_VARS.length);
+  });
+});

package/sentry.ts

@@ -0,0 +1,201 @@
+import * as Sentry from "@sentry/bun";
+import { consoleLoggingIntegration } from "@sentry/bun";
+import type { BunOptions, ErrorEvent, EventHint } from "@sentry/bun";
+import { SECRET_ENV_VARS } from "./secret-env-vars.ts";
+
+/**
+ * `@sentry/bun` doesn't re-export the `Log` type directly (it lives in `@sentry/core`, a
+ * transitive dependency), so it's derived here from `beforeSendLog`'s parameter type instead of
+ * adding a direct dependency on `@sentry/core`.
+ */
+type SentryLog = NonNullable<BunOptions["beforeSendLog"]> extends (
+  log: infer L,
+) => unknown
+  ? L
+  : never;
+
+interface InitSentryOptions {
+  service: string;
+  agentId?: string;
+}
+
+/** Narrowed to the one method initSentry calls, so tests can inject a fake without mock.module(). */
+interface SentryClient {
+  init: (options: Record<string, unknown>) => void;
+}
+
+/**
+ * Narrowed to the one method a scope fork needs to expose — setting a tag on
+ * the forked (not shared/global) scope passed into `withScope`'s callback.
+ * The real `Sentry.Scope` from `@sentry/bun` satisfies this shape via its
+ * `setTag` method; it has many more methods, but callers of `withScope` below
+ * only ever need this one.
+ */
+export interface ScopeTagSetter {
+  setTag: (key: string, value: string) => unknown;
+  /** Optional so tag-only fakes keep type-checking; the real `Scope` has it. */
+  setContext?: (
+    name: string,
+    context: Record<string, unknown> | null,
+  ) => unknown;
+}
+
+/**
+ * Narrowed to the methods callers need to report unhandled errors and
+ * expected-but-notable events, so tests can inject a fake without
+ * mock.module(). Mirrors the SentryClient pattern — the real `Sentry` from
+ * `@sentry/bun` satisfies this shape via its `captureException`/
+ * `captureMessage`/`withScope` exports. `captureMessage` and `withScope` are
+ * optional so existing fakes that only implement `captureException` keep
+ * type-checking.
+ *
+ * `withScope` mirrors `@sentry/bun`'s `Sentry.withScope` signature: it forks
+ * the current scope for the duration of the async `callback`, so tags set on
+ * the forked scope (via `ScopeTagSetter.setTag`) are visible to any Sentry
+ * event (Issue or Log) captured while `callback` is in flight, without
+ * mutating any other concurrent or sequential call's scope. Real `Sentry`
+ * satisfies this via its AsyncLocalStorage-based async context strategy —
+ * scope propagation survives the awaited callback, including nested awaits.
+ */
+export interface ErrorCapturingClient {
+  captureException: (err: unknown) => void;
+  captureMessage?: (message: string) => void;
+  withScope?: <T>(
+    callback: (scope: ScopeTagSetter) => Promise<T>,
+  ) => Promise<T>;
+}
+
+/** Max depth walked when scrubbing, so a pathological/deeply-nested object can't hang scrubbing. */
+const MAX_SCRUB_DEPTH = 20;
+
+/** Recomputed per call (not cached at module load) so tests can mutate env freely between assertions. */
+function liveSecretValues(): string[] {
+  return SECRET_ENV_VARS.map((key) => process.env[key]).filter(
+    (value): value is string => !!value,
+  );
+}
+
+function redactSecrets<T>(
+  value: T,
+  secrets: string[],
+  seen: WeakSet<object>,
+  depth: number,
+): T {
+  if (secrets.length === 0) return value;
+
+  if (typeof value === "string") {
+    let result: string = value;
+    for (const secret of secrets) {
+      if (result.includes(secret)) {
+        result = result.split(secret).join("[Filtered]");
+      }
+    }
+    return result as unknown as T;
+  }
+
+  if (value === null || typeof value !== "object" || depth >= MAX_SCRUB_DEPTH) {
+    return value;
+  }
+
+  if (seen.has(value as object)) {
+    return value;
+  }
+  seen.add(value as object);
+
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      redactSecrets(item, secrets, seen, depth + 1),
+    ) as unknown as T;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+    result[key] = redactSecrets(val, secrets, seen, depth + 1);
+  }
+  return result as unknown as T;
+}
+
+function stripSensitiveHeaders(event: ErrorEvent): ErrorEvent {
+  const headers = event.request?.headers;
+  if (!headers) return event;
+
+  const scrubbedHeaders = { ...headers };
+  for (const key of Object.keys(scrubbedHeaders)) {
+    if (
+      key.toLowerCase() === "authorization" ||
+      key.toLowerCase() === "cookie"
+    ) {
+      scrubbedHeaders[key] = "[Filtered]";
+    }
+  }
+
+  return {
+    ...event,
+    request: { ...event.request, headers: scrubbedHeaders },
+  };
+}
+
+export function scrubEvent(
+  event: ErrorEvent,
+  _hint: EventHint,
+): ErrorEvent | null {
+  const withHeadersStripped = stripSensitiveHeaders(event);
+  return redactSecrets(
+    withHeadersStripped,
+    liveSecretValues(),
+    new WeakSet(),
+    0,
+  );
+}
+
+export function scrubLog(log: SentryLog): SentryLog {
+  return redactSecrets(log, liveSecretValues(), new WeakSet(), 0);
+}
+
+/**
+ * Builds the init options `initSentry` passes to `sentryClient.init` — shared
+ * with callers (like `@sentry/hono`'s `sentry()` middleware) that must
+ * perform their own `Sentry.init` call, so every init site gets the same
+ * enableLogs/environment/scrub-hook config instead of each duplicating it.
+ * Returns `undefined` when SENTRY_DSN is unset (nothing to init), or when
+ * NODE_ENV is "test" — Bun auto-sets this for `bun test`, and without this
+ * guard any SENTRY_DSN present in the environment would leak intentional
+ * error-path test assertions to production Sentry as real events.
+ */
+export function buildSentryInitOptions(
+  opts: InitSentryOptions,
+): Record<string, unknown> | undefined {
+  if (process.env.NODE_ENV === "test") return undefined;
+
+  const dsn = process.env.SENTRY_DSN;
+  if (!dsn) return undefined;
+
+  const tags: Record<string, string> = { service: opts.service };
+  if (opts.agentId) {
+    tags.agent_id = opts.agentId;
+  }
+
+  return {
+    dsn,
+    enableLogs: true,
+    integrations: [
+      consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
+    ],
+    environment:
+      process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "production",
+    initialScope: { tags },
+    beforeSend: scrubEvent,
+    beforeSendLog: scrubLog,
+  };
+}
+
+/** No-ops (zero telemetry, no init call) when SENTRY_DSN is unset. */
+export function initSentry(
+  opts: InitSentryOptions,
+  sentryClient: SentryClient = Sentry,
+): void {
+  const options = buildSentryInitOptions(opts);
+  if (!options) return;
+
+  sentryClient.init(options);
+}

package/sentry.unit.test.ts

@@ -0,0 +1,294 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SECRET_ENV_VARS } from "./secret-env-vars.ts";
+import { initSentry, scrubEvent, scrubLog } from "./sentry.ts";
+
+function createFakeSentryClient() {
+  const calls: unknown[] = [];
+  return {
+    init: (options: unknown) => {
+      calls.push(options);
+    },
+    calls,
+  };
+}
+
+// Snapshot the env vars this suite touches so we can restore them exactly,
+// keeping this suite isolated from sibling suites sharing the Bun test process.
+const ENV_KEYS_UNDER_TEST = [
+  ...SECRET_ENV_VARS,
+  "SENTRY_DSN",
+  "SENTRY_ENVIRONMENT",
+  "NODE_ENV",
+];
+const originalEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  for (const key of ENV_KEYS_UNDER_TEST) {
+    originalEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS_UNDER_TEST) {
+    const original = originalEnv[key];
+    if (original === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = original;
+    }
+  }
+});
+
+describe("initSentry — SENTRY_DSN unset", () => {
+  test("never calls sentryClient.init", () => {
+    delete process.env.SENTRY_DSN;
+    const fakeClient = createFakeSentryClient();
+
+    initSentry({ service: "metrics" }, fakeClient);
+
+    expect(fakeClient.calls.length).toBe(0);
+  });
+});
+
+describe("initSentry — NODE_ENV=test", () => {
+  test("never calls sentryClient.init even with SENTRY_DSN set", () => {
+    process.env.NODE_ENV = "test";
+    process.env.SENTRY_DSN = "https://example@o0.ingest.sentry.io/0";
+    const fakeClient = createFakeSentryClient();
+
+    initSentry({ service: "metrics" }, fakeClient);
+
+    expect(fakeClient.calls.length).toBe(0);
+  });
+});
+
+describe("initSentry — SENTRY_DSN set", () => {
+  test("calls sentryClient.init with enableLogs, service tag, and scrub hooks wired", () => {
+    process.env.SENTRY_DSN = "https://example@o0.ingest.sentry.io/0";
+    const fakeClient = createFakeSentryClient();
+
+    initSentry({ service: "metrics" }, fakeClient);
+
+    expect(fakeClient.calls.length).toBe(1);
+    const options = fakeClient.calls[0] as {
+      dsn: string;
+      enableLogs: boolean;
+      initialScope: { tags: { service: string } };
+      beforeSend: unknown;
+      beforeSendLog: unknown;
+      environment: string;
+    };
+
+    expect(options.dsn).toBe("https://example@o0.ingest.sentry.io/0");
+    expect(options.enableLogs).toBe(true);
+    expect(options.initialScope.tags.service).toBe("metrics");
+    expect(options.beforeSend).toBe(scrubEvent);
+    expect(options.beforeSendLog).toBe(scrubLog);
+  });
+
+  test("environment falls back to SENTRY_ENVIRONMENT, then NODE_ENV, then production", () => {
+    process.env.SENTRY_DSN = "https://example@o0.ingest.sentry.io/0";
+
+    process.env.SENTRY_ENVIRONMENT = "staging";
+    process.env.NODE_ENV = "production";
+    let fakeClient = createFakeSentryClient();
+    initSentry({ service: "agent" }, fakeClient);
+    expect((fakeClient.calls[0] as { environment: string }).environment).toBe(
+      "staging",
+    );
+
+    delete process.env.SENTRY_ENVIRONMENT;
+    process.env.NODE_ENV = "development";
+    fakeClient = createFakeSentryClient();
+    initSentry({ service: "agent" }, fakeClient);
+    expect((fakeClient.calls[0] as { environment: string }).environment).toBe(
+      "development",
+    );
+
+    delete process.env.SENTRY_ENVIRONMENT;
+    delete process.env.NODE_ENV;
+    fakeClient = createFakeSentryClient();
+    initSentry({ service: "agent" }, fakeClient);
+    expect((fakeClient.calls[0] as { environment: string }).environment).toBe(
+      "production",
+    );
+  });
+
+  test("integrations include a console logging integration configured for log/warn/error", () => {
+    process.env.SENTRY_DSN = "https://example@o0.ingest.sentry.io/0";
+    const fakeClient = createFakeSentryClient();
+
+    initSentry({ service: "task-store" }, fakeClient);
+
+    const options = fakeClient.calls[0] as { integrations: unknown[] };
+    expect(Array.isArray(options.integrations)).toBe(true);
+    expect(options.integrations.length).toBeGreaterThan(0);
+  });
+
+  test("agent_id tag is included in initialScope.tags when agentId is passed", () => {
+    process.env.SENTRY_DSN = "https://example@o0.ingest.sentry.io/0";
+    const fakeClient = createFakeSentryClient();
+
+    initSentry({ service: "agent", agentId: "test-agent-123" }, fakeClient);
+
+    expect(fakeClient.calls.length).toBe(1);
+    const options = fakeClient.calls[0] as {
+      initialScope: { tags: Record<string, string> };
+    };
+    expect(options.initialScope.tags.agent_id).toBe("test-agent-123");
+  });
+
+  test("agent_id tag is absent when agentId is not passed", () => {
+    process.env.SENTRY_DSN = "https://example@o0.ingest.sentry.io/0";
+    const fakeClient = createFakeSentryClient();
+
+    initSentry({ service: "metrics" }, fakeClient);
+
+    expect(fakeClient.calls.length).toBe(1);
+    const options = fakeClient.calls[0] as {
+      initialScope: { tags: Record<string, unknown> };
+    };
+    expect(options.initialScope.tags).not.toHaveProperty("agent_id");
+  });
+});
+
+describe("scrubEvent — header stripping", () => {
+  test("strips Authorization and Cookie request headers unconditionally, even with no secrets set", () => {
+    const event = {
+      request: {
+        headers: {
+          Authorization: "Bearer abc123",
+          Cookie: "session=xyz",
+          "User-Agent": "test-agent",
+        },
+      },
+    };
+
+    const scrubbed = scrubEvent(event as never, {} as never);
+
+    expect(scrubbed?.request?.headers?.Authorization).toBe("[Filtered]");
+    expect(scrubbed?.request?.headers?.Cookie).toBe("[Filtered]");
+    expect(scrubbed?.request?.headers?.["User-Agent"]).toBe("test-agent");
+  });
+});
+
+describe("scrubEvent — secret redaction", () => {
+  test("redacts a nested error message matching a currently-set secret env var", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-super-secret-value";
+    const event = {
+      exception: {
+        values: [
+          {
+            type: "Error",
+            value: "sk-ant-super-secret-value",
+          },
+        ],
+      },
+    };
+
+    const scrubbed = scrubEvent(event as never, {} as never) as {
+      exception: { values: Array<{ value: string }> };
+    };
+
+    expect(scrubbed.exception.values[0].value).toBe("[Filtered]");
+  });
+
+  test("redacts a secret embedded within a longer string, not just an exact match", () => {
+    process.env.GH_TOKEN = "ghp_secretvalue";
+    const event = {
+      exception: {
+        values: [
+          {
+            type: "Error",
+            value: "Failed to authenticate: Bearer ghp_secretvalue",
+          },
+        ],
+      },
+    };
+
+    const scrubbed = scrubEvent(event as never, {} as never) as {
+      exception: { values: Array<{ value: string }> };
+    };
+
+    expect(scrubbed.exception.values[0].value).toBe(
+      "Failed to authenticate: Bearer [Filtered]",
+    );
+  });
+
+  test("does not redact anything when no secrets are set (no false positives)", () => {
+    const event = {
+      message: "a perfectly normal message",
+      extra: { note: "nothing sensitive here", count: 42 },
+    };
+
+    const scrubbed = scrubEvent(
+      JSON.parse(JSON.stringify(event)) as never,
+      {} as never,
+    );
+
+    expect(scrubbed).toEqual(event as never);
+  });
+
+  test("does not touch non-string values", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-super-secret-value";
+    const event = {
+      extra: { count: 42, enabled: true, nothing: null },
+    };
+
+    const scrubbed = scrubEvent(event as never, {} as never) as unknown as {
+      extra: { count: number; enabled: boolean; nothing: null };
+    };
+
+    expect(scrubbed.extra.count).toBe(42);
+    expect(scrubbed.extra.enabled).toBe(true);
+    expect(scrubbed.extra.nothing).toBeNull();
+  });
+});
+
+describe("scrubLog — secret redaction", () => {
+  test("redacts log attributes matching a currently-set secret env var", () => {
+    process.env.SHIPWRIGHT_SESSION_SECRET = "super-session-secret-value";
+    const log = {
+      level: "error" as const,
+      message: "session created",
+      attributes: {
+        sessionSecret: "super-session-secret-value",
+        userId: "user-123",
+      },
+    };
+
+    const scrubbed = scrubLog(structuredClone(log));
+
+    expect(scrubbed.attributes?.sessionSecret).toBe("[Filtered]");
+    expect(scrubbed.attributes?.userId).toBe("user-123");
+  });
+
+  test("does not redact anything when no secrets are set (no false positives)", () => {
+    const log = {
+      level: "info" as const,
+      message: "normal log line",
+      attributes: { foo: "bar", count: 1 },
+    };
+
+    const scrubbed = scrubLog(structuredClone(log));
+
+    expect(scrubbed).toEqual(log);
+  });
+
+  test("handles circular references without infinite looping", () => {
+    process.env.GH_TOKEN = "ghp_secretvalue";
+    const attributes: Record<string, unknown> = { token: "ghp_secretvalue" };
+    attributes.self = attributes;
+    const log = {
+      level: "warn" as const,
+      message: "circular test",
+      attributes,
+    };
+
+    // Should complete without throwing / hanging.
+    const scrubbed = scrubLog(log);
+
+    expect(scrubbed.attributes?.token).toBe("[Filtered]");
+  });
+});