Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

39.3 KB
Raw Blame
/**
 * Provider key minting (the OAuth-style flow a catalog group declares).
 *
 * - PKCE: the challenge is the unpadded base64url SHA-256 of a fresh, in-window verifier; the
 *   authorize URL carries the callback, the harness's own app URL and the key name, encoded,
 *   and manual mode omits the callback but still pins S256.
 * - The exchange posts code, verifier and method as JSON and returns the key; a 400, a 403, any
 *   other failure, a 200 without a usable key and an unreachable endpoint each map to their own
 *   reason, never carrying the request's detail.
 * - A flow belongs to one user in one Project, expires after ten minutes and is single use; a
 *   failed exchange or an unstorable key ends it with its reason. A redirect deposits the code
 *   once (a manual flow takes none) and only the owner's poll redeems it; an unpolled deposit
 *   expires with the flow. The callback origin follows the request unless a proxy is trusted.
 * - A redirect opens only to an origin the authorization page accepts — HTTPS, or plain HTTP to
 *   `localhost`, `[::1]` or `127.x.x.x`; asked for anywhere else (a LAN address, a hostname,
 *   `0.0.0.0`), the flow opens in manual mode, says so, and still takes a pasted code.
 * - The routes: only the owner starts, polls and redeems; the key lands on every model of the
 *   group and the Project's open Session channels hear credentials_updated; a rejected code
 *   reaches the dialog through the poll and touches no model; a malformed link answers a page.
 * - The redirect receiver answers without a session: the flow id buys a deposit and nothing
 *   more — not for another user, an unknown flow, another Project, a stale or replayed flow,
 *   a HEAD, or a manual flow — and the exemption covers exactly its literal path.
 *
 * No test reaches the network: the exchange endpoint is the suite's fetch fake, handed to
 * `exchangeCode` and the service, and standing in for the global fetch in the route cases. The
 * route describes share one app, every case in a Project of its own.
 */
import { readFile } from "node:fs/promises";
import path from "node:path";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { APP_URL, presetModelEntries, providerInfo } from "@adelie/core/model-catalog";
import type {
  ModelOAuthCodeResponse,
  ModelOAuthStartResponse,
  ModelOAuthStatusResponse,
  ModelsResponse,
  ProjectCreateResponse,
} from "../src/api/types.js";
import type { ChannelEvent } from "../src/runtime/channel.js";
import { HttpError } from "../src/http/errors.js";
import {
  buildAuthorizeUrl,
  codeChallenge,
  createVerifier,
  exchangeCode,
  FLOW_TTL_MS,
  ModelOAuthService,
  openedMode,
} from "../src/services/model-oauth-service.js";
import { requestOrigin } from "../src/http/routes/model-oauth.js";
import { fakeFetch, jsonResponse, stubFetch } from "./fixtures/fetch.js";
import type { FetchFake } from "./fixtures/fetch.js";
import { sessionRow } from "./fixtures/session.js";
import { apiClient, createTestApp, provisionUser } from "./helpers.js";
import type { TestApp } from "./helpers.js";
import { wire } from "@adelie/core/kernel";

/** The catalog group under test; the flow exists only because this entry declares it. */
const TOKENDANCE = providerInfo("tokendance")!;

/**
 * How many models the minted key lands on — derived from the catalog rather than pinned, so
 * adding a row to this group does not fail three assertions that are not about the count.
 */
const TOKENDANCE_MODELS = presetModelEntries().filter((m) => m.provider === "tokendance").length;

describe("PKCE derivation", () => {
  it("challenge is the unpadded base64url SHA-256 of the verifier (RFC 7636 vector)", () => {
    expect(codeChallenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk")).toBe(
      "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    );
  });

  it("challenge carries no base64 padding or non-url characters", () => {
    const challenge = codeChallenge(createVerifier());
    expect(challenge).toMatch(/^[A-Za-z0-9_-]{43}$/);
  });

  it("verifier is inside the spec's 43-128 window and alphabet, and is not reused", () => {
    const a = createVerifier();
    const b = createVerifier();
    expect(a).toMatch(/^[A-Za-z0-9._~-]{43,128}$/);
    expect(a.length).toBe(72);
    expect(a).not.toBe(b);
  });
});

describe("authorize URL", () => {
  const challenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM";

  it("carries the callback URL, the app URL and the key name, all percent-encoded", () => {
    const url = buildAuthorizeUrl({
      oauth: TOKENDANCE.oauth!,
      challenge,
      callbackUrl: "http://127.0.0.1:8123/api/projects/p1/model-oauth/callback?flow=abc-_1",
    });
    expect(url.startsWith(`${TOKENDANCE.oauth!.authorizeUrl}?`)).toBe(true);
    const q = new URL(url).searchParams;
    expect(q.get("callback_url")).toBe(
      "http://127.0.0.1:8123/api/projects/p1/model-oauth/callback?flow=abc-_1",
    );
    expect(q.get("code_challenge")).toBe(challenge);
    expect(q.get("code_challenge_method")).toBe("S256");
    expect(q.get("app_url")).toBe(APP_URL);
    expect(q.get("key_name")).toBe("Adelie");
    // The two URL-valued parameters travel escaped, never raw.
    expect(url).toContain("app_url=https%3A%2F%2Fpenguin.ooo%2F");
    expect(url).toContain("callback_url=http%3A%2F%2F127.0.0.1%3A8123%2F");
    expect(url).not.toContain("?flow=abc-_1&code_challenge");
  });

  it("app_url is the harness's own stable URL, not the callback's ephemeral port", () => {
    const url = buildAuthorizeUrl({
      oauth: TOKENDANCE.oauth!,
      challenge,
      callbackUrl: "http://127.0.0.1:51234/api/projects/p1/model-oauth/callback?flow=x",
    });
    expect(new URL(url).searchParams.get("app_url")).toBe(APP_URL);
    expect(new URL(url).searchParams.get("app_url")).not.toContain("51234");
  });

  it("manual mode omits the callback and still pins S256", () => {
    const q = new URL(buildAuthorizeUrl({ oauth: TOKENDANCE.oauth!, challenge })).searchParams;
    expect(q.has("callback_url")).toBe(false);
    expect(q.get("code_challenge_method")).toBe("S256");
    expect(q.get("code_challenge")).toBe(challenge);
  });
});

describe("code exchange", () => {
  const call = (impl: typeof fetch) =>
    exchangeCode({
      exchangeUrl: TOKENDANCE.oauth!.exchangeUrl,
      code: "the-code",
      verifier: "the-verifier",
      fetchImpl: impl,
    });

  it("posts the code, the verifier and the method as JSON, and returns the minted key", async () => {
    const exchange = fakeFetch(() => jsonResponse({ key: "sk-minted" }));
    const res = await call(exchange.fetch);
    expect(res).toEqual({ ok: true, key: "sk-minted" });
    expect(exchange.calls.map((c) => c.url)).toEqual([TOKENDANCE.oauth!.exchangeUrl]);
    expect(JSON.parse(exchange.calls[0]!.body)).toEqual({
      code: "the-code",
      code_verifier: "the-verifier",
      code_challenge_method: "S256",
    });
  });

  it("400 is a malformed authorization request; 403 is a rejected code", async () => {
    const fail = (status: number) =>
      call(fakeFetch(() => jsonResponse({ error: "no" }, status)).fetch);
    expect(await fail(400)).toEqual({ ok: false, error: "invalid_request" });
    expect(await fail(403)).toEqual({ ok: false, error: "code_rejected" });
    expect(await fail(500)).toEqual({ ok: false, error: "upstream_failed" });
  });

  it("a 200 without a usable key is a failure, not a key", async () => {
    const answered = (response: Response) => call(fakeFetch(() => response).fetch);
    expect(await answered(jsonResponse({ key: "" }))).toEqual({
      ok: false,
      error: "upstream_failed",
    });
    expect(await answered(jsonResponse({}))).toEqual({ ok: false, error: "upstream_failed" });
    expect(await answered(new Response("not json", { status: 200 }))).toEqual({
      ok: false,
      error: "upstream_failed",
    });
  });

  it("a transport failure reports unreachable and carries no detail (the request holds the code)", async () => {
    const res = await call(
      fakeFetch(() => {
        throw new Error("connect ECONNREFUSED sk-leak");
      }).fetch,
    );
    expect(res).toEqual({ ok: false, error: "unreachable" });
    expect(JSON.stringify(res)).not.toContain("sk-leak");
  });
});

describe("flow store", () => {
  let clock: number;
  let applied: { projectId: string; provider: string; apiKey: string }[];
  /** The provider's exchange endpoint. */
  let exchange: FetchFake;
  /** Codes the exchange endpoint was asked to redeem, in order. */
  const exchanged = () =>
    exchange.calls.map((call) => (JSON.parse(call.body) as { code: string }).code);
  let service: ModelOAuthService;

  const start = () =>
    service.start({
      projectId: "p1",
      userId: "u1",
      provider: "tokendance",
      mode: "callback",
      callbackOrigin: "http://127.0.0.1:8123",
    });

  beforeEach(() => {
    clock = 1_700_000_000_000;
    applied = [];
    exchange = fakeFetch(() => jsonResponse({ key: "sk-minted" }));
    service = wire(ModelOAuthService, {
      applyGroupKey: async (projectId: string, provider: string, apiKey: string) => {
        applied.push({ projectId, provider, apiKey });
        return 6;
      },
      fetchImpl: exchange.fetch,
      now: () => clock,
    });
  });

  it("refuses a provider that declares no flow, and one that is not in the catalog at all", () => {
    for (const provider of ["deepseek", "custom", "not-a-provider"]) {
      expect(() =>
        service.start({
          projectId: "p1",
          userId: "u1",
          provider,
          mode: "callback",
          callbackOrigin: "http://127.0.0.1:8123",
        }),
      ).toThrow(HttpError);
    }
  });

  it("the callback URL keeps its query, so the flow id rides back with the code", () => {
    const { flowId, authorizeUrl } = start();
    expect(new URL(authorizeUrl).searchParams.get("callback_url")).toBe(
      `http://127.0.0.1:8123/api/projects/p1/model-oauth/callback?flow=${encodeURIComponent(flowId)}`,
    );
    // Opaque and unguessable: 32 random bytes, base64url.
    expect(flowId).toMatch(/^[A-Za-z0-9_-]{43}$/);
  });

  it("a flow belongs to one user in one Project; anyone else sees a 404", async () => {
    const { flowId } = start();
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).status).toBe("pending");
    await expect(service.poll({ flowId, userId: "u2", projectId: "p1" })).rejects.toThrow(
      HttpError,
    );
    await expect(service.poll({ flowId, userId: "u1", projectId: "p2" })).rejects.toThrow(
      HttpError,
    );
    await expect(service.poll({ flowId: "nope", userId: "u1", projectId: "p1" })).rejects.toThrow(
      HttpError,
    );
  });

  it("expires after ten minutes, and the expired flow is gone rather than failed", async () => {
    const { flowId } = start();
    clock += 10 * 60 * 1000 - 1;
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).status).toBe("pending");
    clock += 1;
    await expect(service.poll({ flowId, userId: "u1", projectId: "p1" })).rejects.toThrow(
      HttpError,
    );
    await expect(
      service.complete({ flowId, userId: "u1", projectId: "p1", code: "c" }),
    ).rejects.toThrow(HttpError);
  });

  it("is single use: the second redemption is refused and the verifier is spent only once", async () => {
    const { flowId } = start();
    expect(await service.complete({ flowId, userId: "u1", projectId: "p1", code: "c" })).toEqual({
      ok: true,
      applied: 6,
    });
    expect(applied).toEqual([{ projectId: "p1", provider: "tokendance", apiKey: "sk-minted" }]);
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).status).toBe("done");
    await expect(
      service.complete({ flowId, userId: "u1", projectId: "p1", code: "c" }),
    ).rejects.toThrow(HttpError);
    expect(applied).toHaveLength(1);
  });

  it("a failed exchange ends the flow and reports the mapped reason", async () => {
    service = wire(ModelOAuthService, {
      applyGroupKey: async () => 6,
      fetchImpl: fakeFetch(() => jsonResponse({}, 403)).fetch,
      now: () => clock,
    });
    const { flowId } = start();
    expect(await service.complete({ flowId, userId: "u1", projectId: "p1", code: "c" })).toEqual({
      ok: false,
      error: "code_rejected",
    });
    const state = await service.poll({ flowId, userId: "u1", projectId: "p1" });
    expect(state).toEqual({ status: "error", provider: "tokendance", error: "code_rejected" });
  });

  it("a key that cannot be stored is reported as such, not as a success", async () => {
    service = wire(ModelOAuthService, {
      applyGroupKey: async () => {
        throw new Error("disk full");
      },
      fetchImpl: fakeFetch(() => jsonResponse({ key: "sk-minted" })).fetch,
      now: () => clock,
    });
    const { flowId } = start();
    expect(await service.complete({ flowId, userId: "u1", projectId: "p1", code: "c" })).toEqual({
      ok: false,
      error: "apply_failed",
    });
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).error).toBe(
      "apply_failed",
    );
  });

  it("a deposited code is redeemed by the owner's poll, not by the deposit itself", async () => {
    const { flowId } = start();
    service.deposit({ flowId, projectId: "p1", code: "redirected-code" });
    // The deposit alone reaches no provider and writes nothing.
    expect(applied).toEqual([]);
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).status).toBe("done");
    expect(applied).toEqual([{ projectId: "p1", provider: "tokendance", apiKey: "sk-minted" }]);
    // `applied` is set on the redeeming poll only, so the route publishes the change once.
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).applied).toBeUndefined();
    expect(applied).toHaveLength(1);
  });

  it("a manual flow has no redirect to receive, so it cannot be deposited into", () => {
    const { flowId } = service.start({
      projectId: "p1",
      userId: "u1",
      provider: "tokendance",
      mode: "manual",
      callbackOrigin: "http://127.0.0.1:8123",
    });
    expect(() => service.deposit({ flowId, projectId: "p1", code: "c" })).toThrow(HttpError);
  });

  it("the deposit slot holds one code: a second redirect neither overwrites it nor re-arms it", async () => {
    const { flowId } = start();
    service.deposit({ flowId, projectId: "p1", code: "first" });
    expect(() => service.deposit({ flowId, projectId: "p1", code: "second" })).toThrow(HttpError);
    expect((await service.poll({ flowId, userId: "u1", projectId: "p1" })).status).toBe("done");
    expect(exchanged()).toEqual(["first"]);
    // And once redeemed there is nothing left to deposit into either.
    expect(() => service.deposit({ flowId, projectId: "p1", code: "third" })).toThrow(HttpError);
    expect(exchanged()).toEqual(["first"]);
  });

  it("a deposited code that nobody polls for expires with the flow", async () => {
    const { flowId } = start();
    service.deposit({ flowId, projectId: "p1", code: "never-polled" });
    clock += FLOW_TTL_MS;
    await expect(service.poll({ flowId, userId: "u1", projectId: "p1" })).rejects.toThrow(
      HttpError,
    );
    expect(exchanged()).toEqual([]);
    expect(applied).toEqual([]);
  });
});

describe("callback origin", () => {
  it("follows the request's own URL when no proxy is trusted", () => {
    expect(requestOrigin("http://192.168.1.4:7364/api/x", {}, false)).toBe(
      "http://192.168.1.4:7364",
    );
    // Untrusted headers are ignored outright, so a caller cannot choose where the redirect lands.
    expect(
      requestOrigin("http://192.168.1.4:7364/api/x", { proto: "https", host: "evil.test" }, false),
    ).toBe("http://192.168.1.4:7364");
  });

  it("honours the forwarded pair once the deployment trusts it, taking the client-facing hop", () => {
    expect(
      requestOrigin(
        "http://127.0.0.1:7364/api/x",
        { proto: "https, http", host: "penguin.example, inner" },
        true,
      ),
    ).toBe("https://penguin.example");
    // Trusted but absent: the request's own URL still answers.
    expect(requestOrigin("http://127.0.0.1:7364/api/x", {}, true)).toBe("http://127.0.0.1:7364");
  });
});

describe("opened mode", () => {
  it("keeps the redirect for HTTPS and for plain HTTP to a loopback host", () => {
    for (const origin of [
      "http://localhost:7364",
      "http://127.0.0.1:7364",
      "http://127.8.9.10:7364",
      "http://[::1]:7364",
      "https://penguin.example",
      "https://192.168.1.10:7364",
    ]) {
      expect(openedMode("callback", origin), origin).toBe("callback");
    }
  });

  it("opens a manual flow where the provider refuses to redirect: plain HTTP off loopback", () => {
    for (const origin of [
      "http://192.168.1.10:7364",
      "http://penguin.lan:7364",
      "http://0.0.0.0:7364",
      "http://app.localhost:7364",
      "not a url",
    ]) {
      expect(openedMode("callback", origin), origin).toBe("manual");
    }
  });

  it("never turns a manual request into a redirect", () => {
    expect(openedMode("manual", "http://localhost:7364")).toBe("manual");
  });
});

/** The route describes' app and the owner of every Project in it. */
let t: TestApp;
let owner: ReturnType<typeof apiClient>;

beforeAll(async () => {
  t = await createTestApp();
  owner = apiClient(t.app, (await provisionUser(t.app, "owner_o")).cookie);
});
afterAll(async () => {
  await t.cleanup();
});

describe("model-oauth routes", () => {
  let member: ReturnType<typeof apiClient>;
  let projectId: string;
  /** The provider's exchange endpoint, standing in for the global fetch. */
  let exchange: FetchFake;
  const exchanges = () =>
    exchange.calls.map((call) => ({
      url: call.url,
      body: JSON.parse(call.body) as Record<string, unknown>,
    }));

  const base = () => `/api/projects/${projectId}/model-oauth`;

  beforeAll(async () => {
    member = apiClient(t.app, (await provisionUser(t.app, "member_m")).cookie);
  });

  // Every case runs its flows against a Project of its own.
  let projects = 0;
  beforeEach(async () => {
    projects += 1;
    const created = (await (
      await owner.post("/api/projects", {
        projectId: `owner_o-td_${projects}`,
        name: "TokenDance project",
      })
    ).json()) as ProjectCreateResponse;
    projectId = created.project.projectId;
    expect(
      (await owner.post(`/api/projects/${projectId}/members`, { userId: "member_m" })).status,
    ).toBe(201);
    exchange = stubFetch(() => jsonResponse({ key: "sk-oauth-minted-key-9911" }));
  });
  afterEach(() => {
    vi.unstubAllGlobals();
  });

  it("owner starts a flow; a member cannot, and neither can start one for a group with no flow", async () => {
    const res = await owner.post(`${base()}/start`, { provider: "tokendance" });
    expect(res.status).toBe(200);
    const body = (await res.json()) as ModelOAuthStartResponse;
    expect(body.flowId).toMatch(/^[A-Za-z0-9_-]+$/);
    const q = new URL(body.authorizeUrl).searchParams;
    expect(q.get("callback_url")).toBe(
      `http://localhost${base()}/callback?flow=${encodeURIComponent(body.flowId)}`,
    );
    expect(q.get("key_name")).toBe("Adelie");
    expect(q.get("app_url")).toBe(APP_URL);
    expect(body.mode).toBe("callback");

    expect((await member.post(`${base()}/start`, { provider: "tokendance" })).status).toBe(403);
    expect((await owner.post(`${base()}/start`, { provider: "deepseek" })).status).toBe(400);
  });

  it("the callback deposits the code and the owner's poll redeems it, writing the key to every model of the group", async () => {
    const started = (await (
      await owner.post(`${base()}/start`, { provider: "tokendance" })
    ).json()) as ModelOAuthStartResponse;

    // A subscribed tab of this Project must be told the credentials changed.
    t.deps.sessionsRepo.insert(sessionRow("td-live", { projectId, workspace: t.root }));
    const events: ChannelEvent[] = [];
    t.deps.channels.get("td-live").subscribe((e) => events.push(e));

    const cb = await owner.get(
      `${base()}/callback?flow=${encodeURIComponent(started.flowId)}&code=auth-code-1`,
    );
    expect(cb.status).toBe(200);
    expect(cb.headers.get("content-type")).toContain("text/html");
    const page = await cb.text();
    expect(page).toContain("Authorization received");
    // The page tells the user where to look and nothing else.
    expect(page).not.toContain("sk-oauth-minted-key-9911");
    expect(page).not.toContain("auth-code-1");
    expect(page).not.toContain("http://");
    // The receiver only wrote the code onto the flow: no provider was called yet.
    expect(exchanges()).toHaveLength(0);

    // The owner's poll is what redeems it, and it reports the finished flow in the same tick.
    const status = (await (
      await owner.get(`${base()}/${started.flowId}`)
    ).json()) as ModelOAuthStatusResponse;
    expect(status).toEqual({ status: "done", provider: "tokendance", applied: TOKENDANCE_MODELS });

    // The exchange spoke the documented protocol, with a verifier this side never published.
    expect(exchanges()).toHaveLength(1);
    expect(exchanges()[0]!.url).toBe(TOKENDANCE.oauth!.exchangeUrl);
    expect(exchanges()[0]!.body.code).toBe("auth-code-1");
    expect(exchanges()[0]!.body.code_challenge_method).toBe("S256");
    expect(String(exchanges()[0]!.body.code_verifier)).toMatch(/^[A-Za-z0-9._~-]{43,128}$/);
    expect(started.authorizeUrl).not.toContain(String(exchanges()[0]!.body.code_verifier));

    const models = (await (
      await owner.get(`/api/projects/${projectId}/models`)
    ).json()) as ModelsResponse;
    const group = models.models.filter((m) => m.provider === "tokendance");
    expect(group.length).toBeGreaterThan(0);
    for (const m of group) expect(m.credential?.apiKeyMasked).toBeTruthy();
    // Only that group, and never in plaintext.
    for (const m of models.models.filter((m) => m.provider !== "tokendance")) {
      expect(m.credential?.apiKeyMasked).toBeUndefined();
    }
    expect(JSON.stringify(models)).not.toContain("sk-oauth-minted-key-9911");

    const cfg = await readFile(path.join(t.root, projectId, ".project_config.toml"), "utf8");
    expect(cfg).toContain("sk-oauth-minted-key-9911");

    expect(
      events
        .filter((e) => e.event === "server_event")
        .map((e) => (JSON.parse(e.data) as { type: string }).type),
    ).toContain("credentials_updated");
    // Published by the redeeming poll alone; the ones after it report a finished flow only.
    expect(await (await owner.get(`${base()}/${started.flowId}`)).json()).toEqual({
      status: "done",
      provider: "tokendance",
    });
    expect(
      events.filter(
        (e) =>
          e.event === "server_event" &&
          (JSON.parse(e.data) as { type: string }).type === "credentials_updated",
      ),
    ).toHaveLength(1);

    // Replaying the same callback cannot spend the flow twice.
    const replay = await owner.get(
      `${base()}/callback?flow=${encodeURIComponent(started.flowId)}&code=auth-code-1`,
    );
    expect(replay.status).toBe(400);
    expect(exchanges()).toHaveLength(1);
  });

  it("a rejected code leaves the flow in error, reaches the dialog through the poll, and never touches the models", async () => {
    exchange = stubFetch(() => jsonResponse({ error: "invalid_code" }, 403));
    const started = (await (
      await owner.post(`${base()}/start`, { provider: "tokendance" })
    ).json()) as ModelOAuthStartResponse;
    // The redirect cannot know the exchange will fail — it deposits and says so.
    const cb = await owner.get(`${base()}/callback?flow=${started.flowId}&code=stale`);
    expect(cb.status).toBe(200);
    expect(await cb.text()).toContain("Authorization received");

    // The failure surfaces where the dialog is looking, and the flow is left ended, not stuck.
    const status = (await (
      await owner.get(`${base()}/${started.flowId}`)
    ).json()) as ModelOAuthStatusResponse;
    expect(status.status).toBe("error");
    expect(status.error).toBe("code_rejected");
    expect(
      (await (await owner.get(`${base()}/${started.flowId}`)).json()) as ModelOAuthStatusResponse,
    ).toEqual({ status: "error", provider: "tokendance", error: "code_rejected" });

    const models = (await (
      await owner.get(`/api/projects/${projectId}/models`)
    ).json()) as ModelsResponse;
    for (const m of models.models) expect(m.credential?.apiKeyMasked).toBeUndefined();
  });

  it("a malformed callback link answers a page, not a stack trace", async () => {
    const res = await owner.get(`${base()}/callback?flow=&code=`);
    expect(res.status).toBe(400);
    expect(res.headers.get("content-type")).toContain("text/html");
    expect(await res.text()).toContain("Authorization failed");
    expect(exchanges()).toHaveLength(0);
  });

  it("manual mode drops the callback and redeems a pasted code instead", async () => {
    const started = (await (
      await owner.post(`${base()}/start`, { provider: "tokendance", mode: "manual" })
    ).json()) as ModelOAuthStartResponse;
    expect(new URL(started.authorizeUrl).searchParams.has("callback_url")).toBe(false);

    const res = await owner.post(`${base()}/${started.flowId}/code`, { code: "pasted-code" });
    expect(res.status).toBe(200);
    const body = (await res.json()) as ModelOAuthCodeResponse;
    expect(body.ok).toBe(true);
    expect(body.applied).toBeGreaterThan(0);
    expect(exchanges()[0]!.body.code).toBe("pasted-code");

    // Single use here too.
    const again = await owner.post(`${base()}/${started.flowId}/code`, { code: "pasted-code" });
    expect(again.status).toBe(409);
  });

  it("a redirect asked for over plain HTTP on a LAN address opens as manual, says so, and redeems a pasted code", async () => {
    const lan = (apiPath: string) => `http://192.168.1.10:7364${apiPath}`;
    const res = await owner.post(lan(`${base()}/start`), { provider: "tokendance" });
    expect(res.status).toBe(200);
    const started = (await res.json()) as ModelOAuthStartResponse;
    expect(started.mode).toBe("manual");
    const q = new URL(started.authorizeUrl).searchParams;
    expect(q.has("callback_url")).toBe(false);
    expect(q.get("code_challenge_method")).toBe("S256");
    expect(q.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);

    const redeemed = await owner.post(lan(`${base()}/${started.flowId}/code`), {
      code: "pasted-code",
    });
    expect(((await redeemed.json()) as ModelOAuthCodeResponse).ok).toBe(true);
    expect(exchanges()[0]!.body.code).toBe("pasted-code");
  });

  it("polling and redeeming both refuse a member, and 404 an unknown flow", async () => {
    const started = (await (
      await owner.post(`${base()}/start`, { provider: "tokendance" })
    ).json()) as ModelOAuthStartResponse;
    expect((await member.get(`${base()}/${started.flowId}`)).status).toBe(403);
    expect((await member.post(`${base()}/${started.flowId}/code`, { code: "x" })).status).toBe(403);
    expect((await owner.get(`${base()}/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`)).status).toBe(
      404,
    );
  });
});

/**
 * The redirect receiver's exemption from the session gate.
 *
 * This is the desktop's whole story: the shell hands every non-app URL to
 * `shell.openExternal`, so the authorization page opens in the *system* browser, and the
 * system browser is redirected back to `http://localhost:<port>` holding no
 * `penguin_session` cookie for it. Behind the gate that was a bare 401 on every desktop
 * authorization while the browser — whose popup is a tab of the session that opened it —
 * completed fine.
 *
 * So the flow id is the credential on this one route, and these cases pin the whole of what
 * it buys. It is bounded twice over: depositing a code is all the route can do — no key
 * reaches a Project until that Project's owner polls — and the deposit itself is one
 * Project, one code, ten minutes, once, callback flows only, GET only. Everything below is
 * asserted with NO cookie unless the case is specifically about a signed-in browser.
 */
describe("model-oauth callback without a session", () => {
  /** A signed-in member of the flow's Project who is not its owner — the closest anyone gets. */
  let stranger: ReturnType<typeof apiClient>;
  let projectId: string;
  let otherProjectId: string;
  /** The provider's exchange endpoint, standing in for the global fetch. */
  let exchange: FetchFake;

  const base = (p = projectId) => `/api/projects/${p}/model-oauth`;
  /** The system browser the provider redirected: a request carrying no cookie at all. */
  const noSession = (apiPath: string, init?: RequestInit) => t.app.request(apiPath, init);
  const startFlow = async (p = projectId): Promise<string> =>
    (
      (await (
        await owner.post(`${base(p)}/start`, { provider: "tokendance" })
      ).json()) as ModelOAuthStartResponse
    ).flowId;
  const callback = (flowId: string, code = "auth-code-1", p = projectId) =>
    `${base(p)}/callback?flow=${encodeURIComponent(flowId)}&code=${code}`;
  /** What the owner's dialog asks for every two seconds — and what redeems a deposited code. */
  const poll = async (flowId: string, p = projectId): Promise<ModelOAuthStatusResponse> =>
    (await (await owner.get(`${base(p)}/${flowId}`)).json()) as ModelOAuthStatusResponse;
  /**
   * Whether any model of the group ended up with a stored key. The group's entries always
   * carry a `credential` (it holds the catalog's base URL), so only `apiKeyMasked` answers
   * the question actually being asked.
   */
  const groupHasKey = async (p = projectId): Promise<boolean> => {
    const models = (await (await owner.get(`/api/projects/${p}/models`)).json()) as ModelsResponse;
    return models.models.some(
      (m) => m.provider === "tokendance" && m.credential?.apiKeyMasked !== undefined,
    );
  };

  /** A Project of the owner's. */
  const create = async (id: string): Promise<string> =>
    (
      (await (
        await owner.post("/api/projects", { projectId: id, name: id })
      ).json()) as ProjectCreateResponse
    ).project.projectId;

  // The stranger, and another Project the owner also holds (a flow presented under it stores
  // nothing there, which no case changes), are the describe's; the flow's Project is per case.
  beforeAll(async () => {
    stranger = apiClient(t.app, (await provisionUser(t.app, "stranger_s")).cookie);
    otherProjectId = await create("owner_o-other");
  });

  let projects = 0;
  beforeEach(async () => {
    projects += 1;
    projectId = await create(`owner_o-cb_${projects}`);
    expect(
      (await owner.post(`/api/projects/${projectId}/members`, { userId: "stranger_s" })).status,
    ).toBe(201);
    exchange = stubFetch(() => jsonResponse({ key: "sk-oauth-minted-key-9911" }));
  });
  afterEach(() => {
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
  });

  it("takes the code from the system browser, which carries no cookie, and writes nothing until the owner polls", async () => {
    // The desktop path: nothing but the flow id in the URL.
    const flowId = await startFlow();
    const desktop = await noSession(callback(flowId));
    expect(desktop.status).toBe(200);
    expect(desktop.headers.get("content-type")).toContain("text/html");
    const page = await desktop.text();
    expect(page).toContain("Authorization received");
    // Says nothing but where to look, session or no session.
    expect(page).not.toContain("sk-oauth-minted-key-9911");
    expect(page).not.toContain("auth-code-1");

    // Nothing was redeemed and nothing was stored: the route has no such authority.
    expect(exchange.calls).toHaveLength(0);
    expect(await groupHasKey()).toBe(false);

    // The owner's own poll is what spends the code and lands the key.
    expect(await poll(flowId)).toEqual({
      status: "done",
      provider: "tokendance",
      applied: TOKENDANCE_MODELS,
    });
    expect(exchange.calls).toHaveLength(1);
    expect(await groupHasKey()).toBe(true);
  });

  it("still takes the redirect of a signed-in tab, which is the browser path", async () => {
    // The popup of the session that opened it was never broken and must not become so —
    // the cookie is simply not consulted here.
    const flowId = await startFlow();
    const browser = await owner.get(callback(flowId, "auth-code-2"));
    expect(browser.status).toBe(200);
    expect(await browser.text()).toContain("Authorization received");
    expect(await poll(flowId)).toEqual({
      status: "done",
      provider: "tokendance",
      applied: TOKENDANCE_MODELS,
    });
    expect(exchange.calls).toHaveLength(1);
    expect(await groupHasKey()).toBe(true);
  });

  it("lets another signed-in user deposit no more than a stranger, and land nothing", async () => {
    const flowId = await startFlow();
    // Their cookie is not consulted on this route, so their redirect is received like anyone's.
    expect((await stranger.get(callback(flowId))).status).toBe(200);
    // And that is the end of what it buys them: they cannot poll the flow, so they cannot
    // make the code they deposited become a key in someone else's Project.
    expect((await stranger.get(`${base()}/${flowId}`)).status).toBe(403);
    expect(exchange.calls).toHaveLength(0);
    expect(await groupHasKey()).toBe(false);
    // Only the owner's poll spends it.
    expect((await poll(flowId)).status).toBe("done");
    expect(await groupHasKey()).toBe(true);
  });

  it("buys nothing for a flow id that does not exist", async () => {
    const res = await noSession(callback("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"));
    expect(res.status).toBe(400);
    // The same page an expired or foreign flow gets: a flow id is not a probe for what exists.
    expect(await res.text()).toContain("Authorization failed");
    expect(exchange.calls).toHaveLength(0);
    expect(await groupHasKey()).toBe(false);
  });

  it("cannot be redirected at a Project the flow does not belong to", async () => {
    const flowId = await startFlow();
    const res = await noSession(callback(flowId, "auth-code-1", otherProjectId));
    expect(res.status).toBe(400);
    expect(exchange.calls).toHaveLength(0);
    expect(await groupHasKey(otherProjectId)).toBe(false);
    // And the flow itself is untouched — the misdirected attempt did not spend it.
    expect((await noSession(callback(flowId))).status).toBe(200);
    expect((await poll(flowId)).status).toBe("done");
    expect(await groupHasKey()).toBe(true);
  });

  it("refuses a flow past its ten-minute TTL", async () => {
    const flowId = await startFlow();
    // The service reads the clock through `Date.now()` at call time, so moving it is enough.
    const expired = Date.now() + FLOW_TTL_MS + 1;
    vi.spyOn(Date, "now").mockReturnValue(expired);
    const res = await noSession(callback(flowId));
    expect(res.status).toBe(400);
    expect(exchange.calls).toHaveLength(0);
    vi.restoreAllMocks();
    expect(await groupHasKey()).toBe(false);
  });

  it("bounds a deposited code by the same TTL: an unpolled flow expires with it", async () => {
    const flowId = await startFlow();
    expect((await noSession(callback(flowId))).status).toBe(200);
    // The dialog was closed before its next tick; the code must not outlive the flow.
    vi.spyOn(Date, "now").mockReturnValue(Date.now() + FLOW_TTL_MS + 1);
    expect((await owner.get(`${base()}/${flowId}`)).status).toBe(404);
    vi.restoreAllMocks();
    expect(exchange.calls).toHaveLength(0);
    expect(await groupHasKey()).toBe(false);
  });

  it("is single use: the redirect cannot be replayed, before or after the exchange", async () => {
    const flowId = await startFlow();
    expect((await noSession(callback(flowId))).status).toBe(200);
    // A second redirect must not overwrite the deposited code nor re-arm the exchange.
    const replay = await noSession(callback(flowId, "auth-code-2"));
    expect(replay.status).toBe(400);
    expect(await replay.text()).toContain("Authorization failed");

    expect((await poll(flowId)).status).toBe("done");
    expect((await noSession(callback(flowId))).status).toBe(400);
    // One code redeemed, one verifier spent — and it was the first code, not the replay's.
    expect(exchange.calls).toHaveLength(1);
  });

  it("deposits once when two redirects arrive together, and spends it once", async () => {
    const flowId = await startFlow();
    const both = await Promise.all([
      noSession(callback(flowId, "race-a")),
      noSession(callback(flowId, "race-b")),
    ]);
    // The deposit slot is claimed synchronously, so exactly one of them can take it.
    expect(both.map((r) => r.status).sort()).toEqual([200, 400]);
    expect((await poll(flowId)).status).toBe("done");
    expect(exchange.calls).toHaveLength(1);
  });

  it("redeems a deposited code once when two polls arrive together", async () => {
    // The single-use property lives in the exchange claim now: the verifier and the code are
    // both nulled before the first await, so overlapping polls cannot both mint a key.
    const flowId = await startFlow();
    expect((await noSession(callback(flowId))).status).toBe(200);
    const both = await Promise.all([poll(flowId), poll(flowId)]);
    expect(exchange.calls).toHaveLength(1);
    expect(both.map((r) => r.status)).toContain("done");
    for (const r of both) expect(r.status).not.toBe("error");
    expect(await groupHasKey()).toBe(true);
  });

  it("refuses the HEAD that Hono re-dispatches as a GET, leaving the flow unspent", async () => {
    const flowId = await startFlow();
    const head = await noSession(callback(flowId), { method: "HEAD" });
    expect(head.status).toBe(405);
    expect(await head.text()).toBe("");
    // A method HTTP requires to be safe changed nothing, so the real redirect still lands.
    expect((await noSession(callback(flowId))).status).toBe(200);
    expect((await poll(flowId)).status).toBe("done");
    expect(exchange.calls).toHaveLength(1);
    expect(await groupHasKey()).toBe(true);
  });

  it("has no redirect to receive for a flow that chose manual mode", async () => {
    const started = (await (
      await owner.post(`${base()}/start`, { provider: "tokendance", mode: "manual" })
    ).json()) as ModelOAuthStartResponse;
    // The deployment opted out: no callback URL was ever handed to the provider.
    expect(new URL(started.authorizeUrl).searchParams.has("callback_url")).toBe(false);

    const res = await noSession(callback(started.flowId));
    expect(res.status).toBe(400);
    expect(await res.text()).toContain("Authorization failed");
    expect(exchange.calls).toHaveLength(0);
    expect(await groupHasKey()).toBe(false);

    // The paste box that mode did opt into still redeems it.
    expect((await owner.post(`${base()}/${started.flowId}/code`, { code: "pasted" })).status).toBe(
      200,
    );
    expect(exchange.calls).toHaveLength(1);
    expect(await groupHasKey()).toBe(true);
  });

  it("exempts exactly this literal path, and nothing around it", async () => {
    const flowId = await startFlow();
    // GET on the literal path is the exemption — and it beats the `:flowId` status route,
    // which would otherwise match "callback" and answer JSON from behind the gate.
    const literal = await noSession(`${base()}/callback`);
    expect(literal.status).toBe(400);
    expect(literal.headers.get("content-type")).toContain("text/html");
    // Everything adjacent is still gated: a longer path, another method, the sibling routes.
    expect((await noSession(`${base()}/callback/extra`)).status).toBe(401);
    expect((await noSession(`${base()}/callback`, { method: "POST" })).status).toBe(401);
    expect((await noSession(`${base()}/start`, { method: "POST" })).status).toBe(401);
    expect((await noSession(`${base()}/${flowId}`)).status).toBe(401);
    expect((await noSession(`${base()}/${flowId}/code`, { method: "POST" })).status).toBe(401);
    expect(exchange.calls).toHaveLength(0);
  });
});