motr-enclave/README.md

Motr Enclave

Motr Enclave is an Extism 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 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)    │ │
│  │   (TinyGo/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
├── sqlc.yaml           # SQLC configuration
├── Makefile            # Build commands
└── main.go             # Plugin entry point (TBD)

Development

Prerequisites

• Go 1.21+
• TinyGo 0.30+
• SQLC for database code generation
• Extism CLI (optional, for testing)

Building

make build          # Build with TinyGo for wasip1
make generate       # Regenerate SQLC database code
make test           # Run tests (requires Go, not TinyGo)

Testing the Plugin

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

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