diff --git a/README.md b/README.md index 45b629d..58b78bd 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,77 @@ # Motr Enclave -Motr Enclave is an [Extism](https://extism.org) plugin that provides encrypted key storage for the Nebula wallet. Built with Go 1.25+ and compiled for the `wasip1` target, it embeds a SQLite database for managing sensitive identity and cryptographic material. +Extism WASM plugin providing encrypted key storage for Nebula wallet. Built with Go 1.25+ for `wasip1`. -## Overview +## Quick Start -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.). +```bash +make start +``` -## Architecture +This single command: +1. Installs dependencies (Go, Bun) +2. Builds the WASM plugin +3. Builds the TypeScript SDK +4. Starts the dev server at http://localhost:8080 -```text -┌─────────────────────────────────────────────────────────────────────┐ -│ NEBULA WALLET │ -├─────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ -│ │ Extism Plugin │ │ API Clients (Live Data) │ │ -│ │ (Go/wasip1) │ │ │ │ -│ ├──────────────────────┤ ├──────────────────────────────────┤ │ -│ │ • WebAuthn Creds │ │ • Token Balances │ │ -│ │ • MPC Key Shares │ │ • Transaction History │ │ -│ │ • UCAN Tokens │ │ • NFT Holdings │ │ -│ │ • Device Sessions │ │ • Price Data │ │ -│ │ • Service Grants │ │ • Chain State │ │ -│ │ • DID State │ │ • Network Status │ │ -│ │ • Capability Delgs │ │ │ │ -│ └──────────────────────┘ └──────────────────────────────────┘ │ -│ │ │ │ -│ │ Encrypted with │ REST/gRPC │ -│ │ WebAuthn-derived key │ │ -│ ▼ ▼ │ -│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ -│ │ IPFS (CID Storage) │ │ Sonr Protocol / Indexers │ │ -│ │ Browser Storage │ │ (PostgreSQL for live queries) │ │ -│ └──────────────────────┘ └──────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────────┘ +## Manual Setup + +```bash +make deps # Install tooling +make build # Build WASM plugin +make sdk # Build TypeScript SDK +make dev # Start dev server +``` + +## Usage + +### TypeScript/ESM + +```typescript +import { createEnclave } from '@sonr/motr-enclave'; + +const enclave = await createEnclave('/enclave.wasm'); + +const { did, database } = await enclave.generate(credential); + +await enclave.load(database); + +const accounts = await enclave.exec('resource:accounts action:list'); + +const didDoc = await enclave.query(); +``` + +### CLI + +```bash +make test-plugin ``` ## 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 embedded SQLite database stores security-critical information: - -- **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 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. +| Function | Input | Output | +|----------|-------|--------| +| `generate` | WebAuthn credential (base64) | DID + database buffer | +| `load` | Database buffer | Success status | +| `exec` | Filter string + optional UCAN | Action result | +| `query` | DID (optional) | DID document | ## Project Structure ``` motr-enclave/ -├── db/ -│ ├── schema.sql # Database schema (12 tables) -│ └── query.sql # SQLC query definitions -├── example/ -│ ├── index.html # Browser test UI -│ └── test.js # Extism JS SDK test harness -├── sqlc.yaml # SQLC configuration -├── Makefile # Build commands -└── main.go # Plugin entry point +├── main.go # Go plugin source +├── src/ # TypeScript SDK +├── dist/ # Built SDK +├── example/ # Browser test app +├── db/ # SQLite schema +└── Makefile ``` ## Development -### Prerequisites - -- [Go](https://go.dev/doc/install) 1.25+ -- [SQLC](https://sqlc.dev/) for database code generation -- [Extism CLI](https://extism.org/docs/install) (optional, for testing) - -### Building - ```bash -make build # Build WASM for wasip1 -make generate # Regenerate SQLC database code -make test # Run tests +make test # Run Go tests +make lint # Run linter +make clean # Remove build artifacts ``` - -### Testing the Plugin - -**CLI Testing:** -```bash -extism call ./build/enclave.wasm generate --input '{"credential": "dGVzdA=="}' --wasi -extism call ./build/enclave.wasm query --input '{"did": "did:sonr:abc123"}' --wasi -``` - -**Browser Testing:** -```bash -make serve -# Open http://localhost:8080/example/ in your browser -``` - -The browser test UI provides interactive testing of all plugin functions with real-time output. - -## Tables - -| 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 |