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
@@ -1,489 +0,0 @@
|
||||
# Microsoft Entra VerifiedID Integration
|
||||
|
||||
This document describes the integration with Microsoft Entra VerifiedID for verifiable credential issuance and verification.
|
||||
|
||||
## Overview
|
||||
|
||||
The Order integrates with Microsoft Entra VerifiedID to:
|
||||
- Issue verifiable credentials through Microsoft's managed service
|
||||
- Verify verifiable credentials issued by Microsoft Entra VerifiedID
|
||||
- Bridge eIDAS verification with Microsoft Entra VerifiedID credential issuance
|
||||
- Integrate with Azure Logic Apps for workflow orchestration
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐
|
||||
│ Client │────▶│ Identity │────▶│ Entra VerifiedID │
|
||||
│ │ │ Service │ │ API │
|
||||
└─────────────┘ └──────────────┘ └─────────────────────┘
|
||||
│
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ eIDAS Bridge │
|
||||
│ │
|
||||
│ 1. Verify │
|
||||
│ 2. Issue VC │
|
||||
└──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Logic Apps │
|
||||
│ (Optional) │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Microsoft Entra VerifiedID Configuration
|
||||
|
||||
1. **Create Azure AD App Registration**
|
||||
- Go to Azure Portal → Azure Active Directory → App registrations
|
||||
- Create a new registration
|
||||
- Note the **Application (client) ID** and **Directory (tenant) ID**
|
||||
|
||||
2. **Configure API Permissions**
|
||||
- Add permission: `Verifiable Credentials Service - VerifiableCredential.Create.All`
|
||||
- Add permission: `Verifiable Credentials Service - VerifiableCredential.Verify.All`
|
||||
- Grant admin consent
|
||||
|
||||
3. **Create Client Secret**
|
||||
- Go to Certificates & secrets
|
||||
- Create a new client secret
|
||||
- Note the secret value (it's only shown once)
|
||||
|
||||
4. **Create Credential Manifest**
|
||||
- Go to Azure Portal → Verified ID
|
||||
- Create a new credential manifest
|
||||
- Note the **Manifest ID**
|
||||
|
||||
### 2. Environment Variables
|
||||
|
||||
Add the following to your `.env` file:
|
||||
|
||||
```bash
|
||||
# Microsoft Entra VerifiedID
|
||||
ENTRA_TENANT_ID=your-tenant-id
|
||||
ENTRA_CLIENT_ID=your-client-id
|
||||
ENTRA_CLIENT_SECRET=your-client-secret
|
||||
ENTRA_CREDENTIAL_MANIFEST_ID=your-manifest-id
|
||||
|
||||
# eIDAS (for bridge functionality)
|
||||
EIDAS_PROVIDER_URL=https://your-eidas-provider.com
|
||||
EIDAS_API_KEY=your-eidas-api-key
|
||||
|
||||
# Azure Logic Apps (optional)
|
||||
AZURE_LOGIC_APPS_WORKFLOW_URL=https://your-logic-app.azurewebsites.net
|
||||
AZURE_LOGIC_APPS_ACCESS_KEY=your-access-key
|
||||
AZURE_LOGIC_APPS_MANAGED_IDENTITY_CLIENT_ID=your-managed-identity-client-id
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Issue Credential via Entra VerifiedID
|
||||
|
||||
**POST** `/vc/issue/entra`
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"claims": {
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"role": "member"
|
||||
},
|
||||
"pin": "1234",
|
||||
"callbackUrl": "https://your-app.com/callback"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"requestId": "abc123",
|
||||
"url": "https://verifiedid.did.msidentity.com/...",
|
||||
"qrCode": "data:image/png;base64,...",
|
||||
"expiry": 3600
|
||||
}
|
||||
```
|
||||
|
||||
### Verify Credential via Entra VerifiedID
|
||||
|
||||
**POST** `/vc/verify/entra`
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"credential": {
|
||||
"id": "vc:123",
|
||||
"type": ["VerifiableCredential", "IdentityCredential"],
|
||||
"issuer": "did:web:...",
|
||||
"credentialSubject": { ... },
|
||||
"proof": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"verified": true
|
||||
}
|
||||
```
|
||||
|
||||
### eIDAS Verification with Entra Issuance
|
||||
|
||||
**POST** `/eidas/verify-and-issue`
|
||||
|
||||
This endpoint:
|
||||
1. Verifies the eIDAS signature
|
||||
2. Issues a verifiable credential via Microsoft Entra VerifiedID
|
||||
3. Optionally triggers Azure Logic Apps workflow
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"document": "base64-encoded-document",
|
||||
"userId": "user-123",
|
||||
"userEmail": "user@example.com",
|
||||
"pin": "1234"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"verified": true,
|
||||
"credentialRequest": {
|
||||
"requestId": "abc123",
|
||||
"url": "https://verifiedid.did.msidentity.com/...",
|
||||
"qrCode": "data:image/png;base64,..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### TypeScript Client
|
||||
|
||||
```typescript
|
||||
import { EntraVerifiedIDClient } from '@the-order/auth';
|
||||
|
||||
const client = new EntraVerifiedIDClient({
|
||||
tenantId: process.env.ENTRA_TENANT_ID!,
|
||||
clientId: process.env.ENTRA_CLIENT_ID!,
|
||||
clientSecret: process.env.ENTRA_CLIENT_SECRET!,
|
||||
credentialManifestId: process.env.ENTRA_CREDENTIAL_MANIFEST_ID!,
|
||||
});
|
||||
|
||||
// Issue credential
|
||||
const credential = await client.issueCredential({
|
||||
claims: {
|
||||
email: 'user@example.com',
|
||||
name: 'John Doe',
|
||||
},
|
||||
pin: '1234',
|
||||
});
|
||||
|
||||
// Verify credential
|
||||
const verified = await client.verifyCredential(credential);
|
||||
```
|
||||
|
||||
### eIDAS Bridge
|
||||
|
||||
```typescript
|
||||
import { EIDASToEntraBridge } from '@the-order/auth';
|
||||
|
||||
const bridge = new EIDASToEntraBridge({
|
||||
entraVerifiedID: {
|
||||
tenantId: process.env.ENTRA_TENANT_ID!,
|
||||
clientId: process.env.ENTRA_CLIENT_ID!,
|
||||
clientSecret: process.env.ENTRA_CLIENT_SECRET!,
|
||||
credentialManifestId: process.env.ENTRA_CREDENTIAL_MANIFEST_ID!,
|
||||
},
|
||||
eidas: {
|
||||
providerUrl: process.env.EIDAS_PROVIDER_URL!,
|
||||
apiKey: process.env.EIDAS_API_KEY!,
|
||||
},
|
||||
});
|
||||
|
||||
// Verify eIDAS and issue credential
|
||||
const result = await bridge.verifyAndIssue(
|
||||
document,
|
||||
userId,
|
||||
userEmail,
|
||||
pin
|
||||
);
|
||||
```
|
||||
|
||||
## Azure Logic Apps Integration
|
||||
|
||||
The integration supports optional Azure Logic Apps workflows for:
|
||||
- Document processing
|
||||
- eIDAS verification workflows
|
||||
- VC issuance workflows
|
||||
|
||||
### Logic App Workflow Example
|
||||
|
||||
```json
|
||||
{
|
||||
"definition": {
|
||||
"triggers": {
|
||||
"eidas-verification": {
|
||||
"type": "Request",
|
||||
"inputs": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"documentId": { "type": "string" },
|
||||
"userId": { "type": "string" },
|
||||
"eidasProviderUrl": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"actions": {
|
||||
"process-eidas": {
|
||||
"type": "Http",
|
||||
"inputs": {
|
||||
"method": "POST",
|
||||
"uri": "@{triggerBody()['eidasProviderUrl']}/verify",
|
||||
"body": {
|
||||
"documentId": "@{triggerBody()['documentId']}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Client Secrets**: Store securely in Azure Key Vault or similar
|
||||
2. **Access Tokens**: Automatically cached and refreshed
|
||||
3. **PIN Protection**: Optional PIN for credential issuance
|
||||
4. **Certificate Validation**: Full certificate chain validation for eIDAS
|
||||
5. **Managed Identity**: Use Azure Managed Identity when possible instead of client secrets
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"Failed to get access token"**
|
||||
- Check tenant ID, client ID, and client secret
|
||||
- Verify API permissions are granted
|
||||
- Check that admin consent is provided
|
||||
|
||||
2. **"Credential manifest ID is required"**
|
||||
- Ensure `ENTRA_CREDENTIAL_MANIFEST_ID` is set
|
||||
- Verify the manifest exists in Azure Portal
|
||||
|
||||
3. **"eIDAS verification failed"**
|
||||
- Check eIDAS provider URL and API key
|
||||
- Verify network connectivity to eIDAS provider
|
||||
- Check certificate validity
|
||||
|
||||
## Enhanced Features
|
||||
|
||||
### Retry Logic
|
||||
|
||||
The integration includes automatic retry logic for transient failures:
|
||||
|
||||
- **Configurable retries**: Default 3 retries with exponential backoff
|
||||
- **Retryable errors**: 429 (rate limit), 500, 502, 503, 504
|
||||
- **Backoff strategy**: Exponential backoff with configurable delays
|
||||
|
||||
```typescript
|
||||
import { EnhancedEntraVerifiedIDClient } from '@the-order/auth';
|
||||
|
||||
const client = new EnhancedEntraVerifiedIDClient(config, {
|
||||
maxRetries: 3,
|
||||
initialDelayMs: 1000,
|
||||
maxDelayMs: 10000,
|
||||
backoffMultiplier: 2,
|
||||
});
|
||||
```
|
||||
|
||||
### Multi-Manifest Support
|
||||
|
||||
Support for multiple credential manifests:
|
||||
|
||||
```bash
|
||||
# Environment variable (JSON format)
|
||||
ENTRA_MANIFESTS='{"default":"manifest-id-1","diplomatic":"manifest-id-2","judicial":"manifest-id-3"}'
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Issue credential with specific manifest
|
||||
await client.issueCredential({
|
||||
claims: { ... },
|
||||
manifestName: 'diplomatic', // Uses diplomatic manifest
|
||||
});
|
||||
```
|
||||
|
||||
### Webhook/Callback Handling
|
||||
|
||||
Automatic webhook processing for issuance status updates:
|
||||
|
||||
**POST** `/vc/entra/webhook`
|
||||
|
||||
The webhook endpoint:
|
||||
- Receives status updates from Entra VerifiedID
|
||||
- Updates credential status in database
|
||||
- Publishes events for downstream processing
|
||||
- Records metrics for monitoring
|
||||
|
||||
**GET** `/vc/entra/status/:requestId`
|
||||
|
||||
Manual status check endpoint (polling fallback).
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Entra-specific rate limiting to prevent API quota exhaustion:
|
||||
|
||||
```bash
|
||||
# Environment variables
|
||||
ENTRA_RATE_LIMIT_ISSUANCE=10 # Per minute
|
||||
ENTRA_RATE_LIMIT_VERIFICATION=20 # Per minute
|
||||
ENTRA_RATE_LIMIT_STATUS_CHECK=30 # Per minute
|
||||
ENTRA_RATE_LIMIT_GLOBAL=50 # Per minute
|
||||
```
|
||||
|
||||
Rate limits are applied automatically to all Entra endpoints.
|
||||
|
||||
### Monitoring & Metrics
|
||||
|
||||
Comprehensive Prometheus metrics:
|
||||
|
||||
- `entra_api_requests_total` - Total API requests by operation and status
|
||||
- `entra_api_request_duration_seconds` - Request duration histogram
|
||||
- `entra_credentials_issued_total` - Credentials issued by manifest and status
|
||||
- `entra_issuance_duration_seconds` - Issuance duration histogram
|
||||
- `entra_credentials_verified_total` - Verification results
|
||||
- `entra_webhooks_received_total` - Webhook events received
|
||||
- `entra_active_requests` - Currently active requests gauge
|
||||
|
||||
Access metrics at `/metrics` endpoint.
|
||||
|
||||
### Automated Setup Script
|
||||
|
||||
Use the automated setup script for Azure configuration:
|
||||
|
||||
```bash
|
||||
./scripts/deploy/setup-entra-automated.sh
|
||||
```
|
||||
|
||||
The script:
|
||||
- Creates Azure AD App Registration
|
||||
- Configures API permissions
|
||||
- Creates client secrets
|
||||
- Stores secrets in Azure Key Vault
|
||||
- Generates environment file template
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```bash
|
||||
cd packages/auth
|
||||
pnpm test entra-verifiedid.test.ts
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
Integration tests verify:
|
||||
- Token management and caching
|
||||
- Credential issuance flow
|
||||
- Retry logic on failures
|
||||
- Multi-manifest support
|
||||
- Webhook processing
|
||||
|
||||
### End-to-End Testing
|
||||
|
||||
1. Set up test environment variables
|
||||
2. Create test credential manifest in Azure
|
||||
3. Run E2E test suite:
|
||||
```bash
|
||||
pnpm test:e2e entra
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Automated Deployment
|
||||
|
||||
1. Run setup script:
|
||||
```bash
|
||||
./scripts/deploy/setup-entra-automated.sh
|
||||
```
|
||||
|
||||
2. Update environment variables in all environments
|
||||
|
||||
3. Configure webhook URLs in Entra VerifiedID:
|
||||
- Production: `https://api.theorder.org/vc/entra/webhook`
|
||||
- Staging: `https://api-staging.theorder.org/vc/entra/webhook`
|
||||
|
||||
4. Verify integration:
|
||||
```bash
|
||||
curl -X POST https://api.theorder.org/vc/issue/entra \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"claims": {"email": "test@example.com"}}'
|
||||
```
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
Follow the manual steps in `docs/deployment/DEPLOYMENT_STEPS_SUMMARY.md` Phase 3.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Enhanced Client**: Always use `EnhancedEntraVerifiedIDClient` for production
|
||||
2. **Monitor Metrics**: Set up alerts on error rates and latency
|
||||
3. **Configure Rate Limits**: Adjust based on your Entra API quota
|
||||
4. **Webhook Security**: Validate webhook signatures if Entra provides them
|
||||
5. **Multi-Manifest**: Use manifest names for different credential types
|
||||
6. **Error Handling**: Implement proper error handling and logging
|
||||
7. **Retry Configuration**: Tune retry settings based on your needs
|
||||
|
||||
## Credential Images
|
||||
|
||||
### Image Format Support
|
||||
|
||||
**Yes, SVG files can be used!** The integration includes automatic SVG-to-PNG conversion for Entra VerifiedID compatibility.
|
||||
|
||||
#### Officially Supported Formats
|
||||
- **PNG** (Recommended) ✅
|
||||
- **JPG/JPEG** ✅
|
||||
- **BMP** ✅
|
||||
- **SVG** (with automatic conversion) ✅
|
||||
|
||||
#### Using SVG Files
|
||||
|
||||
1. **Automatic Conversion** (Recommended):
|
||||
```typescript
|
||||
import { prepareCredentialImage } from '@the-order/auth';
|
||||
|
||||
const image = await prepareCredentialImage(svgData, 'svg');
|
||||
// Automatically converts to PNG
|
||||
```
|
||||
|
||||
2. **Manual Conversion**:
|
||||
```bash
|
||||
./scripts/tools/convert-svg-to-png.sh logo.svg logo.png 200 200
|
||||
```
|
||||
|
||||
3. **Prepare All Images**:
|
||||
```bash
|
||||
./scripts/tools/prepare-credential-images.sh
|
||||
```
|
||||
|
||||
See [ENTRA_CREDENTIAL_IMAGES.md](./ENTRA_CREDENTIAL_IMAGES.md) for detailed image guide.
|
||||
|
||||
## References
|
||||
|
||||
- [Microsoft Entra VerifiedID Documentation](https://learn.microsoft.com/en-us/azure/active-directory/verifiable-credentials/)
|
||||
- [Azure Logic Apps Documentation](https://learn.microsoft.com/en-us/azure/logic-apps/)
|
||||
- [eIDAS Regulation](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32014R0910)
|
||||
- [Entra VerifiedID Display Definitions](https://learn.microsoft.com/en-us/entra/verified-id/rules-and-display-definitions-model)
|
||||
|
||||
@@ -1,53 +1,53 @@
|
||||
# Integrations Documentation
|
||||
# Integration Documentation
|
||||
|
||||
This directory contains documentation for all external system integrations, APIs, and technical specifications.
|
||||
**Last Updated**: 2025-01-27
|
||||
**Purpose**: Integration guide index
|
||||
|
||||
## Integration Guides
|
||||
## Overview
|
||||
|
||||
### Identity & Credential Systems
|
||||
- **[MICROSOFT_ENTRA_VERIFIEDID.md](./MICROSOFT_ENTRA_VERIFIEDID.md)** - Microsoft Entra VerifiedID integration guide
|
||||
- **[EU_LAISSEZ_PASSER_SPECIFICATION.md](./EU_LAISSEZ_PASSER_SPECIFICATION.md)** - EU Laissez-Passer technical specification
|
||||
This directory contains documentation for all external integrations used by The Order platform.
|
||||
|
||||
### Workflow & Automation
|
||||
- **[INTEGRATION_SUMMARY.md](./INTEGRATION_SUMMARY.md)** - Overview of all integrations
|
||||
- **[CONNECTOR_STATUS.md](./CONNECTOR_STATUS.md)** - Connector status and availability
|
||||
## Available Integrations
|
||||
|
||||
## Integration Categories
|
||||
### Microsoft Entra VerifiedID
|
||||
- [Entra VerifiedID Guide](entra-verifiedid/README.md) - Complete integration guide
|
||||
- Credential issuance and verification
|
||||
- Multi-manifest support
|
||||
- Webhook handling
|
||||
- Rate limiting and metrics
|
||||
|
||||
### ✅ Fully Integrated
|
||||
- Microsoft Entra VerifiedID
|
||||
- Azure Logic Apps
|
||||
- eIDAS Verification
|
||||
- Stripe Payment Gateway
|
||||
- AWS S3 Storage
|
||||
- AWS KMS
|
||||
### Azure Services
|
||||
- [Azure CDN](../deployment/azure/cdn-setup.md) - CDN configuration
|
||||
- [Azure Key Vault](../../infra/terraform/key-vault.tf) - Secrets management
|
||||
- [Azure Storage](../deployment/azure/cdn-setup.md) - Object storage
|
||||
|
||||
### 📋 Documented (Pending Implementation)
|
||||
- EU Laissez-Passer (EU-LP)
|
||||
- ISO 20022 Payment Messages
|
||||
- SWIFT Integration
|
||||
- Additional payment networks
|
||||
### Payment Gateways
|
||||
- Stripe integration (see `services/finance/`)
|
||||
- Additional providers (planned)
|
||||
|
||||
### 🔄 In Progress
|
||||
- Temporal Workflow Engine
|
||||
- AWS Step Functions
|
||||
- Additional compliance systems
|
||||
### E-Signature Providers
|
||||
- DocuSign (planned)
|
||||
- Adobe Sign (planned)
|
||||
|
||||
## Quick Reference
|
||||
### Court E-Filing
|
||||
- Federal court systems (planned)
|
||||
- State court systems (planned)
|
||||
|
||||
### For Developers
|
||||
- See [INTEGRATION_SUMMARY.md](./INTEGRATION_SUMMARY.md) for complete integration status
|
||||
- See [CONNECTOR_STATUS.md](./CONNECTOR_STATUS.md) for connector availability
|
||||
- Check individual integration guides for implementation details
|
||||
## Integration Documentation Structure
|
||||
|
||||
### For Compliance
|
||||
- All integrations comply with relevant standards (ICAO, ISO, etc.)
|
||||
- Security and audit requirements documented in each guide
|
||||
- Certificate management and validation procedures included
|
||||
```
|
||||
integrations/
|
||||
├── README.md # This file
|
||||
└── entra-verifiedid/ # Entra VerifiedID integration
|
||||
└── README.md # Complete guide
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
## Quick Links
|
||||
|
||||
- **[Configuration](../configuration/)** - Environment variables and configuration
|
||||
- **[Governance](../governance/)** - Governance and compliance frameworks
|
||||
- **[Legal](../legal/)** - Legal policies and compliance documents
|
||||
- [Entra VerifiedID](entra-verifiedid/README.md) - Credential issuance
|
||||
- [Azure Deployment](../deployment/azure/) - Azure service integration
|
||||
- [Service Documentation](../../services/) - Service-specific integrations
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
50
docs/integrations/entra-verifiedid/README.md
Normal file
50
docs/integrations/entra-verifiedid/README.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Entra VerifiedID Integration
|
||||
|
||||
Complete integration guide for Microsoft Entra VerifiedID credential issuance and verification.
|
||||
|
||||
## Overview
|
||||
|
||||
The Order integrates with Microsoft Entra VerifiedID for issuing and verifying verifiable credentials. This integration supports multiple credential types, custom display properties, and webhook-based event handling.
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Setup Guide](../../deployment/azure/entra-verifiedid.md)** - Deployment and configuration
|
||||
- **[Credential Images](credential-images.md)** - Image requirements and setup
|
||||
- **[Best Practices](best-practices.md)** - Implementation best practices
|
||||
- **[JSON Content Readiness](json-content-readiness.md)** - Content format requirements
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Enable Entra VerifiedID** in Azure Portal
|
||||
2. **Create Application Registration** with required permissions
|
||||
3. **Configure Credential Manifests** for each credential type
|
||||
4. **Set Environment Variables** (see deployment guide)
|
||||
5. **Deploy Services** with Entra integration
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Multi-manifest support
|
||||
- ✅ Custom credential display (logo, colors)
|
||||
- ✅ Webhook event handling
|
||||
- ✅ Retry logic with exponential backoff
|
||||
- ✅ Rate limiting
|
||||
- ✅ Prometheus metrics
|
||||
- ✅ Comprehensive error handling
|
||||
|
||||
## Credential Types
|
||||
|
||||
- **Default/Identity**: Basic member credentials
|
||||
- **Financial**: Digital Bank credentials
|
||||
- **Judicial**: ICCC credentials
|
||||
- **Diplomatic**: Diplomatic Security credentials
|
||||
- **Legal Office**: Legal Office credentials
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Deployment Guide](../../deployment/azure/entra-verifiedid.md)
|
||||
- [Operations Runbook](../../operations/ENTRA_VERIFIEDID_RUNBOOK.md)
|
||||
- [Training Materials](../../training/ENTRA_VERIFIEDID_TRAINING.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
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