@ouraihub/aether-worker 0.0.0-stage → 0.1.0

package/src/mcp/index.ts

@@ -0,0 +1,239 @@
+import { KitFailure, safeError, badRequest } from '@ouraihub/aether-core/error'
+import type { WorkerContext } from '../context.js'
+import { McpClientSettings } from './client.js'
+import { McpAuth } from './auth.js'
+import { McpOAuth } from './oauth.js'
+import { body, forbidden, json, jsonBody, object, validActor } from './common.js'
+import type { Authentication } from './auth.js'
+import type { ExposedMcpTool, McpServiceOptions } from './types.js'
+export type {
+  ApiKeyRecord,
+  GrantRecord,
+  McpScope,
+  McpSettings,
+  ExposedMcpTool,
+  McpCallContext,
+  McpServiceOptions,
+} from './types.js'
+export { McpClientSettings } from './client.js'
+
+const MAX_RESULT_BYTES = 2 * 1024 * 1024
+const encoder = new TextEncoder()
+function rpc(id: unknown, result: unknown, error = false): Response {
+  const message = {
+    jsonrpc: '2.0',
+    id: typeof id === 'string' || typeof id === 'number' ? id : null,
+    ...(error ? { error: result } : { result }),
+  }
+  if (encoder.encode(JSON.stringify(message)).byteLength > MAX_RESULT_BYTES)
+    return json({ jsonrpc: '2.0', id: message.id, error: { code: -32603, message: 'Result budget exceeded' } })
+  return json(message)
+}
+function rpcError(id: unknown, code: number, message: string): Response {
+  return rpc(id, { code, message }, true)
+}
+
+export class McpService {
+  private readonly auth: McpAuth
+  private readonly oauth: McpOAuth
+  private readonly clients: McpClientSettings
+  readonly options: McpServiceOptions
+  constructor(options: McpServiceOptions) {
+    this.options = options
+    const origin = new URL(options.origin)
+    if (origin.origin !== options.origin || origin.protocol !== 'https:' || !options.applicationId)
+      throw badRequest('origin', 'https_origin_required')
+    const scopeIds = new Set<string>()
+    for (const scope of options.scopes) {
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9:_.-]{0,127}$/u.test(scope.id) || scopeIds.has(scope.id))
+        throw badRequest('scopes', 'invalid_registration')
+      scopeIds.add(scope.id)
+    }
+    const tools = new Set<string>()
+    for (const tool of options.tools) {
+      if (
+        !/^[A-Za-z0-9_.-]{1,128}$/u.test(tool.name) ||
+        tools.has(tool.name) ||
+        !scopeIds.has(tool.scope) ||
+        !object(tool.inputSchema) ||
+        !Number.isSafeInteger(tool.maxRequestBytes ?? 65536) ||
+        (tool.maxRequestBytes ?? 65536) < 1 ||
+        (tool.maxRequestBytes ?? 65536) > MAX_RESULT_BYTES
+      )
+        throw badRequest('tools', 'invalid_registration')
+      tools.add(tool.name)
+    }
+    this.auth = new McpAuth(options)
+    this.oauth = new McpOAuth(options, this.auth)
+    this.clients = new McpClientSettings(options.store, options.credentials, options.outbound)
+  }
+  client(context: WorkerContext) {
+    if (!validActor(context.actor, this.options.applicationId)) forbidden()
+    return this.clients.runtime(context.actor)
+  }
+  async handlePublic(request: Request): Promise<Response | null> {
+    const url = new URL(request.url)
+    if (
+      url.pathname !== '/mcp' &&
+      !url.pathname.startsWith('/oauth/') &&
+      !url.pathname.startsWith('/.well-known/oauth-')
+    )
+      return null
+    if (url.origin !== this.options.origin || url.protocol !== 'https:') return json({ error: 'invalid_request' }, 400)
+    if (url.pathname === '/mcp') return this.mcp(request)
+    return this.oauth.handle(request)
+  }
+  async handle(request: Request, context: WorkerContext): Promise<Response | null> {
+    const path = new URL(request.url).pathname
+    if (!path.startsWith('/api/v1/mcp')) return null
+    this.auth.actor(context.actor)
+    const clientResponse = await this.clients.handle(request, context)
+    if (clientResponse) return clientResponse
+    if (path === '/api/v1/mcp/settings') {
+      if (request.method === 'GET')
+        return json({ ...(await this.auth.settings(context.actor)), scopes: this.options.scopes })
+      if (request.method === 'PUT') {
+        const value = await jsonBody(request)
+        if (
+          !Array.isArray(value.enabledScopes) ||
+          !value.enabledScopes.every((scope: unknown) => typeof scope === 'string')
+        )
+          throw badRequest('enabledScopes', 'invalid')
+        const requested = value.enabledScopes.length ? this.auth.requested(value.enabledScopes, context.actor) : []
+        if (!(await this.options.authorizeConsent(context.actor, requested, request))) forbidden()
+        return json({ ...(await this.auth.saveSettings(context.actor, value)), scopes: this.options.scopes })
+      }
+    }
+    if (path === '/api/v1/mcp/grants' && request.method === 'GET') return json(await this.auth.grants(context.actor))
+    if (path === '/api/v1/mcp/api-keys') {
+      if (request.method === 'GET') return json(await this.auth.keys(context.actor))
+      if (request.method === 'POST')
+        return json(await this.auth.issueKey(context.actor, await jsonBody(request), request), 201)
+    }
+    const revoke = /^\/api\/v1\/mcp\/(grants|api-keys)\/([^/]+)\/revoke$/u.exec(path)
+    if (revoke && request.method === 'POST') {
+      const id = revoke[2]
+      if (!id) throw badRequest('id', 'invalid')
+      await this.auth.revoke(context.actor, revoke[1] === 'grants' ? 'grant' : 'key', decodeURIComponent(id))
+      return json({ ok: true })
+    }
+    return json({ code: 'not_found', message: 'Route not found' }, 404)
+  }
+  private async mcp(request: Request): Promise<Response> {
+    const origin = request.headers.get('Origin')
+    if (origin !== null && ![this.options.origin, ...(this.options.mcpOrigins ?? [])].includes(origin))
+      return json({ error: 'forbidden' }, 403)
+    if (request.method !== 'POST') return new Response(null, { status: 405, headers: { Allow: 'POST' } })
+    const bearer = /^Bearer[\t ]+([^\s,]+)$/iu.exec(request.headers.get('Authorization') ?? '')?.[1]
+    const authentication = bearer ? await this.auth.authenticate(bearer) : null
+    if (!authentication)
+      return json({ error: 'unauthorized' }, 401, {
+        'WWW-Authenticate': `Bearer resource_metadata="${this.options.origin}/.well-known/oauth-protected-resource"`,
+      })
+    if (this.options.scopes.some((scope) => scope.id === 'mcp:access') && !authentication.scopes.includes('mcp:access'))
+      return json({ error: 'forbidden' }, 403)
+    const maxBytes =
+      this.options.tools.reduce((max, tool) => Math.max(max, tool.maxRequestBytes ?? 65536), 65536) + 8192
+    let message: unknown
+    try {
+      message = JSON.parse(await body(request, maxBytes))
+    } catch (error) {
+      if (error instanceof KitFailure && error.code === 'bad_request')
+        return json({ code: 'bad_request', message: 'Invalid request body' }, 413)
+      return rpcError(null, -32700, 'Parse error')
+    }
+    if (
+      !object(message) ||
+      message.jsonrpc !== '2.0' ||
+      typeof message.method !== 'string' ||
+      ('id' in message && typeof message.id !== 'string' && typeof message.id !== 'number' && message.id !== null)
+    )
+      return rpcError(null, -32600, 'Invalid request')
+    if (!('id' in message)) {
+      if (message.method === 'notifications/initialized' || message.method === 'notifications/cancelled')
+        return new Response(null, { status: 202 })
+      return rpcError(null, -32600, 'Invalid request')
+    }
+    const id = message.id
+    if (message.method === 'initialize') {
+      if (!object(message.params) || !['2024-11-05', '2025-03-26'].includes(String(message.params.protocolVersion)))
+        return rpcError(id, -32602, 'Unsupported protocol version')
+      return rpc(id, {
+        protocolVersion: message.params.protocolVersion,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'Aether MCP', version: '1.0.0' },
+      })
+    }
+    const protocol = request.headers.get('MCP-Protocol-Version')
+    if (protocol !== null && !['2024-11-05', '2025-03-26'].includes(protocol))
+      return rpcError(id, -32602, 'Unsupported protocol version')
+    if (message.method === 'ping') return rpc(id, {})
+    if (message.method === 'tools/list')
+      return rpc(id, {
+        tools: this.options.tools
+          .filter((tool) => authentication.scopes.includes(tool.scope))
+          .map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: {
+              readOnlyHint: tool.readOnly,
+              destructiveHint: tool.destructive,
+              idempotentHint: tool.idempotent,
+            },
+          })),
+      })
+    if (message.method !== 'tools/call') return rpcError(id, -32601, 'Method not found')
+    if (!object(message.params) || typeof message.params.name !== 'string')
+      return rpcError(id, -32602, 'Invalid parameters')
+    const toolName = message.params.name
+    const tool = this.options.tools.find((item) => item.name === toolName)
+    if (!tool) return rpcError(id, -32004, 'Tool not found')
+    if (!authentication.scopes.includes(tool.scope)) return rpcError(id, -32001, 'Forbidden')
+    const args: unknown = 'arguments' in message.params ? message.params.arguments : {}
+    if (!object(args)) return rpcError(id, -32602, 'Invalid parameters')
+    if (encoder.encode(JSON.stringify(args)).byteLength > (tool.maxRequestBytes ?? 65536))
+      return rpcError(id, -32602, 'Arguments too large')
+    if (!tool.validate(args)) return rpcError(id, -32602, 'Invalid parameters')
+    return this.call(id, tool, args, authentication, request.signal)
+  }
+  private async call(
+    id: unknown,
+    tool: ExposedMcpTool,
+    args: Record<string, unknown>,
+    auth: Authentication,
+    signal: AbortSignal,
+  ): Promise<Response> {
+    try {
+      if (signal.aborted || !(await this.options.authorizeTool(auth.actor, tool, args, signal)))
+        return rpcError(id, -32001, 'Forbidden')
+      if (signal.aborted) return rpcError(id, -32603, 'Cancelled')
+      const result = await tool.handler(args, { actor: auth.actor, tokenId: auth.tokenId, scopes: auth.scopes, signal })
+      if (result === undefined) throw new KitFailure('internal', 'Invalid tool result')
+      const payload = object(result)
+        ? { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result, isError: false }
+        : {
+            content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
+            isError: false,
+          }
+      const serialized = JSON.stringify({ jsonrpc: '2.0', id, result: payload })
+      if (encoder.encode(serialized).byteLength > MAX_RESULT_BYTES)
+        return rpcError(id, -32603, 'Result budget exceeded')
+      return new Response(serialized, { headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } })
+    } catch (error) {
+      const safe = safeError(error)
+      const code =
+        safe.code === 'bad_request'
+          ? -32602
+          : safe.code === 'not_found'
+            ? -32004
+            : safe.code === 'conflict'
+              ? -32009
+              : -32603
+      return rpc(id, { code, message: safe.message, data: safe }, true)
+    }
+  }
+}
+export function createMcpService(options: McpServiceOptions): McpService {
+  return new McpService(options)
+}

package/src/mcp/oauth.ts

@@ -0,0 +1,284 @@
+import { KitFailure, badRequest } from '@ouraihub/aether-core/error'
+import type { McpServiceOptions } from './types.js'
+import type { McpAuth } from './auth.js'
+import {
+  body,
+  equal,
+  escapeHtml,
+  forbidden,
+  hash,
+  json,
+  jsonBody,
+  object,
+  random,
+  strings,
+  validActor,
+} from './common.js'
+
+interface OAuthClient {
+  id: string
+  name: string
+  redirectUris: readonly string[]
+  createdAt: number
+}
+interface Authorization {
+  client: OAuthClient
+  redirectUri: string
+  scopes: string[]
+  challenge: string
+  state: string
+  resource: string
+}
+function client(value: unknown): value is OAuthClient {
+  return (
+    object(value) &&
+    typeof value.id === 'string' &&
+    typeof value.name === 'string' &&
+    strings(value.redirectUris) &&
+    typeof value.createdAt === 'number'
+  )
+}
+function redirectAllowed(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return (
+      !url.username &&
+      !url.password &&
+      !url.hash &&
+      (url.protocol === 'https:' ||
+        (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+    )
+  } catch {
+    return false
+  }
+}
+function redirect(target: string): Response {
+  return new Response(null, { status: 302, headers: { Location: target, 'Cache-Control': 'no-store' } })
+}
+
+export class McpOAuth {
+  readonly options: McpServiceOptions
+  readonly auth: McpAuth
+  constructor(options: McpServiceOptions, auth: McpAuth) {
+    this.options = options
+    this.auth = auth
+  }
+  async handle(request: Request): Promise<Response | null> {
+    const url = new URL(request.url)
+    const origin = this.options.origin
+    const resource = `${origin}/mcp`
+    if (url.pathname === '/.well-known/oauth-protected-resource' && request.method === 'GET')
+      return json({
+        resource,
+        authorization_servers: [origin],
+        bearer_methods_supported: ['header'],
+        scopes_supported: this.options.scopes.map((scope) => scope.id),
+      })
+    if (url.pathname === '/.well-known/oauth-authorization-server' && request.method === 'GET')
+      return json({
+        issuer: origin,
+        authorization_endpoint: `${origin}/oauth/authorize`,
+        token_endpoint: `${origin}/oauth/token`,
+        registration_endpoint: `${origin}/oauth/register`,
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: ['none'],
+        scopes_supported: this.options.scopes.map((scope) => scope.id),
+      })
+    if (url.pathname === '/oauth/register' && request.method === 'POST') return this.register(request)
+    if (url.pathname === '/oauth/authorize' && (request.method === 'GET' || request.method === 'POST'))
+      return this.authorize(request)
+    if (url.pathname === '/oauth/token' && request.method === 'POST') {
+      try {
+        return await this.token(request)
+      } catch (error) {
+        if (!(error instanceof KitFailure)) throw error
+        return json({ error: error.code === 'bad_request' ? 'invalid_request' : 'invalid_grant' }, 400)
+      }
+    }
+    if (url.pathname.startsWith('/oauth/') || url.pathname.startsWith('/.well-known/oauth-'))
+      return json({ error: 'invalid_request' }, 400)
+    return null
+  }
+  private async register(request: Request): Promise<Response> {
+    const input = await jsonBody(request, 16384)
+    if (
+      !strings(input.redirect_uris) ||
+      input.redirect_uris.length === 0 ||
+      input.redirect_uris.length > 10 ||
+      input.redirect_uris.some((uri) => uri.length > 2048 || !redirectAllowed(uri))
+    )
+      throw badRequest('redirect_uris', 'invalid')
+    if (input.token_endpoint_auth_method !== undefined && input.token_endpoint_auth_method !== 'none')
+      throw badRequest('token_endpoint_auth_method', 'unsupported')
+    if (
+      input.grant_types !== undefined &&
+      (!strings(input.grant_types) ||
+        input.grant_types.some((type) => type !== 'authorization_code' && type !== 'refresh_token'))
+    )
+      throw badRequest('grant_types', 'unsupported')
+    if (
+      input.response_types !== undefined &&
+      (!strings(input.response_types) || input.response_types.some((type) => type !== 'code'))
+    )
+      throw badRequest('response_types', 'unsupported')
+    if (input.client_name !== undefined && (typeof input.client_name !== 'string' || input.client_name.length > 128))
+      throw badRequest('client_name', 'invalid')
+    const record: OAuthClient = {
+      id: crypto.randomUUID(),
+      name: typeof input.client_name === 'string' ? input.client_name : 'MCP client',
+      redirectUris: [...new Set(input.redirect_uris)],
+      createdAt: this.auth.now(),
+    }
+    await this.options.store.compareAndSet(this.auth.system, 'mcp-clients', record.id, null, record)
+    return json(
+      {
+        client_id: record.id,
+        client_name: record.name,
+        redirect_uris: record.redirectUris,
+        token_endpoint_auth_method: 'none',
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+      },
+      201,
+    )
+  }
+  private async parse(request: Request): Promise<Authorization> {
+    const query = new URL(request.url).searchParams
+    for (const key of [
+      'client_id',
+      'redirect_uri',
+      'response_type',
+      'scope',
+      'code_challenge',
+      'code_challenge_method',
+      'state',
+      'resource',
+    ])
+      if (query.getAll(key).length > 1) throw badRequest(key, 'duplicate')
+    const record = await this.options.store.get(this.auth.system, 'mcp-clients', query.get('client_id') ?? '')
+    if (!record || !client(record.value)) throw badRequest('client_id', 'invalid')
+    const redirectUri = query.get('redirect_uri') ?? ''
+    if (!record.value.redirectUris.includes(redirectUri)) throw badRequest('redirect_uri', 'mismatch')
+    if (query.get('response_type') !== 'code' || query.get('code_challenge_method') !== 'S256')
+      throw badRequest('response_type', 'unsupported')
+    const challenge = query.get('code_challenge') ?? ''
+    if (!/^[A-Za-z0-9_-]{43}$/u.test(challenge)) throw badRequest('code_challenge', 'invalid')
+    const resource = `${this.options.origin}/mcp`
+    if (query.has('resource') && query.get('resource') !== resource) throw badRequest('resource', 'invalid')
+    const scopes = this.auth.requested((query.get('scope') ?? '').split(/\s+/u).filter(Boolean))
+    return { client: record.value, redirectUri, scopes, challenge, state: query.get('state') ?? '', resource }
+  }
+  private async authorize(request: Request): Promise<Response> {
+    const parsed = await this.parse(request)
+    const actor = await this.options.resolveIdentity(request)
+    if (!actor || !validActor(actor, this.options.applicationId) || actor.kind !== 'user')
+      return json({ error: 'login_required' }, 401)
+    this.auth.actor(actor)
+    this.auth.requested(parsed.scopes, actor)
+    const settings = await this.auth.settings(actor)
+    if (!settings.enabled || parsed.scopes.some((scope) => !settings.enabledScopes.includes(scope))) forbidden()
+    const requestHash = await hash(new URL(request.url).searchParams.toString())
+    if (request.method === 'GET') {
+      const csrf = random()
+      await this.options.store.compareAndSet(actor, 'mcp-consent', await hash(csrf), null, {
+        requestHash,
+        sessionId: actor.sessionId,
+        expiresAt: this.auth.now() + 600000,
+        used: false,
+      })
+      const scopeLabels = parsed.scopes.map(
+        (scope) => this.options.scopes.find((item) => item.id === scope)?.label ?? scope,
+      )
+      const html = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Authorize MCP client</title><body><main><h1>Authorize ${escapeHtml(parsed.client.name)}</h1><p>Grant the following permissions?</p><ul>${scopeLabels.map((label) => `<li>${escapeHtml(label)}</li>`).join('')}</ul><form method="post" action="${escapeHtml(new URL(request.url).pathname + new URL(request.url).search)}"><input type="hidden" name="csrf" value="${csrf}"><button name="decision" value="approve">Approve</button><button name="decision" value="deny">Deny</button></form></main></body></html>`
+      return new Response(html, {
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+          'Content-Security-Policy': "default-src 'none'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+          'Referrer-Policy': 'no-referrer',
+          'X-Content-Type-Options': 'nosniff',
+        },
+      })
+    }
+    if (request.headers.get('Origin') !== this.options.origin) forbidden()
+    const form = await this.form(request)
+    const csrf = form.get('csrf') ?? ''
+    const document = await this.options.store.get(actor, 'mcp-consent', await hash(csrf))
+    if (
+      !document ||
+      !object(document.value) ||
+      document.value.used !== false ||
+      document.value.requestHash !== requestHash ||
+      document.value.sessionId !== actor.sessionId ||
+      typeof document.value.expiresAt !== 'number' ||
+      document.value.expiresAt <= this.auth.now()
+    )
+      forbidden()
+    await this.options.store.compareAndSet(actor, 'mcp-consent', document.key, document.revision, {
+      ...document.value,
+      used: true,
+    })
+    const target = new URL(parsed.redirectUri)
+    if (parsed.state) target.searchParams.set('state', parsed.state)
+    if (form.get('decision') !== 'approve' || !(await this.options.authorizeConsent(actor, parsed.scopes, request))) {
+      target.searchParams.set('error', 'access_denied')
+      return redirect(target.toString())
+    }
+    const grant = await this.auth.createGrant(actor, parsed.client.id, parsed.redirectUri, parsed.scopes)
+    const code = random()
+    await this.options.store.compareAndSet(this.auth.system, 'mcp-codes', await hash(code), null, {
+      owner: actor,
+      clientId: parsed.client.id,
+      redirectUri: parsed.redirectUri,
+      challenge: parsed.challenge,
+      grantId: grant.id,
+      expiresAt: this.auth.now() + 120000,
+      used: false,
+      resource: parsed.resource,
+    })
+    target.searchParams.set('code', code)
+    return redirect(target.toString())
+  }
+  private async form(request: Request): Promise<URLSearchParams> {
+    if (!(request.headers.get('Content-Type') ?? '').toLowerCase().startsWith('application/x-www-form-urlencoded'))
+      throw badRequest('body', 'form_required')
+    const form = new URLSearchParams(await body(request, 16384))
+    for (const key of new Set(form.keys())) if (form.getAll(key).length !== 1) throw badRequest(key, 'duplicate')
+    return form
+  }
+  private async token(request: Request): Promise<Response> {
+    const form = await this.form(request)
+    const clientId = form.get('client_id') ?? ''
+    if (form.has('resource') && form.get('resource') !== `${this.options.origin}/mcp`)
+      throw badRequest('resource', 'invalid')
+    if (form.get('grant_type') === 'refresh_token')
+      return json(await this.auth.refresh(form.get('refresh_token') ?? '', clientId))
+    if (form.get('grant_type') !== 'authorization_code') throw badRequest('grant_type', 'unsupported')
+    const document = await this.options.store.get(this.auth.system, 'mcp-codes', await hash(form.get('code') ?? ''))
+    if (!document || !object(document.value)) throw new KitFailure('unauthorized', 'Invalid grant')
+    const value = document.value
+    const verifier = form.get('code_verifier') ?? ''
+    if (
+      value.resource !== `${this.options.origin}/mcp` ||
+      !validActor(value.owner, this.options.applicationId) ||
+      value.owner.kind !== 'user' ||
+      value.used !== false ||
+      typeof value.expiresAt !== 'number' ||
+      value.expiresAt <= this.auth.now() ||
+      value.clientId !== clientId ||
+      value.redirectUri !== form.get('redirect_uri') ||
+      typeof value.challenge !== 'string' ||
+      typeof value.grantId !== 'string' ||
+      !/^[A-Za-z0-9._~-]{43,128}$/u.test(verifier) ||
+      !equal(await hash(verifier), value.challenge)
+    )
+      throw new KitFailure('unauthorized', 'Invalid grant')
+    await this.options.store.compareAndSet(this.auth.system, 'mcp-codes', document.key, document.revision, {
+      ...value,
+      used: true,
+    })
+    return json(await this.auth.issueTokens(value.owner, value.grantId, undefined, clientId))
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,74 @@
+import type { OutboundHttp } from '@ouraihub/aether-core'
+import type { Actor } from '../context.js'
+import type { CredentialPort } from '../credentials.js'
+import type { DocumentStore } from '../storage.js'
+
+export interface McpScope {
+  readonly id: string
+  readonly label: string
+  readonly destructive: boolean
+}
+export interface ExposedMcpTool {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: Readonly<Record<string, unknown>>
+  readonly scope: string
+  readonly readOnly: boolean
+  readonly destructive: boolean
+  readonly idempotent: boolean
+  readonly maxRequestBytes?: number
+  readonly validate: (args: Readonly<Record<string, unknown>>) => boolean
+  readonly handler: (args: Readonly<Record<string, unknown>>, context: McpCallContext) => Promise<unknown>
+}
+export interface McpCallContext {
+  readonly actor: Actor
+  readonly tokenId: string
+  readonly scopes: readonly string[]
+  readonly signal: AbortSignal
+}
+export interface McpServiceOptions {
+  readonly applicationId: string
+  readonly origin: string
+  readonly store: DocumentStore
+  readonly credentials: CredentialPort
+  readonly outbound: OutboundHttp
+  readonly scopes: readonly McpScope[]
+  readonly tools: readonly ExposedMcpTool[]
+  readonly resolveIdentity: (request: Request) => Promise<Actor | null>
+  /** Must check the actor may grant every requested scope, not just that login exists. */
+  readonly authorizeConsent: (actor: Actor, scopes: readonly string[], request: Request) => Promise<boolean>
+  /** Must check resource/business access immediately before external tool dispatch. */
+  readonly authorizeTool: (
+    actor: Actor,
+    tool: ExposedMcpTool,
+    args: Readonly<Record<string, unknown>>,
+    signal: AbortSignal,
+  ) => Promise<boolean>
+  readonly mcpOrigins?: readonly string[]
+  readonly now?: () => number
+}
+export interface McpSettings {
+  readonly enabled: boolean
+  readonly enabledScopes: readonly string[]
+}
+export interface GrantRecord {
+  readonly id: string
+  readonly applicationId: string
+  readonly tenantId: string | null
+  readonly subjectId: string
+  readonly clientId: string
+  readonly redirectUri: string
+  readonly scopes: readonly string[]
+  readonly createdAt: number
+  readonly expiresAt: number | null
+  readonly revokedAt: number | null
+}
+export interface ApiKeyRecord {
+  readonly id: string
+  readonly name: string
+  readonly scopes: readonly string[]
+  readonly prefix: string
+  readonly createdAt: number
+  readonly expiresAt: number | null
+  readonly revokedAt: number | null
+}