Files

Prad Nukala 299a10b0a8 docs(crypto): add guidelines for crypto agents

docs(keybase): document keybase guidelines
chore: add search summary
feat: add package lock file

2026-01-10 18:20:33 -05:00

Keybase Guidelines (internal/keybase)

Generated: 2026-01-10 | Namespace: internal/keybase

OVERVIEW

Core database layer utilizing SQLite as a "DID CPU" with custom crypto functions and action dispatching.

exec.go: Action dispatcher mapping resource/action pairs to Go handlers.
functions.go: Registration of custom SQLite functions (mpc_sign, bip44_derive).
store.go: Keybase singleton managing the SQLite connection, mutex, and DID state.
actions.go: ActionManager providing thread-safe high-level API for database operations.
actions_*.go: Resource-specific handlers (accounts, credentials, enclaves, etc.).

Task	Location
Add new `exec` action	`exec.go` (update `handlers` map)
Implement action logic	`actions_<resource>.go`
Define new SQLite function	`functions.go` (use `conn.CreateFunction`)
Register SQLite function	`functions.go` -> `RegisterMPCFunctions`
Database schema/queries	`internal/migrations/` (SQLC source)

Handler Signature: func handle<Res><Act>(ctx, am *ActionManager, subject string) (json.RawMessage, error)
Thread Safety: All ActionManager methods MUST use am.kb.mu.RLock() (reads) or am.kb.mu.Lock() (writes).
Return Type: Handlers must return json.RawMessage or an error. Use json.Marshal for outputs.
Transactions: Use am.kb.WithTx(ctx, func(q *Queries) error { ... }) for multi-step atomic operations.
Subject Parsing: Parse the subject string in handlers (e.g., id:data or address).

Accessing kb.db or kb.queries without holding the kb.mu mutex.
Performing heavy crypto operations inside a write lock (blocks all reads/writes).
Hardcoding SQL strings outside of internal/migrations/ or simple db.Exec updates.
Returning raw internal structs; always map to *Result types for JSON output.