From a633631dcfab66be1ae7748ba1945eb7ac5b6ec5 Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Sat, 10 Jan 2026 11:50:59 -0500 Subject: [PATCH] feat(enclave): complete encryption strategy and database serialization --- TODO.md | 198 +++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 132 insertions(+), 66 deletions(-) diff --git a/TODO.md b/TODO.md index fc94c26..45bedad 100644 --- a/TODO.md +++ b/TODO.md @@ -10,11 +10,11 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. | SQLC Queries | Complete | `internal/migrations/query.sql` - CID-based queries added | | Generated Code | Complete | `internal/keybase/*.go` | | Basic Plugin Functions | Complete | `generate`, `load`, `exec`, `query`, `ping` | -| Encryption | Not Started | WebAuthn PRF key derivation needed | +| **Encryption** | **Complete** | `internal/enclave/` - WebAuthn PRF key derivation + AES-256-GCM | | **UCAN v1.0.0-rc.1** | **Complete** | Core types, builders, policies, DB actions all complete | | UCAN DB Actions | Complete | `actions_delegation.go`, `actions_invocation.go` | -| MPC Key Shares | Not Started | Key share management missing | -| Database Serialization | Incomplete | Export dumps comments only | +| MPC Key Shares | Complete | `actions_keyshare.go` - Full key share management | +| **Database Serialization** | **Complete** | Native SQLite serialization via `ncruces/go-sqlite3/ext/serdes` | --- @@ -184,45 +184,56 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar ## 2. Encryption Strategy > Reference: MIGRATION.md lines 770-814 +> **Status**: ✅ Complete - Implemented in `internal/enclave/` ### 2.1 WebAuthn PRF Key Derivation -- [ ] Implement `DeriveEncryptionKey(prfOutput []byte) ([]byte, error)` -- [ ] Use HKDF with SHA-256 to derive 256-bit encryption key -- [ ] Salt with `"nebula-enclave-v1"` as info parameter +- [x] Implement `DeriveEncryptionKey(prfOutput []byte) ([]byte, error)` +- [x] Use HKDF with SHA-256 to derive 256-bit encryption key +- [x] Salt with `"nebula-enclave-v1"` as info parameter +- [x] `DeriveKeyWithContext()` for purpose-specific key derivation ### 2.2 Database Encryption -- [ ] Implement application-level AES-GCM encryption for serialized pages -- [ ] Add encryption wrapper around `Serialize()` output -- [ ] Add decryption wrapper for `Load()` input -- [ ] Store encryption metadata (IV, auth tag) with serialized data +- [x] Implement application-level AES-256-GCM encryption for serialized pages +- [x] Add encryption wrapper around `Serialize()` output (`EncryptBytes()`) +- [x] Add decryption wrapper for `Load()` input (`DecryptBytes()`) +- [x] Store encryption metadata (version, nonce, auth tag) with serialized data +- [x] `SecureZero()` for memory clearing of sensitive data ### 2.3 Encrypted Database Wrapper -- [ ] Create `internal/enclave/enclave.go` - Encrypted database wrapper -- [ ] Create `internal/enclave/crypto.go` - WebAuthn PRF key derivation -- [ ] Integrate with existing `internal/keybase` package +- [x] Create `internal/enclave/enclave.go` - Encrypted database wrapper + - [x] `Enclave` struct wrapping `Keybase` with encryption key + - [x] `SerializeEncrypted()` - Export encrypted database + - [x] `LoadEncrypted()` - Load from encrypted bytes + - [x] `Export()` / `Import()` - Full bundle operations with DID + - [x] `EncryptedBundle` struct with JSON marshaling +- [x] Create `internal/enclave/crypto.go` - WebAuthn PRF key derivation + - [x] `Encrypt()` / `Decrypt()` with `EncryptedData` struct + - [x] `EncryptBytes()` / `DecryptBytes()` convenience functions + - [x] `GenerateNonce()` for secure random nonce generation +- [x] Integrate with existing `internal/keybase` package via `FromExisting()` --- ## 3. Database Serialization -> Current implementation in `conn.go:exportDump()` only outputs comments +> **Status**: ✅ Complete - Using native SQLite serialization via `ncruces/go-sqlite3/ext/serdes` -### 3.1 Proper Serialization +### 3.1 Native SQLite Serialization -- [ ] Implement full row export with proper SQL INSERT statements -- [ ] Handle JSON columns correctly (escape special characters) -- [ ] Include table creation order for foreign key constraints -- [ ] Add version header for migration compatibility +- [x] `Serialize()` using `serdes.Serialize(conn, "main")` - Binary database export +- [x] Full database state captured as byte slice +- [x] No SQL parsing needed - direct database format +- [x] Preserves all data types, indexes, and constraints -### 3.2 Proper Deserialization +### 3.2 Native SQLite Deserialization -- [ ] Parse serialized SQL dump in `Load()` -- [ ] Execute INSERT statements to restore data -- [ ] Validate data integrity after restore -- [ ] Handle schema version mismatches +- [x] `Load()` using `serdes.Deserialize(conn, "main", data)` - Binary import +- [x] `RestoreFromDump()` for encrypted bundle loading +- [x] Automatic DID context restoration after load +- [x] Integrated with `internal/enclave` for encrypted storage --- @@ -265,28 +276,28 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar ### 4.3 Verification Method Actions -- [ ] `CreateVerificationMethod(ctx, params) (*VerificationMethodResult, error)` -- [ ] `ListVerificationMethods(ctx) ([]VerificationMethodResult, error)` -- [ ] `GetVerificationMethod(ctx, methodID) (*VerificationMethodResult, error)` -- [ ] `DeleteVerificationMethod(ctx, methodID) error` +- [x] `CreateVerificationMethod(ctx, params) (*VerificationMethodResult, error)` +- [x] `ListVerificationMethodsFull(ctx) ([]VerificationMethodResult, error)` +- [x] `GetVerificationMethod(ctx, methodID) (*VerificationMethodResult, error)` +- [x] `DeleteVerificationMethod(ctx, methodID) error` ### 4.4 Service Actions -- [ ] `CreateService(ctx, params) (*ServiceResult, error)` -- [ ] `GetServiceByOrigin(ctx, origin) (*ServiceResult, error)` -- [ ] `GetServiceByID(ctx, serviceID) (*ServiceResult, error)` -- [ ] `UpdateService(ctx, params) error` -- [ ] `ListVerifiedServices(ctx) ([]ServiceResult, error)` +- [x] `CreateService(ctx, params) (*ServiceResult, error)` +- [x] `GetServiceByOrigin(ctx, origin) (*ServiceResult, error)` +- [x] `GetServiceByID(ctx, serviceID) (*ServiceResult, error)` +- [x] `UpdateService(ctx, params) error` +- [x] `ListVerifiedServices(ctx) ([]ServiceResult, error)` ### 4.5 Grant Actions (Extend Existing) -- [ ] `CreateGrant(ctx, params) (*GrantResult, error)` -- [ ] `GetGrantByService(ctx, serviceID) (*GrantResult, error)` -- [ ] `UpdateGrantScopes(ctx, grantID, scopes, accounts) error` -- [ ] `UpdateGrantLastUsed(ctx, grantID) error` -- [ ] `SuspendGrant(ctx, grantID) error` -- [ ] `ReactivateGrant(ctx, grantID) error` -- [ ] `CountActiveGrants(ctx) (int64, error)` +- [x] `CreateGrant(ctx, params) (*GrantResult, error)` +- [x] `GetGrantByService(ctx, serviceID) (*GrantResult, error)` +- [x] `UpdateGrantScopes(ctx, grantID, scopes, accounts) error` +- [x] `UpdateGrantLastUsed(ctx, grantID) error` +- [x] `SuspendGrant(ctx, grantID) error` +- [x] `ReactivateGrant(ctx, grantID) error` +- [x] `CountActiveGrants(ctx) (int64, error)` ### 4.6 Account Actions (Extend Existing) @@ -299,19 +310,19 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar ### 4.7 Credential Actions (Extend Existing) -- [ ] `CreateCredential(ctx, params) (*CredentialResult, error)` -- [ ] `UpdateCredentialCounter(ctx, credentialID, signCount) error` -- [ ] `RenameCredential(ctx, credentialID, name) error` -- [ ] `DeleteCredential(ctx, credentialID) error` -- [ ] `CountCredentialsByDID(ctx) (int64, error)` +- [x] `CreateCredential(ctx, params) (*CredentialResult, error)` +- [x] `UpdateCredentialCounter(ctx, credentialID, signCount) error` +- [x] `RenameCredential(ctx, credentialID, name) error` +- [x] `DeleteCredential(ctx, credentialID) error` +- [x] `CountCredentialsByDID(ctx) (int64, error)` ### 4.8 Session Actions (Extend Existing) -- [ ] `GetSessionByID(ctx, sessionID) (*SessionResult, error)` -- [ ] `GetCurrentSession(ctx) (*SessionResult, error)` -- [ ] `UpdateSessionActivity(ctx, sessionID) error` -- [ ] `SetCurrentSession(ctx, sessionID) error` -- [ ] `DeleteExpiredSessions(ctx) error` +- [x] `GetSessionByID(ctx, sessionID) (*SessionResult, error)` +- [x] `GetCurrentSession(ctx) (*SessionResult, error)` +- [x] `UpdateSessionActivity(ctx, sessionID) error` +- [x] `SetCurrentSession(ctx, sessionID) error` +- [x] `DeleteExpiredSessions(ctx) error` ### 4.9 Sync Checkpoint Actions @@ -355,12 +366,12 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar ### 6.1 Extend `exec` Resource Handlers -- [ ] Add `key_shares` resource handler -- [x] Add `ucans` resource handler (v1.0.0-rc.1 delegations) -- [x] Add `delegations` resource handler (v1.0.0-rc.1) +- [x] Add `key_shares` resource handler (list, get, rotate, archive, delete) +- [x] Add `ucans` resource handler (v1.0.0-rc.1 delegations - list, get, revoke, verify, cleanup) +- [x] Add `delegations` resource handler (v1.0.0-rc.1 - list, list_received, list_command, get, revoke, verify) - [ ] Add `invocations` resource handler (v1.0.0-rc.1) -- [x] Add `verification_methods` resource handler -- [x] Add `services` resource handler +- [x] Add `verification_methods` resource handler (list, get, delete) +- [x] Add `services` resource handler (list, get, get_by_id) - [ ] Add `sync_checkpoints` resource handler ### 6.2 Extend `generate` Function @@ -523,22 +534,23 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar - ~~Database integration (1.8)~~ ✅ Schema, queries, and actions complete - MPC signing integration (1.9) - Next priority -2. **High Priority (Core Functionality)** - - Database Serialization (3.1, 3.2) - - Credential Creation (6.2, 4.7) - - Key Share Actions (4.1) - - Account Actions (4.6) - - Delegation Loader for go-ucan (1.6) +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 -3. **Medium Priority (Authorization)** - - Revocation checker for go-ucan (1.7) - - MPC Signing (1.9) - - Encryption Strategy (2.1, 2.2) +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 4. **Lower Priority (Enhancement)** - TypeScript SDK (9.x) - DID State Sync (8.x) - - Additional exec handlers (6.1) + - Sync checkpoints handler (6.1) - Testing (10.x) - Security Hardening (11.x) @@ -546,6 +558,60 @@ The following files implement UCAN v1.0.0-rc.1 using the official go-ucan librar ## 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: