Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

Add hosted MCP activity and OAuth revocation (#3973)

Himadri Mishra4f8c82f0762c
diff --git a/apps/api/.env.example b/apps/api/.env.example
index 7272572ed..90fdab093 100644
--- a/apps/api/.env.example
+++ b/apps/api/.env.example
@@ -11,6 +11,15 @@ USE_DB_AUTHENTICATION=true
# ===== Optional ENVS ======
+# Hosted MCP metadata-only activity storage and ingestion. Keep disabled until
+# its table exists; writes additionally require the shared MCP-sidecar secret.
+MCP_ACTION_LOG_STORAGE_ENABLED=false
+MCP_ACTION_LOG_WRITES_ENABLED=false
+MCP_ACTION_LOG_SECRET=
+# Shared only between the hosted MCP signer and Core verifier. Use 32+ random
+# characters and do not reuse KEYLESS_PROXY_SECRET.
+MCP_DELEGATED_CREDENTIAL_SECRET=
+
# SearchApi key. Head to https://searchapi.com/ to get your API key
SEARCHAPI_API_KEY=
# SearchApi engine, defaults to google. Available options: google, bing, baidu, google_news, etc. Head to https://searchapi.com/ to explore more engines
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 63c66a047..e29e1dbac 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -1,5 +1,6 @@
import "dotenv/config";
import { z } from "zod";
+import { getMcpActionLogConfigErrors } from "./lib/mcp-action-log-config";
/* Codecs */
const delimitedList = (separator = ",") => {
@@ -43,6 +44,10 @@ const configSchema = z.object({
// forward the real client IP for keyless rate-limiting via the
// `x-firecrawl-keyless-ip` header. Untrusted callers can't override their IP.
KEYLESS_PROXY_SECRET: z.string().optional(),
+ // Dedicated signer/verifier secret for short-lived MCP delegated credentials.
+ // Keep separate from KEYLESS_PROXY_SECRET because delegated credentials can
+ // authorize billed requests for a managed OAuth connection.
+ MCP_DELEGATED_CREDENTIAL_SECRET: emptyStringAsUndefined(z.string().min(32)),
// Optional Spur Context API token (https://docs.spur.us/context-api). When
// set, keyless requests have their client IP checked against Spur and are
// refused if the IP fronts anonymizing/rotating infrastructure (VPN/proxy/
@@ -102,6 +107,9 @@ const configSchema = z.object({
// OAuth token introspection
OAUTH_INTROSPECT_URL: z.string().optional(),
OAUTH_INTROSPECT_SECRET: z.string().optional(),
+ MCP_ACTION_LOG_SECRET: z.string().optional(),
+ MCP_ACTION_LOG_STORAGE_ENABLED: z.stringbool().default(false),
+ MCP_ACTION_LOG_WRITES_ENABLED: z.stringbool().default(false),
// Agent auth discovery (RFC 9728 WWW-Authenticate on 401)
AGENT_AUTH_RESOURCE_METADATA_URL: z
@@ -389,4 +397,14 @@ const configSchema = z.object({
CODE_SANDBOX_URL: z.string().default("ws://code-sandbox:3001"),
});
-export const config = configSchema.parse(process.env);
+const validatedConfigSchema = configSchema.superRefine((value, context) => {
+ for (const error of getMcpActionLogConfigErrors(value)) {
+ context.addIssue({
+ code: "custom",
+ path: [error.path],
+ message: error.message,
+ });
+ }
+});
+
+export const config = validatedConfigSchema.parse(process.env);
diff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.ts
index fdf0c0664..c888c016c 100644
--- a/apps/api/src/controllers/__tests__/auth.test.ts
+++ b/apps/api/src/controllers/__tests__/auth.test.ts
@@ -1,7 +1,17 @@
import { vi } from "vitest";
-import { authenticateUser } from "../auth";
+import { createHmac } from "node:crypto";
+import { authenticateUser, clearACUC } from "../auth";
import { config } from "../../config";
import { RateLimiterMode } from "../../types";
+import { authCreditUsageChunk } from "../../db/rpc";
+import { redlock } from "../../services/redlock";
+import { deleteKey, getValue, setValue } from "../../services/redis";
+import {
+ getAutumnRateLimiter,
+ getRateLimiter,
+} from "../../services/rate-limiter";
+import { db } from "../../db/connection";
+import { autumnService } from "../../services/autumn/autumn.service";
vi.mock("../../services/queue-service", () => ({
getRedisConnection: vi.fn(() => ({
@@ -37,6 +47,13 @@ vi.mock("../../db/rpc", () => ({
vi.mock("../../services/rate-limiter", () => ({
getRateLimiter: vi.fn(),
+ getAutumnRateLimiter: vi.fn(),
+}));
+
+vi.mock("../../services/autumn/autumn.service", () => ({
+ autumnService: {
+ getRateLimitMultiplier: vi.fn(),
+ },
}));
vi.mock("../../services/agent-sponsor", () => ({
@@ -45,11 +62,51 @@ vi.mock("../../services/agent-sponsor", () => ({
describe("authenticateUser", () => {
const originalUseDbAuth = config.USE_DB_AUTHENTICATION;
+ const originalKeylessProxySecret = config.KEYLESS_PROXY_SECRET;
+ const originalMcpDelegatedCredentialSecret =
+ config.MCP_DELEGATED_CREDENTIAL_SECRET;
+ const originalIntrospectUrl = config.OAUTH_INTROSPECT_URL;
+ const originalIntrospectSecret = config.OAUTH_INTROSPECT_SECRET;
+
+ beforeEach(() => {
+ vi.mocked(autumnService.getRateLimitMultiplier).mockResolvedValue(1);
+ vi.mocked(getAutumnRateLimiter).mockReturnValue({
+ consume: vi.fn().mockResolvedValue(undefined),
+ } as never);
+ });
afterEach(() => {
config.USE_DB_AUTHENTICATION = originalUseDbAuth;
+ config.KEYLESS_PROXY_SECRET = originalKeylessProxySecret;
+ config.MCP_DELEGATED_CREDENTIAL_SECRET =
+ originalMcpDelegatedCredentialSecret;
+ config.OAUTH_INTROSPECT_URL = originalIntrospectUrl;
+ config.OAUTH_INTROSPECT_SECRET = originalIntrospectSecret;
+ vi.unstubAllGlobals();
+ vi.clearAllMocks();
});
+ const signDelegation = (
+ overrides: Record<string, unknown> = {},
+ secret = "mcp-delegation-secret",
+ ) => {
+ const now = Math.floor(Date.now() / 1000);
+ const payload = {
+ v: 1,
+ aud: "firecrawl-core",
+ purpose: "hosted_mcp_oauth",
+ api_key: "fc-11111111111111118111111111111111",
+ iat: now,
+ exp: now + 60,
+ ...overrides,
+ };
+ const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+ const signature = createHmac("sha256", secret)
+ .update(encoded)
+ .digest("base64url");
+ return `fcmcp_${encoded}.${signature}`;
+ };
+
it("keeps a mock ACUC chunk in no-auth mode", async () => {
config.USE_DB_AUTHENTICATION = false;
@@ -71,4 +128,293 @@ describe("authenticateUser", () => {
}),
);
});
+
+ it("writes normal API-key ACUC entries to the general-purpose cache", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ vi.mocked(getValue).mockResolvedValue(null);
+ vi.mocked(authCreditUsageChunk).mockResolvedValue([
+ {
+ api_key: "00000000-0000-4000-8000-000000000000",
+ api_key_id: 1,
+ team_id: "team-1",
+ org_id: "org-1",
+ rate_limits: { scrape: 10 },
+ plan_priority: {},
+ concurrency: 2,
+ flags: null,
+ },
+ ]);
+ vi.mocked(redlock.using).mockImplementation(
+ async (_keys, _ttl, _options, fn) => fn({ aborted: false } as never),
+ );
+ vi.mocked(getRateLimiter).mockReturnValue({
+ consume: vi.fn().mockResolvedValue(undefined),
+ } as never);
+
+ const auth = await authenticateUser(
+ {
+ headers: {
+ authorization: "Bearer 00000000-0000-4000-8000-000000000000",
+ },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(auth.success).toBe(true);
+ await vi.waitFor(() =>
+ expect(setValue).toHaveBeenCalledWith(
+ "acuc_general_00000000-0000-4000-8000-000000000000_scrape",
+ expect.any(String),
+ 600,
+ true,
+ ),
+ );
+ });
+
+ it("accepts a signed MCP delegation through the managed credential purpose without caching", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.MCP_DELEGATED_CREDENTIAL_SECRET = "mcp-delegation-secret";
+ vi.mocked(authCreditUsageChunk).mockResolvedValue([
+ {
+ api_key: "11111111-1111-1111-8111-111111111111",
+ api_key_id: 1,
+ team_id: "team-1",
+ org_id: "org-1",
+ rate_limits: { crawl: 10 },
+ plan_priority: {},
+ concurrency: 2,
+ flags: null,
+ },
+ ]);
+ vi.mocked(autumnService.getRateLimitMultiplier).mockResolvedValue(1);
+ vi.mocked(getAutumnRateLimiter).mockReturnValue({
+ consume: vi.fn().mockResolvedValue(undefined),
+ } as never);
+
+ const auth = await authenticateUser(
+ {
+ headers: { authorization: `Bearer ${signDelegation()}` },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Crawl,
+ );
+
+ expect(auth).toEqual(
+ expect.objectContaining({ success: true, team_id: "team-1" }),
+ );
+ expect(authCreditUsageChunk).toHaveBeenCalledWith(
+ db,
+ "11111111-1111-1111-8111-111111111111",
+ "hosted_mcp_oauth",
+ );
+ expect(getValue).not.toHaveBeenCalled();
+ expect(setValue).not.toHaveBeenCalled();
+ });
+
+ it("returns 503 rather than 401 when OAuth introspection is unavailable", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.OAUTH_INTROSPECT_URL = "https://example.test/introspect";
+ config.OAUTH_INTROSPECT_SECRET = "secret";
+ vi.mocked(getValue).mockResolvedValue(null);
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(
+ new Response(JSON.stringify({ error: "temporarily_unavailable" }), {
+ status: 503,
+ headers: { "Content-Type": "application/json" },
+ }),
+ ),
+ );
+
+ const auth = await authenticateUser(
+ {
+ headers: { authorization: "Bearer fco_access_token" },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(auth).toEqual({
+ success: false,
+ error: "OAuth authentication is temporarily unavailable",
+ status: 503,
+ });
+ expect(authCreditUsageChunk).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ["a missing shared secret", undefined, signDelegation()],
+ ["a wrong signature", "mcp-delegation-secret", signDelegation({}, "wrong")],
+ [
+ "an expired assertion",
+ "mcp-delegation-secret",
+ signDelegation({ exp: Math.floor(Date.now() / 1000) }),
+ ],
+ ])("rejects an MCP delegation with %s", async (_label, secret, token) => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.MCP_DELEGATED_CREDENTIAL_SECRET = secret;
+
+ const auth = await authenticateUser(
+ {
+ headers: { authorization: `Bearer ${token}` },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Crawl,
+ );
+
+ expect(auth).toEqual({
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ });
+ expect(authCreditUsageChunk).not.toHaveBeenCalled();
+ });
+
+ it("treats malformed ACUC cache JSON as a miss", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ vi.mocked(getValue).mockResolvedValue("{not-json");
+ vi.mocked(deleteKey).mockResolvedValue(undefined);
+ vi.mocked(authCreditUsageChunk).mockResolvedValue([]);
+
+ const auth = await authenticateUser(
+ {
+ headers: {
+ authorization: "Bearer 00000000-0000-4000-8000-000000000000",
+ },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(auth).toEqual({
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ });
+ expect(authCreditUsageChunk).toHaveBeenCalledWith(
+ expect.anything(),
+ "00000000-0000-4000-8000-000000000000",
+ "general",
+ );
+ await vi.waitFor(() =>
+ expect(deleteKey).toHaveBeenCalledWith(
+ "acuc_general_00000000-0000-4000-8000-000000000000_scrape",
+ ),
+ );
+ });
+
+ it("rejects a managed OAuth credential on the public REST token path", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.OAUTH_INTROSPECT_URL = "https://example.test/introspect";
+ config.OAUTH_INTROSPECT_SECRET = "secret";
+ vi.mocked(getValue).mockResolvedValue(null);
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(
+ new Response(
+ JSON.stringify({
+ active: true,
+ api_key: "fc-11111111111111118111111111111111",
+ scope: "firecrawl:global",
+ client_id: "client-1",
+ team_id: "team-1",
+ exp: Math.floor(Date.now() / 1000) + 60,
+ aud: "https://api.firecrawl.dev/",
+ credential_purpose: "hosted_mcp_oauth",
+ }),
+ { status: 200, headers: { "Content-Type": "application/json" } },
+ ),
+ ),
+ );
+
+ const auth = await authenticateUser(
+ {
+ headers: { authorization: "Bearer fco_managed_token" },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(auth).toEqual({
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ });
+ expect(authCreditUsageChunk).not.toHaveBeenCalled();
+ });
+
+ it("rejects OAuth introspection and ACUC results for different teams", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.OAUTH_INTROSPECT_URL = "https://example.test/introspect";
+ config.OAUTH_INTROSPECT_SECRET = "secret";
+ vi.mocked(getValue).mockResolvedValue(null);
+ vi.mocked(authCreditUsageChunk).mockResolvedValue([
+ {
+ api_key: "11111111-1111-1111-8111-111111111111",
+ api_key_id: 1,
+ team_id: "team-2",
+ org_id: "org-2",
+ rate_limits: { scrape: 10 },
+ plan_priority: {},
+ concurrency: 2,
+ flags: null,
+ },
+ ]);
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(
+ new Response(
+ JSON.stringify({
+ active: true,
+ api_key: "fc-11111111111111118111111111111111",
+ scope: "firecrawl:global",
+ client_id: "client-1",
+ team_id: "team-1",
+ exp: Math.floor(Date.now() / 1000) + 60,
+ aud: "https://api.firecrawl.dev/",
+ credential_purpose: "general",
+ }),
+ { status: 200, headers: { "Content-Type": "application/json" } },
+ ),
+ ),
+ );
+
+ const auth = await authenticateUser(
+ {
+ headers: { authorization: "Bearer fco_general_token" },
+ socket: { remoteAddress: "127.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(auth).toEqual({
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ });
+ });
+
+ it("clears purpose-qualified and legacy ACUC cache entries", async () => {
+ await clearACUC("api-key");
+
+ expect(vi.mocked(deleteKey).mock.calls.map(([key]) => key)).toEqual(
+ expect.arrayContaining([
+ "acuc_api-key_extract",
+ "acuc_api-key_scrape",
+ "acuc_general_api-key_extract",
+ "acuc_general_api-key_scrape",
+ "acuc_hosted_mcp_oauth_api-key_extract",
+ "acuc_hosted_mcp_oauth_api-key_scrape",
+ "acuc_api-key",
+ ]),
+ );
+ });
});
diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.ts
index 043d79772..2c2c80b40 100644
--- a/apps/api/src/controllers/auth.ts
+++ b/apps/api/src/controllers/auth.ts
@@ -1,4 +1,3 @@
-import * as crypto from "crypto";
import { RateLimiterRedis } from "rate-limiter-flexible";
import { isValidUuid } from "../lib/owner-id";
import { config } from "../config";
@@ -27,6 +26,13 @@ import {
} from "../db/rpc";
import { AuthResponse, RateLimiterMode } from "../types";
import { AuthCreditUsageChunk, AuthCreditUsageChunkFromTeam } from "./v1/types";
+import {
+ FIRECRAWL_REST_RESOURCE,
+ OAuthIntrospectionUnavailableError,
+ resolveOAuthToken as resolveOAuthTokenWithIntrospection,
+} from "../services/oauth-token-introspection";
+import type { OAuthIntrospectionResponse } from "../services/oauth-token-introspection";
+import { verifyMcpDelegatedCredential } from "../lib/mcp-delegated-credential";
import { autumnService } from "../services/autumn/autumn.service";
function normalizedApiIsUuid(potentialUuid: string): boolean {
@@ -41,8 +47,9 @@ async function setCachedACUC(
| AuthCreditUsageChunk
| null
| ((acuc: AuthCreditUsageChunk) => AuthCreditUsageChunk | null),
+ credentialPurpose: "general" | "hosted_mcp_oauth" = "general",
) {
- const cacheKeyACUC = `acuc_${api_key}_${is_extract ? "extract" : "scrape"}`;
+ const cacheKeyACUC = `acuc_${credentialPurpose}_${api_key}_${is_extract ? "extract" : "scrape"}`;
const redLockKey = `lock_${cacheKeyACUC}`;
try {
@@ -126,18 +133,6 @@ const mockACUC: () => AuthCreditUsageChunk = () => ({
is_extract: false,
});
-/**
- * Introspection response from the OAuth token endpoint.
- */
-interface OAuthIntrospectionResponse {
- active: boolean;
- api_key: string;
- scope: string;
- client_id: string;
- team_id: string;
- exp: number;
-}
-
/**
* Resolve an OAuth access token (fco_…) to the underlying API key via
* the introspection endpoint. Results are cached in Redis for the
@@ -153,66 +148,16 @@ async function resolveOAuthToken(
logger.warn(
"OAuth introspection not configured (OAUTH_INTROSPECT_URL / OAUTH_INTROSPECT_SECRET)",
);
- return null;
- }
-
- // Check Redis cache first (hash the token to avoid leaking material in key names)
- const tokenHash = crypto
- .createHash("sha256")
- .update(token)
- .digest("hex")
- .substring(0, 32);
- const cacheKey = `oauth_token:${tokenHash}`;
- const cached = await getValue(cacheKey);
- if (cached !== null) {
- try {
- const parsed = JSON.parse(cached);
- if (!parsed.active) return null;
- return parsed;
- } catch {
- // Corrupt cache entry — treat as a miss
- }
+ throw new OAuthIntrospectionUnavailableError(
+ "OAuth introspection is not configured",
+ );
}
- try {
- const response = await fetch(introspectUrl, {
- method: "POST",
- headers: {
- "Content-Type": "application/json",
- Authorization: `Bearer ${introspectSecret}`,
- },
- body: JSON.stringify({ token }),
- });
-
- if (!response.ok) {
- logger.error("OAuth introspection request failed", {
- status: response.status,
- });
- return null;
- }
-
- const data = (await response.json()) as OAuthIntrospectionResponse;
-
- // Cache the result — use remaining TTL (max 5 minutes) or 60s for inactive
- if (data.active) {
- const remainingSeconds = Math.max(
- 0,
- data.exp - Math.floor(Date.now() / 1000),
- );
- const cacheTtl = Math.min(remainingSeconds, 300); // Cap at 5 minutes
- if (cacheTtl > 0) {
- await setValue(cacheKey, JSON.stringify(data), cacheTtl);
- }
- } else {
- // Cache negative results briefly to avoid hammering introspection
- await setValue(cacheKey, JSON.stringify({ active: false }), 60);
- }
-
- return data.active ? data : null;
- } catch (error) {
- logger.error("OAuth introspection error", { error });
- return null;
- }
+ return resolveOAuthTokenWithIntrospection(token, {
+ introspectUrl,
+ introspectSecret,
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ });
}
async function getACUC(
@@ -220,7 +165,15 @@ async function getACUC(
cacheOnly = false,
useCache = true,
mode?: RateLimiterMode,
+ credentialPurpose: "general" | "hosted_mcp_oauth" = "general",
): Promise<AuthCreditUsageChunk | null> {
+ // Managed OAuth credentials are connection-scoped and can be created or
+ // revoked immediately before this request. Never serve them from Redis or a
+ // lagging read replica: both authorization and revocation must observe the
+ // primary database.
+ const requiresPrimaryRead = credentialPurpose === "hosted_mcp_oauth";
+ if (requiresPrimaryRead) useCache = false;
+
let isExtract =
mode === RateLimiterMode.Extract ||
mode === RateLimiterMode.ExtractStatus ||
@@ -238,12 +191,25 @@ async function getACUC(
return acuc;
}
- const cacheKeyACUC = `acuc_${api_key}_${isExtract ? "extract" : "scrape"}`;
+ const cacheKeyACUC = `acuc_${credentialPurpose}_${api_key}_${isExtract ? "extract" : "scrape"}`;
if (useCache) {
const cachedACUC = await getValue(cacheKeyACUC);
if (cachedACUC !== null) {
- return JSON.parse(cachedACUC);
+ try {
+ return JSON.parse(cachedACUC);
+ } catch (error) {
+ logger.warn("Ignoring malformed ACUC cache entry", {
+ cacheKey: cacheKeyACUC,
+ error,
+ });
+ void deleteKey(cacheKeyACUC).catch(deleteError => {
+ logger.warn("Failed to delete malformed ACUC cache entry", {
+ cacheKey: cacheKeyACUC,
+ error: deleteError,
+ });
+ });
+ }
}
}
@@ -252,9 +218,13 @@ async function getACUC(
let retries = 0;
const maxRetries = 5;
while (retries < maxRetries) {
- const database = Math.random() > 2 / 3 ? dbRr : db;
+ const database = requiresPrimaryRead
+ ? db
+ : Math.random() > 2 / 3
+ ? dbRr
+ : db;
try {
- data = await authCreditUsageChunk(database, api_key);
+ data = await authCreditUsageChunk(database, api_key, credentialPurpose);
break;
} catch (error) {
logger.warn(
@@ -287,7 +257,7 @@ async function getACUC(
// NOTE: Should we cache null chunks? - mogery
if (chunk !== null && useCache) {
- setCachedACUC(api_key, isExtract, chunk);
+ setCachedACUC(api_key, isExtract, chunk, credentialPurpose);
}
return chunk;
@@ -413,13 +383,19 @@ export async function getACUCTeam(
}
export async function clearACUC(api_key: string): Promise<void> {
- // Delete cache for all rate limiter modes
+ // Clear both purpose-qualified keys and the legacy unqualified keys during
+ // rollout so credential-purpose isolation cannot leave stale auth entries.
const modes = [true, false];
+ const credentialPurposes = ["general", "hosted_mcp_oauth"] as const;
await Promise.all(
- modes.map(async mode => {
- const cacheKey = `acuc_${api_key}_${mode ? "extract" : "scrape"}`;
- await deleteKey(cacheKey);
- }),
+ modes.flatMap(mode => [
+ deleteKey(`acuc_${api_key}_${mode ? "extract" : "scrape"}`),
+ ...credentialPurposes.map(credentialPurpose =>
+ deleteKey(
+ `acuc_${credentialPurpose}_${api_key}_${mode ? "extract" : "scrape"}`,
+ ),
+ ),
+ ]),
);
// Also clear the base cache key
@@ -677,9 +653,57 @@ async function supaAuthenticateUser(
rateLimiter = getRateLimiter(RateLimiterMode.Preview, null);
}
teamId = `preview_${iptoken}`;
+ } else if (token.startsWith("fcmcp_")) {
+ const delegation = verifyMcpDelegatedCredential(
+ token,
+ config.MCP_DELEGATED_CREDENTIAL_SECRET,
+ );
+ if (!delegation) {
+ return {
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ };
+ }
+
+ const resolvedApi = parseApi(delegation.api_key);
+ chunk = await getACUC(
+ resolvedApi,
+ false,
+ false,
+ RateLimiterMode.Scrape,
+ "hosted_mcp_oauth",
+ );
+ if (chunk === null) {
+ return {
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ };
+ }
+
+ teamId = chunk.team_id;
+ subscriptionData = { team_id: teamId };
+ rateLimiter = await buildAuthenticatedRateLimiter(
+ teamId,
+ chunk.org_id,
+ mode,
+ );
} else if (token.startsWith("fco_")) {
// OAuth access token — resolve via introspection endpoint
- const introspection = await resolveOAuthToken(token);
+ let introspection: OAuthIntrospectionResponse | null;
+ try {
+ introspection = await resolveOAuthToken(token);
+ } catch (error) {
+ if (error instanceof OAuthIntrospectionUnavailableError) {
+ return {
+ success: false,
+ error: "OAuth authentication is temporarily unavailable",
+ status: 503,
+ };
+ }
+ throw error;
+ }
if (!introspection) {
return {
success: false,
@@ -687,10 +711,26 @@ async function supaAuthenticateUser(
status: 401,
};
}
+ if (
+ introspection.credential_purpose !== undefined &&
+ introspection.credential_purpose !== "general"
+ ) {
+ return {
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ };
+ }
// Use the resolved fc- API key to get the normal ACUC chunk
const resolvedApi = parseApi(introspection.api_key);
- chunk = await getACUC(resolvedApi, false, true, RateLimiterMode.Scrape);
+ chunk = await getACUC(
+ resolvedApi,
+ false,
+ true,
+ RateLimiterMode.Scrape,
+ "general",
+ );
if (chunk === null) {
return {
@@ -699,6 +739,13 @@ async function supaAuthenticateUser(
status: 401,
};
}
+ if (chunk.team_id !== introspection.team_id) {
+ return {
+ success: false,
+ error: "Unauthorized: Invalid token",
+ status: 401,
+ };
+ }
teamId = chunk.team_id;
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.ts
index 4d9c63011..0e0788fe5 100644
--- a/apps/api/src/controllers/v1/types.ts
+++ b/apps/api/src/controllers/v1/types.ts
@@ -1255,6 +1255,7 @@ type Account = {
export type AuthCreditUsageChunk = {
api_key: string;
api_key_id: number;
+ api_key_id_text?: string;
team_id: string;
org_id: string;
plan_priority: {
diff --git a/apps/api/src/controllers/v2/keyless-eligibility.ts b/apps/api/src/controllers/v2/keyless-eligibility.ts
index f86701a19..b9eee6cfb 100644
--- a/apps/api/src/controllers/v2/keyless-eligibility.ts
+++ b/apps/api/src/controllers/v2/keyless-eligibility.ts
@@ -3,11 +3,11 @@ import { config } from "../../config";
import { checkKeylessEligibility } from "../../lib/keyless";
/**
- * Internal endpoint for trusted proxies (the hosted MCP) to check, at connect
- * time, whether a client IP can currently use the keyless tier — without
+ * Internal endpoint for trusted proxies (the hosted MCP) to check, before a
+ * keyless tool call, whether a client IP can currently use the tier — without
* consuming quota. Gated by the shared KEYLESS_PROXY_SECRET; the client IP is
* supplied via x-firecrawl-keyless-ip. Lets the MCP serve keyless when eligible
- * and throw (→ OAuth 401 challenge) when the IP is out of free quota.
+ * and return a structured recovery action when the IP is not eligible.
*/
export async function keylessEligibilityController(
req: Request,
diff --git a/apps/api/src/controllers/v2/mcp-action-logs.ts b/apps/api/src/controllers/v2/mcp-action-logs.ts
new file mode 100644
index 000000000..703219f2f
--- /dev/null
+++ b/apps/api/src/controllers/v2/mcp-action-logs.ts
@@ -0,0 +1,116 @@
+import { Request, Response } from "express";
+import { config } from "../../config";
+import { db, dbRr } from "../../db/connection";
+import { ErrorResponse, RequestWithAuth, TeamFlags } from "./types";
+import {
+ authorizeMcpActionLogViewer,
+ listMcpActionLogs,
+ McpActionLogAuthorizationError,
+ McpActionLogValidationError,
+ normalizeMcpActionLogInput,
+ purgeMcpActionLogsForTeam,
+ recordMcpActionLog,
+ resolveMcpActionLogTeamPolicy,
+ validateMcpActionLogActor,
+} from "../../services/mcp/action-logs";
+
+type InternalRequest = Request<unknown, unknown, Record<string, unknown>>;
+type ListResponse =
+ | { success: true; data: unknown[]; nextCursor: string | null }
+ | ErrorResponse;
+
+function isMcpActionLogZdrTeam(flags: TeamFlags | undefined) {
+ return (
+ flags?.forceZDR === true ||
+ flags?.scrapeZDR === "forced" ||
+ flags?.searchZDR === "forced" ||
+ flags?.searchZDR === "forced-zdr" ||
+ flags?.searchZDR === "forced-anon"
+ );
+}
+
+export async function ingestMcpActionLogController(
+ req: InternalRequest,
+ res: Response,
+) {
+ try {
+ const input = normalizeMcpActionLogInput(req.body ?? {});
+ await validateMcpActionLogActor(db, input);
+ const team = await resolveMcpActionLogTeamPolicy(db, input.team_id);
+ if (!team) {
+ return res.status(503).json({
+ success: false,
+ error: "Team policy could not be resolved",
+ });
+ }
+ if (isMcpActionLogZdrTeam(team.flags)) {
+ await purgeMcpActionLogsForTeam(db, input.team_id);
+ return res.status(202).json({
+ success: true,
+ disposition: "zero-data-retention",
+ id: null,
+ });
+ }
+ const result = await recordMcpActionLog(db, input);
+ return res.status(202).json({ success: true, ...result });
+ } catch (error) {
+ if (error instanceof McpActionLogValidationError) {
+ return res.status(400).json({ success: false, error: error.message });
+ }
+ if (error instanceof McpActionLogAuthorizationError) {
+ return res.status(403).json({ success: false, error: error.message });
+ }
+ return res.status(500).json({
+ success: false,
+ error: "Failed to persist MCP action log",
+ });
+ }
+}
+
+export async function listMcpActionLogsController(
+ req: RequestWithAuth,
+ res: Response<ListResponse>,
+) {
+ try {
+ if (!config.MCP_ACTION_LOG_STORAGE_ENABLED) {
+ return res.status(503).json({
+ success: false,
+ error: "MCP action logging is disabled",
+ });
+ }
+ await authorizeMcpActionLogViewer(
+ db,
+ req.auth.team_id,
+ req.acuc?.api_key_id_text ?? req.acuc?.api_key_id,
+ );
+ const team = await resolveMcpActionLogTeamPolicy(db, req.auth.team_id);
+ if (!team) {
+ return res.status(503).json({
+ success: false,
+ error: "Team policy could not be resolved",
+ });
+ }
+ if (isMcpActionLogZdrTeam(team.flags)) {
+ await purgeMcpActionLogsForTeam(db, req.auth.team_id);
+ return res.status(200).json({
+ success: true,
+ data: [],
+ nextCursor: null,
+ });
+ }
+ const parsedLimit = Number.parseInt(String(req.query.limit ?? "50"), 10);
+ const result = await listMcpActionLogs(dbRr, req.auth.team_id, {
+ limit: Number.isFinite(parsedLimit) ? parsedLimit : 50,
+ cursor: typeof req.query.cursor === "string" ? req.query.cursor : null,
+ });
+ return res.status(200).json({ success: true, ...result });
+ } catch (error) {
+ if (error instanceof McpActionLogAuthorizationError) {
+ return res.status(403).json({ success: false, error: error.message });
+ }
+ if (error instanceof McpActionLogValidationError) {
+ return res.status(400).json({ success: false, error: error.message });
+ }
+ throw error;
+ }
+}
diff --git a/apps/api/src/db/auth-credit-usage-rpc.test.ts b/apps/api/src/db/auth-credit-usage-rpc.test.ts
new file mode 100644
index 000000000..bc9169aa8
--- /dev/null
+++ b/apps/api/src/db/auth-credit-usage-rpc.test.ts
@@ -0,0 +1,38 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { execute } = vi.hoisted(() => ({ execute: vi.fn() }));
+
+vi.mock("./connection", () => ({
+ db: { execute: vi.fn() },
+ dbIndex: { execute: vi.fn() },
+}));
+
+import { authCreditUsageChunk } from "./rpc";
+
+describe("auth credit usage database RPC", () => {
+ beforeEach(() => vi.clearAllMocks());
+
+ it("preserves the exact bigint API-key ID alongside the legacy number", async () => {
+ execute.mockResolvedValue({
+ rows: [
+ {
+ team_id: "00000000-0000-4000-8000-000000000001",
+ api_key: "fc-test",
+ api_key_id: "9007199254740993",
+ },
+ ],
+ });
+
+ const rows = await authCreditUsageChunk(
+ { execute } as any,
+ "fc-test",
+ "hosted_mcp_oauth",
+ );
+
+ expect(rows[0].api_key_id_text).toBe("9007199254740993");
+ expect(rows[0].api_key_id).toBe(Number("9007199254740993"));
+ expect(JSON.stringify(execute.mock.calls[0][0])).toContain(
+ "hosted_mcp_oauth",
+ );
+ });
+});
diff --git a/apps/api/src/db/rpc.ts b/apps/api/src/db/rpc.ts
index 5ef79455a..4cf9f1d78 100644
--- a/apps/api/src/db/rpc.ts
+++ b/apps/api/src/db/rpc.ts
@@ -31,14 +31,16 @@ export type AuthCreditUsageChunkRow = Record<string, any> & {
export async function authCreditUsageChunk(
database: DB,
input_key: string,
+ input_credential_purpose: "general" | "hosted_mcp_oauth" = "general",
): Promise<AuthCreditUsageChunkRow[]> {
const rows = await execRows<AuthCreditUsageChunkRow>(
database,
- sql`select * from auth_credit_usage_chunk_56(input_key => ${input_key})`,
+ sql`select * from auth_credit_usage_chunk_57(input_key => ${input_key}, input_credential_purpose => ${input_credential_purpose})`,
);
// api_key_id is a bigint column, so the pg driver hands it back as a string.
for (const row of rows) {
if (row.api_key_id != null) {
+ row.api_key_id_text = String(row.api_key_id);
row.api_key_id = toNum(row.api_key_id);
}
}
diff --git a/apps/api/src/db/schema/public.ts b/apps/api/src/db/schema/public.ts
index e86c8ba23..5acb8afb4 100644
--- a/apps/api/src/db/schema/public.ts
+++ b/apps/api/src/db/schema/public.ts
@@ -15,6 +15,7 @@ import {
bytea,
check,
foreignKey,
+ index,
unique,
} from "drizzle-orm/pg-core";
@@ -557,6 +558,38 @@ export const requests = pgTable("requests", {
api_key_id: bigintNum("api_key_id"),
});
+export const mcp_action_logs = pgTable(
+ "mcp_action_logs",
+ {
+ id: uuid("id").defaultRandom().primaryKey(),
+ team_id: uuid("team_id").notNull(),
+ user_id: uuid("user_id"),
+ api_key_id: bigintNum("api_key_id"),
+ oauth_client_id: text("oauth_client_id"),
+ auth_type: text("auth_type").notNull(),
+ tool_name: text("tool_name").notNull(),
+ status: text("status").notNull(),
+ request_id: uuid("request_id").notNull(),
+ client_name: text("client_name"),
+ client_version: text("client_version"),
+ error_class: text("error_class"),
+ resource: text("resource").notNull(),
+ created_at: ts("created_at").notNull().defaultNow(),
+ expires_at: ts("expires_at").notNull(),
+ },
+ table => [
+ // Mirrors the DB migration and is required by recordMcpActionLog's
+ // ON CONFLICT (team_id, request_id) idempotency contract.
+ unique("mcp_action_logs_team_request_unique").on(
+ table.team_id,
+ table.request_id,
+ ),
+ // Mirrors the DB migration and keeps the retention worker's bounded
+ // expiry scan indexed as the table grows.
+ index("mcp_action_logs_expires_idx").on(table.expires_at),
+ ],
+);
+
export const scrapes = pgTable("scrapes", {
id: uuid("id").notNull(),
request_id: uuid("request_id").notNull(),
diff --git a/apps/api/src/index.ts b/apps/api/src/index.ts
index a163c46fc..ed9b5d50a 100644
--- a/apps/api/src/index.ts
+++ b/apps/api/src/index.ts
@@ -31,6 +31,9 @@ import { v7 as uuidv7 } from "uuid";
import { attachWsProxy } from "./services/agentLivecastWS";
import { cacheableLookup } from "./scraper/scrapeURL/lib/cacheableLookup";
import { v2Router } from "./routes/v2";
+import { registerMcpActionLogIngestRoute } from "./routes/mcp-action-logs";
+import { startMcpActionLogRetentionWorkerIfEnabled } from "./services/mcp/action-logs";
+import { db } from "./db/connection";
import { nuqShutdown } from "./services/worker/nuq";
import { getErrorContactMessage } from "./lib/deployment";
import { initializeBlocklist } from "./scraper/WebScraper/utils/blocklist";
@@ -77,6 +80,8 @@ const captureRawBody = (
}
};
+registerMcpActionLogIngestRoute(app);
+
app.use(bodyParser.urlencoded({ extended: true, verify: captureRawBody }));
app.use(bodyParser.json({ limit: "10mb", verify: captureRawBody }));
@@ -144,6 +149,10 @@ async function startServer(port = DEFAULT_PORT) {
// Attach WebSocket proxy to the Express app
attachWsProxy(app);
+ const mcpActionLogRetention = startMcpActionLogRetentionWorkerIfEnabled({
+ enabled: config.MCP_ACTION_LOG_STORAGE_ENABLED,
+ db,
+ });
const server = app.listen(Number(port), HOST, (error?: Error) => {
if (error) {
logger.error("Failed to start HTTP server", { error, port, host: HOST });
@@ -155,6 +164,7 @@ async function startServer(port = DEFAULT_PORT) {
const exitHandler = async () => {
logger.info("SIGTERM signal received: closing HTTP server");
+ mcpActionLogRetention?.stop();
if (config.IS_KUBERNETES) {
// Account for GCE load balancer drain timeout
logger.info("Waiting 60s for GCE load balancer drain timeout");
@@ -260,6 +270,17 @@ app.use(
error: "Bad request, malformed JSON",
});
}
+ if (
+ typeof err === "object" &&
+ err !== null &&
+ "status" in err &&
+ (err as { status?: number }).status === 413
+ ) {
+ return res.status(413).json({
+ success: false,
+ error: "Request body is too large",
+ });
+ }
const id = res.sentry ?? uuidv7();
diff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.ts
index 014d559cc..bf04f3af4 100644
--- a/apps/api/src/lib/keyless.ts
+++ b/apps/api/src/lib/keyless.ts
@@ -214,8 +214,8 @@ return next
/**
* Read-only check of whether an IP could currently use the keyless tier (no
- * consumption). Used by the hosted MCP to decide, at connect time, whether to
- * serve keyless (eligible) or throw so FastMCP emits the OAuth challenge (not).
+ * consumption). Used by the hosted MCP before a keyless tool call so an
+ * ineligible caller receives structured recovery without an OAuth challenge.
*/
export async function checkKeylessEligibility(
ip: string,
@@ -225,8 +225,8 @@ export async function checkKeylessEligibility(
return { eligible: false, reason: "ineligible_ip" };
}
// Optional Spur Context check (only when SPUR_API_KEY is set): treat IPs on
- // anonymizing/rotating infrastructure as ineligible so the hosted MCP issues
- // an OAuth challenge instead of serving keyless that auth would then reject.
+ // anonymizing/rotating infrastructure as ineligible so the hosted MCP can
+ // return a bounded recovery result instead of serving a request auth rejects.
if (await isKeylessIpSuspicious(ip)) {
return { eligible: false, reason: "suspicious" };
}
@@ -247,8 +247,8 @@ export async function checkKeylessEligibility(
}
return { eligible: true };
} catch {
- // Limiter store unavailable — fail closed so the MCP issues an OAuth
- // challenge rather than granting unbounded keyless.
+ // Limiter store unavailable — fail closed so the MCP returns structured
+ // recovery rather than granting unbounded keyless access.
return { eligible: false, reason: "error" };
}
}
diff --git a/apps/api/src/lib/mcp-action-log-config.test.ts b/apps/api/src/lib/mcp-action-log-config.test.ts
new file mode 100644
index 000000000..ae47aa40c
--- /dev/null
+++ b/apps/api/src/lib/mcp-action-log-config.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { getMcpActionLogConfigErrors } from "./mcp-action-log-config";
+
+describe("MCP action log configuration", () => {
+ it("is inert by default", () => {
+ expect(getMcpActionLogConfigErrors({})).toEqual([]);
+ });
+
+ it("requires primary database authentication before enabling storage", () => {
+ expect(
+ getMcpActionLogConfigErrors({ MCP_ACTION_LOG_STORAGE_ENABLED: true }),
+ ).toEqual([
+ expect.objectContaining({ path: "MCP_ACTION_LOG_STORAGE_ENABLED" }),
+ ]);
+ });
+
+ it("requires storage and a non-empty secret before enabling writes", () => {
+ const errors = getMcpActionLogConfigErrors({
+ MCP_ACTION_LOG_WRITES_ENABLED: true,
+ MCP_ACTION_LOG_SECRET: " ",
+ });
+ expect(errors.map(error => error.path)).toEqual([
+ "MCP_ACTION_LOG_WRITES_ENABLED",
+ "MCP_ACTION_LOG_SECRET",
+ ]);
+ });
+
+ it("accepts the fully enabled production configuration", () => {
+ expect(
+ getMcpActionLogConfigErrors({
+ MCP_ACTION_LOG_STORAGE_ENABLED: true,
+ MCP_ACTION_LOG_WRITES_ENABLED: true,
+ MCP_ACTION_LOG_SECRET: "secret",
+ USE_DB_AUTHENTICATION: true,
+ }),
+ ).toEqual([]);
+ });
+});
diff --git a/apps/api/src/lib/mcp-action-log-config.ts b/apps/api/src/lib/mcp-action-log-config.ts
new file mode 100644
index 000000000..8b8e879ca
--- /dev/null
+++ b/apps/api/src/lib/mcp-action-log-config.ts
@@ -0,0 +1,43 @@
+type McpActionLogConfigInput = {
+ MCP_ACTION_LOG_STORAGE_ENABLED?: boolean;
+ MCP_ACTION_LOG_WRITES_ENABLED?: boolean;
+ MCP_ACTION_LOG_SECRET?: string;
+ USE_DB_AUTHENTICATION?: boolean;
+};
+
+export function getMcpActionLogConfigErrors(config: McpActionLogConfigInput) {
+ const errors: Array<{
+ path: keyof McpActionLogConfigInput;
+ message: string;
+ }> = [];
+ if (
+ config.MCP_ACTION_LOG_STORAGE_ENABLED === true &&
+ config.USE_DB_AUTHENTICATION !== true
+ ) {
+ errors.push({
+ path: "MCP_ACTION_LOG_STORAGE_ENABLED",
+ message: "MCP action log storage requires USE_DB_AUTHENTICATION=true",
+ });
+ }
+ if (
+ config.MCP_ACTION_LOG_WRITES_ENABLED === true &&
+ config.MCP_ACTION_LOG_STORAGE_ENABLED !== true
+ ) {
+ errors.push({
+ path: "MCP_ACTION_LOG_WRITES_ENABLED",
+ message:
+ "MCP action log writes require MCP_ACTION_LOG_STORAGE_ENABLED=true",
+ });
+ }
+ if (
+ config.MCP_ACTION_LOG_WRITES_ENABLED === true &&
+ !config.MCP_ACTION_LOG_SECRET?.trim()
+ ) {
+ errors.push({
+ path: "MCP_ACTION_LOG_SECRET",
+ message:
+ "MCP action log writes require a non-empty MCP_ACTION_LOG_SECRET",
+ });
+ }
+ return errors;
+}
diff --git a/apps/api/src/lib/mcp-delegated-credential.ts b/apps/api/src/lib/mcp-delegated-credential.ts
new file mode 100644
index 000000000..d9b58860b
--- /dev/null
+++ b/apps/api/src/lib/mcp-delegated-credential.ts
@@ -0,0 +1,100 @@
+import { createHmac, timingSafeEqual } from "crypto";
+import { isValidUuid } from "./owner-id";
+import { parseApi } from "./parseApi";
+
+const PREFIX = "fcmcp_";
+const MAX_TOKEN_LENGTH = 2_048;
+const MAX_FUTURE_IAT_SECONDS = 30;
+const MAX_FUTURE_EXP_SECONDS = 120;
+
+type McpDelegatedCredential = {
+ v: 1;
+ aud: "firecrawl-core";
+ purpose: "hosted_mcp_oauth";
+ api_key: string;
+ iat: number;
+ exp: number;
+};
+
+function decodeCanonicalBase64Url(segment: string): Buffer | null {
+ if (!segment || !/^[A-Za-z0-9_-]+$/.test(segment)) return null;
+
+ try {
+ const decoded = Buffer.from(segment, "base64url");
+ return decoded.toString("base64url") === segment ? decoded : null;
+ } catch {
+ return null;
+ }
+}
+
+function isExactPayload(value: unknown): value is McpDelegatedCredential {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
+ return false;
+ }
+
+ const payload = value as Record<string, unknown>;
+ const keys = Object.keys(payload).sort();
+ if (keys.length !== 6 || keys.join(",") !== "api_key,aud,exp,iat,purpose,v") {
+ return false;
+ }
+
+ if (
+ payload.v !== 1 ||
+ payload.aud !== "firecrawl-core" ||
+ payload.purpose !== "hosted_mcp_oauth" ||
+ typeof payload.api_key !== "string" ||
+ !/^fc-[0-9a-f]{32}$/i.test(payload.api_key) ||
+ !isValidUuid(parseApi(payload.api_key)) ||
+ !Number.isInteger(payload.iat) ||
+ !Number.isInteger(payload.exp)
+ ) {
+ return false;
+ }
+
+ return true;
+}
+
+export function verifyMcpDelegatedCredential(
+ token: string,
+ secret: string | undefined,
+ nowSeconds = Math.floor(Date.now() / 1000),
+): McpDelegatedCredential | null {
+ if (!secret || token.length > MAX_TOKEN_LENGTH || !token.startsWith(PREFIX)) {
+ return null;
+ }
+
+ const encoded = token.slice(PREFIX.length);
+ const separator = encoded.indexOf(".");
+ if (separator <= 0 || separator !== encoded.lastIndexOf(".")) return null;
+
+ const payloadSegment = encoded.slice(0, separator);
+ const signatureSegment = encoded.slice(separator + 1);
+ const payloadBytes = decodeCanonicalBase64Url(payloadSegment);
+ const signature = decodeCanonicalBase64Url(signatureSegment);
+ if (!payloadBytes || !signature || signature.length !== 32) return null;
+
+ const expected = createHmac("sha256", secret).update(payloadSegment).digest();
+ if (!timingSafeEqual(signature, expected)) return null;
+
+ let payload: unknown;
+ try {
+ payload = JSON.parse(
+ new TextDecoder("utf-8", { fatal: true }).decode(payloadBytes),
+ );
+ } catch {
+ return null;
+ }
+
+ if (!isExactPayload(payload)) return null;
+ if (payload.iat > nowSeconds + MAX_FUTURE_IAT_SECONDS) return null;
+ if (
+ payload.exp <= nowSeconds ||
+ payload.exp > nowSeconds + MAX_FUTURE_EXP_SECONDS
+ ) {
+ return null;
+ }
+ if (payload.exp <= payload.iat || payload.exp - payload.iat > 120)
+ return null;
+
+ return payload;
+}
diff --git a/apps/api/src/routes/mcp-action-logs.ts b/apps/api/src/routes/mcp-action-logs.ts
new file mode 100644
index 000000000..e4a6a59f5
--- /dev/null
+++ b/apps/api/src/routes/mcp-action-logs.ts
@@ -0,0 +1,144 @@
+import crypto from "node:crypto";
+import express, {
+ Application,
+ NextFunction,
+ Request,
+ RequestHandler,
+ Response,
+ Router,
+} from "express";
+import { config } from "../config";
+import {
+ ingestMcpActionLogController,
+ listMcpActionLogsController,
+} from "../controllers/v2/mcp-action-logs";
+import { wrap } from "./shared";
+
+const BODY_LIMIT = "64kb";
+const DEFAULT_LIMIT = 600;
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_BUCKETS = 10_000;
+
+function bearerToken(value: string | string[] | undefined) {
+ const header = Array.isArray(value) ? value[0] : value;
+ return header?.startsWith("Bearer ") ? header.slice(7) : null;
+}
+
+export function timingSafeSecretEqual(
+ provided: string | null,
+ expected?: string,
+) {
+ if (!provided || !expected) return false;
+ const left = Buffer.from(provided);
+ const right = Buffer.from(expected);
+ return left.length === right.length && crypto.timingSafeEqual(left, right);
+}
+
+function requireWritesEnabled(
+ _req: Request,
+ res: Response,
+ next: NextFunction,
+) {
+ if (
+ !config.MCP_ACTION_LOG_STORAGE_ENABLED ||
+ !config.MCP_ACTION_LOG_WRITES_ENABLED
+ ) {
+ return res
+ .status(503)
+ .json({ success: false, error: "MCP action logging is disabled" });
+ }
+ next();
+}
+
+function authenticate(req: Request, res: Response, next: NextFunction) {
+ if (
+ !timingSafeSecretEqual(
+ bearerToken(req.headers.authorization),
+ config.MCP_ACTION_LOG_SECRET,
+ )
+ ) {
+ return res.status(401).json({ success: false, error: "Unauthorized" });
+ }
+ next();
+}
+
+export function createMcpActionLogRateLimitMiddleware(options?: {
+ limit?: number;
+ windowMs?: number;
+ now?: () => number;
+ maxBuckets?: number;
+}): RequestHandler {
+ // This runs after the shared-secret check and is deliberately local
+ // load-shedding for trusted MCP writers, not a cross-replica billing or
+ // security quota. The bounded map prevents stale pod IPs accumulating.
+ const limit = options?.limit ?? DEFAULT_LIMIT;
+ const windowMs = options?.windowMs ?? DEFAULT_WINDOW_MS;
+ const now = options?.now ?? Date.now;
+ const maxBuckets = options?.maxBuckets ?? DEFAULT_MAX_BUCKETS;
+ const buckets = new Map<string, { count: number; resetAt: number }>();
+ let nextCleanupAt = 0;
+ return (req, res, next) => {
+ const key = req.ip || req.socket.remoteAddress || "unknown";
+ const current = now();
+ if (current >= nextCleanupAt) {
+ for (const [bucketKey, bucket] of buckets) {
+ if (bucket.resetAt <= current) buckets.delete(bucketKey);
+ }
+ nextCleanupAt = current + windowMs;
+ }
+ const previous = buckets.get(key);
+ if (!previous && buckets.size >= maxBuckets) {
+ res.setHeader(
+ "Retry-After",
+ String(Math.max(1, Math.ceil(windowMs / 1000))),
+ );
+ return res
+ .status(429)
+ .json({ success: false, error: "Too many MCP action log sources" });
+ }
+ const bucket =
+ !previous || previous.resetAt <= current
+ ? { count: 0, resetAt: current + windowMs }
+ : previous;
+ bucket.count += 1;
+ buckets.set(key, bucket);
+ if (bucket.count > limit) {
+ res.setHeader(
+ "Retry-After",
+ String(Math.max(1, Math.ceil((bucket.resetAt - current) / 1000))),
+ );
+ return res
+ .status(429)
+ .json({ success: false, error: "Too many MCP action log requests" });
+ }
+ next();
+ };
+}
+
+export function registerMcpActionLogIngestRoute(
+ app: Pick<Application, "post">,
+ options?: { rateLimit?: RequestHandler },
+) {
+ app.post(
+ "/v2/mcp/action-logs",
+ requireWritesEnabled,
+ authenticate,
+ options?.rateLimit ?? createMcpActionLogRateLimitMiddleware(),
+ // This is a JSON-only internal endpoint. Parse every media type here so
+ // callers cannot bypass the route-specific limit with a different
+ // Content-Type before the global parser runs.
+ express.json({ limit: BODY_LIMIT, type: () => true }),
+ wrap(ingestMcpActionLogController),
+ );
+}
+
+export function registerMcpActionLogReadRoute(
+ router: Pick<Router, "get">,
+ authenticateViewer: RequestHandler,
+) {
+ router.get(
+ "/mcp/action-logs",
+ authenticateViewer,
+ wrap(listMcpActionLogsController),
+ );
+}
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 31c9b3997..3cc6ef36e 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -2,6 +2,7 @@ import express from "express";
import multer from "multer";
import { config } from "../config";
import { RateLimiterMode } from "../types";
+import { registerMcpActionLogReadRoute } from "./mcp-action-logs";
import { SEARCH_CREDITS_FEATURE_ID } from "../services/autumn/autumn.service";
import expressWs from "express-ws";
import { searchController } from "../controllers/v2/search";
@@ -96,7 +97,6 @@ import {
slackOAuthStartController,
slackStatusController,
} from "../controllers/v2/slack";
-
export const v2Router = express.Router();
expressWs(express()).applyTo(v2Router);
@@ -161,6 +161,11 @@ v2Router.use(requestTimingMiddleware("v2"));
// inside the controller; no auth middleware.
v2Router.get("/keyless/eligibility", wrap(keylessEligibilityController));
+registerMcpActionLogReadRoute(
+ v2Router,
+ authMiddleware(RateLimiterMode.Account),
+);
+
v2Router.post(
"/search",
authMiddleware(RateLimiterMode.Search, { allowKeyless: true }),
diff --git a/apps/api/src/services/mcp/action-logs-controller.test.ts b/apps/api/src/services/mcp/action-logs-controller.test.ts
new file mode 100644
index 000000000..1da76f3d2
--- /dev/null
+++ b/apps/api/src/services/mcp/action-logs-controller.test.ts
@@ -0,0 +1,187 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { config } from "../../config";
+
+const mocks = vi.hoisted(() => ({
+ primaryDb: { name: "primary" },
+ replicaDb: { name: "replica" },
+ normalize: vi.fn((body: any) => body),
+ validate: vi.fn(),
+ record: vi.fn().mockResolvedValue({ disposition: "stored", id: "log-id" }),
+ policy: vi.fn(),
+ purge: vi.fn(),
+ authorize: vi.fn(),
+ list: vi.fn().mockResolvedValue({ data: [], nextCursor: null }),
+}));
+
+vi.mock("../../db/connection", () => ({
+ db: mocks.primaryDb,
+ dbRr: mocks.replicaDb,
+}));
+vi.mock("./action-logs", async importOriginal => {
+ const actual = await importOriginal<typeof import("./action-logs")>();
+ return {
+ ...actual,
+ normalizeMcpActionLogInput: mocks.normalize,
+ validateMcpActionLogActor: mocks.validate,
+ recordMcpActionLog: mocks.record,
+ resolveMcpActionLogTeamPolicy: mocks.policy,
+ purgeMcpActionLogsForTeam: mocks.purge,
+ authorizeMcpActionLogViewer: mocks.authorize,
+ listMcpActionLogs: mocks.list,
+ };
+});
+
+import {
+ ingestMcpActionLogController,
+ listMcpActionLogsController,
+} from "../../controllers/v2/mcp-action-logs";
+import { McpActionLogAuthorizationError } from "./action-logs";
+
+function response() {
+ const res: any = {};
+ res.status = vi.fn(() => res);
+ res.json = vi.fn(value => value);
+ return res;
+}
+
+describe("MCP action log controllers", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.policy.mockResolvedValue({ flags: null });
+ config.MCP_ACTION_LOG_STORAGE_ENABLED = true;
+ mocks.record.mockResolvedValue({ disposition: "stored", id: "log-id" });
+ mocks.list.mockResolvedValue({ data: [], nextCursor: null });
+ });
+
+ it("skips persistence for teams with forced zero-data retention", async () => {
+ mocks.policy.mockResolvedValue({ flags: { scrapeZDR: "forced" } });
+ const res = response();
+ await ingestMcpActionLogController(
+ { body: { team_id: "team" } } as any,
+ res,
+ );
+ expect(mocks.validate).toHaveBeenCalledTimes(1);
+ expect(mocks.policy).toHaveBeenCalledWith(mocks.primaryDb, "team");
+ expect(mocks.purge).toHaveBeenCalledWith(mocks.primaryDb, "team");
+ expect(mocks.record).not.toHaveBeenCalled();
+ expect(res.status).toHaveBeenCalledWith(202);
+ expect(res.json).toHaveBeenCalledWith(
+ expect.objectContaining({ disposition: "zero-data-retention", id: null }),
+ );
+ });
+
+ it("fails closed when team retention policy cannot be resolved", async () => {
+ mocks.policy.mockResolvedValue(null);
+ const res = response();
+ await ingestMcpActionLogController(
+ { body: { team_id: "team" } } as any,
+ res,
+ );
+ expect(mocks.record).not.toHaveBeenCalled();
+ expect(res.status).toHaveBeenCalledWith(503);
+ });
+
+ it("persists validated non-ZDR events", async () => {
+ const res = response();
+ await ingestMcpActionLogController(
+ { body: { team_id: "team" } } as any,
+ res,
+ );
+ expect(mocks.validate).toHaveBeenCalledTimes(1);
+ expect(mocks.record).toHaveBeenCalledTimes(1);
+ expect(res.status).toHaveBeenCalledWith(202);
+ });
+
+ it("authorizes listing from the authenticated API key id", async () => {
+ const res = response();
+ await listMcpActionLogsController(
+ {
+ auth: { team_id: "team" },
+ acuc: { api_key_id: 42 },
+ query: {},
+ } as any,
+ res,
+ );
+ expect(mocks.authorize).toHaveBeenCalledWith(mocks.primaryDb, "team", 42);
+ expect(mocks.policy).toHaveBeenCalledWith(mocks.primaryDb, "team");
+ expect(mocks.list).toHaveBeenCalledWith(
+ mocks.replicaDb,
+ "team",
+ expect.any(Object),
+ );
+ });
+
+ it("prefers the exact bigint API-key ID when authentication provides it", async () => {
+ const res = response();
+ await listMcpActionLogsController(
+ {
+ auth: { team_id: "team" },
+ acuc: {
+ api_key_id: Number("9007199254740993"),
+ api_key_id_text: "9007199254740993",
+ },
+ query: {},
+ } as any,
+ res,
+ );
+
+ expect(mocks.authorize).toHaveBeenCalledWith(
+ mocks.primaryDb,
+ "team",
+ "9007199254740993",
+ );
+ });
+
+ it("returns 403 when the presented key is not owner-bound", async () => {
+ mocks.authorize.mockRejectedValueOnce(
+ new McpActionLogAuthorizationError("An owner-bound API key is required"),
+ );
+ const res = response();
+
+ await listMcpActionLogsController(
+ {
+ auth: { team_id: "team" },
+ acuc: { api_key_id: 42 },
+ query: {},
+ } as any,
+ res,
+ );
+
+ expect(res.status).toHaveBeenCalledWith(403);
+ expect(mocks.list).not.toHaveBeenCalled();
+ });
+
+ it("does not query storage when activity logging is disabled", async () => {
+ config.MCP_ACTION_LOG_STORAGE_ENABLED = false;
+ const res = response();
+ await listMcpActionLogsController(
+ { auth: { team_id: "team" }, acuc: { api_key_id: 42 }, query: {} } as any,
+ res,
+ );
+ expect(res.status).toHaveBeenCalledWith(503);
+ expect(mocks.authorize).not.toHaveBeenCalled();
+ expect(mocks.policy).not.toHaveBeenCalled();
+ expect(mocks.list).not.toHaveBeenCalled();
+ });
+
+ it("does not expose retained activity to a forced-ZDR request", async () => {
+ mocks.policy.mockResolvedValue({ flags: { forceZDR: true } });
+ const res = response();
+ await listMcpActionLogsController(
+ {
+ auth: { team_id: "team" },
+ acuc: { api_key_id: 42 },
+ query: {},
+ } as any,
+ res,
+ );
+ expect(mocks.authorize).toHaveBeenCalledTimes(1);
+ expect(mocks.purge).toHaveBeenCalledWith(mocks.primaryDb, "team");
+ expect(mocks.list).not.toHaveBeenCalled();
+ expect(res.json).toHaveBeenCalledWith({
+ success: true,
+ data: [],
+ nextCursor: null,
+ });
+ });
+});
diff --git a/apps/api/src/services/mcp/action-logs-http.test.ts b/apps/api/src/services/mcp/action-logs-http.test.ts
new file mode 100644
index 000000000..aa58bc4e4
--- /dev/null
+++ b/apps/api/src/services/mcp/action-logs-http.test.ts
@@ -0,0 +1,182 @@
+import bodyParser from "body-parser";
+import express, { NextFunction, Request, Response } from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { config } from "../../config";
+
+const { ingest, list } = vi.hoisted(() => ({
+ ingest: vi.fn(async (_req: Request, res: Response) =>
+ res.status(202).json({ success: true }),
+ ),
+ list: vi.fn(async (_req: Request, res: Response) =>
+ res.status(200).json({ success: true, data: [] }),
+ ),
+}));
+
+vi.mock("../../controllers/v2/mcp-action-logs", () => ({
+ ingestMcpActionLogController: ingest,
+ listMcpActionLogsController: list,
+}));
+vi.mock("../../routes/shared", () => ({
+ wrap:
+ (controller: any) => (req: Request, res: Response, next: NextFunction) =>
+ Promise.resolve(controller(req, res)).catch(next),
+}));
+
+import {
+ createMcpActionLogRateLimitMiddleware,
+ registerMcpActionLogIngestRoute,
+ registerMcpActionLogReadRoute,
+ timingSafeSecretEqual,
+} from "../../routes/mcp-action-logs";
+
+function app(rateLimit = createMcpActionLogRateLimitMiddleware()) {
+ const server = express();
+ registerMcpActionLogIngestRoute(server, { rateLimit });
+ server.use(bodyParser.json({ limit: "10mb" }));
+ server.use(
+ (error: any, _req: Request, res: Response, _next: NextFunction) => {
+ if (error?.status === 413) {
+ return res
+ .status(413)
+ .json({ success: false, error: "Request body is too large" });
+ }
+ return res.status(500).json({ success: false, error: "unexpected" });
+ },
+ );
+ return server;
+}
+
+function readApp() {
+ const server = express();
+ const router = express.Router();
+ registerMcpActionLogReadRoute(router, (req, res, next) => {
+ if (req.headers.authorization !== "Bearer owner-key") {
+ return res.status(401).json({ success: false, error: "Unauthorized" });
+ }
+ next();
+ });
+ server.use("/v2", router);
+ return server;
+}
+
+describe("MCP action log ingest route", () => {
+ beforeEach(() => {
+ config.MCP_ACTION_LOG_SECRET = "test-secret";
+ config.MCP_ACTION_LOG_STORAGE_ENABLED = true;
+ config.MCP_ACTION_LOG_WRITES_ENABLED = true;
+ ingest.mockClear();
+ list.mockClear();
+ });
+
+ it("is disabled by default through an explicit write flag", async () => {
+ config.MCP_ACTION_LOG_WRITES_ENABLED = false;
+ const response = await request(app())
+ .post("/v2/mcp/action-logs")
+ .set("Authorization", "Bearer test-secret")
+ .send({});
+ expect(response.status).toBe(503);
+ expect(ingest).not.toHaveBeenCalled();
+ });
+
+ it("defensively rejects writes when storage is disabled", async () => {
+ config.MCP_ACTION_LOG_STORAGE_ENABLED = false;
+ const response = await request(app())
+ .post("/v2/mcp/action-logs")
+ .set("Authorization", "Bearer test-secret")
+ .send({});
+ expect(response.status).toBe(503);
+ expect(ingest).not.toHaveBeenCalled();
+ });
+
+ it("uses a timing-safe shared-secret comparison", async () => {
+ expect(timingSafeSecretEqual("test-secret", "test-secret")).toBe(true);
+ expect(timingSafeSecretEqual("short", "long-secret")).toBe(false);
+ const response = await request(app()).post("/v2/mcp/action-logs").send({});
+ expect(response.status).toBe(401);
+ expect(ingest).not.toHaveBeenCalled();
+ });
+
+ it("enforces the dedicated 64 KB body limit before the global parser", async () => {
+ const response = await request(app())
+ .post("/v2/mcp/action-logs")
+ .set("Authorization", "Bearer test-secret")
+ .send({ padding: "x".repeat(65 * 1024) });
+ expect(response.status).toBe(413);
+ expect(ingest).not.toHaveBeenCalled();
+ });
+
+ it("enforces the body limit for non-JSON content types", async () => {
+ const response = await request(app())
+ .post("/v2/mcp/action-logs")
+ .set("Authorization", "Bearer test-secret")
+ .set("Content-Type", "text/plain")
+ .send("x".repeat(65 * 1024));
+ expect(response.status).toBe(413);
+ expect(ingest).not.toHaveBeenCalled();
+ });
+
+ it("rate limits accepted writers with Retry-After", async () => {
+ const server = app(
+ createMcpActionLogRateLimitMiddleware({
+ limit: 1,
+ windowMs: 10_000,
+ now: () => 1_000,
+ }),
+ );
+ const send = () =>
+ request(server)
+ .post("/v2/mcp/action-logs")
+ .set("Authorization", "Bearer test-secret")
+ .send({});
+ expect((await send()).status).toBe(202);
+ const blocked = await send();
+ expect(blocked.status).toBe(429);
+ expect(blocked.headers["retry-after"]).toBe("10");
+ expect(ingest).toHaveBeenCalledTimes(1);
+ });
+
+ it("rejects new authenticated sources at capacity without evicting active buckets", () => {
+ const rateLimit = createMcpActionLogRateLimitMiddleware({
+ limit: 1,
+ windowMs: 10_000,
+ maxBuckets: 2,
+ now: () => 1_000,
+ });
+ const invoke = (ip: string) => {
+ const next = vi.fn();
+ const res = {
+ setHeader: vi.fn(),
+ status: vi.fn().mockReturnThis(),
+ json: vi.fn(),
+ } as any;
+ rateLimit({ ip, socket: {} } as any, res, next);
+ return { next, res };
+ };
+
+ expect(invoke("source-a").next).toHaveBeenCalledTimes(1);
+ expect(invoke("source-b").next).toHaveBeenCalledTimes(1);
+ const rejected = invoke("source-c");
+ expect(rejected.next).not.toHaveBeenCalled();
+ expect(rejected.res.status).toHaveBeenCalledWith(429);
+ expect(rejected.res.json).toHaveBeenCalledWith({
+ success: false,
+ error: "Too many MCP action log sources",
+ });
+ const stillLimited = invoke("source-a");
+ expect(stillLimited.next).not.toHaveBeenCalled();
+ expect(stillLimited.res.status).toHaveBeenCalledWith(429);
+ });
+
+ it("wires the activity read route behind account authentication", async () => {
+ const server = readApp();
+ expect((await request(server).get("/v2/mcp/action-logs")).status).toBe(401);
+ expect(list).not.toHaveBeenCalled();
+
+ const accepted = await request(server)
+ .get("/v2/mcp/action-logs")
+ .set("Authorization", "Bearer owner-key");
+ expect(accepted.status).toBe(200);
+ expect(list).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/apps/api/src/services/mcp/action-logs.test.ts b/apps/api/src/services/mcp/action-logs.test.ts
new file mode 100644
index 000000000..8c32f68b2
--- /dev/null
+++ b/apps/api/src/services/mcp/action-logs.test.ts
@@ -0,0 +1,353 @@
+import { describe, expect, it, vi } from "vitest";
+import { PgDialect } from "drizzle-orm/pg-core";
+
+vi.mock("../../db/rpc", () => ({
+ authCreditUsageChunkFromTeam: vi.fn((db: any, teamId: string) =>
+ db.getTeamPolicy(teamId),
+ ),
+}));
+import {
+ authorizeMcpActionLogViewer,
+ decodeMcpActionLogCursor,
+ encodeMcpActionLogCursor,
+ listMcpActionLogs,
+ normalizeMcpActionLogInput,
+ purgeMcpActionLogsForTeam,
+ recordMcpActionLog,
+ resolveMcpActionLogTeamPolicy,
+ startMcpActionLogRetentionWorker,
+ startMcpActionLogRetentionWorkerIfEnabled,
+ validateMcpActionLogActor,
+} from "./action-logs";
+
+const TEAM_ID = "00000000-0000-4000-8000-000000000001";
+const USER_ID = "00000000-0000-4000-8000-000000000002";
+const REQUEST_ID = "00000000-0000-4000-8000-000000000003";
+const UUID_V7_REQUEST_ID = "0190a5d4-7b10-7cc3-98c4-0242ac120002";
+
+function input(overrides: Record<string, unknown> = {}) {
+ return normalizeMcpActionLogInput({
+ team_id: TEAM_ID,
+ api_key_id: "123",
+ auth_type: "api-key",
+ tool_name: "firecrawl_scrape",
+ status: "success",
+ request_id: REQUEST_ID,
+ resource: "https://mcp.firecrawl.dev/v2/mcp",
+ ...overrides,
+ });
+}
+
+describe("MCP action log contract", () => {
+ it("preserves decimal API-key IDs beyond JavaScript's safe integer range", () => {
+ expect(input({ api_key_id: "9007199254740993" }).api_key_id).toBe(
+ "9007199254740993",
+ );
+ });
+
+ it.each([
+ "",
+ "0",
+ "01",
+ "-1",
+ "+1",
+ "1.0",
+ "1e3",
+ " 1",
+ "1 ",
+ "abc",
+ "9223372036854775808",
+ ])("rejects malformed API-key ID %j", apiKeyId => {
+ expect(() => input({ api_key_id: apiKeyId })).toThrow(
+ "api_key_id must be a positive decimal string",
+ );
+ });
+
+ it("accepts only terminal, attributable events for canonical MCP resources", () => {
+ expect(input()).toMatchObject({
+ auth_type: "api-key",
+ request_id: REQUEST_ID,
+ resource: "https://mcp.firecrawl.dev/v2/mcp",
+ });
+ expect(
+ input({
+ auth_type: "oauth",
+ api_key_id: null,
+ user_id: USER_ID,
+ oauth_client_id: "claude-web",
+ resource: "https://mcp.firecrawl.dev/v2/mcp-oauth",
+ }),
+ ).toMatchObject({ auth_type: "oauth", user_id: USER_ID });
+
+ expect(() => input({ status: "started" })).toThrow(
+ "status must be success or error",
+ );
+ expect(() => input({ request_id: "req-1" })).toThrow(
+ "request_id must be a valid UUID",
+ );
+ expect(() =>
+ input({ resource: "https://mcp.firecrawl.dev/v2/mcp?key=x" }),
+ ).toThrow("resource must be a canonical hosted MCP URL");
+ expect(() => input({ resource: "https://example.com/v2/mcp" })).toThrow(
+ "resource must be a canonical hosted MCP URL",
+ );
+ });
+
+ it("accepts UUIDv7 request IDs", () => {
+ expect(input({ request_id: UUID_V7_REQUEST_ID }).request_id).toBe(
+ UUID_V7_REQUEST_ID,
+ );
+ });
+
+ it("rejects inconsistent authentication fields and raw user agent metadata", () => {
+ expect(() => input({ api_key_id: null })).toThrow(
+ "api_key_id is required for api-key events",
+ );
+ expect(() => input({ user_id: USER_ID })).toThrow(
+ "api-key events must not include OAuth identity fields",
+ );
+ expect(() =>
+ input({
+ auth_type: "oauth",
+ api_key_id: null,
+ user_id: null,
+ oauth_client_id: "client",
+ }),
+ ).toThrow("user_id is required for oauth events");
+ expect(() => input({ auth_type: "keyless" })).toThrow(
+ "auth_type must be oauth or api-key",
+ );
+ expect(input({ user_agent: "Claude/1.0" })).not.toHaveProperty(
+ "user_agent",
+ );
+ expect(() => input({ arguments: { url: "https://private.test" } })).toThrow(
+ "arguments is not accepted",
+ );
+ expect(() => input({ client_name: "Bearer fco_secret" })).toThrow(
+ "client_name must not contain secret-like values",
+ );
+ expect(() => input({ client_name: "fcmcp_secret" })).toThrow(
+ "client_name must not contain secret-like values",
+ );
+ });
+
+ it("validates API-key and OAuth actors against the claimed team", async () => {
+ const apiKeyDb = {
+ select: vi.fn(() => ({
+ from: () => ({
+ where: () => ({ limit: () => Promise.resolve([{ id: 123 }]) }),
+ }),
+ })),
+ };
+ await expect(
+ validateMcpActionLogActor(apiKeyDb as any, input()),
+ ).resolves.toBeUndefined();
+
+ const missingDb = {
+ select: vi.fn(() => ({
+ from: () => ({ where: () => ({ limit: () => Promise.resolve([]) }) }),
+ })),
+ };
+ await expect(
+ validateMcpActionLogActor(missingDb as any, input()),
+ ).rejects.toThrow("api_key_id does not belong to team_id");
+
+ await expect(
+ validateMcpActionLogActor(
+ missingDb as any,
+ input({
+ auth_type: "oauth",
+ api_key_id: null,
+ user_id: USER_ID,
+ oauth_client_id: "client",
+ }),
+ ),
+ ).rejects.toThrow("user_id does not belong to team_id");
+
+ const oauthRows = [[{ id: 123 }], [{ user_id: USER_ID }]];
+ const oauthDb = {
+ select: () => ({
+ from: () => ({
+ where: () => ({
+ limit: () => Promise.resolve(oauthRows.shift() ?? []),
+ }),
+ }),
+ }),
+ };
+ await expect(
+ validateMcpActionLogActor(
+ oauthDb as any,
+ input({
+ auth_type: "oauth",
+ user_id: USER_ID,
+ oauth_client_id: "client",
+ }),
+ ),
+ ).resolves.toBeUndefined();
+ });
+
+ it("resolves retention policy through the explicitly supplied primary DB", async () => {
+ const primaryDb = {
+ getTeamPolicy: vi
+ .fn()
+ .mockResolvedValue([{ team_id: TEAM_ID, flags: { forceZDR: true } }]),
+ };
+ await expect(
+ resolveMcpActionLogTeamPolicy(primaryDb as any, TEAM_ID),
+ ).resolves.toEqual({ flags: { forceZDR: true } });
+ expect(primaryDb.getTeamPolicy).toHaveBeenCalledWith(TEAM_ID);
+ });
+
+ it("reports stored and duplicate deliveries correctly", async () => {
+ const returning = vi.fn().mockResolvedValue([]);
+ const onConflictDoNothing = vi.fn(() => ({ returning }));
+ const values = vi.fn(() => ({ onConflictDoNothing }));
+ const db = { insert: () => ({ values }) };
+
+ await expect(recordMcpActionLog(db as any, input())).resolves.toEqual({
+ disposition: "duplicate",
+ id: null,
+ });
+ expect(onConflictDoNothing).toHaveBeenCalledTimes(1);
+ expect((values.mock.calls as any)[0][0]).not.toHaveProperty("user_agent");
+
+ returning.mockResolvedValueOnce([{ id: REQUEST_ID }]);
+ await expect(recordMcpActionLog(db as any, input())).resolves.toEqual({
+ disposition: "stored",
+ id: REQUEST_ID,
+ });
+ });
+
+ it("requires the API-key owner to be a team admin or owner for listing", async () => {
+ const rows = [
+ [{ owner_id: USER_ID }],
+ [{ role: "admin" }],
+ [{ owner_id: USER_ID }],
+ [{ role: "admin" }],
+ ];
+ const predicates: unknown[] = [];
+ const db = {
+ select: vi.fn(() => ({
+ from: () => ({
+ where: (predicate: unknown) => {
+ predicates.push(predicate);
+ return { limit: () => Promise.resolve(rows.shift() ?? []) };
+ },
+ }),
+ })),
+ };
+ await expect(
+ authorizeMcpActionLogViewer(db as any, TEAM_ID, 123),
+ ).resolves.toEqual({ userId: USER_ID, role: "admin" });
+
+ await expect(
+ authorizeMcpActionLogViewer(db as any, TEAM_ID, "9007199254740993"),
+ ).resolves.toEqual({ userId: USER_ID, role: "admin" });
+ const keyLookup = new PgDialect().sqlToQuery(predicates[2] as any);
+ expect(keyLookup.params).toEqual(["9007199254740993", TEAM_ID]);
+ const membershipLookup = new PgDialect().sqlToQuery(predicates[3] as any);
+ expect(membershipLookup.params).toEqual([USER_ID, TEAM_ID]);
+
+ const noOwner = {
+ select: () => ({
+ from: () => ({ where: () => ({ limit: () => Promise.resolve([]) }) }),
+ }),
+ };
+ await expect(
+ authorizeMcpActionLogViewer(noOwner as any, TEAM_ID, 123),
+ ).rejects.toThrow("An owner-bound API key is required");
+ });
+
+ it("purges all retained rows for a team on the supplied primary DB", async () => {
+ const where = vi.fn().mockResolvedValue(undefined);
+ const db = { delete: vi.fn(() => ({ where })) };
+ await purgeMcpActionLogsForTeam(db as any, TEAM_ID);
+ expect(db.delete).toHaveBeenCalledTimes(1);
+ expect(where).toHaveBeenCalledTimes(1);
+ });
+
+ it("runs bounded retention independently on an unrefed, stoppable timer", async () => {
+ const db = { execute: vi.fn().mockResolvedValue(undefined) };
+ let callback: (() => void) | undefined;
+ const timer = { unref: vi.fn() };
+ const clear = vi.fn();
+ const worker = startMcpActionLogRetentionWorker({
+ db,
+ intervalMs: 1234,
+ setIntervalFn: (next, interval) => {
+ callback = next;
+ expect(interval).toBe(1234);
+ return timer;
+ },
+ clearIntervalFn: clear,
+ });
+ await worker.ready;
+ expect(db.execute).toHaveBeenCalled();
+ expect(timer.unref).toHaveBeenCalledTimes(1);
+ callback?.();
+ await vi.waitFor(() =>
+ expect(db.execute.mock.calls.length).toBeGreaterThan(1),
+ );
+ worker.stop();
+ expect(clear).toHaveBeenCalledWith(timer);
+ });
+
+ it("does not touch storage when retention is disabled", () => {
+ const db = { execute: vi.fn() };
+ const setIntervalFn = vi.fn();
+ expect(
+ startMcpActionLogRetentionWorkerIfEnabled({
+ enabled: false,
+ db,
+ setIntervalFn,
+ }),
+ ).toBeNull();
+ expect(db.execute).not.toHaveBeenCalled();
+ expect(setIntervalFn).not.toHaveBeenCalled();
+ });
+
+ it("paginates non-expired rows with stable cursors", async () => {
+ const rows = [
+ {
+ id: REQUEST_ID,
+ api_key_id: "9007199254740993",
+ created_at: "2026-07-10T10:03:00.000Z",
+ },
+ { id: USER_ID, api_key_id: null, created_at: "2026-07-10T10:02:00.000Z" },
+ ];
+ const execute = vi.fn().mockResolvedValue(undefined);
+ const db = {
+ execute,
+ select: () => ({
+ from() {
+ return this;
+ },
+ where() {
+ return this;
+ },
+ orderBy() {
+ return this;
+ },
+ limit: () => Promise.resolve(rows),
+ }),
+ };
+ const result = await listMcpActionLogs(db as any, TEAM_ID, { limit: 1 });
+ expect(result.data).toEqual(rows.slice(0, 1));
+ expect(result.data[0].api_key_id).toBe("9007199254740993");
+ expect(decodeMcpActionLogCursor(result.nextCursor!)).toEqual({
+ id: rows[0].id,
+ created_at: rows[0].created_at,
+ });
+ expect(execute).not.toHaveBeenCalled();
+
+ const cursor = encodeMcpActionLogCursor(rows[0]);
+ expect(decodeMcpActionLogCursor(cursor)).toEqual({
+ id: rows[0].id,
+ created_at: rows[0].created_at,
+ });
+ expect(() => decodeMcpActionLogCursor("bad")).toThrow("cursor is invalid");
+
+ const complete = await listMcpActionLogs(db as any, TEAM_ID, { limit: 2 });
+ expect(complete.data[1].api_key_id).toBeNull();
+ });
+});
diff --git a/apps/api/src/services/mcp/action-logs.ts b/apps/api/src/services/mcp/action-logs.ts
new file mode 100644
index 000000000..a773e5ff0
--- /dev/null
+++ b/apps/api/src/services/mcp/action-logs.ts
@@ -0,0 +1,435 @@
+import { and, desc, eq, gt, lt, or, sql } from "drizzle-orm";
+import * as schema from "../../db/schema";
+import { authCreditUsageChunkFromTeam } from "../../db/rpc";
+import { logger } from "../../lib/logger";
+
+const STATUSES = ["success", "error"] as const;
+const AUTH_TYPES = ["oauth", "api-key"] as const;
+const RESOURCES = new Set([
+ "https://mcp.firecrawl.dev/v2/mcp",
+ "https://mcp.firecrawl.dev/v2/mcp-oauth",
+]);
+const UUID_PATTERN =
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const POSTGRES_BIGINT_MAX = 9_223_372_036_854_775_807n;
+const SECRET_PATTERN =
+ /(?:\bBearer\s+\S+|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b|\b(?:sk-|fc-|fco_|fcr_|fcmcp_)[A-Za-z0-9_-]+)/i;
+const RETENTION_DAYS = 30;
+const CLEANUP_BATCH_SIZE = 500;
+const ALLOWED_FIELDS = new Set([
+ "team_id",
+ "user_id",
+ "api_key_id",
+ "oauth_client_id",
+ "auth_type",
+ "tool_name",
+ "status",
+ "request_id",
+ "user_agent",
+ "client_name",
+ "client_version",
+ "error_class",
+ "resource",
+]);
+
+export class McpActionLogValidationError extends Error {}
+export class McpActionLogAuthorizationError extends Error {}
+
+function invalid(message: string): never {
+ throw new McpActionLogValidationError(message);
+}
+
+function isCanonicalApiKeyId(value: unknown): value is string {
+ return (
+ typeof value === "string" &&
+ /^[1-9]\d*$/.test(value) &&
+ BigInt(value) <= POSTGRES_BIGINT_MAX
+ );
+}
+
+function uuid(value: unknown, field: string, required = true): string | null {
+ if (value == null || value === "") {
+ if (required) invalid(`${field} is required`);
+ return null;
+ }
+ if (typeof value !== "string" || !UUID_PATTERN.test(value)) {
+ invalid(`${field} must be a valid UUID`);
+ }
+ return value;
+}
+
+function text(value: unknown, field: string, max = 128, required = false) {
+ if (value == null || value === "") {
+ if (required) invalid(`${field} is required`);
+ return null;
+ }
+ if (typeof value !== "string") invalid(`${field} must be a string`);
+ const normalized = value.trim();
+ if (!normalized && required) invalid(`${field} is required`);
+ if (normalized.length > max)
+ invalid(`${field} must be at most ${max} characters`);
+ if (/[\u0000-\u001F\u007F]/.test(normalized)) {
+ invalid(`${field} must not contain control characters`);
+ }
+ if (SECRET_PATTERN.test(normalized)) {
+ invalid(`${field} must not contain secret-like values`);
+ }
+ return normalized || null;
+}
+
+type McpActionLogInput = {
+ team_id: string;
+ user_id: string | null;
+ api_key_id: string | null;
+ oauth_client_id: string | null;
+ auth_type: (typeof AUTH_TYPES)[number];
+ tool_name: string;
+ status: (typeof STATUSES)[number];
+ request_id: string;
+ client_name: string | null;
+ client_version: string | null;
+ error_class: string | null;
+ resource: string;
+};
+
+export function normalizeMcpActionLogInput(
+ payload: Record<string, unknown>,
+): McpActionLogInput {
+ for (const field of Object.keys(payload)) {
+ if (!ALLOWED_FIELDS.has(field)) invalid(`${field} is not accepted`);
+ }
+ const authType = payload.auth_type;
+ if (!AUTH_TYPES.includes(authType as (typeof AUTH_TYPES)[number])) {
+ invalid("auth_type must be oauth or api-key");
+ }
+ const status = payload.status;
+ if (!STATUSES.includes(status as (typeof STATUSES)[number])) {
+ invalid("status must be success or error");
+ }
+ const apiKeyId = payload.api_key_id;
+ if (apiKeyId != null && !isCanonicalApiKeyId(apiKeyId)) {
+ invalid("api_key_id must be a positive decimal string");
+ }
+ const userId = uuid(payload.user_id, "user_id", false);
+ const oauthClientId = text(payload.oauth_client_id, "oauth_client_id");
+ if (authType === "api-key") {
+ if (apiKeyId == null) invalid("api_key_id is required for api-key events");
+ if (userId || oauthClientId) {
+ invalid("api-key events must not include OAuth identity fields");
+ }
+ } else {
+ if (!userId) invalid("user_id is required for oauth events");
+ if (!oauthClientId) invalid("oauth_client_id is required for oauth events");
+ }
+ const resource = text(payload.resource, "resource", 128, true)!;
+ if (!RESOURCES.has(resource)) {
+ invalid("resource must be a canonical hosted MCP URL");
+ }
+ return {
+ team_id: uuid(payload.team_id, "team_id")!,
+ user_id: userId,
+ api_key_id: (apiKeyId as string | null | undefined) ?? null,
+ oauth_client_id: oauthClientId,
+ auth_type: authType as McpActionLogInput["auth_type"],
+ tool_name: text(payload.tool_name, "tool_name", 128, true)!,
+ status: status as McpActionLogInput["status"],
+ request_id: uuid(payload.request_id, "request_id")!,
+ client_name: text(payload.client_name, "client_name"),
+ client_version: text(payload.client_version, "client_version"),
+ error_class: text(payload.error_class, "error_class"),
+ resource,
+ };
+}
+
+async function exists(query: Promise<unknown[]>) {
+ return (await query).length > 0;
+}
+
+export async function validateMcpActionLogActor(
+ db: any,
+ input: McpActionLogInput,
+) {
+ if (input.auth_type === "api-key" || input.api_key_id != null) {
+ const found = await exists(
+ db
+ .select({ id: schema.api_keys.id })
+ .from(schema.api_keys)
+ .where(
+ and(
+ sql`${schema.api_keys.id} = cast(${input.api_key_id!} as bigint)`,
+ eq(schema.api_keys.team_id, input.team_id),
+ ),
+ )
+ .limit(1),
+ );
+ if (!found) {
+ throw new McpActionLogAuthorizationError(
+ "api_key_id does not belong to team_id",
+ );
+ }
+ }
+ if (input.auth_type === "oauth") {
+ const found = await exists(
+ db
+ .select({ user_id: schema.user_teams.user_id })
+ .from(schema.user_teams)
+ .where(
+ and(
+ eq(schema.user_teams.user_id, input.user_id!),
+ eq(schema.user_teams.team_id, input.team_id),
+ ),
+ )
+ .limit(1),
+ );
+ if (!found) {
+ throw new McpActionLogAuthorizationError(
+ "user_id does not belong to team_id",
+ );
+ }
+ }
+}
+
+export async function resolveMcpActionLogTeamPolicy(db: any, teamId: string) {
+ const rows = await authCreditUsageChunkFromTeam(db, teamId);
+ if (rows.length === 0 || rows[0].team_id === null) return null;
+ return { flags: rows[0].flags ?? null };
+}
+
+async function cleanupExpiredMcpActionLogs(db: any) {
+ await db.execute(sql`
+ with expired as (
+ select id from mcp_action_logs
+ where expires_at <= now()
+ order by expires_at asc
+ limit ${CLEANUP_BATCH_SIZE}
+ )
+ delete from mcp_action_logs
+ where id in (select id from expired)
+ `);
+}
+
+export async function purgeMcpActionLogsForTeam(db: any, teamId: string) {
+ await db
+ .delete(schema.mcp_action_logs)
+ .where(eq(schema.mcp_action_logs.team_id, teamId));
+}
+
+type RetentionTimer = {
+ unref?: () => void;
+};
+
+export function startMcpActionLogRetentionWorker(options: {
+ db: any;
+ intervalMs?: number;
+ setIntervalFn?: (callback: () => void, intervalMs: number) => RetentionTimer;
+ clearIntervalFn?: (timer: RetentionTimer) => void;
+}) {
+ const intervalMs = options.intervalMs ?? 5 * 60 * 1000;
+ const setIntervalFn =
+ options.setIntervalFn ?? ((callback, ms) => setInterval(callback, ms));
+ const clearIntervalFn =
+ options.clearIntervalFn ??
+ (timer => clearInterval(timer as NodeJS.Timeout));
+ let running = false;
+
+ const run = async () => {
+ if (running) return;
+ running = true;
+ try {
+ await cleanupExpiredMcpActionLogs(options.db);
+ } catch (error) {
+ logger.warn("Failed to clean up expired MCP action logs", { error });
+ } finally {
+ running = false;
+ }
+ };
+
+ const timer = setIntervalFn(() => void run(), intervalMs);
+ timer.unref?.();
+ const ready = run();
+
+ return {
+ ready,
+ run,
+ stop: () => clearIntervalFn(timer),
+ };
+}
+
+export function startMcpActionLogRetentionWorkerIfEnabled(options: {
+ enabled: boolean;
+ db: any;
+ intervalMs?: number;
+ setIntervalFn?: (callback: () => void, intervalMs: number) => RetentionTimer;
+ clearIntervalFn?: (timer: RetentionTimer) => void;
+}) {
+ if (!options.enabled) return null;
+ return startMcpActionLogRetentionWorker(options);
+}
+
+export async function recordMcpActionLog(db: any, input: McpActionLogInput) {
+ const expiresAt = new Date(
+ Date.now() + RETENTION_DAYS * 24 * 60 * 60 * 1000,
+ ).toISOString();
+ const rows = await db
+ .insert(schema.mcp_action_logs)
+ .values({
+ ...input,
+ api_key_id:
+ input.api_key_id === null
+ ? null
+ : sql`cast(${input.api_key_id} as bigint)`,
+ expires_at: expiresAt,
+ })
+ .onConflictDoNothing({
+ target: [
+ schema.mcp_action_logs.team_id,
+ schema.mcp_action_logs.request_id,
+ ],
+ })
+ .returning({ id: schema.mcp_action_logs.id });
+ return rows[0]
+ ? { disposition: "stored" as const, id: rows[0].id }
+ : { disposition: "duplicate" as const, id: null };
+}
+
+export async function authorizeMcpActionLogViewer(
+ db: any,
+ teamId: string,
+ apiKeyId: string | number | null | undefined,
+) {
+ const canonicalApiKeyId =
+ typeof apiKeyId === "string"
+ ? isCanonicalApiKeyId(apiKeyId)
+ ? apiKeyId
+ : null
+ : typeof apiKeyId === "number" &&
+ Number.isSafeInteger(apiKeyId) &&
+ apiKeyId > 0
+ ? String(apiKeyId)
+ : null;
+ if (!canonicalApiKeyId) {
+ throw new McpActionLogAuthorizationError(
+ "An owner-bound API key is required",
+ );
+ }
+ const keyRows = await db
+ .select({ owner_id: schema.api_keys.owner_id })
+ .from(schema.api_keys)
+ .where(
+ and(
+ sql`${schema.api_keys.id} = cast(${canonicalApiKeyId} as bigint)`,
+ eq(schema.api_keys.team_id, teamId),
+ ),
+ )
+ .limit(1);
+ const ownerId = keyRows[0]?.owner_id;
+ if (!ownerId) {
+ throw new McpActionLogAuthorizationError(
+ "An owner-bound API key is required",
+ );
+ }
+ const membershipRows = await db
+ .select({ role: schema.user_teams.role })
+ .from(schema.user_teams)
+ .where(
+ and(
+ eq(schema.user_teams.user_id, ownerId),
+ eq(schema.user_teams.team_id, teamId),
+ ),
+ )
+ .limit(1);
+ const role = membershipRows[0]?.role;
+ if (role !== "admin" && role !== "owner") {
+ throw new McpActionLogAuthorizationError("Team admin access is required");
+ }
+ return { userId: ownerId, role };
+}
+
+export function encodeMcpActionLogCursor(row: {
+ created_at: Date | string;
+ id: string;
+}) {
+ const createdAt =
+ row.created_at instanceof Date
+ ? row.created_at.toISOString()
+ : row.created_at;
+ return Buffer.from(
+ JSON.stringify({ created_at: createdAt, id: row.id }),
+ ).toString("base64url");
+}
+
+export function decodeMcpActionLogCursor(cursor: string) {
+ try {
+ const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+ if (
+ typeof value.created_at !== "string" ||
+ Number.isNaN(Date.parse(value.created_at)) ||
+ typeof value.id !== "string" ||
+ !UUID_PATTERN.test(value.id)
+ ) {
+ invalid("cursor is invalid");
+ }
+ return value as { created_at: string; id: string };
+ } catch (error) {
+ if (error instanceof McpActionLogValidationError) throw error;
+ invalid("cursor is invalid");
+ }
+}
+
+export async function listMcpActionLogs(
+ db: any,
+ teamId: string,
+ options: { limit?: number; cursor?: string | null } = {},
+) {
+ const limit = Math.min(Math.max(options.limit ?? 50, 1), 100);
+ const cursor = options.cursor
+ ? decodeMcpActionLogCursor(options.cursor)
+ : null;
+ const cursorClause = cursor
+ ? or(
+ lt(schema.mcp_action_logs.created_at, cursor.created_at),
+ and(
+ eq(schema.mcp_action_logs.created_at, cursor.created_at),
+ lt(schema.mcp_action_logs.id, cursor.id),
+ ),
+ )
+ : undefined;
+ const rows = await db
+ .select({
+ id: schema.mcp_action_logs.id,
+ user_id: schema.mcp_action_logs.user_id,
+ // API-key identifiers are bigint in Postgres. Read them as text so the
+ // JSON boundary never rounds values beyond JavaScript's safe integer range.
+ api_key_id: sql<
+ string | null
+ >`${schema.mcp_action_logs.api_key_id}::text`,
+ oauth_client_id: schema.mcp_action_logs.oauth_client_id,
+ auth_type: schema.mcp_action_logs.auth_type,
+ tool_name: schema.mcp_action_logs.tool_name,
+ status: schema.mcp_action_logs.status,
+ request_id: schema.mcp_action_logs.request_id,
+ client_name: schema.mcp_action_logs.client_name,
+ client_version: schema.mcp_action_logs.client_version,
+ error_class: schema.mcp_action_logs.error_class,
+ resource: schema.mcp_action_logs.resource,
+ created_at: schema.mcp_action_logs.created_at,
+ })
+ .from(schema.mcp_action_logs)
+ .where(
+ and(
+ eq(schema.mcp_action_logs.team_id, teamId),
+ gt(schema.mcp_action_logs.expires_at, new Date().toISOString()),
+ cursorClause,
+ ),
+ )
+ .orderBy(
+ desc(schema.mcp_action_logs.created_at),
+ desc(schema.mcp_action_logs.id),
+ )
+ .limit(limit + 1);
+ return {
+ data: rows.slice(0, limit),
+ nextCursor:
+ rows.length > limit ? encodeMcpActionLogCursor(rows[limit - 1]) : null,
+ };
+}
diff --git a/apps/api/src/services/oauth-token-introspection.test.ts b/apps/api/src/services/oauth-token-introspection.test.ts
new file mode 100644
index 000000000..c9889301d
--- /dev/null
+++ b/apps/api/src/services/oauth-token-introspection.test.ts
@@ -0,0 +1,294 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { getValue, setValue } = vi.hoisted(() => ({
+ getValue: vi.fn(),
+ setValue: vi.fn(),
+}));
+
+vi.mock("./redis", () => ({ getValue, setValue }));
+
+import {
+ FIRECRAWL_REST_RESOURCE,
+ OAuthIntrospectionUnavailableError,
+ resolveOAuthToken,
+} from "./oauth-token-introspection";
+
+const ACTIVE = {
+ active: true,
+ api_key: "fc-11111111111111118111111111111111",
+ scope: "firecrawl:global",
+ client_id: "client-1",
+ team_id: "team-1",
+ exp: Math.floor(Date.now() / 1000) + 3600,
+ aud: FIRECRAWL_REST_RESOURCE,
+ credential_purpose: "general" as const,
+};
+
+function response(body: unknown) {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+}
+
+describe("OAuth token introspection", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ getValue.mockResolvedValue(null);
+ setValue.mockResolvedValue(undefined);
+ });
+
+ it("sends and enforces the expected resource", async () => {
+ const fetchFn = vi
+ .fn()
+ .mockResolvedValue(
+ response({ ...ACTIVE, aud: "https://mcp.firecrawl.dev/v2/mcp" }),
+ );
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+ expect(JSON.parse(fetchFn.mock.calls[0][1].body)).toEqual({
+ token: "fco_token",
+ resource: FIRECRAWL_REST_RESOURCE,
+ });
+ });
+
+ it("keeps legacy audience-less REST tokens compatible", async () => {
+ const { aud: _aud, credential_purpose: _purpose, ...legacy } = ACTIVE;
+ const fetchFn = vi.fn().mockResolvedValue(response(legacy));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toEqual(legacy);
+ });
+
+ it("rejects audience-less managed credentials", async () => {
+ const { aud: _aud, ...managed } = {
+ ...ACTIVE,
+ credential_purpose: "hosted_mcp_oauth" as const,
+ };
+ const fetchFn = vi.fn().mockResolvedValue(response(managed));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+ });
+
+ it("does not positive-cache ordinary credentials", async () => {
+ const fetchFn = vi.fn().mockResolvedValue(response(ACTIVE));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toEqual(ACTIVE);
+ expect(setValue).not.toHaveBeenCalled();
+ });
+
+ it("never positive-caches managed credentials", async () => {
+ const managed = {
+ ...ACTIVE,
+ credential_purpose: "hosted_mcp_oauth" as const,
+ };
+ const fetchFn = vi.fn().mockResolvedValue(response(managed));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toEqual(managed);
+ expect(setValue).not.toHaveBeenCalled();
+ });
+
+ it("ignores stale managed cache entries and re-introspects", async () => {
+ const managed = {
+ ...ACTIVE,
+ credential_purpose: "hosted_mcp_oauth" as const,
+ };
+ getValue.mockResolvedValue(JSON.stringify(managed));
+ const fetchFn = vi.fn().mockResolvedValue(response({ active: false }));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+ expect(fetchFn).toHaveBeenCalledTimes(1);
+ });
+
+ it("ignores an active general cache entry and observes live revocation", async () => {
+ getValue.mockResolvedValue(JSON.stringify(ACTIVE));
+ const fetchFn = vi.fn().mockResolvedValue(response({ active: false }));
+
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+
+ expect(fetchFn).toHaveBeenCalledTimes(1);
+ });
+
+ it("bypasses an unavailable cache and uses live introspection", async () => {
+ getValue.mockRejectedValue(new Error("Redis unavailable"));
+ const fetchFn = vi.fn().mockResolvedValue(response(ACTIVE));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toEqual(ACTIVE);
+ expect(fetchFn).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not fail authentication when a cache write fails", async () => {
+ setValue.mockRejectedValue(new Error("Redis unavailable"));
+ const fetchFn = vi.fn().mockResolvedValue(response({ active: false }));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+ expect(setValue).toHaveBeenCalledTimes(1);
+ });
+
+ it("rejects unknown credential purposes from live introspection", async () => {
+ const fetchFn = vi
+ .fn()
+ .mockResolvedValue(response({ ...ACTIVE, credential_purpose: "admin" }));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).rejects.toBeInstanceOf(OAuthIntrospectionUnavailableError);
+ });
+
+ it("never trusts an unknown credential purpose from cache", async () => {
+ getValue.mockResolvedValue(
+ JSON.stringify({ ...ACTIVE, credential_purpose: "admin" }),
+ );
+ const fetchFn = vi.fn().mockResolvedValue(response({ active: false }));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+ expect(fetchFn).toHaveBeenCalledTimes(1);
+ });
+
+ it("fails closed for expired tokens", async () => {
+ const fetchFn = vi
+ .fn()
+ .mockResolvedValue(
+ response({ ...ACTIVE, exp: Math.floor(Date.now() / 1000) - 1 }),
+ );
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).resolves.toBeNull();
+ });
+
+ it("aborts a stalled introspection request", async () => {
+ vi.useFakeTimers();
+ const fetchFn = vi.fn(
+ (_url: string, init?: RequestInit) =>
+ new Promise<Response>((_resolve, reject) => {
+ init?.signal?.addEventListener("abort", () =>
+ reject(new DOMException("aborted", "AbortError")),
+ );
+ }),
+ );
+ const resolving = resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ });
+ const rejection = expect(resolving).rejects.toBeInstanceOf(
+ OAuthIntrospectionUnavailableError,
+ );
+ await vi.advanceTimersByTimeAsync(10_000);
+ await rejection;
+ vi.useRealTimers();
+ });
+
+ it("distinguishes an unavailable introspection service from an inactive token", async () => {
+ const unavailableFetch = vi.fn().mockResolvedValue(
+ new Response(JSON.stringify({ error: "temporarily_unavailable" }), {
+ status: 503,
+ headers: { "Content-Type": "application/json" },
+ }),
+ );
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn: unavailableFetch,
+ }),
+ ).rejects.toBeInstanceOf(OAuthIntrospectionUnavailableError);
+
+ const inactiveFetch = vi
+ .fn()
+ .mockResolvedValue(response({ active: false }));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn: inactiveFetch,
+ }),
+ ).resolves.toBeNull();
+ });
+
+ it("treats malformed introspection responses as unavailable", async () => {
+ const fetchFn = vi
+ .fn()
+ .mockResolvedValue(response({ ...ACTIVE, active: "true" }));
+ await expect(
+ resolveOAuthToken("fco_token", {
+ introspectUrl: "https://example.test/introspect",
+ introspectSecret: "secret",
+ expectedResource: FIRECRAWL_REST_RESOURCE,
+ fetchFn,
+ }),
+ ).rejects.toBeInstanceOf(OAuthIntrospectionUnavailableError);
+ });
+});
diff --git a/apps/api/src/services/oauth-token-introspection.ts b/apps/api/src/services/oauth-token-introspection.ts
new file mode 100644
index 000000000..a4546f957
--- /dev/null
+++ b/apps/api/src/services/oauth-token-introspection.ts
@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { logger } from "../lib/logger";
+import { getValue, setValue } from "./redis";
+
+const INACTIVE_CACHE_TTL_SECONDS = 60;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export const FIRECRAWL_REST_RESOURCE = "https://api.firecrawl.dev/";
+
+export class OAuthIntrospectionUnavailableError extends Error {
+ constructor(message = "OAuth introspection is temporarily unavailable") {
+ super(message);
+ this.name = "OAuthIntrospectionUnavailableError";
+ }
+}
+
+export interface OAuthIntrospectionResponse {
+ active: boolean;
+ api_key: string;
+ scope: string;
+ client_id: string;
+ team_id: string;
+ exp: number;
+ aud?: string | null;
+ credential_purpose?: "general" | "hosted_mcp_oauth";
+}
+
+type Fetch = (
+ input: string | URL | Request,
+ init?: RequestInit,
+) => Promise<Response>;
+
+function cacheKey(token: string): string {
+ const hash = createHash("sha256").update(token).digest("hex");
+ return `oauth_token:${hash.slice(0, 32)}`;
+}
+
+function hasValidCredentialPurpose(data: OAuthIntrospectionResponse): boolean {
+ const purpose = (data as { credential_purpose?: unknown }).credential_purpose;
+ return (
+ purpose === undefined ||
+ purpose === "general" ||
+ purpose === "hosted_mcp_oauth"
+ );
+}
+
+async function writeCache(
+ key: string,
+ value: string,
+ ttlSeconds: number,
+): Promise<void> {
+ try {
+ await setValue(key, value, ttlSeconds);
+ } catch (error) {
+ // Introspection remains authoritative. A cache outage must not turn a
+ // valid credential into an authentication outage.
+ logger.warn("OAuth introspection cache write failed", { error });
+ }
+}
+
+function hasExpectedAudience(
+ data: OAuthIntrospectionResponse,
+ expectedResource: string,
+): boolean {
+ if (data.aud != null) return data.aud === expectedResource;
+ return (
+ expectedResource === FIRECRAWL_REST_RESOURCE &&
+ data.credential_purpose !== "hosted_mcp_oauth"
+ );
+}
+
+function isUsable(
+ data: OAuthIntrospectionResponse,
+ expectedResource: string,
+): boolean {
+ return (
+ data.active === true &&
+ Number.isFinite(data.exp) &&
+ data.exp > Math.floor(Date.now() / 1000) &&
+ hasExpectedAudience(data, expectedResource)
+ );
+}
+
+function isValidActiveResponse(data: OAuthIntrospectionResponse): boolean {
+ return (
+ data.active === true &&
+ typeof data.api_key === "string" &&
+ /^fc-[0-9a-f]{32}$/i.test(data.api_key) &&
+ typeof data.scope === "string" &&
+ typeof data.client_id === "string" &&
+ data.client_id.length > 0 &&
+ typeof data.team_id === "string" &&
+ data.team_id.length > 0 &&
+ hasValidCredentialPurpose(data) &&
+ Number.isFinite(data.exp)
+ );
+}
+
+export async function resolveOAuthToken(
+ token: string,
+ options: {
+ introspectUrl: string;
+ introspectSecret: string;
+ expectedResource: string;
+ fetchFn?: Fetch;
+ timeoutMs?: number;
+ },
+): Promise<OAuthIntrospectionResponse | null> {
+ const key = cacheKey(token);
+ let cached: string | null = null;
+ try {
+ cached = await getValue(key);
+ } catch (error) {
+ // Treat Redis as an optimization: bypass it and use live introspection.
+ logger.warn("OAuth introspection cache read failed", { error });
+ }
+ if (cached !== null) {
+ try {
+ const parsed = JSON.parse(cached) as OAuthIntrospectionResponse;
+ if (parsed.active !== true) return null;
+ // Active OAuth credentials are always resolved live so revocation,
+ // membership loss, and refresh-token reuse take effect immediately.
+ } catch {
+ // Corrupt cache entries are treated as misses.
+ }
+ }
+
+ const controller = new AbortController();
+ const timeout = setTimeout(
+ () => controller.abort(),
+ options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+ );
+ timeout.unref?.();
+
+ try {
+ const response = await (options.fetchFn ?? fetch)(options.introspectUrl, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ Authorization: `Bearer ${options.introspectSecret}`,
+ },
+ body: JSON.stringify({ token, resource: options.expectedResource }),
+ signal: controller.signal,
+ });
+ if (!response.ok) {
+ logger.error("OAuth introspection request failed", {
+ status: response.status,
+ });
+ throw new OAuthIntrospectionUnavailableError();
+ }
+
+ const data = (await response.json()) as OAuthIntrospectionResponse;
+ if (
+ typeof data.active !== "boolean" ||
+ (data.active === true && !isValidActiveResponse(data))
+ ) {
+ throw new OAuthIntrospectionUnavailableError(
+ "OAuth introspection returned an invalid response",
+ );
+ }
+ if (!isUsable(data, options.expectedResource)) {
+ if (data.active !== true) {
+ await writeCache(
+ key,
+ JSON.stringify({ active: false }),
+ INACTIVE_CACHE_TTL_SECONDS,
+ );
+ }
+ return null;
+ }
+
+ return data;
+ } catch (error) {
+ if (error instanceof OAuthIntrospectionUnavailableError) throw error;
+ logger.error("OAuth introspection error", { error });
+ throw new OAuthIntrospectionUnavailableError();
+ } finally {
+ clearTimeout(timeout);
+ }
+}