tapimo 0.14.0 → 0.15.0

package/src/apps/management/routes/invitations.test.ts

@@ -1,10 +1,13 @@
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 
-import * as App from '../App.js'
 import * as TestApp from '../../../../test/App.js'
+import type * as App from '../../../App.js'
 import * as Invitations from '../../../db/tables/invitations.js'
 import * as InvitationsApp from './invitations.js'
 import * as Memberships from '../../../db/tables/memberships.js'
+import * as Metrics from '../../../Metrics.js'
+import * as RateLimit from '../../../internal/RateLimit.js'
+import * as Store from '../../../internal/Store.js'
 import * as Orgs from './orgs.js'
 import * as Organizations from '../../../db/tables/organizations.js'
 import * as Users from '../../../db/tables/users.js'
@@ -50,6 +53,8 @@ function createApp(
     db?: ReturnType<typeof TestApp.database>
     email?: App.Email
     kv?: { store: ReturnType<typeof TestApp.kvStore> }
+    metrics?: TestApp.create.Options['metrics']
+    rateLimit?: TestApp.create.Options['rateLimit']
   } = {},
 ) {
   return TestApp.create({
@@ -57,6 +62,8 @@ function createApp(
     db: options.db ?? TestApp.database(),
     ...(options.email ? { email: options.email } : {}),
     ...(options.kv ? { kv: options.kv } : {}),
+    ...(options.metrics ? { metrics: options.metrics } : {}),
+    ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
     session: { wallet: { origin } },
   })
 }
@@ -105,6 +112,7 @@ test('publishes generator-ready OpenAPI contracts', async () => {
         400: collection.post.responses[400].content['application/json'].schema,
         403: collection.post.responses[403].content['application/json'].schema,
         404: collection.post.responses[404].content['application/json'].schema,
+        429: collection.post.responses[429].content['application/json'].schema,
       },
       operationId: collection.post.operationId,
       request: collection.post.requestBody.content['application/json'].schema,
@@ -184,6 +192,9 @@ test('publishes generator-ready OpenAPI contracts', async () => {
           "404": {
             "$ref": "#/components/schemas/OrganizationNotFoundError",
           },
+          "429": {
+            "$ref": "#/components/schemas/RateLimitExceededError",
+          },
         },
         "operationId": "createInvitation",
         "request": {
@@ -286,6 +297,40 @@ test('publishes generator-ready OpenAPI contracts', async () => {
   `)
 })
 
+describe('recordEmailRateLimitDegradation', () => {
+  test('records only the bounded quota scope', () => {
+    const degraded: string[] = []
+    const metrics = Metrics.from({
+      count(name, _value, tags) {
+        if (name === 'invitation_email_rate_limit_degraded_count')
+          degraded.push(String(tags?.['scope']))
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+
+    InvitationsApp.recordEmailRateLimitDegradation({
+      metrics,
+      scope: 'invitation-email-actor',
+    })
+    InvitationsApp.recordEmailRateLimitDegradation({
+      metrics,
+      scope: 'invitation-email-recipient',
+    })
+    InvitationsApp.recordEmailRateLimitDegradation({
+      metrics,
+      scope: 'invitation-email-global',
+    })
+
+    expect(degraded).toEqual([
+      'invitation-email-actor',
+      'invitation-email-recipient',
+      'invitation-email-global',
+    ])
+  })
+})
+
 describe('invitations', () => {
   test('lets management keys manage organization invitations', async () => {
     const db = TestApp.database()
@@ -506,6 +551,116 @@ describe('invitations', () => {
     expect(pending.data[0]!.role).toBe('admin')
   })
 
+  test('rate limits invitation emails by actor', async () => {
+    const { email, sent } = sender()
+    const app = createApp({
+      email,
+      rateLimit: { now: () => new Date('2026-01-01T00:00:00.000Z') },
+    })
+    const owner = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', owner.cookie, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+    const path = `/v1/orgs/${org.id}/invitations`
+
+    for (let index = 0; index < 10; index++) {
+      const response = await app.request(
+        path,
+        json('POST', owner.cookie, { email: `dev${index}@example.com`, role: 'member' }),
+      )
+      expect(response.status).toBe(200)
+    }
+    const limited = await app.request(
+      path,
+      json('POST', owner.cookie, { email: 'limited@example.com', role: 'member' }),
+    )
+
+    expect(await limited.json()).toMatchObject({
+      error: { code: 'rate_limit_exceeded', message: 'Rate limit exceeded' },
+      requestId: expect.any(String),
+    })
+    expect({
+      limit: limited.headers.get('rateLimit-limit'),
+      remaining: limited.headers.get('rateLimit-remaining'),
+      retryAfterPresent: limited.headers.has('retry-after'),
+      scope: limited.headers.get('rateLimit-scope'),
+      sent: sent.length,
+      status: limited.status,
+    }).toMatchInlineSnapshot(`
+      {
+        "limit": "10",
+        "remaining": "0",
+        "retryAfterPresent": true,
+        "scope": "invitation-email-actor",
+        "sent": 10,
+        "status": 429,
+      }
+    `)
+  })
+
+  test('rate limits invitation emails to one recipient across actors', async () => {
+    const { email, sent } = sender()
+    const app = createApp({
+      email,
+      rateLimit: { now: () => new Date('2026-01-01T00:00:00.000Z') },
+    })
+    const owners = await Promise.all([session(app), session(app), session(app)])
+    const organizations = await Promise.all(
+      owners.map(async (owner, index) => {
+        const created = await app.request(
+          '/v1/orgs',
+          json('POST', owner.cookie, { name: `Organization ${index}` }),
+        )
+        return TestApp.json(created, Orgs.schema.Organization)
+      }),
+    )
+
+    const responses = []
+    for (const [index, owner] of owners.entries())
+      responses.push(
+        await app.request(
+          `/v1/orgs/${organizations[index]!.id}/invitations`,
+          json('POST', owner.cookie, { email: 'target@example.com', role: 'member' }),
+        ),
+      )
+
+    expect({
+      scopes: responses.map((response) => response.headers.get('rateLimit-scope')),
+      sent: sent.length,
+      statuses: responses.map((response) => response.status),
+    }).toEqual({
+      scopes: [null, null, 'invitation-email-recipient'],
+      sent: 2,
+      statuses: [200, 200, 429],
+    })
+  })
+
+  test('caps invitation email dispatch globally', async () => {
+    const now = () => new Date('2026-01-01T00:00:00.000Z')
+    const store = Store.memory()
+    const limiter = RateLimit.memory({ now, store })
+    for (let index = 0; index < 100; index++)
+      await limiter.consume({
+        key: 'invitation-email:global',
+        limit: { limit: 100, period: 'minute' },
+      })
+
+    const { email, sent } = sender()
+    const app = createApp({ email, rateLimit: { now, store } })
+    const owner = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', owner.cookie, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+    const limited = await app.request(
+      `/v1/orgs/${org.id}/invitations`,
+      json('POST', owner.cookie, { email: 'dev@example.com', role: 'member' }),
+    )
+
+    expect({
+      scope: limited.headers.get('rateLimit-scope'),
+      sent: sent.length,
+      status: limited.status,
+    }).toEqual({ scope: 'invitation-email-global', sent: 0, status: 429 })
+  })
+
   test('enforces the inviter role ladder', async () => {
     const db = TestApp.database()
     const app = createApp({ db })
@@ -523,15 +678,127 @@ describe('invitations', () => {
     expect(byMember.status).toBe(403)
     const escalated = await app.request(`/v1/orgs/${org.id}/invitations`, json('POST', admin.cookie, { email: 'a@example.com', role: 'owner' })) // prettier-ignore
     expect(escalated.status).toBe(403)
-    // Admins cannot grant their own role either — only strictly below it.
     const peer = await app.request(`/v1/orgs/${org.id}/invitations`, json('POST', admin.cookie, { email: 'a@example.com', role: 'admin' })) // prettier-ignore
-    expect(peer.status).toBe(403)
+    expect(peer.status).toBe(200)
     const byAdmin = await app.request(`/v1/orgs/${org.id}/invitations`, json('POST', admin.cookie, { email: 'a@example.com', role: 'member' })) // prettier-ignore
     expect(byAdmin.status).toBe(200)
     const byOwner = await app.request(`/v1/orgs/${org.id}/invitations`, json('POST', owner.cookie, { email: 'b@example.com', role: 'owner' })) // prettier-ignore
     expect(byOwner.status).toBe(200)
   })
 
+  test('prevents admins from replacing or revoking owner invitations', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const owner = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', owner.cookie, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+    const admin = await session(app)
+    await Memberships.create(db, { orgId: org.id, role: 'admin', userId: admin.userId })
+    const path = `/v1/orgs/${org.id}/invitations`
+    const ownerInvitation = await TestApp.json(
+      await app.request(
+        path,
+        json('POST', owner.cookie, { email: 'owner@example.com', role: 'owner' }),
+      ),
+      InvitationsApp.schema.Invitation,
+    )
+
+    const replaced = await app.request(
+      path,
+      json('POST', admin.cookie, { email: ownerInvitation.email, role: 'member' }),
+    )
+    const revoked = await app.request(`${path}/${ownerInvitation.id}`, {
+      headers: { cookie: admin.cookie },
+      method: 'DELETE',
+    })
+    const pending = await TestApp.json(
+      await app.request(path, { headers: { cookie: owner.cookie } }),
+      InvitationsApp.schema.listInvitations.Response,
+    )
+
+    expect([replaced.status, revoked.status]).toEqual([403, 403])
+    expect(pending.data).toEqual([ownerInvitation])
+
+    // Once settled, the same row is no longer disclosed as a protected owner grant.
+    expect(
+      (
+        await app.request(`${path}/${ownerInvitation.id}`, {
+          headers: { cookie: owner.cookie },
+          method: 'DELETE',
+        })
+      ).status,
+    ).toBe(200)
+    expect(
+      (
+        await app.request(`${path}/${ownerInvitation.id}`, {
+          headers: { cookie: admin.cookie },
+          method: 'DELETE',
+        })
+      ).status,
+    ).toBe(404)
+
+    // An expired owner grant must not reserve its email against an admin replacement.
+    const expired = await Invitations.create(db, {
+      email: 'expired-owner@example.com',
+      expiresAt: '2020-01-01T00:00:00.000Z',
+      invitedBy: owner.userId,
+      orgId: org.id,
+      role: 'owner',
+    })
+    const refreshed = await app.request(
+      path,
+      json('POST', admin.cookie, { email: expired.email, role: 'member' }),
+    )
+    expect(refreshed.status).toBe(200)
+    expect((await TestApp.json(refreshed, InvitationsApp.schema.Invitation)).id).toBe(expired.id)
+  })
+
+  test('revalidates session authority inside invitation mutations', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const owner = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', owner.cookie, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+    const admin = await session(app)
+    await Memberships.create(db, { orgId: org.id, role: 'admin', userId: admin.userId })
+    await Promise.all(
+      ['first', 'second'].map((email) =>
+        Invitations.create(db, {
+          email: `${email}@example.com`,
+          expiresAt: '2099-01-01T00:00:00.000Z',
+          invitedBy: owner.userId,
+          orgId: org.id,
+          role: 'member',
+        }),
+      ),
+    )
+    const invitation = await Invitations.create(db, {
+      email: 'pending@example.com',
+      expiresAt: '2099-01-01T00:00:00.000Z',
+      invitedBy: owner.userId,
+      orgId: org.id,
+      role: 'member',
+    })
+    await Memberships.update(db, org.id, admin.userId, { role: 'member' })
+
+    await expect(
+      Invitations.create(db, {
+        callerUserId: admin.userId,
+        email: 'new@example.com',
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        invitedBy: admin.userId,
+        orgId: org.id,
+        role: 'member',
+      }),
+    ).rejects.toBeInstanceOf(Invitations.InvitationRoleForbiddenError)
+    await expect(
+      Invitations.revoke(db, invitation.id, {
+        callerUserId: admin.userId,
+        orgId: org.id,
+      }),
+    ).rejects.toBeInstanceOf(Invitations.InvitationRoleForbiddenError)
+  })
+
   test('revoked and expired invitations cannot be accepted', async () => {
     const db = TestApp.database()
     const app = createApp({ db })

package/src/apps/management/routes/invitations.ts

@@ -1,19 +1,26 @@
 import { type Context, Hono } from 'hono'
+import { Hash, Hex } from 'ox'
 import * as z from 'zod/mini'
 
 import * as Auth from '../../../internal/Auth.js'
 import * as Db from '../../../db/Db.js'
+import * as Email from '../../../internal/Email.js'
 import * as Invitations from '../../../db/tables/invitations.js'
 import * as Memberships from '../../../db/tables/memberships.js'
+import type * as Metrics from '../../../Metrics.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
+import * as RateLimit from '../../../internal/RateLimit.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as ManagementError from '../Error.js'
 
-import type { Email, Environment } from '../App.js'
+import type { Environment } from '../App.js'
 
 /** How long an invitation stays acceptable. */
 const ttlDays = 7
+const actorRateLimit = { limit: 10, period: 'minute' } satisfies RateLimit.Limit
+const globalRateLimit = { limit: 100, period: 'minute' } satisfies RateLimit.Limit
+const recipientRateLimit = { limit: 2, period: 'minute' } satisfies RateLimit.Limit
 
 /** Zod schemas owned by the invitations resource. */
 export namespace schema {
@@ -269,6 +276,10 @@ export function invitations() {
               codes: ['organization_not_found'],
               description: 'No accessible organization was found for this id.',
             },
+            429: {
+              codes: ['rate_limit_exceeded'],
+              description: 'The invitation email rate limit was exceeded.',
+            },
           },
           success: { description: 'The created invitation.', schema: schema.Invitation },
         }),
@@ -291,12 +302,12 @@ export function invitations() {
           })
 
         const body = c.req.valid('json')
-        // Owners, write-scoped keys, and the super admin grant any role; admins grant only members.
+        // Owners, write-scoped keys, and the super admin grant any role; admins cannot grant owner.
         const caller = Auth.membership(c)
         if (
           caller &&
           caller.role !== 'owner' &&
-          Memberships.rank[body.role] >= Memberships.rank[caller.role]
+          Memberships.rank[body.role] > Memberships.rank[caller.role]
         )
           return Response.error(c, {
             code: 'forbidden',
@@ -307,18 +318,32 @@ export function invitations() {
         const invitedBy =
           principal?.type === 'api_key' ? principal.id : (caller?.userId ?? 'super_admin')
 
+        const invitationEmail = Email.get(c)
+        const limited = await consumeEmailRateLimit({
+          actor: principal ? `${principal.type}:${principal.id}` : undefined,
+          email: body.email,
+          enabled: !!invitationEmail,
+          metrics: c.get('metrics'),
+          rateLimit: c.get('auth').rateLimit,
+        })
+        if (limited) return rateLimitError(c, limited)
+
         const db = Db.get(c.get('db'))
         try {
-          const record = await Invitations.create(db, {
+          const record = await createInvitation({
+            ...(caller ? { callerUserId: caller.userId } : {}),
+            db,
             email: body.email,
-            expiresAt: new Date(Date.now() + ttlDays * 86_400_000).toISOString(),
+            invitationEmail,
             invitedBy,
-            orgId: Auth.org(c).id,
+            org: Auth.org(c),
             role: body.role,
+            waitUntil: (promise) => c.executionCtx.waitUntil(promise),
           })
-          dispatchEmail(c, { email: c.get('email'), org: Auth.org(c).name, record })
           return c.json(Response.validated(schema.Invitation, serializeInvitation(record)), 200)
         } catch (cause) {
+          if (cause instanceof Invitations.InvitationRoleForbiddenError)
+            return invitationRoleForbidden(c)
           return Response.upstream(c, cause)
         }
       },
@@ -412,16 +437,19 @@ export function invitations() {
         const { invitationId } = c.req.valid('param')
         const db = Db.get(c.get('db'))
         try {
-          // Bind the invitation to the scoped org before revoking.
-          const record = await Invitations.get(db, invitationId)
-          if (!record || record.orgId !== Auth.org(c).id) return invitationNotFound(c)
-          const revoked = await Invitations.revoke(db, invitationId)
+          const caller = Auth.membership(c)
+          const revoked = await Invitations.revoke(db, invitationId, {
+            ...(caller ? { callerUserId: caller.userId } : {}),
+            orgId: Auth.org(c).id,
+          })
           if (!revoked) return invitationNotFound(c)
           return c.json(
             Response.validated(schema.revokeInvitation.Response, { id: invitationId }),
             200,
           )
         } catch (cause) {
+          if (cause instanceof Invitations.InvitationRoleForbiddenError)
+            return invitationRoleForbidden(c)
           return Response.upstream(c, cause)
         }
       },
@@ -594,11 +622,153 @@ export function invitations() {
     )
 }
 
-/** Dispatches the invitation email through the app's sender, best-effort. */
-function dispatchEmail(
+/** Consumes the shared quotas protecting invitation email dispatch. */
+export async function consumeEmailRateLimit(options: consumeEmailRateLimit.Options) {
+  if (!options.enabled) return undefined
+  if (!options.rateLimit) return undefined
+  const auth = { rateLimit: options.rateLimit }
+
+  if (options.actor) {
+    const actor = await Auth.consumeRateLimit(auth, {
+      key: `invitation-email:actor:${options.actor}`,
+      limit: actorRateLimit,
+    })
+    if (!actor)
+      recordEmailRateLimitDegradation({ metrics: options.metrics, scope: 'invitation-email-actor' })
+    if (actor && !actor.allowed) return { result: actor, scope: 'invitation-email-actor' }
+  }
+
+  const recipientHash = Hash.sha256(Hex.fromString(options.email.toLowerCase())).slice(2)
+  const recipient = await Auth.consumeRateLimit(auth, {
+    key: `invitation-email:recipient:${recipientHash}`,
+    limit: recipientRateLimit,
+  })
+  if (!recipient)
+    recordEmailRateLimitDegradation({
+      metrics: options.metrics,
+      scope: 'invitation-email-recipient',
+    })
+  if (recipient && !recipient.allowed)
+    return { result: recipient, scope: 'invitation-email-recipient' }
+
+  const global = await Auth.consumeRateLimit(auth, {
+    key: 'invitation-email:global',
+    limit: globalRateLimit,
+  })
+  if (!global)
+    recordEmailRateLimitDegradation({ metrics: options.metrics, scope: 'invitation-email-global' })
+  if (global && !global.allowed) return { result: global, scope: 'invitation-email-global' }
+  return undefined
+}
+
+export declare namespace consumeEmailRateLimit {
+  /** Fields used to protect one invitation email dispatch. */
+  type Options = {
+    /** Stable identity for the initiating actor, when the caller has one. */
+    actor?: string | undefined
+    /** Intended invitation recipient. */
+    email: string
+    /** Whether this app has an email sender configured. */
+    enabled: boolean
+    /** Bounded operational metrics sink for fail-open degradation. */
+    metrics?: Metrics.Metrics | undefined
+    /** Shared counter store used by every invitation email entrypoint. */
+    rateLimit?: RateLimit.Store | undefined
+  }
+}
+
+/** Records bounded invitation limiter degradation for operational alerting. */
+export function recordEmailRateLimitDegradation(options: recordEmailRateLimitDegradation.Options) {
+  options.metrics?.count('invitation_email_rate_limit_degraded_count', 1, {
+    scope: options.scope,
+  })
+}
+
+export declare namespace recordEmailRateLimitDegradation {
+  /** Inputs for recording one invitation limiter degradation. */
+  type Options = {
+    /** Bounded operational metrics sink. */
+    metrics?: Metrics.Metrics | undefined
+    /** Quota dimension whose counter degraded. */
+    scope: 'invitation-email-actor' | 'invitation-email-global' | 'invitation-email-recipient'
+  }
+}
+
+function rateLimitError(
   c: Context<Environment>,
-  options: { email: Email | undefined; org: string; record: Invitations.Record },
+  limited: {
+    /** Denied quota result. */
+    result: RateLimit.Result
+    /** Quota dimension that denied the request. */
+    scope: string
+  },
 ) {
+  const { result, scope } = limited
+  c.header('RateLimit-Limit', String(result.limit))
+  c.header('RateLimit-Remaining', String(result.remaining))
+  c.header('RateLimit-Reset', String(result.reset))
+  c.header('RateLimit-Scope', scope)
+  c.header('Retry-After', String(Math.max(result.reset - Math.ceil(Date.now() / 1_000), 1)))
+  return Response.error(c, {
+    code: 'rate_limit_exceeded',
+    message: 'Rate limit exceeded',
+    status: 429,
+  })
+}
+
+/** Creates an organization invitation and dispatches its email. */
+export async function createInvitation(options: createInvitation.Options) {
+  const record = await Invitations.create(options.db, {
+    ...(options.callerUserId === undefined ? {} : { callerUserId: options.callerUserId }),
+    email: options.email,
+    expiresAt: options.expiresAt ?? new Date(Date.now() + ttlDays * 86_400_000).toISOString(),
+    invitedBy: options.invitedBy,
+    orgId: options.org.id,
+    role: options.role,
+  })
+  dispatchEmail({ email: options.invitationEmail, org: options.org.name, record, waitUntil: options.waitUntil }) // prettier-ignore
+  return record
+}
+
+export declare namespace createInvitation {
+  /** Fields required to create and deliver an invitation. */
+  type Options = {
+    /** Session user whose current organization role authorizes this write. */
+    callerUserId?: string | undefined
+    /** Database receiving the pending invitation. */
+    db: Db.Db
+    /** Invitee email. */
+    email: string
+    /** Invitation expiry timestamp. */
+    expiresAt?: string | undefined
+    /** Transactional email sender, when configured. */
+    invitationEmail?: Email.Sender | undefined
+    /** Identity attributed with creating the invitation. */
+    invitedBy: string
+    /** Organization receiving the invited member. */
+    org: { id: string; name: string }
+    /** Role granted after acceptance. */
+    role: Memberships.Role
+    /** Keeps email delivery alive after the response. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+  }
+}
+
+function invitationRoleForbidden(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'forbidden',
+    message: 'Cannot manage an invitation above your own role',
+    status: 403,
+  })
+}
+
+/** Dispatches the invitation email through the app's sender, best-effort. */
+function dispatchEmail(options: {
+  email: Email.Sender | undefined
+  org: string
+  record: Invitations.Record
+  waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+}) {
   const { email: sender, org, record } = options
   if (!sender) return
   const days = Math.max(1, Math.round((Date.parse(record.expiresAt) - Date.now()) / 86_400_000))
@@ -618,7 +788,7 @@ function dispatchEmail(
     }),
   ).catch((error) => console.error('invitation email dispatch failed', error))
   try {
-    c.executionCtx.waitUntil(dispatch)
+    options.waitUntil?.(dispatch)
   } catch {
     // Non-Workers runtime: the floating promise settles on its own.
   }