@electric-ax/agents-server 0.4.15 → 0.4.16

package/dist/entrypoint.js

@@ -4,13 +4,13 @@ import { DurableStreamTestServer } from "@durable-streams/server";
 import { createServer } from "node:http";
 import { createServerAdapter } from "@whatwg-node/server";
 import { Agent } from "undici";
-import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, createEntityRegistry, createRuntimeHandler, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, createEntityRegistry, createRuntimeHandler, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import fs, { existsSync } from "node:fs";
 import path, { dirname, resolve } from "node:path";
 import { drizzle } from "drizzle-orm/postgres-js";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
 import postgres from "postgres";
-import { and, desc, eq, lt, ne, sql } from "drizzle-orm";
+import { and, desc, eq, inArray, lt, ne, sql } from "drizzle-orm";
 import { bigint, bigserial, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
 import { AutoRouter, Router, json, status, withParams } from "itty-router";
 import { access, readFile } from "node:fs/promises";
@@ -41,11 +41,16 @@ __export(schema_exports, {
 	entities: () => entities,
 	entityBridges: () => entityBridges,
 	entityDispatchState: () => entityDispatchState,
+	entityEffectivePermissions: () => entityEffectivePermissions,
+	entityLineage: () => entityLineage,
 	entityManifestSources: () => entityManifestSources,
+	entityPermissionGrants: () => entityPermissionGrants,
+	entityTypePermissionGrants: () => entityTypePermissionGrants,
 	entityTypes: () => entityTypes,
 	runnerRuntimeDiagnostics: () => runnerRuntimeDiagnostics,
 	runners: () => runners,
 	scheduledTasks: () => scheduledTasks,
+	sharedStateLinks: () => sharedStateLinks,
 	subscriptionWebhooks: () => subscriptionWebhooks,
 	tagStreamOutbox: () => tagStreamOutbox,
 	users: () => users,
@@ -93,6 +98,94 @@ const entities = pgTable(`entities`, {
 	index(`entities_tags_index_gin`).using(`gin`, table.tagsIndex),
 	check(`chk_entities_status`, sql`${table.status} IN ('spawning', 'running', 'idle', 'paused', 'stopping', 'stopped', 'killed')`)
 ]);
+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')`)
+]);
+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`)
+]);
+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')`)
+]);
+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')`)
+]);
+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)
+]);
 const users = pgTable(`users`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	id: text(`id`).notNull(),
@@ -279,12 +372,18 @@ const entityBridges = pgTable(`entity_bridges`, {
 	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`, { withTimezone: true }).notNull().defaultNow(),
 	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
-}, (table) => [primaryKey({ columns: [table.tenantId, table.sourceRef] }), unique(`uq_entity_bridges_stream_url`).on(table.tenantId, table.streamUrl)]);
+}, (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)
+]);
 const entityManifestSources = pgTable(`entity_manifest_sources`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	ownerEntityUrl: text(`owner_entity_url`).notNull(),
@@ -1045,29 +1144,136 @@ function buildElectricProxyTarget(options) {
 	if (options.electricSecret) target.searchParams.set(`secret`, options.electricSecret);
 	const table = options.incomingUrl.searchParams.get(`table`);
 	if (table === `entities`) {
-		target.searchParams.set(`columns`, `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","sandbox","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		target.searchParams.set(`columns`, `"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
+		}));
 	} 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","sandbox_profiles","created_at","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral$2(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`, `"tenant_id","runner_id","owner_principal","wake_stream_offset","last_seen_at","liveness_lease_expires_at","diagnostics","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral$2(options.principalUrl ?? ``)}`]);
 	} else if (table === `entity_dispatch_state`) {
 		target.searchParams.set(`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;
 }
+function buildReadableEntitiesWhere(options) {
+	const tenant = sqlStringLiteral$2(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	const principalUrl$1 = sqlStringLiteral$2(options.principalUrl);
+	const principalKind = sqlStringLiteral$2(options.principalKind);
+	return [
+		`tenant_id = ${tenant}`,
+		`AND (`,
+		`  created_by = ${principalUrl$1}`,
+		`  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$1})`,
+		`        OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+		`      )`,
+		`  )`,
+		`)`
+	].join(`\n`);
+}
+function buildReadableEntityUrlWhere(options) {
+	const tenant = sqlStringLiteral$2(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`);
+}
+function buildCurrentPrincipalEntityEffectivePermissionsWhere(options) {
+	const tenant = sqlStringLiteral$2(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	const principalUrl$1 = sqlStringLiteral$2(options.principalUrl);
+	const principalKind = sqlStringLiteral$2(options.principalKind);
+	return [
+		`tenant_id = ${tenant}`,
+		`AND (`,
+		`  (subject_kind = 'principal' AND subject_value = ${principalUrl$1})`,
+		`  OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+		`)`,
+		`AND entity_url IN (`,
+		`  SELECT url`,
+		`  FROM entities`,
+		`  WHERE ${buildReadableEntitiesWhere(options)}`,
+		`)`
+	].join(`\n`);
+}
+function buildSpawnableEntityTypesWhere(options) {
+	const tenant = sqlStringLiteral$2(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	const principalUrl$1 = sqlStringLiteral$2(options.principalUrl);
+	const principalKind = sqlStringLiteral$2(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$1})`,
+		`      OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+		`    )`,
+		`)`
+	].join(`\n`);
+}
 async function forwardFetchRequest(options) {
 	const routingAdapter = resolveDurableStreamsRoutingAdapter(options.durableStreamsRouting, options.durableStreamsUrl);
 	const routingInput = {
@@ -1102,13 +1308,18 @@ function decodeJsonObject(body) {
 	return null;
 }
 function applyTenantShapeWhere(target, tenantId, extraConditions = []) {
-	const tenantWhere = [`tenant_id = ${sqlStringLiteral$2(tenantId)}`, ...extraConditions].join(` AND `);
+	applyShapeWhere(target, [`tenant_id = ${sqlStringLiteral$2(tenantId)}`, ...extraConditions].join(` AND `));
+}
+function applyShapeWhere(target, enforcedWhere) {
 	const existingWhere = target.searchParams.get(`where`);
-	target.searchParams.set(`where`, existingWhere ? `${tenantWhere} AND (${existingWhere})` : tenantWhere);
+	target.searchParams.set(`where`, existingWhere ? `${enforcedWhere} AND (${existingWhere})` : enforcedWhere);
 }
 function sqlStringLiteral$2(value) {
 	return `'${value.replace(/'/g, `''`)}'`;
 }
+function indentWhere(where, prefix) {
+	return where.split(`\n`).map((line) => `${prefix}${line}`).join(`\n`);
+}
 
 //#endregion
 //#region src/routing/agent-ui-router.ts
@@ -1402,6 +1613,262 @@ function isLoopbackHostname(hostname) {
 	return hostname === `localhost` || hostname === `127.0.0.1` || hostname === `::1`;
 }
 
+//#endregion
+//#region src/principal.ts
+const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
+const PRINCIPAL_KINDS = new Set([
+	`user`,
+	`agent`,
+	`service`,
+	`system`
+]);
+function parsePrincipalKey(input) {
+	const colon = input.indexOf(`:`);
+	if (colon <= 0) throw new Error(`Invalid principal identifier`);
+	const kind = input.slice(0, colon);
+	const id = input.slice(colon + 1);
+	if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`);
+	if (!id || id.includes(`/`)) throw new Error(`Invalid principal id`);
+	const key = `${kind}:${id}`;
+	return {
+		kind,
+		id,
+		key,
+		url: `/principal/${encodeURIComponent(key)}`
+	};
+}
+function principalUrl(key) {
+	return parsePrincipalKey(key).url;
+}
+function parsePrincipalUrl(url) {
+	if (!url.startsWith(`/principal/`)) return null;
+	const segment = url.slice(`/principal/`.length);
+	if (!segment || segment.includes(`/`)) return null;
+	try {
+		return parsePrincipalKey(decodeURIComponent(segment));
+	} catch {
+		return null;
+	}
+}
+function parsePrincipalInput(input) {
+	const urlPrincipal = parsePrincipalUrl(input);
+	if (urlPrincipal) return urlPrincipal;
+	try {
+		return parsePrincipalKey(input);
+	} catch {
+		return null;
+	}
+}
+function getPrincipalFromRequest(request) {
+	const value = request.headers.get(ELECTRIC_PRINCIPAL_HEADER);
+	if (!value) return null;
+	return parsePrincipalInput(value);
+}
+function getDevPrincipal() {
+	return parsePrincipalKey(`system:dev-local`);
+}
+const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
+	`framework`,
+	`auth-sync`,
+	`dev-local`
+]);
+function isBuiltInSystemPrincipalUrl(url) {
+	if (!url?.startsWith(`/principal/`)) return false;
+	try {
+		const principal = parsePrincipalUrl(url);
+		if (!principal) return false;
+		return principal.kind === `system` && BUILT_IN_SYSTEM_PRINCIPAL_IDS.has(principal.id);
+	} catch {
+		return false;
+	}
+}
+function principalFromCreatedBy(createdBy) {
+	if (!createdBy) return void 0;
+	const principal = parsePrincipalUrl(createdBy);
+	if (!principal) return {
+		url: createdBy,
+		key: null
+	};
+	return {
+		url: principal.url,
+		key: principal.key,
+		kind: principal.kind,
+		id: principal.id
+	};
+}
+const principalIdentityStateSchema = Type.Object({
+	kind: Type.Union([
+		Type.Literal(`user`),
+		Type.Literal(`agent`),
+		Type.Literal(`service`),
+		Type.Literal(`system`)
+	]),
+	id: Type.String(),
+	key: Type.String(),
+	url: Type.String(),
+	updated_at: Type.String(),
+	display_name: Type.Optional(Type.String()),
+	email: Type.Optional(Type.String()),
+	avatar_url: Type.Optional(Type.String()),
+	auth_provider: Type.Optional(Type.String()),
+	auth_subject: Type.Optional(Type.String()),
+	claims: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	created_at: Type.Optional(Type.String())
+}, { additionalProperties: false });
+const principalUpdateIdentityMessageSchema = Type.Object({ identity: principalIdentityStateSchema }, { additionalProperties: false });
+
+//#endregion
+//#region src/permissions.ts
+const authzDecisionCache = new WeakMap();
+function principalSubject(principal) {
+	return {
+		principalUrl: principal.url,
+		principalKind: principal.kind
+	};
+}
+function isPermissionBypassPrincipal(ctx) {
+	return isBuiltInSystemPrincipalUrl(ctx.principal.url);
+}
+async function canAccessEntity(ctx, entity, permission, request) {
+	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
+	});
+}
+async function canAccessEntityType(ctx, entityType, permission, request) {
+	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
+	});
+}
+async function canRegisterEntityType(ctx, input, request) {
+	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
+	});
+}
+async function canAccessSharedState(ctx, sharedStateId, permission, request, ownerEntityUrl) {
+	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, input) {
+	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;
+	try {
+		decision = await hook({
+			tenant: ctx.service,
+			principal: ctx.principal,
+			verb: input.verb,
+			resource: input.resource,
+			request: input.request ? requestMetadata(input.request) : void 0,
+			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, cacheKey) {
+	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, cacheKey, decision) {
+	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) {
+	const headers = {};
+	request.headers.forEach((value, key) => {
+		headers[key] = value;
+	});
+	return {
+		method: request.method,
+		url: request.url,
+		headers
+	};
+}
+
 //#endregion
 //#region src/webhook-signing.ts
 const encoder = new TextEncoder();
@@ -1492,6 +1959,7 @@ const subscriptionControlActions = [
 	`ack`,
 	`release`
 ];
+const SHARED_STATE_OWNER_ENTITY_HEADER = `electric-owner-entity`;
 const durableStreamsRouter = Router();
 durableStreamsRouter.put(`/__ds/subscriptions/:subscriptionId`, putSubscriptionBase);
 durableStreamsRouter.get(`/__ds/subscriptions/:subscriptionId`, getSubscriptionBase);
@@ -1709,6 +2177,8 @@ async function webhookJwks(_request, ctx) {
 	});
 }
 async function streamAppend(request, ctx) {
+	const auth = await authorizeDurableStreamAccess(request, ctx);
+	if (auth) return auth;
 	return await electricAgentsStreamAppendRouter.fetch(createStreamAppendRouteRequest(request), ctx.runtime, (req, body) => forwardFetchRequest({
 		request: {
 			method: req.method,
@@ -1725,8 +2195,9 @@ async function streamAppend(request, ctx) {
 	}));
 }
 async function proxyPassThrough(request, ctx) {
+	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 = method === `GET` ? await ctx.entityBridgeManager.beginClientRead(streamPath) : null;
@@ -1737,6 +2208,51 @@ async function proxyPassThrough(request, ctx) {
 		await endTrackedRead?.();
 	}
 }
+async function authorizeDurableStreamAccess(request, ctx) {
+	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)) return void 0;
+			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)) return void 0;
+			return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to read ${attachmentEntity.url}`);
+		}
+	}
+	const sharedStateId = sharedStateIdFromPath(streamPath);
+	if (!sharedStateId) return void 0;
+	if (method === `GET` || method === `HEAD`) {
+		if (await canAccessSharedState(ctx, sharedStateId, `read`, request)) return void 0;
+		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() || void 0;
+		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) return void 0;
+		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$1) {
+	const match = path$1.match(/^\/([^/]+)\/([^/]+)\/attachments\/[^/]+$/);
+	if (!match) return null;
+	return `/${match[1]}/${match[2]}`;
+}
+function sharedStateIdFromPath(path$1) {
+	const match = path$1.match(/^\/_electric\/shared-state\/([^/]+)$/);
+	if (!match) return null;
+	try {
+		return decodeURIComponent(match[1]);
+	} catch {
+		return match[1];
+	}
+}
 
 //#endregion
 //#region src/routing/electric-proxy-router.ts
@@ -1744,12 +2260,15 @@ const electricProxyRouter = Router({ base: `/_electric/electric` });
 electricProxyRouter.get(`/*`, proxyElectric);
 async function proxyElectric(request, ctx) {
 	if (!ctx.electricUrl) 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
+		principalUrl: ctx.principal.url,
+		principalKind: ctx.principal.kind,
+		permissionBypass: isPermissionBypassPrincipal(ctx)
 	});
 	const headers = new Headers(request.headers);
 	headers.delete(`host`);
@@ -1769,110 +2288,6 @@ async function proxyElectric(request, ctx) {
 	});
 }
 
-//#endregion
-//#region src/principal.ts
-const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
-const PRINCIPAL_KINDS = new Set([
-	`user`,
-	`agent`,
-	`service`,
-	`system`
-]);
-function parsePrincipalKey(input) {
-	const colon = input.indexOf(`:`);
-	if (colon <= 0) throw new Error(`Invalid principal identifier`);
-	const kind = input.slice(0, colon);
-	const id = input.slice(colon + 1);
-	if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`);
-	if (!id || id.includes(`/`)) throw new Error(`Invalid principal id`);
-	const key = `${kind}:${id}`;
-	return {
-		kind,
-		id,
-		key,
-		url: `/principal/${encodeURIComponent(key)}`
-	};
-}
-function principalUrl(key) {
-	return parsePrincipalKey(key).url;
-}
-function parsePrincipalUrl(url) {
-	if (!url.startsWith(`/principal/`)) return null;
-	const segment = url.slice(`/principal/`.length);
-	if (!segment || segment.includes(`/`)) return null;
-	try {
-		return parsePrincipalKey(decodeURIComponent(segment));
-	} catch {
-		return null;
-	}
-}
-function parsePrincipalInput(input) {
-	const urlPrincipal = parsePrincipalUrl(input);
-	if (urlPrincipal) return urlPrincipal;
-	try {
-		return parsePrincipalKey(input);
-	} catch {
-		return null;
-	}
-}
-function getPrincipalFromRequest(request) {
-	const value = request.headers.get(ELECTRIC_PRINCIPAL_HEADER);
-	if (!value) return null;
-	return parsePrincipalInput(value);
-}
-function getDevPrincipal() {
-	return parsePrincipalKey(`system:dev-local`);
-}
-const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
-	`framework`,
-	`auth-sync`,
-	`dev-local`
-]);
-function isBuiltInSystemPrincipalUrl(url) {
-	if (!url?.startsWith(`/principal/`)) return false;
-	try {
-		const principal = parsePrincipalUrl(url);
-		if (!principal) return false;
-		return principal.kind === `system` && BUILT_IN_SYSTEM_PRINCIPAL_IDS.has(principal.id);
-	} catch {
-		return false;
-	}
-}
-function principalFromCreatedBy(createdBy) {
-	if (!createdBy) return void 0;
-	const principal = parsePrincipalUrl(createdBy);
-	if (!principal) return {
-		url: createdBy,
-		key: null
-	};
-	return {
-		url: principal.url,
-		key: principal.key,
-		kind: principal.kind,
-		id: principal.id
-	};
-}
-const principalIdentityStateSchema = Type.Object({
-	kind: Type.Union([
-		Type.Literal(`user`),
-		Type.Literal(`agent`),
-		Type.Literal(`service`),
-		Type.Literal(`system`)
-	]),
-	id: Type.String(),
-	key: Type.String(),
-	url: Type.String(),
-	updated_at: Type.String(),
-	display_name: Type.Optional(Type.String()),
-	email: Type.Optional(Type.String()),
-	avatar_url: Type.Optional(Type.String()),
-	auth_provider: Type.Optional(Type.String()),
-	auth_subject: Type.Optional(Type.String()),
-	claims: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-	created_at: Type.Optional(Type.String())
-}, { additionalProperties: false });
-const principalUpdateIdentityMessageSchema = Type.Object({ identity: principalIdentityStateSchema }, { additionalProperties: false });
-
 //#endregion
 //#region src/dispatch-policy-schema.ts
 const nonEmptyStringSchema = Type.String({ minLength: 1 });
@@ -2046,16 +2461,26 @@ function isDuplicateUrlError(err) {
 	return e.code === `23505`;
 }
 const DEFAULT_RUNNER_LEASE_MS = 3e4;
+const PERMISSION_PRUNE_INTERVAL_MS = 3e4;
 function runnerWakeStream(runnerId) {
 	return `/runners/${runnerId}/wake`;
 }
 var PostgresRegistry = class {
+	lastPermissionPruneStartedAt = 0;
+	permissionPrunePromise = null;
 	constructor(db, tenantId = DEFAULT_TENANT_ID) {
 		this.db = db;
 		this.tenantId = tenantId;
 	}
 	async initialize() {}
 	close() {}
+	async ensureUserForPrincipal(principal) {
+		if (principal.kind !== `user`) return;
+		await this.db.insert(users).values({
+			tenantId: this.tenantId,
+			id: principal.id
+		}).onConflictDoNothing();
+	}
 	async createRunner(input) {
 		const now = new Date();
 		const wakeStream = input.wakeStream ?? runnerWakeStream(input.id);
@@ -2390,6 +2815,59 @@ var PostgresRegistry = class {
 					pendingSourceStreams: [],
 					updatedAt: new Date()
 				}).onConflictDoNothing();
+				await tx.insert(entityLineage).values({
+					tenantId: this.tenantId,
+					ancestorUrl: entity.url,
+					descendantUrl: entity.url,
+					depth: 0
+				}).onConflictDoNothing();
+				if (entity.parent) await tx.execute(sql`
+            INSERT INTO ${entityLineage} (
+              tenant_id,
+              ancestor_url,
+              descendant_url,
+              depth
+            )
+            SELECT
+              ${this.tenantId},
+              ancestor_url,
+              ${entity.url},
+              depth + 1
+            FROM ${entityLineage}
+            WHERE tenant_id = ${this.tenantId}
+              AND descendant_url = ${entity.parent}
+            ON CONFLICT DO NOTHING
+          `);
+				await tx.execute(sql`
+          INSERT INTO ${entityEffectivePermissions} (
+            tenant_id,
+            entity_url,
+            source_entity_url,
+            source_grant_id,
+            permission,
+            subject_kind,
+            subject_value,
+            expires_at
+          )
+          SELECT
+            ${this.tenantId},
+            ${entity.url},
+            grants.entity_url,
+            grants.id,
+            grants.permission,
+            grants.subject_kind,
+            grants.subject_value,
+            grants.expires_at
+          FROM ${entityPermissionGrants} grants
+          JOIN ${entityLineage} lineage
+            ON lineage.tenant_id = grants.tenant_id
+           AND lineage.ancestor_url = grants.entity_url
+           AND lineage.descendant_url = ${entity.url}
+          WHERE grants.tenant_id = ${this.tenantId}
+            AND grants.propagation = 'descendants'
+            AND (grants.expires_at IS NULL OR grants.expires_at > now())
+          ON CONFLICT DO NOTHING
+        `);
 				return parseInt(result[0].txid);
 			});
 		} catch (err) {
@@ -2411,10 +2889,8 @@ var PostgresRegistry = class {
 	}
 	async getEntityByStream(streamPath) {
 		const mainSuffix = `/main`;
-		const errorSuffix = `/error`;
 		let entityUrl = null;
 		if (streamPath.endsWith(mainSuffix)) entityUrl = streamPath.slice(0, -mainSuffix.length);
-		else if (streamPath.endsWith(errorSuffix)) entityUrl = streamPath.slice(0, -errorSuffix.length);
 		if (!entityUrl) return null;
 		return this.getEntity(entityUrl);
 	}
@@ -2424,6 +2900,23 @@ var PostgresRegistry = class {
 		if (filter?.status) conditions.push(eq(entities.status, filter.status));
 		if (filter?.parent) conditions.push(eq(entities.parent, filter.parent));
 		if (filter?.created_by) conditions.push(eq(entities.createdBy, filter.created_by));
+		if (filter?.readableBy && !filter.readableBy.bypass) conditions.push(sql`(
+        ${entities.createdBy} = ${filter.readableBy.principalUrl}
+        OR ${entities.url} IN (
+          SELECT ${entityEffectivePermissions.entityUrl}
+          FROM ${entityEffectivePermissions}
+          WHERE ${entityEffectivePermissions.tenantId} = ${this.tenantId}
+            AND ${entityEffectivePermissions.permission} IN ('read', 'manage')
+            AND (${entityEffectivePermissions.expiresAt} IS NULL OR ${entityEffectivePermissions.expiresAt} > now())
+            AND (
+              (${entityEffectivePermissions.subjectKind} = 'principal'
+                AND ${entityEffectivePermissions.subjectValue} = ${filter.readableBy.principalUrl})
+              OR
+              (${entityEffectivePermissions.subjectKind} = 'principal_kind'
+                AND ${entityEffectivePermissions.subjectValue} = ${filter.readableBy.principalKind})
+            )
+        )
+      )`);
 		const whereClause = and(...conditions);
 		const countResult = await this.db.select({ count: sql`count(*)` }).from(entities).where(whereClause);
 		const total = Number(countResult[0].count);
@@ -2436,6 +2929,189 @@ var PostgresRegistry = class {
 			total
 		};
 	}
+	async createEntityTypePermissionGrant(input) {
+		const [row] = await this.db.insert(entityTypePermissionGrants).values({
+			tenantId: this.tenantId,
+			entityType: input.entityType,
+			permission: input.permission,
+			subjectKind: input.subjectKind,
+			subjectValue: input.subjectValue,
+			createdBy: input.createdBy ?? null,
+			expiresAt: input.expiresAt ?? null
+		}).returning();
+		return this.rowToEntityTypePermissionGrant(row);
+	}
+	async ensureEntityTypePermissionGrant(input) {
+		const [existing] = await this.db.select().from(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, input.entityType), eq(entityTypePermissionGrants.permission, input.permission), eq(entityTypePermissionGrants.subjectKind, input.subjectKind), eq(entityTypePermissionGrants.subjectValue, input.subjectValue), input.expiresAt ? eq(entityTypePermissionGrants.expiresAt, input.expiresAt) : sql`${entityTypePermissionGrants.expiresAt} IS NULL`)).limit(1);
+		if (existing) return this.rowToEntityTypePermissionGrant(existing);
+		return await this.createEntityTypePermissionGrant(input);
+	}
+	async listEntityTypePermissionGrants(entityType) {
+		const rows = await this.db.select().from(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, entityType))).orderBy(entityTypePermissionGrants.id);
+		return rows.map((row) => this.rowToEntityTypePermissionGrant(row));
+	}
+	async deleteEntityTypePermissionGrant(entityType, grantId) {
+		const rows = await this.db.delete(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, entityType), eq(entityTypePermissionGrants.id, grantId))).returning({ id: entityTypePermissionGrants.id });
+		return rows.length > 0;
+	}
+	async hasEntityTypePermission(entityType, permission, subject) {
+		const permissions = [permission, `manage`];
+		const rows = await this.db.select({ id: entityTypePermissionGrants.id }).from(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, entityType), inArray(entityTypePermissionGrants.permission, [...permissions]), sql`(${entityTypePermissionGrants.expiresAt} IS NULL OR ${entityTypePermissionGrants.expiresAt} > now())`, sql`(
+            (${entityTypePermissionGrants.subjectKind} = 'principal'
+              AND ${entityTypePermissionGrants.subjectValue} = ${subject.principalUrl})
+            OR
+            (${entityTypePermissionGrants.subjectKind} = 'principal_kind'
+              AND ${entityTypePermissionGrants.subjectValue} = ${subject.principalKind})
+          )`)).limit(1);
+		return rows.length > 0;
+	}
+	async createEntityPermissionGrant(input) {
+		return await this.db.transaction(async (tx) => {
+			const [row] = await tx.insert(entityPermissionGrants).values({
+				tenantId: this.tenantId,
+				entityUrl: input.entityUrl,
+				permission: input.permission,
+				subjectKind: input.subjectKind,
+				subjectValue: input.subjectValue,
+				propagation: input.propagation ?? `self`,
+				copyToChildren: input.copyToChildren ?? false,
+				createdBy: input.createdBy ?? null,
+				expiresAt: input.expiresAt ?? null
+			}).returning();
+			await this.materializeEntityPermissionGrant(tx, row);
+			return this.rowToEntityPermissionGrant(row);
+		});
+	}
+	async listEntityPermissionGrants(entityUrl) {
+		const rows = await this.db.select().from(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), eq(entityPermissionGrants.entityUrl, entityUrl))).orderBy(entityPermissionGrants.id);
+		return rows.map((row) => this.rowToEntityPermissionGrant(row));
+	}
+	async deleteEntityPermissionGrant(entityUrl, grantId) {
+		return await this.db.transaction(async (tx) => {
+			await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), eq(entityEffectivePermissions.sourceGrantId, grantId)));
+			const rows = await tx.delete(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), eq(entityPermissionGrants.entityUrl, entityUrl), eq(entityPermissionGrants.id, grantId))).returning({ id: entityPermissionGrants.id });
+			return rows.length > 0;
+		});
+	}
+	async copyEntityPermissionGrantsForSpawn(parentEntityUrl, childEntityUrl, createdBy) {
+		const parentGrants = await this.db.select().from(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), eq(entityPermissionGrants.entityUrl, parentEntityUrl), eq(entityPermissionGrants.copyToChildren, true), sql`(${entityPermissionGrants.expiresAt} IS NULL OR ${entityPermissionGrants.expiresAt} > now())`));
+		const copied = [];
+		for (const grant of parentGrants) copied.push(await this.createEntityPermissionGrant({
+			entityUrl: childEntityUrl,
+			permission: grant.permission,
+			subjectKind: grant.subjectKind,
+			subjectValue: grant.subjectValue,
+			propagation: `self`,
+			copyToChildren: grant.copyToChildren,
+			createdBy,
+			expiresAt: grant.expiresAt ?? void 0
+		}));
+		return copied;
+	}
+	async hasEntityPermission(entityUrl, permission, subject) {
+		const permissions = [permission, `manage`];
+		const rows = await this.db.select({ id: entityEffectivePermissions.id }).from(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), eq(entityEffectivePermissions.entityUrl, entityUrl), inArray(entityEffectivePermissions.permission, [...permissions]), sql`(${entityEffectivePermissions.expiresAt} IS NULL OR ${entityEffectivePermissions.expiresAt} > now())`, sql`(
+            (${entityEffectivePermissions.subjectKind} = 'principal'
+              AND ${entityEffectivePermissions.subjectValue} = ${subject.principalUrl})
+            OR
+            (${entityEffectivePermissions.subjectKind} = 'principal_kind'
+              AND ${entityEffectivePermissions.subjectValue} = ${subject.principalKind})
+          )`)).limit(1);
+		return rows.length > 0;
+	}
+	async replaceSharedStateLink(ownerEntityUrl, manifestKey, sharedStateId) {
+		await this.db.delete(sharedStateLinks).where(and(eq(sharedStateLinks.tenantId, this.tenantId), eq(sharedStateLinks.ownerEntityUrl, ownerEntityUrl), eq(sharedStateLinks.manifestKey, manifestKey)));
+		if (!sharedStateId) return;
+		await this.db.insert(sharedStateLinks).values({
+			tenantId: this.tenantId,
+			ownerEntityUrl,
+			manifestKey,
+			sharedStateId
+		}).onConflictDoUpdate({
+			target: [
+				sharedStateLinks.tenantId,
+				sharedStateLinks.ownerEntityUrl,
+				sharedStateLinks.manifestKey
+			],
+			set: {
+				sharedStateId,
+				updatedAt: new Date()
+			}
+		});
+	}
+	async listSharedStateLinkedEntityUrls(sharedStateId) {
+		const rows = await this.db.selectDistinct({ ownerEntityUrl: sharedStateLinks.ownerEntityUrl }).from(sharedStateLinks).where(and(eq(sharedStateLinks.tenantId, this.tenantId), eq(sharedStateLinks.sharedStateId, sharedStateId)));
+		return rows.map((row) => row.ownerEntityUrl);
+	}
+	async pruneExpiredPermissionGrants(now = new Date(), options = {}) {
+		if (this.permissionPrunePromise) return await this.permissionPrunePromise;
+		const startedAt = Date.now();
+		if (!options.force && startedAt - this.lastPermissionPruneStartedAt < PERMISSION_PRUNE_INTERVAL_MS) return;
+		this.lastPermissionPruneStartedAt = startedAt;
+		const promise = this.pruneExpiredPermissionGrantsNow(now);
+		this.permissionPrunePromise = promise;
+		try {
+			await promise;
+		} catch (error) {
+			this.lastPermissionPruneStartedAt = 0;
+			throw error;
+		} finally {
+			if (this.permissionPrunePromise === promise) this.permissionPrunePromise = null;
+		}
+	}
+	async pruneExpiredPermissionGrantsNow(now) {
+		await this.db.transaction(async (tx) => {
+			const expiredEntityGrantIds = await tx.select({ id: entityPermissionGrants.id }).from(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), sql`${entityPermissionGrants.expiresAt} IS NOT NULL`, lt(entityPermissionGrants.expiresAt, now)));
+			const ids = expiredEntityGrantIds.map((row) => row.id);
+			if (ids.length > 0) {
+				await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), inArray(entityEffectivePermissions.sourceGrantId, ids)));
+				await tx.delete(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), inArray(entityPermissionGrants.id, ids)));
+			}
+			await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), sql`${entityEffectivePermissions.expiresAt} IS NOT NULL`, lt(entityEffectivePermissions.expiresAt, now)));
+			await tx.delete(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), sql`${entityTypePermissionGrants.expiresAt} IS NOT NULL`, lt(entityTypePermissionGrants.expiresAt, now)));
+		});
+	}
+	async materializeEntityPermissionGrant(tx, grant) {
+		await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), eq(entityEffectivePermissions.sourceGrantId, grant.id)));
+		if (grant.propagation === `descendants`) {
+			await tx.execute(sql`
+        INSERT INTO ${entityEffectivePermissions} (
+          tenant_id,
+          entity_url,
+          source_entity_url,
+          source_grant_id,
+          permission,
+          subject_kind,
+          subject_value,
+          expires_at
+        )
+        SELECT
+          ${this.tenantId},
+          descendant_url,
+          ${grant.entityUrl},
+          ${grant.id},
+          ${grant.permission},
+          ${grant.subjectKind},
+          ${grant.subjectValue},
+          ${grant.expiresAt}
+        FROM ${entityLineage}
+        WHERE tenant_id = ${this.tenantId}
+          AND ancestor_url = ${grant.entityUrl}
+        ON CONFLICT DO NOTHING
+      `);
+			return;
+		}
+		await tx.insert(entityEffectivePermissions).values({
+			tenantId: this.tenantId,
+			entityUrl: grant.entityUrl,
+			sourceEntityUrl: grant.entityUrl,
+			sourceGrantId: grant.id,
+			permission: grant.permission,
+			subjectKind: grant.subjectKind,
+			subjectValue: grant.subjectValue,
+			expiresAt: grant.expiresAt
+		}).onConflictDoNothing();
+	}
 	async updateStatus(entityUrl, status$1) {
 		const whereClause = isTerminalEntityStatus(status$1) ? this.entityWhere(entityUrl) : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`), ne(entities.status, `killed`));
 		await this.db.update(entities).set({
@@ -2537,7 +3213,9 @@ var PostgresRegistry = class {
 			tenantId: this.tenantId,
 			sourceRef: row.sourceRef,
 			tags: normalizeTags(row.tags),
-			streamUrl: row.streamUrl
+			streamUrl: row.streamUrl,
+			principalUrl: row.principalUrl,
+			principalKind: row.principalKind
 		}).onConflictDoNothing();
 		const existing = await this.getEntityBridge(row.sourceRef);
 		if (!existing) throw new Error(`Failed to load entity bridge ${row.sourceRef}`);
@@ -2699,15 +3377,40 @@ var PostgresRegistry = class {
 			updated_at: row.updatedAt
 		};
 	}
+	rowToEntityTypePermissionGrant(row) {
+		return {
+			id: row.id,
+			entity_type: row.entityType,
+			permission: row.permission,
+			subject_kind: row.subjectKind,
+			subject_value: row.subjectValue,
+			created_by: row.createdBy ?? void 0,
+			expires_at: row.expiresAt?.toISOString(),
+			created_at: row.createdAt.toISOString(),
+			updated_at: row.updatedAt.toISOString()
+		};
+	}
+	rowToEntityPermissionGrant(row) {
+		return {
+			id: row.id,
+			entity_url: row.entityUrl,
+			permission: row.permission,
+			subject_kind: row.subjectKind,
+			subject_value: row.subjectValue,
+			propagation: row.propagation,
+			copy_to_children: row.copyToChildren,
+			created_by: row.createdBy ?? void 0,
+			expires_at: row.expiresAt?.toISOString(),
+			created_at: row.createdAt.toISOString(),
+			updated_at: row.updatedAt.toISOString()
+		};
+	}
 	rowToEntity(row) {
 		return {
 			url: row.url,
 			type: row.type,
 			status: assertEntityStatus(row.status),
-			streams: {
-				main: `${row.url}/main`,
-				error: `${row.url}/error`
-			},
+			streams: { main: `${row.url}/main` },
 			subscription_id: row.subscriptionId,
 			dispatch_policy: row.dispatchPolicy ?? void 0,
 			write_token: row.writeToken,
@@ -2729,6 +3432,8 @@ var PostgresRegistry = class {
 			sourceRef: row.sourceRef,
 			tags: row.tags ?? {},
 			streamUrl: row.streamUrl,
+			principalUrl: row.principalUrl ?? void 0,
+			principalKind: row.principalKind ?? void 0,
 			shapeHandle: row.shapeHandle ?? void 0,
 			shapeOffset: row.shapeOffset ?? void 0,
 			lastObserverActivityAt: row.lastObserverActivityAt,
@@ -3031,7 +3736,10 @@ var EntityManager = class {
 	}
 	async ensurePrincipal(principal) {
 		const existing = await this.registry.getEntity(principal.url);
-		if (existing) return existing;
+		if (existing) {
+			await this.ensureUserPrincipal(principal);
+			return existing;
+		}
 		await this.ensurePrincipalEntityType();
 		try {
 			const entity = await this.spawn(`principal`, {
@@ -3060,15 +3768,22 @@ var EntityManager = class {
 					updated_at: now
 				}
 			}));
+			await this.ensureUserPrincipal(principal);
 			return entity;
 		} catch (error) {
 			if (error instanceof ElectricAgentsError && error.code === ErrCodeDuplicateURL) {
 				const raced = await this.registry.getEntity(principal.url);
-				if (raced) return raced;
+				if (raced) {
+					await this.ensureUserPrincipal(principal);
+					return raced;
+				}
 			}
 			throw error;
 		}
 	}
+	async ensureUserPrincipal(principal) {
+		if (principal.kind === `user`) await this.registry.ensureUserForPrincipal(principal);
+	}
 	/**
 	* Spawn a new entity of the given type with durable streams.
 	*/
@@ -3098,7 +3813,6 @@ var EntityManager = class {
 		const writeToken = randomUUID();
 		const entityURL = typeName === `principal` ? principalUrl(instanceId) : `/${typeName}/${instanceId}`;
 		const mainPath = `${entityURL}/main`;
-		const errorPath = `${entityURL}/error`;
 		const subscriptionId = `${typeName}-handler`;
 		const spawnT0 = performance.now();
 		const existingByURL = await this.registry.getEntity(entityURL);
@@ -3115,10 +3829,7 @@ var EntityManager = class {
 			type: typeName,
 			status: `idle`,
 			url: entityURL,
-			streams: {
-				main: mainPath,
-				error: errorPath
-			},
+			streams: { main: mainPath },
 			subscription_id: subscriptionId,
 			dispatch_policy: dispatchPolicy,
 			write_token: writeToken,
@@ -3171,55 +3882,43 @@ var EntityManager = class {
 		const queueEnterT0 = performance.now();
 		const queueWaiting = this.spawnPersistQueue.length();
 		const queueRunning = this.spawnPersistQueue.running();
-		const [mainStreamResult, errorStreamResult, entityResult] = await this.spawnPersistQueue.push(async () => {
+		const [mainStreamResult, entityResult] = await this.spawnPersistQueue.push(async () => {
 			let entityTxid;
 			try {
 				entityTxid = await withSpan(`db.createEntity`, () => this.registry.createEntity(entityData));
 			} catch (err) {
-				return [
-					{
-						status: `fulfilled`,
-						value: void 0
-					},
-					{
-						status: `fulfilled`,
-						value: void 0
-					},
-					{
-						status: `rejected`,
-						reason: err
-					}
-				];
+				return [{
+					status: `fulfilled`,
+					value: void 0
+				}, {
+					status: `rejected`,
+					reason: err
+				}];
 			}
-			const [mainStreamResult$1, errorStreamResult$1] = await Promise.allSettled([this.streamClient.create(mainPath, {
+			const [mainStreamResult$1] = await Promise.allSettled([this.streamClient.create(mainPath, {
 				contentType,
 				body: initialBody
-			}), this.streamClient.create(errorPath, { contentType })]);
-			return [
-				mainStreamResult$1,
-				errorStreamResult$1,
-				{
-					status: `fulfilled`,
-					value: entityTxid
-				}
-			];
+			})]);
+			return [mainStreamResult$1, {
+				status: `fulfilled`,
+				value: entityTxid
+			}];
 		});
 		const parallelMs = +(performance.now() - queueEnterT0).toFixed(2);
-		if (mainStreamResult.status === `rejected` || errorStreamResult.status === `rejected` || entityResult.status === `rejected`) {
+		if (mainStreamResult.status === `rejected` || entityResult.status === `rejected`) {
 			const entityReason = entityResult.status === `rejected` ? entityResult.reason : null;
-			const streamReason = mainStreamResult.status === `rejected` ? mainStreamResult.reason : errorStreamResult.status === `rejected` ? errorStreamResult.reason : null;
+			const streamReason = mainStreamResult.status === `rejected` ? mainStreamResult.reason : null;
 			const isDuplicate = entityReason instanceof EntityAlreadyExistsError;
 			const isStreamConflict = !!streamReason && typeof streamReason === `object` && (`status` in streamReason && streamReason.status === 409 || `code` in streamReason && streamReason.code === `CONFLICT_SEQ`);
 			const rollbacks = [];
 			if (!isDuplicate && !isStreamConflict) {
 				if (mainStreamResult.status === `fulfilled`) rollbacks.push(this.streamClient.delete(mainPath));
-				if (errorStreamResult.status === `fulfilled`) rollbacks.push(this.streamClient.delete(errorPath));
 				if (entityResult.status === `fulfilled`) rollbacks.push(this.registry.deleteEntity(entityURL));
 				if (req.wake) rollbacks.push(this.wakeRegistry.unregisterBySubscriberAndSource(req.wake.subscriberUrl, entityURL, this.tenantId));
 				await Promise.allSettled(rollbacks);
 			}
 			if (isDuplicate || isStreamConflict) throw new ElectricAgentsError(ErrCodeDuplicateURL, `Entity already exists at URL "${entityURL}"`, 409);
-			const failure = mainStreamResult.status === `rejected` ? mainStreamResult.reason : errorStreamResult.status === `rejected` ? errorStreamResult.reason : entityResult.reason;
+			const failure = mainStreamResult.status === `rejected` ? mainStreamResult.reason : entityResult.reason;
 			if (failure instanceof Error) throw failure;
 			throw new ElectricAgentsError(`SPAWN_FAILED`, `Spawn failed: ${String(failure)}`, 500);
 		}
@@ -3304,7 +4003,7 @@ var EntityManager = class {
 			});
 			const sharedStateIdMap = await this.buildForkSharedStateIdMap(snapshot.sharedStateIds, suffix);
 			const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap);
-			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap);
+			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap, opts.createdBy);
 			this.addForkLocks(this.forkWriteLockedEntities, effectiveSubtree.map((entity) => entity.url), writeEntityLocks);
 			this.addForkLocks(this.forkWriteLockedStreams, [...snapshot.sharedStateIds].map((id) => getSharedStateStreamPath(id)), writeStreamLocks);
 			const createdStreams = [];
@@ -3315,8 +4014,6 @@ var EntityManager = class {
 					const isRoot = plan.source.url === rootUrl;
 					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main, isRoot && opts.forkPointer ? { forkPointer: opts.forkPointer } : void 0);
 					createdStreams.push(plan.fork.streams.main);
-					await this.streamClient.fork(plan.fork.streams.error, plan.source.streams.error);
-					createdStreams.push(plan.fork.streams.error);
 				}
 				for (const [sourceId, forkId] of sharedStateIdMap) {
 					const sourcePath = getSharedStateStreamPath(sourceId);
@@ -3650,7 +4347,6 @@ var EntityManager = class {
 		for (const [sourceUrl, forkUrl] of entityUrlMap) {
 			stringMap.set(sourceUrl, forkUrl);
 			stringMap.set(`${sourceUrl}/main`, `${forkUrl}/main`);
-			stringMap.set(`${sourceUrl}/error`, `${forkUrl}/error`);
 		}
 		for (const [sourceId, forkId] of sharedStateIdMap) {
 			stringMap.set(sourceId, forkId);
@@ -3658,7 +4354,7 @@ var EntityManager = class {
 		}
 		return stringMap;
 	}
-	buildForkEntityPlans(entitiesToFork, entityUrlMap, stringMap) {
+	buildForkEntityPlans(entitiesToFork, entityUrlMap, stringMap, createdBy) {
 		const now = Date.now();
 		return entitiesToFork.map((source) => {
 			const forkUrl = entityUrlMap.get(source.url);
@@ -3671,14 +4367,12 @@ var EntityManager = class {
 				url: forkUrl,
 				type,
 				status: `idle`,
-				streams: {
-					main: `${forkUrl}/main`,
-					error: `${forkUrl}/error`
-				},
+				streams: { main: `${forkUrl}/main` },
 				subscription_id: `${type}-handler`,
 				write_token: randomUUID(),
 				spawn_args: spawnArgs,
 				parent,
+				created_by: createdBy ?? source.created_by,
 				created_at: now,
 				updated_at: now
 			};
@@ -3912,7 +4606,7 @@ var EntityManager = class {
 	}
 	async materializeForkManifestSideEffects(entityUrl, manifests) {
 		for (const [manifestKey, manifest] of manifests) {
-			await this.syncEntitiesManifestSource(entityUrl, manifestKey, `upsert`, manifest);
+			await this.syncManifestLinks(entityUrl, manifestKey, `upsert`, manifest);
 			const wake = buildManifestWakeRegistration(entityUrl, manifest, manifestKey);
 			if (wake) await this.wakeRegistry.register({
 				...wake,
@@ -3942,6 +4636,7 @@ var EntityManager = class {
 		await this.scheduler.syncManifestDelayedSend(ownerEntityUrl, manifestKey, {
 			entityUrl: targetUrl,
 			from: senderUrl,
+			from_agent: senderUrl,
 			payload: manifest.payload,
 			key: `scheduled-${producerId}`,
 			type: typeof manifest.messageType === `string` ? manifest.messageType : void 0,
@@ -3981,12 +4676,14 @@ var EntityManager = class {
 		const now = new Date().toISOString();
 		const key = req.key ?? `msg-in-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		const value = {
-			from: req.from,
+			from: req.from_principal ?? req.from,
 			payload: req.payload,
 			timestamp: now,
 			mode: req.mode ?? `immediate`,
 			status: req.mode === `queued` || req.mode === `paused` ? `pending` : `processed`
 		};
+		if (req.from_principal) value.from_principal = req.from_principal;
+		if (req.from_agent) value.from_agent = req.from_agent;
 		if (req.type) value.message_type = req.type;
 		if (req.position) value.position = req.position;
 		else if (value.mode === `queued` || value.mode === `paused`) value.position = createInitialQueuePosition(new Date(now));
@@ -4158,9 +4855,9 @@ var EntityManager = class {
 		if (result.changed && this.entityBridgeManager) await this.entityBridgeManager.onEntityChanged(entityUrl);
 		return updated;
 	}
-	async ensureEntitiesMembershipStream(tags) {
+	async ensureEntitiesMembershipStream(tags, principal) {
 		if (!this.entityBridgeManager) throw new Error(`Entity bridge manager not configured`);
-		return this.entityBridgeManager.register(this.validateTags(tags));
+		return this.entityBridgeManager.register(this.validateTags(tags), principal.url, principal.kind);
 	}
 	async writeManifestEntry(entityUrl, key, operation, value, opts) {
 		const entity = await this.registry.getEntity(entityUrl);
@@ -4178,11 +4875,11 @@ var EntityManager = class {
 		const encoded = this.encodeChangeEvent(event);
 		if (opts?.producerId) {
 			await this.streamClient.appendIdempotent(entity.streams.main, encoded, { producerId: opts.producerId });
-			await this.syncEntitiesManifestSource(entityUrl, key, operation, value);
+			await this.syncManifestLinks(entityUrl, key, operation, value);
 			return;
 		}
 		await this.streamClient.append(entity.streams.main, encoded);
-		await this.syncEntitiesManifestSource(entityUrl, key, operation, value);
+		await this.syncManifestLinks(entityUrl, key, operation, value);
 	}
 	async upsertCronSchedule(entityUrl, req) {
 		if (req.payload === void 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Missing required field: payload`, 400);
@@ -4331,6 +5028,8 @@ var EntityManager = class {
 		await this.scheduler.enqueueDelayedSend({
 			entityUrl,
 			from: req.from,
+			from_principal: req.from_principal,
+			from_agent: req.from_agent,
 			payload: req.payload,
 			key: req.key,
 			type: req.type,
@@ -4373,14 +5072,23 @@ var EntityManager = class {
 			await this.streamClient.appendIdempotent(subscriber.streams.main, this.encodeChangeEvent(wakeEvent), { producerId: `wake-reg-${result.registrationDbId}-${result.sourceEventKey}` });
 		});
 	}
-	async syncEntitiesManifestSource(entityUrl, manifestKey, operation, value) {
+	async syncManifestLinks(entityUrl, manifestKey, operation, value) {
 		const sourceRef = operation === `delete` ? void 0 : this.extractEntitiesSourceRef(value);
 		await this.registry.replaceEntityManifestSource(entityUrl, manifestKey, sourceRef);
+		const sharedStateId = operation === `delete` ? void 0 : this.extractSharedStateId(value);
+		await this.registry.replaceSharedStateLink(entityUrl, manifestKey, sharedStateId);
 	}
 	extractEntitiesSourceRef(manifest) {
 		if (manifest?.kind === `source` && manifest.sourceType === `entities` && typeof manifest.sourceRef === `string`) return manifest.sourceRef;
 		return void 0;
 	}
+	extractSharedStateId(manifest) {
+		if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) return manifest.id;
+		if (manifest?.kind !== `source` || manifest.sourceType !== `db`) return void 0;
+		if (typeof manifest.sourceRef === `string`) return manifest.sourceRef;
+		const config = isRecord(manifest.config) ? manifest.config : void 0;
+		return typeof config?.id === `string` ? config.id : void 0;
+	}
 	/**
 	* Read a child entity's stream and extract concatenated text deltas
 	* for a specific run, plus any error messages for that run.
@@ -4544,14 +5252,7 @@ var EntityManager = class {
 			await this.streamClient.append(entity.streams.main, signalData);
 			return;
 		}
-		const errorCloseEvent = {
-			type: `signal`,
-			key: signalEvent.key,
-			value: signalEvent.value,
-			headers: signalEvent.headers
-		};
-		const errorSignalData = this.encodeChangeEvent(errorCloseEvent);
-		for (const [streamPath, data] of [[entity.streams.main, signalData], [entity.streams.error, errorSignalData]]) try {
+		for (const [streamPath, data] of [[entity.streams.main, signalData]]) try {
 			await this.streamClient.append(streamPath, data, { close: true });
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -4927,6 +5628,27 @@ const wakeConditionSchema = Type.Union([Type.Literal(`runFinished`), Type.Object
 		Type.Literal(`delete`)
 	])))
 })]);
+const permissionSubjectSchema = Type.Object({
+	subject_kind: Type.Union([Type.Literal(`principal`), Type.Literal(`principal_kind`)]),
+	subject_value: Type.String()
+}, { additionalProperties: false });
+const entityPermissionSchema = Type.Union([
+	Type.Literal(`read`),
+	Type.Literal(`write`),
+	Type.Literal(`delete`),
+	Type.Literal(`signal`),
+	Type.Literal(`fork`),
+	Type.Literal(`schedule`),
+	Type.Literal(`spawn`),
+	Type.Literal(`manage`)
+]);
+const entityPermissionGrantInputSchema = Type.Object({
+	...permissionSubjectSchema.properties,
+	permission: entityPermissionSchema,
+	propagation: Type.Optional(Type.Union([Type.Literal(`self`), Type.Literal(`descendants`)])),
+	copy_to_children: Type.Optional(Type.Boolean()),
+	expires_at: Type.Optional(Type.String())
+}, { additionalProperties: false });
 const spawnBodySchema = Type.Object({
 	args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 	tags: Type.Optional(stringRecordSchema$1),
@@ -4934,6 +5656,7 @@ const spawnBodySchema = Type.Object({
 	dispatch_policy: Type.Optional(dispatchPolicySchema),
 	sandbox: Type.Optional(sandboxChoiceSchema),
 	initialMessage: Type.Optional(Type.Unknown()),
+	grants: Type.Optional(Type.Array(entityPermissionGrantInputSchema)),
 	wake: Type.Optional(Type.Object({
 		subscriberUrl: Type.String(),
 		condition: wakeConditionSchema,
@@ -4955,8 +5678,22 @@ const sendBodySchema = Type.Object({
 	])),
 	position: Type.Optional(Type.String()),
 	afterMs: Type.Optional(Type.Number()),
-	from: Type.Optional(Type.String())
+	from: Type.Optional(Type.String()),
+	from_principal: Type.Optional(Type.String()),
+	from_agent: Type.Optional(Type.String())
 });
+function agentUrlForPrincipal(principal) {
+	if (principal.kind === `agent`) return `/${principal.id}`;
+	if (principal.key.startsWith(`entity:`)) return `/${principal.key.slice(`entity:`.length)}`;
+	return null;
+}
+function agentUrlPath(value) {
+	try {
+		return new URL(value).pathname;
+	} catch {
+		return value;
+	}
+}
 const inboxMessageBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	position: Type.Optional(Type.String()),
@@ -5035,24 +5772,27 @@ const attachmentSubjectTypes = new Set([
 ]);
 const entitiesRouter = Router({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
-entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spawnBodySchema), spawnEntity);
-entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, getEntity);
-entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity);
-entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity);
-entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), signalEntity);
-entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), sendEntity);
-entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, createAttachment);
-entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, readAttachment);
-entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, deleteAttachment);
-entitiesRouter.patch(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withSchema(inboxMessageBodySchema), updateInboxMessage);
-entitiesRouter.delete(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, deleteInboxMessage);
-entitiesRouter.post(`/:type/:instanceId/fork`, withExistingEntity, withSchema(forkBodySchema), forkEntity);
-entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withSchema(setTagBodySchema), setTag);
-entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, deleteTag);
-entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), upsertSchedule);
-entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, deleteSchedule);
-entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), upsertEventSourceSubscription);
-entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, deleteEventSourceSubscription);
+entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spawnBodySchema), withSpawnPermission, spawnEntity);
+entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`read`), getEntity);
+entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`read`), headEntity);
+entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`delete`), killEntity);
+entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), withEntityPermission(`signal`), signalEntity);
+entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), withEntityPermission(`write`), sendEntity);
+entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, withEntityPermission(`write`), createAttachment);
+entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`read`), readAttachment);
+entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`write`), deleteAttachment);
+entitiesRouter.patch(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withSchema(inboxMessageBodySchema), withEntityPermission(`write`), updateInboxMessage);
+entitiesRouter.delete(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withEntityPermission(`write`), deleteInboxMessage);
+entitiesRouter.post(`/:type/:instanceId/fork`, withExistingEntity, withSchema(forkBodySchema), withEntityPermission(`fork`), forkEntity);
+entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withSchema(setTagBodySchema), withEntityPermission(`write`), setTag);
+entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withEntityPermission(`write`), deleteTag);
+entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), withEntityPermission(`schedule`), upsertSchedule);
+entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withEntityPermission(`schedule`), deleteSchedule);
+entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), withEntityPermission(`write`), upsertEventSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withEntityPermission(`write`), deleteEventSourceSubscription);
+entitiesRouter.get(`/:type/:instanceId/grants`, withExistingEntity, withEntityPermission(`manage`), listEntityPermissionGrants);
+entitiesRouter.post(`/:type/:instanceId/grants`, withExistingEntity, withSchema(entityPermissionGrantInputSchema), withEntityPermission(`manage`), createEntityPermissionGrant);
+entitiesRouter.delete(`/:type/:instanceId/grants/:grantId`, withExistingEntity, withEntityPermission(`manage`), deleteEntityPermissionGrant);
 function entityUrlFromSegments(type, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
@@ -5151,6 +5891,17 @@ function rejectPrincipalEntityMutation(request, action) {
 	if (entity.type !== `principal`) return void 0;
 	return apiError(400, ErrCodeInvalidRequest, `Principal entities are built in and cannot be ${action}`);
 }
+function parseExpiresAt$1(value) {
+	if (value === void 0) return void 0;
+	const expiresAt = new Date(value);
+	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
+	return expiresAt;
+}
+function parseGrantId$1(request) {
+	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;
+}
 async function withExistingEntity(request, ctx) {
 	const entityUrl = entityUrlFromSegments(request.params.type, request.params.instanceId);
 	if (!entityUrl) return void 0;
@@ -5181,17 +5932,76 @@ async function withSpawnableEntityType(request, ctx) {
 	if (request.params.type === `principal`) return apiError(400, ErrCodeInvalidRequest, `Principal entities are built in and cannot be spawned directly`);
 	const entityType = await ctx.entityManager.registry.getEntityType(request.params.type);
 	if (!entityType) return apiError(404, ErrCodeUnknownEntityType, `Entity type "${request.params.type}" not found`);
+	request.spawnRoute = { entityType };
 	return void 0;
 }
+function withEntityPermission(permission) {
+	return async (request, ctx) => {
+		const { entity } = requireExistingEntityRoute(request);
+		if (await canAccessEntity(ctx, entity, permission, request)) return void 0;
+		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to ${permission} ${entity.url}`);
+	};
+}
+async function withSpawnPermission(request, ctx) {
+	const parsed = routeBody(request);
+	const entityType = request.spawnRoute?.entityType;
+	if (!entityType) throw new Error(`spawnable entity type middleware did not run`);
+	if (!await canAccessEntityType(ctx, entityType, `spawn`, request)) return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn ${entityType.name}`);
+	if (!parsed.parent) return void 0;
+	const parent = await ctx.entityManager.registry.getEntity(parsed.parent);
+	if (!parent) return apiError(404, ErrCodeNotFound, `Parent entity not found`);
+	if (await canAccessEntity(ctx, parent, `spawn`, request)) return await validateParentedSpawnGrants(request, ctx, parent, parsed);
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn children from ${parent.url}`);
+}
+async function validateParentedSpawnGrants(request, ctx, parent, parsed) {
+	const needsParentManage = (parsed.grants ?? []).some(requiresParentManageForInitialGrant);
+	if (!needsParentManage) return void 0;
+	if (await canAccessEntity(ctx, parent, `manage`, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to delegate broad grants from ${parent.url}`);
+}
+function requiresParentManageForInitialGrant(grant) {
+	return grant.permission === `manage` || grant.subject_kind === `principal_kind` || grant.propagation === `descendants` || grant.copy_to_children === true;
+}
 async function listEntities({ query }, ctx) {
 	const { entities: entities$1 } = await ctx.entityManager.registry.listEntities({
 		type: firstQueryValue$1(query.type),
 		status: firstQueryValue$1(query.status),
 		parent: firstQueryValue$1(query.parent),
-		created_by: firstQueryValue$1(query.created_by)
+		created_by: firstQueryValue$1(query.created_by),
+		readableBy: {
+			...principalSubject(ctx.principal),
+			bypass: isPermissionBypassPrincipal(ctx)
+		}
 	});
 	return json(entities$1.map((entity) => toPublicEntity(entity)));
 }
+async function listEntityPermissionGrants(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const grants = await ctx.entityManager.registry.listEntityPermissionGrants(entityUrl);
+	return json({ grants });
+}
+async function createEntityPermissionGrant(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const parsed = routeBody(request);
+	const grant = await ctx.entityManager.registry.createEntityPermissionGrant({
+		entityUrl,
+		permission: parsed.permission,
+		subjectKind: parsed.subject_kind,
+		subjectValue: parsed.subject_value,
+		propagation: parsed.propagation,
+		copyToChildren: parsed.copy_to_children,
+		expiresAt: parseExpiresAt$1(parsed.expires_at),
+		createdBy: ctx.principal.url
+	});
+	await ctx.entityBridgeManager.onEntityChanged(entityUrl);
+	return json(grant, { status: 201 });
+}
+async function deleteEntityPermissionGrant(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const deleted = await ctx.entityManager.registry.deleteEntityPermissionGrant(entityUrl, parseGrantId$1(request));
+	if (deleted) await ctx.entityBridgeManager.onEntityChanged(entityUrl);
+	return deleted ? status(204) : apiError(404, ErrCodeNotFound, `Grant not found`);
+}
 async function upsertSchedule(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `scheduled`);
 	if (principalMutationError) return principalMutationError;
@@ -5297,6 +6107,7 @@ async function forkEntity(request, ctx) {
 	const result = await ctx.entityManager.forkSubtree(entityUrl, {
 		rootInstanceId: parsed.instance_id,
 		waitTimeoutMs: parsed.waitTimeoutMs,
+		createdBy: ctx.principal.url,
 		...parsed.fork_pointer && { forkPointer: {
 			offset: parsed.fork_pointer.offset,
 			subOffset: parsed.fork_pointer.sub_offset
@@ -5312,26 +6123,27 @@ async function sendEntity(request, ctx) {
 	const parsed = routeBody(request);
 	const principal = ctx.principal;
 	if (parsed.from !== void 0 && parsed.from !== principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from must match Electric-Principal`);
+	if (parsed.from_principal !== void 0 && parsed.from_principal !== principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from_principal must match Electric-Principal`);
+	if (parsed.from_agent !== void 0) {
+		const principalAgentUrl = agentUrlForPrincipal(principal);
+		if (agentUrlPath(parsed.from_agent) !== principalAgentUrl) return apiError(400, ErrCodeInvalidRequest, `Request from_agent must match authenticated agent principal`);
+	}
 	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	const dispatchEntity = entity.dispatch_policy ? entity : await backfillEntityDispatchPolicy(ctx, entity);
 	await linkEntityDispatchSubscription(ctx, dispatchEntity);
-	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, {
+	const sendReq = {
 		from: principal.url,
+		from_principal: principal.url,
+		from_agent: parsed.from_agent,
 		payload: parsed.payload,
 		key: parsed.key,
 		type: parsed.type,
 		mode: parsed.mode,
 		position: parsed.position
-	}, new Date(Date.now() + parsed.afterMs));
-	else await ctx.entityManager.send(entityUrl, {
-		from: principal.url,
-		payload: parsed.payload,
-		key: parsed.key,
-		type: parsed.type,
-		mode: parsed.mode,
-		position: parsed.position
-	});
+	};
+	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, sendReq, new Date(Date.now() + parsed.afterMs));
+	else await ctx.entityManager.send(entityUrl, sendReq);
 	return status(204);
 }
 async function createAttachment(request, ctx) {
@@ -5403,6 +6215,17 @@ async function spawnEntity(request, ctx) {
 		wake: parsed.wake,
 		created_by: principal.url
 	});
+	if (parsed.parent) await ctx.entityManager.registry.copyEntityPermissionGrantsForSpawn(parsed.parent, entity.url, principal.url);
+	for (const grant of parsed.grants ?? []) await ctx.entityManager.registry.createEntityPermissionGrant({
+		entityUrl: entity.url,
+		permission: grant.permission,
+		subjectKind: grant.subject_kind,
+		subjectValue: grant.subject_value,
+		propagation: grant.propagation,
+		copyToChildren: grant.copy_to_children,
+		expiresAt: parseExpiresAt$1(grant.expires_at),
+		createdBy: principal.url
+	});
 	const linkBeforeInitialMessage = parsed.initialMessage !== void 0 && shouldLinkDispatchBeforeInitialMessage(dispatchPolicy);
 	if (linkBeforeInitialMessage) await linkEntityDispatchSubscription(ctx, entity);
 	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(entity.url, {
@@ -5454,6 +6277,12 @@ async function signalEntity(request, ctx) {
 //#region src/routing/entity-types-router.ts
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown());
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema);
+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({
 	name: Type.Optional(Type.String()),
 	description: Type.Optional(Type.String()),
@@ -5461,7 +6290,8 @@ const registerEntityTypeBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
 	state_schemas: Type.Optional(schemaMapSchema),
 	serve_endpoint: Type.Optional(Type.String()),
-	default_dispatch_policy: Type.Optional(dispatchPolicySchema)
+	default_dispatch_policy: Type.Optional(dispatchPolicySchema),
+	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema))
 }, { additionalProperties: false });
 const amendEntityTypeSchemasBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
@@ -5469,20 +6299,56 @@ const amendEntityTypeSchemasBodySchema = Type.Object({
 }, { additionalProperties: false });
 const entityTypesRouter = Router({ base: `/_electric/entity-types` });
 entityTypesRouter.get(`/`, listEntityTypes);
-entityTypesRouter.post(`/`, withSchema(registerEntityTypeBodySchema), registerEntityType);
-entityTypesRouter.patch(`/:name/schemas`, withSchema(amendEntityTypeSchemasBodySchema), amendSchemas);
-entityTypesRouter.get(`/:name`, getEntityType);
-entityTypesRouter.delete(`/:name`, deleteEntityType);
+entityTypesRouter.post(`/`, withSchema(registerEntityTypeBodySchema), withEntityTypeRegistrationPermission, registerEntityType);
+entityTypesRouter.patch(`/:name/schemas`, withExistingEntityType, withEntityTypeManagePermission, withSchema(amendEntityTypeSchemasBodySchema), amendSchemas);
+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, ctx) {
 	const parsed = routeBody(request);
 	const normalized = normalizeEntityTypeRequest(parsed);
 	if (normalized.serve_endpoint && !normalized.description && !normalized.creation_schema) return await discoverServeEndpoint(ctx, normalized);
 	const entityType = await ctx.entityManager.registerEntityType(normalized);
+	await applyRegistrationPermissionGrants(ctx, entityType.name, normalized);
 	return json(toPublicEntityType(entityType), { status: 201 });
 }
 async function listEntityTypes(_request, ctx) {
 	const entityTypes$1 = await ctx.entityManager.registry.listEntityTypes();
-	return json(entityTypes$1.map((entityType) => toPublicEntityType(entityType)));
+	const visible = [];
+	for (const entityType of entityTypes$1) if (await canAccessEntityType(ctx, entityType, `spawn`)) visible.push(entityType);
+	return json(visible.map((entityType) => toPublicEntityType(entityType)));
+}
+async function withExistingEntityType(request, ctx) {
+	const entityType = await ctx.entityManager.registry.getEntityType(request.params.name);
+	if (!entityType) return apiError(404, ErrCodeNotFound, `Entity type not found`);
+	request.entityTypeRoute = { entityType };
+	return void 0;
+}
+async function withEntityTypeManagePermission(request, ctx) {
+	const entityType = request.entityTypeRoute?.entityType;
+	if (!entityType) throw new Error(`entity type middleware did not run`);
+	if (await canAccessEntityType(ctx, entityType, `manage`, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to manage ${entityType.name}`);
+}
+async function withEntityTypeSpawnPermission(request, ctx) {
+	const entityType = request.entityTypeRoute?.entityType;
+	if (!entityType) throw new Error(`entity type middleware did not run`);
+	if (await canAccessEntityType(ctx, entityType, `spawn`, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn ${entityType.name}`);
+}
+async function withEntityTypeRegistrationPermission(request, ctx) {
+	const parsed = normalizeEntityTypeRequest(routeBody(request));
+	if (!parsed.name) return void 0;
+	const existing = await ctx.entityManager.registry.getEntityType(parsed.name);
+	if (existing) {
+		request.entityTypeRoute = { entityType: existing };
+		if (await canAccessEntityType(ctx, existing, `manage`, request)) return void 0;
+		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to manage ${existing.name}`);
+	}
+	if (await canRegisterEntityType(ctx, parsed, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to register entity types`);
 }
 async function discoverServeEndpoint(ctx, parsed) {
 	try {
@@ -5491,17 +6357,17 @@ async function discoverServeEndpoint(ctx, parsed) {
 		const manifest = await response.json();
 		if (manifest.name !== parsed.name) return apiError(400, ErrCodeServeEndpointNameMismatch, `Serve endpoint returned name "${manifest.name}" but expected "${parsed.name}"`);
 		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) throw err;
 		return apiError(502, ErrCodeServeEndpointUnreachable, `Failed to reach serve endpoint: ${err instanceof Error ? err.message : String(err)}`);
 	}
 }
-async function getEntityType(request, ctx) {
-	const entityType = await ctx.entityManager.registry.getEntityType(request.params.name);
-	if (!entityType) return apiError(404, ErrCodeNotFound, `Entity type not found`);
-	return json(toPublicEntityType(entityType));
+async function getEntityType(request) {
+	return json(toPublicEntityType(request.entityTypeRoute.entityType));
 }
 async function amendSchemas(request, ctx) {
 	const parsed = routeBody(request);
@@ -5515,6 +6381,47 @@ async function deleteEntityType(request, ctx) {
 	await ctx.entityManager.deleteEntityType(request.params.name);
 	return status(204);
 }
+async function listTypePermissionGrants(request, ctx) {
+	const grants = await ctx.entityManager.registry.listEntityTypePermissionGrants(request.entityTypeRoute.entityType.name);
+	return json({ grants });
+}
+async function createTypePermissionGrant(request, ctx) {
+	const parsed = routeBody(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, ctx) {
+	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, entityType, request) {
+	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) {
+	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) {
+	if (value === void 0) return void 0;
+	const expiresAt = new Date(value);
+	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
+	return expiresAt;
+}
 function normalizeEntityTypeRequest(parsed) {
 	const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint);
 	return {
@@ -5527,7 +6434,8 @@ function normalizeEntityTypeRequest(parsed) {
 		default_dispatch_policy: parsed.default_dispatch_policy ?? (serveEndpoint ? { targets: [{
 			type: `webhook`,
 			url: serveEndpoint
-		}] } : void 0)
+		}] } : void 0),
+		permission_grants: parsed.permission_grants
 	};
 }
 function toPublicEntityType(entityType) {
@@ -5586,6 +6494,7 @@ function applyCors(response) {
 		`content-type`,
 		`authorization`,
 		`electric-claim-token`,
+		`electric-owner-entity`,
 		ELECTRIC_PRINCIPAL_HEADER,
 		`ngrok-skip-browser-warning`
 	].join(`, `));
@@ -5636,7 +6545,7 @@ observationsRouter.post(`/entities/ensure-stream`, withSchema(ensureEntitiesMemb
 observationsRouter.post(`/cron/ensure-stream`, withSchema(ensureCronStreamBodySchema), ensureCronStream);
 async function ensureEntitiesMembershipStream(request, ctx) {
 	const parsed = routeBody(request);
-	const result = await ctx.entityManager.ensureEntitiesMembershipStream(parsed.tags ?? {});
+	const result = await ctx.entityManager.ensureEntitiesMembershipStream(parsed.tags ?? {}, ctx.principal);
 	return json(result);
 }
 async function ensureCronStream(request, ctx) {
@@ -6515,16 +7424,31 @@ function buildTagsWhereClause(tags) {
 function sqlStringLiteral$1(value) {
 	return `'${value.replace(/'/g, `''`)}'`;
 }
-function buildTenantTagsWhereClause(tenantId, tags) {
-	return `tenant_id = ${sqlStringLiteral$1(tenantId)} AND (${buildTagsWhereClause(tags)})`;
+function buildTenantTagsWhereClause(tenantId, tags, principalUrl$1, principalKind, permissionBypass) {
+	const readableWhere = principalUrl$1 && principalKind ? buildReadableEntitiesWhere({
+		tenantId,
+		principalUrl: principalUrl$1,
+		principalKind,
+		permissionBypass
+	}) : `tenant_id = ${sqlStringLiteral$1(tenantId)} AND FALSE`;
+	return `${readableWhere} AND (${buildTagsWhereClause(tags)})`;
 }
 function shapeEntityKey(message) {
 	return message.value.url;
 }
+function principalScopedSourceRef(tagSourceRef, principalUrl$1, principalKind) {
+	return `${tagSourceRef}-${hashString(JSON.stringify({
+		principalKind,
+		principalUrl: principalUrl$1
+	}))}`;
+}
 var EntityBridge = class {
 	sourceRef;
 	tags;
 	streamUrl;
+	principalUrl;
+	principalKind;
+	permissionBypass;
 	currentMembers = new Map();
 	producer = null;
 	liveAbortController = null;
@@ -6541,6 +7465,9 @@ var EntityBridge = class {
 		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;
 	}
@@ -6648,7 +7575,7 @@ var EntityBridge = class {
 			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`
@@ -6811,15 +7738,17 @@ var EntityBridgeManager = class {
 			await bridge.stop();
 		}));
 	}
-	async register(tagsInput) {
+	async register(tagsInput, principalUrl$1, principalKind) {
 		if (!this.electricUrl) throw new Error(`[entity-bridge] Electric URL is required for entities()`);
 		const tags = normalizeTags(assertTags(tagsInput));
-		const sourceRef = sourceRefForTags(tags);
+		const sourceRef = principalScopedSourceRef(sourceRefForTags(tags), principalUrl$1, principalKind);
 		const streamUrl = getEntitiesStreamPath(sourceRef);
 		const row = await this.registry.upsertEntityBridge({
 			sourceRef,
 			tags,
-			streamUrl
+			streamUrl,
+			principalUrl: principalUrl$1,
+			principalKind
 		});
 		await this.registry.touchEntityBridge(sourceRef);
 		await this.ensureBridge(row);
@@ -7639,6 +8568,8 @@ var ElectricAgentsTenantRuntime = class {
 		try {
 			await this.manager.send(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
@@ -7711,6 +8642,7 @@ var ElectricAgentsTenantRuntime = class {
 		await this.scheduler.syncManifestDelayedSend(ownerEntityUrl, manifestKey, {
 			entityUrl: targetUrl,
 			from: senderUrl,
+			from_agent: senderUrl,
 			payload: value.payload,
 			key: `scheduled-${producerId}`,
 			type: typeof value.messageType === `string` ? value.messageType : void 0,
@@ -7735,11 +8667,20 @@ var ElectricAgentsTenantRuntime = class {
 	async applyManifestEntitySource(ownerEntityUrl, manifestKey, operation, value) {
 		const sourceRef = operation === `delete` ? void 0 : this.extractEntitiesSourceRef(value);
 		await this.manager.registry.replaceEntityManifestSource(ownerEntityUrl, manifestKey, sourceRef);
+		const sharedStateId = operation === `delete` ? void 0 : this.extractSharedStateId(value);
+		await this.manager.registry.replaceSharedStateLink(ownerEntityUrl, manifestKey, sharedStateId);
 	}
 	extractEntitiesSourceRef(manifest) {
 		if (manifest?.kind === `source` && manifest.sourceType === `entities` && typeof manifest.sourceRef === `string`) return manifest.sourceRef;
 		return void 0;
 	}
+	extractSharedStateId(manifest) {
+		if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) return manifest.id;
+		if (manifest?.kind !== `source` || manifest.sourceType !== `db`) return void 0;
+		if (typeof manifest.sourceRef === `string`) return manifest.sourceRef;
+		const config = typeof manifest.config === `object` && manifest.config !== null && !Array.isArray(manifest.config) ? manifest.config : void 0;
+		return typeof config?.id === `string` ? config.id : void 0;
+	}
 	async maybeMarkEntityIdleAfterRunFinished(entityUrl) {
 		const primaryStream = `${entityUrl}/main`;
 		const callbacks = await this.db.select().from(consumerCallbacks).where(and(eq(consumerCallbacks.tenantId, this.serviceId), eq(consumerCallbacks.primaryStream, primaryStream))).limit(1);
@@ -8420,6 +9361,8 @@ var WakeRegistry = class {
 		if (eventType === `inbox`) {
 			const value = event.value;
 			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;
@@ -8770,6 +9713,7 @@ var ElectricAgentsServer = class {
 			entityBridgeManager: this.entityBridgeManager,
 			...this.options.eventSources ? { eventSources: this.options.eventSources } : {},
 			...this.options.ensureEventSourceWakeSource ? { ensureEventSourceWakeSource: this.options.ensureEventSourceWakeSource } : {},
+			...this.options.authorizeRequest ? { authorizeRequest: this.options.authorizeRequest } : {},
 			isShuttingDown: () => this.shuttingDown,
 			mockAgent: this.mockAgentBootstrap ? { runtime: this.mockAgentBootstrap.runtime } : void 0
 		};