feat(agents-server): add permission enforcement (#4475)

## Motivation

Agents Server needs authorization at every entity access path so tenants
can limit which principals can spawn types and access individual entity
instances. The default model should keep entity instances owner-private
while still allowing common sharing flows through explicit grants,
principal-kind grants, spawn-time inheritance, and Electric-visible
effective permissions.

fixes #4464

## What changed

- Added permission storage for entity type spawn grants, entity instance
grants, effective permissions, lineage, and shared-state links.
- Added owner-default permission checks plus middleware enforcement for
entity routes, spawn, durable streams, attachments, schedules,
event-source subscriptions, tags, inbox edits, and shared-state streams.
- Made new entity type registration available to any authenticated
principal by default. Runtime entity definitions can publish their
default spawn grants during `registerTypes()`.
- Added default built-in `spawn` grants for `principal_kind=user` on
Horton and Worker.
- Materialized descendant and copy-at-spawn entity grants into
`entity_effective_permissions` for point decisions and Electric
visibility.
- Scoped entity list, entity type list, Electric shape predicates, and
`entities(tags)` observation streams by the authenticated principal.
Entity `manage` grants are included in read visibility, and entity-type
`manage` grants are included in spawn/type visibility.
- Added spawn-time initial grants for the new entity. Direct root-spawn
grants are allowed because the caller becomes the owner of the new
entity; broad parented-spawn grants require `manage` on the parent
before they can be delegated.
- Added an optional authorization hook for deployments that need custom
point decisions; webhook decisions are not injected into Electric
predicates and should be materialized into effective rows for shape
visibility.
- Enabled Electric subqueries in
`packages/agents-server/docker-compose.dev.yml` with
`ELECTRIC_FEATURE_FLAGS=allow_subqueries`.

## Permissions model

Principals are still defined outside Agents Server. The server consumes
the authenticated principal from the request context/header and stores
grants against either a concrete principal URL, such as
`/principal/user%3Aalice`, or a principal kind, such as `user`, `agent`,
`service`, or `system`. Native group management is intentionally out of
scope for this version; principal-kind grants cover the common
broad-access cases.

Type grants control type-level actions only. A type-level `spawn` grant
decides whether a principal may create an instance of a registered
entity type; type-level `manage` is used for type mutation and is
treated as a superset for type visibility/spawn checks. Type grants
never grant access to existing entity instances. New type creation is
open to authenticated principals so developers can register new entity
definitions, while mutation of an existing type definition remains
guarded by `manage`.

Entity grants control access to individual entity instances. Instance
access defaults to `created_by` ownership, plus explicit/effective
grants for verbs such as `read`, `write`, `delete`, `signal`, `fork`,
`schedule`, and parent `spawn`. Entity `manage` is treated as a superset
for point checks and visibility.

The permission verbs are intentionally granular. `write` covers content
mutation paths such as send, tags, inbox edits, attachments, and
event-source subscription edits. It does not imply `delete`, `signal`,
`fork`, `schedule`, parent `spawn`, or `manage`; those require their own
grants or `manage`. UI sharing presets like “read-only”, “read/write”,
and “full control” should expand into the appropriate set of granular
grants.

Spawn links the new entity into the permission graph:

- The caller must have a type-level `spawn` grant for the target type.
- If the spawn has a parent, the caller must also have `spawn` on that
parent entity.
- The new entity records `created_by` as the caller principal.
- Parent/child lineage is recorded so descendant grants can be
materialized for current and future descendants.
- Grants marked `copy_to_children` are copied into the child as direct
grants during spawn.
- The spawn body may include initial direct grants for the new entity.
- For parented spawns, broad or propagating initial grants require
`manage` on the parent. This covers `principal_kind` grants, `manage`
grants, `propagation=descendants`, and `copy_to_children=true`.
- Manifest-discovered shared-state links connect shared-state streams
back to the linked entity permissions.

## Key decisions

- Electric predicates use only `IN (SELECT ...)` subqueries with no
correlated outer references.
- Entity instance access defaults to `created_by` ownership plus
explicit/effective grants.
- Type grants are not used for instance visibility or instance access;
entity grants are the source of truth there.
- Workspace-wide sharing is represented as `subject_kind=principal_kind`
and `subject_value=user`. This assumes an Agents Server tenant/service
maps to a workspace boundary, and only workspace members can
authenticate as `user` principals in that tenant.
- Groups are not modeled in this version; deployments that need richer
policy can use the authorization hook and/or materialize decisions into
effective permission rows.
- Public or “anyone with the URL” sharing is a follow-up. The model
leaves room for a later `public`/`link` subject kind, synthetic
anonymous/link principals, or Cloud share-link records that resolve into
an authorization context with matching Electric visibility behavior.
- Expired grants are pruned/deactivated server-side rather than using
`now()` in Electric predicates.
- Pre-permission entity observation bridges are rebuilt after upgrade
because old bridge rows do not include principal attribution.

## Coverage

Added focused coverage for permission service behavior, route
middleware, durable stream access, shared-state authorization, Electric
SQL predicate generation, principal-scoped observation streams, runtime
registration grant payloads, spawn-time grant materialization and
parented-spawn delegation checks, and built-in Horton/Worker spawn
grants.

A local smoke run also registered a linked `/tmp` runtime, spawned an
entity as `user:test`, confirmed `user:other` was denied list/send/view
before grants, then confirmed `user:other` could list/send/view after
explicit `read` and `write` grants using
`ELECTRIC_AGENTS_SERVER_HEADERS` with `Electric-Principal`.

Author: icehaunter

.changeset/agents-server-permissions.md

@@ -0,0 +1,11 @@
+---
+"@electric-ax/agents-server": patch
+"@electric-ax/agents-runtime": patch
+"@electric-ax/agents": patch
+---
+
+Add owner-default agents-server permissions with type-level spawn grants, entity grants, effective permission materialization, principal-scoped entity observation streams, shared-state access links, runtime registration permission grants, and default user spawn grants for built-in Horton and Worker types.
+
+Existing entity observation bridges are rebuilt after upgrade because pre-permission bridge rows do not include principal attribution.
+
+Entity `manage` grants participate in read visibility, entity-type `manage` grants participate in spawn visibility, and broad parented spawn-time grants require `manage` on the parent.

packages/agents-runtime/src/agents-client.ts

@@ -63,9 +63,14 @@ export function createAgentsClient(config: AgentsClientConfig): AgentsClient {
       }
 
       if (source.sourceType === `entities`) {
-        await serverClient.ensureEntitiesMembershipStream(
+        const ensured = await serverClient.ensureEntitiesMembershipStream(
           (source as EntitiesObservationSource).tags
         )
+        source = {
+          ...source,
+          sourceRef: ensured.sourceRef,
+          streamUrl: ensured.streamUrl,
+        }
       }
 
       if (!source.streamUrl || !source.schema) {

packages/agents-runtime/src/create-handler.ts

@@ -510,6 +510,9 @@ export function createRuntimeRouter(
             ? mapSchemas(definition.stateSchemas)
             : {}),
         },
+        ...(definition.permissionGrants && {
+          permission_grants: definition.permissionGrants,
+        }),
       }
 
       const defaultDispatchPolicy = defaultDispatchPolicyForType?.(name)

packages/agents-runtime/src/index.ts

@@ -26,6 +26,7 @@ export type {
   AgentConfig,
   AgentModel,
   EntityDefinition,
+  EntityTypePermissionGrantDefinition,
   EntityActionsFactory,
   EntityActionMap,
   EntityArgs,

packages/agents-runtime/src/process-wake.ts

@@ -1396,7 +1396,7 @@ export async function processWake(
       ): Promise<EntityStreamDBWithActions> => {
         const ssStreamPath = serverClient.getSharedStateStreamPath(ssId)
         if (mode === `create`) {
-          await serverClient.ensureSharedStateStream(ssId)
+          await serverClient.ensureSharedStateStream(ssId, entityUrl)
         }
         const ssStreamUrl = appendPathToUrl(baseUrl, ssStreamPath)
         const ssCollections: Record<string, CollectionDefinition> = {}
@@ -1607,6 +1607,7 @@ export async function processWake(
       source: ObservationSource,
       wake?: Wake
     ): Promise<ObservationHandle> => {
+      let observedSource = source
       // Self-observation
       if (
         source.sourceType === `entity` &&
@@ -1647,24 +1648,44 @@ export async function processWake(
       }
 
       if (source.sourceType === `entities`) {
-        await serverClient.ensureEntitiesMembershipStream(
+        const ensured = await serverClient.ensureEntitiesMembershipStream(
           (source as EntitiesObservationSource).tags
         )
+        const originalEntry = source.toManifestEntry() as Record<
+          string,
+          unknown
+        >
+        observedSource = {
+          ...source,
+          sourceRef: ensured.sourceRef,
+          streamUrl: ensured.streamUrl,
+          toManifestEntry() {
+            return {
+              ...originalEntry,
+              key: `source:entities:${ensured.sourceRef}`,
+              sourceRef: ensured.sourceRef,
+              config: {
+                ...((originalEntry.config as Record<string, unknown>) ?? {}),
+                streamUrl: ensured.streamUrl,
+              },
+            } as unknown as ReturnType<ObservationSource[`toManifestEntry`]>
+          },
+        }
       }
 
       if (effectiveWake) {
-        const observeHandle = await setupCtx.observe(source, {
+        const observeHandle = await setupCtx.observe(observedSource, {
           wake: effectiveWake,
         })
 
         const sourceUrl =
           sourceWakeConfig?.sourceUrl ??
-          (source.sourceType === `entity`
-            ? (source as EntityObservationSource).entityUrl
-            : source.streamUrl)
+          (observedSource.sourceType === `entity`
+            ? (observedSource as EntityObservationSource).entityUrl
+            : observedSource.streamUrl)
         if (!sourceUrl) {
           throw new Error(
-            `[agent-runtime] Cannot register wake for source '${source.sourceType}:${source.sourceRef}' without a source URL`
+            `[agent-runtime] Cannot register wake for source '${observedSource.sourceType}:${observedSource.sourceRef}' without a source URL`
           )
         }
 
@@ -1695,7 +1716,7 @@ export async function processWake(
               ? wake.includeResponse
               : undefined
             : sourceWakeConfig?.includeResponse,
-          manifestKey: source.toManifestEntry().key,
+          manifestKey: observedSource.toManifestEntry().key,
         })
 
         if (source.sourceType === `db`) {
@@ -1706,7 +1727,7 @@ export async function processWake(
         return observeHandle
       }
 
-      const observeHandle = await setupCtx.observe(source)
+      const observeHandle = await setupCtx.observe(observedSource)
       if (source.sourceType === `db`) {
         scheduleSharedStateWiring()
         await waitForSharedStateWiring()

packages/agents-runtime/src/runtime-server-client.ts

@@ -122,7 +122,10 @@ export interface RuntimeServerClient {
   }) => Promise<Uint8Array>
   spawnEntity: (options: SpawnEntityOptions) => Promise<RuntimeEntityInfo>
   getEntity: (entityUrl: string) => Promise<RuntimeEntityInfo>
-  ensureSharedStateStream: (sharedStateId: string) => Promise<string>
+  ensureSharedStateStream: (
+    sharedStateId: string,
+    ownerEntityUrl?: string
+  ) => Promise<string>
   signalEntity: (options: SignalEntityOptions) => Promise<{ txid: number }>
   ensureStream: (streamPath: string, contentType?: string) => Promise<string>
   deleteEntity: (entityUrl: string) => Promise<void>
@@ -447,19 +450,24 @@ export function createRuntimeServerClient(
   }
 
   const ensureSharedStateStream = async (
-    sharedStateId: string
+    sharedStateId: string,
+    ownerEntityUrl?: string
   ): Promise<string> => {
     const streamPath = getSharedStateStreamPath(sharedStateId)
-    return await ensureStream(streamPath, `application/json`)
+    return await ensureStream(streamPath, `application/json`, ownerEntityUrl)
   }
 
   const ensureStream = async (
     streamPath: string,
-    contentType = `application/json`
+    contentType = `application/json`,
+    ownerEntityUrl?: string
   ): Promise<string> => {
     const response = await request(streamPath, {
       method: `PUT`,
-      headers: { 'content-type': contentType },
+      headers: {
+        'content-type': contentType,
+        ...(ownerEntityUrl ? { 'electric-owner-entity': ownerEntityUrl } : {}),
+      },
     })
 
     if (!response.ok && response.status !== 409) {

packages/agents-runtime/src/types.ts

@@ -413,6 +413,13 @@ export interface EntityCreated {
   parent_url?: string
 }
 
+export type EntityTypePermissionGrantDefinition = {
+  subject_kind: `principal` | `principal_kind`
+  subject_value: string
+  permission: `spawn` | `manage`
+  expires_at?: string
+}
+
 export interface PendingSend {
   targetUrl: string
   payload: unknown
@@ -1047,6 +1054,7 @@ export interface EntityDefinition<
   creationSchema?: TCreationSchema
   inboxSchemas?: Record<string, StandardJSONSchemaV1>
   stateSchemas?: Record<string, StandardJSONSchemaV1>
+  permissionGrants?: ReadonlyArray<EntityTypePermissionGrantDefinition>
 
   handler: (
     ctx: HandlerContext<

packages/agents-runtime/test/create-handler.test.ts

@@ -659,6 +659,13 @@ describe(`createRuntimeHandler`, () => {
     defineEntity(`schema-agent`, {
       description: `Schema agent`,
       stateSchemas: { custom: makeStandardSchema({ type: `object` }) },
+      permissionGrants: [
+        {
+          subject_kind: `principal_kind`,
+          subject_value: `user`,
+          permission: `spawn`,
+        },
+      ],
       handler: async () => {},
     })
 
@@ -698,6 +705,13 @@ describe(`createRuntimeHandler`, () => {
           },
         ],
       },
+      permission_grants: [
+        {
+          subject_kind: `principal_kind`,
+          subject_value: `user`,
+          permission: `spawn`,
+        },
+      ],
       state_schemas: expect.objectContaining({
         custom: { type: `object` },
         run: expect.any(Object),

packages/agents-runtime/test/electric-agents-client.test.ts

@@ -93,7 +93,7 @@ describe(`createAgentsClient`, () => {
     })
     expect(mockState.createStreamDB).toHaveBeenCalledWith({
       streamOptions: {
-        url: `http://electric-agents.test${source.streamUrl}`,
+        url: `http://electric-agents.test/_entities/source-1`,
         contentType: `application/json`,
       },
       state: source.schema,
@@ -117,7 +117,7 @@ describe(`createAgentsClient`, () => {
 
     expect(mockState.createStreamDB).toHaveBeenCalledWith({
       streamOptions: {
-        url: `http://electric-agents.test/t/tenant-a/v1${source.streamUrl}`,
+        url: `http://electric-agents.test/t/tenant-a/v1/_entities/source-1`,
         contentType: `application/json`,
       },
       state: source.schema,

packages/agents-runtime/test/runtime-server-client-update-metadata.test.ts

@@ -44,6 +44,26 @@ describe(`runtime-server-client.setTag`, () => {
     )
   })
 
+  it(`ensureSharedStateStream sends the owner entity header`, async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = []
+    const fakeFetch = vi.fn(async (url: string, init?: RequestInit) => {
+      calls.push({ url, init })
+      return new Response(null, { status: 201 })
+    }) as unknown as typeof fetch
+    const client = createRuntimeServerClient({
+      baseUrl: `http://test.example`,
+      fetch: fakeFetch,
+    })
+
+    await expect(
+      client.ensureSharedStateStream(`board-1`, `/task/owner`)
+    ).resolves.toBe(`/_electric/shared-state/board-1`)
+
+    const headers = new Headers(calls[0]!.init?.headers)
+    expect(headers.get(`content-type`)).toBe(`application/json`)
+    expect(headers.get(`electric-owner-entity`)).toBe(`/task/owner`)
+  })
+
   it(`sends POST with bearer token and tag body`, async () => {
     const calls: Array<{ url: string; init?: RequestInit }> = []
     const fakeFetch = vi.fn(async (url: string, init?: RequestInit) => {