RFC: Add principals as first-class entities

オープン
#4,306 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
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 の本文から書いたものです。

説明

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 はありません

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

electric-sql/electric のほかの issue

electric-sql/electric の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。