36 lines
1.9 KiB
Markdown
36 lines
1.9 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
## STRUCTURE
|
||
|
|
- `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.).
|
||
|
|
|
||
|
|
## WHERE TO LOOK
|
||
|
|
| 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) |
|
||
|
|
|
||
|
|
## CONVENTIONS
|
||
|
|
- **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`).
|
||
|
|
|
||
|
|
## ANTI-PATTERNS
|
||
|
|
- 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.
|