docs: system_design.md (Mermaid architecture + flows)

[FiscalMindset]

A comprehensive, interactive system-design doc:

• 11 GitHub-native Mermaid diagrams: system context, component architecture, sentinel substitution, the three secret paths (sequence diagrams for proxy/release/register), self-serve signup, attestation, trust boundaries + threat model, the HMAC ledger chain, and a secret-lifecycle state diagram.
• Interactive/responsive: collapsible <details> sections + a 3-column HTML TOC; reference tables for components, threats, and file layout.
• Accurate to the code (contract forward/release-to-tenant, blindfold-proxy v0.5.6, four auth schemes, egress ACL, keychain).
• Mermaid statically validated (no unquoted ()/{}/<> in messages/labels). Linked from the README nav.

Co-authored-by: algsoch algsoch@gmail.com

---

Summary by cubic

Adds system_design.md, an interactive system design doc with 11 GitHub-native Mermaid diagrams covering architecture, flows, and security. Updates the README nav to link the new doc.

• New Features
  • System context and component architecture, including the sentinel-substitution core.
  • Sequence diagrams for proxy/forward, release broker, register; plus signup and attestation.
  • Trust boundaries + threat model, HMAC-chained ledger, and secret lifecycle state diagram.
  • Collapsible sections with a small HTML TOC; Mermaid syntax validated and aligned with current code and contract (forward/release-to-tenant, blindfold-proxy v0.5.6).

^{Written for commit 709ae85. Summary will update on new commits.}

[qodo-code-review]

PR Summary by Qodo

docs: add System Design doc with Mermaid architecture + key flows

📝 Documentation ✨ Enhancement 🕐 40+ Minutes

AI Description

• Add a comprehensive system_design.md with GitHub-native Mermaid diagrams and reference tables.
• Document core security model, key flows (proxy/release/register), and trust boundaries.
• Link the new System Design doc from the README navigation bar.

Diagram

graph TD
  R(["Reader"]) --> A["README.md nav"] --> S["system_design.md"] --> D["Mermaid diagrams"] --> G{{"GitHub renderer"}}
  S --> AR["ARCHITECTURE.md"] --> SE["SECURITY.md"] --> U["usage.md"]
  subgraph Legend
    direction LR
    _p(["Person"]) ~~~ _doc["Doc page"] ~~~ _ext{{"External"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Split into smaller topical docs

• ➕ Easier incremental review and maintenance per subsystem (attestation, ledger, proxy path, etc.)
• ➕ Smaller pages load faster and are easier to link/bookmark
• ➖ Harder to keep a single coherent end-to-end narrative
• ➖ More navigation work; cross-doc consistency drift risk

2. Publish as a docs site (MkDocs/Docusaurus) with Mermaid plugin

• ➕ Better IA/search, versioned docs, and richer layout components
• ➕ Can add automatic link checking and diagram linting in CI
• ➖ Adds infrastructure/tooling overhead beyond GitHub-native Markdown
• ➖ Higher contribution friction for simple doc edits

3. Auto-generate some diagrams from code/config

• ➕ Reduces risk of docs drifting from real endpoints/contracts
• ➕ Can validate URLs/exports/providers via CI
• ➖ Requires building/maintaining generators and conventions
• ➖ Not all security/trust-boundary content is derivable from code

Recommendation: Keep the current GitHub-native single-page system_design.md as the primary entry point (it optimizes for discoverability and a coherent story), but consider future refactors that extract stable sections (e.g., attestation, ledger internals) into separate docs once they start changing independently. If drift becomes an issue, add lightweight CI link/mermaid validation and selectively auto-generate only the most drift-prone reference tables.

Files changed (2) +439 / -1

Documentation (2) +439 / -1

README.mdAdd System Design link to README navigation +1/-1

Add System Design link to README navigation

• Updates the README top navigation bar to include a link to the new system_design.md page for easier discovery.

README.md

system_design.mdAdd comprehensive system design doc with Mermaid diagrams and flows +438/-0

Add comprehensive system design doc with Mermaid diagrams and flows

• Introduces a new, long-form system design document with multiple GitHub-native Mermaid diagrams (context, components, key secret-handling paths, signup, attestation, threat model, ledger, and lifecycle). Adds collapsible sections, a table-based TOC, and reference tables to make the content scannable and maintainable.

system_design.md

[gitar-bot]

Important

You are using the Gitar free plan. Upgrade to unlock code review, CI analysis, auto-apply, custom automations, and more.

_Gitar

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 5 rules

✅ Skills: blindfold

1. RTMR3 pin not mandatory 🐞 Bug ⛨ Security

Description

system_design.md claims RTMR3 pinning is mandatory for sealing, but the current attestation gate is
opt-in unless a pin is already configured (or BLINDFOLD_REQUIRE_ATTEST=1). This overstates the
default protection against a malicious Terminal 3 node and can lead readers to assume sealing is
measurement-verified when it may not be.

Code

system_design.md[R355-361]

+| Threat | Mitigation | Residual |
+|---|---|---|
+| Prompt injection exfiltrates a key | agent only ever holds `__BLINDFOLD__` | none for the proxy path |
+| Proxy misused by a co-resident process | `proxy --auth` session token · `--socket` 0600 | agent as same OS user |
+| Reflection-exfil — key echoed in a response | contract redacts the sealed secret from the returned body | — |
+| Malicious or honest-but-curious T3 node | remote attestation + **mandatory RTMR3 pin** to seal | trust in Intel TDX + T3 |
+| Tenant key stolen from disk | key in the **OS keychain**, not a plaintext file | agent as same user with unlocked keychain |

Evidence

The doc asserts mandatory RTMR3 pinning, but the implementation only enforces attestation when a pin
is present or enforcement is explicitly required; otherwise it returns unenforced/ok, allowing
sealing without any attestation gate.

system_design.md[355-362]
packages/blindfold/src/attest.ts[177-206]
packages/blindfold/src/attest.ts[215-223]
packages/blindfold/bin/cmd-secrets.ts[28-35]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`system_design.md` states RTMR3 pinning is **mandatory** to seal, but the CLI gate is only enforced when a pin exists (or `BLINDFOLD_REQUIRE_ATTEST=1`). This is a security-posture mismatch in the threat model table.

### Issue Context
- Current gate behavior is explicitly documented in code comments and logic: it is a no-op unless a measurement is pinned or the env var forces it.
- The `register` command calls `attestationGate({ requirePin: true })`, but `attestationGate` returns early when `required` is false.

### Fix Focus Areas
- system_design.md[355-362]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Proxy auth behavior misstated 🐞 Bug ≡ Correctness

Description

system_design.md says the proxy “swap[s] any Authorization for Bearer __BLINDFOLD__”, but the proxy
plants the sentinel into a provider-specific header for some providers (e.g., Gemini’s
x-goog-api-key) and strips Authorization entirely for non-bearer schemes (basic/sigv4) because the
enclave computes Authorization. This can mislead readers about what headers the proxy actually
forwards and how non-OpenAI-shaped providers work.

Code

system_design.md[R143-148]

+| Component | File | Responsibility | Sees plaintext? |
+|---|---|---|---|
+| CLI dispatcher | `bin/blindfold.ts` | route commands to `cmd-*.ts` handlers | no |
+| Register | `src/register.ts` | seal a secret with one `map-entry-set` | **once**, dropped immediately |
+| Proxy | `src/proxy.ts` | swap any `Authorization` for `Bearer __BLINDFOLD__`, route by URL, forward to enclave | **no** |
+| Providers | `src/providers.ts` | prefix → upstream host + secret name + auth scheme | no |

Evidence

The docs state the proxy always swaps Authorization to Bearer __BLINDFOLD__, but the provider
registry includes a bearer provider (Gemini) whose sentinel header is not Authorization, and the
proxy strips Authorization for non-bearer schemes because the enclave computes it.

system_design.md[143-148]
packages/blindfold/src/providers.ts[90-112]
packages/blindfold/src/proxy.ts[219-237]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`system_design.md` oversimplifies the proxy’s header behavior by claiming it always swaps `Authorization` to `Bearer __BLINDFOLD__`. In reality:
- bearer providers may use `Authorization: Bearer …` **or** a provider-specific header (Gemini)
- basic/sigv4/webhook paths strip `Authorization`, since auth is computed/applied in-enclave via the structured `auth` spec.

### Issue Context
The code explicitly selects a provider-specific sentinel header for Gemini and removes `authorization` for non-bearer schemes.

### Fix Focus Areas
- system_design.md[143-148]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Rtmr3 pin not mandatory 🐞 Bug ⛨ Security

system_design.md claims RTMR3 pinning is mandatory for sealing, but the current attestation gate is
opt-in unless a pin is already configured (or BLINDFOLD_REQUIRE_ATTEST=1). This overstates the
default protection against a malicious Terminal 3 node and can lead readers to assume sealing is
measurement-verified when it may not be.

Agent Prompt

### Issue description
`system_design.md` states RTMR3 pinning is **mandatory** to seal, but the CLI gate is only enforced when a pin exists (or `BLINDFOLD_REQUIRE_ATTEST=1`). This is a security-posture mismatch in the threat model table.

### Issue Context
- Current gate behavior is explicitly documented in code comments and logic: it is a no-op unless a measurement is pinned or the env var forces it.
- The `register` command calls `attestationGate({ requirePin: true })`, but `attestationGate` returns early when `required` is false.

### Fix Focus Areas
- system_design.md[355-362]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Proxy auth behavior misstated 🐞 Bug ≡ Correctness

system_design.md says the proxy “swap[s] any Authorization for Bearer __BLINDFOLD__”, but the proxy
plants the sentinel into a provider-specific header for some providers (e.g., Gemini’s
x-goog-api-key) and strips Authorization entirely for non-bearer schemes (basic/sigv4) because the
enclave computes Authorization. This can mislead readers about what headers the proxy actually
forwards and how non-OpenAI-shaped providers work.

Agent Prompt

### Issue description
`system_design.md` oversimplifies the proxy’s header behavior by claiming it always swaps `Authorization` to `Bearer __BLINDFOLD__`. In reality:
- bearer providers may use `Authorization: Bearer …` **or** a provider-specific header (Gemini)
- basic/sigv4/webhook paths strip `Authorization`, since auth is computed/applied in-enclave via the structured `auth` spec.

### Issue Context
The code explicitly selects a provider-specific sentinel header for Gemini and removes `authorization` for non-bearer schemes.

### Fix Focus Areas
- system_design.md[143-148]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools