go-crypt/CLAUDE.md

CLAUDE.md — go-crypt Domain Expert Guide

You are a dedicated domain expert for forge.lthn.ai/core/go-crypt. Virgil (in core/go) orchestrates your work via TODO.md. Pick up tasks in phase order, mark [x] when done, commit and push.

What This Package Does

Cryptographic primitives, authentication, and trust policy engine. ~3.7K LOC across 28 Go files. Provides:

• Symmetric encryption — ChaCha20-Poly1305 and AES-256-GCM with Argon2id key derivation
• OpenPGP authentication — Challenge-response (online + air-gapped courier mode)
• Password hashing — Argon2id (primary) + Bcrypt (fallback)
• Trust policy engine — 3-tier agent access control with capability evaluation
• RSA — OAEP-SHA256 key generation and encryption (2048+ bit)
• LTHN hash — RFC-0004 quasi-salted deterministic hash (content IDs, NOT passwords)

Commands

go test ./...                    # Run all tests
go test -v -run TestName ./...   # Single test
go test -race ./...              # Race detector
go vet ./...                     # Static analysis

Local Dependencies

Module	Local Path	Notes
forge.lthn.ai/core/go	../go	Framework (core.E, core.Crypt, io.Medium)
forge.lthn.ai/core/go-store	../go-store	SQLite KV store (session persistence)

Do NOT change the replace directive path. Use go.work for local resolution if needed.

Architecture

auth/ — OpenPGP Challenge-Response + Password Auth (455 LOC)

Authenticator backed by io.Medium storage abstraction.

Registration flow: Generate PGP keypair → store .pub, .key, .rev, .json, .lthn files under users/{userID}/.

Online challenge-response:

1. CreateChallenge(userID) → 32-byte random nonce, encrypted with user's public key
2. Client decrypts nonce, signs it with private key
3. ValidateResponse(userID, signedNonce) → verifies signature, issues 24h session token

Air-gapped (courier) mode:

1. WriteChallengeFile(userID, path) → JSON with encrypted nonce
2. Client signs offline
3. ReadResponseFile(userID, path) → verify, issue session

Session management: Abstracted behind SessionStore interface. 32-byte hex tokens, 24h TTL. ValidateSession, RefreshSession, RevokeSession. Two implementations:

• MemorySessionStore — in-memory sync.RWMutex-protected map (default, sessions lost on restart)
• SQLiteSessionStore — persistent via go-store (SQLite KV), mutex-serialised for single-writer safety

Configure via WithSessionStore(store) option. Background cleanup via StartCleanup(ctx, interval).

Protected users: "server" cannot be deleted.

crypt/ — Symmetric Encryption & Hashing (624 LOC)

File	LOC	Purpose
crypt.go	90	High-level Encrypt/Decrypt (ChaCha20 + Argon2id) and AES-256-GCM variant
kdf.go	60	DeriveKey (Argon2id: 64MB/3 iter/4 threads), DeriveKeyScrypt, HKDF
symmetric.go	100	Low-level ChaCha20Encrypt/Decrypt, AESGCMEncrypt/Decrypt
hash.go	89	HashPassword/VerifyPassword (Argon2id format string), Bcrypt
hmac.go	30	HMACSHA256/512, constant-time VerifyHMAC
checksum.go	55	SHA256File, SHA512File, SHA256Sum, SHA512Sum

crypt/chachapoly/ (50 LOC)

Standalone ChaCha20-Poly1305 AEAD wrapper. 24-byte nonce prepended to ciphertext.

crypt/lthn/ (94 LOC)

RFC-0004 quasi-salted hash. Deterministic: reverse input → leet-speak substitution → SHA-256. For content IDs and deduplication. NOT for passwords.

crypt/pgp/ (230 LOC)

OpenPGP primitives via ProtonMail go-crypto:

• CreateKeyPair(name, email, password) → armored DSA primary + RSA subkey
• Encrypt/Decrypt → armored PGP messages
• Sign/Verify → detached signatures

crypt/rsa/ (91 LOC)

RSA key generation (2048+ bit), OAEP-SHA256 encrypt/decrypt, PEM encoding.

crypt/openpgp/ (191 LOC)

Service wrapper implementing core.Crypt interface. RSA-4096, SHA-256, AES-256. Registers IPC handler for "openpgp.create_key_pair".

trust/ — Agent Trust & Policy Engine (403 LOC)

File	LOC	Purpose
trust.go	165	Registry (thread-safe agent store), Agent struct, Tier enum
policy.go	238	PolicyEngine, 9 capabilities, Evaluate → Allow/Deny/NeedsApproval

Trust tiers:

Tier	Name	Rate Limit	Example Agents
3	Full	Unlimited	Athena, Virgil, Charon
2	Verified	60/min	Clotho, Hypnos (scoped repos)
1	Untrusted	10/min	BugSETI instances

9 Capabilities: repo.push, pr.merge, pr.create, issue.create, issue.comment, secrets.read, cmd.privileged, workspace.access, flows.modify

Evaluation order: Agent exists → policy exists → explicitly denied → requires approval → allowed (with repo scope check).

Algorithm Reference

Component	Algorithm	Parameters
KDF (primary)	Argon2id	Time=3, Memory=64MB, Parallelism=4
KDF (alt)	scrypt	N=32768, r=8, p=1
KDF (expand)	HKDF-SHA256	Variable key length
Symmetric	ChaCha20-Poly1305	24-byte nonce, 32-byte key
Symmetric (alt)	AES-256-GCM	12-byte nonce, 32-byte key
Password hash	Argon2id	Custom format string
Password hash (alt)	Bcrypt	Default cost
Deterministic hash	SHA-256 + quasi-salt	RFC-0004
Asymmetric	RSA-OAEP-SHA256	2048+ bit
PGP	DSA + RSA subkey	ProtonMail go-crypto
HMAC	SHA-256 / SHA-512	Constant-time verify

Security Considerations

1. LTHN hash is NOT for passwords — deterministic, no random salt. Use HashPassword() (Argon2id) instead.
2. Sessions default to in-memory — use WithSessionStore(NewSQLiteSessionStore(path)) for persistence across restarts.
3. PGP output is armored — ~33% Base64 overhead. Consider compression for large payloads.
4. Policy engine returns decisions but doesn't enforce approval workflow — higher-level layer needed.
5. Challenge nonces are 32 bytes — 256-bit, cryptographically random.

Coding Standards

• UK English: colour, organisation, centre
• Tests: testify assert/require, _Good/_Bad/_Ugly naming convention
• Conventional commits: feat(auth):, fix(crypt):, refactor(trust):
• Co-Author: Co-Authored-By: Virgil <virgil@lethean.io>
• Licence: EUPL-1.2
• Imports: stdlib → forge.lthn.ai → third-party, each group separated by blank line

Forge

• Repo: forge.lthn.ai/core/go-crypt
• Push via SSH: git push forge main (remote: ssh://git@forge.lthn.ai:2223/core/go-crypt.git)

Task Queue

See TODO.md for prioritised work. See FINDINGS.md for research notes.