From e4943509c97038e55eecc76ae231a1c5ddf37011 Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Thu, 8 Jan 2026 14:54:40 -0500 Subject: [PATCH] feat(ucan): migrate to UCAN v1.0.0-rc.1 envelope format --- TODO.md | 317 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 231 insertions(+), 86 deletions(-) diff --git a/TODO.md b/TODO.md index cba3c3b..ed5d4d2 100644 --- a/TODO.md +++ b/TODO.md @@ -11,45 +11,187 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. | Generated Code | Complete | `internal/keybase/*.go` | | Basic Plugin Functions | Complete | `generate`, `load`, `exec`, `query`, `ping` | | Encryption | Not Started | WebAuthn PRF key derivation needed | -| UCAN Authorization | Placeholder | Validation logic not implemented | +| **UCAN v1.0.0-rc.1** | **CRITICAL** | Go implementation uses deprecated JWT format | | MPC Key Shares | Not Started | Key share management missing | | Database Serialization | Incomplete | Export dumps comments only | --- -## 1. Encryption Strategy +## 1. UCAN v1.0.0-rc.1 Migration (CRITICAL PRIORITY) + +> **Breaking Change**: Current Go implementation (`internal/crypto/ucan/`) uses deprecated JWT-based UCAN format. Must migrate to envelope format per v1.0.0-rc.1 spec. + +### Current State (DEPRECATED - Must Replace) + +The following files use the **old JWT-based format** and must be rewritten: + +| File | Status | Issue | +|------|--------|-------| +| `jwt.go` | DEPRECATED | Uses `github.com/golang-jwt/jwt/v5`, old `can`+`with` format | +| `capability.go` | DEPRECATED | Old Attenuation/Resource/Capability model | +| `verifier.go` | DEPRECATED | JWT parsing, old proof chain format | +| `source.go` | DEPRECATED | JWT token creation with MPC | +| `vault.go` | PARTIAL | VaultCapability needs Policy migration | + +### Reference Implementation (Already Compliant) + +These files are already aligned with v1.0.0-rc.1: +- `src/ucan.ts` - TypeScript types with envelope format +- `internal/codec/ucan-schemas.json` - JSON Schema definitions + +### 1.1 Core Data Structures + +- [ ] Create `internal/crypto/ucan/types.go` - v1.0.0-rc.1 types + - [ ] `DelegationPayload` struct (iss, aud, sub, cmd, pol, nonce, meta, nbf, exp) + - [ ] `InvocationPayload` struct (iss, sub, aud, cmd, args, prf, meta, nonce, exp, iat, cause) + - [ ] `Delegation` type as `[Signature, DelegationSigPayload]` tuple + - [ ] `Invocation` type as `[Signature, InvocationSigPayload]` tuple + - [ ] `Task` struct (sub, cmd, args, nonce) + - [ ] `ReceiptPayload` struct (iss, ran, out, fx, meta, iat) + - [ ] `RevocationPayload` struct + +- [ ] Create `internal/crypto/ucan/policy.go` - Policy Language + - [ ] `PolicyStatement` union type + - [ ] `EqualityStatement` - `["==", selector, value]` / `["!=", selector, value]` + - [ ] `InequalityStatement` - `[">", selector, number]` etc. + - [ ] `LikeStatement` - `["like", selector, glob]` + - [ ] `NotStatement` - `["not", statement]` + - [ ] `AndStatement` / `OrStatement` - logical connectives + - [ ] `AllStatement` / `AnyStatement` - quantifiers + - [ ] `Selector` parser (jq-inspired: `.foo`, `.bar[0]`, `.items[-1]`) + - [ ] `GlobPattern` matcher + +- [ ] Create `internal/crypto/ucan/command.go` - Command types + - [ ] `Command` type with validation (must start with `/`, lowercase, no trailing slash) + - [ ] Standard commands: `/crud/*`, `/msg/*`, `/ucan/revoke`, `/wasm/run` + - [ ] Custom Sonr commands: `/vault/*`, `/did/*`, `/dwn/*` + +### 1.2 Envelope Format & Encoding + +- [ ] Create `internal/crypto/ucan/envelope.go` - Envelope handling + - [ ] `UCANEnvelope[P]` generic type as `[Signature, {h: VarsigHeader} & P]` + - [ ] Encode envelope to CBOR (requires `github.com/fxamacker/cbor/v2`) + - [ ] Decode envelope from CBOR + - [ ] DAG-JSON encoding for interop + - [ ] CID computation (DAG-CBOR codec, SHA-256 multihash, base58btc) + +- [ ] Create `internal/crypto/ucan/varsig.go` - Varsig v1 headers + - [ ] Varsig header encoding/decoding + - [ ] Algorithm metadata extraction + - [ ] Support Ed25519, P-256, secp256k1 + +### 1.3 Delegation Operations + +- [ ] Create `internal/crypto/ucan/delegation.go` - Delegation creation/validation + - [ ] `NewDelegation(issuer, audience, subject, cmd, policy, exp, meta)` builder + - [ ] Sign delegation with issuer private key + - [ ] Validate delegation signature + - [ ] Validate delegation payload (temporal, structural) + - [ ] Extract `Capability` from delegation (sub + cmd + pol) + +### 1.4 Invocation Operations + +- [ ] Create `internal/crypto/ucan/invocation.go` - Invocation creation/validation + - [ ] `NewInvocation(issuer, subject, cmd, args, proofs, exp)` builder + - [ ] Sign invocation with invoker private key + - [ ] Validate invocation signature + - [ ] Validate proof chain (CID references to delegations) + - [ ] Evaluate policies against invocation args + +### 1.5 Policy Evaluation Engine + +- [ ] Create `internal/crypto/ucan/eval.go` - Policy evaluation + - [ ] `EvaluatePolicy(policy Policy, args Arguments) (bool, error)` + - [ ] Selector resolution against IPLD data + - [ ] Equality comparison (deep IPLD equality) + - [ ] Numeric comparisons + - [ ] Glob pattern matching for `like` operator + - [ ] Logical connectives (`and`, `or`, `not`) + - [ ] Quantifiers (`all`, `any`) over collections + +### 1.6 Proof Chain Validation + +- [ ] Create `internal/crypto/ucan/chain.go` - Chain validation + - [ ] Resolve CID to Delegation (requires delegation store) + - [ ] Validate chain continuity (child.iss == parent.aud) + - [ ] Validate capability attenuation (child.cmd subsumes parent.cmd) + - [ ] Validate policy attenuation (child.pol more restrictive than parent.pol) + - [ ] Validate temporal bounds (child.exp <= parent.exp) + - [ ] Check revocation status for all chain members + +### 1.7 Revocation + +- [ ] Create `internal/crypto/ucan/revocation.go` - Revocation handling + - [ ] `NewRevocation(revoker, delegation_cid)` builder + - [ ] Validate revoker is in delegation's issuer chain + - [ ] Store revocation in database + - [ ] Query revocation status by CID + +### 1.8 Database Integration + +- [ ] Update `internal/migrations/schema.sql` for v1.0.0-rc.1 + - [ ] `ucan_delegations` table (cid, envelope_cbor, iss, aud, sub, cmd, exp, created_at) + - [ ] `ucan_invocations` table (cid, envelope_cbor, iss, sub, cmd, exp, created_at) + - [ ] `ucan_revocations` table (cid, delegation_cid, revoker, created_at) + - [ ] Indexes on iss, aud, sub, cmd for efficient queries + +- [ ] Update `internal/migrations/query.sql` for v1.0.0-rc.1 + - [ ] `InsertDelegation`, `GetDelegationByCID`, `ListDelegationsByAudience` + - [ ] `InsertInvocation`, `GetInvocationByCID` + - [ ] `InsertRevocation`, `IsRevoked`, `GetRevocationsByDelegation` + +### 1.9 Migration from Old Format + +- [ ] Create migration script for existing UCAN data (if any) +- [ ] Remove deprecated files after migration complete: + - [ ] `jwt.go` - Remove entirely + - [ ] `capability.go` - Replace with policy-based capabilities + - [ ] `verifier.go` - Replace with envelope-based verification + - [ ] `source.go` - Replace with envelope-based token creation + +### 1.10 Testing + +- [ ] Unit tests for policy evaluation +- [ ] Unit tests for envelope encoding/decoding +- [ ] Unit tests for chain validation +- [ ] Interoperability tests against TypeScript implementation +- [ ] Test vectors from UCAN spec + +--- + +## 2. Encryption Strategy > Reference: MIGRATION.md lines 770-814 -### 1.1 WebAuthn PRF Key Derivation +### 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 -### 1.2 Database Encryption +### 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 -### 1.3 Encrypted Database Wrapper +### 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 --- -## 2. Database Serialization +## 3. Database Serialization > Current implementation in `conn.go:exportDump()` only outputs comments -### 2.1 Proper Serialization +### 3.1 Proper 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 -### 2.2 Proper Deserialization +### 3.2 Proper Deserialization - [ ] Parse serialized SQL dump in `Load()` - [ ] Execute INSERT statements to restore data - [ ] Validate data integrity after restore @@ -57,11 +199,11 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. --- -## 3. Action Manager Extensions +## 4. Action Manager Extensions > Reference: `internal/keybase/actions.go` -### 3.1 Key Share Actions +### 4.1 Key Share Actions - [ ] `CreateKeyShare(ctx, params) (*KeyShareResult, error)` - [ ] `ListKeyShares(ctx) ([]KeyShareResult, error)` - [ ] `GetKeyShareByID(ctx, shareID) (*KeyShareResult, error)` @@ -70,39 +212,31 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. - [ ] `ArchiveKeyShare(ctx, shareID) error` - [ ] `DeleteKeyShare(ctx, shareID) error` -### 3.2 UCAN Token Actions -- [ ] `CreateUCAN(ctx, params) (*UCANResult, error)` -- [ ] `ListUCANs(ctx) ([]UCANResult, error)` -- [ ] `GetUCANByCID(ctx, cid) (*UCANResult, error)` -- [ ] `ListUCANsByAudience(ctx, audience) ([]UCANResult, error)` +### 4.2 UCAN Token Actions (v1.0.0-rc.1) +- [ ] `CreateDelegation(ctx, params) (*DelegationResult, error)` +- [ ] `ListDelegations(ctx) ([]DelegationResult, error)` +- [ ] `GetDelegationByCID(ctx, cid) (*DelegationResult, error)` +- [ ] `ListDelegationsByAudience(ctx, audience) ([]DelegationResult, error)` +- [ ] `CreateInvocation(ctx, params) (*InvocationResult, error)` +- [ ] `ValidateInvocation(ctx, invocation) (*ValidationResult, error)` - [ ] `RevokeUCAN(ctx, cid) error` - [ ] `IsUCANRevoked(ctx, cid) (bool, error)` -- [ ] `CreateRevocation(ctx, params) error` - [ ] `CleanExpiredUCANs(ctx) error` -### 3.3 Delegation Actions -- [ ] `CreateDelegation(ctx, params) (*DelegationResult, error)` -- [ ] `ListDelegationsByDelegator(ctx, delegator) ([]DelegationResult, error)` -- [ ] `ListDelegationsByDelegate(ctx, delegate) ([]DelegationResult, error)` -- [ ] `ListDelegationsForResource(ctx, resource) ([]DelegationResult, error)` -- [ ] `GetDelegationChain(ctx, delegationID) ([]DelegationResult, error)` -- [ ] `RevokeDelegation(ctx, delegationID) error` -- [ ] `RevokeDelegationChain(ctx, delegationID) error` - -### 3.4 Verification Method Actions +### 4.3 Verification Method Actions - [ ] `CreateVerificationMethod(ctx, params) (*VerificationMethodResult, error)` - [ ] `ListVerificationMethods(ctx) ([]VerificationMethodResult, error)` - [ ] `GetVerificationMethod(ctx, methodID) (*VerificationMethodResult, error)` - [ ] `DeleteVerificationMethod(ctx, methodID) error` -### 3.5 Service Actions +### 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)` -### 3.6 Grant Actions (Extend Existing) +### 4.5 Grant Actions (Extend Existing) - [ ] `CreateGrant(ctx, params) (*GrantResult, error)` - [ ] `GetGrantByService(ctx, serviceID) (*GrantResult, error)` - [ ] `UpdateGrantScopes(ctx, grantID, scopes, accounts) error` @@ -111,7 +245,7 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. - [ ] `ReactivateGrant(ctx, grantID) error` - [ ] `CountActiveGrants(ctx) (int64, error)` -### 3.7 Account Actions (Extend Existing) +### 4.6 Account Actions (Extend Existing) - [ ] `CreateAccount(ctx, params) (*AccountResult, error)` - [ ] `ListAccountsByChain(ctx, chainID) ([]AccountResult, error)` - [ ] `GetDefaultAccount(ctx, chainID) (*AccountResult, error)` @@ -119,57 +253,27 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. - [ ] `UpdateAccountLabel(ctx, accountID, label) error` - [ ] `DeleteAccount(ctx, accountID) error` -### 3.8 Credential Actions (Extend Existing) +### 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)` -### 3.9 Session Actions (Extend Existing) +### 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` -### 3.10 Sync Checkpoint Actions +### 4.9 Sync Checkpoint Actions - [ ] `GetSyncCheckpoint(ctx, resourceType) (*SyncCheckpointResult, error)` - [ ] `UpsertSyncCheckpoint(ctx, params) error` - [ ] `ListSyncCheckpoints(ctx) ([]SyncCheckpointResult, error)` --- -## 4. UCAN Authorization - -> Reference: MIGRATION.md lines 820-821 - -### 4.1 Token Validation -- [ ] Implement proper UCAN token parsing (JWT-like structure) -- [ ] Validate token signature against issuer's public key -- [ ] Check token expiration (`exp` claim) -- [ ] Check token not-before (`nbf` claim) -- [ ] Validate audience matches expected DID - -### 4.2 Capability Verification -- [ ] Parse capabilities array from token -- [ ] Match requested action against granted capabilities -- [ ] Implement resource pattern matching (e.g., `sonr://vault/*`) -- [ ] Respect action restrictions (e.g., `sign`, `read`, `write`) - -### 4.3 Proof Chain Validation -- [ ] Follow proof chain to root UCAN -- [ ] Validate each link in the chain -- [ ] Ensure capability attenuation (child can't exceed parent) -- [ ] Check revocation status for all tokens in chain - -### 4.4 Revocation Checking -- [ ] Query `ucan_revocations` table -- [ ] Check all tokens in proof chain -- [ ] Cache revocation status for performance - ---- - ## 5. MPC Key Share Management > Reference: MIGRATION.md lines 823-824 @@ -201,8 +305,8 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. ### 6.1 Extend `exec` Resource Handlers - [ ] Add `key_shares` resource handler -- [ ] Add `ucans` resource handler -- [ ] Add `delegations` resource handler +- [ ] Add `delegations` resource handler (v1.0.0-rc.1) +- [ ] Add `invocations` resource handler (v1.0.0-rc.1) - [ ] Add `verification_methods` resource handler - [ ] Add `services` resource handler - [ ] Add `sync_checkpoints` resource handler @@ -224,18 +328,24 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. --- -## 7. Capability Delegation +## 7. Capability Delegation (v1.0.0-rc.1) -> Reference: MIGRATION.md lines 826-827 +> Reference: UCAN Delegation specification ### 7.1 Delegation Chain Management - [ ] Enforce maximum delegation depth (prevent infinite chains) -- [ ] Validate delegator has capability to delegate -- [ ] Ensure proper capability attenuation -- [ ] Track parent-child relationships +- [ ] Validate delegator has capability to delegate (sub field) +- [ ] Ensure proper capability attenuation (cmd + pol) +- [ ] Track parent-child relationships via CID references -### 7.2 Delegation Status +### 7.2 Policy Attenuation + +- [ ] Child policy must be more restrictive than parent +- [ ] Implement policy subsumption checking +- [ ] Command hierarchy validation (`/crud/*` subsumes `/crud/read`) + +### 7.3 Delegation Status - [ ] Implement expiration checking - [ ] Handle revocation cascades (revoke chain) @@ -274,11 +384,13 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. - [ ] Implement `exec(filter, token?)` wrapper - [ ] Implement `query(did?)` wrapper -### 9.2 Type Definitions +### 9.2 UCAN SDK (v1.0.0-rc.1) -- [ ] Generate TypeScript types from Go structs -- [ ] Export type definitions for consumers -- [ ] Add JSDoc documentation +- [ ] Delegation builder using `src/ucan.ts` types +- [ ] Invocation builder +- [ ] Policy builder helpers +- [ ] Envelope encoding/decoding (DAG-CBOR) +- [ ] CID computation ### 9.3 WebAuthn Integration @@ -295,14 +407,16 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. - [ ] Test all ActionManager methods - [ ] Test serialization/deserialization roundtrip - [ ] Test encryption/decryption -- [ ] Test UCAN validation logic +- [ ] Test UCAN policy evaluation +- [ ] Test UCAN envelope encoding ### 10.2 Integration Tests -- [ ] Test full generate → load → exec flow +- [ ] Test full generate -> load -> exec flow - [ ] Test credential lifecycle - [ ] Test session management - [ ] Test grant management +- [ ] Test UCAN delegation chain ### 10.3 Plugin Tests @@ -310,6 +424,12 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. - [ ] Add error case testing - [ ] Test with various input formats +### 10.4 Interoperability Tests + +- [ ] Go <-> TypeScript UCAN envelope compatibility +- [ ] CID computation consistency +- [ ] Policy evaluation consistency + --- ## 11. Security Hardening @@ -339,20 +459,45 @@ Remaining tasks from [MIGRATION.md](./MIGRATION.md) for the Nebula Key Enclave. ## Priority Order -1. **High Priority** (Core Functionality) - - Database Serialization (2.1, 2.2) - - Credential Creation (6.2, 3.8) - - Key Share Actions (3.1) - - Account Actions (3.7) +1. **CRITICAL (Spec Compliance)** + - UCAN v1.0.0-rc.1 Migration (Section 1) + - Core data structures (1.1) + - Envelope format (1.2) + - Delegation operations (1.3) + - Policy evaluation (1.5) -2. **Medium Priority** (Authorization) - - UCAN Validation (4.1, 4.2) - - Delegation Management (7.1, 7.2) - - Encryption Strategy (1.1, 1.2) +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) -3. **Lower Priority** (Enhancement) +3. **Medium Priority (Authorization)** + - Invocation operations (1.4) + - Proof chain validation (1.6) + - Revocation (1.7) + - Encryption Strategy (2.1, 2.2) + +4. **Lower Priority (Enhancement)** - TypeScript SDK (9.x) - DID State Sync (8.x) - Additional exec handlers (6.1) - Testing (10.x) - Security Hardening (11.x) + +--- + +## 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 envelope validation (1.2, 1.3) +- ~~Section 4.2 "Capability Verification" - `can`/`with` format~~ -> Replaced by policy evaluation (1.5) +- ~~Section 4.3 "Proof Chain Validation" - JWT proof strings~~ -> Replaced by CID-based chain (1.6) +- ~~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