Skip to content

AI-native design editor. Open-source Figma alternative.

fix(cloud): cap route rate budgets per actor across resources (#1740)

Danila Poyarkov7e53c9b2cee4
diff --git a/changes/1740/security.md b/changes/1740/security.md
new file mode 100644
index 000000000..57a6679ea
--- /dev/null
+++ b/changes/1740/security.md
@@ -0,0 +1 @@
+- Cloud caps how many uploads, documents, collaboration tickets, and invitations one account can request per minute across all of its documents and workspaces, not only per document or workspace.
diff --git a/packages/cloud/AGENTS.md b/packages/cloud/AGENTS.md
index c50eee857..708dddd59 100644
--- a/packages/cloud/AGENTS.md
+++ b/packages/cloud/AGENTS.md
@@ -19,7 +19,7 @@ Optional, self-hostable backend; the design is in `packages/docs/development/clo
- Renaming a table that shipped migrations query gives them a type under the name they ran with, so their SQL stays the same (`LegacyAuthSchemaDatabase` in `src/server/db/migrations/helpers.ts`).
- `user.image` only ever holds an address this server serves; a picture from anywhere else is copied into `user_picture` or dropped, never linked, and a provider's picture comes from the ID token on its account row, never from the endpoint that wrote it (`src/server/pictures/provider.ts`, `tests/integration/server/pictures/provider.test.ts`).
- Name a Better Auth endpoint by the object that declares it: a plugin's from the plugin the factory builds, a core one from `auth.api`; only the core paths options need before Better Auth is built are written out, in `CORE_AUTH_PATHS`, where the type check holds them to the library's own. Match hook paths with `isAuthEndpoint`, and put endpoints clients must not reach in `disabledPaths` (`src/server/auth/factory.ts`, `src/server/auth/endpoints.ts`).
-- A route with a rate budget of its own mounts `createRouteRateLimiter`, and general limiters skip what it counts through `routeHasOwnBudget`; never exempt routes by matching their paths (`tests/integration/server/rate-limit/budgets.test.ts`).
+- A route with a rate budget of its own mounts `createRouteRateLimiter`, or `createResourceRateLimiter` for a budget per resource, whose policy also caps the actor across resources; general limiters skip what either counts through `routeHasOwnBudget`, so never exempt routes by matching their paths (`tests/integration/server/rate-limit/budgets.test.ts`).
- Database rows use `crypto.randomUUID()`; secrets that leave the server use `randomHex` from `@open-pencil/scene-graph/random`, are stored as SHA-256 digests (a single-use OAuth continuation keeps a JWE copy), and travel in URL fragments (`src/server/sharing/capabilities/service.ts`).
- An admin list takes `search`, `filter`, `limit`, and `offset` through `listQuery` and answers with its rows, `total`, and per-filter `counts`; it declares its filters once as `ListFilters`, which count in one query and page with the same condition (`src/admin/list.ts`, `tests/integration/admin/lists.test.ts`).
- Every HTTP body goes through `validatedJSON` with a contract schema, and every response the client reads is parsed with Valibot (`src/server/validation.ts`, `src/client/api.ts`).
diff --git a/packages/cloud/src/server/api/types.ts b/packages/cloud/src/server/api/types.ts
index e731c38af..2fe738741 100644
--- a/packages/cloud/src/server/api/types.ts
+++ b/packages/cloud/src/server/api/types.ts
@@ -1,7 +1,14 @@
import type { CloudActor } from '#cloud/server/auth'
+/** What a rate limiter records on the request about the budget it just counted. */
+export type RateLimitUse = { limit: number; remaining: number; resetTime?: Date }
+
export type CloudAPIEnvironment = {
Variables: {
actor: CloudActor
+ /** Set by `hono-rate-limiter` for the last budget it counted. */
+ rateLimit?: RateLimitUse
+ /** A resource budget's use, kept before the actor-wide budget records its own. */
+ resourceRateLimit?: RateLimitUse
}
}
diff --git a/packages/cloud/src/server/collaboration/routes.ts b/packages/cloud/src/server/collaboration/routes.ts
index fb05393c9..a90601283 100644
--- a/packages/cloud/src/server/collaboration/routes.ts
+++ b/packages/cloud/src/server/collaboration/routes.ts
@@ -5,8 +5,8 @@ import type { CloudDatabase } from '#cloud/server/db'
import { DocumentNotFoundError } from '#cloud/server/documents'
import {
CLOUD_RATE_LIMITS,
- createRouteRateLimiter,
- routeParamResource
+ routeParamResource,
+ createResourceRateLimiter
} from '#cloud/server/rate-limit'
import { DocumentShareInvalidError, DocumentShareSignInRequiredError } from '#cloud/server/sharing'
import { documentParams, shareParams, validatedJSON } from '#cloud/server/validation'
@@ -33,11 +33,10 @@ export function createCollaborationRoutes(
if (rateLimit) {
router.use(
'/documents/:documentId/collaboration-ticket',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.collaborationTicket,
- undefined,
routeParamResource('documentId')
)
)
diff --git a/packages/cloud/src/server/documents/routes.ts b/packages/cloud/src/server/documents/routes.ts
index 39abaf3e9..8ede83b73 100644
--- a/packages/cloud/src/server/documents/routes.ts
+++ b/packages/cloud/src/server/documents/routes.ts
@@ -18,8 +18,8 @@ import type { DocumentService } from '#cloud/server/documents/service'
import { StorageQuotaExceededError } from '#cloud/server/quota'
import {
CLOUD_RATE_LIMITS,
- createRouteRateLimiter,
- routeParamResource
+ routeParamResource,
+ createResourceRateLimiter
} from '#cloud/server/rate-limit'
import {
documentParams,
@@ -78,32 +78,32 @@ export function createDocumentRoutes(
if (rateLimit) {
router.use(
'/workspaces/:workspaceId/documents',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.documentCreation,
- (context) => context.req.method !== 'POST',
- routeParamResource('workspaceId')
+ routeParamResource('workspaceId'),
+ (context) => context.req.method !== 'POST'
)
)
router.use(
'/documents/:documentId/images',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.uploadCreation,
- (context) => context.req.method !== 'POST',
- routeParamResource('documentId')
+ routeParamResource('documentId'),
+ (context) => context.req.method !== 'POST'
)
)
router.use(
'/documents/:documentId/uploads',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.uploadCreation,
- (context) => context.req.method !== 'POST',
- routeParamResource('documentId')
+ routeParamResource('documentId'),
+ (context) => context.req.method !== 'POST'
)
)
}
diff --git a/packages/cloud/src/server/rate-limit/index.ts b/packages/cloud/src/server/rate-limit/index.ts
index 4bce27f23..d28b3c52d 100644
--- a/packages/cloud/src/server/rate-limit/index.ts
+++ b/packages/cloud/src/server/rate-limit/index.ts
@@ -4,10 +4,12 @@ export {
CLOUD_RATE_LIMITS,
createActorRateLimiter,
createCloudRateLimiter,
+ createResourceRateLimiter,
createRouteRateLimiter,
createTrustedIPRateLimiter,
routeHasOwnBudget,
routeParamResource,
- type RateLimitPolicy
+ type RateLimitPolicy,
+ type ResourceRateLimitPolicy
} from './middleware'
export { PostgresRateLimitStore } from './postgres'
diff --git a/packages/cloud/src/server/rate-limit/middleware.ts b/packages/cloud/src/server/rate-limit/middleware.ts
index cef9a4074..5935d4240 100644
--- a/packages/cloud/src/server/rate-limit/middleware.ts
+++ b/packages/cloud/src/server/rate-limit/middleware.ts
@@ -1,7 +1,8 @@
-import type { CloudAPIEnvironment } from '#cloud/server/api/types'
+import type { CloudAPIEnvironment, RateLimitUse } from '#cloud/server/api/types'
import type { CloudDatabase } from '#cloud/server/db'
-import type { Context, Env, Input } from 'hono'
+import type { Context, Env, Input, MiddlewareHandler } from 'hono'
import { rateLimiter, type RateLimitExceededEventHandler } from 'hono-rate-limiter'
+import { every } from 'hono/combine'
import { matchedRoutes } from 'hono/route'
import type { Kysely } from 'kysely'
@@ -14,18 +15,39 @@ export type RateLimitPolicy = {
limit: number
}
+/**
+ * A budget counted per resource, such as a document, with `actorLimit` capping one actor across
+ * every resource, so new resources do not add budget without end.
+ */
+export type ResourceRateLimitPolicy = RateLimitPolicy & { actorLimit: number }
+
export const CLOUD_RATE_LIMITS = {
publicCapability: { namespace: 'public-capability', windowMs: 60_000, limit: 30 },
- collaborationTicket: { namespace: 'collaboration-ticket', windowMs: 60_000, limit: 60 },
- invitationMutation: { namespace: 'invitation-mutation', windowMs: 60_000, limit: 30 },
+ collaborationTicket: {
+ namespace: 'collaboration-ticket',
+ windowMs: 60_000,
+ limit: 60,
+ actorLimit: 300
+ },
+ invitationMutation: {
+ namespace: 'invitation-mutation',
+ windowMs: 60_000,
+ limit: 30,
+ actorLimit: 60
+ },
workspaceCreation: { namespace: 'workspace-creation', windowMs: 60_000, limit: 30 },
- documentCreation: { namespace: 'document-creation', windowMs: 60_000, limit: 60 },
- uploadCreation: { namespace: 'upload-creation', windowMs: 60_000, limit: 120 },
+ documentCreation: {
+ namespace: 'document-creation',
+ windowMs: 60_000,
+ limit: 60,
+ actorLimit: 120
+ },
+ uploadCreation: { namespace: 'upload-creation', windowMs: 60_000, limit: 120, actorLimit: 600 },
authenticatedMutation: { namespace: 'authenticated-mutation', windowMs: 60_000, limit: 120 },
aiToken: { namespace: 'ai-token', windowMs: 60_000, limit: 30 },
adminRead: { namespace: 'admin-read', windowMs: 60_000, limit: 300 },
adminMutation: { namespace: 'admin-mutation', windowMs: 60_000, limit: 30 }
-} as const satisfies Record<string, RateLimitPolicy>
+} as const satisfies Record<string, RateLimitPolicy | ResourceRateLimitPolicy>
/**
* The limiters routes mount for their own budget, each with which requests it counts. A general
@@ -123,17 +145,71 @@ export function createActorRateLimiter(
}
/**
- * A limiter a route mounts for its own budget, such as document creation; general limiters leave
+ * A limiter a route mounts for its own budget, such as workspace creation; general limiters leave
* the requests it counts to it.
*/
export function createRouteRateLimiter(
database: Kysely<CloudDatabase>,
secret: string,
policy: RateLimitPolicy,
- skip?: (context: Context) => boolean,
- resource?: (context: Context<CloudAPIEnvironment, '*'>) => string
+ skip?: (context: Context) => boolean
+) {
+ return ownBudget(createActorRateLimiter(database, secret, policy, skip), skip)
+}
+
+/**
+ * A route's own budget counted per resource, such as uploads per document, and capped per actor
+ * across resources by `actorLimit`; general limiters leave the requests it counts to it.
+ */
+export function createResourceRateLimiter(
+ database: Kysely<CloudDatabase>,
+ secret: string,
+ policy: ResourceRateLimitPolicy,
+ resource: (context: Context<CloudAPIEnvironment, '*'>) => string,
+ skip?: (context: Context) => boolean
) {
- return ownBudget(createActorRateLimiter(database, secret, policy, skip, resource), skip)
+ const perResource = createActorRateLimiter(database, secret, policy, skip, resource)
+ const perActor = createActorRateLimiter(
+ database,
+ secret,
+ { namespace: `${policy.namespace}-actor`, windowMs: policy.windowMs, limit: policy.actorLimit },
+ skip
+ )
+ return ownBudget(
+ every(perResource, keepResourceUse, perActor, reportTighterBudget(policy.windowMs)),
+ skip
+ )
+}
+
+/** Keeps the resource budget's use, which the actor-wide limiter would record over. */
+const keepResourceUse: MiddlewareHandler<CloudAPIEnvironment> = async (context, next) => {
+ context.set('resourceRateLimit', context.get('rateLimit'))
+ await next()
+}
+
+/**
+ * Reports whichever budget has fewer requests left in the `RateLimit` headers, as both limiters
+ * write them and the last would otherwise win. A refused request keeps the headers of the budget
+ * that refused it.
+ */
+function reportTighterBudget(windowMs: number): MiddlewareHandler<CloudAPIEnvironment> {
+ return async (context, next) => {
+ const resource = context.get('resourceRateLimit')
+ const actor = context.get('rateLimit')
+ const tighter = resource && actor && resource.remaining < actor.remaining ? resource : actor
+ if (tighter) setBudgetHeaders(context, tighter, windowMs)
+ await next()
+ }
+}
+
+/** The draft-7 `RateLimit` headers `hono-rate-limiter` writes, for one budget's use. */
+function setBudgetHeaders(context: Context, use: RateLimitUse, windowMs: number): void {
+ const windowSeconds = Math.ceil(windowMs / 1000)
+ const reset = use.resetTime
+ ? Math.max(0, Math.ceil((use.resetTime.getTime() - Date.now()) / 1000))
+ : windowSeconds
+ context.header('RateLimit-Policy', `${use.limit};w=${windowSeconds}`)
+ context.header('RateLimit', `limit=${use.limit}, remaining=${use.remaining}, reset=${reset}`)
}
/**
diff --git a/packages/cloud/src/server/sharing/routes.ts b/packages/cloud/src/server/sharing/routes.ts
index e7909ee08..f8730c0ad 100644
--- a/packages/cloud/src/server/sharing/routes.ts
+++ b/packages/cloud/src/server/sharing/routes.ts
@@ -12,8 +12,8 @@ import type { CloudActor, CloudSessionResolver } from '#cloud/server/auth'
import type { CloudDatabase } from '#cloud/server/db'
import {
CLOUD_RATE_LIMITS,
- createRouteRateLimiter,
- routeParamResource
+ routeParamResource,
+ createResourceRateLimiter
} from '#cloud/server/rate-limit'
import { sharingRoute } from '#cloud/server/sharing/http'
import type { DocumentSharingService } from '#cloud/server/sharing/service'
@@ -44,12 +44,12 @@ export function createDocumentSharingRoutes(
if (rateLimit) {
router.use(
'/documents/:documentId/invitations',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.invitationMutation,
- (context) => context.req.method !== 'POST',
- routeParamResource('documentId')
+ routeParamResource('documentId'),
+ (context) => context.req.method !== 'POST'
)
)
}
diff --git a/packages/cloud/src/server/workspaces/routes.ts b/packages/cloud/src/server/workspaces/routes.ts
index 415227c8d..fdf209bbb 100644
--- a/packages/cloud/src/server/workspaces/routes.ts
+++ b/packages/cloud/src/server/workspaces/routes.ts
@@ -9,7 +9,8 @@ import type { CloudDatabase } from '#cloud/server/db'
import {
CLOUD_RATE_LIMITS,
createRouteRateLimiter,
- routeParamResource
+ routeParamResource,
+ createResourceRateLimiter
} from '#cloud/server/rate-limit'
import {
validatedJSON,
@@ -80,22 +81,22 @@ export function createWorkspaceRoutes(
// Resending mails the invitation again, so it counts against the same budget as sending.
router.use(
'/:workspaceId/invitations/:invitationId/resend',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.invitationMutation,
- () => false,
- routeParamResource('workspaceId')
+ routeParamResource('workspaceId'),
+ () => false
)
)
router.use(
'/:workspaceId/invitations',
- createRouteRateLimiter(
+ createResourceRateLimiter(
rateLimit.database,
rateLimit.secret,
CLOUD_RATE_LIMITS.invitationMutation,
- (context) => context.req.method !== 'POST',
- routeParamResource('workspaceId')
+ routeParamResource('workspaceId'),
+ (context) => context.req.method !== 'POST'
)
)
}
diff --git a/packages/cloud/tests/integration/server/rate-limit/budgets.test.ts b/packages/cloud/tests/integration/server/rate-limit/budgets.test.ts
index 5796908d1..17a354087 100644
--- a/packages/cloud/tests/integration/server/rate-limit/budgets.test.ts
+++ b/packages/cloud/tests/integration/server/rate-limit/budgets.test.ts
@@ -4,8 +4,10 @@ import { createCloudTestDatabase } from '#cloud-tests/helpers/database'
import type { CloudAPIEnvironment } from '#cloud/server/api'
import {
createActorRateLimiter,
+ createResourceRateLimiter,
createRouteRateLimiter,
- routeHasOwnBudget
+ routeHasOwnBudget,
+ routeParamResource
} from '#cloud/server/rate-limit'
import { Hono } from 'hono'
@@ -54,4 +56,47 @@ describe('rate limit budgets', () => {
await runtime.close()
}
})
+
+ test('caps an actor across resources, not only per resource', async () => {
+ const runtime = await createCloudTestDatabase()
+ try {
+ const app = new Hono<CloudAPIEnvironment>()
+ .use('/*', async (context, next) => {
+ context.set('actor', { userId: 'ada', email: '[email protected]', name: 'Ada' })
+ await next()
+ })
+ .use(
+ '/*',
+ createActorRateLimiter(runtime.database, SECRET, policy('general', 1), (context) =>
+ routeHasOwnBudget(context)
+ )
+ )
+ .use(
+ '/documents/:documentId/uploads',
+ createResourceRateLimiter(
+ runtime.database,
+ SECRET,
+ { ...policy('uploads', 2), actorLimit: 3 },
+ routeParamResource('documentId')
+ )
+ )
+ .post('/documents/:documentId/uploads', (context) => context.text('created'))
+ const upload = async (document: string) => {
+ const response = await app.request(`/documents/${document}/uploads`, { method: 'POST' })
+ const budget = response.headers.get('RateLimit')?.match(/limit=(\d+), remaining=(\d+)/)
+ return { status: response.status, limit: budget?.[1], remaining: budget?.[2] }
+ }
+
+ // The headers report whichever budget has fewer requests left.
+ expect(await upload('a')).toEqual({ status: 200, limit: '2', remaining: '1' })
+ expect(await upload('a')).toEqual({ status: 200, limit: '2', remaining: '0' })
+ // The document's own budget is spent; a refused request does not count against the actor.
+ expect((await upload('a')).status).toBe(429)
+ expect(await upload('b')).toEqual({ status: 200, limit: '3', remaining: '0' })
+ // Three uploads in all: another document does not reopen the actor's budget.
+ expect((await upload('c')).status).toBe(429)
+ } finally {
+ await runtime.close()
+ }
+ })
})
diff --git a/packages/cloud/tests/integration/server/workspaces/routes.test.ts b/packages/cloud/tests/integration/server/workspaces/routes.test.ts
index 599bb1e64..f317b55e8 100644
--- a/packages/cloud/tests/integration/server/workspaces/routes.test.ts
+++ b/packages/cloud/tests/integration/server/workspaces/routes.test.ts
@@ -201,7 +201,7 @@ describe('Cloud workspace routes', () => {
}
})
- test("counts a workspace's invitations and resends on one budget", async () => {
+ test("counts a workspace's invitations and resends on one budget, and caps the actor across workspaces", async () => {
const { app, runtime } = await testApp(alice)
try {
const createWorkspace = async (slug: string) => {
@@ -217,6 +217,7 @@ describe('Cloud workspace routes', () => {
}
const first = await createWorkspace('first-team')
const second = await createWorkspace('second-team')
+ const third = await createWorkspace('third-team')
// Bodies the routes refuse still count: the budget is spent before the route answers.
const invite = async (workspaceId: string) =>
(
@@ -243,6 +244,13 @@ describe('Cloud workspace routes', () => {
expect(await resend(first)).toBe(429)
expect(await invite(first)).toBe(429)
expect(await invite(second)).not.toBe(429)
+
+ // Spread over workspaces, each under its own budget, requests still meet the actor's.
+ const { actorLimit } = CLOUD_RATE_LIMITS.invitationMutation
+ for (let sent = limit + 1; sent < actorLimit; sent++) {
+ expect(await invite(second)).not.toBe(429)
+ }
+ expect(await invite(third)).toBe(429)
} finally {
await runtime.close()
}