Consent & Connection

🔐 Data Source Cards

• Open Banking (TrueLayer): Toggle switch, 24-month transaction access, FCA-regulated badge
• Accounting Software (Xero): Toggle switch, P&L and balance sheet access, OAuth security
• Companies House: Toggle switch, public company info, no login required
• Each Card Shows: Provider name, data accessed, purpose, security level, expandable "Why?" section

🎛️ Toggle Controls

• Three-State Toggle: Ready (gray) → Connecting (blue) → Connected (green)
• Progress Bars: Animated 0-100% fill during connection
• Status Badges: "Ready to connect", "Connecting...", "✓ Connected"
• Disable Logic: Must select at least one source to proceed

💬 AI Guidance Message

• Opening Statement: "To assess your loan, I'll need to connect to your financial data sources"
• Reassurance: "This is secure, fast, and you maintain full control"
• Flexibility Note: "You can toggle any source on or off"

📊 Connection Summary

• Success State: Shows after all connections complete
• Data Retrieved: "✓ 1,847 transactions, 36 months P&L, Company verified"
• Next Step: "Continue to Identity Verification" button enabled

🎨 UI Events Captured

• onToggleSource(provider) → Enable/disable connection for specific provider
• onExpandInfo(provider) → Show "Why do you need this?" explanation
• onConnectAll() → Initiates OAuth flows for all selected sources
• onContinue() → Validates all connections and navigates to CM04

🔌 OAuth Initiation Endpoint

• Method: POST
• URL: /api/v1/applications/{application_id}/oauth/init
• Purpose: Generate OAuth authorization URLs for customer redirect

POST /api/v1/applications/app_20251222_143023_usr123/oauth/init
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "providers": ["truelayer", "xero", "companies_house"],
  "redirect_uri": "https://app.aina.co.uk/oauth/callback",
  "state": "app_20251222_143023_usr123"
}

{
  "request_id": "req_cm03_20251222_143345",
  "status": "success",
  "oauth_urls": {
    "truelayer": {
      "authorization_url": "https://auth.truelayer.com/connect?...",
      "state": "state_truelayer_12345",
      "expires_in": 600
    },
    "xero": {
      "authorization_url": "https://login.xero.com/identity/connect/authorize?...",
      "state": "state_xero_67890",
      "expires_in": 600
    },
    "companies_house": {
      "direct_lookup": true,
      "company_number": "12345678",
      // No OAuth needed - public API
    }
  },
  "timestamp": "2025-12-22T14:33:45Z"
}

🔄 OAuth Callback Endpoint

• Method: GET
• URL: /api/v1/oauth/callback
• Purpose: Receive authorization codes and exchange for access tokens

GET /api/v1/oauth/callback
  ?code=auth_code_abc123xyz
  &state=state_truelayer_12345
  &scope=transactions balance

// Server exchanges code for access token
POST https://auth.truelayer.com/connect/token
{
  "grant_type": "authorization_code",
  "client_id": "{AINA_CLIENT_ID}",
  "client_secret": "{AINA_CLIENT_SECRET}",
  "code": "auth_code_abc123xyz",
  "redirect_uri": "https://app.aina.co.uk/oauth/callback"
}

// Response: access_token, refresh_token, expires_in

💾 Token Storage Endpoint

• Method: POST
• URL: /api/v1/applications/{application_id}/tokens
• Purpose: Securely store encrypted access and refresh tokens

{
  "application_id": "app_20251222_143023_usr123",
  "provider": "truelayer",
  "access_token": "{ENCRYPTED}",
  "refresh_token": "{ENCRYPTED}",
  "expires_at": "2025-12-22T15:33:45Z",
  "scope": "transactions balance",
  "created_at": "2025-12-22T14:33:45Z"
}

🔒 Security Measures

• State Parameter: CSRF protection - validate state matches on callback
• Token Encryption: AES-256 encryption for all stored tokens
• HTTPS Only: All OAuth flows use TLS 1.3
• Token Rotation: Automatic refresh before expiry

🔧 OAuth Coordinator Service

• Multi-Provider Management: Handles OAuth flows for TrueLayer, Xero simultaneously
• State Management: Generates cryptographically secure state parameters
• Callback Routing: Routes OAuth callbacks to correct application
• Token Lifecycle: Manages token expiry, refresh, and revocation

// OAuth Flow Orchestration

function initiateOAuthFlow(applicationId, providers) {
  const oauthUrls = {};
  
  for (const provider of providers) {
    // 1. Generate unique state parameter
    const state = generateSecureState(applicationId, provider);
    
    // 2. Store state in Redis (10-minute TTL)
    redis.set(`oauth_state:${state}`, {
      applicationId,
      provider,
      createdAt: Date.now()
    }, 600);
    
    // 3. Build authorization URL
    const authUrl = buildAuthorizationUrl(provider, state);
    oauthUrls[provider] = { authUrl, state };
  }
  
  return oauthUrls;
}

function handleOAuthCallback(code, state) {
  // 1. Validate state parameter
  const stateData = redis.get(`oauth_state:${state}`);
  if (!stateData) throw 'Invalid or expired state';
  
  // 2. Exchange authorization code for tokens
  const tokens = await exchangeCodeForTokens(
    stateData.provider,
    code
  );
  
  // 3. Encrypt and store tokens
  await storeEncryptedTokens(
    stateData.applicationId,
    stateData.provider,
    tokens
  );
  
  // 4. Trigger data sync
  await triggerDataSync(stateData.applicationId, stateData.provider);
  
  // 5. Delete state (prevent reuse)
  redis.del(`oauth_state:${state}`);
}

🔐 Consent Management

• Granular Permissions: Track exactly what data customer consented to
• Consent Audit Trail: Log timestamp, scope, IP address, user agent
• Revocation Support: Customer can revoke consent anytime from settings
• Expiry Tracking: Alert customer when consent nears expiration

♻️ Token Refresh Strategy

• Proactive Refresh: Refresh tokens 5 minutes before expiry
• Background Job: Cron job checks expiring tokens every 5 minutes
• Failure Handling: If refresh fails, notify customer to re-authorize
• Token Rotation: New refresh token issued with each refresh

// Background job runs every 5 minutes

async function refreshExpiringTokens() {
  // Find tokens expiring in next 10 minutes
  const expiring = await db.query(`
    SELECT * FROM oauth_tokens
    WHERE expires_at < NOW() + INTERVAL '10 minutes'
    AND refresh_token IS NOT NULL
  `);
  
  for (const token of expiring) {
    try {
      // Call provider's token refresh endpoint
      const newTokens = await refreshToken(
        token.provider,
        token.refresh_token
      );
      
      // Update database with new tokens
      await db.update('oauth_tokens', {
        access_token: encrypt(newTokens.access_token),
        refresh_token: encrypt(newTokens.refresh_token),
        expires_at: Date.now() + newTokens.expires_in,
        updated_at: Date.now()
      });
      
    } catch (error) {
      // Notify customer to re-authorize
      await sendNotification(token.user_id, {
        type: 'REAUTH_REQUIRED',
        provider: token.provider
      });
    }
  }
}

✅ Connection Validation

• Test API Call: Make test request to verify token works
• Scope Verification: Ensure granted scopes match requested scopes
• Data Availability: Confirm minimum data requirements met
• Quality Check: Validate data format and completeness

💾 Redis State Storage

• Purpose: Store OAuth state parameters temporarily
• TTL: 10 minutes (state expires if customer doesn't complete flow)
• Key Format: oauth_state:{state_parameter}
• Value: JSON with application_id, provider, timestamp

KEY: oauth_state:state_truelayer_12345abc
VALUE: {
  "application_id": "app_20251222_143023_usr123",
  "provider": "truelayer",
  "user_id": "usr_olivia_thompson",
  "created_at": 1703258425000,
  "redirect_uri": "https://app.aina.co.uk/oauth/callback"
}
TTL: 600 seconds (10 min)

🔐 Token Encryption Service

• Algorithm: AES-256-GCM (Galois/Counter Mode)
• Key Management: AWS KMS for encryption key rotation
• Encryption-at-Rest: All tokens encrypted before PostgreSQL storage
• Encryption-in-Transit: TLS 1.3 for all API calls

function encryptToken(plaintext) {
  // 1. Get encryption key from AWS KMS
  const dataKey = await kms.generateDataKey({
    KeyId: process.env.KMS_KEY_ID
  });
  
  // 2. Generate random IV (initialization vector)
  const iv = crypto.randomBytes(16);
  
  // 3. Encrypt with AES-256-GCM
  const cipher = crypto.createCipheriv(
    'aes-256-gcm',
    dataKey.Plaintext,
    iv
  );
  
  const encrypted = Buffer.concat([
    cipher.update(plaintext, 'utf8'),
    cipher.final()
  ]);
  
  const authTag = cipher.getAuthTag();
  
  // 4. Return encrypted data + metadata
  return {
    ciphertext: encrypted.toString('base64'),
    iv: iv.toString('base64'),
    authTag: authTag.toString('base64'),
    encryptedDataKey: dataKey.CiphertextBlob.toString('base64')
  };
}

🌐 API Gateway Routing

• OAuth Init: Routes to OAuth Coordinator service
• OAuth Callback: Validates origin, routes to token exchange handler
• Token Storage: Routes to secure token vault service
• Rate Limiting: Max 10 OAuth initiations per minute per user

📊 Connection Monitoring

• Health Checks: Test OAuth providers every 5 minutes
• Connection Status: Track success rate per provider
• Alerting: Notify ops team if success rate drops below 95%
• Metrics: Average connection time, failure reasons, retry counts

🔄 OAuth Provider Comparison

💾 OAuth Tokens Table

• Database: PostgreSQL
• Table: oauth_tokens
• Encryption: All tokens encrypted at application layer before storage
• Indexing: Indexed on application_id and provider for fast lookups