@electric-ax/agents-server 0.4.15 → 0.4.17

package/src/routing/entity-types-router.ts

@@ -8,22 +8,27 @@ import { dispatchPolicySchema } from '../dispatch-policy-schema.js'
 import { ElectricAgentsError } from '../entity-manager.js'
 import {
   ErrCodeNotFound,
+  ErrCodeInvalidRequest,
+  ErrCodeUnauthorized,
   ErrCodeServeEndpointNameMismatch,
   ErrCodeServeEndpointUnreachable,
 } from '../electric-agents-types.js'
 import { apiError } from '../electric-agents-http.js'
 import { routeBody, withSchema } from './schema.js'
 import { rewriteLoopbackWebhookUrl } from '../utils/webhook-url.js'
+import { canAccessEntityType, canRegisterEntityType } from '../permissions.js'
 import type {
   ElectricAgentsEntityType,
   RegisterEntityTypeRequest,
+  EntityTypePermissionGrantInput,
 } from '../electric-agents-types.js'
 import type { JsonRouteRequest } from './schema.js'
 import type { RouterType } from 'itty-router'
 import type { TenantContext } from './context.js'
 
-export interface ElectricAgentsEntityTypeRouteRequest
-  extends JsonRouteRequest {}
+export interface ElectricAgentsEntityTypeRouteRequest extends JsonRouteRequest {
+  entityTypeRoute?: { entityType: ElectricAgentsEntityType }
+}
 
 type EntityTypeRouteArgs = [TenantContext]
 type EntityTypeRouteResult = Response | undefined
@@ -40,6 +45,40 @@ type PublicEntityTypeResponse = ElectricAgentsEntityType & {
 
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown())
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema)
+const slashCommandArgumentSchema = Type.Object(
+  {
+    name: Type.String(),
+    type: Type.Union([
+      Type.Literal(`string`),
+      Type.Literal(`number`),
+      Type.Literal(`boolean`),
+    ]),
+    required: Type.Optional(Type.Boolean()),
+    description: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false }
+)
+const slashCommandSchema = Type.Object(
+  {
+    name: Type.String(),
+    description: Type.Optional(Type.String()),
+    arguments: Type.Optional(Type.Array(slashCommandArgumentSchema)),
+  },
+  { additionalProperties: false }
+)
+
+const typePermissionGrantInputSchema = Type.Object(
+  {
+    subject_kind: Type.Union([
+      Type.Literal(`principal`),
+      Type.Literal(`principal_kind`),
+    ]),
+    subject_value: Type.String(),
+    permission: Type.Union([Type.Literal(`spawn`), Type.Literal(`manage`)]),
+    expires_at: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false }
+)
 
 const registerEntityTypeBodySchema = Type.Object(
   {
@@ -48,8 +87,12 @@ const registerEntityTypeBodySchema = Type.Object(
     creation_schema: Type.Optional(jsonObjectSchema),
     inbox_schemas: Type.Optional(schemaMapSchema),
     state_schemas: Type.Optional(schemaMapSchema),
+    slash_commands: Type.Optional(Type.Array(slashCommandSchema)),
     serve_endpoint: Type.Optional(Type.String()),
     default_dispatch_policy: Type.Optional(dispatchPolicySchema),
+    permission_grants: Type.Optional(
+      Type.Array(typePermissionGrantInputSchema)
+    ),
   },
   { additionalProperties: false }
 )
@@ -66,6 +109,7 @@ type RegisterEntityTypeBody = Static<typeof registerEntityTypeBodySchema>
 type AmendEntityTypeSchemasBody = Static<
   typeof amendEntityTypeSchemasBodySchema
 >
+type TypePermissionGrantInput = EntityTypePermissionGrantInput
 
 export const entityTypesRouter: ElectricAgentsEntityTypeRoutes = Router<
   ElectricAgentsEntityTypeRouteRequest,
@@ -79,15 +123,47 @@ entityTypesRouter.get(`/`, listEntityTypes)
 entityTypesRouter.post(
   `/`,
   withSchema(registerEntityTypeBodySchema),
+  withEntityTypeRegistrationPermission,
   registerEntityType
 )
 entityTypesRouter.patch(
   `/:name/schemas`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
   withSchema(amendEntityTypeSchemasBodySchema),
   amendSchemas
 )
-entityTypesRouter.get(`/:name`, getEntityType)
-entityTypesRouter.delete(`/:name`, deleteEntityType)
+entityTypesRouter.get(
+  `/:name`,
+  withExistingEntityType,
+  withEntityTypeSpawnPermission,
+  getEntityType
+)
+entityTypesRouter.delete(
+  `/:name`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
+  deleteEntityType
+)
+entityTypesRouter.get(
+  `/:name/grants`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
+  listTypePermissionGrants
+)
+entityTypesRouter.post(
+  `/:name/grants`,
+  withExistingEntityType,
+  withSchema(typePermissionGrantInputSchema),
+  withEntityTypeManagePermission,
+  createTypePermissionGrant
+)
+entityTypesRouter.delete(
+  `/:name/grants/:grantId`,
+  withExistingEntityType,
+  withEntityTypeManagePermission,
+  deleteTypePermissionGrant
+)
 
 async function registerEntityType(
   request: ElectricAgentsEntityTypeRouteRequest,
@@ -105,6 +181,7 @@ async function registerEntityType(
   }
 
   const entityType = await ctx.entityManager.registerEntityType(normalized)
+  await applyRegistrationPermissionGrants(ctx, entityType.name, normalized)
   return json(toPublicEntityType(entityType), { status: 201 })
 }
 
@@ -113,7 +190,102 @@ async function listEntityTypes(
   ctx: TenantContext
 ): Promise<EntityTypeRouteResult> {
   const entityTypes = await ctx.entityManager.registry.listEntityTypes()
-  return json(entityTypes.map((entityType) => toPublicEntityType(entityType)))
+  const visible: Array<ElectricAgentsEntityType> = []
+  for (const entityType of entityTypes) {
+    if (await canAccessEntityType(ctx, entityType, `spawn`)) {
+      visible.push(entityType)
+    }
+  }
+  return json(visible.map((entityType) => toPublicEntityType(entityType)))
+}
+
+async function withExistingEntityType(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = await ctx.entityManager.registry.getEntityType(
+    request.params.name
+  )
+  if (!entityType) {
+    return apiError(404, ErrCodeNotFound, `Entity type not found`)
+  }
+  request.entityTypeRoute = { entityType }
+  return undefined
+}
+
+async function withEntityTypeManagePermission(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = request.entityTypeRoute?.entityType
+  if (!entityType) {
+    throw new Error(`entity type middleware did not run`)
+  }
+  if (
+    await canAccessEntityType(ctx, entityType, `manage`, request as Request)
+  ) {
+    return undefined
+  }
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to manage ${entityType.name}`
+  )
+}
+
+async function withEntityTypeSpawnPermission(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const entityType = request.entityTypeRoute?.entityType
+  if (!entityType) {
+    throw new Error(`entity type middleware did not run`)
+  }
+  if (await canAccessEntityType(ctx, entityType, `spawn`, request as Request)) {
+    return undefined
+  }
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to spawn ${entityType.name}`
+  )
+}
+
+async function withEntityTypeRegistrationPermission(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const parsed = normalizeEntityTypeRequest(
+    routeBody<RegisterEntityTypeBody>(request)
+  )
+  if (!parsed.name) {
+    return undefined
+  }
+
+  const existing = await ctx.entityManager.registry.getEntityType(parsed.name)
+  if (existing) {
+    request.entityTypeRoute = { entityType: existing }
+    if (
+      await canAccessEntityType(ctx, existing, `manage`, request as Request)
+    ) {
+      return undefined
+    }
+    return apiError(
+      401,
+      ErrCodeUnauthorized,
+      `Principal is not allowed to manage ${existing.name}`
+    )
+  }
+
+  if (await canRegisterEntityType(ctx, parsed, request as Request)) {
+    return undefined
+  }
+
+  return apiError(
+    401,
+    ErrCodeUnauthorized,
+    `Principal is not allowed to register entity types`
+  )
 }
 
 async function discoverServeEndpoint(
@@ -141,10 +313,12 @@ async function discoverServeEndpoint(
     }
 
     manifest.serve_endpoint = parsed.serve_endpoint
+    manifest.permission_grants = parsed.permission_grants
 
     const entityType = await ctx.entityManager.registerEntityType(
       normalizeEntityTypeRequest(manifest)
     )
+    await applyRegistrationPermissionGrants(ctx, entityType.name, manifest)
     return json(toPublicEntityType(entityType), { status: 201 })
   } catch (err) {
     if (err instanceof ElectricAgentsError) {
@@ -161,17 +335,9 @@ async function discoverServeEndpoint(
 }
 
 async function getEntityType(
-  request: ElectricAgentsEntityTypeRouteRequest,
-  ctx: TenantContext
+  request: ElectricAgentsEntityTypeRouteRequest
 ): Promise<EntityTypeRouteResult> {
-  const entityType = await ctx.entityManager.registry.getEntityType(
-    request.params.name
-  )
-  if (!entityType) {
-    return apiError(404, ErrCodeNotFound, `Entity type not found`)
-  }
-
-  return json(toPublicEntityType(entityType))
+  return json(toPublicEntityType(request.entityTypeRoute!.entityType))
 }
 
 async function amendSchemas(
@@ -195,6 +361,90 @@ async function deleteEntityType(
   return status(204)
 }
 
+async function listTypePermissionGrants(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const grants =
+    await ctx.entityManager.registry.listEntityTypePermissionGrants(
+      request.entityTypeRoute!.entityType.name
+    )
+  return json({ grants })
+}
+
+async function createTypePermissionGrant(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const parsed = routeBody<TypePermissionGrantInput>(request)
+  const grant =
+    await ctx.entityManager.registry.createEntityTypePermissionGrant({
+      entityType: request.entityTypeRoute!.entityType.name,
+      permission: parsed.permission,
+      subjectKind: parsed.subject_kind,
+      subjectValue: parsed.subject_value,
+      expiresAt: parseExpiresAt(parsed.expires_at),
+      createdBy: ctx.principal.url,
+    })
+  return json(grant, { status: 201 })
+}
+
+async function deleteTypePermissionGrant(
+  request: ElectricAgentsEntityTypeRouteRequest,
+  ctx: TenantContext
+): Promise<EntityTypeRouteResult> {
+  const deleted =
+    await ctx.entityManager.registry.deleteEntityTypePermissionGrant(
+      request.entityTypeRoute!.entityType.name,
+      parseGrantId(request)
+    )
+  return deleted
+    ? status(204)
+    : apiError(404, ErrCodeNotFound, `Grant not found`)
+}
+
+async function applyRegistrationPermissionGrants(
+  ctx: TenantContext,
+  entityType: string,
+  request: Pick<RegisterEntityTypeRequest, `permission_grants`>
+): Promise<void> {
+  for (const grant of request.permission_grants ?? []) {
+    await ctx.entityManager.registry.ensureEntityTypePermissionGrant({
+      entityType,
+      permission: grant.permission,
+      subjectKind: grant.subject_kind,
+      subjectValue: grant.subject_value,
+      expiresAt: parseExpiresAt(grant.expires_at),
+      createdBy: ctx.principal.url,
+    })
+  }
+}
+
+function parseGrantId(request: ElectricAgentsEntityTypeRouteRequest): number {
+  const grantId = Number.parseInt(String(request.params.grantId), 10)
+  if (!Number.isSafeInteger(grantId) || grantId <= 0) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `Invalid grant id`,
+      400
+    )
+  }
+  return grantId
+}
+
+function parseExpiresAt(value: string | undefined): Date | undefined {
+  if (value === undefined) return undefined
+  const expiresAt = new Date(value)
+  if (Number.isNaN(expiresAt.getTime())) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `Invalid expires_at timestamp`,
+      400
+    )
+  }
+  return expiresAt
+}
+
 function normalizeEntityTypeRequest(
   parsed: RegisterEntityTypeBody | RegisterEntityTypeRequest
 ): RegisterEntityTypeRequest {
@@ -205,6 +455,7 @@ function normalizeEntityTypeRequest(
     creation_schema: parsed.creation_schema,
     inbox_schemas: parsed.inbox_schemas,
     state_schemas: parsed.state_schemas,
+    slash_commands: parsed.slash_commands,
     serve_endpoint: serveEndpoint,
     default_dispatch_policy:
       parsed.default_dispatch_policy ??
@@ -213,6 +464,7 @@ function normalizeEntityTypeRequest(
             targets: [{ type: `webhook`, url: serveEndpoint }],
           } as RegisterEntityTypeRequest[`default_dispatch_policy`])
         : undefined),
+    permission_grants: parsed.permission_grants,
   }
 }
 

package/src/routing/hooks.ts

@@ -85,6 +85,7 @@ export function applyCors(
       `content-type`,
       `authorization`,
       `electric-claim-token`,
+      `electric-owner-entity`,
       ELECTRIC_PRINCIPAL_HEADER,
       `ngrok-skip-browser-warning`,
     ].join(`, `)

package/src/routing/observations-router.ts

@@ -56,7 +56,8 @@ async function ensureEntitiesMembershipStream(
 ): Promise<Response> {
   const parsed = routeBody<EnsureEntitiesMembershipStreamBody>(request)
   const result = await ctx.entityManager.ensureEntitiesMembershipStream(
-    parsed.tags ?? {}
+    parsed.tags ?? {},
+    ctx.principal
   )
   return json(result)
 }

package/src/runtime.ts

@@ -316,6 +316,8 @@ export class ElectricAgentsTenantRuntime {
         payload.entityUrl,
         {
           from: payload.from,
+          from_principal: payload.from_principal,
+          from_agent: payload.from_agent,
           payload: payload.payload,
           key: payload.key ?? `scheduled-task-${taskId}`,
           type: payload.type,
@@ -461,6 +463,7 @@ export class ElectricAgentsTenantRuntime {
       {
         entityUrl: targetUrl,
         from: senderUrl,
+        from_agent: senderUrl,
         payload: value.payload,
         key: `scheduled-${producerId}`,
         type:
@@ -499,6 +502,14 @@ export class ElectricAgentsTenantRuntime {
       manifestKey,
       sourceRef
     )
+
+    const sharedStateId =
+      operation === `delete` ? undefined : this.extractSharedStateId(value)
+    await this.manager.registry.replaceSharedStateLink(
+      ownerEntityUrl,
+      manifestKey,
+      sharedStateId
+    )
   }
 
   private extractEntitiesSourceRef(
@@ -514,6 +525,29 @@ export class ElectricAgentsTenantRuntime {
     return undefined
   }
 
+  private extractSharedStateId(
+    manifest: Record<string, unknown> | undefined
+  ): string | undefined {
+    if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) {
+      return manifest.id
+    }
+
+    if (manifest?.kind !== `source` || manifest.sourceType !== `db`) {
+      return undefined
+    }
+
+    if (typeof manifest.sourceRef === `string`) {
+      return manifest.sourceRef
+    }
+    const config =
+      typeof manifest.config === `object` &&
+      manifest.config !== null &&
+      !Array.isArray(manifest.config)
+        ? (manifest.config as Record<string, unknown>)
+        : undefined
+    return typeof config?.id === `string` ? config.id : undefined
+  }
+
   private async maybeMarkEntityIdleAfterRunFinished(
     entityUrl: string
   ): Promise<void> {

package/src/scheduler.ts

@@ -6,6 +6,8 @@ import type { PgClient } from './db/index.js'
 export interface DelayedSendPayload {
   entityUrl: string
   from?: string
+  from_principal?: string
+  from_agent?: string
   payload: unknown
   key?: string
   type?: string

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 }