πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
feat(api): add organization API usage endpoint and integrate into existing components
Bill Yang0d0437cf1536
diff --git a/client/src/api/admin/endpoints/auth.ts b/client/src/api/admin/endpoints/auth.tsindex 8925a619f..d45604bbf 100644--- a/client/src/api/admin/endpoints/auth.ts+++ b/client/src/api/admin/endpoints/auth.ts@@ -27,6 +27,23 @@ export function getOrganizationMembers(organizationId: string) {return authedFetch<GetOrganizationMembersResponse>(`/organizations/${organizationId}/members`);}+export type GetOrgApiUsageResponse = {+ /** False on self-hosted, where API requests are not metered. */+ metered: boolean;+ /** False when the counter could not be read; the quota is still enforced. */+ available: boolean;+ dailyUsed: number;+ dailyLimit: number;+ dailyRemaining: number;+ resetsInSeconds: number;+ burstLimit: number;+ burstWindowSeconds: number;+};++export function getOrgApiUsage(organizationId: string) {+ return authedFetch<GetOrgApiUsageResponse>(`/organizations/${organizationId}/api-usage`);+}+export function updateMemberSiteAccess(organizationId: string,memberId: string,diff --git a/client/src/api/admin/endpoints/index.ts b/client/src/api/admin/endpoints/index.tsindex 5e52672ce..f515a0b85 100644--- a/client/src/api/admin/endpoints/index.ts+++ b/client/src/api/admin/endpoints/index.ts@@ -107,8 +107,8 @@ export { getSiteImports, createSiteImport, deleteSiteImport } from "./import";export type { GetSiteImportsResponse, CreateSiteImportResponse } from "./import";// Auth endpoints-export { getOrganizationMembers } from "./auth";-export type { GetOrganizationMembersResponse } from "./auth";+export { getOrganizationMembers, getOrgApiUsage } from "./auth";+export type { GetOrganizationMembersResponse, GetOrgApiUsageResponse } from "./auth";// Teams endpointsexport {diff --git a/client/src/api/admin/hooks/useOrgApiUsage.ts b/client/src/api/admin/hooks/useOrgApiUsage.tsnew file mode 100644index 000000000..328f8e5a1--- /dev/null+++ b/client/src/api/admin/hooks/useOrgApiUsage.ts@@ -0,0 +1,21 @@+import { useQuery } from "@tanstack/react-query";+import { getOrgApiUsage, GetOrgApiUsageResponse } from "../endpoints";++// Today's API request count against the organization's daily quota. Kept+// briefly fresh rather than cached indefinitely: the number moves whenever an+// integration runs, and a stale reading is the one thing that would make the+// card useless.+export const useOrgApiUsage = (organizationId?: string) => {+ return useQuery<GetOrgApiUsageResponse>({+ queryKey: ["org-api-usage", organizationId],+ queryFn: () => {+ if (!organizationId) {+ throw new Error("Organization ID is required");+ }++ return getOrgApiUsage(organizationId);+ },+ staleTime: 60_000,+ enabled: !!organizationId,+ });+};diff --git a/client/src/components/subscription/components/UsageCards.tsx b/client/src/components/subscription/components/UsageCards.tsxindex f7e2c514a..925c85e34 100644--- a/client/src/components/subscription/components/UsageCards.tsx+++ b/client/src/components/subscription/components/UsageCards.tsx@@ -1,24 +1,27 @@import { authClient } from "@/lib/auth";import { useGetSitesFromOrg } from "@/api/admin/hooks/useSites";import { useOrganizationMembers } from "@/api/admin/hooks/useOrganizationMembers";+import { useOrgApiUsage } from "@/api/admin/hooks/useOrgApiUsage";import { useStripeSubscription } from "../../../lib/subscription/useStripeSubscription";interface UsageCardItem {label: string;current: number;limit: number | null;+ /** The count could not be read. Shows a placeholder instead of a false zero. */+ unavailable?: boolean;}-function UsageCard({ label, current, limit }: UsageCardItem) {+function UsageCard({ label, current, limit, unavailable }: UsageCardItem) {const percentage =- limit === null ? 0 : Math.min((current / limit) * 100, 100);- const isExceeded = limit !== null && current >= limit;+ limit === null || unavailable ? 0 : Math.min((current / limit) * 100, 100);+ const isExceeded = !unavailable && limit !== null && current >= limit;return (<div className="rounded-lg border p-3 pb-0 overflow-hidden relative"><div className="text-sm text-muted-foreground">{label}</div><div className="text-lg font-semibold mb-3">- {current.toLocaleString()} /{" "}+ {unavailable ? "β" : current.toLocaleString()} /{" "}{limit === null ? "Unlimited" : limit.toLocaleString()}</div><div className="relative h-1.5 -mx-3">@@ -34,6 +37,13 @@ function UsageCard({ label, current, limit }: UsageCardItem) {);}+// Tailwind only emits classes it can see as literals, so the column count maps+// to a fixed class rather than being interpolated.+const COLUMN_CLASSES: Record<number, string> = {+ 3: "lg:grid-cols-3",+ 4: "lg:grid-cols-4",+};+export function UsageCards() {const { data: subscription } = useStripeSubscription();const { data: activeOrg } = authClient.useActiveOrganization();@@ -41,9 +51,15 @@ export function UsageCards() {const { data: sitesData } = useGetSitesFromOrg(organizationId);const { data: membersData } = useOrganizationMembers(organizationId ?? "");+ const { data: apiUsage } = useOrgApiUsage(organizationId);if (!subscription) return null;+ // Mirrors the server's gate in createApiKey: free and basic plans can't hold+ // API keys, so a quota card would describe a budget they can't spend.+ const planName = subscription.planName || "free";+ const hasApiAccess = planName !== "free" && !planName.includes("basic");+const items: UsageCardItem[] = [{label: "Events used this month",@@ -62,10 +78,22 @@ export function UsageCards() {},];+ // Organization-owned keys only β personal keys are budgeted per user, so+ // their usage isn't part of this number.+ if (hasApiAccess && apiUsage?.metered) {+ items.push({+ label: "Org API requests today",+ current: apiUsage.dailyUsed,+ limit: apiUsage.dailyLimit,+ unavailable: !apiUsage.available,+ });+ }+return (<div- className="grid gap-4"- style={{ gridTemplateColumns: `repeat(${items.length}, minmax(0, 1fr))` }}+ className={`grid grid-cols-1 sm:grid-cols-2 gap-4 ${+ COLUMN_CLASSES[items.length] ?? "lg:grid-cols-4"+ }`}>{items.map((item) => (<UsageCard key={item.label} {...item} />diff --git a/docs/content/docs/api/api-keys/create-org.mdx b/docs/content/docs/api/api-keys/create-org.mdxindex 56cab7a3e..5a8054e89 100644--- a/docs/content/docs/api/api-keys/create-org.mdx+++ b/docs/content/docs/api/api-keys/create-org.mdx@@ -16,7 +16,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';POST /api/organizations/:organizationId/api-keys```-Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, rate limits, and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.+Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, [rate limits](/docs/api/getting-started#rate-limits-cloud-only), and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.<Callout type="warn">You must be an **owner or admin** of the target organization. This endpoint accepts your dashboard **session** or an **unrestricted (full-access) user API key** β scoped keys and organization keys are rejected, so an organization key cannot mint other keys.</Callout>@@ -105,15 +105,15 @@ Returns the created API key object. The full `key` value carries the `rb_org_` ptype: 'string',},rateLimitEnabled: {- description: 'Whether rate limiting is enabled for the key',+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',type: 'boolean',},rateLimitMax: {- description: 'Requests allowed per window',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number',},rateLimitTimeWindow: {- description: 'Window length in milliseconds',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number',},}}@@ -290,9 +290,9 @@ var data = await response.Content.ReadAsStringAsync();"expiresAt": "2026-07-25T12:00:00.000Z","createdAt": "2026-06-25T12:00:00.000Z","updatedAt": "2026-06-25T12:00:00.000Z",- "rateLimitEnabled": true,- "rateLimitMax": 200,- "rateLimitTimeWindow": 60000+ "rateLimitEnabled": false,+ "rateLimitMax": 10,+ "rateLimitTimeWindow": 86400000}```diff --git a/docs/content/docs/api/api-keys/create.mdx b/docs/content/docs/api/api-keys/create.mdxindex 4b0517839..0cadbdbe3 100644--- a/docs/content/docs/api/api-keys/create.mdx+++ b/docs/content/docs/api/api-keys/create.mdx@@ -84,15 +84,15 @@ Returns the created API key object.type: 'string',},rateLimitEnabled: {- description: 'Whether rate limiting is enabled for the key',+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',type: 'boolean',},rateLimitMax: {- description: 'Requests allowed per window',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number',},rateLimitTimeWindow: {- description: 'Window length in milliseconds',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number',},}}@@ -268,13 +268,13 @@ var data = await response.Content.ReadAsStringAsync();"expiresAt": "2026-07-25T12:00:00.000Z","createdAt": "2026-06-25T12:00:00.000Z","updatedAt": "2026-06-25T12:00:00.000Z",- "rateLimitEnabled": true,- "rateLimitMax": 200,- "rateLimitTimeWindow": 60000+ "rateLimitEnabled": false,+ "rateLimitMax": 10,+ "rateLimitTimeWindow": 86400000}```-<Callout>On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. Rate limits are applied automatically based on your plan.</Callout>+<Callout>On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. [Rate limits](/docs/api/getting-started#rate-limits-cloud-only) are charged to **you**, the owning user, and are shared by every personal key you hold across every organization you belong to β creating a key does not add budget, and a plan change applies to keys you already have. For a budget that belongs to the organization instead, create an [organization key](/docs/api/api-keys/create-org).</Callout></div></div>diff --git a/docs/content/docs/api/api-keys/list.mdx b/docs/content/docs/api/api-keys/list.mdxindex 5fb4c2834..e88e1073a 100644--- a/docs/content/docs/api/api-keys/list.mdx+++ b/docs/content/docs/api/api-keys/list.mdx@@ -116,15 +116,15 @@ Returns all API keys owned by the authenticated user, or by a specific organizattype: 'string',},rateLimitEnabled: {- description: 'Whether rate limiting is enabled',+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',type: 'boolean',},rateLimitMax: {- description: 'Requests allowed per window',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number | null',},rateLimitTimeWindow: {- description: 'Window length in milliseconds',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number | null',},requestCount: {@@ -278,9 +278,9 @@ var data = await response.Content.ReadAsStringAsync();"expiresAt": "2026-07-25T12:00:00.000Z","createdAt": "2026-06-25T12:00:00.000Z","updatedAt": "2026-06-25T12:00:00.000Z",- "rateLimitEnabled": true,- "rateLimitMax": 200,- "rateLimitTimeWindow": 60000,+ "rateLimitEnabled": false,+ "rateLimitMax": 10,+ "rateLimitTimeWindow": 86400000,"requestCount": 42,"remaining": null,"lastRequest": "2026-06-25T13:30:00.000Z",diff --git a/docs/content/docs/api/api-keys/update.mdx b/docs/content/docs/api/api-keys/update.mdxindex b90020950..e0fb07981 100644--- a/docs/content/docs/api/api-keys/update.mdx+++ b/docs/content/docs/api/api-keys/update.mdx@@ -47,7 +47,7 @@ Updates mutable fields on an existing API key. The key is identified by its `keyrequired: false,},rateLimitEnabled: {- description: 'Enable or disable rate limiting on the key',+ description: 'Legacy per-key rate limit toggle. Has no effect β [rate limits](/docs/api/getting-started#rate-limits-cloud-only) are enforced per credential owner and follow that owner\'s plan',type: 'boolean',required: false,},@@ -97,15 +97,15 @@ Returns the updated API key object (without the secret key value).type: 'string',},rateLimitEnabled: {- description: 'Whether rate limiting is enabled',+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',type: 'boolean',},rateLimitMax: {- description: 'Requests allowed per window',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number | null',},rateLimitTimeWindow: {- description: 'Window length in milliseconds',+ description: 'Unused legacy field. It is ignored β see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',type: 'number | null',},}}@@ -284,9 +284,9 @@ var data = await response.Content.ReadAsStringAsync();"expiresAt": "2026-07-25T12:00:00.000Z","createdAt": "2026-06-25T12:00:00.000Z","updatedAt": "2026-06-26T12:00:00.000Z",- "rateLimitEnabled": true,- "rateLimitMax": 200,- "rateLimitTimeWindow": 60000+ "rateLimitEnabled": false,+ "rateLimitMax": 10,+ "rateLimitTimeWindow": 86400000}```diff --git a/docs/content/docs/api/getting-started.mdx b/docs/content/docs/api/getting-started.mdxindex 1ace95294..7f9236555 100644--- a/docs/content/docs/api/getting-started.mdx+++ b/docs/content/docs/api/getting-started.mdx@@ -79,15 +79,62 @@ Both kinds support restricting a key to specific permissions when you create it### Rate Limits (Cloud Only)-API key rate limits depend on your plan:+Requests are limited in two ways: a **burst** limit that is the same on every plan, and a **daily quota** that depends on your plan.-| Plan | Limit |-|------|-------|-| **Free / Basic** | API keys not available |-| **Standard** | 20 requests per minute |-| **Pro** | 200 requests per minute |+| Plan | Burst | Daily quota |+|------|-------|-------------|+| **Free / Basic** | API keys not available | β |+| **Standard** | 50 requests per 10 seconds | 5,000 requests per day |+| **Pro** | 50 requests per 10 seconds | 25,000 requests per day |-Self-hosted instances have no rate limits.+The burst limit is a bucket of 50 requests that refills continuously at 5 requests per second. You can spend all 50 at once, then keep going at 5 per second β so short spikes are fine and there is no window boundary to line up with.++The daily quota resets at **00:00 UTC**.++Requests refused by the burst limit don't count against your daily quota.++#### Which budget a request is charged to++Limits apply per **credential owner**, never per key β creating more keys splits an existing budget rather than adding to it:++| Credential | Budget |+|------------|--------|+| **Organization key** (`rb_org_`) | The organization's. All of an organization's keys share it. |+| **Personal key** | Yours. All of your personal keys share one budget, across every organization you belong to. |+| **OAuth token** (MCP) | Yours, the same budget as your personal keys. |++A personal key's quota follows the most generous plan among the organizations you belong to.++Self-hosted instances are not rate limited at all β neither tier applies, and no rate limit headers are sent.++#### Reading your remaining budget++Analytics and management endpoints report your current budget on every response, so you can pace a client without waiting to be rejected:++| Header | Meaning |+|--------|---------|+| `X-RateLimit-Burst-Limit` / `-Remaining` | Burst bucket size and tokens left |+| `X-RateLimit-Burst-Reset` | Seconds until the bucket is full again |+| `X-RateLimit-Daily-Limit` / `-Remaining` | Daily quota and requests left today |+| `X-RateLimit-Daily-Reset` | Seconds until 00:00 UTC |+| `RateLimit-Limit` / `-Remaining` / `-Reset` | Whichever of the two is closest to running out |++Treat these as advisory: a few endpoints resolve credentials outside the standard path and omit them. `Retry-After` on a `429` is always present.++#### When you hit a limit++A `429` names the limit you hit and tells you how long to wait, in seconds:++```json+{+ "error": "Rate limit exceeded",+ "scope": "daily",+ "limit": 5000,+ "retryAfter": 34200+}+```++`scope` is `burst` or `daily`, and the same value is in the `Retry-After` header. The difference matters: a `burst` rejection clears in about a second, while a `daily` one lasts until the quota resets. Back off accordingly rather than retrying straight away.---diff --git a/docs/content/docs/api/live-feed.mdx b/docs/content/docs/api/live-feed.mdxindex 7b0bcf7f8..82f66a636 100644--- a/docs/content/docs/api/live-feed.mdx+++ b/docs/content/docs/api/live-feed.mdx@@ -184,7 +184,7 @@ for (const e of events) {</Tabs><Callout type="warn">-**Mind the rate limits.** On Rybbit Cloud, API keys are capped per minute by plan (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)). A 10-second poll is 6 requests/minute β well within the Standard tier. If you add the live-count call, that's 12/minute. Lengthen the interval or drop the count call if you're close to your limit. Self-hosted instances have no limit.+**Mind the daily quota.** On Rybbit Cloud, a continuous poll is measured against your plan's daily quota (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)), not just its per-second rate. A 10-second poll running around the clock is 8,640 requests/day β over the Standard quota of 5,000, and 17,280 with the live-count call added. Poll every 20-30 seconds, or only while someone is actually watching the page, and check `X-RateLimit-Daily-Remaining` to see where you stand. Self-hosted instances are not rate limited.</Callout>## Next stepsdiff --git a/docs/src/app/[locale]/(home)/features/api/feature-data.tsx b/docs/src/app/[locale]/(home)/features/api/feature-data.tsxindex 92a772954..584ac0d84 100644--- a/docs/src/app/[locale]/(home)/features/api/feature-data.tsx+++ b/docs/src/app/[locale]/(home)/features/api/feature-data.tsx@@ -144,7 +144,7 @@ export const faqItems: FAQItem[] = [{question: "What are the rate limits?",answer:- "On Rybbit Cloud, Standard plans get 20 requests per minute and Pro plans get 200. Self-hosted instances have no rate limits. API keys aren't available on the free tier.",+ "On Rybbit Cloud, every plan can burst 50 requests per 10 seconds, and the daily quota depends on your plan: 5,000 requests a day on Standard, 25,000 on Pro. Limits apply per credential owner β an organization key draws on the organization's budget, and all of your personal keys share yours β so extra keys don't add budget. Self-hosted instances have no rate limits. API keys aren't available on the free tier.",},{question: "Is the API stable?",diff --git a/server/src/api/user/createApiKey.ts b/server/src/api/user/createApiKey.tsindex cc66f5a0c..52c09a519 100644--- a/server/src/api/user/createApiKey.ts+++ b/server/src/api/user/createApiKey.ts@@ -5,7 +5,7 @@ import { auth } from "../../lib/auth.js";import { getSessionFromReq } from "../../lib/auth-utils.js";import { apiKeyPermissionsSchema } from "../../lib/scopes.js";import { getSubscriptionInner } from "../stripe/getSubscription.js";-import { API_RATE_LIMIT_WINDOW, IS_CLOUD, PRO_API_RATE_LIMIT, STANDARD_API_RATE_LIMIT } from "../../lib/const.js";+import { IS_CLOUD } from "../../lib/const.js";const createApiKeyBodySchema = z.object({name: z.string().trim().min(1, "Name is required"),@@ -16,9 +16,10 @@ const createApiKeyBodySchema = z.object({});/**- * Creates an API key with plan-appropriate rate limits and optional scoped- * permissions. On cloud: blocks free/basic, sets standard or pro limits.- * On self-hosted: uses standard limits as default.+ * Creates an API key with optional scoped permissions. On cloud: blocks+ * free/basic plans. Rate limits are not stamped onto the key β they are+ * resolved from the owner's current plan on every request (lib/apiRateLimit.ts),+ * so an upgrade applies to keys that already exist.*/export async function createUserApiKey(request: FastifyRequest<{ Body: { name: string; expiresIn?: number; permissions?: Record<string, string[]> } }>,@@ -36,9 +37,6 @@ export async function createUserApiKey(const { name, expiresIn, permissions } = parsed.data;let planName: string | null = null;- let rateLimitEnabled = false;- let rateLimitMax: number | undefined;- let rateLimitTimeWindow: number | undefined;if (IS_CLOUD) {const activeOrgId = (session.session as any).activeOrganizationId;@@ -54,10 +52,6 @@ export async function createUserApiKey(error: "API keys require a Standard or Pro plan. Please upgrade to create API keys.",});}-- rateLimitEnabled = true;- rateLimitTimeWindow = API_RATE_LIMIT_WINDOW;- rateLimitMax = planName.includes("pro") || planName === "custom" ? PRO_API_RATE_LIMIT : STANDARD_API_RATE_LIMIT;}const keyLimit = apiKeyLimitForPlan(planName);@@ -68,9 +62,6 @@ export async function createUserApiKey(body: {name,expiresIn: expiresIn ?? undefined,- rateLimitEnabled,- rateLimitTimeWindow,- rateLimitMax,userId: session.user.id,...(permissions ? { permissions: permissions as Record<string, string[]> } : {}),},diff --git a/server/src/api/user/createOrgApiKey.ts b/server/src/api/user/createOrgApiKey.tsindex 281e33fa0..8b68af824 100644--- a/server/src/api/user/createOrgApiKey.ts+++ b/server/src/api/user/createOrgApiKey.ts@@ -3,7 +3,7 @@ import { z } from "zod";import { apiKeyLimitForPlan, createApiKeyWithinLimit } from "../../lib/apiKeyLimits.js";import { auth } from "../../lib/auth.js";import { ORG_API_KEY_CONFIG_ID } from "../../lib/bearerAuth.js";-import { API_RATE_LIMIT_WINDOW, IS_CLOUD, PRO_API_RATE_LIMIT, STANDARD_API_RATE_LIMIT } from "../../lib/const.js";+import { IS_CLOUD } from "../../lib/const.js";import { apiKeyPermissionsSchema } from "../../lib/scopes.js";import { getSubscriptionInner } from "../stripe/getSubscription.js";@@ -49,9 +49,6 @@ export async function createOrgApiKey(const { name, expiresIn, permissions } = parsed.data;let planName: string | null = null;- let rateLimitEnabled = false;- let rateLimitMax: number | undefined;- let rateLimitTimeWindow: number | undefined;if (IS_CLOUD) {const subscription = await getSubscriptionInner(organizationId);@@ -62,10 +59,6 @@ export async function createOrgApiKey(error: "API keys require a Standard or Pro plan. Please upgrade to create API keys.",});}-- rateLimitEnabled = true;- rateLimitTimeWindow = API_RATE_LIMIT_WINDOW;- rateLimitMax = planName.includes("pro") || planName === "custom" ? PRO_API_RATE_LIMIT : STANDARD_API_RATE_LIMIT;}const keyLimit = apiKeyLimitForPlan(planName);@@ -80,9 +73,6 @@ export async function createOrgApiKey(organizationId,userId,metadata: { createdBy: userId },- rateLimitEnabled,- rateLimitTimeWindow,- rateLimitMax,...(permissions ? { permissions: permissions as Record<string, string[]> } : {}),},})diff --git a/server/src/api/user/getMyOrganizations.ts b/server/src/api/user/getMyOrganizations.tsindex 0d43d2ed9..94ed4fedb 100644--- a/server/src/api/user/getMyOrganizations.ts+++ b/server/src/api/user/getMyOrganizations.ts@@ -2,13 +2,25 @@ import { FastifyRequest, FastifyReply } from "fastify";import { db } from "../../db/postgres/postgres.js";import { and, eq } from "drizzle-orm";import { member, organization, sites, user } from "../../db/postgres/schema.js";-import { getSessionFromReq, getUserIdFromRequest } from "../../lib/auth-utils.js";+import { getSessionFromReq, getUserIdFromRequest, wasRateLimited } from "../../lib/auth-utils.js";import { filterSitesByMemberAccess } from "../../lib/siteAccess.js";export const getMyOrganizations = async (request: FastifyRequest, reply: FastifyReply) => {try {const userId = await getUserIdFromRequest(request);if (!userId) {+ // This route has no auth pre-handler, so a throttled credential resolves+ // to no user. Reporting that as 401 would tell a caller their key is+ // invalid when it is merely out of budget.+ const throttled = wasRateLimited(request);+ if (throttled) {+ reply.header("Retry-After", throttled.retryAfterSeconds);+ return reply.status(429).send({+ error: "Rate limit exceeded",+ scope: throttled.scope,+ retryAfter: throttled.retryAfterSeconds,+ });+ }return reply.status(401).send({ error: "Unauthorized" });}diff --git a/server/src/api/user/getOrgApiUsage.ts b/server/src/api/user/getOrgApiUsage.tsnew file mode 100644index 000000000..cfa16887a--- /dev/null+++ b/server/src/api/user/getOrgApiUsage.ts@@ -0,0 +1,70 @@+import { FastifyReply, FastifyRequest } from "fastify";+import { dailyQuotaResetSeconds, peekDailyUsage } from "../../lib/apiRateLimit.js";+import { resolveDailyLimit } from "../../lib/apiRateLimitPolicy.js";+import { API_BURST_LIMIT, API_BURST_WINDOW_MS, IS_CLOUD } from "../../lib/const.js";++export interface OrgApiUsageResponse {+ /** False on self-hosted, where API requests are not metered. */+ metered: boolean;+ /**+ * False when the counter could not be read (Redis unavailable). The quota is+ * still being enforced; only this reading is missing, and callers should say+ * so rather than render a zero.+ */+ available: boolean;+ dailyUsed: number;+ dailyLimit: number;+ dailyRemaining: number;+ /** Seconds until the quota resets at 00:00 UTC. */+ resetsInSeconds: number;+ burstLimit: number;+ burstWindowSeconds: number;+}++/**+ * Today's API request usage for an organization's own API keys.+ *+ * Covers organization-owned keys only. Personal keys are budgeted per user+ * (that is the bucket they are charged against), so their usage is not part of+ * this number.+ */+export async function getOrgApiUsage(+ request: FastifyRequest<{ Params: { organizationId: string } }>,+ reply: FastifyReply+) {+ const { organizationId } = request.params;++ if (!IS_CLOUD) {+ return reply.send({+ metered: false,+ available: true,+ dailyUsed: 0,+ dailyLimit: 0,+ dailyRemaining: 0,+ resetsInSeconds: dailyQuotaResetSeconds(),+ burstLimit: API_BURST_LIMIT,+ burstWindowSeconds: API_BURST_WINDOW_MS / 1000,+ } satisfies OrgApiUsageResponse);+ }++ try {+ const [dailyLimit, dailyUsed] = await Promise.all([+ resolveDailyLimit({ organizationId }),+ peekDailyUsage(organizationId),+ ]);++ return reply.send({+ metered: true,+ available: dailyUsed !== null,+ dailyUsed: dailyUsed ?? 0,+ dailyLimit,+ dailyRemaining: Math.max(dailyLimit - (dailyUsed ?? 0), 0),+ resetsInSeconds: dailyQuotaResetSeconds(),+ burstLimit: API_BURST_LIMIT,+ burstWindowSeconds: API_BURST_WINDOW_MS / 1000,+ } satisfies OrgApiUsageResponse);+ } catch (error) {+ request.log.error({ err: error, organizationId }, "Failed to read API usage");+ return reply.status(500).send({ error: "Failed to fetch API usage" });+ }+}diff --git a/server/src/api/user/index.ts b/server/src/api/user/index.tsindex 94be35394..96eff4ada 100644--- a/server/src/api/user/index.ts+++ b/server/src/api/user/index.ts@@ -12,4 +12,5 @@ export { unsubscribeMarketing, oneClickUnsubscribeMarketing } from "./unsubscrib// API Keysexport { createUserApiKey } from "./createApiKey.js";export { createOrgApiKey } from "./createOrgApiKey.js";+export { getOrgApiUsage } from "./getOrgApiUsage.js";diff --git a/server/src/db/redis/apiRateLimit.integration.test.ts b/server/src/db/redis/apiRateLimit.integration.test.tsnew file mode 100644index 000000000..6884453dc--- /dev/null+++ b/server/src/db/redis/apiRateLimit.integration.test.ts@@ -0,0 +1,178 @@+import RedisMock from "ioredis-mock";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { API_RATE_LIMIT_LUA } from "./apiRateLimitLua.js";++// Behavioral tests for the rate limiter Lua, executed for real by ioredis-mock's+// embedded Lua runtime. The interaction between the two tiers β which one denies+// first, and which one gets charged when the other denies β only exists inside+// the script, so TS-level mocks cannot cover it.++const BURST_CAPACITY = 50;+const BURST_REFILL_PER_SECOND = 5;+const DAILY_LIMIT = 100;+const DAILY_TTL = 90_000;++const BURST_KEY = "rl:burst:org1";+const DAILY_KEY = "rl:day:org1:20000";++interface LimiterMockRedis {+ apiRateLimit(...args: (string | number)[]): Promise<[number, number, number, number, number]>;+ get(key: string): Promise<string | null>;+ ttl(key: string): Promise<number>;+ flushall(): Promise<unknown>;+}++let redis: LimiterMockRedis;++function consume(opts: { dailyLimit?: number; observe?: boolean } = {}) {+ return redis.apiRateLimit(+ BURST_KEY,+ DAILY_KEY,+ BURST_CAPACITY,+ BURST_REFILL_PER_SECOND,+ opts.dailyLimit ?? DAILY_LIMIT,+ DAILY_TTL,+ opts.observe ? 1 : 0+ );+}++async function consumeTimes(count: number, opts: { dailyLimit?: number; observe?: boolean } = {}) {+ let last: [number, number, number, number, number] | undefined;+ for (let i = 0; i < count; i++) {+ last = await consume(opts);+ }+ return last!;+}++describe("apiRateLimit Lua script", () => {+ beforeEach(async () => {+ vi.useFakeTimers();+ vi.setSystemTime(new Date("2024-05-01T12:00:00Z"));+ const client = new RedisMock();+ client.defineCommand("apiRateLimit", { numberOfKeys: 2, lua: API_RATE_LIMIT_LUA });+ redis = client as unknown as LimiterMockRedis;+ await redis.flushall();+ });++ afterEach(() => {+ vi.useRealTimers();+ });++ it("admits a full bucket in one spike and reports the remaining tokens", async () => {+ const [allowed, scope, burstRemaining, dailyRemaining] = await consume();++ expect(allowed).toBe(1);+ expect(scope).toBe(0);+ expect(burstRemaining).toBe(BURST_CAPACITY - 1);+ expect(dailyRemaining).toBe(DAILY_LIMIT - 1);++ const [lastAllowed, lastScope, lastRemaining] = await consumeTimes(BURST_CAPACITY - 1);+ expect(lastAllowed).toBe(1);+ expect(lastScope).toBe(0);+ expect(lastRemaining).toBe(0);+ });++ it("denies on the burst tier once the bucket is drained", async () => {+ await consumeTimes(BURST_CAPACITY);++ const [allowed, scope, burstRemaining, , retryAfterMs] = await consume();++ expect(allowed).toBe(0);+ expect(scope).toBe(1);+ expect(burstRemaining).toBe(0);+ expect(retryAfterMs).toBeGreaterThan(0);+ expect(retryAfterMs).toBeLessThanOrEqual(1000 / BURST_REFILL_PER_SECOND);+ });++ it("refills the bucket continuously rather than at a window boundary", async () => {+ await consumeTimes(BURST_CAPACITY);+ expect((await consume())[0]).toBe(0);++ // One second at 5 tokens/s buys 5 requests, not a whole new window.+ vi.advanceTimersByTime(1000);++ const admitted = [];+ for (let i = 0; i < 6; i++) {+ admitted.push((await consume())[0]);+ }+ expect(admitted).toEqual([1, 1, 1, 1, 1, 0]);+ });++ it("restores at most a full bucket no matter how long it sits idle", async () => {+ await consumeTimes(BURST_CAPACITY);+ vi.advanceTimersByTime(60 * 60 * 1000);++ const [, , burstRemaining] = await consume();+ expect(burstRemaining).toBe(BURST_CAPACITY - 1);+ });++ it("denies on the daily tier without charging the burst bucket", async () => {+ // Drain the quota, refilling the burst bucket between spikes.+ for (let batch = 0; batch < 2; batch++) {+ await consumeTimes(BURST_CAPACITY);+ vi.advanceTimersByTime(BURST_CAPACITY / BURST_REFILL_PER_SECOND * 1000);+ }++ const [allowed, scope, burstRemaining, dailyRemaining] = await consume();++ expect(allowed).toBe(0);+ expect(scope).toBe(2);+ expect(dailyRemaining).toBe(0);+ // The refused request must not cost a burst token: an exhausted quota would+ // otherwise keep draining a budget the caller can no longer spend.+ expect(burstRemaining).toBe(BURST_CAPACITY);+ expect(await redis.get(DAILY_KEY)).toBe(String(DAILY_LIMIT));+ });++ it("reports the daily tier ahead of the burst tier when both are exhausted", async () => {+ // Two full spikes with one refill between them lands on the quota and the+ // empty bucket at the same instant.+ await consumeTimes(BURST_CAPACITY);+ vi.advanceTimersByTime((BURST_CAPACITY / BURST_REFILL_PER_SECOND) * 1000);+ await consumeTimes(BURST_CAPACITY);++ const [allowed, scope, burstRemaining] = await consume();++ expect(allowed).toBe(0);+ expect(burstRemaining).toBe(0);+ // Both tiers would deny, but daily is the one worth reporting: it is the+ // limit the caller has to wait hours rather than milliseconds for.+ expect(scope).toBe(2);+ });++ it("does not charge the quota for a request the burst tier refused", async () => {+ await consumeTimes(BURST_CAPACITY);+ await consumeTimes(10);++ // Only the admitted requests count toward the daily quota β a client stuck+ // in a retry loop must not burn its whole day against a closed burst gate.+ expect(await redis.get(DAILY_KEY)).toBe(String(BURST_CAPACITY));+ });++ it("expires the daily counter so the quota resets by key rollover", async () => {+ await consume();+ expect(await redis.ttl(DAILY_KEY)).toBeGreaterThan(0);+ expect(await redis.ttl(DAILY_KEY)).toBeLessThanOrEqual(DAILY_TTL);+ });++ it("treats a daily limit of 0 as unlimited", async () => {+ const [allowed, scope, , dailyRemaining] = await consume({ dailyLimit: 0 });++ expect(allowed).toBe(1);+ expect(scope).toBe(0);+ expect(dailyRemaining).toBe(-1);+ expect(await redis.get(DAILY_KEY)).toBeNull();+ });++ it("counts but never denies in observe mode", async () => {+ await consumeTimes(BURST_CAPACITY, { observe: true });++ const [allowed, scope] = await consume({ observe: true });++ // The caller still learns it would have been denied, and the daily total+ // keeps climbing so a shadow run measures real traffic.+ expect(allowed).toBe(0);+ expect(scope).toBe(1);+ expect(await redis.get(DAILY_KEY)).toBe(String(BURST_CAPACITY + 1));+ });+});diff --git a/server/src/db/redis/apiRateLimitLua.ts b/server/src/db/redis/apiRateLimitLua.tsnew file mode 100644index 000000000..dcb1e213b--- /dev/null+++ b/server/src/db/redis/apiRateLimitLua.ts@@ -0,0 +1,97 @@+/**+ * Two-tier API rate limiter: a token-bucket burst guard and a UTC-day quota,+ * evaluated and committed in one atomic round trip.+ *+ * Both tiers are checked *before* either is charged, so a request refused on+ * quota never also drains the burst bucket β otherwise a client stuck at its+ * daily limit would keep paying burst tokens for requests it can't make, and+ * `RateLimit-Remaining` would report a burst budget that no longer exists.+ *+ * `TIME` makes the script non-deterministic, which Redis permits alongside+ * writes under effects replication (the default since 5.0). Reading the clock+ * inside Redis rather than passing it from Node keeps every app instance on one+ * clock, so skew between instances cannot refill a bucket early.+ *+ * KEYS[1] burst bucket, a hash of { tokens, ts }+ * KEYS[2] daily counter for the current UTC day (the day is part of the key,+ * so the reset is a natural key rollover rather than a scheduled wipe)+ *+ * ARGV[1] burst capacity (tokens)+ * ARGV[2] burst refill rate (tokens per second)+ * ARGV[3] daily limit, 0 = unlimited+ * ARGV[4] TTL in seconds for the daily counter+ * ARGV[5] 1 = observe only: account for the request but never deny it+ *+ * Returns { allowed, scope, burstRemaining, dailyRemaining, retryAfterMs }+ * where scope is 0 = none, 1 = burst, 2 = daily and dailyRemaining is -1 when+ * the daily tier is unlimited.+ */+export const API_RATE_LIMIT_LUA = `+local capacity = tonumber(ARGV[1])+local refill = tonumber(ARGV[2])+local dailyLimit = tonumber(ARGV[3])+local dailyTtl = tonumber(ARGV[4])+local observe = tonumber(ARGV[5]) == 1++local time = redis.call('TIME')+local now = tonumber(time[1]) + tonumber(time[2]) / 1000000++local dailyUsed = 0+if dailyLimit > 0 then+ dailyUsed = tonumber(redis.call('GET', KEYS[2])) or 0+end+local dailyExceeded = dailyLimit > 0 and dailyUsed >= dailyLimit++local bucket = redis.call('HMGET', KEYS[1], 'tokens', 'ts')+local tokens = tonumber(bucket[1])+local ts = tonumber(bucket[2])+if tokens == nil or ts == nil then+ tokens = capacity+else+ tokens = math.min(capacity, tokens + (now - ts) * refill)+end+local burstExceeded = tokens < 1++local allowed = not dailyExceeded and not burstExceeded++-- Charge the request when it is allowed, and always in observe mode: shadow+-- runs are only useful if their daily totals match the traffic that would have+-- been counted under enforcement.+if allowed or observe then+ if not burstExceeded then+ tokens = tokens - 1+ end+ redis.call('HSET', KEYS[1], 'tokens', tokens, 'ts', now)+ -- Outlive a full refill so an idle owner's bucket expires instead of+ -- lingering; a missing bucket is indistinguishable from a full one.+ redis.call('PEXPIRE', KEYS[1], math.ceil(capacity / refill * 1000) + 1000)+ if dailyLimit > 0 then+ dailyUsed = redis.call('INCR', KEYS[2])+ if dailyUsed == 1 then+ redis.call('EXPIRE', KEYS[2], dailyTtl)+ end+ end+end++local scope = 0+local retryAfterMs = 0+if dailyExceeded then+ scope = 2+elseif burstExceeded then+ scope = 1+ retryAfterMs = math.ceil((1 - tokens) / refill * 1000)+end++local dailyRemaining = -1+if dailyLimit > 0 then+ dailyRemaining = math.max(dailyLimit - dailyUsed, 0)+end++return {+ allowed and 1 or 0,+ scope,+ math.floor(math.max(tokens, 0)),+ dailyRemaining,+ retryAfterMs,+}+`;diff --git a/server/src/db/redis/redis.ts b/server/src/db/redis/redis.tsindex 10789bc23..bccc2018b 100644--- a/server/src/db/redis/redis.ts+++ b/server/src/db/redis/redis.ts@@ -1,5 +1,6 @@import { Redis } from "ioredis";import { createServiceLogger } from "../../lib/logger/logger.js";+import { API_RATE_LIMIT_LUA } from "./apiRateLimitLua.js";import { STICKY_RESOLVE_LUA } from "./stickyResolveLua.js";const logger = createServiceLogger("redis");@@ -156,6 +157,61 @@ export function stickyResolve(input: StickyResolveInput): Promise<[string, Stick);}+// Dedicated connection for API-key rate limiting, isolated for the same reason+// as `sessionRedis`: every authenticated API request runs this script, and a+// shared connection would put it behind the heavier anomaly Lua call.+export const apiRateLimitRedis = createRedisClient("api-rate-limit");++apiRateLimitRedis.defineCommand("apiRateLimit", {+ numberOfKeys: 2,+ lua: API_RATE_LIMIT_LUA,+});++interface ApiRateLimitRedis extends Redis {+ apiRateLimit(...args: (string | number)[]): Promise<[number, number, number, number, number]>;+}++export interface ApiRateLimitInput {+ burstKey: string;+ dailyKey: string;+ burstCapacity: number;+ /** Tokens restored per second; capacity/refillPerSecond is the drain time. */+ burstRefillPerSecond: number;+ /** 0 = unlimited (self-hosted). */+ dailyLimit: number;+ dailyTtlSeconds: number;+ observeOnly: boolean;+}++export interface ApiRateLimitResult {+ allowed: boolean;+ /** 0 = within limits, 1 = burst tier, 2 = daily tier. */+ scope: number;+ burstRemaining: number;+ /** -1 when the daily tier is unlimited. */+ dailyRemaining: number;+ retryAfterMs: number;+}++/**+ * Charge one request against an owner's burst bucket and daily quota. Atomic+ * across all workers and replicas; one round-trip.+ */+export async function apiRateLimitConsume(input: ApiRateLimitInput): Promise<ApiRateLimitResult> {+ const [allowed, scope, burstRemaining, dailyRemaining, retryAfterMs] = await (+ apiRateLimitRedis as ApiRateLimitRedis+ ).apiRateLimit(+ input.burstKey,+ input.dailyKey,+ input.burstCapacity,+ input.burstRefillPerSecond,+ input.dailyLimit,+ input.dailyTtlSeconds,+ input.observeOnly ? 1 : 0+ );+ return { allowed: allowed === 1, scope, burstRemaining, dailyRemaining, retryAfterMs };+}+// Rolling-window counters for the bot anomaly scorer. Each counter is a sorted// set: member -> observation, score -> time (ms). For event-rate counters the// member is a unique per-event token (so cardinality == event count); fordiff --git a/server/src/index.ts b/server/src/index.tsindex a0c261dca..a9016b3bb 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -150,6 +150,7 @@ import {createUserApiKey,createUserInOrganization,getMyOrganizations,+ getOrgApiUsage,getUserOrganizations,listOrganizationMembers,oneClickUnsubscribeMarketing,@@ -489,6 +490,7 @@ async function userRoutes(fastify: FastifyInstance) {fastify.post("/user/unsubscribe-marketing-oneclick", oneClickUnsubscribeMarketing); // Public - for List-Unsubscribe headerfastify.post("/user/api-keys", authOnlyNoScopedKeys, createUserApiKey);fastify.post("/organizations/:organizationId/api-keys", orgAdminNoScopedKeys, createOrgApiKey);+ fastify.get("/organizations/:organizationId/api-usage", orgOrgRead, getOrgApiUsage);}async function gscRoutes(fastify: FastifyInstance) {diff --git a/server/src/lib/apiRateLimit.test.ts b/server/src/lib/apiRateLimit.test.tsnew file mode 100644index 000000000..f4185b73e--- /dev/null+++ b/server/src/lib/apiRateLimit.test.ts@@ -0,0 +1,140 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++const apiRateLimitConsume = vi.fn();++vi.mock("../db/redis/redis.js", () => ({ apiRateLimitConsume }));+vi.mock("./const.js", async importOriginal => ({+ ...(await importOriginal<typeof import("./const.js")>()),+ IS_CLOUD: true,+}));+vi.mock("./logger/logger.js", () => ({+ createServiceLogger: () => ({ warn: vi.fn(), info: vi.fn(), error: vi.fn(), debug: vi.fn() }),+}));++const { consumeApiRateLimit, dailyLimitForPlan } = await import("./apiRateLimit.js");+const { API_BURST_LIMIT, PRO_API_DAILY_LIMIT, STANDARD_API_DAILY_LIMIT } = await import("./const.js");++const redisResult = (overrides: Record<string, unknown> = {}) => ({+ allowed: true,+ scope: 0,+ burstRemaining: 49,+ dailyRemaining: 4999,+ retryAfterMs: 0,+ ...overrides,+});++describe("dailyLimitForPlan", () => {+ it("gives Pro and custom plans the higher quota", () => {+ expect(dailyLimitForPlan("pro")).toBe(PRO_API_DAILY_LIMIT);+ expect(dailyLimitForPlan("pro-annual")).toBe(PRO_API_DAILY_LIMIT);+ expect(dailyLimitForPlan("custom")).toBe(PRO_API_DAILY_LIMIT);+ });++ it("gives every other plan the standard quota", () => {+ expect(dailyLimitForPlan("standard")).toBe(STANDARD_API_DAILY_LIMIT);+ expect(dailyLimitForPlan("free")).toBe(STANDARD_API_DAILY_LIMIT);+ expect(dailyLimitForPlan(null)).toBe(STANDARD_API_DAILY_LIMIT);+ expect(dailyLimitForPlan(undefined)).toBe(STANDARD_API_DAILY_LIMIT);+ });+});++describe("consumeApiRateLimit", () => {+ beforeEach(() => {+ apiRateLimitConsume.mockReset();+ vi.useFakeTimers();+ vi.setSystemTime(new Date("2024-05-01T23:00:00Z"));+ });++ afterEach(() => {+ vi.useRealTimers();+ });++ it("keys the budget on the owner and the current UTC day", async () => {+ apiRateLimitConsume.mockResolvedValue(redisResult());++ await consumeApiRateLimit("org1", 5000);++ expect(apiRateLimitConsume).toHaveBeenCalledWith(+ expect.objectContaining({ burstKey: "rl:burst:org1", dailyKey: `rl:day:org1:${Math.floor(Date.UTC(2024, 4, 1, 23) / 86_400_000)}` })+ );+ });++ it("reports a daily denial as retriable at the next UTC midnight", async () => {+ apiRateLimitConsume.mockResolvedValue(redisResult({ allowed: false, scope: 2, dailyRemaining: 0 }));++ const decision = await consumeApiRateLimit("org1", 5000);++ expect(decision.allowed).toBe(false);+ expect(decision.scope).toBe("daily");+ expect(decision.retryAfterSeconds).toBe(3600);+ expect(decision.dailyResetSeconds).toBe(3600);+ });++ it("rounds a sub-second burst denial up to one second", async () => {+ apiRateLimitConsume.mockResolvedValue(+ redisResult({ allowed: false, scope: 1, burstRemaining: 0, retryAfterMs: 200 })+ );++ const decision = await consumeApiRateLimit("org1", 5000);++ // Retry-After is in whole seconds; rounding down to 0 would invite an+ // immediate retry that is guaranteed to fail again.+ expect(decision.scope).toBe("burst");+ expect(decision.retryAfterSeconds).toBe(1);+ });++ it("falls back to in-process counters when Redis is unreachable", async () => {+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));++ const first = await consumeApiRateLimit("fallback-owner", 5000);+ expect(first.allowed).toBe(true);+ expect(first.burstRemaining).toBe(API_BURST_LIMIT - 1);++ for (let i = 1; i < API_BURST_LIMIT; i++) {+ await consumeApiRateLimit("fallback-owner", 5000);+ }++ // The burst ceiling still holds per instance β the tier that protects the+ // database survives a Redis outage even though the accounting is degraded.+ const denied = await consumeApiRateLimit("fallback-owner", 5000);+ expect(denied.allowed).toBe(false);+ expect(denied.scope).toBe("burst");+ });++ it("enforces the daily quota in the fallback too", async () => {+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));++ for (let i = 0; i < 3; i++) {+ await consumeApiRateLimit("fallback-quota", 3);+ }++ const denied = await consumeApiRateLimit("fallback-quota", 3);+ expect(denied.allowed).toBe(false);+ expect(denied.scope).toBe("daily");+ expect(denied.dailyRemaining).toBe(0);+ });++ it("treats a zero daily limit as unlimited in the fallback", async () => {+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));++ const decision = await consumeApiRateLimit("fallback-selfhosted", 0);++ expect(decision.allowed).toBe(true);+ expect(decision.dailyLimit).toBe(0);+ });++ // Declaration order matters: this trips the shared breaker, so it runs last.+ it("stops calling Redis after a run of failures", async () => {+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));++ for (let i = 0; i < 5; i++) {+ await consumeApiRateLimit("breaker-owner", 5000);+ }+ const callsDuringOutage = apiRateLimitConsume.mock.calls.length;+ await consumeApiRateLimit("breaker-owner", 5000);++ // Every request would otherwise pay the full Redis command timeout, adding+ // a second of latency to the entire API for the length of an outage.+ expect(apiRateLimitConsume.mock.calls.length).toBe(callsDuringOutage);+ });+});diff --git a/server/src/lib/apiRateLimit.ts b/server/src/lib/apiRateLimit.tsnew file mode 100644index 000000000..f5a15e7ff--- /dev/null+++ b/server/src/lib/apiRateLimit.ts@@ -0,0 +1,250 @@+import { apiRateLimitConsume, apiRateLimitRedis } from "../db/redis/redis.js";+import {+ API_BURST_LIMIT,+ API_BURST_WINDOW_MS,+ API_RATE_LIMIT_OBSERVE_ONLY,+ IS_CLOUD,+ PRO_API_DAILY_LIMIT,+ STANDARD_API_DAILY_LIMIT,+} from "./const.js";+import { createServiceLogger } from "./logger/logger.js";++const logger = createServiceLogger("api-rate-limit");++const MS_PER_DAY = 86_400_000;+const BURST_REFILL_PER_SECOND = API_BURST_LIMIT / (API_BURST_WINDOW_MS / 1000);+// Long enough that the counter survives clock skew around the rollover, short+// enough that yesterday's keys are gone well before they matter.+const DAILY_TTL_SECONDS = 90_000;++export type RateLimitScope = "burst" | "daily";++export interface RateLimitDecision {+ /** Whether the request may proceed. Always true in observe-only mode. */+ allowed: boolean;+ /** True when observe-only mode admitted a request the limits would have denied. */+ wouldHaveDenied: boolean;+ /** Which tier bound the request; null when it was within both. */+ scope: RateLimitScope | null;+ burstLimit: number;+ burstRemaining: number;+ /** Seconds until the burst bucket is full again. */+ burstResetSeconds: number;+ /** 0 when the daily tier is unlimited (self-hosted). */+ dailyLimit: number;+ dailyRemaining: number;+ /** Seconds until the next UTC midnight. */+ dailyResetSeconds: number;+ /** Seconds until the binding tier admits another request. 0 when allowed. */+ retryAfterSeconds: number;+}++/**+ * The daily quota for a plan. Mirrors `apiKeyLimitForPlan`'s plan matching so+ * the two limits can never disagree about what counts as Pro. Self-hosted is+ * unlimited (0), as it has no plans and no shared infrastructure to protect.+ */+export function dailyLimitForPlan(planName: string | null | undefined): number {+ if (!IS_CLOUD) {+ return 0;+ }+ const plan = planName || "free";+ return plan.includes("pro") || plan === "custom" ? PRO_API_DAILY_LIMIT : STANDARD_API_DAILY_LIMIT;+}++/** UTC day number. Part of the daily key, so the quota resets by key rollover. */+function utcDay(now: number): number {+ return Math.floor(now / MS_PER_DAY);+}++/**+ * Today's request count for an owner, without charging one. Returns null when+ * the counter can't be read, so callers can say "unavailable" rather than+ * showing a confident zero.+ */+export async function peekDailyUsage(ownerId: string): Promise<number | null> {+ const now = Date.now();+ if (breakerIsOpen(now)) {+ return null;+ }+ try {+ const used = await apiRateLimitRedis.get(`rl:day:${ownerId}:${utcDay(now)}`);+ return used === null ? 0 : Number(used);+ } catch {+ return null;+ }+}++/** Seconds until the daily quota resets, for callers reporting usage. */+export function dailyQuotaResetSeconds(): number {+ return secondsUntilUtcMidnight(Date.now());+}++function secondsUntilUtcMidnight(now: number): number {+ return Math.ceil(((utcDay(now) + 1) * MS_PER_DAY - now) / 1000);+}++/**+ * Per-instance fallback used only while Redis is unreachable. It sees one+ * instance's share of traffic, so N instances allow up to N times the limits β+ * a deliberate trade: degraded accounting never blocks a legitimate request,+ * and the burst ceiling still holds per instance, which is the tier that+ * protects the database.+ */+interface FallbackState {+ tokens: number;+ ts: number;+ day: number;+ dailyUsed: number;+}++const fallbackState = new Map<string, FallbackState>();+const FALLBACK_MAX_OWNERS = 10_000;++// Redis commands time out after a second. Paying that on every request for the+// length of an outage would add a second of latency to the whole API, so a run+// of failures parks the limiter on the in-process path and it retries only+// occasionally.+const BREAKER_FAILURE_THRESHOLD = 5;+const BREAKER_COOLDOWN_MS = 10_000;+let consecutiveFailures = 0;+let breakerOpenUntil = 0;++function breakerIsOpen(now: number): boolean {+ return now < breakerOpenUntil;+}++function recordRedisFailure(now: number): void {+ consecutiveFailures += 1;+ if (consecutiveFailures >= BREAKER_FAILURE_THRESHOLD) {+ breakerOpenUntil = now + BREAKER_COOLDOWN_MS;+ }+}++function recordRedisSuccess(): void {+ consecutiveFailures = 0;+ breakerOpenUntil = 0;+}++function pruneFallbackState(now: number): void {+ if (fallbackState.size <= FALLBACK_MAX_OWNERS) {+ return;+ }+ const today = utcDay(now);+ for (const [owner, state] of fallbackState) {+ // A full bucket carries no information, so an idle owner can be dropped.+ if (state.day !== today || (state.tokens >= API_BURST_LIMIT && now - state.ts > API_BURST_WINDOW_MS)) {+ fallbackState.delete(owner);+ }+ }+ // If that freed nothing, evict least-recently-seen owners instead of clearing+ // the map: wiping every counter at once would hand a full budget back to+ // everybody, turning the memory bound into a way around the limiter.+ if (fallbackState.size > FALLBACK_MAX_OWNERS) {+ const byAge = [...fallbackState.entries()].sort((a, b) => a[1].ts - b[1].ts);+ for (const [owner] of byAge.slice(0, fallbackState.size - FALLBACK_MAX_OWNERS)) {+ fallbackState.delete(owner);+ }+ }+}++function consumeInProcess(ownerId: string, dailyLimit: number, now: number): RateLimitDecision {+ pruneFallbackState(now);+ const today = utcDay(now);+ const state = fallbackState.get(ownerId);+ const bucket: FallbackState =+ !state || state.day !== today+ ? { tokens: API_BURST_LIMIT, ts: now, day: today, dailyUsed: 0 }+ : {+ ...state,+ tokens: Math.min(API_BURST_LIMIT, state.tokens + ((now - state.ts) / 1000) * BURST_REFILL_PER_SECOND),+ ts: now,+ };++ const dailyExceeded = dailyLimit > 0 && bucket.dailyUsed >= dailyLimit;+ const burstExceeded = bucket.tokens < 1;+ const allowed = !dailyExceeded && !burstExceeded;++ if (allowed || API_RATE_LIMIT_OBSERVE_ONLY) {+ if (!burstExceeded) {+ bucket.tokens -= 1;+ }+ bucket.dailyUsed += 1;+ }+ fallbackState.set(ownerId, bucket);++ return buildDecision({+ allowed,+ scope: dailyExceeded ? 2 : burstExceeded ? 1 : 0,+ burstRemaining: Math.floor(Math.max(bucket.tokens, 0)),+ dailyRemaining: dailyLimit > 0 ? Math.max(dailyLimit - bucket.dailyUsed, 0) : -1,+ retryAfterMs: burstExceeded ? Math.ceil(((1 - bucket.tokens) / BURST_REFILL_PER_SECOND) * 1000) : 0,+ dailyLimit,+ now,+ });+}++function buildDecision(input: {+ allowed: boolean;+ scope: number;+ burstRemaining: number;+ dailyRemaining: number;+ retryAfterMs: number;+ dailyLimit: number;+ now: number;+}): RateLimitDecision {+ const scope: RateLimitScope | null = input.scope === 2 ? "daily" : input.scope === 1 ? "burst" : null;+ const dailyResetSeconds = secondsUntilUtcMidnight(input.now);+ return {+ allowed: input.allowed || API_RATE_LIMIT_OBSERVE_ONLY,+ wouldHaveDenied: !input.allowed,+ scope,+ burstLimit: API_BURST_LIMIT,+ burstRemaining: input.burstRemaining,+ burstResetSeconds: Math.ceil((API_BURST_LIMIT - input.burstRemaining) / BURST_REFILL_PER_SECOND),+ dailyLimit: input.dailyLimit,+ dailyRemaining: Math.max(input.dailyRemaining, 0),+ dailyResetSeconds,+ retryAfterSeconds:+ scope === "daily"+ ? dailyResetSeconds+ : scope === "burst"+ ? Math.max(Math.ceil(input.retryAfterMs / 1000), 1)+ : 0,+ };+}++/**+ * Charge one request against an owner's budget and report the outcome.+ *+ * `ownerId` is the credential's owner β an organization id for org keys, a user+ * id for user keys β never the key id, so an org cannot widen its budget by+ * minting more keys.+ */+export async function consumeApiRateLimit(ownerId: string, dailyLimit: number): Promise<RateLimitDecision> {+ const now = Date.now();+ if (breakerIsOpen(now)) {+ return consumeInProcess(ownerId, dailyLimit, now);+ }+ try {+ const result = await apiRateLimitConsume({+ burstKey: `rl:burst:${ownerId}`,+ dailyKey: `rl:day:${ownerId}:${utcDay(now)}`,+ burstCapacity: API_BURST_LIMIT,+ burstRefillPerSecond: BURST_REFILL_PER_SECOND,+ dailyLimit,+ dailyTtlSeconds: DAILY_TTL_SECONDS,+ observeOnly: API_RATE_LIMIT_OBSERVE_ONLY,+ });+ recordRedisSuccess();+ return buildDecision({ ...result, dailyLimit, now });+ } catch (error) {+ recordRedisFailure(now);+ // Only the failure that trips the breaker is logged in full; the rest of an+ // outage would just repeat it once per request.+ if (consecutiveFailures === BREAKER_FAILURE_THRESHOLD) {+ logger.warn({ err: error, ownerId }, "Redis rate limit failing; using in-process counters until it recovers");+ }+ return consumeInProcess(ownerId, dailyLimit, now);+ }+}diff --git a/server/src/lib/apiRateLimitCharging.test.ts b/server/src/lib/apiRateLimitCharging.test.tsnew file mode 100644index 000000000..9fde2998d--- /dev/null+++ b/server/src/lib/apiRateLimitCharging.test.ts@@ -0,0 +1,138 @@+import { beforeEach, describe, expect, it, vi } from "vitest";+import { INTERNAL_BEARER_HANDOFF_HEADER } from "./bearerAuth.js";++// What a *request* costs. Budget is denominated in API requests, but several+// guards resolve the same credential more than once per HTTP request, and the+// MCP proxy injects requests carrying a handoff nonce. These tests pin down how+// many units each of those shapes actually consumes.++const decision = {+ allowed: true,+ wouldHaveDenied: false,+ scope: null,+ burstLimit: 50,+ burstRemaining: 49,+ burstResetSeconds: 1,+ dailyLimit: 5_000,+ dailyRemaining: 4_999,+ dailyResetSeconds: 3_600,+ retryAfterSeconds: 0,+};++const verifyApiKey = vi.fn();+const consumeRateLimitForIdentity = vi.fn();++// The handoff registry is module state, and resetModules gives auth-utils a+// fresh copy of it β so the test has to register nonces through the same graph+// auth-utils is reading from.+async function loadModules(isCloud: boolean) {+ vi.resetModules();+ vi.doMock("./auth.js", () => ({+ auth: { api: { verifyApiKey, getMcpSession: vi.fn(async () => null), getSession: vi.fn(async () => null) } },+ }));+ vi.doMock("./apiRateLimitPolicy.js", () => ({ consumeRateLimitForIdentity }));+ vi.doMock("../db/postgres/postgres.js", () => ({ db: {} }));+ vi.doMock("./const.js", async importOriginal => ({+ ...(await importOriginal<typeof import("./const.js")>()),+ IS_CLOUD: isCloud,+ }));+ const { checkApiKey } = await import("./auth-utils.js");+ const { registerBearerHandoff, releaseBearerHandoff } = await import("./bearerAuth.js");+ return { checkApiKey, registerBearerHandoff, releaseBearerHandoff };+}++// An organization key checked against its own organization resolves without+// touching the database.+const orgRequest = (extraHeaders: Record<string, string> = {}) =>+ ({ headers: { authorization: "Bearer rb_org_key", ...extraHeaders }, query: {} }) as any;++describe("rate limit charging per request", () => {+ beforeEach(() => {+ verifyApiKey.mockReset();+ consumeRateLimitForIdentity.mockReset();+ verifyApiKey.mockResolvedValue({ valid: true, key: { referenceId: "org_a", permissions: null, configId: "org" } });+ consumeRateLimitForIdentity.mockResolvedValue(decision);+ });++ it("charges one unit no matter how many times a request resolves the credential", async () => {+ const { checkApiKey } = await loadModules(true);+ const req = orgRequest();++ // A guard, then its fallback, then a handler calling getUserIdFromRequest.+ await checkApiKey(req, { organizationId: "org_a" });+ await checkApiKey(req, { organizationId: "org_a" });+ await checkApiKey(req, { organizationId: "org_a" });++ expect(consumeRateLimitForIdentity).toHaveBeenCalledTimes(1);+ });++ it("charges separate requests separately", async () => {+ const { checkApiKey } = await loadModules(true);++ await checkApiKey(orgRequest(), { organizationId: "org_a" });+ await checkApiKey(orgRequest(), { organizationId: "org_a" });++ expect(consumeRateLimitForIdentity).toHaveBeenCalledTimes(2);+ });++ it("reports the memoized decision on every resolution", async () => {+ const { checkApiKey } = await loadModules(true);+ const req = orgRequest();++ const first = await checkApiKey(req, { organizationId: "org_a" });+ const second = await checkApiKey(req, { organizationId: "org_a" });++ expect(first.rateLimit).toEqual(decision);+ expect(second.rateLimit).toEqual(decision);+ });++ it("does not charge again for the call the MCP gate already paid for", async () => {+ const { checkApiKey, registerBearerHandoff, releaseBearerHandoff } = await loadModules(true);+ const nonce = registerBearerHandoff("rb_org_key", {+ status: "valid",+ organizationId: "org_a",+ statements: null,+ rateLimit: decision,+ });++ const req = orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce });+ const result = await checkApiKey(req, { organizationId: "org_a" });+ // The handler resolving the credential again must not turn into a charge.+ await checkApiKey(req, { organizationId: "org_a" });++ expect(consumeRateLimitForIdentity).not.toHaveBeenCalled();+ expect(result.rateLimit).toEqual(decision);+ releaseBearerHandoff(nonce);+ });++ it("charges the second injected request of a batched MCP call", async () => {+ const { checkApiKey, registerBearerHandoff, releaseBearerHandoff } = await loadModules(true);+ const nonce = registerBearerHandoff("rb_org_key", {+ status: "valid",+ organizationId: "org_a",+ statements: null,+ rateLimit: decision,+ });++ // Every tool call in one JSON-RPC batch reuses the same nonce, but each is+ // its own injected request; only the first rides on the gate's charge.+ await checkApiKey(orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce }), { organizationId: "org_a" });+ await checkApiKey(orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce }), { organizationId: "org_a" });+ await checkApiKey(orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce }), { organizationId: "org_a" });++ expect(consumeRateLimitForIdentity).toHaveBeenCalledTimes(2);+ releaseBearerHandoff(nonce);+ });++ it("does not meter self-hosted instances at all", async () => {+ const { checkApiKey } = await loadModules(false);++ const result = await checkApiKey(orgRequest(), { organizationId: "org_a" });++ // Self-hosted has no plans and must not take a Redis dependency on the+ // authentication path.+ expect(consumeRateLimitForIdentity).not.toHaveBeenCalled();+ expect(result.valid).toBe(true);+ expect(result.rateLimit).toBeUndefined();+ });+});diff --git a/server/src/lib/apiRateLimitPolicy.ts b/server/src/lib/apiRateLimitPolicy.tsnew file mode 100644index 000000000..513e0faa1--- /dev/null+++ b/server/src/lib/apiRateLimitPolicy.ts@@ -0,0 +1,115 @@+import { eq } from "drizzle-orm";+import NodeCache from "node-cache";+import { db } from "../db/postgres/postgres.js";+import { member } from "../db/postgres/schema.js";+import { consumeApiRateLimit, dailyLimitForPlan, type RateLimitDecision } from "./apiRateLimit.js";+import { IS_CLOUD, PRO_API_DAILY_LIMIT } from "./const.js";+import { createServiceLogger } from "./logger/logger.js";++const logger = createServiceLogger("api-rate-limit");++// Plans are resolved per request rather than stamped onto the key at creation,+// which is what makes an upgrade take effect on keys that already exist. The+// cache keeps that to one lookup per owner per minute; a plan change is visible+// within the TTL.+const PLAN_CACHE_TTL_SECONDS = 60;+const planCache = new NodeCache({ stdTTL: PLAN_CACHE_TTL_SECONDS, checkperiod: 120 });++// Last known good limit per owner, kept beyond the cache TTL. A lookup failure+// falls back to this rather than to a fixed guess, so a Stripe or database blip+// neither throttles a Pro customer nor promotes a Standard one.+const lastKnownLimit = new Map<string, number>();+const MAX_REMEMBERED_OWNERS = 50_000;++async function dailyLimitForOrganization(organizationId: string): Promise<number> {+ const { getSubscriptionInner } = await import("../api/stripe/getSubscription.js");+ const subscription = await getSubscriptionInner(organizationId);+ return dailyLimitForPlan(subscription?.planName);+}++/**+ * A user in several organizations gets the most generous of their plans: the+ * alternative would throttle a Pro customer because they also sit in someone+ * else's free org. Every membership is considered β sampling a subset would+ * make the answer depend on row order, so a Pro customer's quota could silently+ * depend on which organizations happened to come back first.+ */+async function dailyLimitForUser(userId: string): Promise<number> {+ const memberships = await db+ .select({ organizationId: member.organizationId })+ .from(member)+ .where(eq(member.userId, userId));++ if (memberships.length === 0) {+ return dailyLimitForPlan(null);+ }++ const limits = await Promise.all(memberships.map(row => dailyLimitForOrganization(row.organizationId)));+ return Math.max(...limits);+}++function rememberLimit(cacheKey: string, limit: number): void {+ if (lastKnownLimit.size >= MAX_REMEMBERED_OWNERS && !lastKnownLimit.has(cacheKey)) {+ // Map iteration is insertion-ordered, so this drops the oldest entry.+ const oldest = lastKnownLimit.keys().next();+ if (!oldest.done) {+ lastKnownLimit.delete(oldest.value);+ }+ }+ lastKnownLimit.set(cacheKey, limit);+}++/**+ * The daily quota that applies to a credential, cached per owner.+ *+ * A lookup failure reuses this owner's last known quota, and only falls back to+ * the Pro quota when there is none: a Stripe or database blip should not+ * throttle a paying customer, but it also should not hand every Standard owner+ * five times their budget. The burst tier β the one that actually protects the+ * database β does not depend on plan resolution either way.+ */+export async function resolveDailyLimit(identity: { userId?: string; organizationId?: string }): Promise<number> {+ if (!IS_CLOUD) {+ return 0;+ }+ const cacheKey = identity.organizationId ? `org:${identity.organizationId}` : `user:${identity.userId}`;+ const cached = planCache.get<number>(cacheKey);+ if (cached !== undefined) {+ return cached;+ }++ let limit: number;+ try {+ limit = identity.organizationId+ ? await dailyLimitForOrganization(identity.organizationId)+ : await dailyLimitForUser(identity.userId!);+ rememberLimit(cacheKey, limit);+ } catch (error) {+ limit = lastKnownLimit.get(cacheKey) ?? PRO_API_DAILY_LIMIT;+ logger.warn({ err: error, cacheKey, limit }, "Plan lookup failed for rate limit; using last known quota");+ }++ planCache.set(cacheKey, limit);+ return limit;+}++/** Drop a cached plan so a subscription change applies immediately. */+export function invalidateRateLimitPlanCache(ownerId: string): void {+ planCache.del([`org:${ownerId}`, `user:${ownerId}`]);+ lastKnownLimit.delete(`org:${ownerId}`);+ lastKnownLimit.delete(`user:${ownerId}`);+}++/**+ * Resolve the owner's quota and charge one request against it. Wired into the+ * bearer resolver, so it runs exactly once per credential verification β the+ * MCP proxy's handoff reuses that result rather than charging a second time.+ */+export async function consumeRateLimitForIdentity(identity: {+ userId?: string;+ organizationId?: string;+}): Promise<RateLimitDecision> {+ const ownerId = identity.organizationId ?? identity.userId!;+ const dailyLimit = await resolveDailyLimit(identity);+ return consumeApiRateLimit(ownerId, dailyLimit);+}diff --git a/server/src/lib/auth-middleware.test.ts b/server/src/lib/auth-middleware.test.tsindex a4bb75acd..5042deb86 100644--- a/server/src/lib/auth-middleware.test.ts+++ b/server/src/lib/auth-middleware.test.ts@@ -194,3 +194,99 @@ describe("auth middleware scope enforcement", () => {expect(response.statusCode).toBe(429);});});++describe("auth middleware rate limit reporting", () => {+ let app: FastifyInstance;++ const limit = (overrides: Record<string, unknown> = {}) => ({+ allowed: true,+ wouldHaveDenied: false,+ scope: null,+ burstLimit: 50,+ burstRemaining: 40,+ burstResetSeconds: 2,+ dailyLimit: 5000,+ dailyRemaining: 4000,+ dailyResetSeconds: 3600,+ retryAfterSeconds: 0,+ ...overrides,+ });++ beforeEach(async () => {+ vi.clearAllMocks();+ mocks.getSessionFromReq.mockResolvedValue(null);+ mocks.getUserHasAccessToSite.mockResolvedValue(false);+ mocks.getIsUserAdmin.mockResolvedValue(false);++ app = Fastify();+ app.get("/sites/:siteId/goals", { preHandler: [requireSiteAccess()] as any }, async () => ({ ok: true }));+ await app.ready();+ });++ afterEach(async () => {+ await app.close();+ });++ it("reports the remaining budget on a successful request", async () => {+ mocks.checkApiKey.mockResolvedValue({ ...bearerResult(null), rateLimit: limit() });++ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });++ expect(response.statusCode).toBe(200);+ expect(response.headers["x-ratelimit-burst-remaining"]).toBe("40");+ expect(response.headers["x-ratelimit-daily-limit"]).toBe("5000");+ expect(response.headers["x-ratelimit-daily-remaining"]).toBe("4000");+ });++ it("points RateLimit-* at whichever tier is closest to exhaustion", async () => {+ // 100/5000 daily left vs 40/50 burst: daily is the tier a client needs to+ // pace itself against.+ mocks.checkApiKey.mockResolvedValue({ ...bearerResult(null), rateLimit: limit({ dailyRemaining: 100 }) });++ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });++ expect(response.headers["ratelimit-limit"]).toBe("5000");+ expect(response.headers["ratelimit-remaining"]).toBe("100");+ expect(response.headers["ratelimit-reset"]).toBe("3600");+ });++ it("names the tier and the wait on a daily rejection", async () => {+ mocks.checkApiKey.mockResolvedValue({+ valid: false,+ role: null,+ rateLimited: true,+ statements: null,+ rateLimit: limit({ allowed: false, scope: "daily", dailyRemaining: 0, retryAfterSeconds: 3600 }),+ });++ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });++ expect(response.statusCode).toBe(429);+ expect(response.headers["retry-after"]).toBe("3600");+ expect(response.json()).toMatchObject({ scope: "daily", limit: 5000, retryAfter: 3600 });+ });++ it("omits the daily headers when the quota is unlimited", async () => {+ mocks.checkApiKey.mockResolvedValue({+ ...bearerResult(null),+ rateLimit: limit({ dailyLimit: 0, dailyRemaining: 0 }),+ });++ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });++ // Self-hosted has no quota; advertising "0 remaining" would read as blocked.+ expect(response.headers["x-ratelimit-daily-limit"]).toBeUndefined();+ expect(response.headers["ratelimit-limit"]).toBe("50");+ });++ it("sends no rate limit headers for session-authenticated requests", async () => {+ mocks.checkApiKey.mockResolvedValue(invalidResult);+ mocks.getUserHasAccessToSite.mockResolvedValue(true);+ mocks.getSessionFromReq.mockResolvedValue({ user: { id: "user_1" } });++ const response = await app.inject({ method: "GET", url: "/sites/5/goals" });++ expect(response.statusCode).toBe(200);+ expect(response.headers["ratelimit-limit"]).toBeUndefined();+ });+});diff --git a/server/src/lib/auth-middleware.ts b/server/src/lib/auth-middleware.tsindex dcbec681b..6325130ba 100644--- a/server/src/lib/auth-middleware.ts+++ b/server/src/lib/auth-middleware.ts@@ -51,11 +51,68 @@ const getOrganizationIdFromParams = (request: FastifyRequest): string | undefinereturn params?.organizationId;};+/**+ * Report the remaining budget on every bearer-authenticated response, not just+ * on rejections β a client can only pace itself if it can see the budget before+ * it runs out. `RateLimit-*` describes whichever tier is closest to exhaustion+ * (per the IETF draft); the per-tier `X-RateLimit-*` headers always describe+ * both, so a client never has to guess which one it just read.+ */+const applyRateLimitHeaders = (reply: FastifyReply, apiKeyResult: BearerAuthResult) => {+ const limit = apiKeyResult.rateLimit;+ if (!limit) {+ return;+ }++ reply.header("X-RateLimit-Burst-Limit", limit.burstLimit);+ reply.header("X-RateLimit-Burst-Remaining", limit.burstRemaining);+ reply.header("X-RateLimit-Burst-Reset", limit.burstResetSeconds);++ const dailyEnabled = limit.dailyLimit > 0;+ if (dailyEnabled) {+ reply.header("X-RateLimit-Daily-Limit", limit.dailyLimit);+ reply.header("X-RateLimit-Daily-Remaining", limit.dailyRemaining);+ reply.header("X-RateLimit-Daily-Reset", limit.dailyResetSeconds);+ }++ // When the limiter named a binding tier, report that one β otherwise a+ // request denied on the daily quota (both tiers at zero, so neither ratio is+ // smaller) would advertise a 10-second reset next to a Retry-After of hours.+ const dailyIsTighter = limit.scope+ ? limit.scope === "daily"+ : dailyEnabled && limit.dailyRemaining / limit.dailyLimit < limit.burstRemaining / limit.burstLimit;+ reply.header("RateLimit-Limit", dailyIsTighter ? limit.dailyLimit : limit.burstLimit);+ reply.header("RateLimit-Remaining", dailyIsTighter ? limit.dailyRemaining : limit.burstRemaining);+ reply.header("RateLimit-Reset", dailyIsTighter ? limit.dailyResetSeconds : limit.burstResetSeconds);+};++const sendRateLimited = (reply: FastifyReply, apiKeyResult: BearerAuthResult) => {+ const limit = apiKeyResult.rateLimit;+ applyRateLimitHeaders(reply, apiKeyResult);+ if (limit) {+ reply.header("Retry-After", limit.retryAfterSeconds);+ }+ return reply.status(429).send({+ error: "Rate limit exceeded",+ // Naming the tier is the difference between "back off for two seconds" and+ // "you are done until tomorrow" β a client cannot tell them apart from a+ // bare 429.+ ...(limit?.scope+ ? {+ scope: limit.scope,+ limit: limit.scope === "daily" ? limit.dailyLimit : limit.burstLimit,+ retryAfter: limit.retryAfterSeconds,+ }+ : {}),+ });+};+// Attach the authenticated bearer principal. User keys become request.user// like a session; org keys have no user (handlers that attribute a creator// record null) β they set apiKeyOrganizationId instead, which the site-access// resolver (getSitesUserHasAccessTo) maps to the org's full site set.-const attachApiKeyUser = (request: FastifyRequest, apiKeyResult: BearerAuthResult) => {+const attachApiKeyUser = (request: FastifyRequest, reply: FastifyReply, apiKeyResult: BearerAuthResult) => {+ applyRateLimitHeaders(reply, apiKeyResult);if (apiKeyResult.userId) {request.user = { id: apiKeyResult.userId };} else if (apiKeyResult.organizationId) {@@ -99,12 +156,12 @@ export function requireAuth(scope?: RouteScope): AuthMiddleware {if (!bearerScopeOk(apiKeyResult, scope)) {return sendInsufficientScope(reply, scope!);}- attachApiKeyUser(request, apiKeyResult);+ attachApiKeyUser(request, reply, apiKeyResult);return;}if (apiKeyResult.rateLimited) {- return reply.status(429).send({ error: "Rate limit exceeded" });+ return sendRateLimited(reply, apiKeyResult);}return reply.status(401).send({ error: "Unauthorized" });@@ -138,7 +195,7 @@ export function requireSiteAccess(scope?: RouteScope): AuthMiddleware {const apiKeyResult = await checkApiKey(request, { siteId });if (apiKeyResult.valid) {if (bearerScopeOk(apiKeyResult, scope)) {- attachApiKeyUser(request, apiKeyResult);+ attachApiKeyUser(request, reply, apiKeyResult);return;}scopeDenied = true;@@ -153,7 +210,7 @@ export function requireSiteAccess(scope?: RouteScope): AuthMiddleware {}if (apiKeyResult.rateLimited) {- return reply.status(429).send({ error: "Rate limit exceeded" });+ return sendRateLimited(reply, apiKeyResult);}if (scopeDenied) {return sendInsufficientScope(reply, scope!);@@ -178,7 +235,7 @@ export function requireSiteAdminAccess(scope?: RouteScope): AuthMiddleware {const apiKeyResult = await checkApiKey(request, { siteId });if (apiKeyResult.valid && (apiKeyResult.role === "admin" || apiKeyResult.role === "owner")) {if (bearerScopeOk(apiKeyResult, scope)) {- attachApiKeyUser(request, apiKeyResult);+ attachApiKeyUser(request, reply, apiKeyResult);return;}scopeDenied = true;@@ -202,7 +259,7 @@ export function requireSiteAdminAccess(scope?: RouteScope): AuthMiddleware {}if (apiKeyResult.rateLimited) {- return reply.status(429).send({ error: "Rate limit exceeded" });+ return sendRateLimited(reply, apiKeyResult);}if (scopeDenied) {return sendInsufficientScope(reply, scope!);@@ -227,7 +284,7 @@ export function allowPublicSiteAccess(scope?: RouteScope): AuthMiddleware {const apiKeyResult = await checkApiKey(request, { siteId });if (apiKeyResult.valid) {if (bearerScopeOk(apiKeyResult, scope)) {- attachApiKeyUser(request, apiKeyResult);+ attachApiKeyUser(request, reply, apiKeyResult);return;}scopeDenied = true;@@ -244,7 +301,7 @@ export function allowPublicSiteAccess(scope?: RouteScope): AuthMiddleware {}if (apiKeyResult.rateLimited) {- return reply.status(429).send({ error: "Rate limit exceeded" });+ return sendRateLimited(reply, apiKeyResult);}if (scopeDenied) {return sendInsufficientScope(reply, scope!);@@ -270,7 +327,7 @@ export function requireOrgMember(scope?: RouteScope): AuthMiddleware {const apiKeyResult = await checkApiKey(request, { organizationId });if (apiKeyResult.valid) {if (bearerScopeOk(apiKeyResult, scope)) {- attachApiKeyUser(request, apiKeyResult);+ attachApiKeyUser(request, reply, apiKeyResult);return;}scopeDenied = true;@@ -284,7 +341,7 @@ export function requireOrgMember(scope?: RouteScope): AuthMiddleware {}if (apiKeyResult.rateLimited) {- return reply.status(429).send({ error: "Rate limit exceeded" });+ return sendRateLimited(reply, apiKeyResult);}if (scopeDenied) {return sendInsufficientScope(reply, scope!);@@ -313,7 +370,7 @@ export function requireOrgAdminFromParams(scope?: RouteScope): AuthMiddleware {const apiKeyResult = await checkApiKey(request, { organizationId });if (apiKeyResult.valid && (apiKeyResult.role === "admin" || apiKeyResult.role === "owner")) {if (bearerScopeOk(apiKeyResult, scope)) {- attachApiKeyUser(request, apiKeyResult);+ attachApiKeyUser(request, reply, apiKeyResult);return;}scopeDenied = true;@@ -323,7 +380,7 @@ export function requireOrgAdminFromParams(scope?: RouteScope): AuthMiddleware {const session = await getSessionFromReq(request);if (!session?.user?.id) {if (apiKeyResult.rateLimited) {- return reply.status(429).send({ error: "Rate limit exceeded" });+ return sendRateLimited(reply, apiKeyResult);}if (scopeDenied) {return sendInsufficientScope(reply, scope!);diff --git a/server/src/lib/auth-utils.test.ts b/server/src/lib/auth-utils.test.tsindex b41b31802..5a9333cb4 100644--- a/server/src/lib/auth-utils.test.ts+++ b/server/src/lib/auth-utils.test.ts@@ -13,6 +13,25 @@ vi.mock("./auth.js", () => ({},}));+// The bearer resolver charges every verification against the rate limiter,+// which would reach for Redis (and a plan lookup) on each of these tests. Stub+// it out β the limiter has its own tests, and these are about scope carrying+// and org resolution.+vi.mock("./apiRateLimitPolicy.js", () => ({+ consumeRateLimitForIdentity: vi.fn(async () => ({+ allowed: true,+ wouldHaveDenied: false,+ scope: null,+ burstLimit: 50,+ burstRemaining: 49,+ burstResetSeconds: 1,+ dailyLimit: 5_000,+ dailyRemaining: 4_999,+ dailyResetSeconds: 3_600,+ retryAfterSeconds: 0,+ })),+}));+// Replace the postgres-js connection with an in-memory PGlite database so the// real drizzle queries in auth-utils run against real SQL.vi.mock("../db/postgres/postgres.js", async () => {diff --git a/server/src/lib/auth-utils.ts b/server/src/lib/auth-utils.tsindex 112702b81..10a6d9ad8 100644--- a/server/src/lib/auth-utils.ts+++ b/server/src/lib/auth-utils.ts@@ -3,7 +3,10 @@ import { FastifyRequest } from "fastify";import NodeCache from "node-cache";import { db } from "../db/postgres/postgres.js";import { member, memberSiteAccess, sites, user, team, teamMember, teamSiteAccess } from "../db/postgres/schema.js";+import type { RateLimitDecision } from "./apiRateLimit.js";+import { consumeRateLimitForIdentity } from "./apiRateLimitPolicy.js";import { auth } from "./auth.js";+import { IS_CLOUD } from "./const.js";import {consumeBearerHandoff,extractBearerToken,@@ -21,6 +24,56 @@ const bearerResolverDeps: BearerResolverDeps = {getOAuthSession: token => auth.api.getMcpSession({ headers: new Headers({ authorization: `Bearer ${token}` }) }),};+// Several guards resolve the same credential more than once per HTTP request:+// a guard runs checkApiKey and then its session fallback (or the handler's+// getUserIdFromRequest) runs it again. Budget is denominated in API requests,+// not in internal resolutions, so the charge is memoized on the request object+// and every later resolution reuses that one decision.+const REQUEST_RATE_LIMIT = Symbol.for("rybbit.rateLimitDecision");++type RateLimitedRequest = FastifyRequest & { [REQUEST_RATE_LIMIT]?: RateLimitDecision };++function getRequestRateLimit(req: FastifyRequest): RateLimitDecision | undefined {+ return (req as RateLimitedRequest)[REQUEST_RATE_LIMIT];+}++function setRequestRateLimit(req: FastifyRequest, decision: RateLimitDecision): void {+ (req as RateLimitedRequest)[REQUEST_RATE_LIMIT] = decision;+}++/**+ * Whether this request was refused by the rate limiter. For handlers that+ * resolve credentials without a guard and would otherwise report a throttled+ * request as unauthenticated.+ */+export function wasRateLimited(req: FastifyRequest): RateLimitDecision | undefined {+ const decision = getRequestRateLimit(req);+ return decision && !decision.allowed ? decision : undefined;+}++/**+ * Per-request resolver dependencies. Rate limiting is cloud-only: self-hosted+ * instances have no plans, no shared infrastructure to protect, and must not+ * gain a Redis dependency on the authentication path.+ */+function resolverDepsFor(req: FastifyRequest): BearerResolverDeps {+ if (!IS_CLOUD) {+ return bearerResolverDeps;+ }+ return {+ ...bearerResolverDeps,+ consumeRateLimit: async identity => {+ const memoized = getRequestRateLimit(req);+ if (memoized) {+ return memoized;+ }+ const decision = await consumeRateLimitForIdentity(identity);+ setRequestRateLimit(req, decision);+ return decision;+ },+ };+}+function resolveBearerTokenFromRequest(req: FastifyRequest): string | null {// Priority: Authorization: Bearer header (recommended), then ?api_key= (testing).const bearerToken = extractBearerToken(req.headers["authorization"]);@@ -362,6 +415,8 @@ export interface BearerAuthResult {/** Set instead of userId when the credential is an organization-owned key. */organizationId?: string;rateLimited?: boolean;+ /** Budget state for this request, when a bearer credential was resolved. */+ rateLimit?: RateLimitDecision;/*** Scope statements carried by the credential. null = unrestricted (legacy* key with no permissions, or OAuth token with no custom scopes). Guards@@ -385,13 +440,17 @@ export async function checkApiKey(}// Reuse the MCP gate's verification when this is an in-process proxy call, so- // a tool call doesn't verify (and rate-limit) the key a second time.- const identity =- consumeBearerHandoff(req.headers[INTERNAL_BEARER_HANDOFF_HEADER], apiKey) ??- (await resolveBearerIdentity(apiKey, bearerResolverDeps));+ // a tool call doesn't verify (and rate-limit) the key a second time. The+ // gate's charge covers this call; recording it here keeps a second resolution+ // within the same request from charging again.+ const handoffIdentity = consumeBearerHandoff(req.headers[INTERNAL_BEARER_HANDOFF_HEADER], apiKey);+ if (handoffIdentity?.rateLimit) {+ setRequestRateLimit(req, handoffIdentity.rateLimit);+ }+ const identity = handoffIdentity ?? (await resolveBearerIdentity(apiKey, resolverDepsFor(req)));if (identity.status === "rate_limited") {- return { valid: false, role: null, rateLimited: true, statements: null };+ return { valid: false, role: null, rateLimited: true, rateLimit: identity.rateLimit, statements: null };}if (identity.status === "valid" && identity.organizationId) {// Organization-owned key: valid only against its own organization (or a@@ -403,14 +462,15 @@ export async function checkApiKey(valid: true,role: "admin",organizationId: identity.organizationId,+ rateLimit: identity.rateLimit,statements: identity.statements,};}- return { valid: false, role: null, statements: null };+ return { valid: false, role: null, rateLimit: identity.rateLimit, statements: null };}if (identity.status === "valid" && identity.userId) {const membership = await resolveBearerUserOrgRole(identity.userId, options);- return { ...membership, statements: identity.statements };+ return { ...membership, rateLimit: identity.rateLimit, statements: identity.statements };}return { valid: false, role: null, statements: null };}diff --git a/server/src/lib/auth.ts b/server/src/lib/auth.tsindex de4229da7..98169c180 100644--- a/server/src/lib/auth.ts+++ b/server/src/lib/auth.ts@@ -16,7 +16,7 @@ import { invitation, member, memberSiteAccess, sites, user } from "../db/postgreimport { apiKeyLimitForPlan, countApiKeysForReference } from "./apiKeyLimits.js";import { invalidateSitesAccessCache } from "./auth-utils.js";import { ORG_API_KEY_CONFIG_ID } from "./bearerAuth.js";-import { API_RATE_LIMIT_WINDOW, DISABLE_SIGNUP, IS_CLOUD, STANDARD_API_RATE_LIMIT } from "./const.js";+import { DISABLE_SIGNUP, IS_CLOUD } from "./const.js";import {addContactToAudience,sendChangeEmailVerification,@@ -48,14 +48,16 @@ const orgRoles = {member: orgAccessControl.newRole({ ...memberAc.statements }),};-// Default per-key rate limits; the create endpoints override them per plan.-const apiKeyRateLimit = IS_CLOUD- ? {- enabled: true,- timeWindow: API_RATE_LIMIT_WINDOW,- maxRequests: STANDARD_API_RATE_LIMIT,- }- : { maxRequests: 10000, timeWindow: 86400000 };+// Rate limiting moved out of the plugin and into lib/apiRateLimit.ts, which+// enforces a burst tier and a daily quota per credential *owner* rather than a+// fixed window per key β the plugin's limiter is keyed on the key row, so an+// org could multiply its budget by minting more keys.+//+// Disabling it drops the read-modify-write on `requestCount`, but not every+// write: the plugin still stamps `lastRequest` on each verification (it takes+// the "skip" branch with a fresh timestamp), which is also what makes key+// last-used times work.+const apiKeyRateLimit = { enabled: false };const pluginList = [admin(),diff --git a/server/src/lib/bearerAuth.test.ts b/server/src/lib/bearerAuth.test.tsindex 29b31f739..0b34ce0e5 100644--- a/server/src/lib/bearerAuth.test.ts+++ b/server/src/lib/bearerAuth.test.ts@@ -1,4 +1,5 @@import { describe, expect, it, vi } from "vitest";+import type { RateLimitDecision } from "./apiRateLimit.js";import {consumeBearerHandoff,extractBearerToken,@@ -86,6 +87,80 @@ describe("resolveBearerIdentity", () => {});});+describe("resolveBearerIdentity rate limiting", () => {+ const decision = (overrides: Partial<RateLimitDecision> = {}): RateLimitDecision => ({+ allowed: true,+ wouldHaveDenied: false,+ scope: null,+ burstLimit: 50,+ burstRemaining: 49,+ burstResetSeconds: 1,+ dailyLimit: 5000,+ dailyRemaining: 4999,+ dailyResetSeconds: 3600,+ retryAfterSeconds: 0,+ ...overrides,+ });++ it("charges the organization for an org-owned key, not the key itself", async () => {+ const consumeRateLimit = vi.fn(async () => decision());+ const identity = await resolveBearerIdentity(+ "k",+ deps({+ verifyApiKey: async () => ({ valid: true, key: { referenceId: "org1", permissions: null, configId: "org" } }),+ consumeRateLimit,+ })+ );++ expect(consumeRateLimit).toHaveBeenCalledWith({ userId: undefined, organizationId: "org1" });+ expect(identity.status).toBe("valid");+ expect(identity.rateLimit?.dailyRemaining).toBe(4999);+ });++ it("charges OAuth access tokens on the same budget as API keys", async () => {+ const consumeRateLimit = vi.fn(async () => decision());+ const identity = await resolveBearerIdentity(+ "k",+ deps({ getOAuthSession: async () => ({ userId: "u1", accessTokenExpiresAt: future() }), consumeRateLimit })+ );++ expect(consumeRateLimit).toHaveBeenCalledWith({ userId: "u1", organizationId: undefined });+ expect(identity.status).toBe("valid");+ });++ it("rejects a denied request and carries the retry-after through", async () => {+ const identity = await resolveBearerIdentity(+ "k",+ deps({+ verifyApiKey: async () => ({ valid: true, key: { referenceId: "u1", permissions: null } }),+ consumeRateLimit: async () =>+ decision({ allowed: false, wouldHaveDenied: true, scope: "daily", retryAfterSeconds: 3600 }),+ })+ );++ expect(identity.status).toBe("rate_limited");+ expect(identity.userId).toBeUndefined();+ expect(identity.rateLimit?.scope).toBe("daily");+ expect(identity.rateLimit?.retryAfterSeconds).toBe(3600);+ });++ it("admits the request when the limiter itself fails", async () => {+ const identity = await resolveBearerIdentity(+ "k",+ deps({+ verifyApiKey: async () => ({ valid: true, key: { referenceId: "u1", permissions: null } }),+ consumeRateLimit: async () => {+ throw new Error("redis down");+ },+ })+ );++ // A broken limiter must not lock out valid credentials.+ expect(identity.status).toBe("valid");+ expect(identity.rateLimit).toBeUndefined();+ });+});+describe("bearer handoff", () => {it("returns the identity for a matching nonce and token", () => {const identity = { status: "valid" as const, userId: "u1", statements: null };@@ -110,4 +185,17 @@ describe("bearer handoff", () => {releaseBearerHandoff(nonce);expect(consumeBearerHandoff(nonce, "tok")).toBeNull();});++ it("covers only one call, so a JSON-RPC batch cannot ride on one charge", () => {+ const identity = { status: "valid" as const, userId: "u1", statements: null };+ const nonce = registerBearerHandoff("tok", identity);++ expect(consumeBearerHandoff(nonce, "tok")).toBe(identity);+ // A batched MCP request reuses one nonce for every tool call; the rest must+ // fall through to real verification so they are charged.+ expect(consumeBearerHandoff(nonce, "tok")).toBeNull();+ expect(consumeBearerHandoff(nonce, "tok")).toBeNull();++ releaseBearerHandoff(nonce);+ });});diff --git a/server/src/lib/bearerAuth.ts b/server/src/lib/bearerAuth.tsindex fb34f6573..7195a07c7 100644--- a/server/src/lib/bearerAuth.ts+++ b/server/src/lib/bearerAuth.ts@@ -1,4 +1,5 @@import { randomUUID } from "node:crypto";+import type { RateLimitDecision } from "./apiRateLimit.js";import { parseOAuthScopes, statementsFromApiKeyPermissions, type ScopeStatements } from "./scopes.js";/**@@ -40,6 +41,16 @@ export type OAuthTokenLookup = {export interface BearerResolverDeps {verifyApiKey: (token: string) => Promise<ApiKeyVerification>;getOAuthSession: (token: string) => Promise<OAuthTokenLookup>;+ /**+ * Charge one request against the owner's burst bucket and daily quota.+ * Optional so tests and the MCP layer can resolve identities without a+ * limiter; when absent, no request is charged. Returning null means the+ * deployment is not metered (self-hosted), which is not a denial.+ */+ consumeRateLimit?: (identity: {+ userId?: string;+ organizationId?: string;+ }) => Promise<RateLimitDecision | null>;}export type BearerIdentityStatus = "valid" | "invalid" | "rate_limited" | "verify_error";@@ -53,6 +64,12 @@ export interface BearerIdentity {organizationId?: string;/** null = unrestricted (legacy key / full OAuth grant); enforced by callers. */statements: ScopeStatements | null;+ /**+ * The rate-limit outcome for this request, carried so callers can report the+ * remaining budget in response headers. Present on rate_limited identities+ * too β that is where the retry-after comes from.+ */+ rateLimit?: RateLimitDecision;}export function isUsableOAuthToken(token: OAuthTokenLookup): token is NonNullable<OAuthTokenLookup> {@@ -69,6 +86,30 @@ export function isUsableOAuthToken(token: OAuthTokenLookup): token is NonNullabl* cheap DB query the caller does per route, and it never touches the rate* limiter, so it does not need deduplicating.*/+/**+ * Charge a resolved identity against its owner's budget, converting a denial+ * into a rate_limited result. A limiter failure is never fatal: the identity+ * passes through uncharged rather than locking out a valid credential.+ */+async function applyRateLimit(identity: BearerIdentity, deps: BearerResolverDeps): Promise<BearerIdentity> {+ if (!deps.consumeRateLimit) {+ return identity;+ }+ let decision: RateLimitDecision | null;+ try {+ decision = await deps.consumeRateLimit({ userId: identity.userId, organizationId: identity.organizationId });+ } catch {+ return identity;+ }+ if (!decision) {+ return identity;+ }+ if (!decision.allowed) {+ return { status: "rate_limited", statements: null, rateLimit: decision };+ }+ return { ...identity, rateLimit: decision };+}+export async function resolveBearerIdentity(token: string, deps: BearerResolverDeps): Promise<BearerIdentity> {let verifyError = false;let verification: ApiKeyVerification | null = null;@@ -83,9 +124,9 @@ export async function resolveBearerIdentity(token: string, deps: BearerResolverD// referenceId is a user id or an organization id depending on which key// configuration minted the key (legacy keys have a NULL configId = user).if (verification.key.configId === ORG_API_KEY_CONFIG_ID) {- return { status: "valid", organizationId: verification.key.referenceId, statements };+ return applyRateLimit({ status: "valid", organizationId: verification.key.referenceId, statements }, deps);}- return { status: "valid", userId: verification.key.referenceId, statements };+ return applyRateLimit({ status: "valid", userId: verification.key.referenceId, statements }, deps);}if (verification?.error?.code === "RATE_LIMITED") {@@ -102,11 +143,14 @@ export async function resolveBearerIdentity(token: string, deps: BearerResolverD}if (isUsableOAuthToken(oauth)) {- return {- status: "valid",- userId: oauth.userId as string,- statements: parseOAuthScopes(typeof oauth.scopes === "string" ? oauth.scopes : null),- };+ return applyRateLimit(+ {+ status: "valid",+ userId: oauth.userId as string,+ statements: parseOAuthScopes(typeof oauth.scopes === "string" ? oauth.scopes : null),+ },+ deps+ );}return { status: verifyError ? "verify_error" : "invalid", statements: null };@@ -128,12 +172,14 @@ export const INTERNAL_BEARER_HANDOFF_HEADER = "x-rybbit-mcp-bearer";interface HandoffEntry {token: string;identity: BearerIdentity;+ /** A handoff covers exactly one REST call β see consumeBearerHandoff. */+ spent: boolean;}const handoffs = new Map<string, HandoffEntry>();export function registerBearerHandoff(token: string, identity: BearerIdentity): string {const nonce = randomUUID();- handoffs.set(nonce, { token, identity });+ handoffs.set(nonce, { token, identity, spent: false });return nonce;}@@ -154,5 +200,14 @@ export function consumeBearerHandoff(if (!entry || entry.token !== token) {return null;}+ // One handoff covers one REST call. The MCP request already paid for that+ // call at the gate, but a single HTTP request can carry a whole JSON-RPC+ // batch β reusing the nonce for all of them would let a client run any+ // number of tool calls on one unit of budget. Later calls fall through to+ // normal verification, which charges them.+ if (entry.spent) {+ return null;+ }+ entry.spent = true;return entry.identity;}diff --git a/server/src/lib/const.ts b/server/src/lib/const.tsindex e7f1147ad..2e112fa86 100644--- a/server/src/lib/const.ts+++ b/server/src/lib/const.ts@@ -37,10 +37,26 @@ export const BASIC_MEMBER_LIMIT = 1;export const STANDARD_SITE_LIMIT = 5;export const STANDARD_MEMBER_LIMIT = 3;-// API key rate limits per plan (requests per window)-export const API_RATE_LIMIT_WINDOW = 60_000; // 1 minute-export const STANDARD_API_RATE_LIMIT = 20; // 20 req/min-export const PRO_API_RATE_LIMIT = 200; // 200 req/min+// API rate limits. Two tiers with distinct jobs:+//+// burst β identical for every plan, because this is the infrastructure guard.+// It bounds instantaneous request rate per credential owner so no+// single caller can stampede ClickHouse. A full bucket drains in one+// spike; it then refills continuously at capacity/window (5 req/s).+// daily β the plan lever, on a UTC calendar day so it resets predictably and+// reads like the monthly event quota users already understand.+//+// Enforced per *owner* (the organization for org keys, the user for user keys),+// not per key, so minting extra keys cannot multiply an org's budget.+export const API_BURST_LIMIT = 50; // 50 requests+export const API_BURST_WINDOW_MS = 10_000; // per 10s => 5 req/s sustained, 50 in one spike+export const STANDARD_API_DAILY_LIMIT = 5_000;+export const PRO_API_DAILY_LIMIT = 25_000;++// Count usage and report what would have been blocked, but let every request+// through. Deploy in this mode first to size the daily limits against real+// traffic before they start rejecting anyone.+export const API_RATE_LIMIT_OBSERVE_ONLY = process.env.API_RATE_LIMIT_OBSERVE_ONLY === "true";// Maximum number of API keys per owner (a user or an organization)export const STANDARD_API_KEY_LIMIT = 5;diff --git a/server/src/mcp/auth.ts b/server/src/mcp/auth.tsindex 0353304f5..594dff113 100644--- a/server/src/mcp/auth.ts+++ b/server/src/mcp/auth.ts@@ -24,7 +24,9 @@ export interface McpAuthContext {export class McpAuthenticationError extends Error {constructor(message: string,- public readonly statusCode: 401 | 429 | 503+ public readonly statusCode: 401 | 429 | 503,+ /** Seconds to wait before retrying; drives Retry-After on 429/503. */+ public readonly retryAfterSeconds?: number) {super(message);this.name = "McpAuthenticationError";@@ -42,6 +44,15 @@ const defaultDependencies: McpAuthenticatorDependencies = {const { auth } = await import("../lib/auth.js");return auth.api.getMcpSession({ headers: new Headers({ authorization: `Bearer ${bearerToken}` }) });},+ consumeRateLimit: async identity => {+ const { IS_CLOUD } = await import("../lib/const.js");+ // Self-hosted is not metered, and the auth path must not depend on Redis.+ if (!IS_CLOUD) {+ return null;+ }+ const { consumeRateLimitForIdentity } = await import("../lib/apiRateLimitPolicy.js");+ return consumeRateLimitForIdentity(identity);+ },};/**@@ -71,8 +82,19 @@ export function createMcpAuthenticator(dependencies: McpAuthenticatorDependenciescopes: identity.statements,identity,};- case "rate_limited":- throw new McpAuthenticationError("API key rate limit exceeded", 429);+ case "rate_limited": {+ const limit = identity.rateLimit;+ // A daily-quota rejection is not retriable for hours; telling a client+ // to come back in 60s would just have it hammer a closed door.+ const detail = limit?.scope+ ? ` (${limit.scope} limit${limit.scope === "daily" ? ` of ${limit.dailyLimit}/day` : ""})`+ : "";+ throw new McpAuthenticationError(+ `API key rate limit exceeded${detail}`,+ 429,+ limit?.retryAfterSeconds+ );+ }case "verify_error":throw new McpAuthenticationError("Rybbit could not verify the API key", 503);default:diff --git a/server/src/mcp/index.ts b/server/src/mcp/index.tsindex f1f4bebf4..821fa4e7a 100644--- a/server/src/mcp/index.ts+++ b/server/src/mcp/index.ts@@ -71,7 +71,10 @@ export async function mcpRoutes(fastify: FastifyInstance, options: McpRouteOptio);reply.header("Access-Control-Expose-Headers", "WWW-Authenticate");} else {- reply.header("Retry-After", error.statusCode === 429 ? "60" : "30");+ reply.header(+ "Retry-After",+ String(error.retryAfterSeconds ?? (error.statusCode === 429 ? 60 : 30))+ );}return reply.status(error.statusCode).send({jsonrpc: "2.0",