Skip to content

Milestone: M3 — Issuing Functionality | SOW Reference: FR1, INT2, INT6 | Requirement Clarity: ✅ Clear | Dev Status: 🟢 Prototyped in POC Moved from docs/requirements/tasks/POC/07-phase3-claim-page-tracking.md — unmodified below.

M3-06 Phase 3: Claim Page & Tracking - POC Task

🎯 VNF SDK Reference Implementation

PRIMARY REFERENCE: vnf-wallet-sdk-nodejs-main/

All claim page and tracking tasks MUST follow the official VNF SDK sample application patterns

Key Reference Files: - Deep Link Handling: packages/sample-app/src/Constants.ts:10 - Deep link patterns for credential claiming - Presentation Flow: packages/sample-server/src/routes/Inspection.ts - Verification and presentation workflow - Exchange Tracking: packages/sdk/src/api/entities/VCLExchange.ts - Status tracking implementation - Frontend Integration: packages/sample-app/src/screens/MeinScreen.tsx:74 - UI patterns for credential operations - JWT Handling: packages/sdk/src/api/entities/VCLJwt.ts - JWT token management

Overview

FINAL PHASE: Implement public credential claim page and comprehensive tracking system to complete the end-to-end Velocity credentialing workflow following official VNF SDK sample patterns.

Velocity Architecture Alignment

This phase implements the employee claim experience described in the Velocity Phase Explanations using VNF SDK deep link patterns: - Employee receives email with VNF-compliant claim link - Employee clicks claim link and claims credential via VNF SDK - Dashboard updates with claimed/failed status using VCLExchange tracking - Complete audit trail and tracking using VNF SDK entities

Backend Tasks

1. Public Claim Controller

  • Task: Create public credential claim endpoints
  • Create public-claim.controller.ts
  • Implement endpoints:
    • GET /api/v1/public/claim/{token} - Get credential details
    • POST /api/v1/public/claim/{token}/validate - Validate claim token
    • POST /api/v1/public/claim/{token}/claim - Process credential claim
    • GET /api/v1/public/claim/{token}/status - Check claim status
  • Add token security validation and expiration checking

2. Claim Token Management

  • Task: Secure token generation and validation
  • Create claim-token.service.ts
  • Implement JWT-based claim tokens with:
    • Credential offer ID
    • Employee email verification
    • Expiration timestamp (30 days default)
    • Security hash for tampering detection
  • Add token blacklisting for claimed/expired tokens

3. Credential Claim Processing

  • Task: Handle credential claim workflow
  • Create credential-claim.service.ts
  • Implement claim validation:
    • Token validity and expiration
    • Credential offer status
    • Employee email verification
  • Process successful claims:
    • Update credential offer status to 'CLAIMED'
    • Record claim timestamp and metadata
    • Generate claim confirmation
  • Handle claim failures and error scenarios

4. Claim Analytics Service

  • Task: Track claim metrics and analytics
  • Create claim-analytics.service.ts
  • Track claim events:
    • Claim page visits
    • Successful claims
    • Failed claim attempts
    • Time to claim metrics
  • Generate claim rate reports
  • Add claim funnel analysis

5. Real-time Status Updates

  • Task: WebSocket updates for claim events
  • Update dashboard-websocket.gateway.ts
  • Add real-time claim event broadcasting:
    • credential:claimed - Successful claim
    • credential:claim-failed - Failed claim attempt
    • credential:claim-expired - Token expired
  • Update dashboard counters in real-time

Frontend Tasks

1. Public Claim Landing Page

  • Task: Create public credential claim interface
  • Create ClaimPage.tsx
  • Display credential details:
    • Employee name and email
    • Job title and employment period
    • Company information
    • Credential issuer details
  • Add claim instructions and mobile app links
  • Implement responsive design for mobile/desktop

2. Claim Process Flow

  • Task: Step-by-step claim workflow
  • Create ClaimWizard.tsx
  • Step 1: Verify employee email
  • Step 2: Review credential details
  • Step 3: Choose claim method (mobile app/web)
  • Step 4: Complete claim and confirmation
  • Add progress indicators and error handling

3. Mobile App Integration

  • Task: Mobile wallet app integration
  • Create MobileAppLinks.tsx
  • Add QR code generation for mobile claiming
  • Provide download links for credential wallet apps
  • Add deep linking for supported wallet apps
  • Implement fallback web-based claiming

4. Claim Status Tracking

  • Task: Real-time claim status updates
  • Create ClaimStatus.tsx
  • Show claim progress with status indicators
  • Display success/failure messages
  • Add claim confirmation details
  • Implement auto-refresh for status updates

5. Enhanced Dashboard Updates

  • Task: Update dashboard with claim tracking
  • Update CredentialDashboard.tsx
  • Add claim rate metrics and charts
  • Show real-time claim events
  • Add claim funnel analysis
  • Implement claim time analytics

Claim Workflow Implementation

Employee Claim Journey

flowchart TD
    A[Employee Receives Email] --> B[Clicks Claim Link]
    B --> C[Validate Claim Token]
    C --> D{Token Valid?}
    D -->|No| E[Show Error Message]
    D -->|Yes| F[Display Credential Details]
    F --> G[Verify Employee Email]
    G --> H{Email Verified?}
    H -->|No| I[Email Verification Required]
    H -->|Yes| J[Choose Claim Method]
    J --> K{Mobile or Web?}
    K -->|Mobile| L[Show QR Code]
    K -->|Web| M[Web-based Claim]
    L --> N[Open Mobile Wallet]
    M --> O[Download Credential]
    N --> P[Credential Added to Wallet]
    O --> P
    P --> Q[Update Status: CLAIMED]
    Q --> R[Send Confirmation]

Dashboard Update Flow

flowchart TD
    A[Credential Claimed] --> B[Update Database Status]
    B --> C[Broadcast WebSocket Event]
    C --> D[Update Dashboard Counters]
    D --> E[Update Claim Analytics]
    E --> F[Generate Real-time Notifications]

API Endpoints

Public Claim Endpoints

GET /api/v1/public/claim/{token}
POST /api/v1/public/claim/{token}/validate
POST /api/v1/public/claim/{token}/verify-email
POST /api/v1/public/claim/{token}/claim
GET /api/v1/public/claim/{token}/status
GET /api/v1/public/claim/{token}/mobile-apps

Analytics Endpoints

GET /api/v1/issuer/analytics/claim-rates
GET /api/v1/issuer/analytics/claim-funnel
GET /api/v1/issuer/analytics/time-to-claim
GET /api/v1/issuer/analytics/claim-methods

Database Schema Updates

Claim Tracking

CREATE TABLE credential_claims (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    credential_offer_id UUID REFERENCES credential_offers(id),
    claim_token VARCHAR(500) NOT NULL,
    claimed_at TIMESTAMP,
    claim_method VARCHAR(20), -- 'mobile', 'web'
    user_agent TEXT,
    ip_address INET,
    claim_metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_credential_claims_token ON credential_claims(claim_token);
CREATE INDEX idx_credential_claims_offer ON credential_claims(credential_offer_id);

Claim Analytics

CREATE TABLE claim_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    credential_offer_id UUID REFERENCES credential_offers(id),
    event_type VARCHAR(50) NOT NULL, -- 'page_visit', 'claim_attempt', 'claim_success', 'claim_failure'
    event_data JSONB,
    user_agent TEXT,
    ip_address INET,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_claim_events_type ON claim_events(event_type);
CREATE INDEX idx_claim_events_offer ON claim_events(credential_offer_id);

Security Implementation

Token Security

interface ClaimToken {
  credentialOfferId: string;
  employeeEmail: string;
  issuedAt: number;
  expiresAt: number;
  securityHash: string;
}

// Token validation
const validateClaimToken = (token: string): ClaimToken | null => {
  try {
    const decoded = jwt.verify(token, process.env.CLAIM_TOKEN_SECRET);
    // Additional security validations
    return decoded as ClaimToken;
  } catch (error) {
    return null;
  }
};

Rate Limiting

// Implement rate limiting for claim attempts
const claimRateLimit = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 attempts per window
  message: 'Too many claim attempts, please try again later'
});

Mobile Integration

QR Code Generation

// Generate QR code for mobile claiming
const generateClaimQR = (claimUrl: string): string => {
  return QRCode.toDataURL(claimUrl, {
    width: 256,
    margin: 2,
    color: {
      dark: '#000000',
      light: '#FFFFFF'
    }
  });
};

Deep Linking

// Mobile wallet deep links
const walletDeepLinks = {
  velocityWallet: `velocity://claim?token=${claimToken}`,
  genericWallet: `wallet://claim?url=${encodeURIComponent(claimUrl)}`,
  fallbackWeb: claimUrl
};

Dependencies & Prerequisites

Critical Requirements

  • Public route configuration for claim pages
  • JWT token management for secure claim tokens
  • QR code generation library
  • Mobile app download links and deep linking
  • Email verification system

External Dependencies

  • Mobile wallet app availability
  • QR code scanning capability
  • Deep linking support in wallet apps

Acceptance Criteria

Claim Functionality

  • Employees can access claim page via email link
  • Claim tokens are secure and expire after 30 days
  • Email verification required before claiming
  • Support both mobile and web-based claiming
  • QR codes work with mobile wallet apps
  • Successful claims update dashboard in real-time
  • Failed claims are tracked and reported

Analytics & Tracking

  • Track claim page visits and conversion rates
  • Monitor time-to-claim metrics
  • Generate claim funnel analysis
  • Real-time dashboard updates for claim events
  • Comprehensive audit trail for all claim activities

Security & Performance

  • Secure token validation prevents unauthorized claims
  • Rate limiting prevents abuse
  • Responsive design works on all devices
  • Page loads within 2 seconds
  • Handle concurrent claims gracefully

Estimated Timeline

Week 8: 5 days (FINAL PHASE) - Day 1-2: Public claim controller and token management - Day 3: Claim processing and analytics services - Day 4: Frontend claim page and mobile integration - Day 5: Dashboard updates and testing

Blockers & Risks

  • Dependency: Mobile wallet app availability for testing
  • Risk: QR code scanning reliability across devices
  • Blocker: Deep linking configuration for wallet apps
  • Risk: Email verification system integration
  • Dependency: Public route security configuration

✅ COMPLETION: This phase completes the end-to-end Velocity credentialing workflow from organization setup to employee credential claiming.