docs(stage6): federated-email roadmap + broker-not-proxy rule #4 + architecture specs#48
Merged
hanwencheng merged 5 commits intomainfrom Apr 20, 2026
Conversation
…chitecture specs Architectural core ------------------ - wiki/blockchain-tee-architecture.md §6 retitled to "Summary: the four rules"; adds Rule #4 (credential broker, not operation proxy). Our infrastructure mints ephemeral credentials; daemons call remote services directly. No per-operation compute on our side. This rule is why the email, knowledge- base, and OIDC-federation designs refuse to build SaaS-shape proxies. - wiki/Home.md rewritten as a tree-structured index: four rules up front, foundations / credential-lifecycle / service-architecture groupings, and a reading-order matrix by role. Stage 5–7 roadmap ----------------- - docs/spec/plans/development-stages.md: new "Stage 5–7 roadmap update" section near the top. - Stage 5 (quick email demo) stays current - Stage 6 = federated own-email on @agentkeys-email.io (hosted SES + TEE- held Ed25519 DKIM + ES256 OIDC issuer + PrincipalTag isolation) - Stage 7 = generalized OIDC provider (oidc.agentkeys.dev federates into AWS/GCP/Azure/Ali/K8s) - Old Stage 6/7/8/9 sections renamed POSTPONED, preserved inline for reference Architecture specs (new) ------------------------ - docs/spec/ses-email-architecture.md (368 lines) — Stage 6 email spec under the broker-not-proxy shape. SES → S3 direct drop for inbound (no Lambda); daemon calls SES via minted creds for outbound; PrincipalTag isolation on a shared bucket; TEE-derived Ed25519 DKIM + ES256 OIDC keys; data model trimmed to just Inbox + Domain on our side. - docs/spec/email-signing-backends.md (525 lines) — generalized three-layer backend comparison (Google Workspace DWD / AgentKeys TEE / AgentMail SaaS), with AWS OIDC docs verified for algorithm support (ES256, not Ed25519). - docs/stage5-workspace-email-setup.md (471 lines) — BYO Google Workspace DWD runbook, prominently flagged as ADVANCED / deferred past Stage 7 for enterprise deployments that want to reuse an existing Workspace subscription. Stage 5 demo updated -------------------- - docs/manual-test-stage5.md §1 rewritten: dedicated-personal-Gmail + TOTP + app password is now the recommended quickstart (~10 min, zero code changes, reuses existing imapflow path). Workspace DWD and plus-addressing preserved as collapsed alternatives. - harness/stage-5a-done.sh reworked: 8-step non-live gate with colored banners, covers Rust + TS unit tests + phantom-chaos + grep guard + typecheck + clippy + MCP registration + observability metrics, ~90s end-to-end. Session-scratchpad not in this commit ------------------------------------- The project-local `.omc/wiki/` architecture pages (overview, hosted-first, tag-based-access, oidc-federation, email-system, knowledge-storage) that fed this spec round are git-ignored and stay local. They are informally referenced from the committed docs and wiki Home.md, but are not shipped.
Wiki now consistently describes the desired architecture: - blockchain-tee-architecture.md §1 TEE-internal-keys table lists a sealed master seed at the top and marks every long-lived subkey (shielding, issuer JWT, per-user wallet, per-domain DKIM) as SLIP-0010 HDKD-derived. - Rule #2 in §6 re-anchored on the same model. - session-token.md JWT-signing-key section follows the same story and adds the ES256 path needed for AWS OIDC in Stage 7. New docs/spec/heima-gaps-vs-desired-architecture.md captures the six deltas between upstream litentry/heima today and what the wiki describes: key-derivation model, OIDC provider, BYODKIM, email pallets, session-tag propagation, attested pubkey publication. Each gap has current/desired/impact/migration-path sections and flags whether it blocks Stage 6, Stage 7, or neither.
The dev-stages doc (and others) referenced Obsidian-style [[hosted-first]] wiki-links pointing into .omc/wiki/, which is git-ignored and lives only on the author's machine. Readers on GitHub saw the reference with nothing behind it. Move the six content pages from .omc/wiki/ to wiki/ so the mirrored GitHub wiki publishes them: - wiki/hosted-first.md - wiki/oidc-federation.md - wiki/tag-based-access.md - wiki/knowledge-storage.md - wiki/email-system.md - wiki/overview.md Inside each page, convert [[foo]] wiki-links to [foo](foo) Markdown links (GitHub's Markdown doesn't resolve double-bracket syntax). Update every external reference: - wiki/Home.md: drop the ".omc/wiki/ — not published" section, relink the reading-order matrix to published paths. - wiki/blockchain-tee-architecture.md Rule #4: tag-based-access wiki link. - docs/spec/plans/development-stages.md: all [[foo]] (wiki) refs become ../../../wiki/foo.md Markdown links. - docs/spec/ses-email-architecture.md: same, relative ../../wiki/. - docs/spec/heima-gaps-vs-desired-architecture.md: same. - docs/manual-test-stage5.md: ../.omc/wiki/ -> ../wiki/. - docs/stage5-workspace-email-setup.md: same. .omc/wiki/{index,log}.md stay — they're LLM-wiki tooling artifacts, not content.
Audited the 6 newly-promoted wiki pages (email-system, hosted-first,
knowledge-storage, oidc-federation, overview, tag-based-access) against
blockchain-tee-architecture.md and docs/spec/heima-gaps-vs-desired-architecture.md.
Found 12 deltas. Resolutions applied:
A1 oidc issuer URL typo `oidc.agentkeys.io` -> `.dev` in heima-gaps.
A2 email-system isolation diagram mailbox domain switched from the old
`bots.wildmeta.ai` to the canonical `agentkeys-email.io`.
A3 Same domain sweep across ses-email-architecture.md and
manual-test-stage5.md.
A4 oidc-federation.md: "three architectural rules" -> "four"
(rule #4 broker-not-proxy is now canonical).
A5 knowledge-storage.md: same rule-count fix + folded the "Rule #4
candidate" note into the main alignment list.
A6 Removed the duplicate H1 heading (wiki-ingest artifact) on
hosted-first.md, tag-based-access.md, knowledge-storage.md.
B1+B2 Session-JWT key and OIDC-issuer key are now TWO SEPARATE keys,
both ES256. Session-JWT at `issuer/jwt/v1` (internal trust anchor,
not on public JWKS). OIDC-issuer at `oidc/issuer/v1` (public JWKS
at oidc.agentkeys.dev). Separation isolates AWS-cache-driven OIDC
rotations from session-token invalidation. Updated:
- wiki/blockchain-tee-architecture.md §1 table (one row -> two)
- wiki/blockchain-tee-architecture.md §6 rule #2
- wiki/session-token.md alg + separation note
- docs/spec/heima-gaps-vs-desired-architecture.md §2 table + §3 text
B3 email-system.md "AWS_SES-managed DKIM" was a direct violation of
rule #2. Flipped to TEE-held Ed25519 BYODKIM (`dkim/<domain>/v1`)
consistent with every other page.
B4 heima-gaps §6 claim value: was `agentkeys_user_wallet = omni_account`;
reconciled to child wallet with a note that the claim name is
historical. Per-agent blast-radius bounding is the reason.
B5 OIDC `sub` format now consistently includes mrsigner:
`enclave:<mrenclave>:<mrsigner>:agent:<child>` across tag-based-access
+ knowledge-storage. Added §"Why three segments in `sub`" explaining
the three pin-modes (strict mrenclave / loose mrsigner / explicit
both) that this unlocks for relying-party trust policies.
B6 blockchain-tee-architecture rule #3 TTL corrected from "~24h" to
the canonical 30d, and added a brief three-TTL layering note
(30d session bearer / 5-min OIDC JWT / 1h cloud temp creds).
…y reorg
Wraps up the design rounds since the last docs update. Four threads
landing together:
1. Stage 7 revision + new Stage 7b in the development plan.
Stage 7 (generalized OIDC provider) now explicitly documents that
its cryptographic trust anchor is URL + TLS + JWKS signature, with
AWS thumbprint pinning / CAA / DNSSEC / short-TTL JWT as the
baseline hardening stack. `sub`-pattern pinning is presented as
informational-by-default; MRENCLAVE/MRSIGNER pinning is opt-in with
a documented rotation cost.
New Stage 7b (one-sprint follow-on): pallet-oidc-pubkeys +
off-chain watchdog + daemon-side dual-verify for AgentKeys-owned
accounts. Collapses URL-hijack blast window from indefinite to
30-60s for foreign clouds; closes it entirely for our own infra.
Full stage contract, tests, E2E checklist, and deferred items.
2. New required interfaces in heima-gaps.
§8 pallet-oidc-pubkeys: on-chain authoritative OIDC-pubkey
registry. Extrinsics register_oidc_key (TEE-origin) and
revoke_oidc_key (governance), query active_oidc_keys().
Mock-server HTTP mirror at /mock/oidc-pubkeys/*.
§9 pallet-enclave-successors: governance-gated authorized-MRSIGNER
list used by the attested seed handoff during MRSIGNER rotation.
Mock mirror at /mock/enclave-successors/*.
Tracking section renumbered to §10.
3. Security reorg in blockchain-tee-architecture.md.
New §7 "Security model: assumptions and attacker surface"
consolidating:
- 7.1 seven foundational assumptions we take as given
- 7.2 what each of the four rules defends (and what compromise
looks like under each)
- 7.3 attacker-surface matrix by attack class (bearer theft, TEE
compromise, chain attack, OIDC URL hijack, malicious enclave
build, bearer replay, prefix-crossing, insider, registrar
compromise) with net capability without mitigation + the
mitigation we ship
- 7.4 the TEE-extraction disaster-recovery case, explicit
- 7.5 three routine rotation procedures (OIDC-issuer,
session-JWT, MRSIGNER), each cheap under HDKD
- 7.6 pointers to narrower surfaces (key-security, email-system,
tag-based-access, oidc-federation)
References renumbered to §8.
Added §10 to key-security.md summarizing how its client-side model
interacts with the new server-side threat model (they defend
against different adversaries and are additive; neither replaces
the other).
4. docs/spec/post-v0.1-future-work.md (new).
Living backlog for items beyond v0.1:
- OIDC hardening: TEE-hosted endpoint, chain-native relying
parties, on-chain TLS cert fingerprints, per-tenant issuer keys
- MRSIGNER rotation CLI + IaC auto-rotation
- Daemon Priority C hardening (landlock, namespaces, repro builds)
- Knowledge-base backend expansions (Dropbox/Box/OneDrive, IPFS)
- Email follow-ups (token-authority-model spec, 2FA flow, BYO
custom-domain runbook)
- Enterprise integrations (SAML, SCIM, SSO-into-master-CLI)
- Protocol research (K8s audience, x402 payments, attested audit
feed)
- Explicit graveyard of rejected ideas
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A coherent round of architectural clarification that (a) names the credential-broker-not-operation-proxy principle as Rule #4 in the canonical architecture wiki, (b) reorganizes the stage roadmap around that principle with Stage 6 = federated own-email on
@agentkeys-email.ioand Stage 7 = generalized OIDC provider, and (c) lands three architecture specs (SES email, backend comparison, BYO Workspace runbook) that make the roadmap concrete.+1862 / −385 across 8 files.
What changed
Architectural core
wiki/blockchain-tee-architecture.md§6 retitled to "Summary: the four rules". Adds Rule v0.1: TEE-side per-session read rate limit (abuse defense) #4 (credential broker, not operation proxy): our infrastructure mints ephemeral credentials; daemons call remote services directly. No per-operation compute on our side. Compute scales with user count, not operation frequency. This rule is what prevents the email, knowledge-base, and OIDC-federation designs from sliding into SaaS-shape proxies.wiki/Home.mdrewritten as a tree-structured index: four rules up front, then foundations → credential-lifecycle → service-architecture groupings, then a reading-order matrix by role (engineer / PM / operator / security reviewer).Stage 5–7 roadmap
docs/spec/plans/development-stages.mdgains a "Stage 5–7 roadmap update" near the top:agentkeys-email.io(hosted SES + TEE-held Ed25519 DKIM + ES256 OIDC issuer + PrincipalTag-based per-user isolation)oidc.agentkeys.devfederates into AWS / GCP / Azure / Ali Cloud / Kubernetes)POSTPONED, content preserved inline for referenceArchitecture specs (new)
docs/spec/ses-email-architecture.md(368 lines) — Stage 6 email spec under the broker-not-proxy shape. SES → S3 direct drop for inbound (no Lambda, no MIME parsing, no metadata DB); daemon calls SES via minted creds for outbound; PrincipalTag isolation on a shared bucket; TEE-derived Ed25519 DKIM + ES256 OIDC keys. Data model trimmed to justInbox+Domainon our side — threading/labels/drafts/webhooks live daemon-side.docs/spec/email-signing-backends.md(525 lines) — generalized three-layer backend comparison (Google Workspace DWD / AgentKeys TEE / AgentMail SaaS). AWS OIDC docs verified verbatim for algorithm support (ES256 is the ceiling; Ed25519 not accepted for OIDC federation).docs/stage5-workspace-email-setup.md(471 lines) — BYO Google Workspace DWD runbook, prominently flagged as ADVANCED / deferred past Stage 7. Preserved for enterprise deployments that want to reuse an existing Workspace subscription.Stage 5 demo updated
docs/manual-test-stage5.md§1 rewritten: dedicated-personal-Gmail + TOTP + app password is now the recommended quickstart (~10 min, zero code changes, reuses existingimapflowpath). Workspace DWD and plus-addressing preserved as collapsed alternatives.harness/stage-5a-done.shreworked: 8-step non-live gate with colored banners. Covers Rust + TS unit tests + phantom-chaos + grep guard + typecheck + clippy + MCP registration + observability metrics. ~90 s end-to-end.Four-rules reading
Every service spec in this round cites the same architectural invariant chain:
Rule #4 is the lens that keeps Stage 6 from drifting into AgentMail-shape SaaS. The SES spec explicitly does not build: Lambda-based MIME parsing, server-side threading, drafts, label stores, webhook fan-out, or any per-operation backend surface. Those concerns live daemon-side or don't exist.
Test plan
bash -n harness/stage-5a-done.shcleanbash harness/stage-5a-done.shpasses end-to-end (STAGE 5a PASSED; 8 steps green, ~90 s)docs/manual-test-stage5.mddedicated-Gmail quickstart is valid: signup → 2FA+TOTP → app password → env vars → existingimapflowpath runswiki/blockchain-tee-architecture.md§6 reads as four rules, internally consistent with prior three; no prior citation of "rule v0.1: TEE-side per-session read rate limit (abuse defense) #4" in the codebase now has a hanging referencewiki/Home.mdtree renders cleanly; links todocs/spec/*and canonical wiki pages resolveProject-local scratchpad not in this commit
The design round was supported by six project-local architecture pages under
.omc/wiki/(overview, hosted-first, tag-based-access, oidc-federation, email-system, knowledge-storage)..omc/is git-ignored; those pages stay local per AgentKeys convention and are informally referenced from the committed specs/wiki, but are not shipped in this PR.🤖 Generated with Claude Code