@hellcoder/companion 0.96.0

package/server/middleware/managed-auth.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { Hono } from "hono";
+import { createToken, verifyToken, managedAuth } from "./managed-auth.js";
+
+const TEST_SECRET = "test-secret-key-for-hmac-256-signing";
+
+describe("managed-auth token utilities", () => {
+  describe("createToken + verifyToken", () => {
+    it("creates a valid token that can be verified", async () => {
+      const token = await createToken(TEST_SECRET, 60);
+      expect(typeof token).toBe("string");
+      expect(token.split(".")).toHaveLength(2);
+
+      const valid = await verifyToken(token, TEST_SECRET);
+      expect(valid).toBe(true);
+    });
+
+    it("rejects tokens signed with a different secret", async () => {
+      const token = await createToken(TEST_SECRET, 60);
+      const valid = await verifyToken(token, "wrong-secret");
+      expect(valid).toBe(false);
+    });
+
+    it("rejects expired tokens", async () => {
+      // Create a token that expires in -1 seconds (already expired)
+      const token = await createToken(TEST_SECRET, -1);
+      const valid = await verifyToken(token, TEST_SECRET);
+      expect(valid).toBe(false);
+    });
+
+    it("rejects malformed tokens", async () => {
+      expect(await verifyToken("not-a-token", TEST_SECRET)).toBe(false);
+      expect(await verifyToken("a.b.c", TEST_SECRET)).toBe(false);
+      expect(await verifyToken("", TEST_SECRET)).toBe(false);
+    });
+
+    it("rejects tokens with tampered payload", async () => {
+      const token = await createToken(TEST_SECRET, 60);
+      const [, sig] = token.split(".");
+      // Replace payload with different data — signature won't match
+      const tamperedPayload = btoa(JSON.stringify({ exp: 9999999999 }))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+      const valid = await verifyToken(`${tamperedPayload}.${sig}`, TEST_SECRET);
+      expect(valid).toBe(false);
+    });
+
+    it("uses custom TTL for token expiration", async () => {
+      // Create a token with a very long TTL
+      const token = await createToken(TEST_SECRET, 3600);
+      const valid = await verifyToken(token, TEST_SECRET);
+      expect(valid).toBe(true);
+    });
+  });
+});
+
+describe("managed-auth middleware", () => {
+  const savedEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    savedEnv.COMPANION_AUTH_ENABLED = process.env.COMPANION_AUTH_ENABLED;
+    savedEnv.COMPANION_AUTH_SECRET = process.env.COMPANION_AUTH_SECRET;
+    savedEnv.COMPANION_LOGIN_URL = process.env.COMPANION_LOGIN_URL;
+  });
+
+  afterEach(() => {
+    for (const [key, val] of Object.entries(savedEnv)) {
+      if (val === undefined) delete process.env[key];
+      else process.env[key] = val;
+    }
+  });
+
+  /**
+   * Helper: creates a test Hono app with managedAuth middleware
+   * and a catch-all route that returns 200 if reached.
+   */
+  function createTestApp() {
+    const app = new Hono();
+    app.use("/*", managedAuth);
+    app.all("/*", (c) => c.json({ ok: true }));
+    return app;
+  }
+
+  it("enforces auth even without COMPANION_AUTH_ENABLED (enable decision is in index.ts)", async () => {
+    // The middleware is always active when registered — the enable/disable
+    // decision moved to index.ts which only registers it when appropriate.
+    delete process.env.COMPANION_AUTH_ENABLED;
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const res = await app.request("/api/sessions");
+    expect(res.status).toBe(401);
+  });
+
+  it("bypasses auth for /health endpoint", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const res = await app.request("/health");
+    expect(res.status).toBe(200);
+  });
+
+  it("bypasses auth for /ws/cli/ paths", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const res = await app.request("/ws/cli/abc-123");
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 401 when no token is provided and no login URL is set", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    delete process.env.COMPANION_LOGIN_URL;
+    const app = createTestApp();
+
+    const res = await app.request("/api/sessions");
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toBe("Unauthorized");
+  });
+
+  it("redirects when no token is provided and login URL is set", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    process.env.COMPANION_LOGIN_URL = "https://login.example.com";
+    const app = createTestApp();
+
+    const res = await app.request("/api/sessions", { redirect: "manual" });
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("https://login.example.com");
+  });
+
+  it("returns 500 when COMPANION_AUTH_SECRET is missing", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    delete process.env.COMPANION_AUTH_SECRET;
+    const app = createTestApp();
+
+    // Provide a token so it gets past the "no token" check
+    const res = await app.request("/api/sessions?token=fake.token");
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body.error).toBe("Server misconfigured");
+  });
+
+  it("allows access with a valid token in query param", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const token = await createToken(TEST_SECRET, 60);
+    const res = await app.request(`/api/sessions?token=${token}`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+    expect(res.headers.get("set-cookie")).toContain("companion_token=");
+  });
+
+  it("sets a Secure auth cookie for HTTPS requests", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const token = await createToken(TEST_SECRET, 60);
+    const res = await app.request(`https://instance.example.com/api/sessions?token=${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("set-cookie")).toContain("Secure");
+  });
+
+  it("omits Secure on auth cookie for direct HTTP instance URLs", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const token = await createToken(TEST_SECRET, 60);
+    const res = await app.request(`http://5.161.114.105/?token=${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("set-cookie")).not.toContain("Secure");
+  });
+
+  it("persists query-token auth as cookie for follow-up requests", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const token = await createToken(TEST_SECRET, 60);
+    const first = await app.request(`/api/sessions?token=${token}`);
+    expect(first.status).toBe(200);
+
+    const setCookie = first.headers.get("set-cookie");
+    expect(setCookie).toBeTruthy();
+
+    const cookiePair = setCookie!.split(";")[0];
+    const second = await app.request("/api/sessions", {
+      headers: { cookie: cookiePair },
+    });
+    expect(second.status).toBe(200);
+    expect(await second.json()).toEqual({ ok: true });
+  });
+
+  it("allows access with a valid token in cookie", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const token = await createToken(TEST_SECRET, 60);
+    const res = await app.request("/api/sessions", {
+      headers: { cookie: `companion_token=${token}` },
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it("rejects an invalid token", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    delete process.env.COMPANION_LOGIN_URL;
+    const app = createTestApp();
+
+    const res = await app.request("/api/sessions?token=bad.token");
+    expect(res.status).toBe(401);
+  });
+
+  it("rejects an expired token", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    delete process.env.COMPANION_LOGIN_URL;
+    const app = createTestApp();
+
+    const token = await createToken(TEST_SECRET, -1);
+    const res = await app.request(`/api/sessions?token=${token}`);
+    expect(res.status).toBe(401);
+  });
+
+  it("redirects with invalid token when login URL is set", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    process.env.COMPANION_LOGIN_URL = "https://login.example.com";
+    const app = createTestApp();
+
+    const res = await app.request("/api/sessions?token=bad.token", {
+      redirect: "manual",
+    });
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("https://login.example.com");
+  });
+
+  it("prefers query param over cookie when both are present", async () => {
+    process.env.COMPANION_AUTH_ENABLED = "1";
+    process.env.COMPANION_AUTH_SECRET = TEST_SECRET;
+    const app = createTestApp();
+
+    const validToken = await createToken(TEST_SECRET, 60);
+    // Query has valid token, cookie has bad token — query wins.
+    const res = await app.request(`/api/sessions?token=${validToken}`, {
+      headers: { cookie: "companion_token=bad.token" },
+    });
+    expect(res.status).toBe(200);
+  });
+});

package/server/middleware/managed-auth.ts

@@ -0,0 +1,195 @@
+import { createMiddleware } from "hono/factory";
+import type { Context } from "hono";
+
+/**
+ * Auth middleware for managed Companion Cloud instances.
+ *
+ * Only active when COMPANION_AUTH_ENABLED=1. Validates a JWT from a cookie
+ * or query parameter, signed by the control plane using COMPANION_AUTH_SECRET.
+ *
+ * Skipped paths:
+ *  - /ws/cli/*  — internal CLI WebSocket (Claude Code connects from within the machine)
+ *  - /health    — monitoring endpoint used by control plane health checks
+ */
+export const managedAuth = createMiddleware(async (c: Context, next) => {
+  // This middleware is only registered by index.ts when managed auth is
+  // enabled (COMPANION_AUTH_ENABLED=1 or COMPANION_AUTH_SECRET is set).
+  // No redundant env check needed here.
+
+  const path = c.req.path;
+
+  // Internal paths that bypass auth
+  if (path.startsWith("/ws/cli/") || path === "/health") return next();
+
+  const cookieToken = getCookie(c, "companion_token");
+  const queryToken = c.req.query("token");
+  // Give explicit URL token precedence so reconnect links can always override
+  // stale/expired cookies in the browser.
+  const token = queryToken || cookieToken;
+
+  if (!token) {
+    return redirectOrUnauthorized(c);
+  }
+
+  const secret = process.env.COMPANION_AUTH_SECRET;
+  if (!secret) {
+    console.error("[managed-auth] COMPANION_AUTH_SECRET is not set");
+    return c.json({ error: "Server misconfigured" }, 500);
+  }
+
+  const valid = await verifyToken(token, secret);
+  if (!valid) {
+    return redirectOrUnauthorized(c);
+  }
+
+  // When auth arrives via URL query once, persist it to a cookie so static
+  // assets and subsequent API calls are authenticated without ?token=...
+  if (queryToken && queryToken !== cookieToken) {
+    setAuthCookie(c, queryToken);
+  }
+
+  return next();
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getCookie(c: Context, name: string): string | undefined {
+  const header = c.req.header("cookie");
+  if (!header) return undefined;
+  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match?.[1];
+}
+
+function setAuthCookie(c: Context, token: string): void {
+  const encoded = encodeURIComponent(token);
+  const secure = shouldUseSecureCookie(c) ? "; Secure" : "";
+  c.header(
+    "Set-Cookie",
+    `companion_token=${encoded}; Path=/; HttpOnly${secure}; SameSite=Lax; Max-Age=900`,
+  );
+}
+
+function shouldUseSecureCookie(c: Context): boolean {
+  const forwardedProto = c.req.header("x-forwarded-proto")?.split(",")[0]?.trim().toLowerCase();
+  if (forwardedProto) return forwardedProto === "https";
+
+  try {
+    return new URL(c.req.url).protocol === "https:";
+  } catch {
+    return true;
+  }
+}
+
+function redirectOrUnauthorized(c: Context): Response {
+  const loginUrl = process.env.COMPANION_LOGIN_URL;
+  if (loginUrl) {
+    return c.redirect(loginUrl);
+  }
+  return c.json({ error: "Unauthorized" }, 401);
+}
+
+/**
+ * Verify a JWT-like HMAC-SHA256 token.
+ * Token format: base64url(payload).base64url(signature)
+ * Payload: { exp: number } (Unix seconds)
+ */
+export async function verifyToken(
+  token: string,
+  secret: string,
+): Promise<boolean> {
+  const parts = token.split(".");
+  if (parts.length !== 2) return false;
+
+  const [payloadB64, signatureB64] = parts;
+
+  // Verify signature using HMAC-SHA256
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const expectedSig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(payloadB64),
+  );
+
+  const expectedB64 = base64UrlEncode(new Uint8Array(expectedSig));
+  if (!timingSafeEqual(expectedB64, signatureB64)) return false;
+
+  // Check expiration
+  try {
+    const payload = JSON.parse(
+      new TextDecoder().decode(base64UrlDecode(payloadB64)),
+    );
+    if (typeof payload.exp === "number" && payload.exp < Date.now() / 1000) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Create a signed token for the control plane to issue.
+ * Exported for use by the control plane's token endpoint.
+ */
+export async function createToken(
+  secret: string,
+  ttlSeconds = 900, // 15 minutes
+): Promise<string> {
+  const payload = { exp: Math.floor(Date.now() / 1000) + ttlSeconds };
+  const payloadB64 = base64UrlEncode(
+    new TextEncoder().encode(JSON.stringify(payload)),
+  );
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(payloadB64),
+  );
+
+  return `${payloadB64}.${base64UrlEncode(new Uint8Array(sig))}`;
+}
+
+// ─── Base64url ───────────────────────────────────────────────────────────────
+
+function base64UrlEncode(data: Uint8Array): string {
+  let binary = "";
+  for (const byte of data) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64UrlDecode(str: string): Uint8Array {
+  const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}