View source on GitHub →

SDIS + Steward System Status

Date: 2025-12-12
Status: ✅ Infrastructure Deployed, ⚠️ Steward System Pending

Historical snapshot from 2025-12-12. Route truth source: icn/crates/icn-gateway/src/api/sdis/mod.rs and icn/crates/icn-gateway/src/api/sdis/simple_enrollment.rs.

Overview

The Secure Distributed Identity System (SDIS) has its infrastructure deployed on the ICN K3s cluster. API endpoints are live, but end-to-end enrollment requires the Steward system, which is not yet implemented (see SDIS_DEPLOYMENT_STATUS.md for details). This document provides the current status, what works, what's in progress, and next steps.

✅ What's Working

1. SDIS Core API (wired in this snapshot)

Base route: /v1/sdis

Enrollment + Steward workflow endpoints (wired):

  • ✅ POST /v1/sdis/enrollment/start - Start new enrollment
  • ✅ POST /v1/sdis/enrollment/verify/level1 - Verify device proof
  • ✅ POST /v1/sdis/enrollment/verify/level2 - Steward-level verification
  • ✅ POST /v1/sdis/enrollment/complete - Complete enrollment
  • ✅ GET /v1/sdis/status/{enrollment_id} - Enrollment status
  • ✅ GET /v1/sdis/pending - Pending enrollments
  • ✅ POST /v1/sdis/vouch/{enrollment_id} - Steward vouch action
  • ✅ POST /v1/sdis/reject/{enrollment_id} - Steward reject action
  • ✅ GET /v1/sdis/steward/stats - Steward metrics
  • ✅ GET /v1/sdis/steward/history - Steward history

Verification + utility endpoints (wired):

  • ✅ POST /v1/sdis/verify/level1 - QR/device verification
  • ✅ POST /v1/sdis/verify/level2 - Binding verification
  • ✅ POST /v1/sdis/ephemeral/generate - Generate ephemeral DID proof
  • ✅ GET /v1/sdis/health - Health check

Anchor management endpoints (wired):

  • ✅ GET /v1/sdis/anchor/{anchor_id} - Get anchor details
  • ✅ POST /v1/sdis/anchor/rotate-keys - Rotate anchor keys
  • ✅ GET /v1/sdis/anchor/{anchor_id}/history - Rotation history
  • ✅ POST /v1/sdis/anchor/devices/add - Add device to anchor
  • ✅ GET /v1/sdis/anchor/{anchor_id}/devices - List anchor devices

Recovery endpoints (wired):

  • ✅ POST /v1/sdis/recovery/start - Start recovery ceremony
  • ✅ GET /v1/sdis/recovery/{recovery_id} - Recovery status
  • ✅ POST /v1/sdis/recovery/{recovery_id}/approve - Steward approval
  • ✅ POST /v1/sdis/recovery/{recovery_id}/complete - Complete recovery

Known naming drift in older docs:

  • ⚠️ Some older docs use /v1/sdis/anchors/* or /v1/sdis/recovery/initiate; current wired paths use /v1/sdis/anchor/* and /v1/sdis/recovery/start.

Verified Working:

$ curl http://10.8.30.40:30080/v1/sdis/health
{"status":"healthy","timestamp":"2025-12-12T22:00:00Z"}

2. Backend Implementation (WIRED WITH MIXED MATURITY)

Location: icn/crates/icn-gateway/src/api/sdis/

  • ✅ enrollment.rs - Enrollment flow handlers
  • ✅ verify.rs - Multi-level verification
  • ✅ anchor.rs - Anchor device management handlers (wired)
  • ✅ recovery.rs - Identity recovery handlers (wired)
  • ✅ ephemeral.rs - Ephemeral DID generation
  • ✅ qr.rs - QR code generation
  • ✅ mod.rs - Route configuration

Server Integration:

  • ✅ Routes registered in server.rs
  • ✅ SDIS state management configured
  • ✅ Authentication middleware integrated

3. Identity System (V4 SDIS)

Location: icn/crates/icn-identity/

  • ✅ Multi-device key management
  • ✅ Anchor device tracking
  • ✅ Ephemeral DID generation
  • ✅ Recovery code management
  • ✅ Age-encrypted keystore (v4)
  • ✅ Ed25519 + X25519 key pairs

4. Trust Graph Integration

Location: icn/crates/icn-trust/

  • ✅ Trust score computation
  • ✅ Transitive trust calculation
  • ✅ Steward vouching mechanism
  • ✅ Trust-gated access control

5. Documentation

  • ✅ SDIS_API_GUIDE.md - Complete API documentation
  • ✅ SDIS_STEWARD_ROADMAP.md - System architecture
  • ✅ SDIS_SYSTEM.md - Technical design

🚧 In Progress

1. Pilot UI Integration

Location: web/pilot-ui/

Existing Components:

  • ✅ sdis-enrollment.js - Enrollment wizard (needs testing)
  • ⏳ Identity viewer component - Needs deployment testing
  • ⏳ Anchor manager UI - Needs deployment testing
  • ⏳ Steward dashboard - In development

What's Needed:

  • Test enrollment flow end-to-end
  • Add QR code display in UI
  • Implement recovery code display
  • Add device management interface

2. Mobile App Integration

Location: sdk/react-native/examples/CoopWallet/

Status:

  • ⏳ QR scanning for enrollment
  • ⏳ Ephemeral DID generation
  • ⏳ Device verification flow
  • ⏳ Anchor management screens

Blocked On:

  • Need to test mobile-gateway communication
  • Need to implement secure key storage on device

3. Steward System

What Exists:

  • ✅ Backend API for steward vouching (verify/level2)
  • ✅ Trust graph integration
  • ⏳ Steward role assignment (manual via CLI)
  • ⏳ Steward dashboard UI
  • ⏳ Vouching workflow UI

What's Needed:

  • Steward invitation/promotion flow
  • Steward dashboard with pending enrollments
  • Notification system for vouching requests
  • Audit log of steward actions

📋 Next Steps (Priority Order)

Phase 1: Basic Enrollment Flow (IMMEDIATE)

  1. Test SDIS API end-to-end:

    # Test enrollment
curl -X POST http://10.8.30.40:30080/v1/sdis/enrollment/start \
  -H "Content-Type: application/json" \
  -d '{"identity_name":"TestUser","coop_id":"test-coop"}'

  2. Verify Pilot UI enrollment wizard:

    • Access Pilot UI at http://10.8.30.40:30030
    • Test enrollment flow
    • Verify QR code generation
    • Test verification levels

  3. Create test steward:

    # On K3s cluster
POD=$(kubectl get pods -n icn -l component=daemon -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it -n icn $POD -- icnctl id show
# Use this DID as steward for testing

Phase 2: Steward Dashboard (NEXT SPRINT)

  1. Build steward UI components:

    • Pending enrollments list
    • Vouch action buttons
    • Vouch statement input
    • Audit log viewer

  2. Add notifications:

    • WebSocket events for new enrollments
    • Browser notifications for stewards
    • Email notifications (optional)

  3. Steward management:

    • Promote member to steward
    • Revoke steward status
    • View steward activity

Phase 3: Mobile Integration (NEXT SPRINT)

  1. QR Code Scanning:

    • Implement camera permissions
    • Parse enrollment QR codes
    • Extract challenge data

  2. Device Verification:

    • Generate ephemeral DID on device
    • Sign challenge with ephemeral key
    • Submit verification proof

  3. Anchor Management:

    • List user's anchor devices
    • Add/remove anchors
    • Promote primary anchor

Phase 4: Recovery & Advanced Features (FUTURE)

  1. Recovery Flow:

    • Recovery code input UI
    • Challenge-response flow
    • New device binding

  2. Multi-Device Sync:

    • Identity state synchronization
    • Conflict resolution
    • Anchor consensus

  3. Advanced Verification:

    • Level 3: Multi-steward vouching
    • Biometric commitment (future)
    • Government ID verification (future)

🧪 Testing Guide

Manual API Testing

# 1. Health check
curl http://10.8.30.40:30080/v1/sdis/health

# 2. Start enrollment
ENROLLMENT=$(curl -X POST http://10.8.30.40:30080/v1/sdis/enrollment/start \
  -H "Content-Type: application/json" \
  -d '{"identity_name":"Alice","coop_id":"test-coop"}' \
  | jq -r '.enrollment_id')

echo "Enrollment ID: $ENROLLMENT"

# 3. Generate ephemeral DID
EPHEMERAL=$(curl -X POST http://10.8.30.40:30080/v1/sdis/ephemeral/generate \
  -H "Content-Type: application/json" \
  -d '{"purpose":"enrollment","ttl_seconds":3600}' \
  | jq -r '.ephemeral_did')

echo "Ephemeral DID: $EPHEMERAL"

# 4. Get steward token (requires existing identity)
POD=$(kubectl get pods -n icn -l component=daemon -o jsonpath='{.items[0].metadata.name}')
TOKEN=$(kubectl exec -it -n icn $POD -- icnctl auth token \
  --coop-id test-coop \
  --gateway http://localhost:8080)

# 5. Steward vouches for enrollment
curl -X POST http://10.8.30.40:30080/v1/sdis/verify/level2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{\"enrollment_id\":\"$ENROLLMENT\",\"vouch_statement\":\"I vouch for Alice\"}"

UI Testing

  1. Access Pilot UI:

    http://10.8.30.40:30030

  2. Test enrollment flow:

    • Click "New Enrollment" button
    • Fill in identity name
    • View generated QR code
    • Verify QR contains enrollment data

  3. Test anchor management:

    • Login with existing DID
    • Navigate to "Devices" tab
    • View anchor devices
    • Test add/remove/promote actions

📊 Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        User Devices                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Mobile App   │  │  Web UI      │  │  Desktop App │     │
│  │ (CoopWallet) │  │ (Pilot UI)   │  │  (Future)    │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         │                 │                 │              │
│         └─────────────────┼─────────────────┘              │
│                           │                                │
└───────────────────────────┼────────────────────────────────┘
                            │
                            │ HTTP/WS
                            │
┌───────────────────────────▼────────────────────────────────┐
│                    Gateway API Layer                       │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌──────────────────────────────────────────────────────┐ │
│  │           SDIS API Endpoints (/v1/sdis/)             │ │
│  ├──────────────────────────────────────────────────────┤ │
│  │  • Enrollment (start, complete)                      │ │
│  │  • Verification (level1, level2, level3)             │ │
│  │  • Anchor Management (list, add, remove, promote)    │ │
│  │  • Recovery (initiate, complete)                     │ │
│  │  • Ephemeral DIDs (generate)                         │ │
│  └──────────────────────────────────────────────────────┘ │
│                                                            │
└───────────────────────────┬────────────────────────────────┘
                            │
                            │
┌───────────────────────────▼────────────────────────────────┐
│                   Core Actor System                        │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌────────────────┐  ┌────────────────┐  ┌─────────────┐ │
│  │  Identity      │  │  Trust Graph   │  │  Ledger     │ │
│  │  Manager       │  │  Engine        │  │  Actor      │ │
│  │                │  │                │  │             │ │
│  │  • V4 Keystore │  │  • Trust Scores│  │  • Credits  │ │
│  │  • Multi-device│  │  • Vouching    │  │  • History  │ │
│  │  • Anchors     │  │  • Transitive  │  │             │ │
│  └────────────────┘  └────────────────┘  └─────────────┘ │
│                                                            │
│  ┌────────────────┐  ┌────────────────┐                   │
│  │  Gossip        │  │  Storage       │                   │
│  │  Protocol      │  │  (Sled)        │                   │
│  │                │  │                │                   │
│  │  • P2P Sync    │  │  • Persistence │                   │
│  │  • Events      │  │  • Replication │                   │
│  └────────────────┘  └────────────────┘                   │
│                                                            │
└────────────────────────────────────────────────────────────┘

Enrollment Flow:
1. User → Start enrollment (QR generated)
2. Device → Scan QR, generate ephemeral DID
3. Device → Level 1 verification (device proof)
4. Steward → Level 2 verification (vouch)
5. User → Complete enrollment (receive DID + recovery codes)
6. Identity → Stored in keystore, synced via gossip

🔐 Security Considerations

Current Implementation

✅ Cryptography:

  • Ed25519 for signing
  • X25519-ChaCha20-Poly1305 for encryption
  • Age-encrypted keystores

✅ Authentication:

  • Bearer token authentication
  • Token expiry tracking
  • Per-request authorization

✅ Verification Levels:

  • Level 0: Unverified (enrollment started)
  • Level 1: Device verified (QR scanned)
  • Level 2: Steward vouched (trusted member)
  • Level 3: Multi-steward (future)

TODO: Security Hardening

⏳ Rate Limiting:

  • Enrollment attempts per IP
  • Verification attempts per enrollment
  • Recovery attempts per identity

⏳ Audit Logging:

  • All steward vouching actions
  • Recovery attempts
  • Anchor device changes

⏳ Expiry Management:

  • Enrollment expiry (24 hours default)
  • Ephemeral DID expiry (1 hour default)
  • Recovery code rotation

📁 Key Files & Locations

Backend (Rust)

icn/crates/
├── icn-gateway/src/api/sdis/    # SDIS API endpoints
│   ├── enrollment.rs             # Enrollment handlers
│   ├── verify.rs                 # Verification logic
│   ├── anchor.rs                 # Anchor management
│   ├── recovery.rs               # Recovery handlers
│   ├── ephemeral.rs              # Ephemeral DIDs
│   └── qr.rs                     # QR generation
│
├── icn-identity/                 # Identity system
│   ├── keystore.rs               # Age-encrypted keystore
│   ├── anchor.rs                 # Anchor devices
│   └── recovery.rs               # Recovery codes
│
└── icn-trust/                    # Trust graph
    ├── sybil.rs                  # Sybil detection & vouching
    └── computation.rs            # Trust computation

Frontend (JavaScript)

web/pilot-ui/
├── sdis-enrollment.js            # Enrollment wizard
├── identity-viewer.js            # Identity display (WIP)
├── anchor-manager.js             # Device management (WIP)
└── steward-dashboard.js          # Steward UI (TODO)

Documentation

docs/
├── SDIS_API_GUIDE.md            # API documentation
├── SDIS_STEWARD_ROADMAP.md      # Architecture & roadmap
└── sdis-architecture.md         # Technical design

🎯 Success Criteria

Minimum Viable SDIS (CURRENT TARGET)

  • SDIS API deployed and accessible
  • Enrollment endpoints functional
  • Verification levels implemented
  • Anchor device management working
  • End-to-end enrollment test passing
  • Steward can vouch for new users
  • UI shows enrollment QR code
  • Recovery flow tested

Full SDIS v1.0 (NEXT MILESTONE)

  • Mobile app enrollment working
  • Steward dashboard deployed
  • Multi-device sync operational
  • Recovery flow fully tested
  • Audit logging implemented
  • Rate limiting active
  • Production security hardening complete

🐛 Known Issues

  1. Port 30080 NodePort: Sometimes conflicts on deployment

    • Workaround: Delete old service before redeploying

  2. Token expiry: No automatic refresh mechanism yet

    • Workaround: Manual re-authentication required

  3. QR code display: May not render in all browsers

    • Workaround: Use modern browser (Chrome/Firefox)

  4. Mobile app: Not yet connected to gateway

    • Status: In development

📞 How to Get Help

API not responding?

# Check pod status
kubectl get pods -n icn

# Check logs
POD=$(kubectl get pods -n icn -l component=daemon -o jsonpath='{.items[0].metadata.name}')
kubectl logs -n icn $POD | grep sdis

Enrollment failing?

  • Verify gateway URL is correct
  • Check SDIS health endpoint
  • Review API response for error details
  • Check if coop-id exists

Need steward token?

# Get token from pod
POD=$(kubectl get pods -n icn -l component=daemon -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it -n icn $POD -- icnctl auth token \
  --coop-id test-coop \
  --gateway http://localhost:8080

📚 References

Last Updated: 2025-12-12
Next Review: After Phase 1 completion

← Back to Docs