docs(architecture): ADR-0008 — session-to-egress attribution by presented token

[Yambr]

Supersedes the closed #235, which mis-modelled the mechanism (it keyed egress attribution on a host-attested network fact — netns/peer-credentials/vsock CID). That conflated guest isolation (host↔guest channel, NFR-SEC-43) with egress session attribution.

Decision

Because the trust-edge bump-terminates TLS (the guest trusts the per-deployment CA's root in its trust store), Envoy holds the plaintext request and attributes it to its session by the session token presented at L7 — via the native Envoy chain:

jwt_authn → ext_authz → rbac → ratelimit → credential_injector → router

• jwt_authn verifies the token, writes the session claim to metadata
• ext_authz consults the denylist (revoked session?), ratelimit bounds the session
• credential_injector attaches the SDS-delivered upstream credential

Injection stays gated on the presented token by filter ORDER — auth/denylist terminate a disallowed request before the injector (which has no per-request predicate), satisfying the ADR-0007 gate. The session token IS the presented scoped credential ADR-0007 gates on: one L7 read serves both gates.

No custom data-plane code — all native Envoy filters (verified against envoyproxy.io). The network-layer fact (netns/peer-creds/vsock CID) is explicitly NOT the egress key — it is guest isolation on the host↔guest channel (NFR-SEC-43), a different boundary.

Verification

Cross-consistency reviewed against ADR-0007, ADR-0006, component-06, trust-boundaries §4/§7, threat-model P6-E2, and the cited NFRs: CONSISTENT, no contradiction. The two cross-review WARNINGs (FLEX-15 anchor on the bump rung; the token-is-the-scoped-credential statement) are folded in. Adds 0008 to the ADR index and component-06 bound ADRs.

Deferred (not blocking): naming the deny/rate filters in component-06's own spec (the chain currently lives in the ADR).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new architecture decision record (ADR-0008) specifying how the system attributes outbound requests to sessions using token presentation after TLS termination.
  • Updated architecture documentation index and component references to include the new decision record.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 861bfe96-0633-4e51-a78b-53506bae52ca

📥 Commits

Reviewing files that changed from the base of the PR and between 2a8a429 and 9801fb2.

📒 Files selected for processing (3)

• docs/architecture/adr/0008-session-egress-attribution.md
• docs/architecture/adr/README.md
• docs/architecture/components/06-egress-trust-edge.md

---

Walkthrough

This PR introduces Architecture Decision Record 0008 (ADR-0008) specifying that egress session attribution uses session-scoped tokens presented at L7 after TLS termination, with deny and rate-limit decisions keyed to verified token claims. The ADR is integrated into the documentation index and component references.

Changes

ADR-0008: Session-to-egress attribution by presented token

Layer / File(s)	Summary
ADR-0008 decision record docs/architecture/adr/0008-session-egress-attribution.md	Complete ADR document specifies session-scoped token as the attribution key for egress, defines Envoy filter chain order (jwt_authn → ext_authz → rbac → ratelimit → credential_injector → router) and how deny/rate-limit decisions are keyed to verified token claims. Lists rejected alternatives (network facts, source IP, custom filters) and documents compliance, license, and threat-mitigation impacts.
Documentation index and component references docs/architecture/adr/README.md, docs/architecture/components/06-egress-trust-edge.md	ADR-0008 is added to the ADR index table with proposed status and updated last-reviewed date; referenced in component 06 (egress trust-edge) metadata alongside existing ADRs 0005–0007.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Wide-Moat/open-computer-use#177: Documents credential custody and session JWT injection semantics that ADR-0008 relies on for how verified token claims gate deny/rate-limit decisions and credential injection.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary change: adding ADR-0008 for session-to-egress attribution by presented token, which is the main focus of this documentation pull request.
Linked Issues check	✅ Passed	The PR fully addresses all coding/documentation objectives from issue #235: adds ADR-0008 document, updates ADR index, updates component-06 bindings, and documents the session-to-egress attribution decision with filter chain ordering and scope clarification.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue objectives: ADR-0008 documentation, ADR index entry, and component-06 reference updates. No unrelated alterations detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/adr-0008-egress-session-token

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}