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

docs(TODO): update with new sqlite functions and priorities

Browse Source
This commit is contained in:
Prad Nu
2026-01-10 17:10:45 -05:00
parent ad3ab3f2ac
commit aec599af0e
1 changed files with 111 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
TODO.md
View File

@@ -15,6 +15,56 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave.
| UCAN DB Actions | Complete | `actions_delegation.go`, `actions_invocation.go` |
| MPC Key Shares | Complete | `actions_keyshare.go` - Full key share management |
| **Database Serialization** | **Complete** | Native SQLite serialization via `ncruces/go-sqlite3/ext/serdes` |
| **BIP44 Multi-Chain** | **Complete** | SQLite functions: `bip44_derive()`, `bip44_derive_from_enclave()` |
| **MPC Signing** | **Complete** | `SignWithEnclave()` via exec handlers |
---
## Architecture: SQLite as DID CPU
The enclave uses a **SQLite-centric architecture** where custom functions, JSON1 extension, and encryption at rest make the database the central computation engine for DID operations.
### Core Principles
1. **Custom SQLite Functions** - Crypto operations live in the database layer
- `bip44_derive(pubkey, chain)` - BIP44 address derivation
- `bip44_derive_from_enclave(enclave_id, chain)` - Derive from stored enclave
- `enclave_sign(enclave_id, data)` - Sign with MPC key (planned)
- `ucan_*` functions for UCAN operations (planned)
2. **JSON1 Extension** - UCAN envelope manipulation in SQL
- Extract fields from DAG-JSON encoded envelopes
- Policy evaluation via JSON path queries
- Build query results as JSON directly
3. **Encryption at Rest** - Application-level AES-256-GCM
- `Serialize()` → `EncryptBytes()` → storage
- WebAuthn PRF key derivation for encryption key
- Full database encrypted as single blob
4. **Generated Columns & Views** - Computed DID state
- `is_expired`, `is_active` for delegation status
- `valid_delegations` view for chain validation
- Recursive CTEs for proof chain traversal
### Implemented SQLite Functions
| Function | Location | Purpose |
|----------|----------|---------|
| `bip44_derive(pubkey_hex, chain)` | `functions.go` | Derive address from public key |
| `bip44_derive_from_enclave(enclave_id, chain)` | `functions.go` | Derive address from stored enclave |
### Planned SQLite Functions
| Function | Purpose |
|----------|---------|
| `enclave_sign(enclave_id, data)` | Sign data with enclave's MPC key |
| `ucan_sign(enclave_id, payload)` | Sign UCAN payload, return varsig |
| `ucan_seal(enclave_id, delegation_json)` | Build complete sealed envelope |
| `ucan_parse_envelope(blob)` | Extract UCAN fields as JSON |
| `ucan_policy_match(policy, args)` | Evaluate policy against args |
| `ucan_cmd_subsumes(parent, child)` | Check command hierarchy |
| `ucan_chain_valid(invocation_cid)` | Validate full proof chain |
---
@@ -106,25 +156,32 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar
### 1.5 Policy Evaluation Engine
> Note: go-ucan provides `ExecutionAllowed()` on invocations which validates proofs and evaluates policies.
> **Architecture**: Use SQLite JSON1 extension for policy evaluation in queries.
- [x] Policy evaluation via go-ucan's `invocation.ExecutionAllowed(loader)`
- [ ] Create `internal/crypto/ucan/eval.go` - Additional evaluation helpers (if needed)
- [ ] Custom selector resolution for Sonr-specific args
- [ ] Caching layer for repeated evaluations
- [ ] Create `ucan_policy_match(policy_json, args_json)` SQLite function
- [ ] Evaluate policy statements against invocation args
- [ ] Support all UCAN policy operators (==, !=, <, >, like, glob)
- [ ] Create `ucan_cmd_subsumes(parent_cmd, child_cmd)` SQLite function
- [ ] Check command hierarchy (e.g., `/vault/*` covers `/vault/read`)
- [ ] Add computed columns/indexes for common policy queries
### 1.6 Proof Chain Validation
> Note: go-ucan handles chain validation internally via `ExecutionAllowed()`.
> **Architecture**: SQLite recursive CTEs for chain traversal, JSON extraction for envelope parsing.
- [x] Chain validation via go-ucan library
- [x] Delegation storage in SQLite via `actions_delegation.go`
- [x] `GetDelegationByCID`, `GetDelegationEnvelope` methods
- [x] `ListDelegations*` methods for chain traversal
- [ ] Create `internal/crypto/ucan/store.go` - Delegation loader for go-ucan
- [ ] Implement `delegation.Loader` interface wrapping keybase actions
- [ ] `GetDelegation(cid.Cid) (*delegation.Token, error)`
- [ ] Cache loaded delegations for performance
- [ ] Create `ucan_chain_valid(invocation_cid)` SQLite function
- [ ] Recursive CTE to walk proof chain via `prf` field
- [ ] Check each delegation's expiry, revocation, and policy
- [ ] Return validation result as JSON
- [ ] Create `ucan_parse_envelope(envelope_blob)` SQLite function
- [ ] Extract iss, aud, sub, cmd, pol, exp, nbf from DAG-CBOR
- [ ] Return as JSON for SQL queries
- [ ] Implement `delegation.Loader` interface backed by SQLite queries
### 1.7 Revocation
@@ -166,10 +223,15 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar
### 1.9 MPC Signing Integration
- [ ] Create `internal/crypto/ucan/signer.go` - MPC key integration
- [ ] Implement `crypto.PrivateKeySigningBytes` interface for MPC
- [ ] Sign delegations with MPC key shares
- [ ] Sign invocations with MPC key shares
> **Architecture**: Leverage SQLite custom functions for UCAN signing, keeping crypto operations in the database layer.
- [ ] Create `ucan_sign(enclave_id, payload)` SQLite function
- [ ] Sign DAG-CBOR encoded delegation/invocation payloads
- [ ] Return varsig-encoded signature bytes
- [ ] Create `ucan_seal(enclave_id, delegation_json)` SQLite function
- [ ] Build sealed envelope from JSON input
- [ ] Compute CID and return complete envelope
- [ ] Integrate with go-ucan's `crypto.Signer` interface via SQLite bridge
### 1.10 Testing
@@ -347,9 +409,9 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar
- [x] Basic address derivation from public key - `deriveCosmosAddress()`
- [x] Create initial account during generate - `createInitialAccount()`
- [ ] Implement BIP44 derivation path parsing
- [ ] Support multiple chains (Cosmos 118, Ethereum 60)
- [ ] Generate proper bech32 address encoding per chain
- [x] Implement BIP44 derivation path parsing - `bip44_derive()` SQLite function
- [x] Support multiple chains (Cosmos 118, Ethereum 60, Bitcoin 0) - `initializeWithMPC()`
- [x] Generate proper bech32 address encoding per chain - `bip44_derive_from_enclave()` SQLite function
### 5.3 Key Rotation
@@ -386,35 +448,37 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar
### 6.3 Signing Function
- [ ] Implement `sign` wasmexport function
- [ ] Support signing with MPC key shares
- [ ] Return signature in appropriate format
- [ ] Log signing operations for audit
- [x] Support signing with MPC key shares - `SignWithEnclave()` in `actions_enclave.go`
- [x] Return signature in appropriate format - hex-encoded secp256k1 signature
- [x] Log signing operations for audit - logged via keybase actions
- [ ] Implement dedicated `sign` wasmexport function (currently via `exec` handlers)
- [ ] Add `enclave_sign()` SQLite function for in-query signing
---
## 7. Capability Delegation (v1.0.0-rc.1)
> Reference: UCAN Delegation specification
> **Architecture**: SQLite triggers and views for real-time delegation validation.
### 7.1 Delegation Chain Management
- [ ] Enforce maximum delegation depth (prevent infinite chains)
- [ ] Validate delegator has capability to delegate (sub field)
- [ ] Ensure proper capability attenuation (cmd + pol)
- [ ] Track parent-child relationships via CID references
- [ ] Create `delegation_depth` generated column using recursive CTE
- [ ] Add CHECK constraint for max depth (e.g., 10 levels)
- [ ] Create `valid_delegations` view joining chain validation
- [ ] Index on `(aud, cmd)` for efficient capability lookups
### 7.2 Policy Attenuation
### 7.2 Policy Attenuation (SQLite Functions)
- [ ] Child policy must be more restrictive than parent
- [ ] Implement policy subsumption checking
- [ ] Command hierarchy validation (`/crud/*` subsumes `/crud/read`)
- [ ] `ucan_policy_subsumes(parent_pol, child_pol)` - Check attenuation
- [ ] `ucan_cmd_covers(parent_cmd, child_cmd)` - Command hierarchy
- [ ] Add trigger `BEFORE INSERT ON ucan_delegations` to validate attenuation
### 7.3 Delegation Status
### 7.3 Delegation Status (SQLite Automation)
- [ ] Implement expiration checking
- [ ] Handle revocation cascades (revoke chain)
- [ ] Update status on expiry
- [ ] `is_expired` generated column: `exp IS NOT NULL AND exp < unixepoch()`
- [ ] `is_active` generated column: `NOT is_expired AND NOT is_revoked`
- [ ] Create `expired_delegations` view for cleanup queries
- [ ] Add partial index on `is_active = 1` for fast lookups
---
@@ -532,157 +596,28 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar
- ~~Delegation operations (1.3)~~ ✅ DelegationBuilder complete
- ~~Invocation operations (1.4)~~ ✅ InvocationBuilder complete
- ~~Database integration (1.8)~~ ✅ Schema, queries, and actions complete
- MPC signing integration (1.9) - Next priority
- ~~MPC Key Derivation (5.2)~~ ✅ BIP44 SQLite functions complete
- ~~MPC Signing (6.3)~~ ✅ SignWithEnclave via exec handlers
2. **High Priority (Core Functionality)** - ✅ Mostly Complete
- ~~Database Serialization (3.1, 3.2)~~ ✅ Native SQLite serdes
- ~~Credential Actions (4.7)~~ ✅ All CRUD operations
- ~~Key Share Actions (4.1)~~ ✅ All operations
- ~~Account Actions (4.6)~~ ✅ All operations
- Delegation Loader for go-ucan (1.6) - Remaining
- Invocations exec handler (6.1) - Remaining
2. **High Priority (SQLite Functions)** - Next Phase
- `ucan_sign()` / `ucan_seal()` SQLite functions (1.9)
- `ucan_parse_envelope()` for JSON extraction (1.6)
- `ucan_chain_valid()` for proof validation (1.6)
- `enclave_sign()` for general signing (6.3)
- Invocations exec handler (6.1)
3. **Medium Priority (Authorization)** - ✅ Partially Complete
- Revocation checker for go-ucan (1.7) - Remaining
- MPC Signing (1.9) - Remaining
- ~~Encryption Strategy (2.1, 2.2, 2.3)~~ ✅ Complete
3. **Medium Priority (SQLite Automation)**
- Generated columns for delegation status (7.3)
- Policy evaluation functions (1.5, 7.2)
- Delegation depth constraints (7.1)
- Revocation cascade triggers (1.7)
4. **Lower Priority (Enhancement)**
- TypeScript SDK (9.x)
- DID State Sync (8.x)
- Sync checkpoints handler (6.1)
- Testing (10.x)
- Security Hardening (11.x)
---
## Completed Items
### Encryption & Serialization (January 2025)
Full encryption layer and native SQLite serialization implemented:
- ✅ `internal/enclave/crypto.go` - WebAuthn PRF key derivation
- `DeriveEncryptionKey()` using HKDF with SHA-256
- `DeriveKeyWithContext()` for purpose-specific keys
- AES-256-GCM encryption/decryption (`Encrypt`, `Decrypt`)
- `EncryptBytes()` / `DecryptBytes()` convenience functions
- `SecureZero()` for memory clearing
- ✅ `internal/enclave/enclave.go` - Encrypted database wrapper
- `Enclave` struct wrapping `Keybase` with encryption
- `SerializeEncrypted()` / `LoadEncrypted()` methods
- `Export()` / `Import()` with `EncryptedBundle`
- `FromExisting()` to wrap existing keybase
- ✅ `internal/keybase/conn.go` - Native SQLite serialization
- `Serialize()` using `serdes.Serialize()` from ncruces/go-sqlite3
- `Load()` using `serdes.Deserialize()`
- `RestoreFromDump()` for encrypted bundle loading
### Action Manager Extensions (January 2025)
All CRUD action handlers completed for remaining entities:
- ✅ `internal/keybase/actions_verification.go`
- CreateVerificationMethod, ListVerificationMethodsFull
- GetVerificationMethod, DeleteVerificationMethod
- ✅ `internal/keybase/actions_service.go`
- CreateService, GetServiceByOrigin, GetServiceByID
- UpdateService, ListVerifiedServices
- ✅ `internal/keybase/actions_grant.go`
- CreateGrant, GetGrantByService, UpdateGrantScopes
- UpdateGrantLastUsed, SuspendGrant, ReactivateGrant, CountActiveGrants
- ✅ `internal/keybase/actions_credential.go`
- CreateCredential, UpdateCredentialCounter, RenameCredential
- DeleteCredential, CountCredentialsByDID
- ✅ `internal/keybase/actions_session.go`
- GetSessionByID, GetCurrentSession, UpdateSessionActivity
- SetCurrentSession, DeleteExpiredSessions
### Plugin Exec Handlers (January 2025)
Extended exec function with new resource handlers:
- ✅ `key_shares` - list, get, rotate, archive, delete
- ✅ `verification_methods` - list, get, delete
- ✅ `services` - list, get, get_by_id
### UCAN v1.0.0-rc.1 Database Integration (January 2025)
Schema and action handlers for storing/querying UCAN delegations and invocations:
- ✅ `internal/migrations/schema.sql` - v1.0.0-rc.1 tables
- `ucan_delegations` - CID-indexed delegation storage with envelope BLOB
- `ucan_invocations` - CID-indexed invocation storage with execution tracking
- `ucan_revocations` - Revocation records with reason and invocation CID
- Updated `grants` table to use `delegation_cid` instead of `ucan_id`
- ✅ `internal/migrations/query.sql` - CID-based queries
- Delegation CRUD: Create, Get by CID, List by DID/Issuer/Audience/Subject/Command
- Invocation CRUD: Create, Get by CID, List by DID/Issuer/Command, Mark executed
- Revocation: Create, Check revoked, Get revocation, List by revoker
- ✅ `internal/keybase/actions_delegation.go` - Delegation action handlers
- StoreDelegation, GetDelegationByCID, GetDelegationEnvelope
- ListDelegations, ListDelegationsByIssuer, ListDelegationsByAudience
- ListDelegationsForCommand, IsDelegationRevoked, RevokeDelegation
- DeleteDelegation, CleanExpiredDelegations
- ✅ `internal/keybase/actions_invocation.go` - Invocation action handlers
- StoreInvocation, GetInvocationByCID, GetInvocationEnvelope
- ListInvocations, ListInvocationsByCommand, ListPendingInvocations
- MarkInvocationExecuted, CleanOldInvocations
- ✅ `main.go` - Updated exec handlers for v1.0.0-rc.1
- `executeUCANAction` uses delegation methods (list, get, revoke, verify, cleanup)
- `executeDelegationAction` uses CID-based methods (list by issuer/audience/command)
- `validateUCAN` uses `IsDelegationRevoked` instead of old `IsUCANRevoked`
- ✅ Deleted old action files
- `internal/keybase/actions_ucan.go` - Old JWT-based UCAN actions
- `internal/keybase/actions_delegation.go` - Old ID-based delegation actions
### UCAN v1.0.0-rc.1 Core (January 2025)
The following was completed using `github.com/ucan-wg/go-ucan v1.1.0`:
- ✅ Type re-exports from go-ucan (Delegation, Invocation, Command, Policy)
- ✅ Sonr command constants (/vault/*, /did/*, /dwn/*)
- ✅ DelegationBuilder fluent API with Sonr-specific helpers
- ✅ InvocationBuilder fluent API with Sonr-specific helpers
- ✅ PolicyBuilder fluent API with all operators
- ✅ Sonr policy helpers (VaultPolicy, DIDPolicy, ChainPolicy)
- ✅ ValidationError types matching TypeScript definitions
- ✅ Capability, ExecutionResult, and related types
### Deleted (Deprecated JWT-based)
- ✅ Deleted `jwt.go` - Old JWT token handling
- ✅ Deleted `capability.go` - Old Attenuation/Resource/Capability model
- ✅ Deleted `verifier.go` - Old JWT verification
- ✅ Deleted `source.go` - Old JWT token creation
- ✅ Deleted `internal/crypto/mpc/spec/` - Old MPC JWT integration
- ✅ Removed `github.com/golang-jwt/jwt/v5` dependency
---
## Deprecated Items (Removed)
The following items from the previous TODO have been removed as they reference the **deprecated JWT-based UCAN format**:
- ~~Section 4.1 "Token Validation" - JWT parsing~~ -> Replaced by go-ucan validation
- ~~Section 4.2 "Capability Verification" - `can`/`with` format~~ -> Replaced by policy evaluation
- ~~Section 4.3 "Proof Chain Validation" - JWT proof strings~~ -> Replaced by CID-based chain
- ~~Section 3.2 "UCAN Token Actions" - Old format~~ -> Replaced by v1.0.0-rc.1 actions (4.2)
- ~~Section 3.3 "Delegation Actions" - Old delegation model~~ -> Merged into Section 1 and 4.2
The old capability model (`Attenuation`, `Resource`, `Capability` interfaces) is replaced by:
- `sub` (DID) - Subject of the capability
- `cmd` (Command) - Action being delegated
- `pol` (Policy) - Constraints on invocation arguments
See [CHANGELOG.md](./CHANGELOG.md) for completed items and version history.