@ouraihub/aether-worker 0.0.0-stage → 0.1.1

package/src/files.ts

@@ -0,0 +1,117 @@
+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,25 @@
+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,227 @@
+import { badRequest, KitFailure } from '@ouraihub/aether-core'
+import { immutableActor, isActor, ownerKey, type Actor } from './context.ts'
+import { retryCas } from './storage.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.
+    await retryCas(
+      async (cas) => {
+        const document = await this.#store.get(this.#registry, 'opaque_sessions', key)
+        if (document)
+          await cas(() =>
+            this.#store.remove(this.#registry, 'opaque_sessions', key, document.revision),
+          )
+      },
+      () => 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,73 @@
+import type { ImagePart, ImageRef } from '@ouraihub/aether-contracts'
+import {
+  generateImage,
+  ImageFailure,
+  type ImageConnection,
+  type ImageRequest,
+  type ImageGeneration,
+  type ImageLimits,
+} from '@ouraihub/aether-core/images'
+import type { OutboundHttp } from '@ouraihub/aether-core/ports'
+import type { WorkerContext } from '../context.js'
+
+export interface GeneratedImage extends ImageGeneration {
+  readonly reference: ImageRef
+  readonly persisted: boolean
+}
+export interface ImageServiceOptions {
+  readonly outbound: OutboundHttp
+  readonly limits?: ImageLimits
+  /** 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 result = await generateImage(
+      this.options.outbound,
+      connection,
+      input,
+      context.signal,
+      this.options.limits,
+    )
+    const { image } = result
+    if (!this.options.persist) {
+      return {
+        ...result,
+        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 { ...result, 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,98 @@
+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) }))
+    },
+  })
+}