@kelpie/server 0.10.0 → 0.12.0

package/migrations/meta/_journal.json

@@ -260,6 +260,55 @@
       "when": 1788146891073,
       "tag": "0036_form_field_notice_type",
       "breakpoints": true
+    },
+    {
+      "idx": 37,
+      "version": "7",
+      "when": 1788150000000,
+      "tag": "0037_drop_lists_consent_purpose_id",
+      "breakpoints": true
+    },
+    {
+      "idx": 38,
+      "version": "7",
+      "when": 1788214656489,
+      "tag": "0038_smart_white_queen",
+      "breakpoints": true
+    },
+    {
+      "idx": 39,
+      "version": "7",
+      "when": 1788300000000,
+      "tag": "0039_form_map_to_open",
+      "breakpoints": true
+    },
+    {
+      "idx": 40,
+      "version": "7",
+      "when": 1788400000000,
+      "tag": "0040_pipeline_converted_to",
+      "breakpoints": true
+    },
+    {
+      "idx": 41,
+      "version": "7",
+      "when": 1788500000000,
+      "tag": "0041_api_key_scopes",
+      "breakpoints": true
+    },
+    {
+      "idx": 42,
+      "version": "7",
+      "when": 1788600000000,
+      "tag": "0042_drop_workspace_identity",
+      "breakpoints": true
+    },
+    {
+      "idx": 43,
+      "version": "7",
+      "when": 1788700000000,
+      "tag": "0043_external_sign_in",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelpie/server",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The Kelpie service as a library: module runtime, core CRM modules, REST API, MCP surface, and the shared migration pipeline.",
   "keywords": [
     "kelpie",
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.12",
-    "@kelpie/schemas": "^0.10.0",
+    "@kelpie/schemas": "^0.12.0",
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "emittery": "^2.0.0",

package/src/app.ts

@@ -14,6 +14,7 @@ import { securityHeadersMiddleware } from './lib/securityHeaders.ts'
 import type { CredentialDependencies } from './modules/auth/credentials.ts'
 import { MCP_INSTRUCTIONS, MCP_ROUTE_PREFIX, MCP_SERVER_INFO } from './modules/mcp/index.ts'
 import { createMcpEndpoint } from './modules/mcp/router.ts'
+import { createApiKeyScopeMiddleware } from './modules/api-keys/scopeMiddleware.ts'
 import {
   createAuthAndApiRateLimitMiddleware,
   createFormSubmitRateLimitMiddleware,
@@ -145,6 +146,8 @@ export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
 
   app.use('/v1/*', workspaceAccessMiddleware)
 
+  app.use('/v1/*', createApiKeyScopeMiddleware(dependencies.credentials))
+
   // Every module's `POST` gets this the same way, decided once here rather than
   // per route (`api.md`). It skips `/v1/public/*` itself — a public request has
   // no `Actor` to scope a key to — so it is mounted ahead of the public CORS

package/src/index.ts

@@ -64,13 +64,21 @@ export type { SecretCipher, SecretEncryptionConfig } from './lib/secrets.ts'
 
 export {
   AppError,
+  ExternalSignInError,
   describeThrown,
   describeValidationIssue,
   internalErrorBody,
   toErrorBody,
   toErrorDetails,
 } from './lib/errors.ts'
-export type { ErrorBody, ErrorCode, ErrorDetail, ErrorStatus, ValidationIssue } from './lib/errors.ts'
+export type {
+  ErrorBody,
+  ErrorCode,
+  ErrorDetail,
+  ErrorStatus,
+  ExternalSignInRefusal,
+  ValidationIssue,
+} from './lib/errors.ts'
 
 export { createIdFactory, idPrefixes } from './lib/ids.ts'
 export type { IdFactory, ObjectKind } from './lib/ids.ts'
@@ -84,6 +92,9 @@ export {
 export type { CreateLoggerOptions, LogFields, Logger, LoggingDestination } from './lib/logger.ts'
 
 export type {
+  CompletedSignIn,
+  CompletedSignInAccount,
+  ExternalSignInHandler,
   KelpieModule,
   McpTool,
   McpToolDefinition,
@@ -91,6 +102,7 @@ export type {
   ModuleCatalogEntry,
   ModuleContext,
   SchemaContribution,
+  VerifiedIdentity,
 } from './runtime/module.ts'
 
 export { ModuleBootError, orderModules } from './runtime/order.ts'

package/src/lib/actor.ts

@@ -1,4 +1,4 @@
-import type { EventActor, MemberRole } from '@kelpie/schemas'
+import type { ApiKeyScope, EventActor, MemberRole } from '@kelpie/schemas'
 
 import { AppError } from './errors.ts'
 
@@ -39,6 +39,8 @@ export interface ApiKeyActor {
   readonly userId: string | null
   readonly workspaceId: string
   readonly role: MemberRole
+  /** Empty means full access. Presets and granular tokens may be mixed. */
+  readonly scopes: readonly ApiKeyScope[]
   /** Null for a workspace key: it belongs to the workspace, not to a member. */
   readonly memberId: string | null
 }

package/src/lib/apiKeyScopes.ts

@@ -0,0 +1,213 @@
+import type { ApiKeyGranularScope, ApiKeyScope } from '@kelpie/schemas'
+import { satisfiesApiKeyScope } from '@kelpie/schemas'
+
+import type { Actor } from './actor.ts'
+import { AppError } from './errors.ts'
+
+/**
+ * REST and MCP scope enforcement for API keys.
+ *
+ * Sessions are never scoped. An empty scope list on a key means full access.
+ */
+
+interface RouteScopeRule {
+  readonly methods: readonly string[]
+  readonly pattern: RegExp
+  readonly scope: ApiKeyGranularScope
+}
+
+/** Paths that need no scope check (session-only or unauthenticated). */
+function isExempt(method: string, path: string): boolean {
+  if (path.startsWith('/v1/public/')) {
+    return true
+  }
+
+  if (path.startsWith('/v1/auth/')) {
+    return true
+  }
+
+  if (path.startsWith('/v1/account')) {
+    return true
+  }
+
+  if (method === 'POST' && path === '/v1/workspaces') {
+    return true
+  }
+
+  return method === 'POST' && path === '/v1/invites/accept'
+}
+
+const ROUTE_SCOPE_RULES: readonly RouteScopeRule[] = [
+  { methods: ['GET'], pattern: /^\/v1\/people(?:\/[^/]+)?$/u, scope: 'people:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/people(?:\/[^/]+)?$/u, scope: 'people:write' },
+  { methods: ['GET'], pattern: /^\/v1\/companies(?:\/[^/]+)?$/u, scope: 'companies:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/companies(?:\/[^/]+)?$/u, scope: 'companies:write' },
+  { methods: ['GET'], pattern: /^\/v1\/positions(?:\/[^/]+)?$/u, scope: 'positions:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/positions(?:\/[^/]+)?$/u, scope: 'positions:write' },
+  { methods: ['GET'], pattern: /^\/v1\/deals(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'deals:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/deals(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'deals:write' },
+  { methods: ['GET'], pattern: /^\/v1\/enquiries(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'enquiries:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/enquiries(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'enquiries:write' },
+  { methods: ['GET'], pattern: /^\/v1\/opportunities(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'opportunities:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/opportunities(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'opportunities:write' },
+  { methods: ['GET'], pattern: /^\/v1\/partnerships(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'partnerships:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/partnerships(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'partnerships:write' },
+  { methods: ['GET'], pattern: /^\/v1\/raises(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'raises:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/raises(?:\/[^/]+(?:\/convert)?)?$/u, scope: 'raises:write' },
+  { methods: ['GET'], pattern: /^\/v1\/roles(?:\/[^/]+)?$/u, scope: 'roles:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/roles(?:\/[^/]+)?$/u, scope: 'roles:write' },
+  { methods: ['GET'], pattern: /^\/v1\/candidates(?:\/[^/]+)?$/u, scope: 'candidates:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/candidates(?:\/[^/]+)?$/u, scope: 'candidates:write' },
+  { methods: ['GET'], pattern: /^\/v1\/decisions(?:\/[^/]+)?$/u, scope: 'decisions:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/decisions(?:\/[^/]+)?$/u, scope: 'decisions:write' },
+  { methods: ['GET'], pattern: /^\/v1\/plan_items(?:\/[^/]+)?$/u, scope: 'plan_items:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/plan_items(?:\/[^/]+)?$/u, scope: 'plan_items:write' },
+  { methods: ['GET'], pattern: /^\/v1\/notes(?:\/[^/]+)?$/u, scope: 'notes:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/notes(?:\/[^/]+)?$/u, scope: 'notes:write' },
+  { methods: ['GET'], pattern: /^\/v1\/(?:lists(?:\/[^/]+(?:\/members(?:\/[^/]+)?)?)?|list-memberships)$/u, scope: 'lists:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/(?:lists(?:\/[^/]+(?:\/members(?:\/[^/]+)?)?)?|list-memberships)$/u, scope: 'lists:write' },
+  { methods: ['GET'], pattern: /^\/v1\/handbook_pages(?:\/[^/]+)?$/u, scope: 'handbook:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/handbook_pages(?:\/[^/]+)?$/u, scope: 'handbook:write' },
+  { methods: ['GET'], pattern: /^\/v1\/(?:forms(?:\/[^/]+(?:\/(?:submissions(?:\/[^/]+)?|embed))?)?|form-submissions)$/u, scope: 'forms:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/forms(?:\/[^/]+)?$/u, scope: 'forms:write' },
+  { methods: ['GET'], pattern: /^\/v1\/activities$/u, scope: 'activities:read' },
+  { methods: ['GET'], pattern: /^\/v1\/search$/u, scope: 'search:read' },
+  { methods: ['GET'], pattern: /^\/v1\/dashboard$/u, scope: 'dashboard:read' },
+  { methods: ['GET'], pattern: /^\/v1\/custom_fields(?:\/[^/]+)?$/u, scope: 'custom_fields:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/custom_fields(?:\/[^/]+)?$/u, scope: 'custom_fields:write' },
+  { methods: ['GET'], pattern: /^\/v1\/pipeline_stages(?:\/[^/]+)?$/u, scope: 'pipeline_stages:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/pipeline_stages(?:\/[^/]+)?$/u, scope: 'pipeline_stages:write' },
+  { methods: ['GET'], pattern: /^\/v1\/consent_purposes(?:\/[^/]+)?$/u, scope: 'consent_purposes:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/consent_purposes(?:\/[^/]+)?$/u, scope: 'consent_purposes:write' },
+  { methods: ['GET'], pattern: /^\/v1\/export(?:\/|$)/u, scope: 'import_export:read' },
+  { methods: ['GET'], pattern: /^\/v1\/import\/jobs(?:\/[^/]+)?$/u, scope: 'import_export:read' },
+  { methods: ['POST', 'DELETE'], pattern: /^\/v1\/import\/jobs(?:\/[^/]+(?:\/commit)?)?$/u, scope: 'import_export:write' },
+  { methods: ['GET'], pattern: /^\/v1\/webhooks(?:\/[^/]+(?:\/deliveries)?)?$/u, scope: 'webhooks:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/webhooks(?:\/[^/]+(?:\/rotate_secret)?)?$/u, scope: 'webhooks:write' },
+  { methods: ['GET'], pattern: /^\/v1\/api-keys(?:\/[^/]+)?$/u, scope: 'api_keys:read' },
+  { methods: ['POST', 'DELETE'], pattern: /^\/v1\/api-keys(?:\/[^/]+)?$/u, scope: 'api_keys:write' },
+  { methods: ['GET'], pattern: /^\/v1\/agent-tasks(?:\/[^/]+(?:\/(?:resolve|run))?)?$/u, scope: 'agent_tasks:read' },
+  { methods: ['POST'], pattern: /^\/v1\/agent-tasks\/[^/]+(?:\/(?:resolve|run))?$/u, scope: 'agent_tasks:write' },
+  { methods: ['GET'], pattern: /^\/v1\/agent-runs(?:\/[^/]+)?$/u, scope: 'agent_runs:read' },
+  { methods: ['GET'], pattern: /^\/v1\/agents(?:\/[^/]+)?$/u, scope: 'agents:read' },
+  { methods: ['POST', 'PATCH', 'DELETE'], pattern: /^\/v1\/agents(?:\/[^/]+)?$/u, scope: 'agents:write' },
+  { methods: ['GET'], pattern: /^\/v1\/workspaces\/[^/]+$/u, scope: 'workspace:read' },
+  { methods: ['PATCH'], pattern: /^\/v1\/workspaces\/[^/]+$/u, scope: 'workspace:write' },
+  { methods: ['GET'], pattern: /^\/v1\/workspaces\/[^/]+\/members(?:\/[^/]+)?$/u, scope: 'workspace:read' },
+  { methods: ['PATCH', 'DELETE'], pattern: /^\/v1\/workspaces\/[^/]+\/members(?:\/[^/]+)?$/u, scope: 'workspace:write' },
+  { methods: ['GET'], pattern: /^\/v1\/workspaces\/[^/]+\/invites(?:\/[^/]+(?:\/resend)?)?$/u, scope: 'workspace:read' },
+  { methods: ['POST', 'DELETE'], pattern: /^\/v1\/workspaces\/[^/]+\/invites(?:\/[^/]+(?:\/resend)?)?$/u, scope: 'workspace:write' },
+  { methods: ['GET'], pattern: /^\/v1\/workspaces\/[^/]+\/modules(?:\/[^/]+)?$/u, scope: 'modules:read' },
+  { methods: ['PATCH'], pattern: /^\/v1\/workspaces\/[^/]+\/modules(?:\/[^/]+)?$/u, scope: 'modules:write' },
+  { methods: ['POST'], pattern: /^\/v1\/workspaces\/[^/]+\/sample-data$/u, scope: 'sample_data:write' },
+  { methods: ['POST'], pattern: /^\/v1\/workspaces\/[^/]+\/relink-email-domains$/u, scope: 'workspace:write' },
+  { methods: ['GET'], pattern: /^\/v1\/mcp\/tools$/u, scope: 'search:read' },
+]
+
+function storedScopes(actor: Actor): readonly ApiKeyScope[] {
+  if (actor.kind !== 'api_key') {
+    return []
+  }
+
+  return actor.scopes
+}
+
+export function hasApiKeyScope(actor: Actor, required: ApiKeyGranularScope): boolean {
+  if (actor.kind !== 'api_key') {
+    return true
+  }
+
+  return satisfiesApiKeyScope(actor.scopes, required)
+}
+
+export function requireApiKeyScope(actor: Actor, required: ApiKeyGranularScope): void {
+  if (hasApiKeyScope(actor, required)) {
+    return
+  }
+
+  throw new AppError('forbidden', `This API key does not have the ${required} scope`)
+}
+
+export function resolveRestScope(method: string, path: string): ApiKeyGranularScope | null {
+  if (isExempt(method, path)) {
+    return null
+  }
+
+  if (method === 'DELETE' && /^\/v1\/workspaces\/[^/]+$/u.test(path)) {
+    return 'workspace:write'
+  }
+
+  for (const rule of ROUTE_SCOPE_RULES) {
+    if (rule.methods.includes(method) && rule.pattern.test(path)) {
+      return rule.scope
+    }
+  }
+
+  return null
+}
+
+const MCP_READ_VERBS = new Set(['list', 'get', 'query'])
+const MCP_WRITE_VERBS = new Set(['create', 'update', 'delete', 'commit', 'resolve', 'run', 'rotate_secret', 'install'])
+
+/** Maps REST resource segments used in MCP tool names to scope resources. */
+const MCP_RESOURCE_ALIASES: Readonly<Record<string, string>> = {
+  handbook_pages: 'handbook',
+  plan_items: 'plan_items',
+  pipeline_stages: 'pipeline_stages',
+  custom_fields: 'custom_fields',
+  consent_purposes: 'consent_purposes',
+  form_submissions: 'forms',
+  list_memberships: 'lists',
+  agent_tasks: 'agent_tasks',
+  agent_runs: 'agent_runs',
+  import_jobs: 'import_export',
+  export: 'import_export',
+}
+
+export function resolveMcpScope(toolName: string): ApiKeyGranularScope | null {
+  if (toolName === 'search_query') {
+    return 'search:read'
+  }
+
+  const match = /^([a-z0-9_]+)_(list|get|create|update|delete|query|commit|resolve|run|rotate_secret|install)$/u.exec(
+    toolName,
+  )
+
+  if (match === null) {
+    const parts = toolName.split('_')
+    const verb = parts.at(-1)
+
+    if (verb === undefined) {
+      return null
+    }
+
+    const resource = MCP_RESOURCE_ALIASES[parts.slice(0, -1).join('_')] ?? parts.slice(0, -1).join('_')
+
+    if (MCP_READ_VERBS.has(verb)) {
+      return `${resource}:read` as ApiKeyGranularScope
+    }
+
+    if (MCP_WRITE_VERBS.has(verb)) {
+      return `${resource}:write` as ApiKeyGranularScope
+    }
+
+    return null
+  }
+
+  const [, rawResource, verb] = match
+  const resource = MCP_RESOURCE_ALIASES[rawResource ?? ''] ?? rawResource ?? ''
+
+  if (MCP_READ_VERBS.has(verb ?? '')) {
+    return `${resource}:read` as ApiKeyGranularScope
+  }
+
+  if (MCP_WRITE_VERBS.has(verb ?? '')) {
+    return `${resource}:write` as ApiKeyGranularScope
+  }
+
+  return null
+}
+
+export function actorHasStoredScopes(actor: Actor): boolean {
+  return storedScopes(actor).length > 0
+}

package/src/lib/errors.ts

@@ -83,6 +83,36 @@ export class AppError extends Error {
   }
 }
 
+/**
+ * Why core refused an identity a module handed to `completeExternalSignIn`.
+ *
+ * A reason rather than a message, so a provider module can branch on it (to
+ * redirect somewhere useful, say) without matching on English text.
+ */
+export type ExternalSignInRefusal = 'email_unverified' | 'unknown_identity'
+
+/**
+ * An external sign-in core would not complete.
+ *
+ * An `AppError`, so an uncaught one still renders as the `api.md` body. No new
+ * `ErrorCode`: refusing an unverified identity is an ordinary `401`, and
+ * refusing to provision is an ordinary `403`.
+ */
+export class ExternalSignInError extends AppError {
+  readonly reason: ExternalSignInRefusal
+
+  constructor(reason: ExternalSignInRefusal) {
+    super(
+      reason === 'email_unverified' ? 'unauthorized' : 'forbidden',
+      reason === 'email_unverified'
+        ? 'The identity provider did not verify this email address'
+        : 'No account exists for this identity',
+    )
+    this.name = 'ExternalSignInError'
+    this.reason = reason
+  }
+}
+
 /**
  * Renders an `AppError` into the wire body from `api.md`. `details` is omitted
  * rather than sent as null when the error carries none.

package/src/modules/activities/repository.ts

@@ -193,3 +193,27 @@ export async function deleteForTarget(
 
   return deleted.length
 }
+
+/** Moves every activity from one target to another inside a conversion transaction. */
+export async function repointForTarget(
+  db: Queryable,
+  workspaceId: string,
+  fromType: string,
+  fromId: string,
+  toType: string,
+  toId: string,
+): Promise<number> {
+  const updated = await db
+    .update(activities)
+    .set({ targetType: toType, targetId: toId })
+    .where(
+      and(
+        eq(activities.workspaceId, workspaceId),
+        eq(activities.targetType, fromType),
+        eq(activities.targetId, fromId),
+      ),
+    )
+    .returning({ id: activities.id })
+
+  return updated.length
+}

package/src/modules/agent-tasks/repository.ts

@@ -150,3 +150,27 @@ export async function updateRun(
 ): Promise<void> {
   await db.update(agentRuns).set(changes).where(eq(agentRuns.id, id))
 }
+
+/** Moves every agent run from one target to another inside a conversion transaction. */
+export async function repointForTarget(
+  db: Queryable,
+  workspaceId: string,
+  fromType: string,
+  fromId: string,
+  toType: string,
+  toId: string,
+): Promise<number> {
+  const updated = await db
+    .update(agentRuns)
+    .set({ targetType: toType, targetId: toId })
+    .where(
+      and(
+        eq(agentRuns.workspaceId, workspaceId),
+        eq(agentRuns.targetType, fromType),
+        eq(agentRuns.targetId, fromId),
+      ),
+    )
+    .returning({ id: agentRuns.id })
+
+  return updated.length
+}

package/src/modules/api-keys/routes.ts

@@ -1,3 +1,5 @@
+import type { ApiKeyScope } from '@kelpie/schemas'
+import { API_KEY_SCOPES } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -13,6 +15,7 @@ import type { ApiKeyService, ApiKeyView, MintedApiKey } from './service.ts'
 const createBody = z.object({
   name: z.string().min(1),
   kind: z.enum(KEY_KINDS),
+  scopes: z.array(z.enum(API_KEY_SCOPES)).optional(),
 })
 
 const listQuery = z.object({ kind: z.enum(KEY_KINDS) })
@@ -39,6 +42,7 @@ function keyResponse(key: ApiKeyView): Record<string, unknown> {
     id: key.id,
     name: key.name,
     kind: key.kind,
+    scopes: key.scopes,
     display_prefix: key.displayPrefix,
     last_used_at: key.lastUsedAt === null ? null : key.lastUsedAt.toISOString(),
     created_at: key.createdAt.toISOString(),
@@ -55,6 +59,7 @@ export function mountApiKeyRoutes(router: Hono, dependencies: ApiKeyRoutesDepend
       await requireActor(context),
       body.name,
       body.kind,
+      body.scopes as ApiKeyScope[] | undefined,
     )
 
     return context.json({ ...keyResponse(minted), secret: minted.secret }, 201)

package/src/modules/api-keys/schema.ts

@@ -20,6 +20,8 @@ export const apiKeys = pgTable(
     name: text('name').notNull(),
     secretHash: text('secret_hash').notNull().unique(),
     displayPrefix: text('display_prefix').notNull(),
+    /** Empty array means full access. Presets and granular tokens may be mixed. */
+    scopes: text('scopes').array().notNull().default([]),
     lastUsedAt: moment('last_used_at'),
     createdAt: createdAt(),
     updatedAt: updatedAt(),

package/src/modules/api-keys/scopeMiddleware.ts

@@ -0,0 +1,30 @@
+import type { MiddlewareHandler } from 'hono'
+
+import { requireApiKeyScope, resolveRestScope } from '../../lib/apiKeyScopes.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+
+/**
+ * Blocks API-key requests that lack the scope a route needs. Sessions pass
+ * through unchanged.
+ */
+export function createApiKeyScopeMiddleware(
+  dependencies: CredentialDependencies,
+): MiddlewareHandler {
+  return async (context, next) => {
+    const required = resolveRestScope(context.req.method, context.req.path)
+
+    if (required === null) {
+      await next()
+      return
+    }
+
+    const actor = await resolveActorFrom(dependencies, context)
+
+    if (actor.kind === 'api_key') {
+      requireApiKeyScope(actor, required)
+    }
+
+    await next()
+  }
+}

package/src/modules/api-keys/service.ts

@@ -1,5 +1,9 @@
+import type { ApiKeyScope } from '@kelpie/schemas'
+import { API_KEY_SCOPES, dedupeApiKeyScopes } from '@kelpie/schemas'
+
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
+import { hasApiKeyScope } from '../../lib/apiKeyScopes.ts'
 import type { IdFactory } from '../../lib/ids.ts'
 import type { Actor } from '../auth/actor.ts'
 import { roleAllows } from '../workspace/roles.ts'
@@ -27,6 +31,7 @@ export interface ApiKeyView {
   readonly id: string
   readonly name: string
   readonly kind: KeyKind
+  readonly scopes: readonly ApiKeyScope[]
   readonly displayPrefix: string
   readonly lastUsedAt: Date | null
   readonly createdAt: Date
@@ -38,7 +43,7 @@ export interface MintedApiKey extends ApiKeyView {
 }
 
 export interface ApiKeyService {
-  create(actor: Actor, name: string, kind: KeyKind): Promise<MintedApiKey>
+  create(actor: Actor, name: string, kind: KeyKind, scopes?: readonly ApiKeyScope[]): Promise<MintedApiKey>
   list(actor: Actor, kind: KeyKind): Promise<readonly ApiKeyView[]>
   revoke(actor: Actor, id: string): Promise<void>
 }
@@ -48,12 +53,31 @@ function toView(record: repository.ApiKeyRecord): ApiKeyView {
     id: record.id,
     name: record.name,
     kind: record.userId === null ? 'workspace' : 'personal',
+    scopes: record.scopes as ApiKeyScope[],
     displayPrefix: record.displayPrefix,
     lastUsedAt: record.lastUsedAt,
     createdAt: record.createdAt,
   }
 }
 
+function parseScopes(scopes: readonly ApiKeyScope[] | undefined): ApiKeyScope[] {
+  if (scopes === undefined || scopes.length === 0) {
+    return []
+  }
+
+  const deduped = dedupeApiKeyScopes(scopes)
+  const allowed = new Set<string>(API_KEY_SCOPES)
+  const invalid = deduped.filter((scope) => !allowed.has(scope))
+
+  if (invalid.length > 0) {
+    throw AppError.validationFailed('One or more scopes are not valid', [
+      { field: 'scopes', message: `Unknown scopes: ${invalid.join(', ')}` },
+    ])
+  }
+
+  return deduped
+}
+
 export function createApiKeyService(dependencies: ApiKeyDependencies): ApiKeyService {
   /**
    * Keys are always workspace-bound, so an actor with no workspace cannot have
@@ -92,14 +116,19 @@ export function createApiKeyService(dependencies: ApiKeyDependencies): ApiKeySer
   }
 
   return {
-    async create(actor, name, kind) {
+    async create(actor, name, kind, scopes) {
       const workspaceId = requireWorkspace(actor)
       const userId = kind === 'workspace' ? null : requireUser(actor)
+      const storedScopes = parseScopes(scopes)
 
       if (kind === 'workspace') {
         requireAdmin(actor)
       }
 
+      if (actor.kind === 'api_key' && !hasApiKeyScope(actor, 'api_keys:write')) {
+        throw new AppError('forbidden', 'This API key does not have the api_keys:write scope')
+      }
+
       const minted = mintKey(kind, dependencies.newToken)
       const record = await repository.insertApiKey(dependencies.db, {
         id: dependencies.createId('apiKey'),
@@ -108,6 +137,7 @@ export function createApiKeyService(dependencies: ApiKeyDependencies): ApiKeySer
         name,
         secretHash: minted.secretHash,
         displayPrefix: minted.displayPrefix,
+        scopes: storedScopes,
       })
 
       // The only time the secret leaves this process. Nothing stores it.
@@ -146,6 +176,10 @@ export function createApiKeyService(dependencies: ApiKeyDependencies): ApiKeySer
         throw AppError.notFound('API key not found')
       }
 
+      if (actor.kind === 'api_key' && !hasApiKeyScope(actor, 'api_keys:write')) {
+        throw new AppError('forbidden', 'This API key does not have the api_keys:write scope')
+      }
+
       await repository.deleteApiKey(dependencies.db, workspaceId, id)
     },
   }

package/src/modules/auth/credentials.ts

@@ -1,6 +1,8 @@
 import { getCookie } from 'hono/cookie'
 import type { Context } from 'hono'
 
+import type { ApiKeyScope } from '@kelpie/schemas'
+
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
 import { hashToken } from '../../lib/tokens.ts'
@@ -100,6 +102,7 @@ async function resolveApiKeyActor(
       userId: null,
       workspaceId: record.workspaceId,
       role: WORKSPACE_KEY_ROLE,
+      scopes: record.scopes as ApiKeyScope[],
       memberId: null,
     }
   }
@@ -118,6 +121,7 @@ async function resolveApiKeyActor(
     userId: record.userId,
     workspaceId: record.workspaceId,
     role: roleFromMembership(membership.role),
+    scopes: record.scopes as ApiKeyScope[],
     memberId: membership.id,
   }
 }