@ossy/platform 1.39.2 → 3.0.1

package/src/mcp/mount-ossy-mcp.js

@@ -0,0 +1,72 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { createOssyMcpServer } from './create-ossy-mcp-server.js'
+
+/**
+ * @param {import('express').Express} app
+ * @param {{
+ *   capabilities: object,
+ *   invokeAction: (actionId: string, payload: object, req: import('express').Request) => Promise<unknown>,
+ *   requireAuth?: (req: import('express').Request, res: import('express').Response) => boolean,
+ *   customTools?: Array<object>,
+ *   path?: string,
+ *   capabilitiesPath?: string,
+ * }} options
+ */
+export function mountOssyMcp ({ app, capabilities, invokeAction, requireAuth, customTools, path = '/mcp', capabilitiesPath = '/capabilities.json' }) {
+  app.get(capabilitiesPath, (req, res) => {
+    if (requireAuth && !requireAuth(req, res)) return
+    res.json(capabilities)
+  })
+
+  const handleMcpPost = async (req, res) => {
+    if (requireAuth && !requireAuth(req, res)) return
+
+    const server = createOssyMcpServer({
+      capabilities,
+      customTools: customTools?.map((tool) => ({
+        ...tool,
+        handler: (args, extra) => tool.handler(args, req, extra),
+      })),
+      invokeAction: (actionId, payload) => invokeAction(actionId, payload, req),
+    })
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    })
+
+    try {
+      await server.connect(transport)
+      await transport.handleRequest(req, res, req.body)
+      res.on('close', () => {
+        transport.close()
+        server.close()
+      })
+    } catch (err) {
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: err?.message || 'Internal error' },
+          id: null,
+        })
+      }
+    }
+  }
+
+  app.post(path, handleMcpPost)
+
+  app.get(path, (_req, res) => {
+    res.status(405).json({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Method not allowed.' },
+      id: null,
+    })
+  })
+
+  app.delete(path, (_req, res) => {
+    res.status(405).json({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Method not allowed.' },
+      id: null,
+    })
+  })
+}

package/src/mcp/mount-platform-mcp.js

@@ -0,0 +1,101 @@
+import { buildCapabilities } from '@ossy/app/manifest/build-capabilities'
+import { mountOssyMcp } from './mount-ossy-mcp.js'
+import { uploadFileToolHandler, UPLOAD_FILE_TOOL } from './upload-file-tool.js'
+import { ActionService } from '../actions/action.service.js'
+import { TaskService } from '../tasks/task-service.js'
+import { IntegrationService } from '../integration.service.js'
+import { createLogger } from '@ossy/observability'
+import { assertActionEntitled } from '../entitlements/action-entitlement.js'
+
+/**
+ * @param {import('express').Express} app
+ * @param {{
+ *   manifest: object,
+ *   capabilities?: object,
+ *   log?: import('@ossy/observability').Logger,
+ *   actionEntitlementIndex?: Map<string, { packageName: string, entitlementRequired: boolean }>,
+ *   loadWorkspaceForEntitlements?: (workspaceId: string) => Promise<{ services?: Record<string, unknown> } | null>,
+ * }} options
+ */
+export function mountPlatformMcp (app, {
+  manifest,
+  capabilities,
+  log = createLogger('platform/mcp'),
+  actionEntitlementIndex,
+  loadWorkspaceForEntitlements,
+}) {
+  const resolvedCapabilities = capabilities ?? buildCapabilities({
+    actions: manifest.actions,
+    tasks: manifest.tasks,
+    schemas: manifest.schemas,
+    taskCatalog: manifest.taskCatalog,
+    taskGraphEdges: manifest.taskGraphEdges,
+  })
+
+  const requireAuth = (req, res) => {
+    if (!req.userId || req.userId === 'anonymous') {
+      res.status(401).json({ error: 'Unauthorized — MCP requires API token or session auth' })
+      return false
+    }
+    return true
+  }
+
+  const invokePlatformAction = async (actionId, payload, req) => {
+    const action = ActionService.get(actionId)
+    if (!action) {
+      throw Object.assign(new Error(`Action not found: ${actionId}`), { status: 404 })
+    }
+
+    if (action.access === 'authenticated' && (!req?.userId || req.userId === 'anonymous')) {
+      throw Object.assign(new Error('Unauthorized'), { status: 401 })
+    }
+    if (action.access === 'workspace' && !req?.workspaceId) {
+      throw Object.assign(new Error('Forbidden — workspaceId header required'), { status: 403 })
+    }
+    if (!ActionService.hasHandler(actionId)) {
+      throw Object.assign(new Error(`Action has no server handler: ${actionId}`), { status: 405 })
+    }
+
+    if (actionEntitlementIndex && loadWorkspaceForEntitlements) {
+      await assertActionEntitled({
+        actionId,
+        access: action.access,
+        workspaceId: payload?.workspaceId ?? req?.workspaceId,
+        entitlementIndex: actionEntitlementIndex,
+        loadWorkspace: loadWorkspaceForEntitlements,
+      })
+    }
+
+    const actionLog = createLogger(actionId)
+    return ActionService.invoke(actionId, {
+      payload: {
+        workspaceId: payload?.workspaceId ?? req?.workspaceId,
+        user: req?.user,
+        userId: req?.userId,
+        ...payload,
+      },
+      sdk: req?.sdk ?? null,
+      log: actionLog,
+      integrations: IntegrationService,
+      req,
+    })
+  }
+
+  mountOssyMcp({
+    app,
+    capabilities: resolvedCapabilities,
+    requireAuth,
+    invokeAction: invokePlatformAction,
+    customTools: [
+      {
+        ...UPLOAD_FILE_TOOL,
+        handler: (args, req) => uploadFileToolHandler(invokePlatformAction, args, req),
+      },
+    ],
+  })
+
+  log.info(`MCP mounted at /mcp (${resolvedCapabilities.tools?.length ?? 0} action tools, ${resolvedCapabilities.tasks?.length ?? 0} tasks in topology resource)`)
+  return resolvedCapabilities
+}
+
+export { buildCapabilities }

package/src/mcp/upload-file-tool.js

@@ -0,0 +1,62 @@
+import { readFile, stat } from 'node:fs/promises'
+
+/**
+ * Composite upload: create binary resource + PUT file bytes.
+ *
+ * @param {(actionId: string, payload: object, req?: object) => Promise<unknown>} invokeAction
+ * @param {import('express').Request} [req]
+ */
+export async function uploadFileToolHandler (invokeAction, args, req) {
+  const filePath = args.filePath
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('filePath is required')
+  }
+
+  const fileStat = await stat(filePath)
+  const body = await readFile(filePath)
+  const type = args.type || 'application/octet-stream'
+
+  const resource = await invokeAction('@ossy/resources/actions/create', {
+    workspaceId: args.workspaceId,
+    location: args.location,
+    name: args.name,
+    type,
+    size: fileStat.size,
+  }, req)
+
+  const uploadUrl = resource?.content?.uploadUrl
+  if (!uploadUrl) {
+    throw new Error('Storage is not configured or create did not return uploadUrl')
+  }
+
+  const response = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': type },
+    body,
+  })
+
+  if (!response.ok) {
+    throw new Error(`Upload failed: HTTP ${response.status}`)
+  }
+
+  return invokeAction('@ossy/resources/actions/get', {
+    workspaceId: args.workspaceId,
+    resourceId: resource.id,
+  }, req)
+}
+
+export const UPLOAD_FILE_TOOL = {
+  name: 'ossy_storage_upload_file',
+  description: 'Create a binary file resource and upload bytes from a local file path.',
+  inputSchema: {
+    type: 'object',
+    required: ['location', 'name', 'type', 'filePath'],
+    properties: {
+      workspaceId: { type: 'string' },
+      location: { type: 'string', description: 'Parent folder path, e.g. /test/' },
+      name: { type: 'string', description: 'Filename with extension' },
+      type: { type: 'string', description: 'Mime type, e.g. image/png' },
+      filePath: { type: 'string', description: 'Absolute path to the file on disk' },
+    },
+  },
+}

package/src/metering/metering-service.js

@@ -0,0 +1,91 @@
+import { nanoid } from 'nanoid'
+import { EventStore } from '@ossy/event-store'
+import { createLogger, metrics } from '@ossy/observability'
+import { moduleIdFromTaskId } from '../audit/audit-helpers.js'
+
+const log = createLogger('platform/metering')
+
+/**
+ * Append-only usage records for billing replay (Wave 3 — record only).
+ */
+export const MeteringService = {
+
+  /**
+   * @param {{
+   *   kind: 'action' | 'task',
+   *   actionId?: string | null,
+   *   taskId?: string | null,
+   *   channel?: string | null,
+   *   workspaceId?: string | null,
+   *   actorId?: string | null,
+   *   durationMs?: number | null,
+   *   success?: boolean,
+   *   actionInvocationId?: string | null,
+   *   taskRunId?: string | null,
+   *   trigger?: string | null,
+   * }} record
+   */
+  async record (record) {
+    const {
+      kind,
+      actionId = null,
+      taskId = null,
+      channel = null,
+      workspaceId = null,
+      actorId = null,
+      durationMs = null,
+      success = true,
+      actionInvocationId = null,
+      taskRunId = null,
+      trigger = null,
+    } = record
+
+    const moduleId = taskId
+      ? moduleIdFromTaskId(taskId)
+      : actionId
+        ? moduleIdFromTaskId(actionId)
+        : 'unknown'
+
+    const envelope = {
+      kind,
+      moduleId,
+      actionId,
+      taskId,
+      channel,
+      workspaceId,
+      actorId,
+      durationMs,
+      success,
+      actionInvocationId,
+      taskRunId,
+      trigger,
+      recordedAt: Date.now(),
+    }
+
+    try {
+      metrics.increment('meter.record', { kind, module: moduleId, success: String(success) })
+      if (durationMs != null) {
+        metrics.timing('meter.duration', durationMs, { kind, module: moduleId })
+      }
+    } catch {}
+
+    try {
+      await EventStore.AppendResourceEvent({
+        id: nanoid(),
+        type: '@ossy/platform/schema/meter-event',
+        resourceId: nanoid(),
+        event: 'Recorded',
+        version: 1,
+        created: Date.now(),
+        createdBy: actorId ?? undefined,
+        payload: {
+          ...envelope,
+          belongsTo: workspaceId,
+          location: '/@ossy/metering/',
+        },
+      })
+    } catch (err) {
+      log.warn('[MeteringService] Failed to persist meter event', envelope, err)
+    }
+  },
+}

package/src/{platform-config.resource.js → platform-config.schema.js}

@@ -10,7 +10,7 @@
  */
 export default {
   name: 'Platform config',
-  id: '@ossy/platform/config',
+  id: '@ossy/platform/schema/config',
   icon: 'controller',
   fields: [
     {

package/src/proxy-internal.js

@@ -1,4 +1,8 @@
 import { createLogger } from '@ossy/observability'
+import {
+  mergeUserAppSettingsCookie,
+  readUserAppSettings,
+} from './user-app-settings.js'
 
 const log = createLogger('platform')
 
@@ -23,19 +27,7 @@ export function ProxyInternal () {
       }
 
       const requestedSettings = req.body
-      const expiresMaxAge = 2147483647
-      const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
-
-      const updatedSettings = {
-        ...userSettings,
-        ...requestedSettings,
-      }
-
-      res.cookie('x-ossy-user-settings', JSON.stringify(updatedSettings), {
-        httpOnly: true,
-        signed: true,
-        expires: new Date(Date.now() + expiresMaxAge),
-      })
+      mergeUserAppSettingsCookie(req, res, requestedSettings)
 
       res.status(201)
       res.json('')
@@ -44,7 +36,7 @@ export function ProxyInternal () {
 
     if (req.originalUrl.startsWith('/@ossy/users/me/app-settings') && req.method === 'GET') {
       log.info('[@ossy/platform][proxy] GET /@ossy/users/me/app-settings')
-      const userSettings = JSON.parse(req.signedCookies?.['x-ossy-user-settings'] || '{}')
+      const userSettings = readUserAppSettings(req)
       res.status(200)
       res.json(userSettings)
       return
@@ -52,8 +44,13 @@ export function ProxyInternal () {
 
     log.info(`[@ossy/platform][proxy] ${req.method} ${req.originalUrl}`)
 
-    const domain = process.env.OSSY_API_URL || 'https://api.ossy.se'
-    const url = `${domain}${req.originalUrl?.replace('/@ossy', '/api/v0')}`
+    const domain = (process.env.OSSY_API_URL || 'https://api.ossy.se')
+      .replace(/\/api\/v0\/?$/, '')
+      .replace(/\/$/, '')
+    const pathAfterOssy = req.originalUrl.replace(/^\/@ossy/, '') || '/'
+    // POST /actions lives on the app server root — not under /api/v0.
+    const upstreamPath = pathAfterOssy === '/actions' ? '/actions' : `/api/v0${pathAfterOssy}`
+    const url = `${domain}${upstreamPath}`
     const forwardedHeaders = JSON.parse(JSON.stringify(req.headers))
     const workspaceId = normalizeWorkspaceIdHeader(req.get('workspaceId'))
 

package/src/push/mount-push-sse.js

@@ -0,0 +1,91 @@
+import { PushInvalidation } from '@ossy/event-store'
+import { createLogger } from '@ossy/observability'
+
+const log = createLogger('@ossy/platform')
+
+const HEARTBEAT_MS = 25_000
+
+/** @type {Map<string, number>} */
+const activeConnectionsByWorkspace = new Map()
+
+/** @type {Set<{ res: import('express').Response, heartbeat: ReturnType<typeof setInterval>, unsubscribe: () => void, workspaceId: string }>} */
+const activeConnections = new Set()
+
+function trackConnection (workspaceId, delta) {
+  const next = Math.max(0, (activeConnectionsByWorkspace.get(workspaceId) ?? 0) + delta)
+  if (next === 0) {
+    activeConnectionsByWorkspace.delete(workspaceId)
+  } else {
+    activeConnectionsByWorkspace.set(workspaceId, next)
+  }
+  return next
+}
+
+function releaseConnection (connection) {
+  if (!activeConnections.delete(connection)) return
+
+  clearInterval(connection.heartbeat)
+  connection.unsubscribe()
+  const remaining = trackConnection(connection.workspaceId, -1)
+  log.debug('[push] SSE closed', {
+    workspaceId: connection.workspaceId,
+    activeForWorkspace: remaining,
+  })
+}
+
+/**
+ * Tear down all open SSE connections so HTTP server shutdown is not blocked.
+ */
+export function closePushSseConnections () {
+  for (const connection of [...activeConnections]) {
+    releaseConnection(connection)
+    if (!connection.res.writableEnded) {
+      connection.res.end()
+    }
+  }
+}
+
+/**
+ * ADR 0008 §9 — workspace-scoped SSE invalidation bus.
+ *
+ * @param {import('express').Express} app
+ */
+export function mountPushSse (app) {
+  app.get('/events', (req, res) => {
+    const workspaceId = req.workspaceId
+    if (!workspaceId) {
+      res.status(403).json({ error: 'Forbidden' })
+      return
+    }
+
+    res.setHeader('Content-Type', 'text/event-stream; charset=utf-8')
+    res.setHeader('Cache-Control', 'no-cache, no-transform')
+    res.setHeader('Connection', 'keep-alive')
+    res.flushHeaders?.()
+
+    const send = (message) => {
+      res.write(`data: ${JSON.stringify(message)}\n\n`)
+    }
+
+    send({ kind: 'connected', scope: { workspaceId } })
+
+    const unsubscribe = PushInvalidation.subscribe(workspaceId, send)
+    const activeForWorkspace = trackConnection(workspaceId, 1)
+    log.debug('[push] SSE opened', {
+      workspaceId,
+      activeForWorkspace,
+      userId: req.userId,
+    })
+
+    const heartbeat = setInterval(() => {
+      res.write(': heartbeat\n\n')
+    }, HEARTBEAT_MS)
+
+    const connection = { res, heartbeat, unsubscribe, workspaceId }
+    activeConnections.add(connection)
+
+    req.on('close', () => {
+      releaseConnection(connection)
+    })
+  })
+}

package/src/request-diagnostics.js

@@ -0,0 +1,144 @@
+import { createLogger } from '@ossy/observability'
+
+const log = createLogger('@ossy/platform/request-diagnostics')
+
+export class OperationTimeoutError extends Error {
+  constructor (label, timeoutMs) {
+    super(`Operation timed out after ${timeoutMs}ms: ${label}`)
+    this.name = 'OperationTimeoutError'
+    this.label = label
+    this.timeoutMs = timeoutMs
+  }
+}
+
+export function resolveTimeoutMs (envKey, fallback) {
+  const raw = process.env[envKey]
+  const parsed = Number.parseInt(String(raw ?? ''), 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+/**
+ * Reject when `promise` does not settle within `timeoutMs`.
+ * Pass `timeoutMs <= 0` to disable (returns `promise` unchanged).
+ *
+ * When `abortController` is supplied, aborts its signal on timeout so callers
+ * can propagate cancellation into long-running work.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} timeoutMs
+ * @param {string} label
+ * @param {{ abortController?: AbortController }} [options]
+ * @returns {Promise<T>}
+ */
+export function withTimeout (promise, timeoutMs, label, options = {}) {
+  if (!timeoutMs || timeoutMs <= 0) return promise
+
+  const { abortController } = options
+  let timer
+
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const err = new OperationTimeoutError(label, timeoutMs)
+      abortController?.abort(err)
+      reject(err)
+    }, timeoutMs)
+  })
+
+  const abortPromise = abortController
+    ? new Promise((_, reject) => {
+        const { signal } = abortController
+        if (signal.aborted) {
+          reject(signal.reason ?? new OperationTimeoutError(label, timeoutMs))
+          return
+        }
+        signal.addEventListener('abort', () => {
+          reject(signal.reason ?? new OperationTimeoutError(label, timeoutMs))
+        }, { once: true })
+      })
+    : null
+
+  const races = abortPromise ? [promise, timeoutPromise, abortPromise] : [promise, timeoutPromise]
+
+  return Promise.race(races).finally(() => {
+    clearTimeout(timer)
+  })
+}
+
+/**
+ * Reject when a signal aborts (used to race cooperative task handlers).
+ *
+ * @param {AbortSignal} signal
+ * @returns {Promise<never>}
+ */
+export function rejectOnAbort (signal) {
+  return new Promise((_, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason ?? new Error('Operation aborted'))
+      return
+    }
+    signal.addEventListener('abort', () => {
+      reject(signal.reason ?? new Error('Operation aborted'))
+    }, { once: true })
+  })
+}
+
+/**
+ * Log when an operation exceeds the slow threshold.
+ *
+ * @param {string} label
+ * @param {{ log?: import('@ossy/observability').Logger, warnThresholdMs?: number }} [options]
+ */
+export function createTimedOperation (label, options = {}) {
+  const logger = options.log ?? log
+  const warnThresholdMs = options.warnThresholdMs
+    ?? resolveTimeoutMs('OSSY_REQUEST_SLOW_MS', 5000)
+  const start = performance.now()
+
+  return {
+    finish (detail) {
+      const elapsedMs = Math.round(performance.now() - start)
+      const payload = { label, elapsedMs, ...(detail ?? {}) }
+      if (elapsedMs >= warnThresholdMs) {
+        logger.warn('[slow-operation]', payload)
+      } else {
+        logger.debug('[timing]', payload)
+      }
+      return elapsedMs
+    },
+  }
+}
+
+/**
+ * Express middleware — logs requests that exceed OSSY_REQUEST_SLOW_MS (default 5s).
+ *
+ * @param {import('@ossy/observability').Logger} [logger]
+ */
+export function createSlowRequestLogger (logger = log) {
+  const slowThresholdMs = resolveTimeoutMs('OSSY_REQUEST_SLOW_MS', 5000)
+
+  return (req, res, next) => {
+    const start = performance.now()
+    const requestUrl = req.originalUrl || req.url || '/'
+
+    const onFinished = () => {
+      res.removeListener('finish', onFinished)
+      res.removeListener('close', onFinished)
+      const elapsedMs = Math.round(performance.now() - start)
+      if (elapsedMs < slowThresholdMs) return
+
+      logger.warn('[slow-request]', {
+        method: req.method,
+        url: requestUrl,
+        elapsedMs,
+        statusCode: res.statusCode,
+        userId: req.userId,
+        workspaceId: req.workspaceId,
+      })
+    }
+
+    res.on('finish', onFinished)
+    res.on('close', onFinished)
+    next()
+  }
+}

package/src/request-diagnostics.spec.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from '@jest/globals'
+import { OperationTimeoutError, rejectOnAbort, withTimeout } from './request-diagnostics.js'
+
+describe('request-diagnostics', () => {
+  it('withTimeout resolves when promise settles in time', async () => {
+    const result = await withTimeout(Promise.resolve('ok'), 100, 'fast')
+    expect(result).toBe('ok')
+  })
+
+  it('withTimeout rejects with OperationTimeoutError when promise is slow', async () => {
+    await expect(withTimeout(new Promise(() => {}), 20, 'slow-op')).rejects.toMatchObject({
+      label: 'slow-op',
+      timeoutMs: 20,
+    })
+    await expect(withTimeout(new Promise(() => {}), 20, 'slow-op')).rejects.toBeInstanceOf(OperationTimeoutError)
+  })
+
+  it('withTimeout passes through when timeout is disabled', async () => {
+    const result = await withTimeout(Promise.resolve(42), 0, 'disabled')
+    expect(result).toBe(42)
+  })
+
+  it('withTimeout aborts the supplied controller on timeout', async () => {
+    const abortController = new AbortController()
+    let aborted = false
+    abortController.signal.addEventListener('abort', () => { aborted = true })
+
+    await expect(
+      withTimeout(new Promise(() => {}), 20, 'abortable', { abortController }),
+    ).rejects.toBeInstanceOf(OperationTimeoutError)
+    expect(aborted).toBe(true)
+    expect(abortController.signal.aborted).toBe(true)
+  })
+
+  it('rejectOnAbort rejects when signal is already aborted', async () => {
+    const abortController = new AbortController()
+    abortController.abort(new Error('already gone'))
+    await expect(rejectOnAbort(abortController.signal)).rejects.toThrow(/already gone/)
+  })
+})

package/src/resources/index.js

@@ -1,2 +1,3 @@
-export { registerResourceTemplate, getSystemResourceTemplates } from './resource-template.registry.js'
-export { normalizeAndValidateDocumentContent, validateResourceTemplatesForImport, ALLOWED_FIELD_TYPES } from './resource-template.validation.js'
+export { registerSchema, getSystemSchemas } from './schema.registry.js'
+export { getPlatformSchema, initPlatformSchema, createSchemaEngine, schemaForWorkspace } from './schema.service.js'
+export { validateSchemasForImport, ALLOWED_FIELD_TYPES, normalizeFieldType, resolveFieldDef } from './schema.validation.js'