motr-enclave/TODO.md

Implementation TODO

Remaining tasks from MIGRATION.md for the Nebula Key Enclave.

Status Summary

Category	Status	Notes
Schema (10 tables)	Complete	internal/migrations/schema.sql - Updated for v1.0.0-rc.1
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
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

---

1. UCAN v1.0.0-rc.1 Migration (CRITICAL PRIORITY)

Status: Core implementation complete using github.com/ucan-wg/go-ucan v1.1.0. Deprecated JWT-based files deleted. Remaining work is database integration and MPC signing.

Completed Implementation

The following files implement UCAN v1.0.0-rc.1 using the official go-ucan library:

File	Status	Description
ucan.go	✅ Complete	Type re-exports, Sonr commands, pre-parsed constants
policy.go	✅ Complete	PolicyBuilder fluent API, Sonr-specific policy helpers
delegation.go	✅ Complete	DelegationBuilder fluent API, Sonr delegation helpers
invocation.go	✅ Complete	InvocationBuilder fluent API, Sonr invocation helpers
types.go	✅ Complete	ValidationError, Capability, ExecutionResult, Sonr types

Dependencies Added

• github.com/ucan-wg/go-ucan v1.1.0 - Official UCAN library
• github.com/ipld/go-ipld-prime v0.21.0 - IPLD encoding
• github.com/MetaMask/go-did-it v1.0.0-pre1 - DID handling (indirect)
• github.com/ipfs/go-cid v0.5.0 - Content addressing (indirect)

Deleted (Deprecated JWT-based)

• jwt.go - Removed
• capability.go - Removed
• verifier.go - Removed
• source.go - Removed
• internal/crypto/mpc/spec/ - Entire directory removed

1.1 Core Data Structures

• Create internal/crypto/ucan/types.go - v1.0.0-rc.1 types

  • Re-export Delegation and Invocation from go-ucan
  • Task struct (sub, cmd, args, nonce)
  • ReceiptPayload struct (iss, ran, out, fx, meta, iat)
  • RevocationPayload struct
  • ValidationError with error codes matching TypeScript
  • Capability struct (sub, cmd, pol)
  • ExecutionResult[T, E] generic type
  • Sonr-specific types: VaultCapability, DIDCapability, DWNCapability

• Create internal/crypto/ucan/policy.go - Policy Language

  • PolicyBuilder fluent API with all operators
  • Equal, NotEqual - equality statements
  • GreaterThan, LessThan, etc. - inequality statements
  • Like - glob pattern matching
  • Not, And, Or - logical connectives
  • All, Any - quantifiers
  • Sonr helpers: VaultPolicy, DIDPolicy, ChainPolicy, AccountPolicy

• Create internal/crypto/ucan/ucan.go - Command types

  • Command type re-exported from go-ucan
  • Sonr commands: /vault/*, /did/*, /dwn/*, /ucan/revoke
  • Pre-parsed command constants: VaultRead, VaultWrite, DIDUpdate, etc.
  • CommandSubsumes() helper using go-ucan's Covers() method

1.2 Envelope Format & Encoding

• Envelope handling via go-ucan library

  • ToSealed() method produces DAG-CBOR bytes + CID
  • ToDagCbor(), ToDagJson() encoding methods
  • CID computation handled by go-ucan

• Varsig support via go-ucan library

  • Ed25519, P-256, secp256k1 via go-did-it/crypto

1.3 Delegation Operations

• Create internal/crypto/ucan/delegation.go - Delegation creation/validation
  • DelegationBuilder fluent API
  • NewDelegation, NewRootDelegation, NewPowerlineDelegation re-exports
  • BuildSealed(privKey) for signing
  • Sonr helpers: NewVaultDelegation, NewDIDDelegation, NewDWNDelegation
  • Temporal options: ExpiresAt, ExpiresIn, NotBefore, NotBeforeIn

1.4 Invocation Operations

• Create internal/crypto/ucan/invocation.go - Invocation creation/validation
  • InvocationBuilder fluent API
  • NewInvocation re-export
  • BuildSealed(privKey) for signing
  • Proof chain management: Proof(), Proofs()
  • Sonr helpers: VaultReadInvocation, VaultSignInvocation, DIDUpdateInvocation

1.5 Policy Evaluation Engine

Note: go-ucan provides ExecutionAllowed() on invocations which validates proofs and evaluates policies.

• 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

1.6 Proof Chain Validation

Note: go-ucan handles chain validation internally via ExecutionAllowed().

• Chain validation via go-ucan library
• Delegation storage in SQLite via actions_delegation.go
  • GetDelegationByCID, GetDelegationEnvelope methods
  • 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

1.7 Revocation

• RevocationInvocation() helper in invocation.go
• Revocation storage via actions_delegation.go
  • RevokeDelegation(ctx, params) - Create revocation record
  • IsDelegationRevoked(ctx, cid) (bool, error) - Query revocation status
• Create internal/crypto/ucan/revocation.go - Revocation checker for go-ucan
  • Implement revocation checking interface
  • Integration with chain validation via ExecutionAllowed()

1.8 Database Integration

• Update internal/migrations/schema.sql for v1.0.0-rc.1

  • ucan_delegations table (cid, envelope BLOB, iss, aud, sub, cmd, pol, nbf, exp, is_root, is_powerline)
  • ucan_invocations table (cid, envelope BLOB, iss, sub, aud, cmd, prf, exp, iat, executed_at, result_cid)
  • ucan_revocations table (delegation_cid, revoked_by, invocation_cid, reason)
  • Indexes on iss, aud, sub, cmd for efficient queries

• Update internal/migrations/query.sql for v1.0.0-rc.1

  • CreateDelegation, GetDelegationByCID, GetDelegationEnvelopeByCID
  • ListDelegationsByDID, ListDelegationsByIssuer, ListDelegationsByAudience, ListDelegationsBySubject
  • ListDelegationsForCommand, ListRootDelegations, ListPowerlineDelegations
  • CreateInvocation, GetInvocationByCID, GetInvocationEnvelopeByCID
  • ListInvocationsByDID, ListInvocationsByIssuer, ListInvocationsForCommand
  • MarkInvocationExecuted, ListPendingInvocations
  • CreateRevocation, IsDelegationRevoked, GetRevocation, ListRevocationsByRevoker

• Create internal/keybase/actions_delegation.go - Delegation action handlers

  • StoreDelegation, GetDelegationByCID, GetDelegationEnvelope
  • ListDelegations, ListDelegationsByIssuer, ListDelegationsByAudience
  • ListDelegationsForCommand, IsDelegationRevoked, RevokeDelegation
  • DeleteDelegation, CleanExpiredDelegations

• Create internal/keybase/actions_invocation.go - Invocation action handlers

  • StoreInvocation, GetInvocationByCID, GetInvocationEnvelope
  • ListInvocations, ListInvocationsByCommand, ListPendingInvocations
  • MarkInvocationExecuted, CleanOldInvocations

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

1.10 Testing

• Unit tests for builders (DelegationBuilder, InvocationBuilder)
• Unit tests for policy helpers
• Unit tests for Sonr-specific invocations
• Interoperability tests against TypeScript implementation
• Test vectors from UCAN spec

---

2. Encryption Strategy

Reference: MIGRATION.md lines 770-814

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

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

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

---

3. Database Serialization

Current implementation in conn.go:exportDump() only outputs comments

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

3.2 Proper Deserialization

• Parse serialized SQL dump in Load()
• Execute INSERT statements to restore data
• Validate data integrity after restore
• Handle schema version mismatches

---

4. Action Manager Extensions

Reference: internal/keybase/actions.go

4.1 Key Share Actions

• CreateKeyShare(ctx, params) (*KeyShareResult, error)
• ListKeyShares(ctx) ([]KeyShareResult, error)
• GetKeyShareByID(ctx, shareID) (*KeyShareResult, error)
• GetKeyShareByKeyID(ctx, keyID) (*KeyShareResult, error)
• RotateKeyShare(ctx, shareID) error
• ArchiveKeyShare(ctx, shareID) error
• DeleteKeyShare(ctx, shareID) error

4.2 UCAN Token Actions (v1.0.0-rc.1)

• StoreDelegation(ctx, params) (*DelegationResult, error)
• ListDelegations(ctx) ([]DelegationResult, error)
• GetDelegationByCID(ctx, cid) (*DelegationResult, error)
• GetDelegationEnvelope(ctx, cid) ([]byte, error)
• ListDelegationsByIssuer(ctx, issuer) ([]DelegationResult, error)
• ListDelegationsByAudience(ctx, audience) ([]DelegationResult, error)
• ListDelegationsForCommand(ctx, cmd) ([]DelegationResult, error)
• StoreInvocation(ctx, params) (*InvocationResult, error)
• GetInvocationByCID(ctx, cid) (*InvocationResult, error)
• GetInvocationEnvelope(ctx, cid) ([]byte, error)
• ListInvocations(ctx, limit) ([]InvocationResult, error)
• ListInvocationsByCommand(ctx, cmd, limit) ([]InvocationResult, error)
• ListPendingInvocations(ctx) ([]InvocationResult, error)
• MarkInvocationExecuted(ctx, cid, resultCID) error
• RevokeDelegation(ctx, params) error
• IsDelegationRevoked(ctx, cid) (bool, error)
• DeleteDelegation(ctx, cid) error
• CleanExpiredDelegations(ctx) error
• CleanOldInvocations(ctx) error
• ValidateInvocation(ctx, invocation) (*ValidationResult, error) - Requires delegation.Loader

4.3 Verification Method Actions

• CreateVerificationMethod(ctx, params) (*VerificationMethodResult, error)
• ListVerificationMethods(ctx) ([]VerificationMethodResult, error)
• GetVerificationMethod(ctx, methodID) (*VerificationMethodResult, error)
• 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)

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)

4.6 Account Actions (Extend Existing)

• CreateAccount(ctx, params) (*AccountResult, error)
• ListAccountsByChain(ctx, chainID) ([]AccountResult, error)
• GetDefaultAccount(ctx, chainID) (*AccountResult, error)
• SetDefaultAccount(ctx, accountID, chainID) error
• UpdateAccountLabel(ctx, accountID, label) error
• DeleteAccount(ctx, accountID) error

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)

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

4.9 Sync Checkpoint Actions

• GetSyncCheckpoint(ctx, resourceType) (*SyncCheckpointResult, error)
• UpsertSyncCheckpoint(ctx, params) error
• ListSyncCheckpoints(ctx) ([]SyncCheckpointResult, error)

---

5. MPC Key Share Management

Reference: MIGRATION.md lines 823-824

5.1 Key Share Storage

• Parse key share data from MPC protocol - KeyShareInput in generate
• Store public key and chain code - CreateKeyShare action
• Track party index and threshold - stored in key_shares table
• Encrypt share data before storage - PRF key derivation needed

5.2 Account Derivation

• Basic address derivation from public key - deriveCosmosAddress()
• 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

5.3 Key Rotation

• Implement key rotation workflow - RotateKeyShare action
• Archive old shares - ArchiveKeyShare action
• Status transitions - managed in database
• Handle rotation failures gracefully

---

6. Plugin Function Extensions

Reference: main.go

6.1 Extend exec Resource Handlers

• Add key_shares resource handler
• Add ucans resource handler (v1.0.0-rc.1 delegations)
• 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

6.2 Extend generate Function

• Accept optional MPC keyshare data in input
• Create initial keyshare if provided
• Create initial account from keyshare
• Parse WebAuthn credential properly (CBOR/COSE format)
• Extract public key from credential
• Create initial verification method
• Create initial credential record

6.3 Signing Function

• Implement sign wasmexport function
• Support signing with MPC key shares
• Return signature in appropriate format
• Log signing operations for audit

---

7. Capability Delegation (v1.0.0-rc.1)

Reference: UCAN Delegation specification

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

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)
• Update status on expiry

---

8. DID State Sync

Reference: MIGRATION.md line 827

8.1 Sync Infrastructure

• Create internal/enclave/sync.go - DID state sync logic
• Implement checkpoint tracking
• Store last synced block height
• Track last processed transaction hash

8.2 Sync Operations

• Fetch DID document updates from chain
• Validate on-chain document hash
• Update local state on changes
• Handle reorgs and rollbacks

---

9. TypeScript SDK

Reference: README.md, src/ directory

9.1 Core SDK

• Implement createEnclave(wasmPath) factory
• Implement generate(credential) wrapper
• Implement load(database) wrapper
• Implement exec(filter, token?) wrapper
• Implement query(did?) wrapper

9.2 UCAN SDK (v1.0.0-rc.1)

• Delegation builder using src/ucan.ts types
• Invocation builder
• Policy builder helpers
• Envelope encoding/decoding (DAG-CBOR)
• CID computation

9.3 WebAuthn Integration

• Helper for credential creation
• Helper for PRF extension output
• Proper encoding/decoding utilities

---

10. Testing

10.1 Unit Tests

• Test all ActionManager methods
• Test serialization/deserialization roundtrip
• Test encryption/decryption
• Test UCAN policy evaluation
• Test UCAN envelope encoding

10.2 Integration Tests

• Test full generate -> load -> exec flow
• Test credential lifecycle
• Test session management
• Test grant management
• Test UCAN delegation chain

10.3 Plugin Tests

• Extend make test-plugin with all functions
• 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

11.1 Input Validation

• Validate all JSON inputs against schemas
• Sanitize SQL-sensitive characters in serialization
• Validate DID format on all inputs
• Validate base64 encoding

11.2 Cryptographic Security

• Use constant-time comparison for sensitive data
• Clear sensitive data from memory after use
• Validate key sizes and formats
• Implement proper nonce generation

11.3 Access Control

• Enforce DID ownership on all mutations
• Validate session before sensitive operations
• Check grant scopes before data access
• Log security-relevant operations

---

Priority Order

1. CRITICAL (Spec Compliance) - ✅ Complete

   • UCAN v1.0.0-rc.1 Migration (Section 1) ✅ All core items complete
   • Core data structures (1.1) ✅ Using go-ucan v1.1.0
   • Envelope format (1.2) ✅ Handled by go-ucan
   • 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

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)

3. Medium Priority (Authorization)

   • Revocation checker for go-ucan (1.7)
   • MPC Signing (1.9)
   • 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)

---

Completed Items

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