@nuxtagentic/integrations 0.0.0-stage → 0.1.0

package/runtime/server/utils/integration-context.ts

@@ -0,0 +1,510 @@
+import { createError, setHeader, type H3Event } from 'h3'
+import { useRuntimeConfig } from '#imports'
+import { useCloudConfigServer } from '#cloudconfig/server'
+import { resolveConfigExport, type InferServerSelect } from '@cloudconfig/core'
+import { compileConfig, createServerClient, type DbProvider } from '@cloudconfig/core/server'
+import {
+  ConnectError,
+  createConnect,
+  resolveActor,
+  type Connect,
+  type ConnectActor,
+} from '@cloudconfig/core/connect'
+import * as configModule from '#cloudconfig/config'
+import type { IntegrationsConfig } from '../../../schema'
+import {
+  getIntegrationDefinition,
+  getIntegrationToolName,
+  isMcpWrite,
+  type IntegrationScope,
+} from '../../shared/catalog'
+import {
+  executeIntegrationAction,
+  listIntegrationActions,
+  type Credentials,
+} from './integration-adapters'
+import {
+  executeGoogleMcpAction,
+  isGoogleMcpEnabled,
+  isGoogleMcpWriteAction,
+  planGoogleMcpAction,
+} from './google-mcp'
+
+export type Binding = InferServerSelect<IntegrationsConfig, 'integrationConnection'>
+export const backendConfig = resolveConfigExport(configModule, '#cloudconfig/config')
+
+/** Who a run acts as. `workspace` runs may only use shared connections. */
+export type RunAs = 'owner' | 'workspace'
+
+export interface IntegrationServiceContext {
+  ownerId: number
+  /** The active organization id as text, or `personal`. */
+  workspace: string
+  env: Record<string, unknown> | undefined
+  database: DbProvider
+  request: Request
+  runAs?: RunAs
+  /** Resolved membership; cached per context. */
+  actor?: ConnectActor | null
+}
+
+export function organizationOf(workspace: string): number | null {
+  const id = Number(workspace)
+  return Number.isSafeInteger(id) && id > 0 ? id : null
+}
+
+/**
+ * The actor runs act as: the owner, inside the workspace, with their current
+ * role. Throws once the owner has left the workspace, so their agents and
+ * automations stop using its connections immediately.
+ */
+export async function actorOf(context: IntegrationServiceContext): Promise<ConnectActor> {
+  if (context.actor === undefined) {
+    const db = await context.database.connect({ env: context.env, request: context.request })
+    context.actor = await resolveActor(compileConfig(backendConfig), db, {
+      userId: context.ownerId,
+      organizationId: organizationOf(context.workspace),
+    })
+  }
+  if (!context.actor) {
+    throw new OwnerLeftError()
+  }
+  return context.actor
+}
+
+/** The run's owner is no longer a member of its workspace. */
+export class OwnerLeftError extends Error {
+  constructor() {
+    super('The owner of this run is no longer a member of the workspace.')
+  }
+}
+
+/** A server client whose access rules see the actor's organization and role. */
+export async function integrationApi(context: IntegrationServiceContext) {
+  const actor = await actorOf(context)
+  return createServerClient(
+    backendConfig as IntegrationsConfig,
+    { env: context.env, request: context.request },
+    {
+      db: context.database,
+      getUser: () => ({
+        id: actor.userId,
+        organization:
+          actor.organizationId === null ? null : { id: actor.organizationId, role: actor.role },
+      }),
+    },
+  )
+}
+
+export async function connectOf(
+  context: Pick<IntegrationServiceContext, 'database' | 'env' | 'request'>,
+): Promise<Connect> {
+  const db = await context.database.connect({ env: context.env, request: context.request })
+  return createConnect(compileConfig(backendConfig), { db, env: context.env })
+}
+
+export async function getIntegrationContext(event: H3Event) {
+  setHeader(event, 'Cache-Control', 'private, no-store')
+  const runtime = useRuntimeConfig(event)
+  const authBase =
+    (runtime.public.cloudconfig as { authBasePath?: string }).authBasePath ?? '/api/auth'
+  const session = await event.$fetch<{
+    user: { id: string; email: string }
+    session: { activeOrganizationId?: string }
+  } | null>(`${authBase}/get-session`, { query: { disableCookieCache: true } })
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: 'Sign in to manage integrations.' })
+  }
+  const env = event.context.cloudflare?.env as Record<string, unknown> | undefined
+  const settings = runtime.cloudconfig as { d1Binding?: string; localDb?: string }
+  const database = await getDatabaseProvider(env, settings)
+  const context: IntegrationServiceContext = {
+    ownerId: Number(session.user.id),
+    workspace: String(session.session.activeOrganizationId ?? 'personal'),
+    env,
+    database,
+    request: new Request('https://integrations.internal'),
+  }
+  const actor = await actorOf(context).catch(() => {
+    throw createError({ statusCode: 403, statusMessage: 'You are not a member of this workspace.' })
+  })
+  return {
+    ...context,
+    actor,
+    api: await useCloudConfigServer<IntegrationsConfig>(event),
+    email: session.user.email,
+    /** Owners and admins manage shared connections. */
+    manager:
+      actor.organizationId !== null &&
+      actor.role.split(',').some((role) => ['owner', 'admin'].includes(role.trim())),
+  }
+}
+
+export async function getDatabaseProvider(
+  env: Record<string, unknown> | undefined,
+  settings: { d1Binding?: string; localDb?: string } = {},
+): Promise<DbProvider> {
+  if (env) {
+    return (await import('@cloudconfig/core/drivers/d1')).d1(settings.d1Binding ?? 'DB')
+  }
+  return (await import('@cloudconfig/core/drivers/better-sqlite3')).sqliteFile(
+    settings.localDb ?? backendConfig.db?.local ?? '.cloudconfig/dev.db',
+  )
+}
+
+/**
+ * Connections a run may use in this workspace: the owner's own, and the
+ * workspace's shared ones — or only the shared ones when it runs as the workspace.
+ */
+export async function listBindings(
+  context: IntegrationServiceContext,
+  filter: { provider?: string; enabledOnly?: boolean } = {},
+): Promise<Binding[]> {
+  const api = await integrationApi(context)
+  const result = await api.integrationConnection.list({
+    pageSize: 100,
+    sortBy: 'id',
+    filters: {
+      type: 'group',
+      logic: 'and',
+      children: [
+        { type: 'condition', field: 'workspace', operator: 'eq', value: context.workspace },
+        ...(filter.provider
+          ? [
+              {
+                type: 'condition' as const,
+                field: 'provider',
+                operator: 'eq' as const,
+                value: filter.provider,
+              },
+            ]
+          : []),
+      ],
+    },
+  })
+  return result.data.filter(
+    (row) =>
+      (!filter.enabledOnly || row.enabled) &&
+      (context.runAs !== 'workspace' || row.scope === 'workspace') &&
+      (row.scope === 'workspace' || row.ownerId === context.ownerId),
+  )
+}
+
+export interface GrantedTool {
+  name: string
+  label: string
+  description: string
+  parameters: Record<string, unknown>
+  provider: string
+  action: string
+  bindingId: number
+  approvalRequired: boolean
+  account: string
+  scope: IntegrationScope
+}
+
+/**
+ * The tools agents may call: each enabled connection's permitted actions, and
+ * for MCP connections the permitted tools the server offers right now.
+ */
+export async function listGrantedTools(context: IntegrationServiceContext): Promise<GrantedTool[]> {
+  const bindings = await listBindings(context, { enabledOnly: true })
+  const seen = new Set<string>()
+  const tools: GrantedTool[] = []
+  for (const binding of bindings) {
+    const definition = getIntegrationDefinition(binding.provider)
+    if (!definition) {
+      continue
+    }
+    // The first connection of an integration keeps the plain tool names.
+    const suffix = seen.has(binding.provider) ? binding.id : undefined
+    seen.add(binding.provider)
+    const permissions = binding.permissions as string[]
+    if (definition.auth.mcp) {
+      if (!binding.connectionId) {
+        continue
+      }
+      const connect = await connectOf(context)
+      const available = await connect
+        .mcp(await actorOf(context), binding.connectionId)
+        .listTools()
+        .catch(() => [])
+      const approvals = binding.approvals as string[]
+      for (const tool of available.filter((entry) => permissions.includes(entry.name))) {
+        tools.push({
+          name: getIntegrationToolName(binding.provider, tool.name, suffix),
+          label: tool.title ?? tool.annotations?.title ?? tool.name,
+          description: tool.description ?? tool.name,
+          parameters: Object.keys(tool.inputSchema).length
+            ? tool.inputSchema
+            : { type: 'object', properties: {} },
+          provider: binding.provider,
+          action: tool.name,
+          bindingId: binding.id,
+          approvalRequired: approvals.includes(tool.name),
+          account: binding.account,
+          scope: binding.scope as IntegrationScope,
+        })
+      }
+      continue
+    }
+    for (const action of listIntegrationActions(binding.provider)) {
+      if (!permissions.includes(action.id)) {
+        continue
+      }
+      tools.push({
+        name: getIntegrationToolName(binding.provider, action.id, suffix),
+        label: action.label,
+        description: suffix ? `${action.label} (${binding.account})` : action.label,
+        parameters: action.parameters,
+        provider: binding.provider,
+        action: action.id,
+        bindingId: binding.id,
+        approvalRequired:
+          !!action.approval ||
+          (isGoogleMcpEnabled(context.env) && isGoogleMcpWriteAction(binding.provider, action.id)),
+        account: binding.account,
+        scope: binding.scope as IntegrationScope,
+      })
+    }
+  }
+  return tools
+}
+
+/** What the adapters need from a connection, read through Connect on every call. */
+export async function credentialsFor(
+  context: IntegrationServiceContext,
+  binding: Binding,
+): Promise<Credentials> {
+  const definition = getIntegrationDefinition(binding.provider)!
+  const settings = Object.fromEntries(
+    Object.entries((binding.settings ?? {}) as Record<string, unknown>).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string',
+    ),
+  )
+  let access
+  try {
+    access = await (await connectOf(context)).access(await actorOf(context), binding.connectionId)
+  } catch (cause) {
+    if (cause instanceof ConnectError && cause.code === 'reauthorize') {
+      throw new Error(`Reconnect ${definition.name} in Integrations: ${cause.message}`)
+    }
+    if (cause instanceof ConnectError && cause.status === 404) {
+      throw new Error(
+        `The ${definition.name} account behind this connection was removed. Connect it again.`,
+      )
+    }
+    throw cause
+  }
+  const credentials: Credentials = { ...settings, ...access.fields }
+  if (access.connection.kind !== 'api_key') {
+    credentials.token = access.accessToken
+  }
+  if (access.tokenType.toLowerCase() === 'bot') {
+    credentials.tokenType = 'Bot'
+  }
+  if (typeof access.metadata.shop === 'string') {
+    credentials.shop = access.metadata.shop
+  }
+  if (
+    binding.provider === 'github' &&
+    access.connection.scope === 'workspace' &&
+    access.metadata.installationId
+  ) {
+    credentials.githubInstallation = '1'
+  }
+  if (binding.provider === 'gads') {
+    const developerToken = String(
+      context.env?.NUXT_GOOGLE_ADS_DEVELOPER_TOKEN ??
+        process.env.NUXT_GOOGLE_ADS_DEVELOPER_TOKEN ??
+        '',
+    )
+    if (developerToken) {
+      credentials.developerToken = developerToken
+    }
+  }
+  return credentials
+}
+
+export interface IntegrationActionRequest {
+  /** Catalog integration id. */
+  provider: string
+  /** Action id, or the MCP tool name. */
+  action: string
+  input: Record<string, unknown>
+  /** A specific connection; defaults to the first one that allows the action. */
+  bindingId?: number
+}
+
+export interface IntegrationActionOptions {
+  /** Set once the owner approved the action, so approval-gated actions run instead of queueing. */
+  approved?: boolean
+  signal?: AbortSignal
+  idempotencyKey?: string
+  /** Stored with a pending approval so the waiting agent or automation can resume. */
+  continuation?: Record<string, unknown>
+}
+
+/**
+ * Runs an integration action as the context's actor, enforcing the
+ * connection's permissions. Actions that need approval are queued and return
+ * `approvalRequired` instead of running.
+ */
+export async function performIntegrationAction(
+  context: IntegrationServiceContext,
+  { provider, action, input, bindingId }: IntegrationActionRequest,
+  options: IntegrationActionOptions = {},
+) {
+  const definition = getIntegrationDefinition(provider)
+  if (!definition) {
+    throw new Error('Choose a supported integration.')
+  }
+  const bindings = await listBindings(context, { provider, enabledOnly: true })
+  const binding = bindingId
+    ? bindings.find((row) => row.id === bindingId)
+    : bindings.find((row) => (row.permissions as string[]).includes(action))
+  if (!binding) {
+    throw new Error(`Connect ${definition.name} in Integrations first.`)
+  }
+  if (!(binding.permissions as string[]).includes(action)) {
+    throw new Error(
+      'This connection does not grant that action. Update its permissions in Integrations.',
+    )
+  }
+  if (definition.auth.mcp) {
+    const needsApproval = (binding.approvals as string[]).includes(action)
+    if (needsApproval && !options.approved) {
+      return queueApproval(context, binding, { action, input, continuation: options.continuation })
+    }
+    const result = await (
+      await connectOf(context)
+    )
+      .mcp(await actorOf(context), binding.connectionId)
+      .callTool(action, input, 60_000)
+    if (result.isError) {
+      throw new Error(
+        `${definition.name} reported an error: ${JSON.stringify(result.content).slice(0, 500)}`,
+      )
+    }
+    return result.structuredContent ?? result.content
+  }
+  const entry = listIntegrationActions(provider).find((item) => item.id === action)
+  if (!entry) {
+    throw new Error('This integration does not support that action.')
+  }
+  const needsApproval =
+    entry.approval || (isGoogleMcpEnabled(context.env) && isGoogleMcpWriteAction(provider, action))
+  if (needsApproval && !options.approved) {
+    return queueApproval(context, binding, { action, input, continuation: options.continuation })
+  }
+  if (isGoogleMcpEnabled(context.env)) {
+    const request = planGoogleMcpAction({ provider, action, input })
+    if (request) {
+      const connect = await connectOf(context)
+      const actor = await actorOf(context)
+      const connection = await connect.get(actor, binding.connectionId)
+      if (connection.kind === 'oauth' && connection.provider === 'google') {
+        return executeGoogleMcpAction({
+          connect,
+          actor,
+          connectionId: binding.connectionId,
+          request,
+          ...(options.signal ? { signal: options.signal } : {}),
+        })
+      }
+    }
+  }
+  const credentials = await credentialsFor(context, binding)
+  return executeIntegrationAction(
+    provider,
+    action,
+    { credentials, input },
+    { signal: options.signal, idempotencyKey: options.idempotencyKey },
+  )
+}
+
+async function queueApproval(
+  context: IntegrationServiceContext,
+  binding: Binding,
+  {
+    action,
+    input,
+    continuation,
+  }: {
+    action: string
+    input: Record<string, unknown>
+    continuation?: IntegrationActionOptions['continuation']
+  },
+) {
+  const approval = await (
+    await integrationApi(context)
+  ).integrationApproval.create({
+    connectionId: binding.id,
+    action,
+    input,
+    ownerId: context.ownerId,
+    continuation: continuation ?? null,
+  })
+  return {
+    approvalRequired: true,
+    approvalId: approval.id,
+    message: 'The owner must approve this action in Integrations.',
+  }
+}
+
+export function toPublicConnection(row: Binding, viewer?: { ownerId: number; manager: boolean }) {
+  const {
+    id,
+    provider,
+    account,
+    label,
+    scope,
+    connectionId,
+    enabled,
+    permissions,
+    approvals,
+    settings,
+    ownerId,
+  } = row
+  const isMine = viewer ? ownerId === viewer.ownerId : false
+  const canManage = !!viewer && (scope === 'user' ? isMine : viewer.manager)
+
+  return {
+    id,
+    provider,
+    account,
+    label,
+    scope: scope as IntegrationScope,
+    connectionId,
+    enabled,
+    permissions: permissions as string[],
+    approvals: approvals as string[],
+    settings: settings as Record<string, string>,
+    mine: isMine,
+    canManage,
+  }
+}
+
+export function isMcpIntegration(provider: string) {
+  return !!getIntegrationDefinition(provider)?.auth.mcp
+}
+
+/** MCP tools that ask for approval by default: anything not marked read-only. */
+export function defaultMcpApprovals(
+  tools: { name: string; annotations?: { readOnlyHint?: boolean } }[],
+) {
+  return tools.filter((tool) => isMcpWrite(tool.annotations)).map((tool) => tool.name)
+}
+
+export function toActionError(cause: unknown) {
+  if (cause && typeof cause === 'object' && 'statusCode' in cause) {
+    return cause
+  }
+  if (cause instanceof ConnectError) {
+    return createError({ statusCode: cause.status, statusMessage: cause.message })
+  }
+  return createError({
+    statusCode: 400,
+    statusMessage: cause instanceof Error ? cause.message : 'Could not complete this action.',
+  })
+}

package/runtime/server/utils/integration-crypto.ts

@@ -0,0 +1,13 @@
+/** Connection credentials are sealed by CloudConfig Connect; only token comparison lives here. */
+export async function tokenMatches(value: string, expected: string) {
+  const digest = (text: string) => crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  const [valueDigest, expectedDigest] = await Promise.all([digest(value), digest(expected)])
+  const actualBytes = new Uint8Array(valueDigest)
+  const expectedBytes = new Uint8Array(expectedDigest)
+  // Compare every byte so timing does not reveal how much of the token matched.
+  let difference = 0
+  for (let index = 0; index < actualBytes.length; index++) {
+    difference |= actualBytes[index]! ^ expectedBytes[index]!
+  }
+  return difference === 0
+}

package/runtime/server/utils/request-body.ts

@@ -0,0 +1,38 @@
+import { createError, getRequestWebStream, type H3Event } from 'h3'
+export async function readCommandBody<T>(event: H3Event, limit = 100000): Promise<T> {
+  const reader = getRequestWebStream(event)?.getReader()
+  if (!reader) {
+    throw createError({ statusCode: 400, statusMessage: 'Send a JSON object as the request body.' })
+  }
+  const decoder = new TextDecoder()
+  const chunks: string[] = []
+  let size = 0
+  while (true) {
+    const { value, done } = await reader.read()
+    if (done) {
+      break
+    }
+    size += value.length
+    if (size > limit) {
+      await reader.cancel()
+      throw createError({
+        statusCode: 413,
+        statusMessage: `Send a request body up to ${Math.round(limit / 1000)} KB.`,
+      })
+    }
+    chunks.push(decoder.decode(value, { stream: true }))
+  }
+  chunks.push(decoder.decode())
+  try {
+    const value = JSON.parse(chunks.join(''))
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return value as T
+    }
+  } catch {
+    /* Format error below. */
+  }
+  throw createError({
+    statusCode: 400,
+    statusMessage: 'Send a valid JSON object as the request body.',
+  })
+}

package/runtime/shared/agent.ts

@@ -0,0 +1,14 @@
+export default {
+  excludedModels: ['integrationConnection', 'integrationApproval'],
+  googleServices: {
+    drive: { label: 'Google Drive', scopes: ['https://www.googleapis.com/auth/drive.file'] },
+    calendar: {
+      label: 'Google Calendar',
+      scopes: [
+        'https://www.googleapis.com/auth/calendar.events',
+        'https://www.googleapis.com/auth/calendar.calendarlist.readonly',
+      ],
+    },
+    gmail: { label: 'Gmail', scopes: ['https://www.googleapis.com/auth/gmail.modify'] },
+  },
+}