x/motr-enclave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c1e7d772a18bdffc2b0c6f0e742e993891a10ecf
motr-enclave/TODO.md

18 KiB
Raw Blame History

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
SQLC Queries Complete internal/migrations/query.sql
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 CRITICAL Go implementation uses deprecated JWT format
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)

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

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)

  • 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)
  • CleanExpiredUCANs(ctx) error

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
  • Encrypt share data before storage
  • Store public key and chain code
  • Track party index and threshold

5.2 Account Derivation

  • Implement BIP44 derivation path parsing
  • Derive addresses from public keys
  • Support multiple chains (Cosmos 118, Ethereum 60)
  • Generate proper address encoding per chain

5.3 Key Rotation

  • Implement key rotation workflow
  • Archive old shares
  • Update status transitions
  • Handle rotation failures gracefully

6. Plugin Function Extensions

Reference: main.go

6.1 Extend exec Resource Handlers

  • Add key_shares 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

6.2 Extend generate Function

  • Parse WebAuthn credential properly (CBOR/COSE format)
  • Extract public key from credential
  • Create initial verification method
  • Create initial credential record
  • Generate initial account (if key share provided)

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)

    • 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. 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. 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
Reference in New Issue View Git Blame Copy Permalink