x/motr-enclave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): update enclave readme to reflect extism plugin changes

Browse Source
This commit is contained in:
Prad Nu
2026-01-07 14:26:24 -05:00
parent b13901df62
commit e271062313
1 changed files with 86 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
README.md
View File

@@ -1,10 +1,10 @@
# Motr Enclave
Motr Enclave is the encrypted key storage layer for the Nebula wallet. It provides a secure, client-side SQLite environment for managing sensitive identity and cryptographic material.
Motr Enclave is an [Extism](https://extism.org) 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 is built as a SQLite WASM database, ensuring that sensitive data remains on the user's device. All data is encrypted at rest using a secret derived from the user's WebAuthn credentials, providing a seamless yet highly secure experience.
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
@@ -14,8 +14,8 @@ The enclave is built as a SQLite WASM database, ensuring that sensitive data rem
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │
│ │ SQLite Enclave │ │ API Clients (Live Data) │ │
│ │ (Encrypted WASM) │ │ │ │
│ │ Extism Plugin │ │ API Clients (Live Data) │ │
│ │ (TinyGo/wasip1) │ │ │ │
│ ├──────────────────────┤ ├──────────────────────────────────┤ │
│ │ • WebAuthn Creds │ │ • Token Balances │ │
│ │ • MPC Key Shares │ │ • Transaction History │ │
@@ -30,60 +30,111 @@ The enclave is built as a SQLite WASM database, ensuring that sensitive data rem
│ │ WebAuthn-derived key │ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │
│ │ IndexedDB/OPFS │ │ Sonr Protocol / Indexers │ │
│ │ (Browser Storage) │ │ (PostgreSQL for live queries) │ │
│ │ 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 enclave stores security-critical information required for wallet operations:
The embedded SQLite database stores security-critical information:
- **Identity**: Local cache of DID documents and associated 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 device sessions and protocol sync checkpoints.
- **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 employs a WebAuthn-based encryption strategy. Using the WebAuthn PRF (Pseudo-Random Function) extension, a unique secret is derived during authentication. This secret is then used via HKDF to generate a 256-bit AES key that encrypts the SQLite database at rest (stored in IndexedDB or OPFS).
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
- `db/schema.sql`: Database schema definition.
- `db/query.sql`: SQLC query definitions for type-safe Go code generation.
- `sqlc.yaml`: Configuration for the SQLC compiler.
```
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](https://go.dev/doc/install) (latest stable version)
- [SQLC](https://sqlc.dev/) for generating Go database code
- [Go](https://go.dev/doc/install) 1.21+
- [TinyGo](https://tinygo.org/getting-started/install/) 0.30+
- [SQLC](https://sqlc.dev/) for database code generation
- [Extism CLI](https://extism.org/docs/install) (optional, for testing)
### Generating Code
To regenerate the Go database implementation after modifying the schema or queries:
### Building
```bash
sqlc generate
make build # Build with TinyGo for wasip1
make generate # Regenerate SQLC database code
make test # Run tests (requires Go, not TinyGo)
```
This will update the Go files in the `db/` directory, providing type-safe interfaces for all database operations.
### Testing the Plugin
```bash
extism call ./build/enclave.wasm generate --input '{"credential": "..."}'
extism call ./build/enclave.wasm query --input 'did:sonr:abc123'
```
## Tables
The enclave database consists of the following primary tables:
1. `did_documents`: Local cache of Sonr DID state and documents.
2. `verification_methods`: Cryptographic keys associated with a DID for various purposes.
3. `credentials`: WebAuthn credential storage for secure device-bound authentication.
4. `key_shares`: MPC/TSS key share storage encrypted at rest.
5. `accounts`: Blockchain accounts derived from key shares using BIP44 paths.
6. `ucan_tokens`: Capability authorization tokens for fine-grained permissioning.
7. `sessions`: Active device sessions for managing wallet access.
8. `services`: Registry of connected third-party services and dApps.
9. `grants`: User-authorized permissions and scopes granted to specific services.
10. `delegations`: Chains of capability delegations between DIDs for resource access.
| 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 |