@electric-ax/agents-server 0.4.14 → 0.4.16

package/src/server.ts

@@ -16,6 +16,7 @@ import { apiError } from './electric-agents-http.js'
 import {
   ErrCodeInvalidRequest,
   ErrCodeUnauthorized,
+  type AuthorizeRequest,
 } from './electric-agents-types.js'
 import { ElectricAgentsError } from './entity-manager.js'
 import { serverLog } from './utils/log.js'
@@ -67,6 +68,7 @@ export interface ElectricAgentsServerOptions {
   authenticateRequest?: (
     request: Request
   ) => Promise<Principal | null> | Principal | null
+  authorizeRequest?: AuthorizeRequest
   allowDevPrincipalFallback?: boolean
   eventSources?: EventSourceCatalog
   ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
@@ -453,6 +455,9 @@ export class ElectricAgentsServer {
               this.options.ensureEventSourceWakeSource,
           }
         : {}),
+      ...(this.options.authorizeRequest
+        ? { authorizeRequest: this.options.authorizeRequest }
+        : {}),
       isShuttingDown: () => this.shuttingDown,
       mockAgent: this.mockAgentBootstrap
         ? { runtime: this.mockAgentBootstrap.runtime }

package/src/stream-client.ts

@@ -4,6 +4,7 @@ import {
   FetchError,
   IdempotentProducer,
 } from '@durable-streams/client'
+import type { EventPointer } from '@electric-ax/agents-runtime'
 import { ErrCodeNotFound } from './electric-agents-types.js'
 import { ATTR, injectTraceHeaders, withSpan } from './tracing.js'
 import type { HeadersRecord, MaybePromise } from '@durable-streams/client'
@@ -242,7 +243,11 @@ export class StreamClient {
     })
   }
 
-  async fork(path: string, sourcePath: string): Promise<void> {
+  async fork(
+    path: string,
+    sourcePath: string,
+    opts?: { forkPointer?: EventPointer }
+  ): Promise<void> {
     return await withSpan(`stream.fork`, async (span) => {
       span.setAttributes({
         [ATTR.STREAM_PATH]: path,
@@ -252,6 +257,17 @@ export class StreamClient {
         'content-type': `application/json`,
         'Stream-Forked-From': new URL(this.streamUrl(sourcePath)).pathname,
       }
+      if (opts?.forkPointer) {
+        // The durable-streams server returns 400 if Stream-Fork-Sub-Offset
+        // > 0 without an accompanying Stream-Fork-Offset. When our
+        // pointer's offset is `null` (anchor at stream start), send the
+        // explicit zero-offset string to satisfy that constraint.
+        const ZERO_OFFSET = `0000000000000000_0000000000000000`
+        headers[`Stream-Fork-Offset`] = opts.forkPointer.offset ?? ZERO_OFFSET
+        if (opts.forkPointer.subOffset > 0) {
+          headers[`Stream-Fork-Sub-Offset`] = String(opts.forkPointer.subOffset)
+        }
+      }
       injectTraceHeaders(headers)
 
       const response = await fetch(this.streamUrl(path), {

package/src/utils/server-utils.ts

@@ -96,6 +96,8 @@ export function buildElectricProxyTarget(options: {
   electricSecret?: string
   tenantId: string
   principalUrl?: string
+  principalKind?: string
+  permissionBypass?: boolean
 }): URL {
   const targetPath = options.incomingUrl.pathname.replace(
     `/_electric/electric`,
@@ -119,23 +121,59 @@ export function buildElectricProxyTarget(options: {
   if (table === `entities`) {
     target.searchParams.set(
       `columns`,
-      `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`
+      `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","sandbox","parent","created_by","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`
+    )
+    applyShapeWhere(
+      target,
+      buildReadableEntitiesWhere({
+        tenantId: options.tenantId,
+        principalUrl: options.principalUrl ?? ``,
+        principalKind: options.principalKind ?? ``,
+        permissionBypass: options.permissionBypass,
+      })
     )
-    applyTenantShapeWhere(target, options.tenantId)
   } else if (table === `entity_types`) {
     target.searchParams.set(
       `columns`,
       `"tenant_id","name","description","creation_schema","inbox_schemas","state_schemas","serve_endpoint","default_dispatch_policy","revision","created_at","updated_at"`
     )
-    applyTenantShapeWhere(target, options.tenantId)
+    applyShapeWhere(
+      target,
+      buildSpawnableEntityTypesWhere({
+        tenantId: options.tenantId,
+        principalUrl: options.principalUrl ?? ``,
+        principalKind: options.principalKind ?? ``,
+        permissionBypass: options.permissionBypass,
+      })
+    )
   } else if (table === `runners`) {
     target.searchParams.set(
       `columns`,
-      `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","created_at","updated_at"`
+      `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","sandbox_profiles","created_at","updated_at"`
     )
     applyTenantShapeWhere(target, options.tenantId, [
       `owner_principal = ${sqlStringLiteral(options.principalUrl ?? ``)}`,
     ])
+  } else if (table === `users`) {
+    target.searchParams.set(
+      `columns`,
+      `"tenant_id","id","display_name","email","avatar_url","created_at","updated_at"`
+    )
+    applyTenantShapeWhere(target, options.tenantId)
+  } else if (table === `entity_effective_permissions`) {
+    target.searchParams.set(
+      `columns`,
+      `"tenant_id","id","entity_url","source_entity_url","source_grant_id","permission","subject_kind","subject_value","expires_at","created_at"`
+    )
+    applyShapeWhere(
+      target,
+      buildCurrentPrincipalEntityEffectivePermissionsWhere({
+        tenantId: options.tenantId,
+        principalUrl: options.principalUrl ?? ``,
+        principalKind: options.principalKind ?? ``,
+        permissionBypass: options.permissionBypass,
+      })
+    )
   } else if (table === `runner_runtime_diagnostics`) {
     target.searchParams.set(
       `columns`,
@@ -149,24 +187,154 @@ export function buildElectricProxyTarget(options: {
       `columns`,
       `"tenant_id","entity_url","pending_source_streams","pending_reason","pending_since","outstanding_wake_id","outstanding_wake_target","outstanding_wake_created_at","active_consumer_id","active_runner_id","active_epoch","active_claimed_at","active_lease_expires_at","last_wake_id","last_claimed_at","last_released_at","last_completed_at","last_error","updated_at"`
     )
-    applyTenantShapeWhere(target, options.tenantId)
+    applyShapeWhere(
+      target,
+      buildReadableEntityUrlWhere({
+        tenantId: options.tenantId,
+        principalUrl: options.principalUrl ?? ``,
+        principalKind: options.principalKind ?? ``,
+        permissionBypass: options.permissionBypass,
+      })
+    )
   } else if (table === `wake_notifications`) {
     target.searchParams.set(
       `columns`,
       `"tenant_id","wake_id","entity_url","target_type","target_runner_id","target_webhook_url","target_worker_pool_id","runner_wake_stream","runner_wake_stream_offset","notification_public","delivery_status","claim_status","created_at","delivered_at","claimed_at","resolved_at"`
     )
-    applyTenantShapeWhere(target, options.tenantId)
+    applyShapeWhere(
+      target,
+      buildReadableEntityUrlWhere({
+        tenantId: options.tenantId,
+        principalUrl: options.principalUrl ?? ``,
+        principalKind: options.principalKind ?? ``,
+        permissionBypass: options.permissionBypass,
+      })
+    )
   } else if (table === `consumer_claims`) {
     target.searchParams.set(
       `columns`,
       `"tenant_id","consumer_id","epoch","wake_id","entity_url","stream_path","runner_id","status","claimed_at","last_heartbeat_at","lease_expires_at","released_at","acked_streams","updated_at"`
     )
-    applyTenantShapeWhere(target, options.tenantId)
+    applyShapeWhere(
+      target,
+      buildReadableEntityUrlWhere({
+        tenantId: options.tenantId,
+        principalUrl: options.principalUrl ?? ``,
+        principalKind: options.principalKind ?? ``,
+        permissionBypass: options.permissionBypass,
+      })
+    )
   }
 
   return target
 }
 
+export function buildReadableEntitiesWhere(options: {
+  tenantId: string
+  principalUrl: string
+  principalKind: string
+  permissionBypass?: boolean
+}): string {
+  const tenant = sqlStringLiteral(options.tenantId)
+  if (options.permissionBypass) {
+    return `tenant_id = ${tenant}`
+  }
+  const principalUrl = sqlStringLiteral(options.principalUrl)
+  const principalKind = sqlStringLiteral(options.principalKind)
+  return [
+    `tenant_id = ${tenant}`,
+    `AND (`,
+    `  created_by = ${principalUrl}`,
+    `  OR url IN (`,
+    `    SELECT entity_url`,
+    `    FROM entity_effective_permissions`,
+    `    WHERE tenant_id = ${tenant}`,
+    `      AND permission IN ('read', 'manage')`,
+    `      AND (`,
+    `        (subject_kind = 'principal' AND subject_value = ${principalUrl})`,
+    `        OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+    `      )`,
+    `  )`,
+    `)`,
+  ].join(`\n`)
+}
+
+export function buildReadableEntityUrlWhere(options: {
+  tenantId: string
+  principalUrl: string
+  principalKind: string
+  permissionBypass?: boolean
+}): string {
+  const tenant = sqlStringLiteral(options.tenantId)
+  if (options.permissionBypass) {
+    return `tenant_id = ${tenant}`
+  }
+  return [
+    `tenant_id = ${tenant}`,
+    `AND entity_url IN (`,
+    `  SELECT url`,
+    `  FROM entities`,
+    `  WHERE ${indentWhere(
+      buildReadableEntitiesWhere(options),
+      `    `
+    ).trimStart()}`,
+    `)`,
+  ].join(`\n`)
+}
+
+export function buildCurrentPrincipalEntityEffectivePermissionsWhere(options: {
+  tenantId: string
+  principalUrl: string
+  principalKind: string
+  permissionBypass?: boolean
+}): string {
+  const tenant = sqlStringLiteral(options.tenantId)
+  if (options.permissionBypass) {
+    return `tenant_id = ${tenant}`
+  }
+  const principalUrl = sqlStringLiteral(options.principalUrl)
+  const principalKind = sqlStringLiteral(options.principalKind)
+  return [
+    `tenant_id = ${tenant}`,
+    `AND (`,
+    `  (subject_kind = 'principal' AND subject_value = ${principalUrl})`,
+    `  OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+    `)`,
+    `AND entity_url IN (`,
+    `  SELECT url`,
+    `  FROM entities`,
+    `  WHERE ${buildReadableEntitiesWhere(options)}`,
+    `)`,
+  ].join(`\n`)
+}
+
+export function buildSpawnableEntityTypesWhere(options: {
+  tenantId: string
+  principalUrl: string
+  principalKind: string
+  permissionBypass?: boolean
+}): string {
+  const tenant = sqlStringLiteral(options.tenantId)
+  if (options.permissionBypass) {
+    return `tenant_id = ${tenant}`
+  }
+  const principalUrl = sqlStringLiteral(options.principalUrl)
+  const principalKind = sqlStringLiteral(options.principalKind)
+  return [
+    `tenant_id = ${tenant}`,
+    `AND name IN (`,
+    `  SELECT entity_type`,
+    `  FROM entity_type_permission_grants`,
+    `  WHERE tenant_id = ${tenant}`,
+    `    AND permission IN ('spawn', 'manage')`,
+    `    AND (`,
+    `      (subject_kind = 'principal' AND subject_value = ${principalUrl})`,
+    `      OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+    `    )`,
+    `)`,
+  ].join(`\n`)
+}
+
 export async function forwardFetchRequest(options: {
   request: {
     method: string
@@ -248,17 +416,29 @@ function applyTenantShapeWhere(
   tenantId: string,
   extraConditions: Array<string> = []
 ): void {
-  const tenantWhere = [
-    `tenant_id = ${sqlStringLiteral(tenantId)}`,
-    ...extraConditions,
-  ].join(` AND `)
+  applyShapeWhere(
+    target,
+    [`tenant_id = ${sqlStringLiteral(tenantId)}`, ...extraConditions].join(
+      ` AND `
+    )
+  )
+}
+
+function applyShapeWhere(target: URL, enforcedWhere: string): void {
   const existingWhere = target.searchParams.get(`where`)
   target.searchParams.set(
     `where`,
-    existingWhere ? `${tenantWhere} AND (${existingWhere})` : tenantWhere
+    existingWhere ? `${enforcedWhere} AND (${existingWhere})` : enforcedWhere
   )
 }
 
 function sqlStringLiteral(value: string): string {
   return `'${value.replace(/'/g, `''`)}'`
 }
+
+function indentWhere(where: string, prefix: string): string {
+  return where
+    .split(`\n`)
+    .map((line) => `${prefix}${line}`)
+    .join(`\n`)
+}

package/src/wake-registry.ts

@@ -41,6 +41,12 @@ export interface WakeEvalResult {
       collection: string
       kind: `insert` | `update` | `delete`
       key: string
+      from?: string
+      from_principal?: string
+      from_agent?: string
+      payload?: unknown
+      timestamp?: string
+      message_type?: string
     }>
   }
   runFinishedStatus?: `completed` | `failed`
@@ -885,11 +891,7 @@ export class WakeRegistry {
     reg: WakeRegistration,
     event: Record<string, unknown>
   ): {
-    change: {
-      collection: string
-      kind: `insert` | `update` | `delete`
-      key: string
-    }
+    change: WakeEvalResult[`wakeMessage`][`changes`][number]
     runFinishedStatus?: `completed` | `failed`
   } | null {
     if (reg.condition === `runFinished`) {
@@ -935,12 +937,29 @@ export class WakeRegistry {
       return null
     }
 
-    return {
-      change: {
-        collection: eventType,
-        kind,
-        key: (event.key as string) || ``,
-      },
+    const change: WakeEvalResult[`wakeMessage`][`changes`][number] = {
+      collection: eventType,
+      kind,
+      key: (event.key as string) || ``,
     }
+
+    if (eventType === `inbox`) {
+      const value = event.value as Record<string, unknown> | undefined
+      if (typeof value?.from === `string`) change.from = value.from
+      if (typeof value?.from_principal === `string`) {
+        change.from_principal = value.from_principal
+      }
+      if (typeof value?.from_agent === `string`) {
+        change.from_agent = value.from_agent
+      }
+      if (`payload` in (value ?? {})) change.payload = value?.payload
+      if (typeof value?.timestamp === `string`)
+        change.timestamp = value.timestamp
+      if (typeof value?.message_type === `string`) {
+        change.message_type = value.message_type
+      }
+    }
+
+    return { change }
   }
 }