From aadde39fcdb9528e38a594ab22818026efab0015 Mon Sep 17 00:00:00 2001 From: FiscalMindset <254638087+FiscalMindset@users.noreply.github.com> Date: Mon, 13 Jul 2026 02:20:22 +0530 Subject: [PATCH] docs: embed proxy sequence diagram in README + teach the chatbot the architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: add a step-by-step proxy-request sequence diagram (collapsible) in 'How Blindfold fixes it', linking to system_design.md's full diagram set. - Chatbot: add curated KB entries system_architecture + three_secret_paths (pointing to system_design.md) with classifier patterns + Intent types. Verified routing at conf 1.00. (The extract run merged system_design.md to 0 new entries β€” its content mapped onto existing intents β€” so these are curated.) Co-authored-by: algsoch --- README.md | 24 +++++++++- packages/chatbot/data/knowledge.json | 65 +++++++++++++++++++++++++++- packages/chatbot/src/intents.ts | 26 +++++++++++ packages/chatbot/src/types.ts | 2 + 4 files changed, 114 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index aeb0125..a50719b 100644 --- a/README.md +++ b/README.md @@ -288,7 +288,29 @@ flowchart LR - The Blindfold Proxy on your machine **never has the key** β€” its only inputs are the agent's HTTP request and a sentinel string `__BLINDFOLD__`. - The contract reads the key from KV **inside TDX memory**, substitutes it into the headers, makes the call, and returns the response. The plaintext key exists only on one stack frame, inside the enclave, for the duration of one call. -Architecture in detail: [`docs/03-architecture.md`](docs/03-architecture.md). +
+Step-by-step: one request through the proxy (sequence) + +```mermaid +sequenceDiagram + autonumber + participant A as πŸ€– Agent + participant P as Proxy + participant E as πŸ”’ Enclave + participant U as Upstream API + A->>P: request with Authorization Bearer __BLINDFOLD__ + Note over P: overwrite Authorization with the sentinel,
match URL prefix to provider host and secret + P->>E: ForwardRequest, sentinel only + Note over E: read secret from the map,
replace __BLINDFOLD__ with the real key,
apply the auth scheme + E->>U: real HTTPS request from inside TDX + U-->>E: response + E-->>P: response, sealed secret redacted + P-->>A: response β€” the key never crossed back out +``` + +
+ +**Full architecture** — 11 diagrams (context, components, all three secret paths, signup, attestation, trust boundaries, ledger, lifecycle): [`system_design.md`](system_design.md). Original writeup: [`docs/03-architecture.md`](docs/03-architecture.md). --- diff --git a/packages/chatbot/data/knowledge.json b/packages/chatbot/data/knowledge.json index 7777cf4..2bc7be5 100644 --- a/packages/chatbot/data/knowledge.json +++ b/packages/chatbot/data/knowledge.json @@ -1,7 +1,7 @@ { "schemaVersion": "1.0.0", - "generatedAt": "2026-07-12", - "source": "Manually curated from docs/, README.md, FAQ.md, usage.md, EXAMPLES.md, packages/blindfold/src/*.ts and contract/src/*.rs + extraction pipeline (2026-07-04) + extraction pipeline (2026-07-04) + extraction pipeline (2026-07-04) + extraction pipeline (2026-07-11) + extraction pipeline (2026-07-12)", + "generatedAt": "2026-07-13", + "source": "Manually curated from docs/, README.md, FAQ.md, usage.md, EXAMPLES.md, packages/blindfold/src/*.ts and contract/src/*.rs + extraction pipeline (2026-07-04) + extraction pipeline (2026-07-04) + extraction pipeline (2026-07-04) + extraction pipeline (2026-07-11) + extraction pipeline (2026-07-12) + extraction pipeline (2026-07-12)", "entries": [ { "id": "kb-001", @@ -20125,6 +20125,67 @@ ], "confidence": 0.7, "lastVerified": "2026-07-12" + }, + { + "id": "kb-system-architecture", + "intent": "system_architecture", + "audience": [ + "user", + "founder", + "developer", + "enterprise", + "researcher", + "general" + ], + "question": "How is Blindfold architected / how does the whole system work?", + "shortAnswer": "Client side: the CLI, a local sentinel proxy, and a Terminal 3 SDK wrapper. Server side: a Rust→WASM contract (`blindfold-proxy`) running inside an Intel TDX enclave, holding your secrets map and enforcing an egress allowlist. Your agent only ever sends the placeholder `__BLINDFOLD__`; the real key is substituted inside the enclave. Full diagrams are in system_design.md.", + "longAnswer": "## System architecture\n\n**Client side (`packages/blindfold`)** — all treated as *untrusted for secrets*:\n- `bin/blindfold.ts` — CLI dispatcher.\n- `src/proxy.ts` — the local sentinel proxy; overwrites any `Authorization` with `Bearer __BLINDFOLD__` and routes by URL prefix.\n- `src/providers.ts` — maps a URL prefix → upstream host + sealed-secret name + auth scheme (bearer/basic/sigv4/webhook).\n- `src/t3-client.ts` — wraps `@terminal3/t3n-sdk` (auth, seed, forward, release, delete, balance).\n- `src/sealed-ledger.ts` — a metadata-only, HMAC hash-chained record of what's sealed.\n\n**Server side (Terminal 3, Intel TDX)**:\n- `contract/` — a Rust→WASM contract published as `blindfold-proxy`. Its `forward` function substitutes the sealed secret *inside* the enclave and makes the outbound call; `release-to-tenant` returns plaintext to the authenticated tenant.\n- The tenant's `secrets` map holds the canonical key value — the only place it lives.\n- An egress allowlist (`agent-auth-update`) denies any host you haven't granted.\n\n**The flow:** agent → local proxy (sees only the sentinel) → enclave `forward` (swaps sentinel for the real key, calls the API) → response back. The plaintext key exists only inside the enclave, for one call. See **system_design.md** for the full set of diagrams (context, components, sequence flows, signup, attestation, trust boundaries, ledger, lifecycle).", + "links": [ + { + "label": "system_design.md", + "url": "system_design.md", + "type": "code" + }, + { + "label": "ARCHITECTURE.md", + "url": "ARCHITECTURE.md", + "type": "code" + } + ], + "sources": [ + "system_design.md", + "packages/blindfold/src/proxy.ts", + "contract/src/forward.rs" + ], + "confidence": 0.97, + "lastVerified": "2026-07-13" + }, + { + "id": "kb-three-secret-paths", + "intent": "three_secret_paths", + "audience": [ + "developer", + "enterprise", + "researcher", + "general", + "user" + ], + "question": "What are the three ways a sealed secret gets used (proxy vs release vs register)?", + "shortAnswer": "1) Proxy/forward — the key is substituted INSIDE the enclave, so your agent never holds it (strongest). 2) Release broker — the plaintext is returned to YOUR local process for one call (protects the agent's context, not your process). 3) Seed/register — the value enters the enclave once, at seal time. Pick per workload; see the Cost section.", + "longAnswer": "## The three secret paths\n\nBlindfold uses a sealed secret in three ways, with different security postures:\n\n| Path | Where plaintext appears | Guarantee | Use for |\n|---|---|---|---|\n| **Proxy / forward** | only inside the enclave | strongest — the agent never holds it | agent HTTP calls, autonomous agents |\n| **Release broker** | your local process, briefly | protects the agent's *context*, not your process | `blindfold use`, non-HTTP protocols, batch |\n| **Seed / register** | your process once, at seal time | unavoidable — the value must enter the enclave once | one-time setup |\n\n**Proxy** (`proxy.ts` → contract `forward`): the agent sends `Bearer __BLINDFOLD__`; the enclave swaps it for the real key and makes the call. **Release** (`release.ts` → contract `release-to-tenant`): hands the plaintext to your process for one command — cheaper for bursts (release once, reuse for N calls), but the value lives in your memory for that window. **Register** (`register.ts`): the single line that ever sees plaintext, sealing the value via `map-entry-set`. See system_design.md §4 for sequence diagrams of each.", + "links": [ + { + "label": "system_design.md#4--the-three-secret-paths", + "url": "system_design.md", + "type": "code" + } + ], + "sources": [ + "system_design.md", + "packages/blindfold/src/release.ts" + ], + "confidence": 0.96, + "lastVerified": "2026-07-13" } ] } diff --git a/packages/chatbot/src/intents.ts b/packages/chatbot/src/intents.ts index c2312d3..9362d85 100644 --- a/packages/chatbot/src/intents.ts +++ b/packages/chatbot/src/intents.ts @@ -711,6 +711,32 @@ export const INTENT_PATTERNS: IntentPattern[] = [ ], examples: ["is Blindfold on npm?", "how do I install Blindfold?", "what's the npm package?"], }, + { + intent: "system_architecture", + patterns: [ + { type: "phrase", value: "system design", weight: 6 }, + { type: "phrase", value: "architect", weight: 5 }, + { type: "phrase", value: "design of", weight: 3 }, + { type: "phrase", value: "how is it built", weight: 4 }, + { type: "phrase", value: "how is blindfold built", weight: 5 }, + { type: "phrase", value: "how does the whole system", weight: 5 }, + { type: "phrase", value: "components", weight: 2 }, + { type: "phrase", value: "how it works end to end", weight: 4 }, + ], + examples: ["how is Blindfold architected?", "explain the system design", "what are the components?"], + }, + { + intent: "three_secret_paths", + patterns: [ + { type: "phrase", value: "three ways", weight: 6 }, + { type: "phrase", value: "three paths", weight: 6 }, + { type: "phrase", value: "proxy vs release", weight: 7 }, + { type: "phrase", value: "release vs proxy", weight: 7 }, + { type: "phrase", value: "secret paths", weight: 6 }, + { type: "phrase", value: "release broker", weight: 4 }, + ], + examples: ["what are the three secret paths?", "proxy vs release?"], + }, { intent: "signup_vs_login", patterns: [ diff --git a/packages/chatbot/src/types.ts b/packages/chatbot/src/types.ts index 47fe1cc..80ac8a1 100644 --- a/packages/chatbot/src/types.ts +++ b/packages/chatbot/src/types.ts @@ -22,6 +22,8 @@ export type Intent = | "signup_self_serve" | "install_from_npm" | "signup_vs_login" + | "system_architecture" + | "three_secret_paths" | "one_line_change" | "is_production_ready" // Concepts