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

25 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 - 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 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 Complete actions_keyshare.go - Full key share management
Database Serialization Complete Native SQLite serialization via ncruces/go-sqlite3/ext/serdes
BIP44 Multi-Chain Complete SQLite functions: bip44_derive(), bip44_derive_from_enclave()
MPC Signing Complete SignWithEnclave() via exec handlers

Architecture: SQLite as DID CPU

The enclave uses a SQLite-centric architecture where custom functions, JSON1 extension, and encryption at rest make the database the central computation engine for DID operations.

Core Principles

  1. Custom SQLite Functions - Crypto operations live in the database layer

    • bip44_derive(pubkey, chain) - BIP44 address derivation
    • bip44_derive_from_enclave(enclave_id, chain) - Derive from stored enclave
    • enclave_sign(enclave_id, data) - Sign with MPC key (planned)
    • ucan_* functions for UCAN operations (planned)

  2. JSON1 Extension - UCAN envelope manipulation in SQL

    • Extract fields from DAG-JSON encoded envelopes
    • Policy evaluation via JSON path queries
    • Build query results as JSON directly

  3. Encryption at Rest - Application-level AES-256-GCM

    • Serialize() → EncryptBytes() → storage
    • WebAuthn PRF key derivation for encryption key
    • Full database encrypted as single blob

  4. Generated Columns & Views - Computed DID state

    • is_expired, is_active for delegation status
    • valid_delegations view for chain validation
    • Recursive CTEs for proof chain traversal

Implemented SQLite Functions

Function Location Purpose
bip44_derive(pubkey_hex, chain) functions.go Derive address from public key
bip44_derive_from_enclave(enclave_id, chain) functions.go Derive address from stored enclave

Planned SQLite Functions

Function Purpose
enclave_sign(enclave_id, data) Sign data with enclave's MPC key
ucan_sign(enclave_id, payload) Sign UCAN payload, return varsig
ucan_seal(enclave_id, delegation_json) Build complete sealed envelope
ucan_parse_envelope(blob) Extract UCAN fields as JSON
ucan_policy_match(policy, args) Evaluate policy against args
ucan_cmd_subsumes(parent, child) Check command hierarchy
ucan_chain_valid(invocation_cid) Validate full proof chain

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

Architecture: Use SQLite JSON1 extension for policy evaluation in queries.

  • Policy evaluation via go-ucan's invocation.ExecutionAllowed(loader)
  • Create ucan_policy_match(policy_json, args_json) SQLite function
    • Evaluate policy statements against invocation args
    • Support all UCAN policy operators (==, !=, <, >, like, glob)
  • Create ucan_cmd_subsumes(parent_cmd, child_cmd) SQLite function
    • Check command hierarchy (e.g., /vault/* covers /vault/read)
  • Add computed columns/indexes for common policy queries

1.6 Proof Chain Validation

Architecture: SQLite recursive CTEs for chain traversal, JSON extraction for envelope parsing.

  • Chain validation via go-ucan library
  • Delegation storage in SQLite via actions_delegation.go
    • GetDelegationByCID, GetDelegationEnvelope methods
    • ListDelegations* methods for chain traversal
  • Create ucan_chain_valid(invocation_cid) SQLite function
    • Recursive CTE to walk proof chain via prf field
    • Check each delegation's expiry, revocation, and policy
    • Return validation result as JSON
  • Create ucan_parse_envelope(envelope_blob) SQLite function
    • Extract iss, aud, sub, cmd, pol, exp, nbf from DAG-CBOR
    • Return as JSON for SQL queries
  • Implement delegation.Loader interface backed by SQLite queries

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

Architecture: Leverage SQLite custom functions for UCAN signing, keeping crypto operations in the database layer.

  • Create ucan_sign(enclave_id, payload) SQLite function
    • Sign DAG-CBOR encoded delegation/invocation payloads
    • Return varsig-encoded signature bytes
  • Create ucan_seal(enclave_id, delegation_json) SQLite function
    • Build sealed envelope from JSON input
    • Compute CID and return complete envelope
  • Integrate with go-ucan's crypto.Signer interface via SQLite bridge

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 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
  • DeriveKeyWithContext() for purpose-specific key derivation

2.2 Database Encryption

  • Implement application-level AES-256-GCM encryption for serialized pages
  • Add encryption wrapper around Serialize() output (EncryptBytes())
  • Add decryption wrapper for Load() input (DecryptBytes())
  • Store encryption metadata (version, nonce, auth tag) with serialized data
  • SecureZero() for memory clearing of sensitive data

2.3 Encrypted Database Wrapper

  • Create internal/enclave/enclave.go - Encrypted database wrapper
    • Enclave struct wrapping Keybase with encryption key
    • SerializeEncrypted() - Export encrypted database
    • LoadEncrypted() - Load from encrypted bytes
    • Export() / Import() - Full bundle operations with DID
    • EncryptedBundle struct with JSON marshaling
  • Create internal/enclave/crypto.go - WebAuthn PRF key derivation
    • Encrypt() / Decrypt() with EncryptedData struct
    • EncryptBytes() / DecryptBytes() convenience functions
    • GenerateNonce() for secure random nonce generation
  • Integrate with existing internal/keybase package via FromExisting()

3. Database Serialization

Status: ✅ Complete - Using native SQLite serialization via ncruces/go-sqlite3/ext/serdes

3.1 Native SQLite Serialization

  • Serialize() using serdes.Serialize(conn, "main") - Binary database export
  • Full database state captured as byte slice
  • No SQL parsing needed - direct database format
  • Preserves all data types, indexes, and constraints

3.2 Native SQLite Deserialization

  • Load() using serdes.Deserialize(conn, "main", data) - Binary import
  • RestoreFromDump() for encrypted bundle loading
  • Automatic DID context restoration after load
  • Integrated with internal/enclave for encrypted storage

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)
  • ListVerificationMethodsFull(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 - bip44_derive() SQLite function
  • Support multiple chains (Cosmos 118, Ethereum 60, Bitcoin 0) - initializeWithMPC()
  • Generate proper bech32 address encoding per chain - bip44_derive_from_enclave() SQLite function

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 (list, get, rotate, archive, delete)
  • Add ucans resource handler (v1.0.0-rc.1 delegations - list, get, revoke, verify, cleanup)
  • 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)
  • Add verification_methods resource handler (list, get, delete)
  • Add services resource handler (list, get, get_by_id)
  • 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

  • Support signing with MPC key shares - SignWithEnclave() in actions_enclave.go
  • Return signature in appropriate format - hex-encoded secp256k1 signature
  • Log signing operations for audit - logged via keybase actions
  • Implement dedicated sign wasmexport function (currently via exec handlers)
  • Add enclave_sign() SQLite function for in-query signing

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

Architecture: SQLite triggers and views for real-time delegation validation.

7.1 Delegation Chain Management

  • Create delegation_depth generated column using recursive CTE
  • Add CHECK constraint for max depth (e.g., 10 levels)
  • Create valid_delegations view joining chain validation
  • Index on (aud, cmd) for efficient capability lookups

7.2 Policy Attenuation (SQLite Functions)

  • ucan_policy_subsumes(parent_pol, child_pol) - Check attenuation
  • ucan_cmd_covers(parent_cmd, child_cmd) - Command hierarchy
  • Add trigger BEFORE INSERT ON ucan_delegations to validate attenuation

7.3 Delegation Status (SQLite Automation)

  • is_expired generated column: exp IS NOT NULL AND exp < unixepoch()
  • is_active generated column: NOT is_expired AND NOT is_revoked
  • Create expired_delegations view for cleanup queries
  • Add partial index on is_active = 1 for fast lookups

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 Key Derivation (5.2) ✅ BIP44 SQLite functions complete
    • MPC Signing (6.3) ✅ SignWithEnclave via exec handlers

  2. High Priority (SQLite Functions) - Next Phase

    • ucan_sign() / ucan_seal() SQLite functions (1.9)
    • ucan_parse_envelope() for JSON extraction (1.6)
    • ucan_chain_valid() for proof validation (1.6)
    • enclave_sign() for general signing (6.3)
    • Invocations exec handler (6.1)

  3. Medium Priority (SQLite Automation)

    • Generated columns for delegation status (7.3)
    • Policy evaluation functions (1.5, 7.2)
    • Delegation depth constraints (7.1)
    • Revocation cascade triggers (1.7)

  4. Lower Priority (Enhancement)

    • TypeScript SDK (9.x)
    • DID State Sync (8.x)
    • Testing (10.x)
    • Security Hardening (11.x)

See CHANGELOG.md for completed items and version history.

Reference in New Issue View Git Blame Copy Permalink