Skip to content

docs: correct blind-index claims (unkeyed SHA-256, not HMAC) - #679

Open
p-diogo wants to merge 1 commit into
mainfrom
docs/blind-index-accuracy
Open

p-diogo wants to merge 1 commit into
mainfrom
docs/blind-index-accuracy

Conversation

@p-diogo

@p-diogo p-diogo commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

What

Several docs said word-level blind indices are HMAC outputs under a per-user secret and "cannot be inverted". In fact they're unkeyed SHA-256 of each token, its Porter stem, and entity names (rust/totalreclaw-core/src/blind.rs:22-49; entity trapdoors per docs/specs/totalreclaw/flows/02-write-path.md). So hashing a wordlist inverts them, and they're public on-chain. This makes the docs say so.

  • docs/guides/beta-tester-guide-detailed.md:
    • write-path step 3 and the "Server-blind search" guarantee now describe unkeyed hashes and what that exposes
    • the "never sees query terms" line is qualified
    • step 2's content fingerprint is corrected too: it's HMAC-SHA256 under dedupKey, not plain SHA-256
  • docs/specs/totalreclaw/architecture.md: the primitives table no longer says "cannot invert".
  • docs/specs/totalreclaw/retrieval-v2.md, tiered-retrieval.md: diagram labels HMAC → SHA-256.
  • docs/specs/totalreclaw/flows/02-write-path.md: adds a short "What blind indices reveal" note. It covers wordlist inversion, token order, on-chain visibility and query trapdoors reaching indexers, and notes that LSH buckets are per-user.

The fix itself (keyed word indices) is tracked separately.

Verification

Docs only. Claims checked against code:

  • blind.rs (unkeyed sha256_hex(token) and sha256_hex("stem:"+stem), emitted in first-occurrence token order)
  • mcp/src/subgraph/crypto.ts header (SHA-256 blind indices, HMAC-SHA256 content fingerprints)
  • LSH bucket derivation from lshSeed per the write-path flow

docs/architecture.md already says SHA-256 and is left alone (it's also being edited in #674). The website's architecture page also says SHA-256, so it needs no change.

Checklist

  • No recovery phrase, API key, or other secret appears anywhere in this diff or its logs.
  • Docs touched by this change are updated (guides / feature-comparison / CLAUDE.md matrix where relevant).
  • For behavior changes: E2E validated against staging (never production). (N/A, docs only)

🤖 Generated with Claude Code

Several docs said word-level blind indices are HMAC outputs under a
per-user secret and can't be reversed. They're unkeyed SHA-256 of each
token, its stem and entity names (rust/totalreclaw-core/src/blind.rs), so
a wordlist inverts them, and they're public on-chain. Corrects the beta
tester guide, the architecture spec table, the retrieval-v2 and
tiered-retrieval diagrams, and adds a "what blind indices reveal" note to
the write-path flow. Also fixes the beta guide's description of the content
fingerprint, which is HMAC-SHA256 under dedupKey, not plain SHA-256.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant