Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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();
+ }
+ });
});