@hellcoder/companion 0.96.0

package/server/linear-oauth-connections.test.ts

@@ -0,0 +1,365 @@
+/**
+ * Tests for linear-oauth-connections.ts — file-based CRUD store for
+ * Linear OAuth connections.
+ *
+ * Validates:
+ * - CRUD: create, read, update, delete
+ * - List and lookup operations
+ * - findOAuthConnectionByClientId lookup
+ * - sanitizeOAuthConnection masks secrets
+ * - Auto-derived status from accessToken
+ * - _resetForTest clears state
+ * - Persistence to disk (write + reload)
+ * - Invalid/corrupt JSON file handling
+ */
+import { describe, it, expect, beforeEach, afterAll } from "vitest";
+import { mkdirSync, rmSync, existsSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  listOAuthConnections,
+  getOAuthConnection,
+  findOAuthConnectionByClientId,
+  createOAuthConnection,
+  updateOAuthConnection,
+  deleteOAuthConnection,
+  sanitizeOAuthConnection,
+  _resetForTest,
+  type LinearOAuthConnection,
+} from "./linear-oauth-connections.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const TEST_DIR = join(tmpdir(), `companion-oauth-test-${Date.now()}`);
+const TEST_FILE = join(TEST_DIR, "linear-oauth-connections.json");
+
+beforeEach(() => {
+  // Reset state and point at a temp file per test
+  _resetForTest(TEST_FILE);
+  // Ensure clean directory
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterAll(() => {
+  // Clean up temp directory
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("linear-oauth-connections", () => {
+  // ─── List ─────────────────────────────────────────────────────────────────
+
+  it("returns empty array when no connections exist", () => {
+    const conns = listOAuthConnections();
+    expect(conns).toEqual([]);
+  });
+
+  // ─── Create ───────────────────────────────────────────────────────────────
+
+  it("creates a connection with all required fields", () => {
+    const conn = createOAuthConnection({
+      name: "My App",
+      oauthClientId: "client-123",
+      oauthClientSecret: "secret-456",
+      webhookSecret: "webhook-789",
+    });
+
+    expect(conn.id).toBeTruthy();
+    expect(conn.name).toBe("My App");
+    expect(conn.oauthClientId).toBe("client-123");
+    expect(conn.oauthClientSecret).toBe("secret-456");
+    expect(conn.webhookSecret).toBe("webhook-789");
+    expect(conn.accessToken).toBe("");
+    expect(conn.refreshToken).toBe("");
+    expect(conn.status).toBe("disconnected");
+    expect(conn.createdAt).toBeGreaterThan(0);
+    expect(conn.updatedAt).toBeGreaterThan(0);
+  });
+
+  it("trims whitespace from inputs", () => {
+    const conn = createOAuthConnection({
+      name: "  Trimmed App  ",
+      oauthClientId: "  cid  ",
+      oauthClientSecret: "  csec  ",
+      webhookSecret: "  wsec  ",
+    });
+
+    expect(conn.name).toBe("Trimmed App");
+    expect(conn.oauthClientId).toBe("cid");
+    expect(conn.oauthClientSecret).toBe("csec");
+    expect(conn.webhookSecret).toBe("wsec");
+  });
+
+  it("sets status to 'connected' when accessToken is provided", () => {
+    const conn = createOAuthConnection({
+      name: "With Token",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+      accessToken: "tok-123",
+    });
+
+    expect(conn.status).toBe("connected");
+    expect(conn.accessToken).toBe("tok-123");
+  });
+
+  // ─── Get ──────────────────────────────────────────────────────────────────
+
+  it("retrieves a connection by ID", () => {
+    const created = createOAuthConnection({
+      name: "Findable",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    const found = getOAuthConnection(created.id);
+    expect(found).not.toBeNull();
+    expect(found!.name).toBe("Findable");
+  });
+
+  it("returns null for non-existent ID", () => {
+    expect(getOAuthConnection("non-existent-id")).toBeNull();
+  });
+
+  // ─── Find by client ID ────────────────────────────────────────────────────
+
+  it("finds a connection by oauthClientId", () => {
+    createOAuthConnection({
+      name: "Target",
+      oauthClientId: "unique-client-id",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    const found = findOAuthConnectionByClientId("unique-client-id");
+    expect(found).not.toBeNull();
+    expect(found!.name).toBe("Target");
+  });
+
+  it("returns null when no matching oauthClientId", () => {
+    expect(findOAuthConnectionByClientId("nope")).toBeNull();
+  });
+
+  // ─── Update ───────────────────────────────────────────────────────────────
+
+  it("updates connection fields", () => {
+    const conn = createOAuthConnection({
+      name: "Old Name",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    const updated = updateOAuthConnection(conn.id, { name: "New Name" });
+    expect(updated).not.toBeNull();
+    expect(updated!.name).toBe("New Name");
+    expect(updated!.oauthClientId).toBe("cid"); // unchanged
+  });
+
+  it("auto-derives connected status when accessToken is set", () => {
+    const conn = createOAuthConnection({
+      name: "App",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+    expect(conn.status).toBe("disconnected");
+
+    const updated = updateOAuthConnection(conn.id, { accessToken: "tok" });
+    expect(updated!.status).toBe("connected");
+  });
+
+  it("auto-derives disconnected status when accessToken is cleared", () => {
+    const conn = createOAuthConnection({
+      name: "App",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+      accessToken: "tok",
+    });
+    expect(conn.status).toBe("connected");
+
+    const updated = updateOAuthConnection(conn.id, { accessToken: "" });
+    expect(updated!.status).toBe("disconnected");
+  });
+
+  it("allows explicit status override", () => {
+    const conn = createOAuthConnection({
+      name: "App",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    const updated = updateOAuthConnection(conn.id, { status: "connected" });
+    expect(updated!.status).toBe("connected");
+  });
+
+  it("returns null when updating non-existent ID", () => {
+    expect(updateOAuthConnection("nope", { name: "x" })).toBeNull();
+  });
+
+  // ─── Delete ───────────────────────────────────────────────────────────────
+
+  it("deletes a connection and returns true", () => {
+    const conn = createOAuthConnection({
+      name: "Deletable",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    expect(deleteOAuthConnection(conn.id)).toBe(true);
+    expect(getOAuthConnection(conn.id)).toBeNull();
+    expect(listOAuthConnections()).toHaveLength(0);
+  });
+
+  it("returns false when deleting non-existent ID", () => {
+    expect(deleteOAuthConnection("nope")).toBe(false);
+  });
+
+  // ─── List ─────────────────────────────────────────────────────────────────
+
+  it("lists all connections", () => {
+    createOAuthConnection({ name: "A", oauthClientId: "a", oauthClientSecret: "s", webhookSecret: "w" });
+    createOAuthConnection({ name: "B", oauthClientId: "b", oauthClientSecret: "s", webhookSecret: "w" });
+
+    const all = listOAuthConnections();
+    expect(all).toHaveLength(2);
+    expect(all.map((c) => c.name)).toEqual(["A", "B"]);
+  });
+
+  it("returns a copy (mutations don't affect store)", () => {
+    createOAuthConnection({ name: "Safe", oauthClientId: "cid", oauthClientSecret: "s", webhookSecret: "w" });
+    const list = listOAuthConnections();
+    list.pop();
+    expect(listOAuthConnections()).toHaveLength(1);
+  });
+
+  // ─── Sanitize ─────────────────────────────────────────────────────────────
+
+  it("masks secrets in sanitized output", () => {
+    const conn = createOAuthConnection({
+      name: "Sensitive",
+      oauthClientId: "visible-client-id",
+      oauthClientSecret: "super-secret",
+      webhookSecret: "wh-secret",
+      accessToken: "at-secret",
+    });
+
+    const sanitized = sanitizeOAuthConnection(conn);
+
+    // Should include these public fields
+    expect(sanitized.id).toBe(conn.id);
+    expect(sanitized.name).toBe("Sensitive");
+    expect(sanitized.oauthClientId).toBe("visible-client-id");
+    expect(sanitized.status).toBe("connected");
+    expect(sanitized.createdAt).toBe(conn.createdAt);
+    expect(sanitized.updatedAt).toBe(conn.updatedAt);
+
+    // Should have boolean flags instead of actual secrets
+    expect(sanitized.hasAccessToken).toBe(true);
+    expect(sanitized.hasClientSecret).toBe(true);
+    expect(sanitized.hasWebhookSecret).toBe(true);
+
+    // Should NOT contain the actual secrets
+    const raw = sanitized as unknown as Record<string, unknown>;
+    expect(raw["oauthClientSecret"]).toBeUndefined();
+    expect(raw["webhookSecret"]).toBeUndefined();
+    expect(raw["accessToken"]).toBeUndefined();
+    expect(raw["refreshToken"]).toBeUndefined();
+  });
+
+  it("reports false flags when secrets are empty", () => {
+    const conn = createOAuthConnection({
+      name: "No Secrets",
+      oauthClientId: "cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    const sanitized = sanitizeOAuthConnection(conn);
+    expect(sanitized.hasAccessToken).toBe(false); // no accessToken provided
+  });
+
+  // ─── Persistence ──────────────────────────────────────────────────────────
+
+  it("persists to disk and reloads correctly", () => {
+    // Create a connection
+    const conn = createOAuthConnection({
+      name: "Persistent",
+      oauthClientId: "persist-cid",
+      oauthClientSecret: "persist-csec",
+      webhookSecret: "persist-wsec",
+    });
+
+    // Verify file exists
+    expect(existsSync(TEST_FILE)).toBe(true);
+
+    // Reset state (simulates server restart) and reload
+    _resetForTest(TEST_FILE);
+    const reloaded = listOAuthConnections();
+    expect(reloaded).toHaveLength(1);
+    expect(reloaded[0].id).toBe(conn.id);
+    expect(reloaded[0].name).toBe("Persistent");
+  });
+
+  it("handles corrupt JSON file gracefully", () => {
+    // Write invalid JSON to the file
+    writeFileSync(TEST_FILE, "not valid json{{{", "utf-8");
+
+    _resetForTest(TEST_FILE);
+    const conns = listOAuthConnections();
+    expect(conns).toEqual([]);
+  });
+
+  it("handles non-array JSON file gracefully", () => {
+    // Write valid JSON but not an array
+    writeFileSync(TEST_FILE, JSON.stringify({ foo: "bar" }), "utf-8");
+
+    _resetForTest(TEST_FILE);
+    const conns = listOAuthConnections();
+    expect(conns).toEqual([]);
+  });
+
+  it("filters out malformed entries from JSON file", () => {
+    // Write array with mix of valid and invalid entries
+    const data = [
+      { id: "valid", oauthClientId: "cid", name: "Valid", oauthClientSecret: "", webhookSecret: "", accessToken: "", refreshToken: "", status: "disconnected", createdAt: 1, updatedAt: 1 },
+      { noId: true }, // missing id
+      null,           // null entry
+      "string entry", // not an object
+    ];
+    writeFileSync(TEST_FILE, JSON.stringify(data), "utf-8");
+
+    _resetForTest(TEST_FILE);
+    const conns = listOAuthConnections();
+    expect(conns).toHaveLength(1);
+    expect(conns[0].name).toBe("Valid");
+  });
+
+  // ─── _resetForTest ────────────────────────────────────────────────────────
+
+  it("clears state when _resetForTest is called", () => {
+    createOAuthConnection({ name: "Will Reset", oauthClientId: "cid", oauthClientSecret: "s", webhookSecret: "w" });
+    expect(listOAuthConnections()).toHaveLength(1);
+
+    _resetForTest(TEST_FILE);
+    // Next list call will attempt to read from TEST_FILE which no longer has this connection
+    // But since we created a connection above, the file DOES have it.
+    // So reset and use a non-existent file to prove state is cleared
+    const emptyFile = join(TEST_DIR, "empty.json");
+    _resetForTest(emptyFile);
+    expect(listOAuthConnections()).toHaveLength(0);
+  });
+});

package/server/linear-oauth-connections.ts

@@ -0,0 +1,294 @@
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { COMPANION_HOME } from "./paths.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface LinearOAuthConnection {
+  id: string;
+  name: string;
+  oauthClientId: string;
+  oauthClientSecret: string;
+  webhookSecret: string;
+  accessToken: string;
+  refreshToken: string;
+  status: "connected" | "disconnected";
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Sanitized version for API responses (secrets masked). */
+export interface LinearOAuthConnectionSummary {
+  id: string;
+  name: string;
+  oauthClientId: string;
+  status: "connected" | "disconnected";
+  hasAccessToken: boolean;
+  hasClientSecret: boolean;
+  hasWebhookSecret: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+const DEFAULT_PATH = join(COMPANION_HOME, "linear-oauth-connections.json");
+
+// ─── Store ───────────────────────────────────────────────────────────────────
+
+let connections: LinearOAuthConnection[] = [];
+let loaded = false;
+let filePath = DEFAULT_PATH;
+
+function ensureLoaded(): void {
+  if (loaded) return;
+  try {
+    if (existsSync(filePath)) {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (Array.isArray(raw)) {
+        connections = raw.filter(
+          (c: unknown): c is LinearOAuthConnection =>
+            typeof c === "object" &&
+            c !== null &&
+            typeof (c as LinearOAuthConnection).id === "string" &&
+            typeof (c as LinearOAuthConnection).oauthClientId === "string",
+        );
+      } else {
+        connections = [];
+      }
+    }
+  } catch {
+    connections = [];
+  }
+  loaded = true;
+
+  // Auto-migrate from agents with inline credentials + global settings
+  migrateFromAgents();
+}
+
+// ─── Migration ───────────────────────────────────────────────────────────────
+
+interface MigrationSettings {
+  linearOAuthClientId: string;
+  linearOAuthClientSecret: string;
+  linearOAuthWebhookSecret: string;
+  linearOAuthAccessToken: string;
+  linearOAuthRefreshToken: string;
+  [key: string]: unknown;
+}
+
+interface MigrationDeps {
+  listAgents: () => Array<{ id: string; name: string; triggers?: { linear?: Record<string, unknown> } }>;
+  updateAgent: (id: string, patch: Record<string, unknown>) => void;
+  getSettings: () => MigrationSettings;
+}
+
+/**
+ * One-time migration: if no OAuth connections exist, extract inline credentials
+ * from agents and global settings into standalone OAuth connections.
+ * Deduplicates by oauthClientId so multiple agents sharing the same app
+ * get a single connection.
+ *
+ * Accepts optional deps parameter for testability.
+ */
+export function migrateFromAgents(deps?: MigrationDeps): void {
+  if (connections.length > 0) return;
+
+  let resolvedDeps: MigrationDeps;
+  if (deps) {
+    resolvedDeps = deps;
+  } else {
+    // Lazy import to avoid circular dependency at module load time
+    try {
+      const agentStoreModule = require("./agent-store.js") as typeof import("./agent-store.js");
+      const settingsModule = require("./settings-manager.js") as typeof import("./settings-manager.js");
+      resolvedDeps = {
+        listAgents: agentStoreModule.listAgents as MigrationDeps["listAgents"],
+        updateAgent: agentStoreModule.updateAgent as MigrationDeps["updateAgent"],
+        getSettings: settingsModule.getSettings as unknown as MigrationDeps["getSettings"],
+      };
+    } catch {
+      return; // Can't migrate without dependencies
+    }
+  }
+
+  const agents = resolvedDeps.listAgents();
+  const seenClientIds = new Set<string>();
+
+  for (const agent of agents) {
+    const linear = agent.triggers?.linear;
+    const oauthClientId = linear?.oauthClientId as string | undefined;
+    if (!oauthClientId || seenClientIds.has(oauthClientId)) continue;
+    seenClientIds.add(oauthClientId);
+
+    const now = Date.now();
+    const conn: LinearOAuthConnection = {
+      id: randomUUID(),
+      name: `${agent.name} OAuth App`,
+      oauthClientId,
+      oauthClientSecret: (linear?.oauthClientSecret as string) || "",
+      webhookSecret: (linear?.webhookSecret as string) || "",
+      accessToken: (linear?.accessToken as string) || "",
+      refreshToken: (linear?.refreshToken as string) || "",
+      status: linear?.accessToken ? "connected" : "disconnected",
+      createdAt: now,
+      updatedAt: now,
+    };
+    connections.push(conn);
+
+    // Update all agents with this clientId to reference the new connection
+    for (const a of agents) {
+      if ((a.triggers?.linear?.oauthClientId as string) === oauthClientId) {
+        resolvedDeps.updateAgent(a.id, {
+          triggers: {
+            ...a.triggers,
+            linear: {
+              ...a.triggers!.linear,
+              oauthConnectionId: conn.id,
+            },
+          },
+        });
+      }
+    }
+  }
+
+  // Also migrate from global settings if present
+  const settings = resolvedDeps.getSettings();
+  if (settings.linearOAuthClientId && !seenClientIds.has(settings.linearOAuthClientId)) {
+    const now = Date.now();
+    connections.push({
+      id: randomUUID(),
+      name: "Default OAuth App",
+      oauthClientId: settings.linearOAuthClientId,
+      oauthClientSecret: settings.linearOAuthClientSecret,
+      webhookSecret: settings.linearOAuthWebhookSecret,
+      accessToken: settings.linearOAuthAccessToken,
+      refreshToken: settings.linearOAuthRefreshToken,
+      status: settings.linearOAuthAccessToken ? "connected" : "disconnected",
+      createdAt: now,
+      updatedAt: now,
+    });
+  }
+
+  if (connections.length > 0) {
+    persist();
+    console.log(`[linear-oauth-connections] Migrated ${connections.length} OAuth connection(s) from agents/settings`);
+  }
+}
+
+function persist(): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(connections, null, 2), "utf-8");
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function listOAuthConnections(): LinearOAuthConnection[] {
+  ensureLoaded();
+  return [...connections];
+}
+
+export function getOAuthConnection(id: string): LinearOAuthConnection | null {
+  ensureLoaded();
+  return connections.find((c) => c.id === id) ?? null;
+}
+
+/** Look up an OAuth connection by its Linear OAuth app client ID. */
+export function findOAuthConnectionByClientId(
+  oauthClientId: string,
+): LinearOAuthConnection | null {
+  ensureLoaded();
+  return connections.find((c) => c.oauthClientId === oauthClientId) ?? null;
+}
+
+export function createOAuthConnection(data: {
+  name: string;
+  oauthClientId: string;
+  oauthClientSecret: string;
+  webhookSecret: string;
+  accessToken?: string;
+  refreshToken?: string;
+}): LinearOAuthConnection {
+  ensureLoaded();
+  const now = Date.now();
+  const conn: LinearOAuthConnection = {
+    id: randomUUID(),
+    name: data.name.trim(),
+    oauthClientId: data.oauthClientId.trim(),
+    oauthClientSecret: data.oauthClientSecret.trim(),
+    webhookSecret: data.webhookSecret.trim(),
+    accessToken: data.accessToken?.trim() || "",
+    refreshToken: data.refreshToken?.trim() || "",
+    status: data.accessToken?.trim() ? "connected" : "disconnected",
+    createdAt: now,
+    updatedAt: now,
+  };
+  connections.push(conn);
+  persist();
+  return conn;
+}
+
+export function updateOAuthConnection(
+  id: string,
+  patch: Partial<Omit<LinearOAuthConnection, "id" | "createdAt">>,
+): LinearOAuthConnection | null {
+  ensureLoaded();
+  const conn = connections.find((c) => c.id === id);
+  if (!conn) return null;
+
+  if (patch.name !== undefined) conn.name = patch.name.trim();
+  if (patch.oauthClientId !== undefined) conn.oauthClientId = patch.oauthClientId.trim();
+  if (patch.oauthClientSecret !== undefined) conn.oauthClientSecret = patch.oauthClientSecret.trim();
+  if (patch.webhookSecret !== undefined) conn.webhookSecret = patch.webhookSecret.trim();
+  if (patch.accessToken !== undefined) conn.accessToken = patch.accessToken.trim();
+  if (patch.refreshToken !== undefined) conn.refreshToken = patch.refreshToken.trim();
+  if (patch.status !== undefined) {
+    conn.status = patch.status;
+  } else if (patch.accessToken !== undefined) {
+    // Auto-derive status from accessToken presence
+    conn.status = patch.accessToken.trim() ? "connected" : "disconnected";
+  }
+  conn.updatedAt = Date.now();
+
+  persist();
+  return conn;
+}
+
+export function deleteOAuthConnection(id: string): boolean {
+  ensureLoaded();
+  const idx = connections.findIndex((c) => c.id === id);
+  if (idx === -1) return false;
+  connections.splice(idx, 1);
+  persist();
+  return true;
+}
+
+/** Sanitize an OAuth connection for API responses (mask secrets). */
+export function sanitizeOAuthConnection(
+  conn: LinearOAuthConnection,
+): LinearOAuthConnectionSummary {
+  return {
+    id: conn.id,
+    name: conn.name,
+    oauthClientId: conn.oauthClientId,
+    status: conn.status,
+    hasAccessToken: !!conn.accessToken,
+    hasClientSecret: !!conn.oauthClientSecret,
+    hasWebhookSecret: !!conn.webhookSecret,
+    createdAt: conn.createdAt,
+    updatedAt: conn.updatedAt,
+  };
+}
+
+/** Reset internal state and optionally set a custom file path (for testing). */
+export function _resetForTest(customPath?: string): void {
+  connections = [];
+  loaded = false;
+  filePath = customPath || DEFAULT_PATH;
+}