VNF Sandbox Limitations & Real Integration Requirements¶

REC Verifiable Credentialing Platform¶

Executive Summary¶

This document outlines the current limitations of using mock VNF APIs and the specific requirements needed to transition to real Velocity Network Foundation integration for production-ready credential issuance.

Current Mock Implementation Analysis¶

Mock VCL Provider Implementation¶

Location: app/backend/src/shared/services/vnf-sdk.service.ts

// Current Mock Implementation
class MockVCLProvider {
  async generateCredentialOffer(credentialData: any): Promise<any> {
    return {
      id: `offer-${Date.now()}`,
      type: 'CredentialOffer',
      credentialSubject: credentialData,
      issuer: 'did:example:issuer',
      issuanceDate: new Date().toISOString(),
    };
  }

  async issueCredential(offer: any, holderDid: string): Promise<any> {
    return {
      ...offer,
      id: `credential-${Date.now()}`,
      type: 'VerifiableCredential',
      holder: holderDid,
      proof: {
        type: 'JsonWebSignature2020',
        created: new Date().toISOString(),
        proofPurpose: 'assertionMethod',
      },
    };
  }
}

Current Limitations¶

1. No Real Credential Validation¶

Issue: Mock credentials are not validated against VNF schemas
Impact: Cannot verify credential structure compliance
Risk: Production credentials may fail validation

2. Fake Digital Signatures¶

Issue: Mock proof signatures (jws: 'mock-signature-' + Math.random())
Impact: Credentials cannot be cryptographically verified
Risk: Security vulnerabilities in production

3. No Network Registration¶

Issue: Organization DIDs are simulated (did:vnf:${organizationId})
Impact: Organizations not actually registered on Velocity Network
Risk: Credential issuance will fail in production

4. Missing Credential Agent Integration¶

Issue: No real Credential Agent API calls
Impact: Cannot test actual credential delivery mechanisms
Risk: Email/mobile delivery may not work as expected

5. No Status Synchronization¶

Issue: Credential status changes are only local
Impact: Cannot track real credential claim status
Risk: Inaccurate reporting and analytics

Real VNF Integration Requirements¶

1. Production API Access¶

Required Environment Variables:¶

# VNF Core Configuration
VNF_API_KEY=<production-api-key>
VNF_ENVIRONMENT=production  # or sandbox
VNF_X_VNF_PROTOCOL_VERSION=2

# VNF Service Endpoints
VNF_AGENT_OPERATOR_API_URL=https://api.velocitynetwork.foundation/agent-operator
VNF_REGISTRAR_API_URL=https://api.velocitynetwork.foundation/registrar
VNF_CIH_OPERATOR_API_URL=https://api.velocitynetwork.foundation/cih-operator

# Organization Credentials
VNF_ORGANIZATION_DID=<real-organization-did>
VNF_ORGANIZATION_PRIVATE_KEY=<organization-private-key>
VNF_ORGANIZATION_PUBLIC_KEY=<organization-public-key>

API Access Requirements:¶

VNF Developer Account: Active account with Velocity Career Labs
API Key Approval: Production API key with appropriate rate limits
Organization Registration: Completed organization onboarding process
Credential Agent Access: Assigned Credential Agent instance

2. Cryptographic Services¶

Key Management:¶

// Real implementation needed
interface VNFKeyService {
  generateDidJwk(algorithm: string): Promise<DidJwk>;
  getOrganizationKeys(): Promise<KeyPair>;
  signCredential(credential: any, privateKey: string): Promise<string>;
  verifyCredential(credential: any, publicKey: string): Promise<boolean>;
}

Required Certificates:¶

SSL/TLS Certificates: For secure API communication
Organization Certificate: For VNF network authentication
Signing Certificates: For credential digital signatures

3. Real SDK Integration¶

VNF Node.js SDK Installation:¶

npm install @velocitynetwork/vnf-sdk

Required SDK Services:¶

// Replace mock implementation with real SDK
import {
  VCLProvider,
  VCLInitializationDescriptor,
  VCLCredentialManifest,
  VCLCredentialOffer,
  VCLSubmissionResult
} from '@velocitynetwork/vnf-sdk';

4. Network Registration Process¶

Organization Registration Steps:¶

Submit Application: Complete VNF organization registration form
Identity Verification: Provide legal entity documentation
Technical Integration: Complete API integration testing
Compliance Review: Pass security and compliance audit
Production Approval: Receive production API credentials

Required Documentation:¶

Business Registration: Company incorporation documents
Technical Architecture: System integration documentation
Security Assessment: Security controls and procedures
Compliance Certification: GDPR, data protection compliance

Sandbox Environment Requirements¶

VNF Sandbox Access¶

Sandbox API Endpoint: https://sandbox.velocitynetwork.foundation
Test Organization DID: Sandbox-specific organization identifier
Test Credentials: Sample credential types for testing
Rate Limits: Sandbox-appropriate API rate limits

Sandbox Limitations¶

Test Data Only: Cannot issue production credentials
Limited Credential Types: May not support all credential schemas
Network Isolation: Separate from production VNF network
Data Retention: Test data may be periodically purged

Implementation Transition Plan¶

Phase 1: Sandbox Integration (Weeks 1-2)¶

Week 1: Setup & Configuration¶

Obtain VNF sandbox API credentials
Configure sandbox environment variables
Install real VNF Node.js SDK
Update service configuration

Week 2: Basic Integration¶

Replace mock credential generation with sandbox APIs
Implement real organization registration
Test credential issuance flow
Validate credential structure compliance

Phase 2: Production Preparation (Weeks 3-4)¶

Week 3: Security Implementation¶

Implement proper key management
Add digital signature verification
Enhance error handling for API failures
Add comprehensive logging

Week 4: Testing & Validation¶

End-to-end testing with sandbox
Performance testing with real API calls
Security testing and vulnerability assessment
Documentation updates

Phase 3: Production Deployment (Weeks 5-6)¶

Week 5: Production Setup¶

Obtain production API credentials
Complete organization registration process
Configure production environment
Deploy to staging environment

Week 6: Go-Live¶

Production deployment
Monitor system performance
Validate credential issuance
User acceptance testing

Technical Implementation Changes¶

1. Service Layer Updates¶

VNF SDK Service Replacement:¶

// Replace MockVCLProvider with real implementation
@Injectable()
export class VnfSdkService implements OnModuleInit {
  private vclProvider: VCLProvider;

  async onModuleInit() {
    const initDescriptor: VCLInitializationDescriptor = {
      environment: this.configService.get('VNF_ENVIRONMENT'),
      apiKey: this.configService.get('VNF_API_KEY'),
      xVnfProtocolVersion: this.configService.get('VNF_X_VNF_PROTOCOL_VERSION'),
    };

    this.vclProvider = new VCLProvider();
    await this.vclProvider.initialize(initDescriptor);
  }
}

2. Credential Generation Updates¶

Real Credential Issuance:¶

async generateCredentialOffer(credentialData: any): Promise<VCLCredentialOffer> {
  const manifest = await this.getCredentialManifest();
  const submission = await this.createSubmission(credentialData, manifest);
  return await this.vclProvider.submitCredentialApplication(submission);
}

3. Error Handling Enhancement¶

API Error Management:¶

// Handle real API errors
try {
  const credential = await this.vclProvider.issueCredential(offer);
  return credential;
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Implement retry with exponential backoff
    return await this.retryWithBackoff(() => this.vclProvider.issueCredential(offer));
  } else if (error.code === 'INVALID_CREDENTIAL_DATA') {
    // Handle validation errors
    throw new BadRequestException('Credential data validation failed');
  }
  // Handle other API errors
  throw new InternalServerErrorException('VNF API error');
}

Testing Strategy¶

1. Unit Testing¶

Mock API Responses: Test service logic with mocked VNF responses
Error Scenarios: Test handling of various API error conditions
Data Validation: Test credential data validation logic

2. Integration Testing¶

Sandbox Testing: End-to-end testing with VNF sandbox
API Contract Testing: Validate API request/response formats
Performance Testing: Test system performance with real API calls

3. Security Testing¶

Credential Verification: Test digital signature validation
Key Management: Test secure key storage and usage
API Security: Test authentication and authorization

Monitoring & Observability¶

1. API Monitoring¶

Response Times: Monitor VNF API response times
Error Rates: Track API error rates and types
Rate Limiting: Monitor API usage against rate limits

2. Credential Tracking¶

Issuance Success Rate: Track successful credential issuance
Claim Status: Monitor credential claim rates
Verification Results: Track credential verification success

3. System Health¶

Service Availability: Monitor VNF service availability
Network Connectivity: Track network connectivity to VNF APIs
Certificate Expiry: Monitor SSL certificate expiration

Cost Implications¶

VNF API Usage Costs¶

Credential Issuance: Cost per credential issued
Verification Requests: Cost per credential verification
API Calls: Rate-based pricing for API usage
Storage: Cost for credential storage on VNF network

Infrastructure Costs¶

SSL Certificates: Annual certificate renewal costs
Key Management: Secure key storage infrastructure
Monitoring Tools: API monitoring and alerting services
Compliance: Security audit and compliance certification costs

Risk Mitigation¶

1. API Dependency Risks¶

Fallback Mechanisms: Implement graceful degradation for API failures
Retry Logic: Exponential backoff for transient failures
Circuit Breakers: Prevent cascade failures from API issues

2. Security Risks¶

Key Compromise: Implement key rotation procedures
API Key Exposure: Secure storage and rotation of API keys
Certificate Management: Automated certificate renewal

3. Performance Risks¶

Rate Limiting: Implement request queuing and throttling
Caching: Cache frequently accessed data to reduce API calls
Load Balancing: Distribute API calls across multiple instances

Success Criteria¶

Technical Success Metrics¶

99.9% credential issuance success rate
<2 second average API response time
Zero security vulnerabilities in credential handling
100% credential verification accuracy

Business Success Metrics¶

Successful integration with VNF production environment
Compliance with all VNF network requirements
Positive feedback from initial user testing
Readiness for production credential issuance

Next Steps¶

Immediate Actions (This Week)¶

Contact VCL: Request sandbox API access and documentation
Technical Review: Assess current mock implementation gaps
Resource Planning: Allocate development resources for integration

Short-term Actions (Next 2 Weeks)¶

Sandbox Setup: Configure sandbox environment and credentials
SDK Integration: Replace mock implementation with real SDK
Testing Framework: Develop comprehensive testing strategy

Medium-term Goals (Next Month)¶

Production Readiness: Complete all requirements for production access
Security Audit: Conduct thorough security review
Performance Optimization: Optimize system for production load

Document Status: Draft v1.0
Last Updated: March 10, 2026
Next Review: March 17, 2026
Owner: Technical Team Lead