RFC: Add principals as first-class entities
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 30/100
- issue の種類
- 機能追加
- 明瞭さ
- 説明が足りない
- 活発さ
- 静か
- 技術スタック
- typescript
調査の方向性
まず、asserted identity headers と created_by tagging を導入する #4305 を読み、続いて 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 ファイルなし
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- 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 ·
-
Listen IP addressオープンfeature request triage
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
electric-sql/electric#4150 · コメント 1 件 ·
electric-sql/electric の issue をすべて見る
似ている issue
-
clawsweeper:fix-shape-clear clawsweeper:queueable-fix clawsweeper:source-repro impact:ux-friction issue-rating: 🦞 diamond lobster no-stale P2
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
openclaw/openclaw#199885 · コメント 2 件 · リアクション 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
-
feature needs-triage
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
BoardGamesEmpire/board-games-empire-backend#1306 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100
sequant-io/sequant#1689 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100