npm package: @hyperauth/sdk
Description: Extism WASM plugin providing encrypted key storage for the Nebula wallet. Built with Go 1.25+ for `wasip1` target.
Latest version: 0.5.0

# Motr Enclave

Extism WASM plugin providing encrypted key storage for the Nebula wallet. Built with Go 1.25+ for `wasip1` target.

## Features

- **WebAuthn Integration** - Device-bound credentials with PRF key derivation
- **MPC Key Shares** - Secure threshold signature key storage
- **Multi-Chain Support** - BIP44 derivation for Sonr, Ethereum, Bitcoin
- **UCAN v1.0.0-rc.1** - Capability-based authorization with CID-indexed delegations
- **Encryption at Rest** - AES-256-GCM encrypted database serialization
- **SQLite Functions** - Custom functions for address derivation and signing

## Quick Start

```bash
make start
```

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

## Manual Setup

```bash
make deps      # Install tooling
make build     # Build WASM plugin
make sdk       # Build TypeScript SDK
make dev       # Start dev server
```

## Library Quickstart

### Installation

```bash
npm install @hyperauth/sdk
# or
bun add @hyperauth/sdk
```

### 1. Initialize the Enclave

```typescript
import { createEnclave, createSecureStorage } from '@hyperauth/sdk';

// Create enclave instance (loads WASM)
const enclave = await createEnclave('/enclave.wasm', {
  debug: true,              // Enable logging
  autoLockTimeout: 300000,  // Auto-lock after 5 minutes of inactivity
});

// Create encrypted browser storage for persisting the database
const storage = await createSecureStorage();
```

### 2. Create a New Identity

```typescript
// After WebAuthn registration, pass the credential
const credential = btoa(JSON.stringify(webAuthnCredential));
const result = await enclave.generate(credential);

console.log(result.did);        // "did:sonr:abc123..."
console.log(result.enclave_id); // MPC enclave identifier
console.log(result.accounts);   // Default accounts (Sonr, Ethereum, Bitcoin)

// Persist the database for later sessions
await storage.set('vault', result.database);
```

### 3. Load an Existing Identity

```typescript
// On app startup, check for existing vault
const database = await storage.get('vault');

if (database) {
  const loaded = await enclave.load(database);
  if (loaded.success) {
    console.log(`Loaded identity: ${loaded.did}`);
  }
}
```

### 4. Work with Accounts

```typescript
// List all accounts
const accounts = await enclave.exec('resource:accounts action:list');
console.log(accounts.result);

// Get a specific account
const account = await enclave.exec('resource:accounts action:get subject:sonr1abc...');

// Or use the typed execute method
const result = await enclave.execute('accounts', 'list');
```

### 5. Sign Data

```typescript
// Sign arbitrary data with the MPC enclave
const dataHex = Buffer.from('Hello, World!').toString('hex');
const signature = await enclave.exec(
  `resource:enclaves action:sign subject:${enclaveId}:${dataHex}`
);

console.log(signature.result); // 64-byte signature
```

### 6. Lock/Unlock Flow

```typescript
// Set callback for auto-lock events
enclave.setAutoLockCallback(async (database) => {
  await storage.set('vault', database);
  console.log('Vault auto-locked and saved');
});

// Manual lock (returns serialized database)
const lockResult = await enclave.lock();
if (lockResult.success && lockResult.database) {
  await storage.set('vault', lockResult.database);
}

// Check status
const status = await enclave.status();
console.log(status.locked);      // true/false
console.log(status.initialized); // true if identity exists

// Unlock with stored database
const database = await storage.get('vault');
const unlockResult = await enclave.unlock(database);
```

### 7. Query DID Document

```typescript
const didDoc = await enclave.query();

console.log(didDoc.did);                   // DID identifier
console.log(didDoc.verification_methods);  // Public keys
console.log(didDoc.accounts);              // Blockchain addresses
console.log(didDoc.credentials);           // WebAuthn credentials
```

### 8. Cleanup

```typescript
// Close enclave when done
await enclave.close();
await storage.close();
```

### CLI Testing

```bash
make test-plugin
```

## Plugin Functions

| Function | Input | Output |
|----------|-------|--------|
| `ping` | Message string | Echo response |
| `generate` | WebAuthn credential (base64) | DID, enclave_id, public_key, accounts[], database |
| `load` | Database buffer | Success status, DID |
| `exec` | Filter string | Action result |
| `query` | DID (optional) | DID document |

### Exec Resources & Actions

| Resource | Actions |
|----------|---------|
| `accounts` | list, get, sign |
| `enclaves` | list, get, sign, rotate, archive, delete |
| `credentials` | list, get |
| `sessions` | list, revoke |
| `grants` | list, revoke |
| `delegations` | list, list_received, list_command, get, revoke, verify, cleanup |
| `verification_methods` | list, get, delete |
| `services` | list, get, get_by_id |

### Filter Syntax

```
resource:<name> action:<action> [subject:<value>]
```

Examples:
```bash
# List all accounts
resource:accounts action:list

# Get specific account
resource:accounts action:get subject:sonr1abc...

# Sign with enclave
resource:enclaves action:sign subject:enc_123:48656c6c6f

# List delegations by command
resource:delegations action:list_command subject:/vault/read
```

## Architecture

The enclave uses SQLite as a computation engine with custom functions:

| Function | Purpose |
|----------|---------|
| `bip44_derive(pubkey, chain)` | Derive address from public key |
| `bip44_derive_from_enclave(id, chain)` | Derive address from stored enclave |

Supported chains: `sonr` (Cosmos 118), `ethereum` (60), `bitcoin` (0)

## Project Structure

```
motr-enclave/
├── cmd/enclave/          # WASM plugin entry point
├── internal/
│   ├── keybase/          # Database layer + SQLite functions
│   ├── crypto/mpc/       # MPC key operations
│   ├── crypto/ucan/      # UCAN v1.0.0-rc.1 builders
│   └── migrations/       # Schema + queries
├── src/                  # TypeScript SDK
├── dist/                 # Built SDK
├── example/              # Browser demo
└── Makefile
```

## Development

```bash
make test      # Run Go tests
make lint      # Run linter
make clean     # Remove build artifacts
make generate  # Regenerate SQLC code
```

## Documentation

- [AGENTS.md](./AGENTS.md) - Architecture and coding guidelines
- [TODO.md](./TODO.md) - Remaining implementation tasks
- [CHANGELOG.md](./CHANGELOG.md) - Version history
- [MIGRATION.md](./MIGRATION.md) - Original schema design