Add Extism JS Async Lib and State #1
186
README.md
186
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 |
|
||||
|
||||
Reference in New Issue
Block a user