From 299a10b0a8c4f2f36f56b79975681920aa067f80 Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Sat, 10 Jan 2026 18:20:33 -0500 Subject: [PATCH] docs(crypto): add guidelines for crypto agents docs(keybase): document keybase guidelines chore: add search summary feat: add package lock file --- internal/crypto/AGENTS.md | 32 ++++++++++++++++++ internal/keybase/AGENTS.md | 35 +++++++++++++++++++ package-lock.json | 69 ++++++++++++++++++++++++++++++++++++++ search_summary.md | 32 ++++++++++++++++++ 4 files changed, 168 insertions(+) create mode 100644 internal/crypto/AGENTS.md create mode 100644 internal/keybase/AGENTS.md create mode 100644 package-lock.json create mode 100644 search_summary.md diff --git a/internal/crypto/AGENTS.md b/internal/crypto/AGENTS.md new file mode 100644 index 0000000..a1a7fee --- /dev/null +++ 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/: `. +- **Statelessness**: Favor pure functions or immutable builders over stateful managers. +- **WASM Safety**: Avoid non-deterministic functions or external syscalls not provided by PDK. diff --git a/internal/keybase/AGENTS.md b/internal/keybase/AGENTS.md new file mode 100644 index 0000000..e8e3314 --- /dev/null +++ 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_.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(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. diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..5434ac6 --- /dev/null +++ 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" + } + } +} diff --git a/search_summary.md b/search_summary.md new file mode 100644 index 0000000..343614f --- /dev/null +++ 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.