RFC: Add principals as first-class entities

未关闭
#4,306 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 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 内容生成。

描述

feature

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 users
  • agent: — automation agents owned by a user
  • service: — 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/admin defined 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

  1. Header name: X-Electric-Principal? X-Electric-User? Align with #4305's X-Electric-Asserted-* headers?
  2. Principal entity handler: What built-in collections does a principal stream have? (inbox, log, state, capabilities?)
  3. 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 trustHeaders config?
  4. System principal bootstrap: How do system:cron, system:default get created at startup?
  5. 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 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

electric-sql/electric 的其他 Issue

查看 electric-sql/electric 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。