diff --git a/TODO.md b/TODO.md index 45bedad..e9d11a0 100644 --- a/TODO.md +++ b/TODO.md @@ -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.