tools/ts_interfaces/identity.ts

/**
 * @file identity.ts
 * @description Identity verification interfaces
 * Extensible design for passport/NFC, document+selfie, video ident, and third-party providers
 */

import * as plugins from './plugins.js';
import type {
  TIdentityVerificationMethod,
  TVerificationConfidence,
  TIdentityVerificationStatus,
  TIdentityDocumentType,
} from './types.js';

// ============================================================================
// IDENTITY VERIFICATION REQUEST
// ============================================================================

/**
 * Expected identity to verify against
 */
export interface IExpectedIdentity {
  fullName?: string;
  dateOfBirth?: string;
  nationality?: string;
  documentNumber?: string;
}

/**
 * Request for identity verification
 */
export interface IIdentityVerificationRequest {
  id: string;
  methods: TIdentityVerificationMethod[];
  requiredConfidence: TVerificationConfidence;
  expectedIdentity?: IExpectedIdentity;
  createdAt: number;
  expiresAt: number;
  callbackUrl?: string;
}

// ============================================================================
// DOCUMENT VERIFICATION
// ============================================================================

/**
 * Personal information from identity document
 */
export interface IDocumentPersonalInfo {
  fullName: string;
  givenNames: string;
  surname: string;
  dateOfBirth: string;
  sex: 'M' | 'F' | 'X';
  nationality: string;
  placeOfBirth?: string;
}

/**
 * Document validity information
 */
export interface IDocumentValidity {
  issueDate?: string;
  expiryDate: string;
  issuingAuthority?: string;
}

/**
 * Machine Readable Zone data
 */
export interface IMrzData {
  raw: string[];
  valid: boolean;
  checkDigitsValid: boolean;
}

/**
 * NFC chip data (for ePassports)
 */
export interface INfcChipData {
  readSuccess: boolean;
  chipAuthenticated: boolean;
  activeAuthentication?: {
    performed: boolean;
    success: boolean;
  };
  passiveAuthentication?: {
    performed: boolean;
    success: boolean;
    certificateChainValid: boolean;
  };
  dataGroupsRead: string[];
  photoBase64?: string;
}

/**
 * Document images
 */
export interface IDocumentImages {
  frontBase64?: string;
  backBase64?: string;
  portraitBase64?: string;
}

/**
 * Identity document data extracted from document
 */
export interface IIdentityDocument {
  documentType: TIdentityDocumentType;
  issuingCountry: string;
  documentNumber: string;
  personalInfo: IDocumentPersonalInfo;
  validity: IDocumentValidity;
  mrz?: IMrzData;
  nfcData?: INfcChipData;
  images?: IDocumentImages;
}

// ============================================================================
// FACIAL/BIOMETRIC VERIFICATION
// ============================================================================

/**
 * Liveness check result
 */
export interface ILivenessResult {
  isLive: boolean;
  confidence: number;
  checks: {
    blinkDetected?: boolean;
    headMovementDetected?: boolean;
    depthAnalysis?: boolean;
    textureAnalysis?: boolean;
  };
}

/**
 * Face matching result
 */
export interface IFaceMatchResult {
  matched: boolean;
  confidence: number;
  referenceSource: 'document_photo' | 'nfc_photo' | 'existing_profile';
}

/**
 * Facial verification result
 */
export interface IFacialVerification {
  livenessCheckPerformed: boolean;
  livenessResult?: ILivenessResult;
  faceMatchResult?: IFaceMatchResult;
  selfieReference?: string;
  capturedAt: number;
}

// ============================================================================
// THIRD-PARTY IDENTITY PROVIDER
// ============================================================================

/**
 * Third-party identity provider configuration
 */
export interface IIdentityProvider {
  id: string;
  name: string;
  type: 'oidc' | 'saml' | 'proprietary' | 'bankid' | 'eid';
  countries: string[];
  methods: TIdentityVerificationMethod[];
  maxConfidence: TVerificationConfidence;
  config?: Record<string, unknown>;
}

/**
 * Third-party verification result
 */
export interface IThirdPartyVerification {
  provider: IIdentityProvider;
  providerReference: string;
  verifiedAt: number;
  claims: Record<string, unknown>;
  levelOfAssurance?: 'low' | 'substantial' | 'high';
  rawAssertionReference?: string;
}

// ============================================================================
// VERIFICATION FAILURES
// ============================================================================

/**
 * Verification failure details
 */
export interface IVerificationFailure {
  code: string;
  method: TIdentityVerificationMethod;
  message: string;
  timestamp: number;
  recoverable: boolean;
}

/**
 * Verification audit entry
 */
export interface IVerificationAuditEntry {
  timestamp: number;
  action: string;
  details: Record<string, unknown>;
  actor?: {
    type: 'user' | 'system' | 'agent';
    id: string;
  };
}

// ============================================================================
// IDENTITY VERIFICATION RESULT
// ============================================================================

/**
 * Verified identity information
 */
export interface IVerifiedIdentity {
  fullName: string;
  givenNames?: string;
  surname?: string;
  dateOfBirth?: string;
  nationality?: string;
  address?: plugins.tsclass.business.IAddress;
}

/**
 * Complete identity verification result
 */
export interface IIdentityVerificationResult {
  id: string;
  requestId: string;
  status: TIdentityVerificationStatus;
  confidence: TVerificationConfidence;
  confidenceScore: number;
  methodsAttempted: TIdentityVerificationMethod[];
  successfulMethod?: TIdentityVerificationMethod;
  verifiedIdentity?: IVerifiedIdentity;
  documentVerification?: IIdentityDocument;
  facialVerification?: IFacialVerification;
  thirdPartyVerification?: IThirdPartyVerification;
  timestamps: {
    started: number;
    completed: number;
    expiresAt?: number;
  };
  failureReasons: IVerificationFailure[];
  auditTrail: IVerificationAuditEntry[];
}

// ============================================================================
// FACTORY FUNCTIONS
// ============================================================================

/**
 * Create an identity verification request
 */
export function createIdentityVerificationRequest(
  methods: TIdentityVerificationMethod[],
  requiredConfidence: TVerificationConfidence,
  expiresInSeconds: number = 3600
): IIdentityVerificationRequest {
  const now = Date.now();
  return {
    id: crypto.randomUUID(),
    methods,
    requiredConfidence,
    createdAt: now,
    expiresAt: now + expiresInSeconds * 1000,
  };
}

/**
 * Create a pending identity verification result
 */
export function createPendingVerificationResult(requestId: string): IIdentityVerificationResult {
  const now = Date.now();
  return {
    id: crypto.randomUUID(),
    requestId,
    status: 'pending',
    confidence: 'none',
    confidenceScore: 0,
    methodsAttempted: [],
    timestamps: {
      started: now,
      completed: 0,
    },
    failureReasons: [],
    auditTrail: [],
  };
}