RFC: Add principals as first-class entities
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 30/100
- Issue 类型
- 功能
- 描述清晰度
- 需要澄清
- 活跃度
- 冷清
- 技术栈
- typescript
调研方向
先阅读 #4305,其中介绍了 asserted identity headers 和 created_by 标记,然后查看 signals/dialectic-darix-auth 下的 dialectic artifacts。使用 RFC 中的开放问题来定义 principal entity、header trust、bootstrap 和 cleanup 的行为;完成意味着 principal 设计已经解决到足以一致实现的程度。
由索引模型根据 Issue 内容生成。
描述
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.
- 主要语言
- TypeScript
- 星标
- 10.4k
- 派生
- 399
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
electric-sql/electric 的其他 Issue
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundary未关闭
难度 2/5 1-3 小时 新手友好度 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error value可能已有人在做 @Tyagiquamar 于 19 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)可能已有人在做 @mohanedmoh 于 37 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 72/100
electric-sql/electric#4826 · 1 条评论 ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wake可能已有人在做 @adityavkk 于 133 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 78/100
electric-sql/electric#4687 ·
-
feature request triage
难度 2/5 1-3 小时 新手友好度 68/100
electric-sql/electric#4150 · 1 条评论 ·
查看 electric-sql/electric 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 82/100
software-mansion/argent#1946 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 63/100
podman-desktop/podman-desktop#20216 ·
维护者通常 1 天内回复
-
[Type] Bug
难度 2/5 1-3 小时 新手友好度 76/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 5 天内回复
-
难度 2/5 1-3 小时 新手友好度 65/100
omdsh-dev/DSH-better-sidebar#1205 ·
维护者通常 3 天内回复