⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
fix(api): send complete rate limit headers on every API key path
Andrej29ff184fcacb
diff --git a/apps/api/src/index.ts b/apps/api/src/index.tsindex a0c7f8aa3..4c8160c77 100644--- a/apps/api/src/index.ts+++ b/apps/api/src/index.ts@@ -72,6 +72,7 @@ import timeEntry from "./time-entry";import user from "./user";import getAvatar from "./user/controllers/get-avatar";import { apiKeyRejection } from "./utils/api-key-rejection";+import { applyApiKeyHeaders } from "./utils/apply-api-key-headers";import { authenticateApiRequest } from "./utils/authenticate-api-request";import {authorizeAssetAccess,@@ -87,11 +88,8 @@ import { normalizeApiServerUrl } from "./utils/openapi-spec";import { seedDefaultWorkspaceRoles } from "./utils/seed-default-workspace-roles";import { drainSignInEmails } from "./utils/sign-in-email-tasks";import { validateWorkspaceAccess } from "./utils/validate-workspace-access";-import {- type ApiKeyRateLimit,- rateLimitHeaders,-} from "./utils/rate-limit-headers";-import { readApiKeyRateLimit, verifyApiKey } from "./utils/verify-api-key";+import { apiKeyResponseHeaders } from "./utils/rate-limit-headers";+import { readApiKeyCheck, verifyApiKey } from "./utils/verify-api-key";import workflowRule from "./workflow-rule";import workspace from "./workspace";import {@@ -131,7 +129,7 @@ type ApiVariables = {userId: string;userEmail: string;apiKey?: ApiKey;- apiKeyRateLimit?: ApiKeyRateLimit | null;+ apiKeyHeaders?: Record<string, string>;};};@@ -243,14 +241,36 @@ export function createApp() {const api = new OpenAPIHono<ApiVariables>();- api.use("*", async (c, next) => {- await next();- const rateLimit = c.get("apiKeyRateLimit");- if (!rateLimit) return;- for (const [name, value] of Object.entries(rateLimitHeaders(rateLimit))) {- c.header(name, value);- }- });+ api.use("*", applyApiKeyHeaders);++ const apiKeyRateLimited = api.openAPIRegistry.registerComponent(+ "responses",+ "ApiKeyRateLimited",+ {+ description:+ "The API key exceeded its rate limit or usage quota. Wait the number of seconds in Retry-After before retrying. The X-RateLimit headers are sent only when the rate limit was hit.",+ headers: {+ "Retry-After": {+ description:+ "Seconds to wait before retrying. Omitted when an exhausted usage quota never refills.",+ schema: { type: "integer" },+ },+ "X-RateLimit-Limit": {+ description: "Requests the API key may make per window.",+ schema: { type: "integer" },+ },+ "X-RateLimit-Remaining": {+ description: "Requests left in the current window.",+ schema: { type: "integer" },+ },+ "X-RateLimit-Reset": {+ description: "Unix time in seconds when the current window resets.",+ schema: { type: "integer" },+ },+ },+ content: { "text/plain": { schema: { type: "string" } } },+ },+ );api.get("/health", (c) => {return c.json({ status: "ok" });@@ -423,7 +443,14 @@ export function createApp() {const apiKeyResult = await verifyApiKey(apiKeyHeader, { consume: false });if (apiKeyResult?.status !== "valid") throw apiKeyRejection(apiKeyResult);await next();- c.set("apiKeyRateLimit", await readApiKeyRateLimit(apiKeyHeader));+ c.set(+ "apiKeyHeaders",+ apiKeyResponseHeaders(+ await readApiKeyCheck(apiKeyHeader),+ c.res,+ new Date(),+ ),+ );});api.openapi(@@ -440,6 +467,7 @@ export function createApp() {200: {description: "Current session details, or null when unauthenticated",},+ 429: apiKeyRateLimited.ref,},}),async (c) => auth.handler(c.req.raw),@@ -464,6 +492,7 @@ export function createApp() {304: { description: "Not modified" },403: { description: "No access to this asset" },404: { description: "Asset not found" },+ 429: apiKeyRateLimited.ref,},}),async (c) => {@@ -583,34 +612,6 @@ export function createApp() {scheme: "bearer",description: "API key or session token (Bearer)",});- const apiKeyRateLimited = api.openAPIRegistry.registerComponent(- "responses",- "ApiKeyRateLimited",- {- description:- "The API key exceeded its rate limit or usage quota. Wait the number of seconds in Retry-After before retrying. The X-RateLimit headers are sent only when the rate limit was hit.",- headers: {- "Retry-After": {- description:- "Seconds to wait before retrying. Omitted when an exhausted usage quota never refills.",- schema: { type: "integer" },- },- "X-RateLimit-Limit": {- description: "Requests the API key may make per window.",- schema: { type: "integer" },- },- "X-RateLimit-Remaining": {- description: "Requests left in the current window.",- schema: { type: "integer" },- },- "X-RateLimit-Reset": {- description: "Unix time in seconds when the current window resets.",- schema: { type: "integer" },- },- },- content: { "text/plain": { schema: { type: "string" } } },- },- );organizationRoutes(api.openAPIRegistry);api.get("/openapi", (c) => {@@ -701,6 +702,7 @@ export function createApp() {description: "Redirects the browser to the web app device screen",},200: { description: "Device authorization payload from Better Auth" },+ 429: apiKeyRateLimited.ref,},}),async (c) => {@@ -745,7 +747,14 @@ export function createApp() {headers.set("x-api-key", bearerToken);const response = await auth.handler(new Request(c.req.raw, { headers }));- c.set("apiKeyRateLimit", await readApiKeyRateLimit(bearerToken));+ c.set(+ "apiKeyHeaders",+ apiKeyResponseHeaders(+ await readApiKeyCheck(bearerToken),+ response,+ new Date(),+ ),+ );return response;}diff --git a/apps/api/src/utils/api-key-rejection.test.ts b/apps/api/src/utils/api-key-rejection.test.tsnew file mode 100644index 000000000..c45e47ebd--- /dev/null+++ b/apps/api/src/utils/api-key-rejection.test.ts@@ -0,0 +1,59 @@+import { describe, expect, it } from "vite-plus/test";+import { betterAuthLimitRejection } from "./api-key-rejection";++const now = new Date("2026-01-01T00:00:00.000Z");+const rateLimitedBody = {+ code: "RATE_LIMITED",+ details: { tryAgainIn: 4_500 },+};++function headersOf(error: ReturnType<typeof betterAuthLimitRejection>) {+ return Object.fromEntries(error.getResponse().headers);+}++describe("betterAuthLimitRejection", () => {+ it("answers with the key's own retry headers when the key is denied", () => {+ const resetAt = new Date(now.getTime() + 30_000);+ const error = betterAuthLimitRejection(+ rateLimitedBody,+ { status: "rate_limited", limit: 10, resetAt },+ now,+ );++ expect(error.status).toBe(429);+ expect(headersOf(error)).toMatchObject({+ "retry-after": "30",+ "x-ratelimit-limit": "10",+ "x-ratelimit-remaining": "0",+ "x-ratelimit-reset": String(Math.ceil(resetAt.getTime() / 1000)),+ });+ });++ it("uses the refill time for an exhausted quota", async () => {+ const error = betterAuthLimitRejection(+ { code: "USAGE_EXCEEDED" },+ {+ status: "usage_exceeded",+ retryAt: new Date(now.getTime() + 120_000),+ rateLimit: null,+ },+ now,+ );++ expect(headersOf(error)).toMatchObject({ "retry-after": "120" });+ expect(await error.getResponse().text()).toBe(+ "API key usage limit exceeded",+ );+ });++ it("falls back to Better Auth's wait when the key cannot be checked", () => {+ for (const check of [null, { status: "valid" as const, rateLimit: null }]) {+ const error = betterAuthLimitRejection(rateLimitedBody, check, now);+ expect(error.status).toBe(429);+ expect(headersOf(error)).toEqual({+ "content-type": "text/plain;charset=UTF-8",+ "retry-after": "5",+ });+ }+ });+});diff --git a/apps/api/src/utils/api-key-rejection.ts b/apps/api/src/utils/api-key-rejection.tsindex 748d4151e..56c8412e0 100644--- a/apps/api/src/utils/api-key-rejection.ts+++ b/apps/api/src/utils/api-key-rejection.ts@@ -1,5 +1,6 @@import { HTTPException } from "hono/http-exception";import {+ type ApiKeyCheck,type ApiKeyDenial,apiKeyDenialHeaders,retryAfterSeconds,@@ -22,13 +23,21 @@ export function apiKeyRejection(denial: ApiKeyDenial | null, now = new Date()) {);}-export function betterAuthLimitRejection(body: unknown, now = new Date()) {+export function betterAuthLimitRejection(+ body: unknown,+ check: ApiKeyCheck | null,+ now = new Date(),+) {+ if (check && check.status !== "valid") return apiKeyRejection(check, now);const { code, details } = (body ?? {}) as {code?: unknown;details?: { tryAgainIn?: unknown };};if (code === "USAGE_EXCEEDED")- return apiKeyRejection({ status: "usage_exceeded", retryAt: null }, now);+ return apiKeyRejection(+ { status: "usage_exceeded", retryAt: null, rateLimit: null },+ now,+ );const tryAgainIn = details?.tryAgainIn;return tooManyRequests("Rate limit exceeded",diff --git a/apps/api/src/utils/api-key-usage.test.ts b/apps/api/src/utils/api-key-usage.test.tsnew file mode 100644index 000000000..3bab498eb--- /dev/null+++ b/apps/api/src/utils/api-key-usage.test.ts@@ -0,0 +1,124 @@+import { describe, expect, it } from "vite-plus/test";+import { type ApiKeyUsageRow, evaluateApiKeyUsage } from "./api-key-usage";++const now = new Date("2026-01-01T00:00:00.000Z");+const at = (ms: number) => new Date(now.getTime() + ms);++function row(overrides: Partial<ApiKeyUsageRow> = {}): ApiKeyUsageRow {+ return {+ createdAt: at(-86_400_000),+ lastRefillAt: null,+ lastRequest: at(-10_000),+ rateLimitEnabled: true,+ rateLimitMax: 5,+ rateLimitTimeWindow: 60_000,+ refillAmount: null,+ refillInterval: null,+ remaining: null,+ requestCount: 2,+ ...overrides,+ };+}++describe("evaluateApiKeyUsage", () => {+ it("reads the window without spending a request", () => {+ expect(evaluateApiKeyUsage(row(), now, false)).toEqual({+ status: "valid",+ remaining: null,+ lastRefillAt: null,+ requestCount: 2,+ rateLimit: { limit: 5, remaining: 3, resetAt: at(50_000) },+ });+ });++ it("spends one request and restarts the window when consuming", () => {+ expect(evaluateApiKeyUsage(row({ remaining: 4 }), now, true)).toEqual({+ status: "valid",+ remaining: 3,+ lastRefillAt: null,+ requestCount: 3,+ rateLimit: { limit: 5, remaining: 2, resetAt: at(60_000) },+ });+ });++ it("starts a fresh window after a full idle window", () => {+ expect(+ evaluateApiKeyUsage(+ row({ lastRequest: at(-60_000), requestCount: 5 }),+ now,+ false,+ ),+ ).toMatchObject({+ status: "valid",+ requestCount: 0,+ rateLimit: { limit: 5, remaining: 5, resetAt: at(60_000) },+ });+ });++ it("denies a full window", () => {+ expect(evaluateApiKeyUsage(row({ requestCount: 5 }), now, true)).toEqual({+ status: "rate_limited",+ limit: 5,+ resetAt: at(50_000),+ });+ });++ it("keeps the window on an exhausted quota", () => {+ expect(evaluateApiKeyUsage(row({ remaining: 0 }), now, false)).toEqual({+ status: "usage_exceeded",+ retryAt: null,+ rateLimit: { limit: 5, remaining: 3, resetAt: at(50_000) },+ });+ });++ it("reports when an exhausted quota refills", () => {+ expect(+ evaluateApiKeyUsage(+ row({+ remaining: 0,+ refillAmount: 10,+ refillInterval: 3_600_000,+ lastRefillAt: at(-600_000),+ rateLimitEnabled: false,+ }),+ now,+ true,+ ),+ ).toEqual({+ status: "usage_exceeded",+ retryAt: at(3_000_000),+ rateLimit: null,+ });+ });++ it("refills a due quota before spending from it", () => {+ expect(+ evaluateApiKeyUsage(+ row({+ remaining: 0,+ refillAmount: 10,+ refillInterval: 3_600_000,+ lastRefillAt: at(-3_600_000),+ }),+ now,+ true,+ ),+ ).toMatchObject({ status: "valid", remaining: 9, lastRefillAt: now });+ });++ it("leaves the stored count alone when rate limiting is off", () => {+ expect(+ evaluateApiKeyUsage(+ row({ rateLimitEnabled: false, requestCount: 7 }),+ now,+ true,+ ),+ ).toEqual({+ status: "valid",+ remaining: null,+ lastRefillAt: null,+ requestCount: 7,+ rateLimit: null,+ });+ });+});diff --git a/apps/api/src/utils/api-key-usage.ts b/apps/api/src/utils/api-key-usage.tsnew file mode 100644index 000000000..5fa9d33ca--- /dev/null+++ b/apps/api/src/utils/api-key-usage.ts@@ -0,0 +1,101 @@+import type { apikeyTable } from "../database/schema";+import type { ApiKeyDenial, ApiKeyRateLimit } from "./rate-limit-headers";++export type ApiKeyUsageRow = Pick<+ typeof apikeyTable.$inferSelect,+ | "createdAt"+ | "lastRefillAt"+ | "lastRequest"+ | "rateLimitEnabled"+ | "rateLimitMax"+ | "rateLimitTimeWindow"+ | "refillAmount"+ | "refillInterval"+ | "remaining"+ | "requestCount"+>;++export type ApiKeyAllowance = {+ status: "valid";+ remaining: number | null;+ lastRefillAt: Date | null;+ requestCount: number;+ rateLimit: ApiKeyRateLimit | null;+};++type RateWindow = {+ limit: number;+ length: number;+ count: number;+ anchor: Date;+};++function currentWindow(apiKey: ApiKeyUsageRow, now: Date): RateWindow {+ const limit = apiKey.rateLimitMax ?? 100;+ const length = apiKey.rateLimitTimeWindow ?? 60_000;+ const anchor = apiKey.lastRequest;+ if (!anchor || now.getTime() - anchor.getTime() >= length)+ return { limit, length, count: 0, anchor: now };+ return { limit, length, count: apiKey.requestCount ?? 0, anchor };+}++function windowRateLimit(window: RateWindow): ApiKeyRateLimit {+ return {+ limit: window.limit,+ remaining: window.limit - window.count,+ resetAt: new Date(window.anchor.getTime() + window.length),+ };+}++export function evaluateApiKeyUsage(+ apiKey: ApiKeyUsageRow,+ now: Date,+ consume: boolean,+): ApiKeyDenial | ApiKeyAllowance {+ let remaining = apiKey.remaining;+ let lastRefillAt = apiKey.lastRefillAt;+ if (+ remaining !== null &&+ apiKey.refillInterval &&+ apiKey.refillAmount &&+ now.getTime() - (lastRefillAt ?? apiKey.createdAt).getTime() >=+ apiKey.refillInterval+ ) {+ remaining = apiKey.refillAmount;+ lastRefillAt = now;+ }++ const window = apiKey.rateLimitEnabled ? currentWindow(apiKey, now) : null;++ if (remaining !== null && remaining <= 0)+ return {+ status: "usage_exceeded",+ retryAt:+ apiKey.refillInterval && apiKey.refillAmount+ ? new Date(+ (lastRefillAt ?? apiKey.createdAt).getTime() ++ apiKey.refillInterval,+ )+ : null,+ rateLimit: window && windowRateLimit(window),+ };++ if (window && window.count >= window.limit)+ return {+ status: "rate_limited",+ limit: window.limit,+ resetAt: windowRateLimit(window).resetAt,+ };++ const used =+ window && consume+ ? { ...window, count: window.count + 1, anchor: now }+ : window;+ return {+ status: "valid",+ remaining: consume && remaining !== null ? remaining - 1 : remaining,+ lastRefillAt,+ requestCount: used ? used.count : (apiKey.requestCount ?? 0),+ rateLimit: used && windowRateLimit(used),+ };+}diff --git a/apps/api/src/utils/apply-api-key-headers.test.ts b/apps/api/src/utils/apply-api-key-headers.test.tsnew file mode 100644index 000000000..e9e4c4d90--- /dev/null+++ b/apps/api/src/utils/apply-api-key-headers.test.ts@@ -0,0 +1,52 @@+import { Hono } from "hono";+import { describe, expect, it } from "vite-plus/test";+import { applyApiKeyHeaders } from "./apply-api-key-headers";++function appWith(cacheControl: string, apiKeyHeaders?: Record<string, string>) {+ const app = new Hono<{+ Variables: { apiKeyHeaders?: Record<string, string> };+ }>();+ app.use("*", applyApiKeyHeaders);+ app.get("/", (c) => {+ if (apiKeyHeaders) c.set("apiKeyHeaders", apiKeyHeaders);+ return new Response("asset", {+ headers: { "Cache-Control": cacheControl },+ });+ });+ return app;+}++const limitHeaders = {+ "X-RateLimit-Limit": "100",+ "X-RateLimit-Remaining": "99",+ "X-RateLimit-Reset": "1767225660",+};++describe("applyApiKeyHeaders", () => {+ it("adds the key's headers to the response", async () => {+ const response = await appWith("no-store", limitHeaders).request("/");++ expect(response.headers.get("x-ratelimit-remaining")).toBe("99");+ expect(response.headers.get("cache-control")).toBe("no-store");+ });++ it("keeps per-key headers out of shared caches", async () => {+ const response = await appWith("public, max-age=300", limitHeaders).request(+ "/",+ );++ expect(response.headers.get("x-ratelimit-limit")).toBe("100");+ expect(response.headers.get("cache-control")).toBe("private, max-age=300");+ });++ it("leaves responses without key headers untouched", async () => {+ for (const headers of [undefined, {}]) {+ const response = await appWith("public, max-age=300", headers).request(+ "/",+ );++ expect(response.headers.get("cache-control")).toBe("public, max-age=300");+ expect(response.headers.get("x-ratelimit-limit")).toBeNull();+ }+ });+});diff --git a/apps/api/src/utils/apply-api-key-headers.ts b/apps/api/src/utils/apply-api-key-headers.tsnew file mode 100644index 000000000..72bae8e8e--- /dev/null+++ b/apps/api/src/utils/apply-api-key-headers.ts@@ -0,0 +1,13 @@+import { createMiddleware } from "hono/factory";++export const applyApiKeyHeaders = createMiddleware<{+ Variables: { apiKeyHeaders?: Record<string, string> };+}>(async (c, next) => {+ await next();+ const headers = Object.entries(c.get("apiKeyHeaders") ?? {});+ if (headers.length === 0) return;+ for (const [name, value] of headers) c.header(name, value);+ const cacheControl = c.res.headers.get("Cache-Control");+ if (cacheControl && /\bpublic\b/i.test(cacheControl))+ c.header("Cache-Control", cacheControl.replace(/\bpublic\b/gi, "private"));+});diff --git a/apps/api/src/utils/authenticate-api-request.ts b/apps/api/src/utils/authenticate-api-request.tsindex 700a313c8..54a0ad23f 100644--- a/apps/api/src/utils/authenticate-api-request.ts+++ b/apps/api/src/utils/authenticate-api-request.ts@@ -4,7 +4,8 @@ import type { Context } from "hono";import { HTTPException } from "hono/http-exception";import { auth } from "../auth";import { apiKeyRejection, betterAuthLimitRejection } from "./api-key-rejection";-import { verifyApiKey } from "./verify-api-key";+import { type ApiKeyRateLimit, rateLimitHeaders } from "./rate-limit-headers";+import { readApiKeyCheck, verifyApiKey } from "./verify-api-key";// User is tagged on Sentry's isolation scope; the per-request isolation// scope is forked by Sentry.withIsolationScope in the api.use("*", ...)@@ -26,7 +27,11 @@ async function getSession(headers: Headers) {return await auth.api.getSession({ headers });} catch (error) {if (error instanceof APIError && error.statusCode === 429) {- throw betterAuthLimitRejection(error.body);+ const apiKeyHeader = headers.get("x-api-key")?.trim();+ throw betterAuthLimitRejection(+ error.body,+ apiKeyHeader ? await readApiKeyCheck(apiKeyHeader) : null,+ );}if (isAuthRejection(error)) {return null;@@ -65,6 +70,10 @@ function parseBearerToken(authHeader: string | undefined): {};}+function setRateLimitHeaders(c: Context, rateLimit: ApiKeyRateLimit | null) {+ if (rateLimit) c.set("apiKeyHeaders", rateLimitHeaders(rateLimit));+}+type VerifiedApiKey = Extract<Awaited<ReturnType<typeof verifyApiKey>>,{ status: "valid" }@@ -81,7 +90,7 @@ function setApiKeyContext(c: Context, { key, rateLimit }: VerifiedApiKey) {enabled: key.enabled,permissions: key.permissions,});- c.set("apiKeyRateLimit", rateLimit);+ setRateLimitHeaders(c, rateLimit);attachUserToScope(key.userId);}@@ -150,7 +159,7 @@ export async function resolveAssetBearerOrCookie(c: Context): Promise<{if (apiKeyResult?.status !== "valid") {throw apiKeyRejection(apiKeyResult);}- c.set("apiKeyRateLimit", apiKeyResult.rateLimit);+ setRateLimitHeaders(c, apiKeyResult.rateLimit);return {userId: apiKeyResult.key.userId,apiKeyId: apiKeyResult.key.id,@@ -160,7 +169,7 @@ export async function resolveAssetBearerOrCookie(c: Context): Promise<{if (token) {const apiKeyResult = await verifyApiKey(token);if (apiKeyResult?.status === "valid") {- c.set("apiKeyRateLimit", apiKeyResult.rateLimit);+ setRateLimitHeaders(c, apiKeyResult.rateLimit);return {userId: apiKeyResult.key.userId,apiKeyId: apiKeyResult.key.id,diff --git a/apps/api/src/utils/rate-limit-headers.test.ts b/apps/api/src/utils/rate-limit-headers.test.tsindex 281ba83dc..093820434 100644--- a/apps/api/src/utils/rate-limit-headers.test.ts+++ b/apps/api/src/utils/rate-limit-headers.test.ts@@ -1,6 +1,7 @@import { describe, expect, it } from "vite-plus/test";import {apiKeyDenialHeaders,+ apiKeyResponseHeaders,rateLimitHeaders,retryAfterSeconds,} from "./rate-limit-headers";@@ -58,12 +59,76 @@ describe("apiKeyDenialHeaders", () => {it("sends Retry-After for an exhausted quota only when it refills", () => {expect(apiKeyDenialHeaders(- { status: "usage_exceeded", retryAt: at(3_600_000) },+ { status: "usage_exceeded", retryAt: at(3_600_000), rateLimit: null },now,),).toEqual({ "Retry-After": "3600" });expect(- apiKeyDenialHeaders({ status: "usage_exceeded", retryAt: null }, now),+ apiKeyDenialHeaders(+ { status: "usage_exceeded", retryAt: null, rateLimit: null },+ now,+ ),).toEqual({});});});++describe("apiKeyResponseHeaders", () => {+ const window = { limit: 5, remaining: 2, resetAt: at(30_000) };+ const ok = new Response("ok");+ const tooMany = new Response("slow down", { status: 429 });++ it("reports the window after a successful request", () => {+ expect(+ apiKeyResponseHeaders({ status: "valid", rateLimit: window }, ok, now),+ ).toEqual(rateLimitHeaders(window));+ });++ it("still reports the window when the request spent the last quota unit", () => {+ expect(+ apiKeyResponseHeaders(+ { status: "usage_exceeded", retryAt: null, rateLimit: window },+ ok,+ now,+ ),+ ).toEqual(rateLimitHeaders(window));+ });++ it("reports an empty window when the request filled it", () => {+ expect(+ apiKeyResponseHeaders(+ { status: "rate_limited", limit: 5, resetAt: at(30_000) },+ ok,+ now,+ ),+ ).toEqual(rateLimitHeaders({ ...window, remaining: 0 }));+ });++ it("adds the retry headers to a 429 that lacks Retry-After", () => {+ const denial = {+ status: "rate_limited" as const,+ limit: 5,+ resetAt: at(30_000),+ };+ expect(apiKeyResponseHeaders(denial, tooMany, now)).toEqual(+ apiKeyDenialHeaders(denial, now),+ );+ });++ it("leaves Retry-After alone when the 429 already has one", () => {+ const answered = new Response(null, {+ status: 429,+ headers: { "Retry-After": "7" },+ });+ expect(+ apiKeyResponseHeaders(+ { status: "rate_limited", limit: 5, resetAt: at(30_000) },+ answered,+ now,+ ),+ ).not.toHaveProperty("Retry-After");+ });++ it("sends nothing when the key could not be read", () => {+ expect(apiKeyResponseHeaders(null, tooMany, now)).toEqual({});+ });+});diff --git a/apps/api/src/utils/rate-limit-headers.ts b/apps/api/src/utils/rate-limit-headers.tsindex 0ec36558c..f05c40fe2 100644--- a/apps/api/src/utils/rate-limit-headers.ts+++ b/apps/api/src/utils/rate-limit-headers.ts@@ -6,7 +6,15 @@ export type ApiKeyRateLimit = {export type ApiKeyDenial =| { status: "rate_limited"; limit: number; resetAt: Date }- | { status: "usage_exceeded"; retryAt: Date | null };+ | {+ status: "usage_exceeded";+ retryAt: Date | null;+ rateLimit: ApiKeyRateLimit | null;+ };++export type ApiKeyCheck =+ | ApiKeyDenial+ | { status: "valid"; rateLimit: ApiKeyRateLimit | null };export function retryAfterSeconds(retryAt: Date, now: Date) {return String(@@ -44,3 +52,24 @@ export function apiKeyDenialHeaders(? { "Retry-After": retryAfterSeconds(denial.retryAt, now) }: {};}++export function apiKeyResponseHeaders(+ check: ApiKeyCheck | null,+ response: Response,+ now: Date,+): Record<string, string> {+ if (!check) return {};+ if (+ check.status !== "valid" &&+ response.status === 429 &&+ !response.headers.has("Retry-After")+ )+ return apiKeyDenialHeaders(check, now);+ if (check.status === "rate_limited")+ return rateLimitHeaders({+ limit: check.limit,+ remaining: 0,+ resetAt: check.resetAt,+ });+ return check.rateLimit ? rateLimitHeaders(check.rateLimit) : {};+}diff --git a/apps/api/src/utils/verify-api-key.ts b/apps/api/src/utils/verify-api-key.tsindex 2b5e5f4a5..82c3fb3d0 100644--- a/apps/api/src/utils/verify-api-key.ts+++ b/apps/api/src/utils/verify-api-key.ts@@ -1,7 +1,7 @@import { createHash } from "node:crypto";import { and, eq, exists, gt, isNull, or, sql } from "drizzle-orm";import db, { schema } from "../database";-import type { ApiKeyRateLimit } from "./rate-limit-headers";+import { evaluateApiKeyUsage } from "./api-key-usage";import { notBannedCondition } from "./user-ban";async function hashApiKey(key: string): Promise<string> {@@ -38,41 +38,67 @@ function parsePermissions(raw: string | null): Record<string, string[]> | null {return permissions;}+function activeApiKey(hashedKey: string) {+ return and(+ eq(schema.apikeyTable.key, hashedKey),+ eq(schema.apikeyTable.enabled, true),+ // Fail closed even before legacy databases finish the repair migration.+ exists(+ db+ .select({ id: schema.userTable.id })+ .from(schema.userTable)+ .where(+ and(+ eq(+ schema.userTable.id,+ sql`coalesce(${schema.apikeyTable.referenceId}, ${schema.apikeyTable.userId})`,+ ),+ notBannedCondition(),+ ),+ ),+ ),+ or(+ isNull(schema.apikeyTable.expiresAt),+ gt(schema.apikeyTable.expiresAt, new Date()),+ ),+ );+}++async function checkApiKey(hashedKey: string) {+ const [apiKey] = await db+ .select()+ .from(schema.apikeyTable)+ .where(activeApiKey(hashedKey))+ .limit(1);+ if (!apiKey) return null;++ const usage = evaluateApiKeyUsage(apiKey, new Date(), false);+ if (usage.status !== "valid") return usage;+ return {+ status: "valid" as const,+ rateLimit: usage.rateLimit,+ key: {+ ...apiKey,+ userId: apiKey.referenceId ?? apiKey.userId ?? "",+ enabled: apiKey.enabled ?? false,+ permissions: parsePermissions(apiKey.permissions),+ metadata: null,+ },+ };+}+export async function verifyApiKey(key: string,options: { consume?: boolean } = {},) {const hashedKey = await hashApiKey(key);+ if (options.consume === false) return checkApiKey(hashedKey);return db.transaction(async (tx) => {const [apiKey] = await tx.select().from(schema.apikeyTable)- .where(- and(- eq(schema.apikeyTable.key, hashedKey),- eq(schema.apikeyTable.enabled, true),- // Fail closed even before legacy databases finish the repair migration.- exists(- db- .select({ id: schema.userTable.id })- .from(schema.userTable)- .where(- and(- eq(- schema.userTable.id,- sql`coalesce(${schema.apikeyTable.referenceId}, ${schema.apikeyTable.userId})`,- ),- notBannedCondition(),- ),- ),- ),- or(- isNull(schema.apikeyTable.expiresAt),- gt(schema.apikeyTable.expiresAt, new Date()),- ),- ),- )+ .where(activeApiKey(hashedKey)).limit(1).for("update");@@ -85,71 +111,10 @@ export async function verifyApiKey(// Locking the key serializes quota/refill and window accounting across API// instances. Neither a stale lookup nor a rejected request can restore quota.- let remaining = apiKey.remaining;- let lastRefillAt = apiKey.lastRefillAt;- if (remaining !== null) {- if (- apiKey.refillInterval &&- apiKey.refillAmount &&- now.getTime() - (lastRefillAt ?? apiKey.createdAt).getTime() >=- apiKey.refillInterval- ) {- remaining = apiKey.refillAmount;- lastRefillAt = now;- }- if (remaining <= 0)- return {- status: "usage_exceeded" as const,- retryAt:- apiKey.refillInterval && apiKey.refillAmount- ? new Date(- (lastRefillAt ?? apiKey.createdAt).getTime() +- apiKey.refillInterval,- )- : null,- };- }- let requestCount = apiKey.requestCount ?? 0;- let rateLimit: ApiKeyRateLimit | null = null;- if (apiKey.rateLimitEnabled) {- const window = apiKey.rateLimitTimeWindow ?? 60_000;- const limit = apiKey.rateLimitMax ?? 100;- let windowAnchor = apiKey.lastRequest;- if (!windowAnchor || now.getTime() - windowAnchor.getTime() >= window) {- requestCount = 0;- windowAnchor = now;- }- if (requestCount >= limit)- return {- status: "rate_limited" as const,- limit,- resetAt: new Date(windowAnchor.getTime() + window),- };- if (options.consume !== false) {- requestCount++;- windowAnchor = now;- }- rateLimit = {- limit,- remaining: limit - requestCount,- resetAt: new Date(windowAnchor.getTime() + window),- };- }+ const usage = evaluateApiKeyUsage(apiKey, now, true);+ if (usage.status !== "valid") return usage;- if (options.consume === false)- return {- status: "valid" as const,- rateLimit,- key: {- ...apiKey,- userId: apiKey.referenceId ?? apiKey.userId ?? "",- enabled: apiKey.enabled ?? false,- permissions: parsePermissions(apiKey.permissions),- metadata: null,- },- };-- if (remaining !== null) remaining--;+ const { remaining, lastRefillAt, requestCount, rateLimit } = usage;await tx.update(schema.apikeyTable).set({@@ -190,11 +155,11 @@ export async function verifyApiKey(});}-export async function readApiKeyRateLimit(- key: string,-): Promise<ApiKeyRateLimit | null> {- const result = await verifyApiKey(key, { consume: false });- if (result?.status === "rate_limited")- return { limit: result.limit, remaining: 0, resetAt: result.resetAt };- return result?.status === "valid" ? result.rateLimit : null;+export async function readApiKeyCheck(key: string) {+ try {+ return await verifyApiKey(key, { consume: false });+ } catch (error) {+ console.error("Failed to read API key usage:", error);+ return null;+ }}diff --git a/apps/docs/openapi.json b/apps/docs/openapi.jsonindex 1b39f9a15..550dd2cb6 100644--- a/apps/docs/openapi.json+++ b/apps/docs/openapi.json@@ -17,13 +17,6 @@}],"components": {- "securitySchemes": {- "bearerAuth": {- "type": "http",- "scheme": "bearer",- "description": "API key or session token (Bearer)"- }- },"responses": {"ApiKeyRateLimited": {"description": "The API key exceeded its rate limit or usage quota. Wait the number of seconds in Retry-After before retrying. The X-RateLimit headers are sent only when the rate limit was hit.",@@ -62,6 +55,13 @@}}},+ "securitySchemes": {+ "bearerAuth": {+ "type": "http",+ "scheme": "bearer",+ "description": "API key or session token (Bearer)"+ }+ },"schemas": {"InstanceStatus": {"type": "object",@@ -5246,6 +5246,9 @@"responses": {"200": {"description": "Current session details, or null when unauthenticated"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5289,6 +5292,9 @@},"404": {"description": "Asset not found"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7544,6 +7550,9 @@},"302": {"description": "Redirects the browser to the web app device screen"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}diff --git a/tests/api-integration/api-key-accounting.test.ts b/tests/api-integration/api-key-accounting.test.tsindex c234a4c68..4f86539c4 100644--- a/tests/api-integration/api-key-accounting.test.ts+++ b/tests/api-integration/api-key-accounting.test.ts@@ -36,6 +36,7 @@ describe("API key accounting", () => {expect(await verifyApiKey(key)).toEqual({status: "usage_exceeded",retryAt: null,+ rateLimit: { limit: 2, remaining: 2, resetAt: expect.any(Date) },});});it("enforces a rate window across concurrent requests", async () => {@@ -108,54 +109,74 @@ it("creates normal API keys with the configured 100-per-minute limit", async ()expect(await verifyApiKey(created.key)).toMatchObject({ status: "valid" });});-it.each([true, false])(- "rejects a key that expires while waiting for its row lock (consume=%s)",- async (consume) => {- const expiresAt = new Date(Date.now() + 1200);- const { key, row } = await seedKey({ expiresAt, remaining: 1 });- let release!: () => void;- let ready!: () => void;- const locked = new Promise<void>((resolve) => {- ready = resolve;- });- const hold = new Promise<void>((resolve) => {- release = resolve;- });- const holder = db.transaction(async (tx) => {- await tx- .select()- .from(schema.apikeyTable)- .where(eq(schema.apikeyTable.id, row.id))- .for("update");- ready();- await hold;+async function holdRowLock(id: string) {+ let release!: () => void;+ let ready!: () => void;+ const locked = new Promise<void>((resolve) => {+ ready = resolve;+ });+ const hold = new Promise<void>((resolve) => {+ release = resolve;+ });+ const holder = db.transaction(async (tx) => {+ await tx+ .select()+ .from(schema.apikeyTable)+ .where(eq(schema.apikeyTable.id, id))+ .for("update");+ ready();+ await hold;+ });+ await locked;+ return { release, holder };+}++it("reads a key without waiting for its row lock", async () => {+ const { key, row } = await seedKey({ remaining: 1 });+ const { release, holder } = await holdRowLock(row.id);+ try {+ const result = await Promise.race([+ verifyApiKey(key, { consume: false }),+ new Promise((resolve) => setTimeout(() => resolve("blocked"), 2_000)),+ ]);+ expect(result).toMatchObject({+ status: "valid",+ rateLimit: { limit: 2, remaining: 2 },});- await locked;- try {- const verification = verifyApiKey(key, { consume });- let waiting = false;- for (let attempt = 0; attempt < 100 && !waiting; attempt++) {- const result = await getDatabasePool().query<{ waiting: boolean }>(- `SELECT EXISTS (SELECT 1 FROM pg_stat_activity WHERE datname = current_database() AND wait_event_type = 'Lock' AND query LIKE '%"apikey"%') AS waiting`,- );- waiting = result.rows[0].waiting;- if (!waiting) await new Promise((resolve) => setTimeout(resolve, 10));- }- expect(waiting).toBe(true);- await new Promise((resolve) =>- setTimeout(resolve, Math.max(0, expiresAt.getTime() - Date.now() + 50)),+ } finally {+ release();+ await holder;+ }+});++it("rejects a key that expires while waiting for its row lock", async () => {+ const expiresAt = new Date(Date.now() + 1200);+ const { key, row } = await seedKey({ expiresAt, remaining: 1 });+ const { release, holder } = await holdRowLock(row.id);+ try {+ const verification = verifyApiKey(key);+ let waiting = false;+ for (let attempt = 0; attempt < 100 && !waiting; attempt++) {+ const result = await getDatabasePool().query<{ waiting: boolean }>(+ `SELECT EXISTS (SELECT 1 FROM pg_stat_activity WHERE datname = current_database() AND wait_event_type = 'Lock' AND query LIKE '%"apikey"%') AS waiting`,);- release();- await expect(verification).resolves.toBeNull();- const [saved] = await db- .select()- .from(schema.apikeyTable)- .where(eq(schema.apikeyTable.id, row.id));- expect(saved.remaining).toBe(1);- expect(saved.requestCount).toBe(0);- } finally {- release();- await holder;+ waiting = result.rows[0].waiting;+ if (!waiting) await new Promise((resolve) => setTimeout(resolve, 10));}- },-);+ expect(waiting).toBe(true);+ await new Promise((resolve) =>+ setTimeout(resolve, Math.max(0, expiresAt.getTime() - Date.now() + 50)),+ );+ release();+ await expect(verification).resolves.toBeNull();+ const [saved] = await db+ .select()+ .from(schema.apikeyTable)+ .where(eq(schema.apikeyTable.id, row.id));+ expect(saved.remaining).toBe(1);+ expect(saved.requestCount).toBe(0);+ } finally {+ release();+ await holder;+ }+});diff --git a/tests/api-integration/api-key-rate-limit.test.ts b/tests/api-integration/api-key-rate-limit.test.tsindex 22d4da2d7..cdacb22f5 100644--- a/tests/api-integration/api-key-rate-limit.test.ts+++ b/tests/api-integration/api-key-rate-limit.test.ts@@ -1,7 +1,8 @@import { createHash, randomUUID } from "node:crypto";import { eq } from "drizzle-orm";-import { beforeEach, describe, expect, it } from "vite-plus/test";-import db, { schema } from "../../apps/api/src/database";+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";+import { auth } from "../../apps/api/src/auth";+import db, { getDatabase, schema } from "../../apps/api/src/database";import { createApp } from "../../apps/api/src/index";import { signUpWithSession } from "./helpers/auth-session";import { resetTestDatabase } from "./helpers/database";@@ -172,8 +173,121 @@ describe("API key rate limits", () => {expect(response.status).toBe(429);expect(await response.text()).toContain("Rate limit exceeded");- expect(Number(limitHeaders(response).retryAfter)).toBeGreaterThanOrEqual(- 59,+ const headers = limitHeaders(response);+ expect(headers).toMatchObject({+ limit: String(LIMIT),+ remaining: "0",+ reset: expect.stringMatching(/^\d+$/),+ });+ expect(Number(headers.retryAfter)).toBeGreaterThanOrEqual(59);+ });++ it("answers 429 with the refill time when Better Auth rejects an exhausted key", async () => {+ const { key } = await seedKey({+ remaining: 0,+ refillAmount: 5,+ refillInterval: 3_600_000,+ lastRefillAt: new Date(Date.now() - 600_000),+ });+ const { app } = createApp();++ const response = await app.request("/api/user/me", {+ headers: { Authorization: "Bearer not-a-real-key", "x-api-key": key },+ });++ expect(response.status).toBe(429);+ expect(await response.text()).toContain("API key usage limit exceeded");+ const retryAfter = Number(limitHeaders(response).retryAfter);+ expect(retryAfter).toBeGreaterThanOrEqual(2_999);+ expect(retryAfter).toBeLessThanOrEqual(3_000);+ });++ it.each([+ [+ "x-api-key",+ "/api/auth/get-session",+ (key: string) => ({ "x-api-key": key }),+ ],+ [+ "a Bearer key",+ "/api/auth/organization/list",+ (key: string) => ({ Authorization: `Bearer ${key}` }),+ ],+ ])(+ "reports the window on an auth request that spends the last quota unit via %s",+ async (_, path, headersFor) => {+ const { key, row } = await seedKey({ remaining: 1 });+ const { app } = createApp();++ const response = await app.request(path, { headers: headersFor(key) });++ expect(response.status).toBe(200);+ expect(limitHeaders(response)).toMatchObject({+ limit: String(LIMIT),+ remaining: String(LIMIT - 1),+ retryAfter: null,+ });+ expect((await savedKey(row.id)).remaining).toBe(0);+ },+ );++ it.each([+ [+ "x-api-key",+ "/api/auth/get-session",+ (key: string) => ({ "x-api-key": key }),+ ],+ [+ "a Bearer key",+ "/api/auth/organization/list",+ (key: string) => ({ Authorization: `Bearer ${key}` }),+ ],+ ])(+ "adds retry headers when the window fills before Better Auth checks a key via %s",+ async (_, path, headersFor) => {+ const { key, row } = await seedKey();+ const handler = auth.handler;+ vi.spyOn(auth, "handler").mockImplementationOnce(async (request) => {+ await fillWindow(row.id, new Date());+ return handler(request);+ });+ const { app } = createApp();++ const response = await app.request(path, { headers: headersFor(key) });++ expect(response.status).toBe(429);+ const headers = limitHeaders(response);+ expect(headers).toMatchObject({ limit: String(LIMIT), remaining: "0" });+ expect(Number(headers.retryAfter)).toBeGreaterThanOrEqual(59);+ expect(Number(headers.retryAfter)).toBeLessThanOrEqual(60);+ },+ );++ it("still answers when the rate limit headers cannot be read", async () => {+ const { key, row } = await seedKey();+ const handler = auth.handler;+ const errors = vi.spyOn(console, "error").mockImplementation(() => {});+ vi.spyOn(auth, "handler").mockImplementationOnce(async (request) => {+ const response = await handler(request);+ vi.spyOn(getDatabase(), "select").mockImplementationOnce(() => {+ throw new Error("database unavailable");+ });+ return response;+ });+ const { app } = createApp();++ const response = await app.request("/api/auth/get-session", {+ headers: { "x-api-key": key },+ });++ expect(response.status).toBe(200);+ expect(await response.json()).toMatchObject({+ user: { id: row.referenceId },+ });+ expect(limitHeaders(response).limit).toBeNull();+ expect(errors).toHaveBeenCalledWith(+ "Failed to read API key usage:",+ expect.any(Error),);});diff --git a/tests/api-integration/openapi.test.ts b/tests/api-integration/openapi.test.tsindex 72c12655f..d656dc3a3 100644--- a/tests/api-integration/openapi.test.ts+++ b/tests/api-integration/openapi.test.ts@@ -150,4 +150,27 @@ describe("Kaneo API OpenAPI spec", () => {$ref: "#/components/responses/ApiKeyRateLimited",});});++ it("documents the API key rate limit on public routes that read an API key", () => {+ const byId = new Map(+ operations(spec).map(([, , operation]) => [+ operation.operationId,+ operation,+ ]),+ );+ for (const id of ["getSession", "getAsset", "getDeviceAuthorizationPage"]) {+ expect(byId.get(id)?.responses["429"], id).toEqual({+ $ref: "#/components/responses/ApiKeyRateLimited",+ });+ }+ for (const id of [+ "getInstanceStatus",+ "getPublicProject",+ "getUserAvatar",+ "getCalendarFeed",+ "getConfig",+ ]) {+ expect(byId.get(id)?.responses["429"], id).toBeUndefined();+ }+ });});