motr-enclave/README.md

# 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.

## Overview

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

```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)  │ │
│  └──────────────────────┘      └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```

## 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.

## 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
```

## 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
```

### 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 |