@ouraihub/aether-worker 0.0.0-stage → 0.1.1

package/src/mcp/types.ts

@@ -0,0 +1,81 @@
+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
+}

package/src/outbound.ts

@@ -0,0 +1,320 @@
+import { badRequest, KitFailure } from '@ouraihub/aether-core'
+import type { OutboundHttp } from '@ouraihub/aether-core/ports'
+import type { FetchBinding } from './cloudflare.ts'
+
+export interface OutboundLimits {
+  readonly firstByteMs: number
+  readonly idleMs: number
+  readonly totalMs: number
+  readonly maxResponseBytes: number
+}
+/** This binding MUST enforce public-only DNS at connect time, including all resolved
+ * IPv4/IPv6 addresses and rebinding. A DNS preflight followed by ordinary fetch is
+ * not this contract. It must not follow redirects or forward through an open proxy.
+ * Deploy a trusted egress service binding; absent that binding remote egress fails.
+ */
+export interface TrustedOutboundGateway {
+  readonly security: 'public-addresses-at-connect-time'
+  readonly binding: FetchBinding
+}
+/** Separately deployed, target-bound internal gateway. It must enforce exact
+ * configured origin/port at connect time, including DNS, with no redirect/proxy. */
+export interface TrustedPrivateOutboundGateway {
+  readonly security: 'explicit-private-targets-at-connect-time'
+  readonly binding: FetchBinding
+  readonly allowedOrigins: readonly string[]
+}
+export interface WorkerOutboundOptions {
+  readonly gateway?: TrustedOutboundGateway
+  readonly privateGateway?: TrustedPrivateOutboundGateway
+  readonly allowedOrigins: readonly string[]
+  readonly limits: OutboundLimits
+  /** Local integration tests only, literal loopback hosts; never hostname DNS. */
+  readonly allowLoopbackForTests?: boolean
+  readonly localFetch?: (url: string, init: RequestInit) => Promise<Response>
+}
+function isLoopback(hostname: string): boolean {
+  return hostname === '[::1]' || /^127(?:\.(?:\d{1,3})){3}$/u.test(hostname)
+}
+function privateLiteral(host: string): boolean {
+  if (host.startsWith('[')) {
+    const ip = host.slice(1, -1).toLowerCase()
+    // Public IPv6 unicast only; mapped/compatible IPv4, special and local ranges fail closed.
+    return (
+      !/^[23][0-9a-f]{0,3}:/u.test(ip) ||
+      ip.startsWith('2001:db8:') ||
+      ip.startsWith('2001:0:') ||
+      ip.startsWith('2002:')
+    )
+  }
+  if (!/^\d+(?:\.\d+){3}$/u.test(host))
+    return (
+      host === 'localhost' ||
+      host.endsWith('.localhost') ||
+      host.endsWith('.local') ||
+      !host.includes('.')
+    )
+  const parts = host.split('.').map(Number)
+  const a = parts[0],
+    b = parts[1],
+    c = parts[2]
+  return (
+    a === undefined ||
+    b === undefined ||
+    c === undefined ||
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    a >= 224 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && (b === 168 || b === 0 || b === 2)) ||
+    (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+    (a === 203 && b === 0 && c === 113)
+  )
+}
+export function createWorkerOutbound(options: WorkerOutboundOptions): OutboundHttp {
+  const limits = Object.freeze({ ...options.limits })
+  for (const value of Object.values(limits))
+    if (!Number.isSafeInteger(value) || value <= 0) throw badRequest('outboundLimits', 'invalid')
+  const origins = new Set(
+    options.allowedOrigins.map((origin) => {
+      let url: URL
+      try {
+        url = new URL(origin)
+      } catch {
+        throw badRequest('allowedOrigins', 'invalid')
+      }
+      if (url.origin !== origin || url.username || url.password)
+        throw badRequest('allowedOrigins', 'invalid')
+      return origin
+    }),
+  )
+  if (origins.size === 0)
+    throw new KitFailure('needs_config', 'Outbound origins must be explicitly configured')
+  const privateOrigins = new Set(options.privateGateway?.allowedOrigins ?? [])
+  for (const origin of privateOrigins) {
+    let target: URL
+    try {
+      target = new URL(origin)
+    } catch {
+      throw badRequest('privateOrigins', 'invalid')
+    }
+    if (
+      target.origin !== origin ||
+      !origins.has(origin) ||
+      (target.protocol !== 'http:' && target.protocol !== 'https:')
+    )
+      throw badRequest('privateOrigins', 'invalid')
+  }
+  return Object.freeze({
+    async fetch(url: string, init: RequestInit): Promise<Response> {
+      let target: URL
+      try {
+        target = new URL(url)
+      } catch {
+        throw badRequest('url', 'invalid')
+      }
+      const local = options.allowLoopbackForTests === true && isLoopback(target.hostname)
+      const privateTarget = privateOrigins.has(target.origin)
+      if (
+        target.username ||
+        target.password ||
+        target.hash ||
+        (!local && !privateTarget && target.protocol !== 'https:') ||
+        ((local || privateTarget) && target.protocol !== 'https:' && target.protocol !== 'http:') ||
+        (!local && !privateTarget && privateLiteral(target.hostname)) ||
+        !origins.has(target.origin)
+      )
+        throw badRequest('url', 'outbound_policy')
+      const gateway = privateTarget ? options.privateGateway : options.gateway
+      if (
+        !local &&
+        (!gateway ||
+          gateway.security !==
+            (privateTarget
+              ? 'explicit-private-targets-at-connect-time'
+              : 'public-addresses-at-connect-time'))
+      )
+        throw new KitFailure('needs_config', 'Trusted connect-time outbound gateway is required')
+      const abort = new AbortController()
+      let failure: KitFailure | null = null
+      const firstTimer = setTimeout(
+        () => fail(new KitFailure('timeout', 'Outbound first-byte deadline exceeded')),
+        limits.firstByteMs,
+      )
+      let idleTimer: ReturnType<typeof setTimeout> | undefined
+      const totalTimer = setTimeout(
+        () => fail(new KitFailure('timeout', 'Outbound total deadline exceeded')),
+        limits.totalMs,
+      )
+      let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+      let bodyController: ReadableStreamDefaultController<Uint8Array> | undefined
+      let finished = false
+      function clean(): void {
+        clearTimeout(firstTimer)
+        clearTimeout(idleTimer ?? 0)
+        clearTimeout(totalTimer)
+        init.signal?.removeEventListener('abort', callerAbort)
+        abort.signal.removeEventListener('abort', onAbort)
+      }
+      function fail(error: KitFailure): void {
+        if (!abort.signal.aborted) {
+          failure = error
+          abort.abort()
+        }
+      }
+      function callerAbort(): void {
+        fail(new KitFailure('cancelled', 'Outbound request cancelled'))
+      }
+      function onAbort(): void {
+        if (finished) return
+        finished = true
+        bodyController?.error(failure ?? new KitFailure('cancelled', 'Outbound request cancelled'))
+        if (reader) void reader.cancel().catch(() => {})
+        clean()
+      }
+      init.signal?.addEventListener('abort', callerAbort, { once: true })
+      abort.signal.addEventListener('abort', onAbort, { once: true })
+      if (init.signal?.aborted) callerAbort()
+      if (abort.signal.aborted)
+        throw failure ?? new KitFailure('cancelled', 'Outbound request cancelled')
+      try {
+        const headers = new Headers(init.headers)
+        headers.set('User-Agent', 'Aether-Worker/1')
+        const request: RequestInit & { credentials: 'omit' } = {
+          ...init,
+          headers,
+          redirect: 'manual',
+          signal: abort.signal,
+          credentials: 'omit',
+        }
+        // Remote fetch is always the trusted binding. Global fetch is only the literal-loopback opt-in.
+        const pending = local
+          ? (options.localFetch ?? fetch)(target.href, request)
+          : gateway?.binding.fetch(target.href, request)
+        if (!pending)
+          throw new KitFailure('needs_config', 'Trusted connect-time outbound gateway is required')
+        void pending.then(
+          (response) => {
+            if (abort.signal.aborted) void response.body?.cancel().catch(() => {})
+          },
+          () => {},
+        )
+        const aborted = Promise.withResolvers<never>()
+        const rejectAbort = () =>
+          aborted.reject(failure ?? new KitFailure('cancelled', 'Outbound request cancelled'))
+        abort.signal.addEventListener('abort', rejectAbort, { once: true })
+        let response: Response
+        try {
+          response = await Promise.race([pending, aborted.promise])
+        } finally {
+          abort.signal.removeEventListener('abort', rejectAbort)
+        }
+        if (abort.signal.aborted) {
+          void response.body?.cancel().catch(() => {})
+          throw failure
+        }
+        if (response.redirected || (response.url && response.url !== target.href)) {
+          void response.body?.cancel().catch(() => {})
+          throw badRequest('url', 'redirect_forbidden')
+        }
+        const length = response.headers.get('content-length')
+        if (
+          length !== null &&
+          (!/^\d+$/u.test(length) || Number(length) > limits.maxResponseBytes)
+        ) {
+          void response.body?.cancel().catch(() => {})
+          throw badRequest('response', 'too_large', limits.maxResponseBytes)
+        }
+        if (!response.body) {
+          finished = true
+          clean()
+          return response
+        }
+        reader = response.body.getReader()
+        let received = 0
+        const body = new ReadableStream<Uint8Array>({
+          start(controller) {
+            bodyController = controller
+          },
+          async pull(controller) {
+            if (!reader || finished) return
+            idleTimer = setTimeout(
+              () => fail(new KitFailure('timeout', 'Outbound idle deadline exceeded')),
+              limits.idleMs,
+            )
+            try {
+              const result = await reader.read()
+              clearTimeout(idleTimer)
+              if (finished) return
+              if (result.done) {
+                finished = true
+                clean()
+                controller.close()
+                reader.releaseLock()
+                return
+              }
+              clearTimeout(firstTimer)
+              received += result.value.byteLength
+              if (received > limits.maxResponseBytes) {
+                fail(badRequest('response', 'too_large', limits.maxResponseBytes))
+                return
+              }
+              controller.enqueue(result.value)
+            } catch {
+              fail(new KitFailure('internal', 'Outbound response failed'))
+            }
+          },
+          async cancel() {
+            finished = true
+            clean()
+            abort.abort()
+            await reader?.cancel().catch(() => {})
+          },
+        })
+        return new Response(body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+        })
+      } catch (error) {
+        finished = true
+        clean()
+        abort.abort()
+        if (error instanceof KitFailure) throw error
+        throw failure ?? new KitFailure('internal', 'Outbound request failed')
+      }
+    },
+  })
+}
+
+export interface TrustedTargetChecker {
+  readonly security: 'all-dns-addresses-preflight'
+  /** Reject if any A/AAAA result is private/special/unknown, or lookup fails.
+   * The content proxy must independently enforce its own connect-time address policy. */
+  checkTarget(url: URL, signal: AbortSignal): Promise<void>
+}
+export function createWorkerTargetCheck(options: {
+  readonly checker: TrustedTargetChecker
+  readonly allowLoopbackForTests?: boolean
+}): (url: URL, signal: AbortSignal) => Promise<void> {
+  if (!options.checker || options.checker.security !== 'all-dns-addresses-preflight')
+    throw new KitFailure('needs_config', 'Trusted DNS target checker is required')
+  return async (url: URL, signal: AbortSignal): Promise<void> => {
+    if (signal.aborted) throw new KitFailure('cancelled', 'Target check cancelled')
+    const local = options.allowLoopbackForTests === true && isLoopback(url.hostname)
+    if (
+      url.username ||
+      url.password ||
+      url.hash ||
+      (!local && url.protocol !== 'https:') ||
+      (local && url.protocol !== 'http:' && url.protocol !== 'https:') ||
+      (!local && privateLiteral(url.hostname))
+    )
+      throw badRequest('url', 'outbound_policy')
+    if (!local) await options.checker.checkTarget(new URL(url.href), signal)
+    if (signal.aborted) throw new KitFailure('cancelled', 'Target check cancelled')
+  }
+}

package/src/providers/catalog.ts

@@ -0,0 +1,63 @@
+import { isContract, type Provider } from '@ouraihub/aether-contracts'
+import { KitFailure } from '@ouraihub/aether-core/error'
+import { inferReasoning } from '@ouraihub/aether-core/providers/infer'
+import { isSealedCredential, type SealedCredential } from '../credentials.js'
+
+export interface Secret {
+  endpointId: string
+  keyId: string
+  sealed: SealedCredential
+}
+
+export interface Catalog {
+  providers: Provider[]
+  secrets: Secret[]
+  inferred: string[]
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function parseCatalog(value: unknown): Catalog {
+  if (
+    !record(value) ||
+    !Array.isArray(value.providers) ||
+    !Array.isArray(value.secrets) ||
+    !Array.isArray(value.inferred)
+  )
+    throw new KitFailure('incompatible_db', 'Invalid provider catalog')
+  const providers: Provider[] = []
+  const secrets: Secret[] = []
+  const inferred: string[] = []
+  for (const item of value.providers) {
+    if (!isContract('Provider', item))
+      throw new KitFailure('incompatible_db', 'Invalid provider document')
+    providers.push(item)
+  }
+  for (const item of value.secrets) {
+    if (
+      !record(item) ||
+      typeof item.endpointId !== 'string' ||
+      typeof item.keyId !== 'string' ||
+      !isSealedCredential(item.sealed)
+    )
+      throw new KitFailure('incompatible_db', 'Invalid provider credential')
+    secrets.push({ endpointId: item.endpointId, keyId: item.keyId, sealed: item.sealed })
+  }
+  for (const item of value.inferred) {
+    if (typeof item !== 'string')
+      throw new KitFailure('incompatible_db', 'Invalid reasoning declaration')
+    inferred.push(item)
+  }
+  const automatic = new Set(inferred)
+  for (const provider of providers)
+    for (const endpoint of provider.endpoints)
+      for (const model of endpoint.models)
+        if (automatic.has(JSON.stringify([endpoint.id, model.id])))
+          model.reasoning =
+            model.modelType === 'chat'
+              ? inferReasoning(model.id, endpoint.protocol, endpoint.baseUrl, model.maxOutput)
+              : null
+  return { providers, secrets, inferred }
+}

package/src/providers/http.ts

@@ -0,0 +1,88 @@
+import {
+  isContract,
+  type ModelFilter,
+  type ProviderSave,
+  type EndpointKeySave,
+  type ProbeTarget,
+} from '@ouraihub/aether-contracts'
+import { KitFailure, badRequest } from '@ouraihub/aether-core/error'
+import type { WorkerContext } from '../context.js'
+import type { ProviderService } from './index.js'
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export async function handleProviderRequest(
+  service: ProviderService,
+  request: Request,
+  context: WorkerContext,
+  authorizeReveal: (request: Request, context: WorkerContext) => Promise<void>,
+): Promise<Response | null> {
+  const url = new URL(request.url)
+  const path = url.pathname
+  const root = '/api/v1/providers'
+  if (path !== root && !path.startsWith(`${root}/`)) return null
+  const actor = context.actor
+  const json = (value: unknown): Response => Response.json(value)
+  if (path === root && request.method === 'GET') return json(await service.list(actor))
+  if (path === root && request.method === 'POST') {
+    const value: unknown = await request.json()
+    if (!isContract('ProviderSave', value)) throw badRequest('provider', 'invalid')
+    return json(await service.save(actor, value as ProviderSave))
+  }
+  if (path === `${root}/model-options` && request.method === 'GET') {
+    const value: unknown = {
+      ...(url.searchParams.has('modelType')
+        ? { modelType: url.searchParams.get('modelType') }
+        : {}),
+      ...(url.searchParams.has('supportsTools')
+        ? { supportsTools: url.searchParams.get('supportsTools') === 'true' }
+        : {}),
+    }
+    if (
+      url.searchParams.has('supportsTools') &&
+      !['true', 'false'].includes(url.searchParams.get('supportsTools') ?? '')
+    )
+      throw badRequest('supportsTools', 'invalid')
+    if (!isContract('ModelFilter', value)) throw badRequest('filter', 'invalid')
+    return json(await service.modelOptions(actor, value as ModelFilter))
+  }
+  if (path === `${root}/probe` && request.method === 'POST') {
+    const value: unknown = await request.json()
+    if (!isContract('ProbeTarget', value)) throw badRequest('target', 'invalid')
+    return json(await service.probe(actor, value as ProbeTarget, context.signal))
+  }
+  if (path === `${root}/keys` && request.method === 'POST') {
+    const value: unknown = await request.json()
+    if (!isContract('EndpointKeySave', value)) throw badRequest('key', 'invalid')
+    return json(await service.saveKey(actor, value as EndpointKeySave))
+  }
+  const reveal = path.match(/^\/api\/v1\/providers\/keys\/([^/]+)\/reveal$/)
+  if (reveal && request.method === 'POST') {
+    await authorizeReveal(request, context)
+    return json(await service.revealKey(actor, decodeURIComponent(reveal[1] ?? '')))
+  }
+  const key = path.match(/^\/api\/v1\/providers\/([^/]+)\/keys\/([^/]+)$/)
+  if (key && request.method === 'DELETE')
+    return json(
+      await service.removeKey(
+        actor,
+        decodeURIComponent(key[1] ?? ''),
+        decodeURIComponent(key[2] ?? ''),
+      ),
+    )
+  const enabled = path.match(/^\/api\/v1\/providers\/([^/]+)\/enabled$/)
+  if (enabled && request.method === 'POST') {
+    const value: unknown = await request.json()
+    if (!record(value) || Object.keys(value).length !== 1 || typeof value.enabled !== 'boolean')
+      throw badRequest('enabled', 'invalid')
+    return json(
+      await service.setEnabled(actor, decodeURIComponent(enabled[1] ?? ''), value.enabled),
+    )
+  }
+  const provider = path.match(/^\/api\/v1\/providers\/([^/]+)$/)
+  if (provider && request.method === 'DELETE')
+    return json(await service.remove(actor, decodeURIComponent(provider[1] ?? '')))
+  throw new KitFailure('not_found', 'Unknown route', { entity: 'route' })
+}