@electric-ax/agents-server 0.4.15 → 0.4.16

package/drizzle/0011_entity_permissions.sql

@@ -0,0 +1,100 @@
+CREATE TABLE "entity_type_permission_grants" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "entity_type" text NOT NULL,
+  "permission" text NOT NULL,
+  "subject_kind" text NOT NULL,
+  "subject_value" text NOT NULL,
+  "created_by" text,
+  "expires_at" timestamp with time zone,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "chk_type_permission_grants_permission" CHECK ("entity_type_permission_grants"."permission" IN ('spawn', 'manage')),
+  CONSTRAINT "chk_type_permission_grants_subject_kind" CHECK ("entity_type_permission_grants"."subject_kind" IN ('principal', 'principal_kind'))
+);
+--> statement-breakpoint
+CREATE TABLE "entity_lineage" (
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "ancestor_url" text NOT NULL,
+  "descendant_url" text NOT NULL,
+  "depth" integer NOT NULL,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "entity_lineage_pkey" PRIMARY KEY ("tenant_id", "ancestor_url", "descendant_url"),
+  CONSTRAINT "chk_entity_lineage_depth" CHECK ("entity_lineage"."depth" >= 0)
+);
+--> statement-breakpoint
+CREATE TABLE "entity_permission_grants" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "entity_url" text NOT NULL,
+  "permission" text NOT NULL,
+  "subject_kind" text NOT NULL,
+  "subject_value" text NOT NULL,
+  "propagation" text DEFAULT 'self' NOT NULL,
+  "copy_to_children" boolean DEFAULT false NOT NULL,
+  "created_by" text,
+  "expires_at" timestamp with time zone,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "chk_entity_permission_grants_permission" CHECK ("entity_permission_grants"."permission" IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')),
+  CONSTRAINT "chk_entity_permission_grants_subject_kind" CHECK ("entity_permission_grants"."subject_kind" IN ('principal', 'principal_kind')),
+  CONSTRAINT "chk_entity_permission_grants_propagation" CHECK ("entity_permission_grants"."propagation" IN ('self', 'descendants'))
+);
+--> statement-breakpoint
+CREATE TABLE "entity_effective_permissions" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "entity_url" text NOT NULL,
+  "source_entity_url" text NOT NULL,
+  "source_grant_id" bigint NOT NULL,
+  "permission" text NOT NULL,
+  "subject_kind" text NOT NULL,
+  "subject_value" text NOT NULL,
+  "expires_at" timestamp with time zone,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "uq_entity_effective_permission" UNIQUE ("tenant_id", "entity_url", "source_grant_id"),
+  CONSTRAINT "chk_entity_effective_permissions_permission" CHECK ("entity_effective_permissions"."permission" IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')),
+  CONSTRAINT "chk_entity_effective_permissions_subject_kind" CHECK ("entity_effective_permissions"."subject_kind" IN ('principal', 'principal_kind'))
+);
+--> statement-breakpoint
+CREATE TABLE "shared_state_links" (
+  "tenant_id" text DEFAULT 'default' NOT NULL,
+  "shared_state_id" text NOT NULL,
+  "owner_entity_url" text NOT NULL,
+  "manifest_key" text NOT NULL,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "shared_state_links_pkey" PRIMARY KEY ("tenant_id", "owner_entity_url", "manifest_key")
+);
+--> statement-breakpoint
+CREATE INDEX "idx_type_permission_grants_lookup" ON "entity_type_permission_grants" USING btree ("tenant_id", "entity_type", "permission", "subject_kind", "subject_value");
+--> statement-breakpoint
+CREATE INDEX "idx_type_permission_grants_expiry" ON "entity_type_permission_grants" USING btree ("tenant_id", "expires_at");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_lineage_descendant" ON "entity_lineage" USING btree ("tenant_id", "descendant_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_permission_grants_entity" ON "entity_permission_grants" USING btree ("tenant_id", "entity_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_permission_grants_subject" ON "entity_permission_grants" USING btree ("tenant_id", "permission", "subject_kind", "subject_value");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_permission_grants_expiry" ON "entity_permission_grants" USING btree ("tenant_id", "expires_at");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_effective_permissions_lookup" ON "entity_effective_permissions" USING btree ("tenant_id", "permission", "subject_kind", "subject_value", "entity_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_effective_permissions_entity" ON "entity_effective_permissions" USING btree ("tenant_id", "entity_url");
+--> statement-breakpoint
+CREATE INDEX "idx_entity_effective_permissions_expiry" ON "entity_effective_permissions" USING btree ("tenant_id", "expires_at");
+--> statement-breakpoint
+CREATE INDEX "idx_shared_state_links_shared_state" ON "shared_state_links" USING btree ("tenant_id", "shared_state_id");
+--> statement-breakpoint
+CREATE INDEX "idx_shared_state_links_owner" ON "shared_state_links" USING btree ("tenant_id", "owner_entity_url");
+--> statement-breakpoint
+-- Pre-permission entity bridge rows do not carry principal attribution. Drop them
+-- so observation bridges are rebuilt with principal_url/principal_kind scoping.
+DELETE FROM "entity_bridges";
+--> statement-breakpoint
+ALTER TABLE "entity_bridges" ADD COLUMN "principal_url" text;
+--> statement-breakpoint
+ALTER TABLE "entity_bridges" ADD COLUMN "principal_kind" text;
+--> statement-breakpoint
+CREATE INDEX "idx_entity_bridges_principal" ON "entity_bridges" USING btree ("tenant_id", "principal_kind", "principal_url");

package/drizzle/0012_horton_user_manage_permission.sql

@@ -0,0 +1,25 @@
+INSERT INTO "entity_type_permission_grants" (
+  "tenant_id",
+  "entity_type",
+  "permission",
+  "subject_kind",
+  "subject_value"
+)
+SELECT
+  "entity_types"."tenant_id",
+  "entity_types"."name",
+  'manage',
+  'principal_kind',
+  'user'
+FROM "entity_types"
+WHERE "entity_types"."name" = 'horton'
+  AND NOT EXISTS (
+    SELECT 1
+    FROM "entity_type_permission_grants"
+    WHERE "entity_type_permission_grants"."tenant_id" = "entity_types"."tenant_id"
+      AND "entity_type_permission_grants"."entity_type" = "entity_types"."name"
+      AND "entity_type_permission_grants"."permission" = 'manage'
+      AND "entity_type_permission_grants"."subject_kind" = 'principal_kind'
+      AND "entity_type_permission_grants"."subject_value" = 'user'
+      AND "entity_type_permission_grants"."expires_at" IS NULL
+  );

package/drizzle/0013_worker_user_manage_permission.sql

@@ -0,0 +1,25 @@
+INSERT INTO "entity_type_permission_grants" (
+  "tenant_id",
+  "entity_type",
+  "permission",
+  "subject_kind",
+  "subject_value"
+)
+SELECT
+  "entity_types"."tenant_id",
+  "entity_types"."name",
+  'manage',
+  'principal_kind',
+  'user'
+FROM "entity_types"
+WHERE "entity_types"."name" = 'worker'
+  AND NOT EXISTS (
+    SELECT 1
+    FROM "entity_type_permission_grants"
+    WHERE "entity_type_permission_grants"."tenant_id" = "entity_types"."tenant_id"
+      AND "entity_type_permission_grants"."entity_type" = "entity_types"."name"
+      AND "entity_type_permission_grants"."permission" = 'manage'
+      AND "entity_type_permission_grants"."subject_kind" = 'principal_kind'
+      AND "entity_type_permission_grants"."subject_value" = 'user'
+      AND "entity_type_permission_grants"."expires_at" IS NULL
+  );

package/drizzle/meta/_journal.json

@@ -78,6 +78,27 @@
       "when": 1779062400000,
       "tag": "0010_sandbox_profiles",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1779050000000,
+      "tag": "0011_entity_permissions",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1780584581000,
+      "tag": "0012_horton_user_manage_permission",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1780588695000,
+      "tag": "0013_worker_user_manage_permission",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -37,8 +37,8 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@durable-streams/client": "^0.2.6",
-    "@durable-streams/server": "^0.3.5",
-    "@durable-streams/state": "^0.2.9",
+    "@durable-streams/server": "^0.3.7",
+    "@durable-streams/state": "^0.3.1",
     "@electric-sql/client": "^1.5.20",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@opentelemetry/api": "^1.9.1",
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.8"
+    "@electric-ax/agents-runtime": "0.3.9"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
@@ -65,9 +65,9 @@
     "tsx": "^4.19.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
-    "@electric-ax/agents": "0.4.12",
-    "@electric-ax/agents-server-conformance-tests": "0.1.10",
-    "@electric-ax/agents-server-ui": "0.4.15"
+    "@electric-ax/agents": "0.4.13",
+    "@electric-ax/agents-server-conformance-tests": "0.1.11",
+    "@electric-ax/agents-server-ui": "0.4.16"
   },
   "files": [
     "dist",

package/src/db/schema.ts

@@ -72,6 +72,197 @@ export const entities = pgTable(
   ]
 )
 
+export const entityTypePermissionGrants = pgTable(
+  `entity_type_permission_grants`,
+  {
+    id: bigserial(`id`, { mode: `number` }).primaryKey(),
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    entityType: text(`entity_type`).notNull(),
+    permission: text(`permission`).notNull(),
+    subjectKind: text(`subject_kind`).notNull(),
+    subjectValue: text(`subject_value`).notNull(),
+    createdBy: text(`created_by`),
+    expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp(`updated_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index(`idx_type_permission_grants_lookup`).on(
+      table.tenantId,
+      table.entityType,
+      table.permission,
+      table.subjectKind,
+      table.subjectValue
+    ),
+    index(`idx_type_permission_grants_expiry`).on(
+      table.tenantId,
+      table.expiresAt
+    ),
+    check(
+      `chk_type_permission_grants_permission`,
+      sql`${table.permission} IN ('spawn', 'manage')`
+    ),
+    check(
+      `chk_type_permission_grants_subject_kind`,
+      sql`${table.subjectKind} IN ('principal', 'principal_kind')`
+    ),
+  ]
+)
+
+export const entityLineage = pgTable(
+  `entity_lineage`,
+  {
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    ancestorUrl: text(`ancestor_url`).notNull(),
+    descendantUrl: text(`descendant_url`).notNull(),
+    depth: integer(`depth`).notNull(),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.tenantId, table.ancestorUrl, table.descendantUrl],
+    }),
+    index(`idx_entity_lineage_descendant`).on(
+      table.tenantId,
+      table.descendantUrl
+    ),
+    check(`chk_entity_lineage_depth`, sql`${table.depth} >= 0`),
+  ]
+)
+
+export const entityPermissionGrants = pgTable(
+  `entity_permission_grants`,
+  {
+    id: bigserial(`id`, { mode: `number` }).primaryKey(),
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    entityUrl: text(`entity_url`).notNull(),
+    permission: text(`permission`).notNull(),
+    subjectKind: text(`subject_kind`).notNull(),
+    subjectValue: text(`subject_value`).notNull(),
+    propagation: text(`propagation`).notNull().default(`self`),
+    copyToChildren: boolean(`copy_to_children`).notNull().default(false),
+    createdBy: text(`created_by`),
+    expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp(`updated_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index(`idx_entity_permission_grants_entity`).on(
+      table.tenantId,
+      table.entityUrl
+    ),
+    index(`idx_entity_permission_grants_subject`).on(
+      table.tenantId,
+      table.permission,
+      table.subjectKind,
+      table.subjectValue
+    ),
+    index(`idx_entity_permission_grants_expiry`).on(
+      table.tenantId,
+      table.expiresAt
+    ),
+    check(
+      `chk_entity_permission_grants_permission`,
+      sql`${table.permission} IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')`
+    ),
+    check(
+      `chk_entity_permission_grants_subject_kind`,
+      sql`${table.subjectKind} IN ('principal', 'principal_kind')`
+    ),
+    check(
+      `chk_entity_permission_grants_propagation`,
+      sql`${table.propagation} IN ('self', 'descendants')`
+    ),
+  ]
+)
+
+export const entityEffectivePermissions = pgTable(
+  `entity_effective_permissions`,
+  {
+    id: bigserial(`id`, { mode: `number` }).primaryKey(),
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    entityUrl: text(`entity_url`).notNull(),
+    sourceEntityUrl: text(`source_entity_url`).notNull(),
+    sourceGrantId: bigint(`source_grant_id`, { mode: `number` }).notNull(),
+    permission: text(`permission`).notNull(),
+    subjectKind: text(`subject_kind`).notNull(),
+    subjectValue: text(`subject_value`).notNull(),
+    expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    unique(`uq_entity_effective_permission`).on(
+      table.tenantId,
+      table.entityUrl,
+      table.sourceGrantId
+    ),
+    index(`idx_entity_effective_permissions_lookup`).on(
+      table.tenantId,
+      table.permission,
+      table.subjectKind,
+      table.subjectValue,
+      table.entityUrl
+    ),
+    index(`idx_entity_effective_permissions_entity`).on(
+      table.tenantId,
+      table.entityUrl
+    ),
+    index(`idx_entity_effective_permissions_expiry`).on(
+      table.tenantId,
+      table.expiresAt
+    ),
+    check(
+      `chk_entity_effective_permissions_permission`,
+      sql`${table.permission} IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')`
+    ),
+    check(
+      `chk_entity_effective_permissions_subject_kind`,
+      sql`${table.subjectKind} IN ('principal', 'principal_kind')`
+    ),
+  ]
+)
+
+export const sharedStateLinks = pgTable(
+  `shared_state_links`,
+  {
+    tenantId: text(`tenant_id`).notNull().default(`default`),
+    sharedStateId: text(`shared_state_id`).notNull(),
+    ownerEntityUrl: text(`owner_entity_url`).notNull(),
+    manifestKey: text(`manifest_key`).notNull(),
+    createdAt: timestamp(`created_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp(`updated_at`, { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    primaryKey({
+      columns: [table.tenantId, table.ownerEntityUrl, table.manifestKey],
+    }),
+    index(`idx_shared_state_links_shared_state`).on(
+      table.tenantId,
+      table.sharedStateId
+    ),
+    index(`idx_shared_state_links_owner`).on(
+      table.tenantId,
+      table.ownerEntityUrl
+    ),
+  ]
+)
+
 export const users = pgTable(
   `users`,
   {
@@ -436,6 +627,8 @@ export const entityBridges = pgTable(
     sourceRef: text(`source_ref`).notNull(),
     tags: jsonb(`tags`).notNull(),
     streamUrl: text(`stream_url`).notNull(),
+    principalUrl: text(`principal_url`),
+    principalKind: text(`principal_kind`),
     shapeHandle: text(`shape_handle`),
     shapeOffset: text(`shape_offset`),
     lastObserverActivityAt: timestamp(`last_observer_activity_at`, {
@@ -453,6 +646,11 @@ export const entityBridges = pgTable(
   (table) => [
     primaryKey({ columns: [table.tenantId, table.sourceRef] }),
     unique(`uq_entity_bridges_stream_url`).on(table.tenantId, table.streamUrl),
+    index(`idx_entity_bridges_principal`).on(
+      table.tenantId,
+      table.principalKind,
+      table.principalUrl
+    ),
   ]
 )
 

package/src/electric-agents-types.ts

@@ -67,6 +67,78 @@ export type RunnerKind = `local` | `cloud-worker` | `sandbox` | `ci` | `server`
 export type RunnerAdminStatus = `enabled` | `disabled`
 export type RunnerLiveness = `online` | `offline`
 
+export type PermissionSubjectKind = `principal` | `principal_kind`
+export type PermissionSubject = {
+  subject_kind: PermissionSubjectKind
+  subject_value: string
+}
+export type EntityPermission =
+  | `read`
+  | `write`
+  | `delete`
+  | `signal`
+  | `fork`
+  | `schedule`
+  | `spawn`
+  | `manage`
+export type EntityTypePermission = `spawn` | `manage`
+export type EntityPermissionPropagation = `self` | `descendants`
+
+export interface EntityPermissionGrant extends PermissionSubject {
+  id: number
+  entity_url: string
+  permission: EntityPermission
+  propagation: EntityPermissionPropagation
+  copy_to_children: boolean
+  created_by?: string
+  expires_at?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface EntityTypePermissionGrant extends PermissionSubject {
+  id: number
+  entity_type: string
+  permission: EntityTypePermission
+  created_by?: string
+  expires_at?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface EntityTypePermissionGrantInput extends PermissionSubject {
+  permission: EntityTypePermission
+  expires_at?: string
+}
+
+export type AuthorizationResource =
+  | { kind: `entity`; entity: ElectricAgentsEntity }
+  | { kind: `entity_type`; entityType: ElectricAgentsEntityType }
+  | { kind: `entity_type_registration`; entityTypeName: string }
+  | {
+      kind: `shared_state`
+      sharedStateId: string
+      linkedEntityUrls: Array<string>
+    }
+
+export type AuthorizationDecision = {
+  decision: `allow` | `deny`
+  expires_at?: string
+}
+
+export type AuthorizeRequest = (input: {
+  tenant: string
+  principal: Principal
+  verb: EntityPermission | EntityTypePermission
+  resource: AuthorizationResource
+  request?: {
+    method: string
+    url: string
+    headers: Record<string, string>
+  }
+  builtInAllowed: boolean
+}) => Promise<AuthorizationDecision> | AuthorizationDecision
+
 const VALID_RUNNER_KINDS = new Set<string>([
   `local`,
   `cloud-worker`,
@@ -356,7 +428,6 @@ export interface ElectricAgentsEntity {
   status: EntityStatus
   streams: {
     main: string
-    error: string
   }
   subscription_id: string
   dispatch_policy?: DispatchPolicy
@@ -385,7 +456,7 @@ export interface PublicElectricAgentsEntity {
   url: string
   type: string
   status: EntityStatus
-  streams: { main: string; error: string }
+  streams: { main: string }
   dispatch_policy?: DispatchPolicy
   tags: Record<string, string>
   spawn_args?: Record<string, unknown>
@@ -443,6 +514,7 @@ export interface RegisterEntityTypeRequest {
   state_schemas?: Record<string, Record<string, unknown>>
   serve_endpoint?: string
   default_dispatch_policy?: DispatchPolicy
+  permission_grants?: Array<EntityTypePermissionGrantInput>
 }
 
 export interface TypedSpawnRequest {
@@ -477,6 +549,8 @@ export interface TypedSpawnRequest {
 
 export interface SendRequest {
   from?: string
+  from_principal?: string
+  from_agent?: string
   payload?: unknown
   key?: string
   type?: string

package/src/entity-bridge-manager.ts

@@ -3,6 +3,7 @@ import {
   assertTags,
   buildTagsIndex,
   getEntitiesStreamPath,
+  hashString,
   normalizeTags,
   sourceRefForTags,
 } from '@electric-ax/agents-runtime'
@@ -13,7 +14,9 @@ import {
 } from '@electric-sql/client'
 import { serverLog } from './utils/log.js'
 import { electricUrlWithPath } from './utils/electric-url.js'
+import { buildReadableEntitiesWhere } from './utils/server-utils.js'
 import { DEFAULT_TENANT_ID } from './tenant.js'
+import { isBuiltInSystemPrincipalUrl } from './principal.js'
 import type { EntityBridgeRow, PostgresRegistry } from './entity-registry.js'
 import type { StreamClient } from './stream-client.js'
 import type {
@@ -30,7 +33,11 @@ import type {
 export interface EntityBridgeCoordinator {
   start(): Promise<void>
   stop(): Promise<void>
-  register(tagsInput: unknown): Promise<{
+  register(
+    tagsInput: unknown,
+    principalUrl: string,
+    principalKind: string
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }>
@@ -115,19 +122,44 @@ function sqlStringLiteral(value: string): string {
 
 function buildTenantTagsWhereClause(
   tenantId: string,
-  tags: EntityTags
+  tags: EntityTags,
+  principalUrl?: string,
+  principalKind?: string,
+  permissionBypass?: boolean
 ): string {
-  return `tenant_id = ${sqlStringLiteral(tenantId)} AND (${buildTagsWhereClause(tags)})`
+  const readableWhere =
+    principalUrl && principalKind
+      ? buildReadableEntitiesWhere({
+          tenantId,
+          principalUrl,
+          principalKind,
+          permissionBypass,
+        })
+      : `tenant_id = ${sqlStringLiteral(tenantId)} AND FALSE`
+  return `${readableWhere} AND (${buildTagsWhereClause(tags)})`
 }
 
 function shapeEntityKey(message: ChangeMessage<EntityShapeRow>): string {
   return message.value.url
 }
 
+function principalScopedSourceRef(
+  tagSourceRef: string,
+  principalUrl: string,
+  principalKind: string
+): string {
+  return `${tagSourceRef}-${hashString(
+    JSON.stringify({ principalKind, principalUrl })
+  )}`
+}
+
 class EntityBridge {
   readonly sourceRef: string
   readonly tags: EntityTags
   readonly streamUrl: string
+  private readonly principalUrl?: string
+  private readonly principalKind?: string
+  private readonly permissionBypass: boolean
 
   private currentMembers = new Map<string, EntityMembershipRow>()
   private producer: IdempotentProducer | null = null
@@ -152,6 +184,9 @@ class EntityBridge {
     this.sourceRef = row.sourceRef
     this.tags = normalizeTags(row.tags)
     this.streamUrl = row.streamUrl
+    this.principalUrl = row.principalUrl
+    this.principalKind = row.principalKind
+    this.permissionBypass = isBuiltInSystemPrincipalUrl(row.principalUrl)
     this.initialShapeHandle = row.shapeHandle
     this.initialShapeOffset = row.shapeOffset
   }
@@ -316,7 +351,13 @@ class EntityBridge {
       url: electricUrlWithPath(this.electricUrl, `/v1/shape`).toString(),
       params: {
         table: `entities`,
-        where: buildTenantTagsWhereClause(this.tenantId, this.tags),
+        where: buildTenantTagsWhereClause(
+          this.tenantId,
+          this.tags,
+          this.principalUrl,
+          this.principalKind,
+          this.permissionBypass
+        ),
         ...(this.electricSecret ? { secret: this.electricSecret } : {}),
         columns: [...ENTITY_SHAPE_COLUMNS],
         replica: `full`,
@@ -564,7 +605,11 @@ export class EntityBridgeManager implements EntityBridgeCoordinator {
     )
   }
 
-  async register(tagsInput: unknown): Promise<{
+  async register(
+    tagsInput: unknown,
+    principalUrl: string,
+    principalKind: string
+  ): Promise<{
     sourceRef: string
     streamUrl: string
   }> {
@@ -573,13 +618,19 @@ export class EntityBridgeManager implements EntityBridgeCoordinator {
     }
 
     const tags = normalizeTags(assertTags(tagsInput))
-    const sourceRef = sourceRefForTags(tags)
+    const sourceRef = principalScopedSourceRef(
+      sourceRefForTags(tags),
+      principalUrl,
+      principalKind
+    )
     const streamUrl = getEntitiesStreamPath(sourceRef)
 
     const row = await this.registry.upsertEntityBridge({
       sourceRef,
       tags,
       streamUrl,
+      principalUrl,
+      principalKind,
     })
     await this.registry.touchEntityBridge(sourceRef)
     await this.ensureBridge(row)