@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/extension/src/ui-proxy.ts

@@ -0,0 +1,269 @@
+/**
+ * UI Proxy for the dashboard bridge extension.
+ *
+ * Wraps ctx.ui dialog methods (confirm, select, input, editor) to forward
+ * them to the dashboard server. For TUI sessions, races the original method
+ * against the dashboard response. For headless sessions, only the dashboard
+ * can respond.
+ *
+ * Fire-and-forget methods (notify) are forwarded alongside the original call.
+ */
+
+import type { ExtensionUiResponseMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+
+export interface UiProxyOptions {
+  /** The original ctx.ui object to wrap */
+  ui: {
+    confirm(title: string, message: string, opts?: any): Promise<boolean>;
+    select(title: string, options: string[], opts?: any): Promise<string | undefined>;
+    input(title: string, placeholder?: string, opts?: any): Promise<string | undefined>;
+    editor?(title: string, prefill?: string, opts?: any): Promise<string | undefined>;
+    notify(message: string, type?: string): void;
+  };
+  /** Whether TUI is available (race mode vs dashboard-only) */
+  hasUI: boolean;
+  /** Get current session ID */
+  getSessionId: () => string;
+  /** Send a message to the dashboard server */
+  send: (msg: any) => void;
+}
+
+interface PendingRequest {
+  method: string;
+  params: Record<string, unknown>;
+  resolve: (value: any) => void;
+}
+
+export function createUiProxy(options: UiProxyOptions) {
+  const { ui, hasUI, getSessionId, send } = options;
+  const pending = new Map<string, PendingRequest>();
+
+  // Capture original method references BEFORE ctx.ui is patched in-place.
+  // Without this, the proxy's call to ui.notify() would recurse into itself
+  // because bridge.ts overwrites ctx.ui.notify with the proxy's own method.
+  const originalConfirm = ui.confirm.bind(ui);
+  const originalSelect = ui.select.bind(ui);
+  const originalInput = ui.input.bind(ui);
+  const originalEditor = ui.editor?.bind(ui);
+  const originalNotify = ui.notify.bind(ui);
+
+  function generateRequestId(): string {
+    return crypto.randomUUID();
+  }
+
+  function sendRequest(method: string, params: Record<string, unknown>): string {
+    const requestId = generateRequestId();
+    send({
+      type: "extension_ui_request",
+      sessionId: getSessionId(),
+      requestId,
+      method,
+      params,
+    });
+    return requestId;
+  }
+
+  function createDashboardPromise<T>(requestId: string, method: string, params: Record<string, unknown>): Promise<T> {
+    return new Promise<T>((resolve) => {
+      pending.set(requestId, { method, params, resolve });
+    });
+  }
+
+  /** Re-send all pending UI requests (e.g. after server reconnect) */
+  function resendPending(): void {
+    for (const [requestId, entry] of pending) {
+      send({
+        type: "extension_ui_request",
+        sessionId: getSessionId(),
+        requestId,
+        method: entry.method,
+        params: entry.params,
+      });
+    }
+  }
+
+  /** Extract the result for a specific dialog method from the response */
+  function extractResult(method: string, response: ExtensionUiResponseMessage): any {
+    if (response.cancelled) {
+      switch (method) {
+        case "confirm":
+          return false;
+        case "multiselect":
+          return [];
+        default:
+          return undefined;
+      }
+    }
+
+    const result = response.result as Record<string, unknown> | undefined;
+    switch (method) {
+      case "confirm":
+        return result?.confirmed ?? false;
+      case "select":
+      case "input":
+      case "editor":
+        return result?.value;
+      case "multiselect":
+        return (result?.values as string[]) ?? [];
+      default:
+        return result;
+    }
+  }
+
+  // Recursion guard: if ui.confirm/select/etc is actually our own proxy
+  // (e.g. ctx.ui was already patched from a previous /reload), skip the
+  // TUI race to avoid infinite recursion.
+  let inProxy = false;
+
+  /** Send a dismiss message to the server so dashboard can close the stale dialog */
+  function sendDismiss(requestId: string): void {
+    send({
+      type: "extension_ui_dismiss",
+      sessionId: getSessionId(),
+      requestId,
+    });
+  }
+
+  /**
+   * Race TUI promise against dashboard promise with proper cancellation.
+   * When TUI wins: clean up pending Map entry + send dismiss to server.
+   * When dashboard wins: abort TUI dialog via AbortController.
+   */
+  function raceWithCancellation<T>(requestId: string, tuiPromise: Promise<T>, dashPromise: Promise<T>, ac: AbortController): Promise<T> {
+    // Wire up cross-cancellation before racing
+    tuiPromise.then(() => {
+      // TUI won — clean up dashboard side
+      pending.delete(requestId);
+      sendDismiss(requestId);
+    }).catch(() => {});
+    dashPromise.then(() => {
+      // Dashboard won — abort TUI dialog
+      ac.abort();
+    }).catch(() => {});
+    return Promise.race([tuiPromise, dashPromise]);
+  }
+
+  const wrappedUi = {
+    confirm: (title: string, message: string, opts?: any): Promise<boolean> => {
+      const params = { title, message };
+      const requestId = sendRequest("confirm", params);
+      const dashPromise = createDashboardPromise<boolean>(requestId, "confirm", params);
+
+      if (hasUI && !inProxy) {
+        const ac = new AbortController();
+        inProxy = true;
+        const originalPromise = originalConfirm(title, message, { ...opts, signal: ac.signal }).finally(() => { inProxy = false; });
+        return raceWithCancellation(requestId, originalPromise, dashPromise, ac);
+      }
+      return dashPromise;
+    },
+
+    select: (title: string, selectOptions: string[], opts?: any): Promise<string | undefined> => {
+      const message = opts?.message as string | undefined;
+      const params = { title, options: selectOptions, ...(message ? { message } : {}) };
+      const requestId = sendRequest("select", params);
+      const dashPromise = createDashboardPromise<string | undefined>(requestId, "select", params);
+
+      if (hasUI && !inProxy) {
+        const ac = new AbortController();
+        inProxy = true;
+        const tuiTitle = message ? `${title}\n\n${message}` : title;
+        const originalPromise = originalSelect(tuiTitle, selectOptions, { ...opts, signal: ac.signal }).finally(() => { inProxy = false; });
+        return raceWithCancellation(requestId, originalPromise, dashPromise, ac);
+      }
+      return dashPromise;
+    },
+
+    input: (title: string, placeholder?: string, opts?: any): Promise<string | undefined> => {
+      const message = opts?.message as string | undefined;
+      const params = { title, placeholder, ...(message ? { message } : {}) };
+      const requestId = sendRequest("input", params);
+      const dashPromise = createDashboardPromise<string | undefined>(requestId, "input", params);
+
+      if (hasUI && !inProxy) {
+        const ac = new AbortController();
+        inProxy = true;
+        const tuiTitle = message ? `${title}\n\n${message}` : title;
+        const originalPromise = originalInput(tuiTitle, placeholder, { ...opts, signal: ac.signal }).finally(() => { inProxy = false; });
+        return raceWithCancellation(requestId, originalPromise, dashPromise, ac);
+      }
+      return dashPromise;
+    },
+
+    editor: (title: string, prefill?: string, opts?: any): Promise<string | undefined> => {
+      const params = { title, prefill };
+      const requestId = sendRequest("editor", params);
+      const dashPromise = createDashboardPromise<string | undefined>(requestId, "editor", params);
+
+      if (hasUI && !inProxy && originalEditor) {
+        const ac = new AbortController();
+        inProxy = true;
+        const originalPromise = originalEditor(title, prefill, { ...opts, signal: ac.signal }).finally(() => { inProxy = false; });
+        return raceWithCancellation(requestId, originalPromise, dashPromise, ac);
+      }
+      return dashPromise;
+    },
+
+    multiselect: (title: string, selectOptions: string[], opts?: any): Promise<string[]> => {
+      const message = opts?.message as string | undefined;
+      const params = { title, options: selectOptions, ...(message ? { message } : {}) };
+      const requestId = sendRequest("multiselect", params);
+      const dashPromise = createDashboardPromise<string[]>(requestId, "multiselect", params);
+
+      if (hasUI && !inProxy) {
+        const ac = new AbortController();
+        inProxy = true;
+        const numbered = selectOptions.map((o, i) => `${i + 1}. ${o}`).join("\n");
+        const tuiBase = message ? `${title}\n\n${message}` : title;
+        const tuiPromise = originalInput(`${tuiBase}\n${numbered}`, "e.g. 1,3", { signal: ac.signal }).then((raw) => {
+          if (!raw) return [] as string[];
+          return raw
+            .split(",")
+            .map((s) => parseInt(s.trim(), 10))
+            .filter((n) => !isNaN(n) && n >= 1 && n <= selectOptions.length)
+            .map((n) => selectOptions[n - 1]);
+        }).finally(() => { inProxy = false; });
+        return raceWithCancellation(requestId, tuiPromise, dashPromise, ac);
+      }
+      return dashPromise;
+    },
+
+    notify: (message: string, type?: string): void => {
+      originalNotify(message, type);
+      sendRequest("notify", { message, level: type });
+    },
+  };
+
+  function handleResponse(response: ExtensionUiResponseMessage): void {
+    const entry = pending.get(response.requestId);
+    if (!entry) return;
+
+    pending.delete(response.requestId);
+    entry.resolve(extractResult(entry.method, response));
+  }
+
+  /**
+   * Cancel all pending UI requests. Resolves each pending promise with a
+   * "cancelled" result so the TUI dialogs are dismissed.
+   *
+   * Used when an external channel (e.g. architect_prompt_response) answers a
+   * question that was also forwarded through the ui-proxy. Without this, the
+   * TUI dialog would stay open forever because the proxy’s dashPromise never
+   * resolves.
+   */
+  function cancelAllPending(): void {
+    for (const [requestId, entry] of pending) {
+      const cancelled: ExtensionUiResponseMessage = {
+        type: "extension_ui_response",
+        sessionId: getSessionId(),
+        requestId,
+        cancelled: true,
+      };
+      entry.resolve(extractResult(entry.method, cancelled));
+      sendDismiss(requestId);
+    }
+    pending.clear();
+  }
+
+  return { wrappedUi, handleResponse, resendPending, cancelAllPending };
+}

package/packages/extension/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "references": [
+    { "path": "../shared" }
+  ],
+  "include": ["src"]
+}

package/packages/server/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@blackbelt-technology/pi-dashboard-server",
+  "version": "0.2.0",
+  "description": "Dashboard server for monitoring and interacting with pi agent sessions",
+  "type": "module",
+  "main": "src/cli.ts",
+  "bin": {
+    "pi-dashboard": "src/cli.ts"
+  },
+  "files": [
+    "src/",
+    "scripts/"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/fix-pty-permissions.cjs"
+  },
+  "dependencies": {
+    "@blackbelt-technology/pi-dashboard-shared": "*",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.0.0",
+    "@fastify/http-proxy": "^11.4.3",
+    "@fastify/reply-from": "^12.6.1",
+    "@fastify/static": "^8.0.0",
+    "@fastify/websocket": "^11.0.0",
+    "bonjour-service": "^1.3.0",
+    "diff": "^8.0.3",
+    "fastify": "^5.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "node-pty": "^1.1.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.0",
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/ws": "^8.18.1"
+  }
+}

package/packages/server/src/__tests__/auth-plugin.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import { validateWsUpgrade, escapeHtml, isBypassed } from "../auth-plugin.js";
+import { isBypassedHost } from "../localhost-guard.js";
+import { signToken, COOKIE_NAME } from "../auth.js";
+
+const SECRET = "test-secret-for-ws-auth-testing";
+
+describe("validateWsUpgrade", () => {
+  it("should allow localhost without cookie", () => {
+    expect(validateWsUpgrade(undefined, "127.0.0.1", SECRET)).toBe(true);
+    expect(validateWsUpgrade(undefined, "::1", SECRET)).toBe(true);
+    expect(validateWsUpgrade(undefined, "::ffff:127.0.0.1", SECRET)).toBe(true);
+  });
+
+  it("should reject external request without cookie", () => {
+    expect(validateWsUpgrade(undefined, "1.2.3.4", SECRET)).toBe(false);
+  });
+
+  it("should reject external request with invalid cookie", () => {
+    expect(validateWsUpgrade(`${COOKIE_NAME}=invalidtoken`, "1.2.3.4", SECRET)).toBe(false);
+  });
+
+  it("should allow external request with valid cookie", () => {
+    const token = signToken({ sub: "user@example.com", name: "User", username: "user", provider: "github" }, SECRET);
+    expect(validateWsUpgrade(`${COOKIE_NAME}=${token}`, "1.2.3.4", SECRET)).toBe(true);
+  });
+
+  it("should reject external request with wrong secret", () => {
+    const token = signToken({ sub: "user@example.com", name: "User", username: "user", provider: "github" }, "other-secret");
+    expect(validateWsUpgrade(`${COOKIE_NAME}=${token}`, "1.2.3.4", SECRET)).toBe(false);
+  });
+});
+
+describe("isBypassed", () => {
+  it("should return false for empty bypassUrls list", () => {
+    expect(isBypassed("/api/sessions", [])).toBe(false);
+  });
+
+  it("should return true when URL starts with a bypass prefix", () => {
+    expect(isBypassed("/webhooks/github", ["/webhooks/"])).toBe(true);
+  });
+
+  it("should return false when URL does not start with any bypass prefix", () => {
+    expect(isBypassed("/api/sessions", ["/webhooks/"])).toBe(false);
+  });
+
+  it("should match multiple prefixes", () => {
+    expect(isBypassed("/metrics", ["/webhooks/", "/metrics"])).toBe(true);
+    expect(isBypassed("/healthz/ready", ["/healthz", "/metrics"])).toBe(true);
+  });
+
+  it("should match because startsWith is a prefix check (not word-boundary)", () => {
+    // /api/public IS a prefix of /api/publications — this is expected, documented behaviour
+    expect(isBypassed("/api/publications", ["/api/public"])).toBe(true);
+  });
+
+  it("should not match when prefix is only a substring in the middle", () => {
+    expect(isBypassed("/v1/webhooks/data", ["/webhooks/"])).toBe(false);
+  });
+
+  it("should return false when no prefix matches", () => {
+    expect(isBypassed("/secure/data", ["/webhooks/", "/metrics"])).toBe(false);
+  });
+});
+
+describe("isBypassedHost", () => {
+  it("should return false for empty bypass list", () => {
+    expect(isBypassedHost("10.0.0.5", [])).toBe(false);
+  });
+
+  it("should match exact IP", () => {
+    expect(isBypassedHost("10.0.0.5", ["10.0.0.5"])).toBe(true);
+  });
+
+  it("should match exact hostname", () => {
+    expect(isBypassedHost("build-server.local", ["build-server.local"])).toBe(true);
+  });
+
+  it("should not match different IP", () => {
+    expect(isBypassedHost("10.0.0.6", ["10.0.0.5"])).toBe(false);
+  });
+
+  it("should match CIDR notation", () => {
+    expect(isBypassedHost("192.168.1.50", ["192.168.1.0/24"])).toBe(true);
+    expect(isBypassedHost("192.168.2.50", ["192.168.1.0/24"])).toBe(false);
+  });
+
+  it("should match wildcard subnet", () => {
+    expect(isBypassedHost("10.0.0.99", ["10.0.0.*"])).toBe(true);
+    expect(isBypassedHost("10.0.1.99", ["10.0.0.*"])).toBe(false);
+  });
+
+  it("should match multiple entries", () => {
+    expect(isBypassedHost("10.0.0.5", ["192.168.1.1", "10.0.0.5"])).toBe(true);
+  });
+});
+
+describe("escapeHtml", () => {
+  it("should escape all HTML special characters", () => {
+    expect(escapeHtml('&<>"\'')).toBe("&amp;&lt;&gt;&quot;&#39;");
+  });
+
+  it("should escape script tags to prevent XSS", () => {
+    expect(escapeHtml('<script>alert(1)</script>')).toBe("&lt;script&gt;alert(1)&lt;/script&gt;");
+  });
+
+  it("should escape crafted email addresses", () => {
+    expect(escapeHtml('<img onerror="alert(1)" src=x>@evil.com')).toBe(
+      '&lt;img onerror=&quot;alert(1)&quot; src=x&gt;@evil.com',
+    );
+  });
+
+  it("should pass through safe strings unchanged", () => {
+    expect(escapeHtml("user@example.com")).toBe("user@example.com");
+    expect(escapeHtml("hello world")).toBe("hello world");
+  });
+});

package/packages/server/src/__tests__/auth.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  signToken,
+  verifyToken,
+  parseAuthCookie,
+  isUserAllowed,
+  ensureAuthSecret,
+  buildAuthorizeUrl,
+  buildProviderRegistry,
+  COOKIE_NAME,
+  type AuthUser,
+  type ResolvedProvider,
+} from "../auth.js";
+import type { AuthConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// ─── JWT Token Tests ────────────────────────────────────────────────────────
+
+describe("signToken / verifyToken", () => {
+  const secret = "test-secret-32-chars-long-abcdef";
+  const user: AuthUser = { sub: "user@example.com", name: "Test User", username: "testuser", provider: "github" };
+
+  it("should sign and verify a token", () => {
+    const token = signToken(user, secret);
+    const payload = verifyToken(token, secret);
+    expect(payload).not.toBeNull();
+    expect(payload!.sub).toBe("user@example.com");
+    expect(payload!.name).toBe("Test User");
+    expect(payload!.provider).toBe("github");
+    expect(payload!.exp).toBeGreaterThan(Math.floor(Date.now() / 1000));
+  });
+
+  it("should return null for tampered token", () => {
+    const token = signToken(user, secret);
+    const tampered = token.slice(0, -5) + "XXXXX";
+    expect(verifyToken(tampered, secret)).toBeNull();
+  });
+
+  it("should return null for wrong secret", () => {
+    const token = signToken(user, secret);
+    expect(verifyToken(token, "wrong-secret")).toBeNull();
+  });
+
+  it("should return null for garbage string", () => {
+    expect(verifyToken("not.a.jwt", secret)).toBeNull();
+  });
+});
+
+// ─── Cookie Parsing Tests ───────────────────────────────────────────────────
+
+describe("parseAuthCookie", () => {
+  it("should parse cookie from header", () => {
+    const header = `other=abc; ${COOKIE_NAME}=mytoken123; another=def`;
+    expect(parseAuthCookie(header)).toBe("mytoken123");
+  });
+
+  it("should return null when cookie not present", () => {
+    expect(parseAuthCookie("other=abc")).toBeNull();
+  });
+
+  it("should return null for undefined header", () => {
+    expect(parseAuthCookie(undefined)).toBeNull();
+  });
+
+  it("should parse when cookie is first", () => {
+    expect(parseAuthCookie(`${COOKIE_NAME}=token1; other=x`)).toBe("token1");
+  });
+
+  it("should parse when cookie is only value", () => {
+    expect(parseAuthCookie(`${COOKIE_NAME}=singletoken`)).toBe("singletoken");
+  });
+});
+
+// ─── Email Allowlist Tests ──────────────────────────────────────────────────
+
+describe("isUserAllowed", () => {
+  it("should allow any user when allowedUsers is undefined", () => {
+    expect(isUserAllowed("anyone@example.com", "anyone")).toBe(true);
+  });
+
+  it("should allow any user when allowedUsers is empty", () => {
+    expect(isUserAllowed("anyone@example.com", "anyone", [])).toBe(true);
+  });
+
+  it("should allow exact email match", () => {
+    expect(isUserAllowed("user@example.com", "user", ["user@example.com"])).toBe(true);
+  });
+
+  it("should allow exact username match", () => {
+    expect(isUserAllowed("other@example.com", "octocat", ["octocat"])).toBe(true);
+  });
+
+  it("should reject non-matching email and username", () => {
+    expect(isUserAllowed("other@example.com", "other", ["user@example.com"])).toBe(false);
+  });
+
+  it("should support domain wildcard", () => {
+    expect(isUserAllowed("anyone@company.com", "anyone", ["*@company.com"])).toBe(true);
+    expect(isUserAllowed("anyone@other.com", "anyone", ["*@company.com"])).toBe(false);
+  });
+
+  it("should be case-insensitive for email", () => {
+    expect(isUserAllowed("User@Example.COM", "user", ["user@example.com"])).toBe(true);
+    expect(isUserAllowed("test@Company.Com", "test", ["*@company.com"])).toBe(true);
+  });
+
+  it("should be case-insensitive for username", () => {
+    expect(isUserAllowed("x@y.com", "OctoCat", ["octocat"])).toBe(true);
+  });
+});
+
+// ─── Auth Secret Management Tests ───────────────────────────────────────────
+
+describe("ensureAuthSecret", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-auth-secret-${Date.now()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("should return existing secret when present", () => {
+    const config: AuthConfig = {
+      secret: "existing-secret",
+      providers: { github: { clientId: "id", clientSecret: "sec" } },
+    };
+    expect(ensureAuthSecret(config)).toBe("existing-secret");
+  });
+
+  it("should generate secret when missing and update config object", () => {
+    // Note: persistence to file depends on CONFIG_FILE which is resolved at module load.
+    // We test the in-memory behavior here.
+    const config: AuthConfig = {
+      secret: "",
+      providers: { github: { clientId: "id", clientSecret: "sec" } },
+    };
+    const secret = ensureAuthSecret(config);
+
+    expect(secret).toHaveLength(32);
+    expect(config.secret).toBe(secret);
+    // Secret should be hex
+    expect(/^[0-9a-f]{32}$/.test(secret)).toBe(true);
+  });
+
+  it("should generate different secrets each time", () => {
+    const config1: AuthConfig = { secret: "", providers: {} };
+    const config2: AuthConfig = { secret: "", providers: {} };
+    const s1 = ensureAuthSecret(config1);
+    const s2 = ensureAuthSecret(config2);
+    expect(s1).not.toBe(s2);
+  });
+});
+
+// ─── Provider Registry Tests ────────────────────────────────────────────────
+
+describe("buildProviderRegistry", () => {
+  // We test buildProviderRegistry indirectly through the resolved provider for GitHub
+  // (since Google/Keycloak/OIDC require OIDC discovery which needs network)
+
+  it("should resolve GitHub provider with hardcoded endpoints", async () => {
+    const registry = await buildProviderRegistry({
+      github: { clientId: "gh-id", clientSecret: "gh-secret" },
+    });
+    expect(registry.size).toBe(1);
+    const gh = registry.get("github")!;
+    expect(gh.name).toBe("GitHub");
+    expect(gh.authorizeUrl).toBe("https://github.com/login/oauth/authorize");
+    expect(gh.tokenUrl).toBe("https://github.com/login/oauth/access_token");
+    expect(gh.userInfoUrl).toBe("https://api.github.com/user");
+    expect(gh.scopes).toBe("user:email");
+    expect(gh.clientId).toBe("gh-id");
+  });
+
+  it("should return empty registry for empty providers", async () => {
+    const registry = await buildProviderRegistry({});
+    expect(registry.size).toBe(0);
+  });
+
+  it("should skip providers that fail to resolve (e.g. OIDC without issuerUrl)", async () => {
+    const registry = await buildProviderRegistry({
+      keycloak: { clientId: "kc", clientSecret: "ks" }, // missing issuerUrl
+      github: { clientId: "gh", clientSecret: "gs" },
+    });
+    // keycloak should be skipped (no issuerUrl), github should resolve
+    expect(registry.size).toBe(1);
+    expect(registry.has("github")).toBe(true);
+  });
+});
+
+// ─── Authorize URL Builder Tests ────────────────────────────────────────────
+
+describe("buildAuthorizeUrl", () => {
+  it("should build correct authorize URL", () => {
+    const provider: ResolvedProvider = {
+      key: "github",
+      name: "GitHub",
+      authorizeUrl: "https://github.com/login/oauth/authorize",
+      tokenUrl: "https://github.com/login/oauth/access_token",
+      userInfoUrl: "https://api.github.com/user",
+      scopes: "user:email",
+      clientId: "my-client-id",
+      clientSecret: "secret",
+    };
+    const url = buildAuthorizeUrl(provider, "http://localhost:8000/auth/callback/github", "state123");
+    expect(url).toContain("https://github.com/login/oauth/authorize?");
+    expect(url).toContain("client_id=my-client-id");
+    expect(url).toContain("redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Fauth%2Fcallback%2Fgithub");
+    expect(url).toContain("scope=user%3Aemail");
+    expect(url).toContain("state=state123");
+    expect(url).toContain("response_type=code");
+  });
+});