From e271062313603e098ef33ba59eaa162cfe8f96af Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Wed, 7 Jan 2026 14:26:24 -0500 Subject: [PATCH] docs(readme): update enclave readme to reflect extism plugin changes --- README.md | 121 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 86 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 38b3115..9840f66 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Motr Enclave -Motr Enclave is the encrypted key storage layer for the Nebula wallet. It provides a secure, client-side SQLite environment for managing sensitive identity and cryptographic material. +Motr Enclave is an [Extism](https://extism.org) plugin that provides encrypted key storage for the Nebula wallet. Built with Go and compiled with TinyGo for the `wasip1` target, it embeds a SQLite database for managing sensitive identity and cryptographic material. ## Overview -The enclave is built as a SQLite WASM database, ensuring that sensitive data remains on the user's device. All data is encrypted at rest using a secret derived from the user's WebAuthn credentials, providing a seamless yet highly secure experience. +The enclave runs as a portable WASM plugin with an embedded SQLite database. All data is encrypted at rest using a secret derived from the user's WebAuthn credentials. The plugin can be loaded by any Extism host runtime (browser, Node.js, Python, Rust, etc.). ## Architecture @@ -14,8 +14,8 @@ The enclave is built as a SQLite WASM database, ensuring that sensitive data rem ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ -│ │ SQLite Enclave │ │ API Clients (Live Data) │ │ -│ │ (Encrypted WASM) │ │ │ │ +│ │ Extism Plugin │ │ API Clients (Live Data) │ │ +│ │ (TinyGo/wasip1) │ │ │ │ │ ├──────────────────────┤ ├──────────────────────────────────┤ │ │ │ • WebAuthn Creds │ │ • Token Balances │ │ │ │ • MPC Key Shares │ │ • Transaction History │ │ @@ -30,60 +30,111 @@ The enclave is built as a SQLite WASM database, ensuring that sensitive data rem │ │ WebAuthn-derived key │ │ │ ▼ ▼ │ │ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ -│ │ IndexedDB/OPFS │ │ Sonr Protocol / Indexers │ │ -│ │ (Browser Storage) │ │ (PostgreSQL for live queries) │ │ +│ │ IPFS (CID Storage) │ │ Sonr Protocol / Indexers │ │ +│ │ Browser Storage │ │ (PostgreSQL for live queries) │ │ │ └──────────────────────┘ └──────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` +## Plugin Functions + +The Extism plugin exposes four host-callable functions: + +### `generate()` + +Initializes the database and generates initial MPC key shares. + +- **Input**: Base64-encoded `PublicKeyCredential` from a WebAuthn registration ceremony +- **Output**: Serialized database buffer ready for storage +- **Side Effects**: Creates DID document, credentials, and key shares + +### `load()` + +Loads an existing database from a serialized buffer. + +- **Input**: Raw database bytes (typically resolved from an IPFS CID) +- **Output**: Success/error status +- **Usage**: Client resolves CID from IPFS, passes buffer to plugin + +### `exec()` + +Executes an action by parsing a UCAN token with GitHub-style filter syntax. + +- **Input**: Filter string (e.g., `resource:accounts action:sign subject:did:sonr:abc`) +- **Output**: Action result or error +- **Authorization**: Validates UCAN capability chain before execution + +### `query()` + +Resolves a DID to its document and queries associated resources. + +- **Input**: DID string (e.g., `did:sonr:abc123`) +- **Output**: JSON-encoded DID document with resolved resources +- **Usage**: Lookup identity state, verification methods, accounts + ## Data Storage -The enclave stores security-critical information required for wallet operations: +The embedded SQLite database stores security-critical information: -- **Identity**: Local cache of DID documents and associated verification methods. -- **Credentials**: WebAuthn registrations for device-bound authentication. -- **Key Material**: MPC key shares and derived blockchain accounts. -- **Authorization**: UCAN tokens, capability delegations, and service grants. -- **State**: Active device sessions and protocol sync checkpoints. +- **Identity**: DID documents and verification methods +- **Credentials**: WebAuthn registrations for device-bound authentication +- **Key Material**: MPC key shares and derived blockchain accounts +- **Authorization**: UCAN tokens, capability delegations, and service grants +- **State**: Active sessions and protocol sync checkpoints ## Security Model -The enclave employs a WebAuthn-based encryption strategy. Using the WebAuthn PRF (Pseudo-Random Function) extension, a unique secret is derived during authentication. This secret is then used via HKDF to generate a 256-bit AES key that encrypts the SQLite database at rest (stored in IndexedDB or OPFS). +The enclave uses WebAuthn PRF (Pseudo-Random Function) extension to derive encryption keys. During authentication, the PRF output is passed through HKDF to generate a 256-bit AES key. This key encrypts the SQLite database before serialization to IPFS or local storage. ## Project Structure -- `db/schema.sql`: Database schema definition. -- `db/query.sql`: SQLC query definitions for type-safe Go code generation. -- `sqlc.yaml`: Configuration for the SQLC compiler. +``` +motr-enclave/ +├── db/ +│ ├── schema.sql # Database schema (12 tables) +│ └── query.sql # SQLC query definitions +├── sqlc.yaml # SQLC configuration +├── Makefile # Build commands +└── main.go # Plugin entry point (TBD) +``` ## Development ### Prerequisites -- [Go](https://go.dev/doc/install) (latest stable version) -- [SQLC](https://sqlc.dev/) for generating Go database code +- [Go](https://go.dev/doc/install) 1.21+ +- [TinyGo](https://tinygo.org/getting-started/install/) 0.30+ +- [SQLC](https://sqlc.dev/) for database code generation +- [Extism CLI](https://extism.org/docs/install) (optional, for testing) -### Generating Code - -To regenerate the Go database implementation after modifying the schema or queries: +### Building ```bash -sqlc generate +make build # Build with TinyGo for wasip1 +make generate # Regenerate SQLC database code +make test # Run tests (requires Go, not TinyGo) ``` -This will update the Go files in the `db/` directory, providing type-safe interfaces for all database operations. +### Testing the Plugin + +```bash +extism call ./build/enclave.wasm generate --input '{"credential": "..."}' +extism call ./build/enclave.wasm query --input 'did:sonr:abc123' +``` ## Tables -The enclave database consists of the following primary tables: - -1. `did_documents`: Local cache of Sonr DID state and documents. -2. `verification_methods`: Cryptographic keys associated with a DID for various purposes. -3. `credentials`: WebAuthn credential storage for secure device-bound authentication. -4. `key_shares`: MPC/TSS key share storage encrypted at rest. -5. `accounts`: Blockchain accounts derived from key shares using BIP44 paths. -6. `ucan_tokens`: Capability authorization tokens for fine-grained permissioning. -7. `sessions`: Active device sessions for managing wallet access. -8. `services`: Registry of connected third-party services and dApps. -9. `grants`: User-authorized permissions and scopes granted to specific services. -10. `delegations`: Chains of capability delegations between DIDs for resource access. +| Table | Description | +|-------|-------------| +| `did_documents` | Local cache of Sonr DID state | +| `verification_methods` | Cryptographic keys for DID operations | +| `credentials` | WebAuthn credential storage | +| `key_shares` | MPC/TSS key shares (encrypted) | +| `accounts` | Derived blockchain accounts | +| `ucan_tokens` | Capability authorization tokens | +| `ucan_revocations` | Revoked UCAN registry | +| `sessions` | Active device sessions | +| `services` | Connected third-party dApps | +| `grants` | Service permissions | +| `delegations` | Capability delegation chains | +| `sync_checkpoints` | Protocol sync state |