@electric-ax/agents-server 0.4.15 → 0.4.16

package/src/index.ts

@@ -43,6 +43,12 @@ export type {
   ElectricAgentsEntity,
   ElectricAgentsEntityRow,
   ElectricAgentsEntityType,
+  EntityPermission,
+  EntityPermissionGrant,
+  EntityPermissionPropagation,
+  EntityTypePermission,
+  EntityTypePermissionGrant,
+  EntityTypePermissionGrantInput,
   EntityStatus,
   EntitySignal,
   PublicElectricAgentsEntity,
@@ -52,6 +58,11 @@ export type {
   SignalRequest,
   SignalResponse,
   TypedSpawnRequest,
+  PermissionSubject,
+  PermissionSubjectKind,
+  AuthorizationDecision,
+  AuthorizationResource,
+  AuthorizeRequest,
 } from './electric-agents-types.js'
 export type {
   EventSourceBucket,

package/src/permissions.ts

@@ -0,0 +1,239 @@
+import { isBuiltInSystemPrincipalUrl } from './principal.js'
+import type {
+  AuthorizeRequest,
+  ElectricAgentsEntity,
+  ElectricAgentsEntityType,
+  EntityPermission,
+  RegisterEntityTypeRequest,
+  EntityTypePermission,
+} from './electric-agents-types.js'
+import type { TenantContext } from './routing/context.js'
+import { serverLog } from './utils/log.js'
+
+const authzDecisionCache = new WeakMap<
+  AuthorizeRequest,
+  Map<string, { decision: `allow` | `deny`; expiresAt: number }>
+>()
+
+export function principalSubject(principal: { url: string; kind: string }): {
+  principalUrl: string
+  principalKind: string
+} {
+  return { principalUrl: principal.url, principalKind: principal.kind }
+}
+
+export function isPermissionBypassPrincipal(ctx: TenantContext): boolean {
+  return isBuiltInSystemPrincipalUrl(ctx.principal.url)
+}
+
+export async function canAccessEntity(
+  ctx: TenantContext,
+  entity: ElectricAgentsEntity,
+  permission: EntityPermission,
+  request?: Request
+): Promise<boolean> {
+  if (isPermissionBypassPrincipal(ctx)) return true
+  await ctx.entityManager.registry.pruneExpiredPermissionGrants?.()
+
+  const builtInAllowed =
+    entity.created_by === ctx.principal.url ||
+    (await ctx.entityManager.registry.hasEntityPermission(
+      entity.url,
+      permission,
+      principalSubject(ctx.principal)
+    ))
+
+  return await applyAuthorizationHook(ctx, {
+    verb: permission,
+    resourceKey: `entity:${entity.url}`,
+    resource: { kind: `entity`, entity },
+    builtInAllowed,
+    request,
+  })
+}
+
+export async function canAccessEntityType(
+  ctx: TenantContext,
+  entityType: ElectricAgentsEntityType,
+  permission: EntityTypePermission,
+  request?: Request
+): Promise<boolean> {
+  if (isPermissionBypassPrincipal(ctx)) return true
+  await ctx.entityManager.registry.pruneExpiredPermissionGrants?.()
+
+  const builtInAllowed =
+    await ctx.entityManager.registry.hasEntityTypePermission(
+      entityType.name,
+      permission,
+      principalSubject(ctx.principal)
+    )
+
+  return await applyAuthorizationHook(ctx, {
+    verb: permission,
+    resourceKey: `entity_type:${entityType.name}`,
+    resource: { kind: `entity_type`, entityType },
+    builtInAllowed,
+    request,
+  })
+}
+
+export async function canRegisterEntityType(
+  ctx: TenantContext,
+  input: Pick<RegisterEntityTypeRequest, `name`>,
+  request?: Request
+): Promise<boolean> {
+  if (isPermissionBypassPrincipal(ctx)) return true
+
+  return await applyAuthorizationHook(ctx, {
+    verb: `manage`,
+    resourceKey: `entity_type_registration:${input.name}`,
+    resource: {
+      kind: `entity_type_registration`,
+      entityTypeName: input.name,
+    },
+    builtInAllowed: true,
+    request,
+  })
+}
+
+export async function canAccessSharedState(
+  ctx: TenantContext,
+  sharedStateId: string,
+  permission: `read` | `write`,
+  request?: Request,
+  ownerEntityUrl?: string
+): Promise<boolean> {
+  if (isPermissionBypassPrincipal(ctx)) return true
+  await ctx.entityManager.registry.pruneExpiredPermissionGrants?.()
+
+  const storedLinkedEntityUrls =
+    await ctx.entityManager.registry.listSharedStateLinkedEntityUrls(
+      sharedStateId
+    )
+  const bootstrapEntityUrls =
+    storedLinkedEntityUrls.length === 0 && ownerEntityUrl
+      ? [ownerEntityUrl]
+      : []
+  const linkedEntityUrls = [
+    ...new Set([...storedLinkedEntityUrls, ...bootstrapEntityUrls]),
+  ]
+  for (const entityUrl of linkedEntityUrls) {
+    const entity = await ctx.entityManager.registry.getEntity(entityUrl)
+    if (!entity) continue
+    if (
+      entity.created_by === ctx.principal.url ||
+      (await ctx.entityManager.registry.hasEntityPermission(
+        entity.url,
+        permission,
+        principalSubject(ctx.principal)
+      ))
+    ) {
+      return await applyAuthorizationHook(ctx, {
+        verb: permission,
+        resourceKey: `shared_state:${sharedStateId}`,
+        resource: {
+          kind: `shared_state`,
+          sharedStateId,
+          linkedEntityUrls,
+        },
+        builtInAllowed: true,
+        request,
+      })
+    }
+  }
+
+  return await applyAuthorizationHook(ctx, {
+    verb: permission,
+    resourceKey: `shared_state:${sharedStateId}`,
+    resource: {
+      kind: `shared_state`,
+      sharedStateId,
+      linkedEntityUrls,
+    },
+    builtInAllowed: false,
+    request,
+  })
+}
+
+async function applyAuthorizationHook(
+  ctx: TenantContext,
+  input: {
+    verb: EntityPermission | EntityTypePermission
+    resourceKey: string
+    resource: Parameters<AuthorizeRequest>[0][`resource`]
+    builtInAllowed: boolean
+    request?: Request
+  }
+): Promise<boolean> {
+  const hook = ctx.authorizeRequest
+  if (!hook) return input.builtInAllowed
+
+  const cacheKey = [
+    ctx.service,
+    ctx.principal.url,
+    input.verb,
+    input.resourceKey,
+  ].join(`|`)
+  const cached = getCachedDecision(hook, cacheKey)
+  if (cached) return cached.decision === `allow`
+
+  let decision: Awaited<ReturnType<AuthorizeRequest>>
+  try {
+    decision = await hook({
+      tenant: ctx.service,
+      principal: ctx.principal,
+      verb: input.verb,
+      resource: input.resource,
+      request: input.request ? requestMetadata(input.request) : undefined,
+      builtInAllowed: input.builtInAllowed,
+    })
+  } catch (error) {
+    serverLog.warn(`[agent-server] authorization hook failed:`, error)
+    return false
+  }
+
+  cacheDecision(hook, cacheKey, decision)
+  return decision.decision === `allow`
+}
+
+function getCachedDecision(
+  hook: AuthorizeRequest,
+  cacheKey: string
+): { decision: `allow` | `deny` } | null {
+  const cache = authzDecisionCache.get(hook)
+  const entry = cache?.get(cacheKey)
+  if (!entry) return null
+  if (entry.expiresAt <= Date.now()) {
+    cache?.delete(cacheKey)
+    return null
+  }
+  return { decision: entry.decision }
+}
+
+function cacheDecision(
+  hook: AuthorizeRequest,
+  cacheKey: string,
+  decision: Awaited<ReturnType<AuthorizeRequest>>
+): void {
+  if (!decision.expires_at) return
+  const expiresAt = Date.parse(decision.expires_at)
+  if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) return
+  let cache = authzDecisionCache.get(hook)
+  if (!cache) {
+    cache = new Map()
+    authzDecisionCache.set(hook, cache)
+  }
+  cache.set(cacheKey, { decision: decision.decision, expiresAt })
+}
+
+function requestMetadata(request: Request): {
+  method: string
+  url: string
+  headers: Record<string, string>
+} {
+  const headers: Record<string, string> = {}
+  request.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+  return { method: request.method, url: request.url, headers }
+}

package/src/routing/context.ts

@@ -12,6 +12,7 @@ import type { DurableStreamsRoutingAdapter } from './durable-streams-routing-ada
 import type { Principal } from '../principal.js'
 import type { DurableStreamsBearerProvider } from '../stream-client.js'
 import type { WebhookSigner } from '../webhook-signing.js'
+import type { AuthorizeRequest } from '../electric-agents-types.js'
 
 export interface EventSourceCatalog {
   listEventSources: () =>
@@ -55,5 +56,6 @@ export interface TenantContext {
   entityBridgeManager: EntityBridgeCoordinator
   eventSources?: EventSourceCatalog
   ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
+  authorizeRequest?: AuthorizeRequest
   isShuttingDown: () => boolean
 }

package/src/routing/durable-streams-router.ts

@@ -6,8 +6,16 @@ import { appendPathToUrl } from '@electric-ax/agents-runtime'
 import { Type, type Static } from '@sinclair/typebox'
 import { and, eq } from 'drizzle-orm'
 import { Router } from 'itty-router'
-import { readRequestBody, responseHeaders } from '../electric-agents-http.js'
+import {
+  apiError,
+  readRequestBody,
+  responseHeaders,
+} from '../electric-agents-http.js'
 import { subscriptionWebhooks } from '../db/schema.js'
+import {
+  ErrCodeNotFound,
+  ErrCodeUnauthorized,
+} from '../electric-agents-types.js'
 import {
   createStreamAppendRouteRequest,
   electricAgentsStreamAppendRouter,
@@ -15,6 +23,7 @@ import {
 import { validateBody } from './schema.js'
 import { rewriteLoopbackWebhookUrl } from '../utils/webhook-url.js'
 import { forwardFetchRequest } from '../utils/server-utils.js'
+import { canAccessEntity, canAccessSharedState } from '../permissions.js'
 import {
   getDefaultWebhookSigner,
   webhookSigningMetadata,
@@ -48,6 +57,8 @@ const subscriptionControlActions = [
   `release`,
 ] as const
 
+const SHARED_STATE_OWNER_ENTITY_HEADER = `electric-owner-entity`
+
 export type DurableStreamsRoutes = RouterType<
   IRequest,
   [TenantContext],
@@ -583,6 +594,8 @@ async function streamAppend(
   request: IRequest,
   ctx: TenantContext
 ): Promise<Response | undefined> {
+  const auth = await authorizeDurableStreamAccess(request, ctx)
+  if (auth) return auth
   return await electricAgentsStreamAppendRouter.fetch(
     createStreamAppendRouteRequest(request as Request),
     ctx.runtime,
@@ -608,10 +621,9 @@ async function proxyPassThrough(
   request: IRequest,
   ctx: TenantContext
 ): Promise<Response> {
+  const auth = await authorizeDurableStreamAccess(request, ctx)
+  if (auth) return auth
   const streamPath = new URL(request.url).pathname
-  if (ctx.entityManager?.isAttachmentStreamPath(streamPath)) {
-    return new Response(null, { status: 404 })
-  }
   const upstream = await forwardToDurableStreams(ctx, request)
   const method = request.method.toUpperCase()
   const endTrackedRead =
@@ -627,3 +639,112 @@ async function proxyPassThrough(
     await endTrackedRead?.()
   }
 }
+
+async function authorizeDurableStreamAccess(
+  request: IRequest,
+  ctx: TenantContext
+): Promise<Response | undefined> {
+  const method = request.method.toUpperCase()
+  const streamPath = new URL(request.url).pathname
+
+  if (method === `GET` || method === `HEAD`) {
+    const registry = ctx.entityManager?.registry
+    const entity = registry?.getEntityByStream
+      ? await registry.getEntityByStream(streamPath)
+      : null
+    if (entity) {
+      if (await canAccessEntity(ctx, entity, `read`, request as Request)) {
+        return undefined
+      }
+      return apiError(
+        401,
+        ErrCodeUnauthorized,
+        `Principal is not allowed to read ${entity.url}`
+      )
+    }
+
+    const attachmentEntityUrl = entityUrlFromAttachmentStreamPath(streamPath)
+    if (attachmentEntityUrl) {
+      const attachmentEntity = registry?.getEntity
+        ? await registry.getEntity(attachmentEntityUrl)
+        : null
+      if (!attachmentEntity) {
+        return apiError(404, ErrCodeNotFound, `Entity not found`)
+      }
+      if (
+        await canAccessEntity(ctx, attachmentEntity, `read`, request as Request)
+      ) {
+        return undefined
+      }
+      return apiError(
+        401,
+        ErrCodeUnauthorized,
+        `Principal is not allowed to read ${attachmentEntity.url}`
+      )
+    }
+  }
+
+  const sharedStateId = sharedStateIdFromPath(streamPath)
+  if (!sharedStateId) {
+    // Durable Streams also hosts non-Agents utility streams. Entity streams,
+    // attachment streams, and shared-state streams are guarded above; paths that
+    // do not match those resource classes are intentionally passed through.
+    return undefined
+  }
+
+  if (method === `GET` || method === `HEAD`) {
+    if (
+      await canAccessSharedState(ctx, sharedStateId, `read`, request as Request)
+    ) {
+      return undefined
+    }
+    return apiError(
+      401,
+      ErrCodeUnauthorized,
+      `Principal is not allowed to read shared state`
+    )
+  }
+
+  if (method === `PUT` || method === `POST`) {
+    const ownerEntityUrl =
+      request.headers.get(SHARED_STATE_OWNER_ENTITY_HEADER)?.trim() || undefined
+    if (
+      await canAccessSharedState(
+        ctx,
+        sharedStateId,
+        `write`,
+        request as Request,
+        ownerEntityUrl
+      )
+    ) {
+      return undefined
+    }
+    return apiError(
+      401,
+      ErrCodeUnauthorized,
+      `Principal is not allowed to write shared state`
+    )
+  }
+
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to access shared state`
+  )
+}
+
+function entityUrlFromAttachmentStreamPath(path: string): string | null {
+  const match = path.match(/^\/([^/]+)\/([^/]+)\/attachments\/[^/]+$/)
+  if (!match) return null
+  return `/${match[1]}/${match[2]}`
+}
+
+function sharedStateIdFromPath(path: string): string | null {
+  const match = path.match(/^\/_electric\/shared-state\/([^/]+)$/)
+  if (!match) return null
+  try {
+    return decodeURIComponent(match[1]!)
+  } catch {
+    return match[1]!
+  }
+}

package/src/routing/electric-proxy-router.ts

@@ -5,6 +5,7 @@
 
 import { Router } from 'itty-router'
 import { apiError, responseHeaders } from '../electric-agents-http.js'
+import { isPermissionBypassPrincipal } from '../permissions.js'
 import { buildElectricProxyTarget } from '../utils/server-utils.js'
 import type { IRequest, RouterType } from 'itty-router'
 import type { TenantContext } from './context.js'
@@ -33,12 +34,15 @@ async function proxyElectric(
     return apiError(500, `ELECTRIC_PROXY_FAILED`, `Electric URL not configured`)
   }
 
+  await ctx.entityManager.registry.pruneExpiredPermissionGrants?.()
   const target = buildElectricProxyTarget({
     incomingUrl: new URL(request.url),
     electricUrl: ctx.electricUrl,
     electricSecret: ctx.electricSecret,
     tenantId: ctx.service,
     principalUrl: ctx.principal.url,
+    principalKind: ctx.principal.kind,
+    permissionBypass: isPermissionBypassPrincipal(ctx),
   })
   const headers = new Headers(request.headers)
   headers.delete(`host`)