Skip to content

docs: complete key-derivation docs; fix stale auth and chain comments - #674

Open
tmigone wants to merge 1 commit into
chore/remove-dead-contractsfrom
docs/key-derivation-and-stale-comments
Open

tmigone wants to merge 1 commit into
chore/remove-dead-contractsfrom
docs/key-derivation-and-stale-comments

Conversation

@tmigone

@tmigone tmigone commented Oct 15, 2026 •

Copy link
Copy Markdown
Member

This PR rewrites the key derivation section of docs/architecture.md to cover all four HKDF keys and the BIP-44 owner key that controls the Smart Account. It also corrects the claim that the relay only sees a hash of authKey; the relay receives the key itself on every request. Separately, it fixes a Python comment that still described free-tier reads routing to Base Sepolia, and a server docstring that said hashing the auth key prevents replay attacks.

- docs/architecture.md: document both derivation branches (HKDF vault keys
  incl. lshSeed and the seed[0..32] salt; BIP-44 owner key -> Smart Account),
  correct the key-usage table (authKey is sent as a bearer token), describe
  where keys live under derived-bundle-v1, and scope Argon2id to the legacy
  self-hosted password path.
- python relay.py: the subgraph-routing comment still described
  Free -> Base Sepolia routing, retired in ops-1.
- server auth.py: hashing the auth key protects against a DB leak, not replay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tmigone
tmigone added this pull request to stack #675 October 15, 2026 15:19
@tmigone
tmigone requested a review from p-diogo October 15, 2026 15:29
@p-diogo

p-diogo commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

Thanks, this is a big improvement, and correcting the "relay only sees a hash of authKey" claim matters. Two fixes before merge:

1. "only authKey is ever sent anywhere" isn't quite true. POST /v1/register also sends the HKDF salt (seed[0..32]) and SHA-256(authKey), and the relay stores both (Python client.py:885-886, MCP index.ts:476-477). That isn't a weakness on its own, since HKDF and BIP-32 both take the full 64-byte seed, but the doc should say it. Suggested:

A client configured with a recovery phrase derives every key on the device. It sends authKey with each request, and at registration also sends the HKDF salt (seed[0..32]) and SHA-256(authKey). No other key or seed material leaves the device.

2. Legacy password path: "takes the place of the seed in Step 2" reads as if Step 2's salt = seed[0..32] applies here too. In fact this path uses the random Argon2 salt as the HKDF salt (mcp/src/subgraph/crypto.ts:102-121, and deriveLshSeed the same way), so a literal reimplementation would derive different keys. Suggested:

…stretched with Argon2id (t=3, m=64 MB, p=4) over a random 32-byte salt into a master key. Step 2 then runs with the master key as the HKDF input and that same random salt as the HKDF salt.

Then it's good to merge.

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.

2 participants