@ouraihub/aether-worker 0.0.0-stage → 0.1.0

package/src/credentials.ts

@@ -0,0 +1,153 @@
+import { badRequest, KitFailure } from '@ouraihub/aether-core'
+
+export interface CredentialScope {
+  readonly applicationId: string
+  readonly tenantId: string | null
+  readonly subjectId: string | null
+  readonly purpose: 'provider' | 'search' | 'mcp' | 'oauth'
+  readonly recordId: string
+}
+export interface SealedCredential {
+  readonly version: 1
+  readonly keyId: string
+  readonly nonce: string
+  readonly ciphertext: string
+}
+export interface CredentialPort {
+  seal(scope: CredentialScope, value: Uint8Array): Promise<SealedCredential>
+  open(scope: CredentialScope, sealed: SealedCredential): Promise<Uint8Array>
+  rotate(scope: CredentialScope, sealed: SealedCredential): Promise<SealedCredential>
+}
+const MAX_BYTES = 64 * 1024
+function unreadable(): KitFailure {
+  return new KitFailure('needs_config', 'Credential is unreadable', { reason: 'key_unreadable' })
+}
+function base64(bytes: Uint8Array): string {
+  let text = ''
+  for (const byte of bytes) text += String.fromCharCode(byte)
+  return btoa(text)
+}
+function unbase64(text: string): Uint8Array<ArrayBuffer> {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(text)) throw unreadable()
+  const bytes = Uint8Array.from(atob(text), (character) => character.charCodeAt(0))
+  if (base64(bytes) !== text) throw unreadable()
+  return bytes
+}
+export function isSealedCredential(value: unknown): value is SealedCredential {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'version' in value &&
+    value.version === 1 &&
+    'keyId' in value &&
+    typeof value.keyId === 'string' &&
+    value.keyId.length > 0 &&
+    value.keyId.length <= 128 &&
+    'nonce' in value &&
+    typeof value.nonce === 'string' &&
+    value.nonce.length === 16 &&
+    'ciphertext' in value &&
+    typeof value.ciphertext === 'string' &&
+    value.ciphertext.length >= 24 &&
+    value.ciphertext.length <= Math.ceil((MAX_BYTES + 16) / 3) * 4
+  )
+}
+function aad(scope: CredentialScope, keyId: string): Uint8Array<ArrayBuffer> {
+  if (
+    !scope.applicationId ||
+    !scope.recordId ||
+    scope.applicationId.length > 256 ||
+    scope.recordId.length > 256 ||
+    (scope.tenantId !== null && (!scope.tenantId || scope.tenantId.length > 256)) ||
+    (scope.subjectId !== null && (!scope.subjectId || scope.subjectId.length > 256)) ||
+    !['provider', 'search', 'mcp', 'oauth'].includes(scope.purpose)
+  )
+    throw badRequest('credentialScope', 'invalid')
+  return new TextEncoder().encode(
+    JSON.stringify([1, keyId, scope.applicationId, scope.tenantId, scope.subjectId, scope.purpose, scope.recordId]),
+  )
+}
+/** Supply non-extractable AES-GCM keys from deployment secrets/KMS; old keys are read-only until explicit rotation. */
+export function createCredentialPort(options: {
+  readonly currentKeyId: string
+  readonly keys: ReadonlyMap<string, CryptoKey>
+}): CredentialPort {
+  const keys = new Map(options.keys)
+  const currentKeyId = options.currentKeyId
+  if (!currentKeyId || currentKeyId.length > 128 || !keys.has(currentKeyId))
+    throw new KitFailure('needs_config', 'Credential key configuration is required')
+  for (const [id, key] of keys) {
+    if (
+      !id ||
+      id.length > 128 ||
+      key.type !== 'secret' ||
+      key.algorithm.name !== 'AES-GCM' ||
+      key.extractable ||
+      !key.usages.includes('decrypt') ||
+      (id === currentKeyId && !key.usages.includes('encrypt'))
+    )
+      throw new KitFailure('needs_config', 'Invalid credential key configuration')
+  }
+  async function seal(scope: CredentialScope, value: Uint8Array): Promise<SealedCredential> {
+    if (value.byteLength > MAX_BYTES) throw badRequest('credential', 'too_large', MAX_BYTES)
+    const key = keys.get(currentKeyId)
+    if (!key) throw unreadable()
+    const additionalData = aad(scope, currentKeyId)
+    const nonce = crypto.getRandomValues(new Uint8Array(12))
+    try {
+      const ciphertext = await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv: nonce, additionalData, tagLength: 128 },
+        key,
+        new Uint8Array(value),
+      )
+      return { version: 1, keyId: currentKeyId, nonce: base64(nonce), ciphertext: base64(new Uint8Array(ciphertext)) }
+    } catch {
+      throw unreadable()
+    }
+  }
+  async function open(scope: CredentialScope, sealed: SealedCredential): Promise<Uint8Array> {
+    try {
+      if (!isSealedCredential(sealed)) throw unreadable()
+      const key = keys.get(sealed.keyId)
+      if (!key) throw unreadable()
+      const nonce = unbase64(sealed.nonce)
+      const ciphertext = unbase64(sealed.ciphertext)
+      if (nonce.byteLength !== 12 || ciphertext.byteLength < 16 || ciphertext.byteLength > MAX_BYTES + 16)
+        throw unreadable()
+      return new Uint8Array(
+        await crypto.subtle.decrypt(
+          { name: 'AES-GCM', iv: nonce, additionalData: aad(scope, sealed.keyId), tagLength: 128 },
+          key,
+          ciphertext,
+        ),
+      )
+    } catch {
+      throw unreadable()
+    }
+  }
+  return Object.freeze({
+    seal,
+    open,
+    async rotate(scope: CredentialScope, sealed: SealedCredential) {
+      const plaintext = await open(scope, sealed)
+      try {
+        return await seal(scope, plaintext)
+      } finally {
+        plaintext.fill(0)
+      }
+    },
+  })
+}
+export async function importCredentialKey(encoded: string): Promise<CryptoKey> {
+  try {
+    const raw = unbase64(encoded)
+    if (raw.byteLength !== 32) throw unreadable()
+    try {
+      return await crypto.subtle.importKey('raw', raw, 'AES-GCM', false, ['encrypt', 'decrypt'])
+    } finally {
+      raw.fill(0)
+    }
+  } catch {
+    throw new KitFailure('needs_config', 'A 256-bit credential secret is required')
+  }
+}

package/src/files.ts

@@ -0,0 +1,105 @@
+import { badRequest, KitFailure } from '@ouraihub/aether-core'
+import { ownerKey, type Actor } from './context.ts'
+import type { R2Bucket } from './cloudflare.ts'
+
+export interface StoredFile {
+  readonly id: string
+  readonly mime: string
+  readonly size: number
+  readonly data: Uint8Array
+}
+export interface FileStore {
+  put(actor: Actor, id: string, file: { readonly mime: string; readonly data: Uint8Array }): Promise<StoredFile>
+  get(actor: Actor, id: string): Promise<StoredFile | null>
+  remove(actor: Actor, id: string): Promise<void>
+  /** An authenticated application route, never an R2 public/presigned secret URL. */
+  url(actor: Actor, id: string): string
+}
+const MIME_TYPES: Readonly<Record<string, true>> = {
+  'image/png': true,
+  'image/jpeg': true,
+  'image/webp': true,
+  'image/gif': true,
+  'application/json': true,
+  'application/octet-stream': true,
+}
+function fileId(id: string): void {
+  if (!/^[A-Za-z0-9_-]{1,128}$/u.test(id)) throw badRequest('fileId', 'invalid')
+}
+function matchesMime(data: Uint8Array, mime: string): boolean {
+  if (mime === 'image/png')
+    return (
+      data[0] === 137 &&
+      data[1] === 80 &&
+      data[2] === 78 &&
+      data[3] === 71 &&
+      data[4] === 13 &&
+      data[5] === 10 &&
+      data[6] === 26 &&
+      data[7] === 10
+    )
+  if (mime === 'image/jpeg') return data[0] === 255 && data[1] === 216 && data[2] === 255
+  if (mime === 'image/gif')
+    return (
+      new TextDecoder().decode(data.subarray(0, 6)) === 'GIF87a' ||
+      new TextDecoder().decode(data.subarray(0, 6)) === 'GIF89a'
+    )
+  if (mime === 'image/webp')
+    return (
+      new TextDecoder().decode(data.subarray(0, 4)) === 'RIFF' &&
+      new TextDecoder().decode(data.subarray(8, 12)) === 'WEBP'
+    )
+  return mime === 'application/json' || mime === 'application/octet-stream'
+}
+export class R2FileStore implements FileStore {
+  readonly #bucket: R2Bucket
+  readonly #maxBytes: number
+  constructor(bucket: R2Bucket, options: { readonly maxBytes: number }) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) throw badRequest('fileLimit', 'invalid')
+    this.#bucket = bucket
+    this.#maxBytes = options.maxBytes
+  }
+  async #key(actor: Actor, id: string): Promise<string> {
+    fileId(id)
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(ownerKey(actor)))
+    const ownerHash = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+    return `aether/files/v1/${ownerHash}/${id}`
+  }
+  async put(actor: Actor, id: string, file: { readonly mime: string; readonly data: Uint8Array }): Promise<StoredFile> {
+    if (!MIME_TYPES[file.mime] || !matchesMime(file.data, file.mime)) throw badRequest('mime', 'unsupported')
+    if (file.data.byteLength === 0 || file.data.byteLength > this.#maxBytes)
+      throw badRequest('file', 'too_large', this.#maxBytes)
+    const key = await this.#key(actor, id)
+    const written = await this.#bucket.put(key, file.data, {
+      httpMetadata: { contentType: file.mime },
+      onlyIf: { etagDoesNotMatch: '*' },
+    })
+    if (written === null) throw new KitFailure('conflict', 'File already exists')
+    return { id, mime: file.mime, size: file.data.byteLength, data: file.data }
+  }
+  async get(actor: Actor, id: string): Promise<StoredFile | null> {
+    const object = await this.#bucket.get(await this.#key(actor, id))
+    if (!object) return null
+    const mime = object.httpMetadata?.contentType
+    if (
+      !mime ||
+      !MIME_TYPES[mime] ||
+      !Number.isSafeInteger(object.size) ||
+      object.size < 1 ||
+      object.size > this.#maxBytes
+    )
+      throw new KitFailure('internal', 'Stored file is unreadable')
+    const data = new Uint8Array(await object.arrayBuffer())
+    if (data.byteLength !== object.size || !matchesMime(data, mime))
+      throw new KitFailure('internal', 'Stored file is unreadable')
+    return { id, mime, size: object.size, data }
+  }
+  async remove(actor: Actor, id: string): Promise<void> {
+    await this.#bucket.delete(await this.#key(actor, id))
+  }
+  url(actor: Actor, id: string): string {
+    ownerKey(actor)
+    fileId(id)
+    return `/api/v1/files/${encodeURIComponent(id)}`
+  }
+}

package/src/host.ts

@@ -0,0 +1,17 @@
+import type { Approval, ModelRef, PermissionMode, RunRequest } from '@ouraihub/aether-contracts'
+import type { AuthorizeContext, ToolCall, ToolExecution, ToolSpec } from '@ouraihub/aether-core/types'
+import type { WorkerContext } from './context.js'
+
+/** Business authorization remains the host's responsibility for every actor and resource. */
+export interface WorkerHost {
+  selectModel(request: RunRequest, context: WorkerContext): Promise<ModelRef>
+  systemPrompt(request: RunRequest, context: WorkerContext): Promise<string | null>
+  context(request: RunRequest, context: WorkerContext): Promise<{ source: string; text: string } | null>
+  tools(request: RunRequest, runId: string, context: WorkerContext): Promise<readonly ToolSpec[]>
+  permissionModes(request: RunRequest, context: WorkerContext): readonly PermissionMode[]
+  authorize(call: ToolCall, authorization: AuthorizeContext, context: WorkerContext): Approval
+  callTool(call: ToolCall, signal: AbortSignal, context: WorkerContext): Promise<ToolExecution>
+  runFinished(runId: string, context: WorkerContext): Promise<void>
+  mcpTools?(request: RunRequest, context: WorkerContext): boolean
+  paintingModel?(request: RunRequest, context: WorkerContext): Promise<ModelRef | null>
+}

package/src/identity.ts

@@ -0,0 +1,198 @@
+import { badRequest, KitFailure } from '@ouraihub/aether-core'
+import { immutableActor, isActor, ownerKey, type Actor } from './context.ts'
+import type { DocumentStore, StoredDocument } from './storage.ts'
+
+export interface IdentityPort {
+  resolve(request: Request): Promise<Actor | null>
+  verifyFresh(request: Request, actor: Actor): Promise<boolean>
+}
+/** Login, cookies, CSRF and reauthentication remain product-owned callbacks. */
+export function createIdentityPort(options: {
+  readonly applicationId: string
+  readonly resolve: (request: Request) => Promise<Actor | null>
+  readonly verifyFresh: (request: Request, actor: Actor) => Promise<boolean>
+}): IdentityPort {
+  if (!options.applicationId) throw new KitFailure('needs_config', 'Identity application is required')
+  return Object.freeze({
+    async resolve(request: Request): Promise<Actor | null> {
+      const actor = await options.resolve(request)
+      return isActor(actor) && actor.applicationId === options.applicationId ? immutableActor(actor) : null
+    },
+    async verifyFresh(request: Request, actor: Actor): Promise<boolean> {
+      if (!isActor(actor) || actor.applicationId !== options.applicationId) return false
+      const current = await options.resolve(request)
+      if (
+        !isActor(current) ||
+        ownerKey(current) !== ownerKey(actor) ||
+        current.sessionId !== actor.sessionId ||
+        current.kind !== actor.kind
+      )
+        return false
+      // Never cache this result: each reveal invokes the host's fresh verification.
+      return options.verifyFresh(request, immutableActor(current))
+    },
+  })
+}
+interface SessionRecord {
+  readonly actor: Actor
+  readonly createdAt: number
+  readonly lastSeenAt: number
+  readonly expiresAt: number
+}
+function parseSession(value: unknown): SessionRecord | null {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('actor' in value) ||
+    !isActor(value.actor) ||
+    value.actor.kind !== 'user' ||
+    value.actor.sessionId === null ||
+    !('createdAt' in value) ||
+    typeof value.createdAt !== 'number' ||
+    !Number.isSafeInteger(value.createdAt) ||
+    !('lastSeenAt' in value) ||
+    typeof value.lastSeenAt !== 'number' ||
+    !Number.isSafeInteger(value.lastSeenAt) ||
+    !('expiresAt' in value) ||
+    typeof value.expiresAt !== 'number' ||
+    !Number.isSafeInteger(value.expiresAt) ||
+    value.createdAt < 0 ||
+    value.lastSeenAt < value.createdAt ||
+    value.expiresAt <= value.lastSeenAt
+  )
+    return null
+  return { actor: value.actor, createdAt: value.createdAt, lastSeenAt: value.lastSeenAt, expiresAt: value.expiresAt }
+}
+function opaqueToken(): string {
+  return Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+async function tokenKey(token: string): Promise<string | null> {
+  if (!/^[a-f0-9]{64}$/u.test(token)) return null
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token))
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+/** Opaque browser sessions only; not OAuth bearer credentials or a login provider. */
+export class OpaqueSessionStore {
+  readonly #store: DocumentStore
+  readonly #registry: Actor
+  readonly #idleMs: number
+  readonly #absoluteMs: number
+  readonly #now: () => number
+  constructor(options: {
+    readonly store: DocumentStore
+    readonly applicationId: string
+    readonly idleMs: number
+    readonly absoluteMs: number
+    readonly now?: () => number
+  }) {
+    if (
+      !options.applicationId ||
+      !Number.isSafeInteger(options.idleMs) ||
+      options.idleMs <= 0 ||
+      !Number.isSafeInteger(options.absoluteMs) ||
+      options.absoluteMs < options.idleMs
+    )
+      throw badRequest('session', 'invalid_configuration')
+    this.#store = options.store
+    this.#registry = immutableActor({
+      applicationId: options.applicationId,
+      tenantId: null,
+      subjectId: 'aether:session-registry',
+      kind: 'service',
+      sessionId: null,
+      scopes: [],
+    })
+    this.#idleMs = options.idleMs
+    this.#absoluteMs = options.absoluteMs
+    this.#now = options.now ?? Date.now
+  }
+  async issue(actor: Actor): Promise<{ readonly token: string; readonly actor: Actor; readonly expiresAt: number }> {
+    if (!isActor(actor) || actor.kind !== 'user' || actor.applicationId !== this.#registry.applicationId)
+      throw badRequest('actor', 'invalid_session_owner')
+    const token = opaqueToken()
+    const key = await tokenKey(token)
+    if (key === null) throw new KitFailure('internal', 'Session generation failed')
+    const now = this.#now()
+    const sessionActor = immutableActor({ ...actor, sessionId: crypto.randomUUID() })
+    const expiresAt = now + this.#absoluteMs
+    await this.#store.compareAndSet(this.#registry, 'opaque_sessions', key, null, {
+      actor: sessionActor,
+      createdAt: now,
+      lastSeenAt: now,
+      expiresAt,
+    })
+    return { token, actor: sessionActor, expiresAt }
+  }
+  async #load(
+    token: string,
+  ): Promise<{ readonly key: string; readonly document: StoredDocument; readonly session: SessionRecord } | null> {
+    const key = await tokenKey(token)
+    if (key === null) return null
+    const document = await this.#store.get(this.#registry, 'opaque_sessions', key)
+    if (!document) return null
+    const session = parseSession(document.value)
+    const now = this.#now()
+    if (
+      !session ||
+      session.actor.applicationId !== this.#registry.applicationId ||
+      now < session.lastSeenAt ||
+      now >= session.expiresAt ||
+      now - session.lastSeenAt >= this.#idleMs
+    )
+      return null
+    return { key, document, session }
+  }
+  async resolve(token: string): Promise<Actor | null> {
+    const found = await this.#load(token)
+    if (!found) return null
+    try {
+      await this.#store.compareAndSet(this.#registry, 'opaque_sessions', found.key, found.document.revision, {
+        ...found.session,
+        lastSeenAt: this.#now(),
+      })
+      return immutableActor(found.session.actor)
+    } catch (error) {
+      if (error instanceof KitFailure && error.code === 'conflict') return null
+      throw error
+    }
+  }
+  async revoke(token: string): Promise<void> {
+    const key = await tokenKey(token)
+    if (key === null) return
+    // Retry only metadata CAS, never authentication or external side effects.
+    for (let attempt = 0; attempt < 8; attempt++) {
+      const document = await this.#store.get(this.#registry, 'opaque_sessions', key)
+      if (!document) return
+      try {
+        await this.#store.remove(this.#registry, 'opaque_sessions', key, document.revision)
+        return
+      } catch (error) {
+        if (!(error instanceof KitFailure) || error.code !== 'conflict') throw error
+      }
+    }
+    throw new KitFailure('conflict', 'Session revocation conflicted')
+  }
+  async rotate(
+    token: string,
+  ): Promise<{ readonly token: string; readonly actor: Actor; readonly expiresAt: number } | null> {
+    const found = await this.#load(token)
+    if (!found) return null
+    try {
+      await this.#store.remove(this.#registry, 'opaque_sessions', found.key, found.document.revision)
+    } catch (error) {
+      if (error instanceof KitFailure && error.code === 'conflict') return null
+      throw error
+    }
+    // Old token is already invalid even if issuing the replacement fails.
+    const replacement = opaqueToken()
+    const key = await tokenKey(replacement)
+    if (key === null) throw new KitFailure('internal', 'Session generation failed')
+    const actor = immutableActor({ ...found.session.actor, sessionId: crypto.randomUUID() })
+    await this.#store.compareAndSet(this.#registry, 'opaque_sessions', key, null, {
+      ...found.session,
+      actor,
+      lastSeenAt: this.#now(),
+    })
+    return { token: replacement, actor, expiresAt: found.session.expiresAt }
+  }
+}

package/src/images/index.ts

@@ -0,0 +1,46 @@
+import type { ImagePart, ImageRef } from '@ouraihub/aether-contracts'
+import { generateImage, ImageFailure, type ImageConnection, type ImageRequest } from '@ouraihub/aether-core/images'
+import type { OutboundHttp } from '@ouraihub/aether-core/ports'
+import type { WorkerContext } from '../context.js'
+
+export interface GeneratedImage {
+  readonly image: ImagePart
+  readonly reference: ImageRef
+  readonly persisted: boolean
+}
+export interface ImageServiceOptions {
+  readonly outbound: OutboundHttp
+  /** Host stores kind=generated under context.actor and returns a controlled display URL. */
+  readonly persist?: (image: ImagePart, context: WorkerContext) => Promise<ImageRef>
+}
+
+/** Explicit-input operation; runtime owns tool authorization, references and per-run limits. */
+export class ImageService {
+  private readonly options: ImageServiceOptions
+  constructor(options: ImageServiceOptions) {
+    this.options = options
+  }
+
+  async generate(connection: ImageConnection, input: ImageRequest, context: WorkerContext): Promise<GeneratedImage> {
+    const image = await generateImage(this.options.outbound, connection, input, context.signal)
+    if (!this.options.persist) {
+      return {
+        image,
+        reference: { mime: image.mime, url: `data:${image.mime};base64,${image.data}` },
+        persisted: false,
+      }
+    }
+    try {
+      if (context.signal.aborted)
+        throw new ImageFailure('cancelled', 'Image generated; persistence was cancelled', 'generated')
+      const reference = await this.options.persist(image, context)
+      return { image, reference, persisted: true }
+    } catch {
+      // Generation succeeded. Do not claim the provider did nothing or that saving succeeded.
+      throw new ImageFailure('internal', 'Image generated but persistence could not be confirmed', 'generated', {
+        field: 'images',
+        reason: 'generated_save_failed',
+      })
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export { createAetherWorkerApp } from './app.ts'
+export type { WorkerAppOptions, WorkerHandler, PublicWorkerHandler } from './app.ts'
+export { createRunCoordinator } from './coordinator.ts'
+export { WorkerRuntime } from './runtime.ts'
+export type { RuntimeOptions, PreparedExecution } from './runtime.ts'
+export type { WorkerHost } from './host.ts'
+export { immutableActor, isActor, ownerKey } from './context.ts'
+export type { Actor, WorkerContext } from './context.ts'
+export type * from './cloudflare.ts'
+export { D1DocumentStore, validateD1Schema } from './storage.ts'
+export type { DocumentStore, StoredDocument, DocumentListOptions } from './storage.ts'
+export { createCredentialPort, importCredentialKey, isSealedCredential } from './credentials.ts'
+export type { CredentialPort, CredentialScope, SealedCredential } from './credentials.ts'
+export { createIdentityPort, OpaqueSessionStore } from './identity.ts'
+export type { IdentityPort } from './identity.ts'
+export { createWorkerOutbound, createWorkerTargetCheck } from './outbound.ts'
+export type { WorkerOutboundOptions, OutboundLimits } from './outbound.ts'
+export { R2FileStore } from './files.ts'
+export type { FileStore, StoredFile } from './files.ts'
+export { createLogger } from './logger.ts'
+export type { Logger, LogRecord } from './logger.ts'
+export { ProviderService } from './providers/index.ts'
+export { SearchService } from './search/index.ts'
+export { ImageService } from './images/index.ts'
+export { SkillsService } from './skills/service.ts'
+export { ConversationService } from './conversations/index.ts'
+export type { AcceptedHandle } from './conversations/index.ts'
+export { createMcpService } from './mcp/index.ts'
+export type { McpService } from './mcp/index.ts'
+export type { McpServiceOptions } from './mcp/types.ts'

package/src/logger.ts

@@ -0,0 +1,87 @@
+export type LogEvent =
+  | 'request.finished'
+  | 'auth.rejected'
+  | 'session.revoked'
+  | 'mcp.grant.created'
+  | 'mcp.grant.revoked'
+  | 'mcp.api_key.created'
+  | 'mcp.api_key.revoked'
+  | 'tool.denied'
+  | 'run.finished'
+  | 'run.unknown'
+  | 'credential.decrypt_failed'
+export type LogValue = string | number | boolean
+export interface Logger {
+  log(event: LogEvent, fields: Readonly<Record<string, unknown>>): void
+}
+export interface LogRecord {
+  readonly event: LogEvent
+  readonly fields: Readonly<Record<string, LogValue>>
+}
+const EVENTS: Readonly<Record<LogEvent, true>> = {
+  'request.finished': true,
+  'auth.rejected': true,
+  'session.revoked': true,
+  'mcp.grant.created': true,
+  'mcp.grant.revoked': true,
+  'mcp.api_key.created': true,
+  'mcp.api_key.revoked': true,
+  'tool.denied': true,
+  'run.finished': true,
+  'run.unknown': true,
+  'credential.decrypt_failed': true,
+}
+const IDENTIFIERS: Readonly<Record<string, true>> = {
+  requestId: true,
+  runId: true,
+  applicationId: true,
+  actorHash: true,
+  providerId: true,
+  endpointId: true,
+  modelId: true,
+  toolId: true,
+  errorCode: true,
+}
+const COUNTERS: Readonly<Record<string, true>> = {
+  status: true,
+  durationMs: true,
+  count: true,
+  eventCount: true,
+  revision: true,
+  rounds: true,
+}
+/** Pass only internal opaque identifiers, never prompt/header objects. Unknown fields are dropped.
+ * Route values must be registered templates, not request URLs or user-supplied paths. */
+export function createLogger(options: {
+  readonly sink: (record: LogRecord) => void
+  readonly routes: readonly string[]
+}): Logger {
+  const routes = new Set(options.routes)
+  for (const route of routes)
+    if (!/^\/[A-Za-z0-9_/:.{}-]*$/u.test(route) || route.length > 256) throw new Error('Invalid log route template')
+  return Object.freeze({
+    log(event: LogEvent, fields: Readonly<Record<string, unknown>>): void {
+      if (!Object.hasOwn(EVENTS, event)) throw new Error('Invalid log event')
+      const safe: Record<string, LogValue> = {}
+      for (const [key, value] of Object.entries(fields)) {
+        if (Object.hasOwn(IDENTIFIERS, key) && typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/u.test(value))
+          safe[key] = value
+        else if (Object.hasOwn(COUNTERS, key) && typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+          safe[key] = value
+        else if (key === 'usageAvailable' && typeof value === 'boolean') safe[key] = value
+        else if (key === 'route' && typeof value === 'string' && routes.has(value)) safe[key] = value
+        else if (
+          key === 'state' &&
+          (value === 'accepted' ||
+            value === 'running' ||
+            value === 'completed' ||
+            value === 'failed' ||
+            value === 'cancelled' ||
+            value === 'unknown')
+        )
+          safe[key] = value
+      }
+      options.sink(Object.freeze({ event, fields: Object.freeze(safe) }))
+    },
+  })
+}