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
parent 25fc4dabf3
commit 299a10b0a8
4 changed files with 168 additions and 0 deletions
--- a/internal/crypto/AGENTS.md
+++ b/internal/crypto/AGENTS.md
@@ -0,0 +1,32 @@
+# Crypto Agent Guidelines
+
+## OVERVIEW
+Low-level primitives for 2-of-2 MPC (secp256k1), UCAN v1.0.0-rc.1 capabilities, and BIP-44 address derivation.
+
+## STRUCTURE
+```
+internal/crypto/
+├── bip44/      # SLIP-0044 multi-chain address derivation (Sonr, ETH, BTC)
+├── mpc/        # 2-of-2 threshold ECDSA (secp256k1) signing logic
+└── ucan/       # UCAN v1.0.0-rc.1 builders using DAG-CBOR envelopes
+```
+
+## WHERE TO LOOK
+| Task | File | Primary Types/Funcs |
+|------|------|----------------------|
+| MPC Lifecycle | `mpc/simple.go` | `SimpleEnclave`, `NewSimpleEnclave()`, `Sign()` |
+| MPC Verification | `mpc/verify.go` | `VerifyWithPubKey()`, `Verify()` |
+| MPC Serialization | `mpc/codec.go` | `Marshal()`, `Unmarshal()` |
+| UCAN Delegation | `ucan/delegation.go` | `NewBuilder()`, `BuildDelegation()` |
+| UCAN Invocation | `ucan/invocation.go` | `Invocation`, `BuildInvocation()` |
+| UCAN Policies | `ucan/policy.go` | `Evaluate()`, `Statement` |
+| Address Derivation | `bip44/bip44.go` | `DeriveAddress(pubkey, coinType)` |
+
+## CONVENTIONS
+- **MPC Security**: Restricted to `secp256k1`. Implements 2-of-2 additive secret sharing. Never log raw shares.
+- **UCAN Encoding**: Strictly follows v1.0.0-rc.1 spec using DAG-CBOR (no JWT/JSON strings).
+- **BIP44 Support**: Handles Sonr (118/60), Ethereum (60), and Bitcoin (0). Default is Sonr (60).
+- **No Side Effects**: Crypto packages must not perform I/O or networking.
+- **Error Prefixing**: Every error must be prefixed: `crypto/<pkg>: <reason>`.
+- **Statelessness**: Favor pure functions or immutable builders over stateful managers.
+- **WASM Safety**: Avoid non-deterministic functions or external syscalls not provided by PDK.
--- a/internal/keybase/AGENTS.md
+++ b/internal/keybase/AGENTS.md
@@ -0,0 +1,35 @@
+# 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.
--- a/package-lock.json
+++ b/package-lock.json
@@ -0,0 +1,69 @@
+{
+  "name": "@sonr/motr-enclave",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@sonr/motr-enclave",
+      "version": "0.1.0",
+      "dependencies": {
+        "@extism/extism": "^2.0.0-rc13"
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.0.0"
+      },
+      "peerDependencies": {
+        "@extism/extism": "^2.0.0-rc13"
+      }
+    },
+    "node_modules/@extism/extism": {
+      "version": "2.0.0-rc13",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@types/bun": {
+      "version": "1.3.5",
+      "resolved": "https://registry.npmjs.org/@types/bun/-/bun-1.3.5.tgz",
+      "integrity": "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bun-types": "1.3.5"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "25.0.3",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.16.0"
+      }
+    },
+    "node_modules/bun-types": {
+      "version": "1.3.5",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.16.0",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}
--- a/search_summary.md
+++ b/search_summary.md
@@ -0,0 +1,32 @@
+# Search Summary - Motr Enclave Codebase
+
+## Literal Request
+The user requested a maximum effort search to explore patterns, file structures, and project configurations (go.mod, sqlc.yaml, Makefile, etc.).
+
+## Intent Analysis
+The goal is to provide a comprehensive map of the codebase to allow for immediate action, understanding the "how" and "where" of the Motr Enclave implementation.
+
+## Key Findings
+
+### Project Configuration
+- **Go Version**: 1.25.5
+- **WASM Target**: `wasip1/wasm`
+- **Database**: SQLite with SQLC for Go code generation
+- **TypeScript SDK**: Bun-based build and test system
+- **Build System**: Makefile with targets for build, generate, lint, and test
+
+### Architecture
+- **SQLite as DID CPU**: Custom SQLite functions in `internal/keybase/functions.go` (`bip44_derive`, etc.)
+- **Extism Plugin**: Main entry point in `cmd/enclave/main.go`. Exported functions: `generate`, `load`, `exec`, `query`, `ping`.
+- **Encryption**: AES-256-GCM for database serialization (`internal/keybase/conn.go`)
+- **UCAN**: v1.0.0-rc.1 support (`internal/crypto/ucan`)
+- **MPC**: Key share management (`internal/crypto/mpc`)
+
+### Core Files
+- `cmd/enclave/main.go`: WASM entry point
+- `internal/keybase/`: Database logic, actions, and generated SQLC code
+- `internal/migrations/`: Schema (`schema.sql`) and Queries (`query.sql`)
+- `AGENTS.md`: Detailed architectural guidelines and coding standards
+
+## Results
+See the structured results block in the main response.