motr-enclave/README.md

Motr Enclave

Motr Enclave is an Extism 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

┌─────────────────────────────────────────────────────────────────────┐
│                        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 1.25+
• SQLC for database code generation
• Extism CLI (optional, for testing)

Building

make build          # Build WASM for wasip1
make generate       # Regenerate SQLC database code
make test           # Run tests

Testing the Plugin

CLI Testing:

extism call ./build/enclave.wasm generate --input '{"credential": "dGVzdA=="}' --wasi
extism call ./build/enclave.wasm query --input '{"did": "did:sonr:abc123"}' --wasi

Browser Testing:

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