@sena-ai/platform-core 1.4.0

package/src/runtime/cf/relay.ts

@@ -0,0 +1,74 @@
+import type { Context } from 'hono'
+import type { RelayHub } from '../../types/relay.js'
+
+/**
+ * Durable Objects-based RelayHub for CF Workers.
+ *
+ * This stub communicates with a Durable Object namespace.
+ * Each bot gets its own Durable Object instance that manages WebSocket connections.
+ *
+ * The actual Durable Object class (RelayDurableObject) is exported from apps/worker.
+ */
+export function createCfRelay(doNamespace: DurableObjectNamespace): RelayHub {
+  function getStub(botId: string): DurableObjectStub {
+    const id = doNamespace.idFromName(botId)
+    return doNamespace.get(id)
+  }
+
+  return {
+    async handleStream(
+      c: Context,
+      botId: string,
+      _connectKey: string,
+    ): Promise<Response> {
+      const upgradeHeader = c.req.header('Upgrade')
+      if (upgradeHeader !== 'websocket') {
+        return c.json(
+          { error: 'expected websocket upgrade' },
+          { status: 426 },
+        )
+      }
+
+      // Forward the WebSocket upgrade request to the Durable Object
+      const stub = getStub(botId)
+      const url = new URL(c.req.url)
+      url.pathname = '/ws'
+      url.searchParams.set('botId', botId)
+
+      return stub.fetch(url.toString(), {
+        headers: c.req.raw.headers,
+      }) as unknown as Response
+    },
+
+    dispatch(botId: string, event: unknown): boolean {
+      // Fire and forget -- send event to the DO
+      const stub = getStub(botId)
+      const url = new URL('https://internal/dispatch')
+      url.searchParams.set('botId', botId)
+
+      stub
+        .fetch(url.toString(), {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(event),
+        })
+        .catch((err: unknown) => {
+          console.error(`[cf-relay] dispatch error for bot ${botId}:`, err)
+        })
+
+      // We return true optimistically; the DO handles delivery
+      return true
+    },
+
+    isConnected(_botId: string): boolean {
+      // In CF Workers, we cannot synchronously check DO state
+      // This is best-effort
+      return true
+    },
+
+    connectedBots(): string[] {
+      // Cannot enumerate Durable Objects synchronously
+      return []
+    },
+  }
+}

package/src/runtime/cf/vault.ts

@@ -0,0 +1,99 @@
+import type { Vault } from '../../types/vault.js'
+
+const ALGORITHM = 'AES-GCM'
+const IV_LENGTH = 12
+
+/**
+ * AES-256-GCM Vault implementation using Web Crypto API.
+ * Compatible with CF Workers runtime.
+ */
+export async function createCfVault(masterKeyHex: string): Promise<Vault> {
+  const rawKey = hexToArrayBuffer(masterKeyHex)
+  if (rawKey.byteLength !== 32) {
+    throw new Error('VAULT_MASTER_KEY must be 32 bytes (64 hex chars)')
+  }
+
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    rawKey,
+    { name: ALGORITHM },
+    false,
+    ['encrypt', 'decrypt'],
+  )
+
+  return {
+    async encrypt(plaintext: string): Promise<string> {
+      const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))
+      const encoded = new TextEncoder().encode(plaintext)
+
+      const ciphertext = await crypto.subtle.encrypt(
+        { name: ALGORITHM, iv },
+        cryptoKey,
+        encoded,
+      )
+
+      // Web Crypto appends authTag to ciphertext
+      // Format: base64(iv + ciphertext_with_tag) -- matches Node.js layout
+      // Node layout: iv(12) + authTag(16) + ciphertext
+      // WebCrypto layout: ciphertext + authTag(16)
+      // We need to rearrange to match Node.js format
+      const ctBytes = new Uint8Array(ciphertext)
+      const actualCiphertext = ctBytes.slice(0, ctBytes.length - 16)
+      const authTag = ctBytes.slice(ctBytes.length - 16)
+
+      const result = new Uint8Array(
+        iv.length + authTag.length + actualCiphertext.length,
+      )
+      result.set(iv, 0)
+      result.set(authTag, iv.length)
+      result.set(actualCiphertext, iv.length + authTag.length)
+
+      return uint8ArrayToBase64(result)
+    },
+
+    async decrypt(encoded: string): Promise<string> {
+      const data = base64ToUint8Array(encoded)
+      const iv = data.slice(0, IV_LENGTH)
+      const authTag = data.slice(IV_LENGTH, IV_LENGTH + 16)
+      const ciphertext = data.slice(IV_LENGTH + 16)
+
+      // Reconstruct WebCrypto format: ciphertext + authTag
+      const combined = new Uint8Array(ciphertext.length + authTag.length)
+      combined.set(ciphertext, 0)
+      combined.set(authTag, ciphertext.length)
+
+      const decrypted = await crypto.subtle.decrypt(
+        { name: ALGORITHM, iv },
+        cryptoKey,
+        combined,
+      )
+
+      return new TextDecoder().decode(decrypted)
+    },
+  }
+}
+
+function hexToArrayBuffer(hex: string): ArrayBuffer {
+  const bytes = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(hex.substring(i, i + 2), 16)
+  }
+  return bytes.buffer
+}
+
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i])
+  }
+  return btoa(binary)
+}
+
+function base64ToUint8Array(base64: string): Uint8Array {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}

package/src/runtime/node/crypto.ts

@@ -0,0 +1,33 @@
+import {
+  createHmac,
+  randomBytes,
+  timingSafeEqual as nodeTimingSafeEqual,
+} from 'node:crypto'
+import { v4 as uuidv4 } from 'uuid'
+import type { CryptoProvider } from '../../types/crypto.js'
+
+/**
+ * CryptoProvider implementation using Node.js crypto module.
+ */
+export function createNodeCrypto(): CryptoProvider {
+  return {
+    async randomHex(byteLength: number): Promise<string> {
+      return randomBytes(byteLength).toString('hex')
+    },
+
+    uuid(): string {
+      return uuidv4()
+    },
+
+    async hmacSha256(key: string, data: string): Promise<string> {
+      return createHmac('sha256', key).update(data).digest('hex')
+    },
+
+    async timingSafeEqual(a: string, b: string): Promise<boolean> {
+      const bufA = Buffer.from(a, 'utf8')
+      const bufB = Buffer.from(b, 'utf8')
+      if (bufA.length !== bufB.length) return false
+      return nodeTimingSafeEqual(bufA, bufB)
+    },
+  }
+}

package/src/runtime/node/index.ts

@@ -0,0 +1,28 @@
+import type { Vault } from '../../types/vault.js'
+import type { RelayHub } from '../../types/relay.js'
+import type { CryptoProvider } from '../../types/crypto.js'
+import { createNodeVault } from './vault.js'
+import { createNodeCrypto } from './crypto.js'
+import { createNodeRelay } from './relay.js'
+
+export interface NodeRuntimeConfig {
+  vaultMasterKey: string
+}
+
+export interface NodeRuntime {
+  vault: Vault
+  relay: RelayHub
+  crypto: CryptoProvider
+}
+
+/**
+ * Create runtime services for Node.js (vault, relay, crypto).
+ * Does NOT include DB repositories -- those are created separately via the DB subpath.
+ */
+export function createNodeRuntime(config: NodeRuntimeConfig): NodeRuntime {
+  const vault = createNodeVault(config.vaultMasterKey)
+  const crypto = createNodeCrypto()
+  const relay = createNodeRelay()
+
+  return { vault, relay, crypto }
+}

package/src/runtime/node/relay.ts

@@ -0,0 +1,98 @@
+import type { Context } from 'hono'
+import { streamSSE } from 'hono/streaming'
+import type { RelayHub } from '../../types/relay.js'
+
+type SSEClient = {
+  botId: string
+  connectKey: string
+  send: (event: string, data: string, id?: string) => void
+  close: () => void
+}
+
+/**
+ * SSE-based RelayHub implementation for Node.js.
+ */
+export function createNodeRelay(): RelayHub {
+  // botId -> SSEClient (1 bot = 1 active connection)
+  const clients = new Map<string, SSEClient>()
+
+  let eventCounter = 0
+
+  return {
+    async handleStream(
+      c: Context,
+      botId: string,
+      connectKey: string,
+    ): Promise<Response> {
+      return streamSSE(c, async (stream) => {
+        // Replace existing connection (reconnect scenario)
+        const existing = clients.get(botId)
+        if (existing) {
+          existing.close()
+        }
+
+        let closed = false
+
+        const client: SSEClient = {
+          botId,
+          connectKey,
+          send(event, data, id) {
+            if (closed) return
+            stream.writeSSE({ event, data, id }).catch(() => {
+              closed = true
+            })
+          },
+          close() {
+            closed = true
+          },
+        }
+
+        clients.set(botId, client)
+
+        // Connection confirmation event
+        client.send('connected', JSON.stringify({ botId, ts: Date.now() }))
+
+        // Heartbeat (every 30 seconds)
+        const heartbeatInterval = setInterval(() => {
+          if (closed) {
+            clearInterval(heartbeatInterval)
+            return
+          }
+          client.send('ping', JSON.stringify({ ts: Date.now() }))
+        }, 30_000)
+
+        // Wait for connection close
+        stream.onAbort(() => {
+          closed = true
+          clearInterval(heartbeatInterval)
+          clients.delete(botId)
+        })
+
+        // Keep connection alive until aborted
+        while (!closed) {
+          await new Promise((r) => setTimeout(r, 1000))
+        }
+
+        clearInterval(heartbeatInterval)
+        clients.delete(botId)
+      }) as unknown as Response
+    },
+
+    dispatch(botId: string, event: unknown): boolean {
+      const client = clients.get(botId)
+      if (!client) return false
+
+      const id = String(++eventCounter)
+      client.send('slack_event', JSON.stringify(event), id)
+      return true
+    },
+
+    isConnected(botId: string): boolean {
+      return clients.has(botId)
+    },
+
+    connectedBots(): string[] {
+      return Array.from(clients.keys())
+    },
+  }
+}

package/src/runtime/node/vault.ts

@@ -0,0 +1,50 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+} from 'node:crypto'
+import type { Vault } from '../../types/vault.js'
+
+const ALGORITHM = 'aes-256-gcm'
+const IV_LENGTH = 12
+const AUTH_TAG_LENGTH = 16
+
+/**
+ * AES-256-GCM Vault implementation using Node.js crypto.
+ * Returns Promises to match the Vault interface (Web Crypto compatibility).
+ */
+export function createNodeVault(masterKeyHex: string): Vault {
+  const masterKey = Buffer.from(masterKeyHex, 'hex')
+  if (masterKey.length !== 32) {
+    throw new Error('VAULT_MASTER_KEY must be 32 bytes (64 hex chars)')
+  }
+
+  return {
+    async encrypt(plaintext: string): Promise<string> {
+      const iv = randomBytes(IV_LENGTH)
+      const cipher = createCipheriv(ALGORITHM, masterKey, iv, {
+        authTagLength: AUTH_TAG_LENGTH,
+      })
+      const encrypted = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+      ])
+      const authTag = cipher.getAuthTag()
+      // Format: base64(iv + authTag + ciphertext)
+      return Buffer.concat([iv, authTag, encrypted]).toString('base64')
+    },
+
+    async decrypt(encoded: string): Promise<string> {
+      const data = Buffer.from(encoded, 'base64')
+      const iv = data.subarray(0, IV_LENGTH)
+      const authTag = data.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH)
+      const ciphertext = data.subarray(IV_LENGTH + AUTH_TAG_LENGTH)
+
+      const decipher = createDecipheriv(ALGORITHM, masterKey, iv, {
+        authTagLength: AUTH_TAG_LENGTH,
+      })
+      decipher.setAuthTag(authTag)
+      return decipher.update(ciphertext) + decipher.final('utf8')
+    },
+  }
+}

package/src/slack/events.ts

@@ -0,0 +1,92 @@
+import { Hono } from 'hono'
+import type { Vault } from '../types/vault.js'
+import type { RelayHub } from '../types/relay.js'
+import type { CryptoProvider } from '../types/crypto.js'
+import type { BotRepository } from '../types/repository.js'
+
+/**
+ * Slack HTTP Events API receiver + relay to SSE/WebSocket Hub.
+ *
+ * Route: POST /slack/events/:botId
+ * - url_verification challenge auto-response
+ * - signing_secret signature verification
+ * - Relay to local runtime via RelayHub
+ */
+export function createSlackEventsHandler(
+  botRepo: BotRepository,
+  vault: Vault,
+  relay: RelayHub,
+  crypto: CryptoProvider,
+) {
+  const app = new Hono()
+
+  app.post('/slack/events/:botId', async (c) => {
+    const botId = c.req.param('botId')
+    const rawBody = await c.req.text()
+
+    const bot = await botRepo.findByIdAndStatus(botId, 'active')
+    if (!bot) {
+      return c.json({ error: 'unknown bot' }, 404)
+    }
+
+    // Signing secret verification
+    if (bot.signingSecretEnc) {
+      const signingSecret = await vault.decrypt(bot.signingSecretEnc)
+      const timestamp = c.req.header('x-slack-request-timestamp')
+      const slackSignature = c.req.header('x-slack-signature')
+
+      if (!timestamp || !slackSignature) {
+        return c.json({ error: 'missing slack signature headers' }, 401)
+      }
+
+      // Only allow requests within 5 minutes (replay attack prevention)
+      const now = Math.floor(Date.now() / 1000)
+      if (Math.abs(now - Number(timestamp)) > 300) {
+        return c.json({ error: 'request too old' }, 401)
+      }
+
+      const basestring = `v0:${timestamp}:${rawBody}`
+      const hmac = await crypto.hmacSha256(signingSecret, basestring)
+      const computed = `v0=${hmac}`
+
+      const isValid = await crypto.timingSafeEqual(computed, slackSignature)
+      if (!isValid) {
+        return c.json({ error: 'invalid signature' }, 401)
+      }
+    }
+
+    const payload = JSON.parse(rawBody) as {
+      type: string
+      challenge?: string
+      event?: unknown
+      event_id?: string
+      event_time?: number
+      team_id?: string
+    }
+
+    // URL verification challenge
+    if (payload.type === 'url_verification') {
+      return c.json({ challenge: payload.challenge })
+    }
+
+    // event_callback -> relay to local runtime
+    if (payload.type === 'event_callback') {
+      const dispatched = relay.dispatch(botId, {
+        type: payload.type,
+        event: payload.event,
+        event_id: payload.event_id,
+        event_time: payload.event_time,
+        team_id: payload.team_id,
+      })
+
+      if (!dispatched) {
+        console.warn(`[events] bot ${botId} not connected, event dropped`)
+      }
+    }
+
+    // Slack expects 200 within 3 seconds
+    return c.json({ ok: true })
+  })
+
+  return app
+}

package/src/slack/oauth.ts

@@ -0,0 +1,127 @@
+import { Hono } from 'hono'
+import type { Vault } from '../types/vault.js'
+import type { CryptoProvider } from '../types/crypto.js'
+import type {
+  BotRepository,
+  OAuthStateRepository,
+} from '../types/repository.js'
+
+type OAuthAccessResponse = {
+  ok: boolean
+  access_token?: string
+  team?: { id: string; name: string }
+  bot_user_id?: string
+  error?: string
+}
+
+/**
+ * Slack OAuth 2.0 handler.
+ *
+ * Flow:
+ * 1. GET /oauth/start/:botId -> Redirect to Slack auth page
+ * 2. Slack approves -> GET /oauth/callback -> acquire bot_token -> save to Vault
+ */
+export function createOAuthHandler(
+  botRepo: BotRepository,
+  vault: Vault,
+  crypto: CryptoProvider,
+  oauthStates: OAuthStateRepository,
+) {
+  const app = new Hono()
+
+  app.get('/oauth/start/:botId', async (c) => {
+    const botId = c.req.param('botId')
+    const bot = await botRepo.findById(botId)
+
+    if (!bot || !bot.clientId) {
+      return c.json({ error: 'bot not found or not provisioned' }, 404)
+    }
+
+    // Clean up expired states
+    await oauthStates.deleteExpired()
+
+    const state = await crypto.randomHex(16)
+    await oauthStates.create({
+      state,
+      botId,
+      expiresAt: new Date(Date.now() + 5 * 60 * 1000),
+    })
+
+    const scopes = [
+      'app_mentions:read',
+      'chat:write',
+      'chat:write.public',
+      'channels:history',
+      'channels:read',
+      'channels:join',
+      'groups:history',
+      'groups:read',
+      'im:history',
+      'im:read',
+      'im:write',
+      'reactions:read',
+      'reactions:write',
+      'files:read',
+      'files:write',
+      'users:read',
+    ].join(',')
+
+    const slackUrl = new URL('https://slack.com/oauth/v2/authorize')
+    slackUrl.searchParams.set('client_id', bot.clientId)
+    slackUrl.searchParams.set('scope', scopes)
+    slackUrl.searchParams.set('state', state)
+
+    return c.redirect(slackUrl.toString())
+  })
+
+  app.get('/oauth/callback', async (c) => {
+    const code = c.req.query('code')
+    const state = c.req.query('state')
+
+    if (!code || !state) {
+      return c.json({ error: 'missing code or state' }, 400)
+    }
+
+    await oauthStates.deleteExpired()
+    const entry = await oauthStates.consume(state)
+    if (!entry) {
+      return c.json({ error: 'invalid or expired state' }, 400)
+    }
+
+    const bot = await botRepo.findById(entry.botId)
+    if (!bot || !bot.clientId || !bot.clientSecretEnc) {
+      return c.json({ error: 'bot configuration incomplete' }, 500)
+    }
+
+    const clientSecret = await vault.decrypt(bot.clientSecretEnc)
+
+    // Exchange code for token
+    const res = await fetch('https://slack.com/api/oauth.v2.access', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        client_id: bot.clientId,
+        client_secret: clientSecret,
+        code,
+      }),
+    })
+
+    const data = (await res.json()) as OAuthAccessResponse
+
+    if (!data.ok || !data.access_token) {
+      return c.json({ error: `Slack OAuth failed: ${data.error}` }, 400)
+    }
+
+    // Save bot token to Vault and activate
+    await botRepo.update(entry.botId, {
+      botTokenEnc: await vault.encrypt(data.access_token),
+      slackTeamId: data.team?.id ?? null,
+      status: 'active',
+    })
+
+    // Redirect to completion page
+    return c.redirect(`/bots/${entry.botId}/complete`)
+  })
+
+  return app
+}