Repository navigation
Conversation
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
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
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.
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 perdocs/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:dedupKey, not plain SHA-256docs/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(unkeyedsha256_hex(token)andsha256_hex("stem:"+stem), emitted in first-occurrence token order)mcp/src/subgraph/crypto.tsheader (SHA-256 blind indices, HMAC-SHA256 content fingerprints)lshSeedper the write-path flowdocs/architecture.mdalready 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
🤖 Generated with Claude Code