Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Apr 20, 2026 · 3 revisions

AgentKeys — Wiki

This wiki is auto-generated from the wiki/ folder in the main repo. Edit the source files there, not through the web UI — direct edits will be overwritten on the next push to main. The canonical source is wiki/ in litentry/agentKeys.

AgentKeys is a credential custody service: a TEE-backed vault that issues long-lived bearer tokens for per-agent credential access, with on-chain audit. We mint ephemeral credentials; daemons use them to call remote services directly. Credential broker, not operation proxy.

The four rules

Every spec and every service on top of AgentKeys preserves these four invariants (details in Blockchain TEE Architecture §6):

  1. Chain stores everything persistent — single source of truth.
  2. TEE holds all private keys and does all computation — no key leaves the enclave.
  3. Clients hold only a JWT, not private keys — bearer tokens, short blast radius.
  4. AgentKeys brokers credentials, not operations — daemons call remote services directly; our compute scales with user count, not operation frequency.

Wiki tree

Foundations (canonical, published wiki)

Credential lifecycle (canonical, published wiki)

Service architectures (published wiki, Stage 6/7)

Design docs for specific services built on top of the foundations:

  • Overview — tree + reading order for the service-architecture pages
  • Hosted-First — Stage 6 default (xyz@agentkeys-email.io on our infra) vs bring-your-own (advanced)
  • Tag-Based Access — agentkeys_user_wallet JWT claim → AWS PrincipalTag → per-user isolation on shared buckets
  • OIDC Federation — TEE as a conforming OIDC issuer; one ES256 key federates into AWS / GCP / Azure / Ali / K8s
  • Email System — Stage 6 email architecture on AWS SES; broker-not-proxy; zero per-operation compute
  • Knowledge Storage — deferred backend decision between GitHub / AWS S3 / Google Drive / Ali Cloud OSS, by user segment

Reading order by role

Role Start here Then Then
New engineer Blockchain TEE Architecture Session Token Email System
Product / roadmap This page, §Wiki tree docs/spec/plans/development-stages.md Hosted-First
Operator / infra Key Security, Serve and Audit docs/spec/ses-email-architecture.md OIDC Federation §Consumer-registration recipes
Security reviewer Blockchain TEE Architecture §6 (four rules) Data Classification Tag-Based Access §Security and attacker surface

Specs (outside the wiki)

Canonical design records live in docs/spec/:

  • docs/spec/plans/development-stages.md — build plan. Stages 0–5 shipped; Stage 6 = federated own email; Stage 7 = generalized OIDC provider; remaining stages postponed.
  • docs/spec/ses-email-architecture.md — Stage 6 SES email spec.
  • docs/spec/email-signing-backends.md — generalized backend comparison (SES / DWD / SaaS).
  • docs/spec/credential-backend-interface.md — the CredentialBackend trait.
  • docs/spec/architecture.md — 13-component system architecture.
  • docs/spec/heima-gaps-vs-desired-architecture.md — living gap list: where current upstream litentry/heima differs from what the wiki describes (HDKD master seed, OIDC provider, BYODKIM, email pallets, session-tag propagation).

Demo / operator docs:

  • docs/manual-test-stage4.md — Stage 4 end-to-end walkthrough
  • docs/manual-test-stage5.md — Stage 5 demo (dedicated-Gmail quick path)
  • docs/stage5-workspace-email-setup.md — advanced BYO Workspace runbook (deferred past Stage 7)
  • docs/contradictions.md — living tracker of cross-doc contradictions

How to edit this wiki

  1. Open wiki/<Page>.md in the main repo.
  2. Make changes in a PR.
  3. Merge to main.
  4. The Publish wiki GitHub Action mirrors wiki/** to the wiki repo.

A maintainer can also trigger the mirror manually from the repo's Actions tab — the workflow exposes workflow_dispatch.

See .github/workflows/publish-wiki.yml for the implementation.

Clone this wiki locally