feat(ucan): migrate to UCAN v1.0.0-rc.1 envelope format

2026-01-08 14:54:40 -05:00
parent f6dde77e60
commit e4943509c9
1 changed files with 231 additions and 86 deletions
--- 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