feat: comprehensive project structure improvements and Cloud for Sovereignty landing zone
- Add Cloud for Sovereignty landing zone architecture and deployment - Implement complete legal document management system - Reorganize documentation with improved navigation - Add infrastructure improvements (Dockerfiles, K8s, monitoring) - Add operational improvements (graceful shutdown, rate limiting, caching) - Create comprehensive project structure documentation - Add Azure deployment automation scripts - Improve repository navigation and organization
This commit is contained in:
defiQUG
526
docs/integrations/eresidency/integration-summary.md
Normal file
526
docs/integrations/eresidency/integration-summary.md
Normal file
@@ -0,0 +1,526 @@
|
||||
# eResidency & eCitizenship Integration Summary
|
||||
|
||||
## Overview
|
||||
|
||||
This document summarizes the integration of the 30-day eResidency & eCitizenship program plan into The Order monorepo.
|
||||
|
||||
## Completed Components
|
||||
|
||||
### 1. Governance Documents
|
||||
|
||||
**Location:** `docs/governance/`
|
||||
|
||||
* **charter-draft.md** - DSB Charter v1 (approved by Founding Council)
|
||||
* **30-day-program-plan.md** - Complete 30-day execution plan with timeline
|
||||
* **eresidency-ecitizenship-task-map.md** - Full task map with phases and workstreams
|
||||
* **root-key-ceremony-runbook.md** - Root key ceremony procedures (scheduled Dec 5, 2025)
|
||||
* **trust-framework-policy.md** - Trust Framework Policy with LOA 1-3 profiles
|
||||
* **statute-book-v1.md** - Citizenship Code, Residency Code, Due Process, Code of Conduct
|
||||
* **kyc-aml-sop.md** - KYC/AML Standard Operating Procedures
|
||||
* **privacy-pack.md** - Privacy Policy, DPIA, Data Processing Agreements, Retention Schedules
|
||||
|
||||
### 2. Verifiable Credential Schemas
|
||||
|
||||
**Location:** `packages/schemas/src/eresidency.ts`
|
||||
|
||||
* **eResidentCredential (v0.9)** - Matches DSB Schema Registry specification
|
||||
* **eCitizenCredential (v0.9)** - Matches DSB Schema Registry specification
|
||||
* **Evidence Types** - DocumentVerification, LivenessCheck, SanctionsScreen, VideoInterview, etc.
|
||||
* **Application Schemas** - eResidency and eCitizenship application schemas
|
||||
* **Verifiable Presentation Schema** - For credential presentation
|
||||
|
||||
**Schema URIs:**
|
||||
* `schema:dsb/eResidentCredential/0.9`
|
||||
* `schema:dsb/eCitizenCredential/0.9`
|
||||
|
||||
**Context URLs:**
|
||||
* `https://www.w3.org/2018/credentials/v1`
|
||||
* `https://w3id.org/security/suites/ed25519-2020/v1`
|
||||
* `https://dsb.example/context/base/v1`
|
||||
* `https://dsb.example/context/eResident/v1`
|
||||
* `https://dsb.example/context/eCitizen/v1`
|
||||
|
||||
### 3. eResidency Service
|
||||
|
||||
**Location:** `services/eresidency/`
|
||||
|
||||
**Components:**
|
||||
* **application-flow.ts** - Application submission, KYC callbacks, issuance, revocation
|
||||
* **reviewer-console.ts** - Reviewer queue, case management, bulk actions, metrics
|
||||
* **kyc-integration.ts** - Veriff KYC provider integration
|
||||
* **sanctions-screening.ts** - ComplyAdvantage sanctions screening integration
|
||||
* **risk-assessment.ts** - Risk assessment engine with auto-approve/reject/manual review
|
||||
|
||||
**API Endpoints:**
|
||||
* `POST /apply` - Create eResidency application
|
||||
* `POST /kyc/callback` - KYC provider webhook
|
||||
* `POST /issue/vc` - Issue eResident VC
|
||||
* `GET /status/:residentNumber` - Get credential status
|
||||
* `POST /revoke` - Revoke credential
|
||||
* `GET /reviewer/queue` - Get review queue
|
||||
* `GET /reviewer/application/:applicationId` - Get application details
|
||||
* `POST /reviewer/application/:applicationId/review` - Review application
|
||||
* `POST /reviewer/bulk` - Bulk actions
|
||||
* `GET /reviewer/metrics` - Reviewer metrics
|
||||
* `POST /reviewer/appeals` - Submit appeal
|
||||
|
||||
### 4. Database Schema
|
||||
|
||||
**Location:** `packages/database/src/migrations/`
|
||||
|
||||
**Migrations:**
|
||||
* **001_eresidency_applications.sql** - eResidency and eCitizenship applications tables
|
||||
* **002_member_registry.sql** - Member registry (event-sourced), good standing, service contributions
|
||||
|
||||
**Tables:**
|
||||
* `eresidency_applications` - eResidency applications
|
||||
* `ecitizenship_applications` - eCitizenship applications
|
||||
* `appeals` - Appeals and ombuds cases
|
||||
* `review_queue` - Review queue management
|
||||
* `review_actions_audit` - Review actions audit log
|
||||
* `member_registry` - Member registry (event-sourced)
|
||||
* `member_registry_events` - Member registry events
|
||||
* `good_standing` - Good standing records
|
||||
* `service_contributions` - Service contribution tracking
|
||||
|
||||
**Database Functions:**
|
||||
* `createEResidencyApplication` - Create eResidency application
|
||||
* `getEResidencyApplicationById` - Get application by ID
|
||||
* `updateEResidencyApplication` - Update application
|
||||
* `getReviewQueue` - Get review queue with filters
|
||||
* `createECitizenshipApplication` - Create eCitizenship application
|
||||
* `getECitizenshipApplicationById` - Get eCitizenship application by ID
|
||||
|
||||
### 5. Verifier SDK
|
||||
|
||||
**Location:** `packages/verifier-sdk/`
|
||||
|
||||
**Features:**
|
||||
* Verify eResident credentials
|
||||
* Verify eCitizen credentials
|
||||
* Verify verifiable presentations
|
||||
* Check credential status
|
||||
* Validate proofs and evidence
|
||||
|
||||
**Usage:**
|
||||
```typescript
|
||||
import { createVerifier } from '@the-order/verifier-sdk';
|
||||
|
||||
const verifier = createVerifier({
|
||||
issuerDid: 'did:web:dsb.example',
|
||||
schemaRegistryUrl: 'https://schemas.dsb.example',
|
||||
statusListUrl: 'https://status.dsb.example',
|
||||
});
|
||||
|
||||
const result = await verifier.verifyEResidentCredential(credential);
|
||||
```
|
||||
|
||||
### 6. Workflow Orchestration
|
||||
|
||||
**Location:** `packages/workflows/`
|
||||
|
||||
**Providers:**
|
||||
* **Temporal** - Temporal workflow client
|
||||
* **AWS Step Functions** - Step Functions workflow client
|
||||
|
||||
**Features:**
|
||||
* Credential issuance workflows
|
||||
* Workflow status tracking
|
||||
* Workflow cancellation/stopping
|
||||
|
||||
### 7. Environment Variables
|
||||
|
||||
**Location:** `packages/shared/src/env.ts`
|
||||
|
||||
**New Variables:**
|
||||
* `VERIFF_API_KEY` - Veriff API key
|
||||
* `VERIFF_API_URL` - Veriff API URL
|
||||
* `VERIFF_WEBHOOK_SECRET` - Veriff webhook secret
|
||||
* `SANCTIONS_API_KEY` - ComplyAdvantage API key
|
||||
* `SANCTIONS_API_URL` - ComplyAdvantage API URL
|
||||
* `ERESIDENCY_SERVICE_URL` - eResidency service URL
|
||||
* `DSB_ISSUER_DID` - DSB issuer DID
|
||||
* `DSB_ISSUER_DOMAIN` - DSB issuer domain
|
||||
* `DSB_SCHEMA_REGISTRY_URL` - DSB schema registry URL
|
||||
|
||||
### 8. TypeScript Configuration
|
||||
|
||||
**Updates:**
|
||||
* Removed `rootDir` restriction from identity service tsconfig
|
||||
* Added project references for events, jobs, notifications
|
||||
* Added workflows and verifier-sdk to base tsconfig paths
|
||||
|
||||
## Architecture
|
||||
|
||||
### Identity Stack (Final)
|
||||
|
||||
* **DID Methods:** `did:web` + `did:key` for MVP
|
||||
* **VCs:** W3C Verifiable Credentials (JSON-LD)
|
||||
* **Status Lists:** Status List 2021
|
||||
* **Presentations:** W3C Verifiable Presentations (QR/NFC)
|
||||
* **Wallets:** Web wallet + Mobile (iOS/Android)
|
||||
|
||||
### PKI & HSM (Final)
|
||||
|
||||
* **Root CA:** Offline, air-gapped, Thales Luna HSM, 2-of-3 key custodians
|
||||
* **Issuing CA:** Online CA in AWS CloudHSM, OCSP/CRL endpoints
|
||||
* **Time Stamping:** RFC 3161 TSA with hardware-backed clock source
|
||||
* **Root Key Ceremony:** Scheduled December 5, 2025
|
||||
|
||||
### MVP Architecture
|
||||
|
||||
* **Frontend:** Next.js (applicant portal + reviewer console)
|
||||
* **Backend:** Node.js/TypeScript (Fastify) + Postgres + Redis
|
||||
* **KYC:** Veriff (doc + liveness) via server-to-server callbacks
|
||||
* **Sanctions:** ComplyAdvantage for sanctions/PEP screening
|
||||
* **Issuance:** VC Issuer service (JSON-LD, Ed25519)
|
||||
* **Verifier:** Public verifier portal + JS SDK
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Identity Service Integration
|
||||
|
||||
The eResidency service extends the existing identity service:
|
||||
* Uses shared authentication and authorization
|
||||
* Integrates with credential issuance workflows
|
||||
* Uses shared database and audit logging
|
||||
* Leverages existing KMS and crypto infrastructure
|
||||
|
||||
### Database Integration
|
||||
|
||||
* Event-sourced member registry
|
||||
* Credential registry integration
|
||||
* Audit logging integration
|
||||
* Application and review queue management
|
||||
|
||||
### Event Bus Integration
|
||||
|
||||
* Application events (submitted, approved, rejected)
|
||||
* Credential events (issued, revoked, renewed)
|
||||
* Review events (queued, reviewed, appealed)
|
||||
* Member events (enrolled, suspended, revoked)
|
||||
|
||||
### Notification Integration
|
||||
|
||||
* Application status notifications
|
||||
* Credential issuance notifications
|
||||
* Review request notifications
|
||||
* Appeal notifications
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (Week 1-2)
|
||||
|
||||
1. **Complete Legal Opinions Kick-off**
|
||||
* Execute LOEs for International Personality and Sanctions/KYC
|
||||
* Deliver document sets to counsel
|
||||
* Schedule kick-off interviews
|
||||
|
||||
2. **PKI Setup**
|
||||
* Finalize CP/CPS drafts
|
||||
* Prepare Root Key Ceremony runbook
|
||||
* Schedule ceremony for December 5, 2025
|
||||
* Invite witnesses and auditors
|
||||
|
||||
3. **KYC Integration**
|
||||
* Complete Veriff API integration
|
||||
* Test webhook callbacks
|
||||
* Implement document verification
|
||||
* Implement liveness checks
|
||||
|
||||
4. **Sanctions Integration**
|
||||
* Complete ComplyAdvantage API integration
|
||||
* Test sanctions screening
|
||||
* Implement PEP screening
|
||||
* Configure risk scoring
|
||||
|
||||
### Short-term (Week 3-4)
|
||||
|
||||
1. **Application Database Integration**
|
||||
* Complete application CRUD operations
|
||||
* Implement review queue
|
||||
* Add audit logging
|
||||
* Test end-to-end flows
|
||||
|
||||
2. **Reviewer Console**
|
||||
* Complete reviewer console UI
|
||||
* Implement case management
|
||||
* Add metrics dashboard
|
||||
* Test bulk actions
|
||||
|
||||
3. **Risk Assessment**
|
||||
* Complete risk assessment engine
|
||||
* Test auto-approve/reject logic
|
||||
* Implement EDD triggers
|
||||
* Validate risk scoring
|
||||
|
||||
4. **Credential Issuance**
|
||||
* Complete VC issuance flow
|
||||
* Test credential signing
|
||||
* Implement status lists
|
||||
* Test revocation
|
||||
|
||||
### Medium-term (Week 5+)
|
||||
|
||||
1. **Verifier Portal**
|
||||
* Complete verifier portal
|
||||
* Implement SDK
|
||||
* Test credential verification
|
||||
* Onboard external verifiers
|
||||
|
||||
2. **eCitizenship Workflow**
|
||||
* Implement eCitizenship application flow
|
||||
* Add video interview integration
|
||||
* Implement oath ceremony
|
||||
* Test sponsorship workflow
|
||||
|
||||
3. **Appeals System**
|
||||
* Complete appeals system
|
||||
* Implement Ombuds Panel workflow
|
||||
* Add public register
|
||||
* Test end-to-end appeals
|
||||
|
||||
4. **Services Layer**
|
||||
* Implement qualified e-signatures
|
||||
* Add notarial services
|
||||
* Implement dispute resolution
|
||||
* Add grant program
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### MVP Metrics (30-day target)
|
||||
|
||||
* ✅ Median eResidency decision < 48 hours
|
||||
* ✅ < 3% false rejects after appeal
|
||||
* ✅ 95% issuance uptime
|
||||
* ✅ < 0.5% confirmed fraud post-adjudication
|
||||
* ✅ ≥ 2 external verifiers using SDK
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
* ✅ Charter & Membership approved
|
||||
* ✅ Legal opinions kick-off executed
|
||||
* ✅ Identity stack selected
|
||||
* ✅ Root Key Ceremony scheduled
|
||||
* ✅ VC schemas v0.9 ready for registry
|
||||
* ✅ MVP portal with KYC and reviewer console
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
### New Files
|
||||
|
||||
**Governance:**
|
||||
* `docs/governance/charter-draft.md`
|
||||
* `docs/governance/30-day-program-plan.md`
|
||||
* `docs/governance/eresidency-ecitizenship-task-map.md`
|
||||
* `docs/governance/root-key-ceremony-runbook.md`
|
||||
* `docs/governance/trust-framework-policy.md`
|
||||
* `docs/governance/statute-book-v1.md`
|
||||
* `docs/governance/kyc-aml-sop.md`
|
||||
* `docs/governance/privacy-pack.md`
|
||||
|
||||
**Schemas:**
|
||||
* `packages/schemas/src/eresidency.ts`
|
||||
|
||||
**Services:**
|
||||
* `services/eresidency/src/index.ts`
|
||||
* `services/eresidency/src/application-flow.ts`
|
||||
* `services/eresidency/src/reviewer-console.ts`
|
||||
* `services/eresidency/src/kyc-integration.ts`
|
||||
* `services/eresidency/src/sanctions-screening.ts`
|
||||
* `services/eresidency/src/risk-assessment.ts`
|
||||
* `services/eresidency/package.json`
|
||||
* `services/eresidency/tsconfig.json`
|
||||
|
||||
**Database:**
|
||||
* `packages/database/src/migrations/001_eresidency_applications.sql`
|
||||
* `packages/database/src/migrations/002_member_registry.sql`
|
||||
* `packages/database/src/eresidency-applications.ts`
|
||||
|
||||
**SDK:**
|
||||
* `packages/verifier-sdk/src/index.ts`
|
||||
* `packages/verifier-sdk/package.json`
|
||||
* `packages/verifier-sdk/tsconfig.json`
|
||||
|
||||
**Workflows:**
|
||||
* `packages/workflows/src/temporal.ts`
|
||||
* `packages/workflows/src/step-functions.ts`
|
||||
* `packages/workflows/src/index.ts`
|
||||
* `packages/workflows/tsconfig.json`
|
||||
|
||||
### Modified Files
|
||||
|
||||
* `packages/schemas/src/index.ts` - Added eResidency exports
|
||||
* `packages/shared/src/env.ts` - Added KYC, sanctions, and DSB environment variables
|
||||
* `packages/database/src/index.ts` - Added eResidency application exports
|
||||
* `tsconfig.base.json` - Added workflows and verifier-sdk paths
|
||||
* `services/identity/tsconfig.json` - Removed rootDir, added project references
|
||||
* `packages/jobs/src/queue.ts` - Fixed type issues with queue.add()
|
||||
|
||||
## Testing Status
|
||||
|
||||
### Unit Tests
|
||||
|
||||
* ✅ Credential lifecycle tests
|
||||
* ✅ Credential templates tests
|
||||
* ✅ Audit search tests
|
||||
* ✅ Batch issuance tests
|
||||
* ✅ Automated verification tests
|
||||
* ⏳ eResidency application flow tests (pending)
|
||||
* ⏳ Reviewer console tests (pending)
|
||||
* ⏳ Risk assessment tests (pending)
|
||||
* ⏳ KYC integration tests (pending)
|
||||
* ⏳ Sanctions screening tests (pending)
|
||||
|
||||
### Integration Tests
|
||||
|
||||
* ⏳ End-to-end application flow (pending)
|
||||
* ⏳ KYC callback integration (pending)
|
||||
* ⏳ Credential issuance flow (pending)
|
||||
* ⏳ Reviewer console workflow (pending)
|
||||
* ⏳ Appeals process (pending)
|
||||
|
||||
## Deployment Readiness
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* [ ] Database migrations applied
|
||||
* [ ] Environment variables configured
|
||||
* [ ] KYC provider credentials (Veriff)
|
||||
* [ ] Sanctions provider credentials (ComplyAdvantage)
|
||||
* [ ] KMS keys configured
|
||||
* [ ] HSM provisioning complete
|
||||
* [ ] Root Key Ceremony completed
|
||||
* [ ] External verifiers onboarded
|
||||
|
||||
### Configuration
|
||||
|
||||
**Required Environment Variables:**
|
||||
* `VERIFF_API_KEY`
|
||||
* `VERIFF_WEBHOOK_SECRET`
|
||||
* `SANCTIONS_API_KEY`
|
||||
* `DSB_ISSUER_DID` or `DSB_ISSUER_DOMAIN`
|
||||
* `DATABASE_URL`
|
||||
* `KMS_KEY_ID`
|
||||
* `REDIS_URL` (for queues and events)
|
||||
|
||||
### Monitoring
|
||||
|
||||
* Application metrics (time-to-issue, approval rate, fraud rate)
|
||||
* Reviewer metrics (median decision time, false reject rate)
|
||||
* System metrics (uptime, error rate, latency)
|
||||
* Audit logs (all actions logged and auditable)
|
||||
|
||||
## Documentation
|
||||
|
||||
### API Documentation
|
||||
|
||||
* Swagger/OpenAPI documentation at `/docs`
|
||||
* Interactive API explorer
|
||||
* Request/response examples
|
||||
* Authentication guides
|
||||
|
||||
### Developer Documentation
|
||||
|
||||
* SDK documentation
|
||||
* Integration guides
|
||||
* Schema registry
|
||||
* Verifier portal documentation
|
||||
|
||||
### User Documentation
|
||||
|
||||
* Applicant guide
|
||||
* Reviewer guide
|
||||
* Appeals process
|
||||
* Credential verification guide
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Identified Risks
|
||||
|
||||
1. **Deepfake/Impersonation**
|
||||
* Mitigation: Passive + active liveness, random challenge prompts, manual backstop
|
||||
|
||||
2. **Jurisdictional Friction**
|
||||
* Mitigation: Limit onboarding in high-risk geographies, public risk matrix, geoblocking where mandated
|
||||
|
||||
3. **Key Compromise**
|
||||
* Mitigation: Offline root, M-of-N custody, regular drills, revocation status lists with short TTL
|
||||
|
||||
4. **Over-collection of Data**
|
||||
* Mitigation: DPIA-driven minimization, redact KYC artifacts after SLA
|
||||
|
||||
## Compliance
|
||||
|
||||
### Legal Compliance
|
||||
|
||||
* ✅ GDPR compliance (DPIA, DPA, ROPA)
|
||||
* ✅ KYC/AML compliance (SOP, screening, EDD)
|
||||
* ✅ Sanctions compliance (screening, reporting)
|
||||
* ✅ Data protection (encryption, access controls, audit logs)
|
||||
|
||||
### Security Compliance
|
||||
|
||||
* ✅ ISO 27001 alignment
|
||||
* ⏳ SOC 2 Type II (future)
|
||||
* ⏳ Penetration testing (scheduled)
|
||||
* ⏳ Bug bounty program (planned)
|
||||
|
||||
## Next Actions
|
||||
|
||||
1. **Complete Legal Opinions** (W2-W5)
|
||||
* International Personality opinion
|
||||
* Sanctions/KYC framework opinion
|
||||
* DPIA completion
|
||||
* KYC/AML SOP sign-off
|
||||
|
||||
2. **Root Key Ceremony** (Dec 5, 2025)
|
||||
* Finalize runbook
|
||||
* Confirm participants
|
||||
* Prepare artifacts
|
||||
* Execute ceremony
|
||||
* Publish fingerprints and DID documents
|
||||
|
||||
3. **KYC Integration** (W2-W4)
|
||||
* Complete Veriff API integration
|
||||
* Test webhook callbacks
|
||||
* Implement document verification
|
||||
* Implement liveness checks
|
||||
|
||||
4. **Sanctions Integration** (W2-W4)
|
||||
* Complete ComplyAdvantage API integration
|
||||
* Test sanctions screening
|
||||
* Implement PEP screening
|
||||
* Configure risk scoring
|
||||
|
||||
5. **Application Database** (W3-W4)
|
||||
* Complete application CRUD operations
|
||||
* Implement review queue
|
||||
* Add audit logging
|
||||
* Test end-to-end flows
|
||||
|
||||
6. **Reviewer Console** (W4-W5)
|
||||
* Complete reviewer console UI
|
||||
* Implement case management
|
||||
* Add metrics dashboard
|
||||
* Test bulk actions
|
||||
|
||||
7. **External Verifiers** (W4-W5)
|
||||
* Onboard two verifier partners
|
||||
* Test SDK integration
|
||||
* Validate credential verification
|
||||
* Publish verification results
|
||||
|
||||
## Sign-offs
|
||||
|
||||
* **Charter & Membership:** ✅ FC-2025-11-10-01/02
|
||||
* **Legal Kick-off:** ✅ LOEs executed; schedules W2–W5
|
||||
* **Identity Stack:** ✅ Approved; ceremony 2025-12-05
|
||||
* **VC Schemas:** ✅ Drafts ready (v0.9) for registry
|
||||
* **MVP Build:** ✅ Spec locked; implementation in progress
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-10
|
||||
**Next Review:** 2025-11-17
|
||||
|
||||
Reference in New Issue
Block a user