RFC: Add principals as first-class entities
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 30/100
- Issue type
- Feature
- Clarity
- Needs clarification
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- authorization, backend-api-design
Research direction
Start by reading #4305, which introduces asserted identity headers and created_by tagging, then review the dialectic artifacts under signals/dialectic-darix-auth. Use the RFC's open questions to define the principal entity, header trust, bootstrap, and cleanup behavior; done means the principal design is resolved enough to implement consistently.
Written by the indexing model from the issue text.
Description
Summary
Add principals as a first-class entity type so that every action in the agents system traces to an owning identity. This provides the foundation for per-user agent sessions, auditing, observability, and (later) capability-based authorization.
Builds on #4305 which introduces asserted identity headers and created_by tagging for desktop dispatch.
Motivation
Today the agents system has no concept of "who" — entities have write_token for mutation auth and a free-form from string on messages, but there's no structured identity that links agents to users, enables per-user observability, or supports multi-principal isolation.
Without principals you can't build basics like:
- An app showing all of a user's agent sessions
- Audit logs of which user triggered which agent actions
- Multi-tenant isolation where different users' agents are separated
- Per-user rate limiting or quota enforcement
Three target use cases
Personal system — Single user, everything allowed, zero auth config. Principals exist for observability but impose no restrictions.
Software factory — Multiple engineers with individual accounts, automation agents, CI bots. Different principals see different things. Misbehaving agents are contained by the tools they're given.
Customer success app — External auth (Clerk, Better Auth, enterprise SSO) handles identity. Per-customer authorization expressed through what tools/functions the handler exposes based on the authenticated principal.
Design
Principals are entities
Addressed at /principal/{type}:{id} (e.g., /principal/user:kyle, /principal/agent:ci-bot). The principal entity type is built-in. The stream IS the principal — identity, inbox, state, and (eventually) capabilities are collections on the same stream.
Principal types:
user:— human usersagent:— automation agents owned by a userservice:— system integrations (CI, webhooks)system:— framework-level principals (cron, default)
Type is part of the ID, follows SPIFFE/IAM convention.
Identity via header
Inbound requests carry the principal in a header (e.g., X-Electric-Principal: user:kyle). The integrator's edge (reverse proxy, gateway, auth middleware) authenticates the user and sets the header. The agents server trusts the header.
Dev mode: Falls back to dev:local when the header is absent, so personal-system use cases work with zero config.
Lazy materialization: First sight of a principal creates its entity stream. No upfront registration required.
Agents owned by principals
Every agent records its owning principal at spawn time (created_by). This enables:
- Querying all agents belonging to a user
- Cascading cleanup when a principal is removed
- Audit trail linking agent actions to the initiating user
Authorization via handler & tools
For v1, authorization is encoded at the handler level — the integrator decides what tools and functions to expose to each agent based on the principal context. The handler can load auth rules from an external API (e.g., check a permissions service, query your database, call Clerk's API) to decide what to include in the agent's tool set.
// Example: handler scopes tools based on principal
export default defineHandler({
async handle(ctx) {
const principal = ctx.principal; // { type: "user", id: "kyle" }
// Load permissions from your auth system
const perms = await myAuthAPI.getPermissions(principal.id);
// Only give the agent tools it's allowed to use
const tools = [];
if (perms.canReadDocs) tools.push(readDocsTool);
if (perms.canSendMessages) tools.push(sendMessageTool);
if (perms.isAdmin) tools.push(adminTool);
return runAgent({ tools, ...ctx });
}
});
This keeps authorization flexible and application-specific without the framework needing to own an auth model. The framework provides the principal identity; the integrator decides what that identity can do.
Inter-principal messaging
ctx.send("/principal/user:bob", msg) writes to Bob's inbox collection. Same verb whether the target is a user, agent, or service. Authorization for cross-principal messaging is handler-level (the integrator decides whether to include send in the agent's tools).
Future work (not in this RFC)
These are known future layers that this design should not preclude:
- Public sharing links / signed URLs — Serializable scoped authority for read-only (or scoped) access via URL. HMAC-signed, short-expiry. Needed fairly soon for sharing agent sessions, read-only dashboards, etc.
- Capability expressions in entity streams — A runtime-evaluated expression language for per-resource, per-principal authorization conditions (time-based, relationship-based, context-based). Stored in principal entity streams, materialized in Postgres for querying.
- Named capability sets — Conventional names like
viewer/editor/admindefined as macros over capability expressions, providing an adoptable entry point that integrators can outgrow. - Monotonic capability decrease on delegation — When an agent spawns a sub-agent, the child's authority is provably a subset of the parent's.
- Cross-principal policy — Framework-level rules for inter-principal communication (can agent owned by Alice message Bob?).
These can be layered on incrementally because principals + entity streams are already the substrate.
Open questions
- Header name:
X-Electric-Principal?X-Electric-User? Align with #4305'sX-Electric-Asserted-*headers? - Principal entity handler: What built-in collections does a principal stream have? (inbox, log, state, capabilities?)
- Trust boundary for self-hosted: Managed Electric Cloud can enforce header trust via infrastructure. Self-hosted needs guidance — bind to localhost by default? Require explicit
trustHeadersconfig? - System principal bootstrap: How do
system:cron,system:defaultget created at startup? - Principal GC: When an upstream user is deleted, what happens to their principal stream, owned agents, and spawned entities?
Context
This design emerged from a structured analysis of authorization approaches for the agents framework (dialectic artifacts). The key finding: ship principals + headers + tool-level constraints now, let capability machinery emerge from actual usage patterns rather than designing it in advance.
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 399
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryOpen
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valuePossibly taken @Tyagiquamar claimed this 19 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Possibly taken @mohanedmoh claimed this 37 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4826 · 1 comment ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakePossibly taken @adityavkk claimed this 133 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
electric-sql/electric#4687 ·
-
Listen IP addressOpenfeature request triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
electric-sql/electric#4150 · 1 comment ·
All issues in electric-sql/electric
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
"code source" and "numerique.gouv" links: "new window" mention duplicated in the accessible nameOpenaccessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
numerique-gouv/lasuite-landingpage#315 ·
Maintainers usually reply within 1 day
-
needs:triage
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
HyeokjaeChoi/vaultme#585 ·
Maintainers usually reply within 1 day
-
enhancement priority/P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
beettlle/pi-smart-router#200 ·