feat(interfaces): add comprehensive TypeScript interface modules, demo data, docs, and publish metadata

ts_interfaces/identity.ts

@@ -0,0 +1,295 @@
+/**
+ * @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: [],
+  };
+}