Testing authentication

import { createHash, randomBytes } from "node:crypto";

const REDIRECT_URI = "http://localhost:3000/callback";

/**
 * Signs in to a local or remote server as a user's browser does, following
 * every redirect and keeping cookies, and returns the token response.
 * `fields` fill in local mode's sign-in form. Without `clientId`, it registers a client;
 * a CIMD client passes its metadata URL instead.
 */
export async function signIn(baseUrl: string, fields: Record<string, string> = {}, scope?: string, clientId?: string) {
  const cookies = new Map<string, string>();
  const send = async (url: string, init: RequestInit = {}) => {
    const headers = new Headers(init.headers);
    if (cookies.size) headers.set("cookie", [...cookies].map(([name, value]) => `${name}=${value}`).join("; "));
    const response = await fetch(url, { ...init, headers, redirect: "manual" });
    for (const cookie of response.headers.getSetCookie()) {
      const [pair] = cookie.split(";");
      const name = pair.slice(0, pair.indexOf("="));
      const value = pair.slice(pair.indexOf("=") + 1);
      if (value) cookies.set(name, value);
      else cookies.delete(name);
    }
    return response;
  };

  // Register a client, unless a CIMD client's metadata URL was given, and make a PKCE verifier and its challenge.
  let client_id = clientId;
  if (!client_id) {
    const registration = await send(`${baseUrl}/oauth/register`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ client_name: "tests", redirect_uris: [REDIRECT_URI] }),
    });
    client_id = (await registration.json()).client_id as string;
  }
  const verifier = randomBytes(32).toString("base64url");
  const challenge = createHash("sha256").update(verifier).digest("base64url");

  const query = new URLSearchParams({
    response_type: "code",
    client_id,
    redirect_uri: REDIRECT_URI,
    code_challenge: challenge,
    code_challenge_method: "S256",
    state: "test",
    ...(scope ? { scope } : {}),
  });
  let response = await send(`${baseUrl}/oauth/authorize?${query}`);

  for (let step = 0; step < 10; step++) {
    const location = response.headers.get("location");
    if (location?.startsWith(REDIRECT_URI)) {
      // Back at the client, with a code: trade it for tokens.
      const code = new URL(location).searchParams.get("code");
      if (!code) throw new Error(`Sign-in failed: ${location}`);
      const tokens = await send(`${baseUrl}/oauth/token`, {
        method: "POST",
        headers: { "content-type": "application/x-www-form-urlencoded" },
        body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: REDIRECT_URI, client_id, code_verifier: verifier }),
      });
      return tokens.json();
    }
    if (location) {
      response = await send(new URL(location, response.url).toString());
      continue;
    }
    // Local mode's sign-in page: submit its form.
    const page = await response.text();
    const pendingAuthId = page.match(/name="pending_auth_id" value="([^"]+)"/)?.[1];
    if (response.status !== 200 || !pendingAuthId) {
      const text = page.replace(/<style[^]*?<\/style>/, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
      throw new Error(`Sign-in stopped with ${response.status}: ${text.slice(0, 300)}`);
    }
    response = await send(`${baseUrl}/oauth/callback`, {
      method: "POST",
      headers: { "content-type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ pending_auth_id: pendingAuthId, ...fields }),
    });
  }
  throw new Error("Sign-in didn't finish in 10 steps");
}

import { App, PublicMcpError, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "whoami", description: "Who is calling", inputSchema: {} })
export class WhoAmI extends ToolContext {
  async execute() {
    const { user, isAnonymous } = this.auth;
    return { sub: user.sub, email: user.email ?? null, anonymous: isAnonymous };
  }
}

@Tool({ name: "close_ticket", description: "Close a ticket. Needs tickets:write.", inputSchema: { id: z.string() } })
export class CloseTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    if (!this.auth.hasScope("tickets:write")) this.fail(new PublicMcpError("Closing tickets needs tickets:write."));
    return { closed: id, by: this.auth.user.sub };
  }
}

@App({ name: "help-desk", tools: [WhoAmI, CloseTicket] })
export class HelpDesk {}

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  http: { port: Number(process.env.PORT ?? 3000) },
  auth: { mode: "local", allowedScopes: ["tickets:read", "tickets:write"] },
})
export default class Server {}

import { test, expect } from "@frontmcp/testing";

test.use({ server: "./src/main.ts", env: { JWT_SECRET: "a-test-secret-of-at-least-32-bytes!!" } });

test("tools see the user the token names", async ({ server, auth }) => {
  const token = await auth.createToken({ sub: "agent-1", email: "nour@acme.dev", scopes: ["tickets:write"] });
  const nour = await server.createClient({ token });
  try {
    expect((await nour.tools.call("whoami")).json()).toEqual({ sub: "agent-1", email: "nour@acme.dev", anonymous: false });
    expect((await nour.tools.call("close_ticket", { id: "T-1" })).json()).toEqual({ closed: "T-1", by: "agent-1" });
  } finally {
    await nour.disconnect();
  }
});

test("a token without tickets:write can't close tickets", async ({ server, auth }) => {
  const lin = await server.createClient({ token: await auth.createToken({ sub: "agent-2", scopes: ["tickets:read"] }) });
  try {
    const result = await lin.tools.call("close_ticket", { id: "T-1" });
    expect(result).toBeError();
    expect(result.text()).toBe("Closing tickets needs tickets:write.");
  } finally {
    await lin.disconnect();
  }
});

test("the built-in users", async ({ server, auth }) => {
  const readOnly = await server.createClient({ token: await auth.createToken(auth.users.readOnly) });
  try {
    expect((await readOnly.tools.call("whoami")).json()).toMatchObject({ sub: "readonly-001", email: "readonly@test.local" });
  } finally {
    await readOnly.disconnect();
  }
});

import { test, expect } from "@frontmcp/testing";

test.use({ server: "./src/main.ts", env: { JWT_SECRET: "a-test-secret-of-at-least-32-bytes!!" } });

const refused = "HTTP 401: Unauthorized";

test("no token", async ({ server }) => {
  await expect(server.createClient()).rejects.toThrow(refused);
});

test("an expired token", async ({ server, auth }) => {
  await expect(server.createClient({ token: await auth.createExpiredToken({ sub: "agent-1" }) })).rejects.toThrow(refused);
});

test("a token with a bad signature", async ({ server, auth }) => {
  await expect(server.createClient({ token: auth.createInvalidToken({ sub: "agent-1" }) })).rejects.toThrow(refused);
});

test("a token for another server", async ({ server, auth }) => {
  const token = await auth.createToken({ sub: "agent-1", claims: { aud: "https://other-desk.example.com" } });
  await expect(server.createClient({ token })).rejects.toThrow(refused);
});

test("a token that expires during the test", async ({ server, auth }) => {
  const client = await server.createClient({ token: await auth.createToken({ sub: "agent-1", expiresIn: 2 }) });
  try {
    expect(await client.tools.call("whoami")).toBeSuccessful();
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const result = await client.tools.call("whoami");
    expect(result.error).toMatchObject({ code: -32000, message: refused });
  } finally {
    await client.disconnect();
  }
});

import { test, expect } from "@frontmcp/testing";

// src/static.ts has auth: { mode: "static", tokens: [process.env.DESK_KEY!] }
test.use({ server: "./src/static.ts", env: { DESK_KEY: "desk-key-1" } });

test("the key is accepted", async ({ server }) => {
  const client = await server.createClient({ token: "desk-key-1" });
  try {
    expect((await client.tools.call("whoami")).json()).toMatchObject({ anonymous: false });
  } finally {
    await client.disconnect();
  }
});

test("another key isn't", async ({ server }) => {
  await expect(server.createClient({ token: "desk-key-2" })).rejects.toThrow("HTTP 401: Unauthorized");
});

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  http: { port: Number(process.env.PORT ?? 3000) },
  auth: {
    mode: "transparent",
    provider: process.env.IDP_URL!,
    expectedAudience: "https://desk.example.com",
  },
})
export default class Server {}

import { test, expect, MockOAuthServer, TestTokenFactory } from "@frontmcp/testing";

const IDP_URL = "http://localhost:50900";
const tokens = new TestTokenFactory({ issuer: IDP_URL, audience: "https://desk.example.com" });
const idp = new MockOAuthServer(tokens, { port: 50900 });

test.use({ server: "./src/transparent.ts", env: { IDP_URL } });
test.beforeAll(() => idp.start());
test.afterAll(() => idp.stop());

test("a token from the provider is accepted", async ({ server }) => {
  const token = await tokens.createTestToken({ sub: "sso|nour", scopes: ["tickets:write"], claims: { email: "nour@acme.dev" } });
  const nour = await server.createClient({ token });
  try {
    expect((await nour.tools.call("whoami")).json()).toEqual({ sub: "sso|nour", email: "nour@acme.dev", anonymous: false });
    expect(await nour.tools.call("close_ticket", { id: "T-1" })).toBeSuccessful();
  } finally {
    await nour.disconnect();
  }
});

test("tokens the provider didn't sign, or not for this server, are refused", async ({ server, auth }) => {
  const refused = "HTTP 401: Unauthorized";
  // The auth fixture signs with a key of its own, which the provider doesn't publish
  await expect(server.createClient({ token: await auth.createToken({ sub: "sso|nour" }) })).rejects.toThrow(refused);
  await expect(server.createClient({ token: await tokens.createExpiredToken({ sub: "sso|nour" }) })).rejects.toThrow(refused);
  await expect(
    server.createClient({ token: await tokens.createTestToken({ sub: "sso|nour", aud: "https://other-desk.example.com" }) }),
  ).rejects.toThrow(refused);
});

import { test, expect } from "@frontmcp/testing";
import { signIn } from "./sign-in";

test.use({ server: "./src/main.ts", env: { JWT_SECRET: "a-test-secret-of-at-least-32-bytes!!" } });

test("signing in with the built-in page", async ({ server }) => {
  const tokens = await signIn(server.info.baseUrl, { email: "nour@acme.dev", name: "Nour" }, "tickets:write");
  expect(tokens).toMatchObject({ token_type: "Bearer", scope: "tickets:write" });

  const nour = await server.createClient({ token: tokens.access_token });
  try {
    expect((await nour.tools.call("whoami")).json()).toMatchObject({ email: "nour@acme.dev", anonymous: false });
    expect(await nour.tools.call("close_ticket", { id: "T-1" })).toBeSuccessful();
  } finally {
    await nour.disconnect();
  }
});

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";

const idp = process.env.IDP_URL!;

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  http: { port: Number(process.env.PORT ?? 3000) },
  auth: {
    mode: "remote",
    provider: idp,
    clientId: "help-desk-mcp",
    scopes: ["openid", "profile", "email"],
    providerConfig: { id: "idp", authEndpoint: `${idp}/oauth/authorize`, tokenEndpoint: `${idp}/oauth/token` },
  },
})
export default class Server {}

import { test, expect, MockOAuthServer, TestTokenFactory } from "@frontmcp/testing";
import { signIn } from "./sign-in";

const IDP_URL = "http://localhost:50901";
const idp = new MockOAuthServer(new TestTokenFactory({ issuer: IDP_URL, audience: "help-desk-mcp" }), {
  port: 50901,
  autoApprove: true,
  testUser: { sub: "sso|nour", email: "nour@acme.dev", name: "Nour" },
  clientId: "help-desk-mcp",
});

test.use({ server: "./src/remote.ts", env: { IDP_URL, JWT_SECRET: "a-test-secret-of-at-least-32-bytes!!" } });
test.beforeAll(() => idp.start());
test.afterAll(() => idp.stop());

test("signing in through the provider", async ({ server }) => {
  const tokens = await signIn(server.info.baseUrl);
  const nour = await server.createClient({ token: tokens.access_token });
  try {
    expect((await nour.tools.call("whoami")).json()).toEqual({ sub: "sso|nour", email: "nour@acme.dev", anonymous: false });
  } finally {
    await nour.disconnect();
  }
});

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  http: { port: Number(process.env.PORT ?? 3000) },
  auth: {
    mode: "local",
    allowedScopes: ["tickets:read", "tickets:write"],
    // Lets a client publish its document at http://localhost, as MockCimdServer does. Tests only.
    cimd: { security: { allowInsecureForTesting: process.env.CIMD_ON_LOCALHOST === "1" } },
  },
})
export default class Server {}

import { test, expect, MockCimdServer } from "@frontmcp/testing";
import { signIn } from "./sign-in";

const clients = new MockCimdServer();

test.use({ server: "./src/cimd.ts", env: { CIMD_ON_LOCALHOST: "1", JWT_SECRET: "a-test-secret-of-at-least-32-bytes!!" } });
test.beforeAll(() => clients.start());
test.afterAll(() => clients.stop());

test("a client signs in with its metadata URL as client_id", async ({ server }) => {
  const clientId = clients.registerClient({ name: "Notes Desktop" });
  expect(clientId).toBe(`${clients.info.baseUrl}/clients/notes-desktop/metadata.json`);

  const tokens = await signIn(server.info.baseUrl, { email: "nour@acme.dev" }, "tickets:write", clientId);
  const nour = await server.createClient({ token: tokens.access_token });
  try {
    expect((await nour.tools.call("whoami")).json()).toMatchObject({ email: "nour@acme.dev", anonymous: false });
  } finally {
    await nour.disconnect();
  }
});

test("a redirect URI the document doesn't list is refused", async ({ server }) => {
  const clientId = clients.registerClient({ name: "Notes Web", redirectUris: ["https://notes.example.com/callback"] });
  await expect(signIn(server.info.baseUrl, { email: "nour@acme.dev" }, undefined, clientId)).rejects.toThrow("is not registered for client");
});

test("a document that can't be fetched, or isn't valid, is refused", async ({ server }) => {
  const { baseUrl } = clients.info;
  clients.registerFetchError("/clients/gone/metadata.json", 500);
  await expect(signIn(server.info.baseUrl, {}, undefined, `${baseUrl}/clients/gone/metadata.json`)).rejects.toThrow(
    "Failed to fetch CIMD document",
  );

  // No client_name
  clients.registerInvalidDocument("/clients/nameless/metadata.json", {
    client_id: `${baseUrl}/clients/nameless/metadata.json`,
    redirect_uris: ["http://localhost:3000/callback"],
  });
  await expect(signIn(server.info.baseUrl, {}, undefined, `${baseUrl}/clients/nameless/metadata.json`)).rejects.toThrow(
    "CIMD document validation failed: client_name",
  );
});