Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
Add hosted MCP activity and OAuth revocation (#3973)
Himadri Mishra4f8c82f0762c
diff --git a/apps/api/.env.example b/apps/api/.env.exampleindex 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 keySEARCHAPI_API_KEY=# SearchApi engine, defaults to google. Available options: google, bing, baidu, google_news, etc. Head to https://searchapi.com/ to explore more enginesdiff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex 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 introspectionOAUTH_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.tsindex 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.tsindex 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? - mogeryif (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 chunkconst 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 appattachWsProxy(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 timeoutlogger.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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ }+}