facecog-liveness-showcase 0.0.1

package/projects/facecog-liveness-verification/src/lib/interfaces/camera-provider.interface.ts

@@ -0,0 +1,107 @@
+import { InjectionToken } from '@angular/core';
+
+/**
+ * Interface for camera provider abstraction
+ * Implement this interface in your app to provide platform-specific camera access
+ * (e.g., Capacitor for mobile, browser API for web)
+ *
+ * @example
+ * ```typescript
+ * // capacitor-camera.provider.ts
+ * @Injectable()
+ * export class CapacitorCameraProvider implements ICameraProvider {
+ *   async checkPermissions(): Promise<boolean> {
+ *     const status = await Camera.checkPermissions();
+ *     return status.camera === 'granted';
+ *   }
+ *
+ *   async requestPermissions(): Promise<boolean> {
+ *     const status = await Camera.requestPermissions();
+ *     return status.camera === 'granted';
+ *   }
+ *
+ *   async startCamera(videoElement: HTMLVideoElement): Promise<MediaStream> {
+ *     // Implementation
+ *   }
+ *
+ *   stopCamera(): void {
+ *     // Implementation
+ *   }
+ * }
+ *
+ * // app.module.ts
+ * providers: [
+ *   { provide: CAMERA_PROVIDER, useClass: CapacitorCameraProvider }
+ * ]
+ * ```
+ */
+/**
+ * Brightness analysis result
+ */
+export interface BrightnessData {
+  brightness: number;
+  isLowLight: boolean;
+  isTooLight: boolean;
+}
+
+export interface ICameraProvider {
+  /**
+   * Check if camera permissions are granted
+   */
+  checkPermissions(): Promise<boolean>;
+
+  /**
+   * Request camera permissions from the user
+   * @returns true if permission was granted, false otherwise
+   */
+  requestPermissions(): Promise<boolean>;
+
+  /**
+   * Start the camera and attach to video element
+   * @param videoElement The video element to attach the stream to
+   * @returns The media stream
+   */
+  startCamera(videoElement: HTMLVideoElement): Promise<MediaStream>;
+
+  /**
+   * Stop the camera and release resources
+   */
+  stopCamera(): void;
+
+  /**
+   * Analyze brightness of a video frame
+   * @param videoElement The video element to analyze
+   * @returns Brightness data including level and warnings
+   */
+  analyzeBrightness?(videoElement: HTMLVideoElement): BrightnessData;
+
+  /**
+   * Start continuous brightness monitoring
+   * @param videoElement The video element to monitor
+   * @param callback Callback function called with brightness data
+   * @param intervalMs How often to check brightness (default 1000ms)
+   * @returns Monitoring ID that can be used to stop monitoring
+   */
+  startBrightnessMonitoring?(
+    videoElement: HTMLVideoElement,
+    callback: (data: BrightnessData) => void,
+    intervalMs?: number
+  ): number;
+
+  /**
+   * Stop brightness monitoring
+   * @param monitoringId The ID returned by startBrightnessMonitoring
+   */
+  stopBrightnessMonitoring?(monitoringId: number): void;
+}
+
+/**
+ * Injection token for the camera provider
+ * Provide this in your app module with your implementation
+ *
+ * @example
+ * providers: [
+ *   { provide: CAMERA_PROVIDER, useClass: MyCameraProvider }
+ * ]
+ */
+export const CAMERA_PROVIDER = new InjectionToken<ICameraProvider>('CAMERA_PROVIDER');

package/projects/facecog-liveness-verification/src/lib/interfaces/category-info.interface.ts

@@ -0,0 +1,9 @@
+/**
+ * Category display information
+ */
+export interface CategoryInfo {
+  name: string;
+  icon: string;
+  color: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/custom-pose-data.interface.ts

@@ -0,0 +1,14 @@
+/**
+ * Data structure for a custom pose saved by a user
+ */
+export interface CustomPoseData {
+  id: number;
+  userId: string;
+  name: string;
+  description: string;
+  category: string;
+  difficulty: string;
+  detectionStrategy: string;
+  imageBlobUrl: string;
+  poseKeypoints: any;
+}

package/projects/facecog-liveness-verification/src/lib/interfaces/custom-pose-repository.interface.ts

@@ -0,0 +1,48 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { CustomPoseData } from './custom-pose-data.interface';
+import { CustomPoseResponse } from './custom-pose-response.interface';
+
+/**
+ * Interface for custom pose repository implementations.
+ * Allows the library to work with custom poses without depending on a specific backend.
+ */
+export interface ICustomPoseRepository {
+  /**
+   * Observable stream of custom poses
+   */
+  customPoses$: Observable<CustomPoseData[]>;
+
+  /**
+   * Load all custom poses from the backend
+   */
+  loadCustomPoses(): Observable<CustomPoseResponse>;
+
+  /**
+   * Create a new custom pose from a base64 image
+   * Returns { pose, isNew } - isNew is false if a duplicate was found
+   */
+  createCustomPoseFromBase64(
+    name: string,
+    description: string,
+    category: string,
+    difficulty: string,
+    base64Image: string,
+    poseKeypoints: any
+  ): Promise<{ pose: CustomPoseData; isNew: boolean }>;
+
+  /**
+   * Delete a custom pose by ID
+   */
+  deleteCustomPose(id: number): Observable<CustomPoseResponse>;
+
+  /**
+   * Get current custom poses synchronously
+   */
+  getCustomPoses(): CustomPoseData[];
+}
+
+/**
+ * Injection token for custom pose repository
+ */
+export const CUSTOM_POSE_REPOSITORY = new InjectionToken<ICustomPoseRepository>('CUSTOM_POSE_REPOSITORY');

package/projects/facecog-liveness-verification/src/lib/interfaces/custom-pose-response.interface.ts

@@ -0,0 +1,14 @@
+import { CustomPoseData } from './custom-pose-data.interface';
+
+/**
+ * Response from custom pose API operations
+ */
+export interface CustomPoseResponse {
+  success: boolean;
+  pose?: CustomPoseData;
+  poses?: CustomPoseData[];
+  count?: number;
+  error?: string;
+  message?: string;
+  isNew?: boolean; // True if pose was newly created, false if duplicate found
+}

package/projects/facecog-liveness-verification/src/lib/interfaces/index.ts

@@ -0,0 +1,52 @@
+export { LivenessVerificationConfig } from './liveness-verification-config.interface';
+export { VerificationStepChangeEvent } from './verification-step-change-event.interface';
+export { VerificationProgressEvent } from './verification-progress-event.interface';
+export { LivenessConfig } from './liveness-config.interface';
+export { LivenessMetadata } from './liveness-metadata.interface';
+export { AnalyzeResponse } from './analyze-response.interface';
+export { MultiBackendAnalyzeResponse } from './multi-backend-analyze-response.interface';
+export { LivenessResult } from './liveness-result.interface';
+export { PoseMatchResult } from './pose-match-result.interface';
+export { LivenessActionResult } from './liveness-action-result.interface';
+export { VideoRecording } from './video-recording.interface';
+export { BackendResponse } from './backend-response.interface';
+export { MultiBackendLivenessResult } from './multi-backend-liveness-result.interface';
+export { PoseKeypoint } from './pose-keypoint.interface';
+export { PoseDefinition } from './pose-definition.interface';
+export { CategoryInfo } from './category-info.interface';
+export { CustomPoseData } from './custom-pose-data.interface';
+export { CustomPoseResponse } from './custom-pose-response.interface';
+export { PoseVerifyResponse } from './pose-verify-response.interface';
+
+// Backend and provider interfaces (moved from services/)
+export { IBackendAdapter } from './backend-adapter.interface';
+export { IBackendHttpClient, SessionResponse, BACKEND_HTTP_CLIENT } from './backend-http-client.interface';
+export { ICameraProvider, BrightnessData, CAMERA_PROVIDER } from './camera-provider.interface';
+export { ICustomPoseRepository, CUSTOM_POSE_REPOSITORY } from './custom-pose-repository.interface';
+
+// Verification plan and session
+export {
+  VerificationStep,
+  VerificationPlan,
+  GestureResult,
+  FaceTecResult
+} from './verification-plan.interface';
+export {
+  VerificationSessionStartRequest,
+  VerificationSessionStartResponse,
+  VerifyGesturesRequest,
+  VerifyGesturesResponse,
+  VerifyFaceTecRequest,
+  VerifyFaceTecResponse,
+  VerifyFinalizeResponse
+} from './verification-session.interface';
+
+// AWS Face Liveness
+export {
+  AwsFaceLivenessSessionResponse,
+  AwsFaceLivenessResultsResponse,
+  AwsCredentialsResponse
+} from './aws-face-liveness.interface';
+
+// Scan results (FaceTec, AWS Face Liveness component results)
+export { FaceTecScanResult, AwsFaceLivenessScanResult } from './scan-results.interface';

package/projects/facecog-liveness-verification/src/lib/interfaces/liveness-action-result.interface.ts

@@ -0,0 +1,13 @@
+import { LivenessAction } from '../types/liveness-action.type';
+
+/**
+ * Result of a liveness action challenge
+ */
+export interface LivenessActionResult {
+  action: LivenessAction;
+  completed: boolean;
+  /** Progress value from 0-1 */
+  progress: number;
+  message: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/liveness-config.interface.ts

@@ -0,0 +1,17 @@
+import { LivenessBackend } from '../types/liveness-backend.type';
+
+/**
+ * Legacy liveness configuration interface
+ */
+export interface LivenessConfig {
+  exampleImageUrl?: string;
+  exampleImageBase64?: string;
+  backends: LivenessBackend[];
+  similarityThreshold?: number;
+  maxRetries?: number;
+  videoMaxSizeMB?: number;
+  enableVideoRecording?: boolean;
+  enableAutoCapture?: boolean;
+  captureFrameCount?: number;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/liveness-metadata.interface.ts

@@ -0,0 +1,17 @@
+import { LivenessBackend } from '../types/liveness-backend.type';
+
+/**
+ * Metadata for a liveness verification result
+ */
+export interface LivenessMetadata {
+  timestamp: string;
+  backend: LivenessBackend;
+  confidence: number;
+  attemptNumber: number;
+  videoSizeMB?: number;
+  capturedFrames?: number;
+  sessionId?: string;
+  gestureResult?: unknown;
+  facetecResult?: unknown;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/liveness-result.interface.ts

@@ -0,0 +1,24 @@
+import { LivenessMetadata } from './liveness-metadata.interface';
+import { MultiBackendAnalyzeResponse } from './multi-backend-analyze-response.interface';
+
+/**
+ * Result of a liveness verification
+ */
+export interface LivenessResult {
+  success: boolean;
+  confidence: number;
+  /** Base64 JPEG/PNG of verified image */
+  verifiedImage: string;
+  /** MP4 video blob (local) */
+  videoBlob?: Blob;
+  /** S3 URL (after upload) */
+  videoUrl?: string;
+  multiBackendResults?: MultiBackendAnalyzeResponse;
+  metadata: LivenessMetadata;
+  error?: string;
+  /** ISO timestamp of when the user clicked "Start video check" in AWS Face Liveness */
+  startVideoCheckClickedAt?: string;
+  /** ISO timestamp of when video recording began */
+  recordingStartedAt?: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/liveness-verification-config.interface.ts

@@ -0,0 +1,41 @@
+import { LivenessBackend } from '../types/liveness-backend.type';
+
+/**
+ * Configuration for the Liveness Verification library
+ */
+export interface LivenessVerificationConfig {
+  /** API URL for verification backend. Default: 'http://localhost:3002' */
+  apiUrl?: string;
+  /** Backends to use for verification. Default: ['mock'] */
+  backends?: LivenessBackend[];
+  /** ID of predefined pose to verify (1-40). If not set, user selects from pose grid */
+  poseId?: number;
+  /** Custom pose for verification (alternative to poseId) */
+  customPose?: {
+    imageData: string;
+    description: string;
+  };
+  /** Maximum retry attempts. Default: 3 */
+  maxRetries?: number;
+  /** Enable auto-capture when pose is matched. Default: true */
+  autoCapture?: boolean;
+  /** Enable video recording during verification. Default: true */
+  enableVideoRecording?: boolean;
+  /** Similarity threshold for pose matching (0-1). Default: 0.62 */
+  similarityThreshold?: number;
+  /** Maximum video size in MB. Default: 10 */
+  videoMaxSizeMB?: number;
+  /** Number of frames to capture. Default: 5 */
+  captureFrameCount?: number;
+  /** Show intro screen with pose selection. Default: true */
+  showIntroScreen?: boolean;
+  /** Show pose selector grid. Default: true */
+  showPoseSelector?: boolean;
+  /** Enable AWS Face Liveness (oval challenge) after pose capture. Default: false */
+  useAwsFaceLiveness?: boolean;
+  /** Example image URL for reference pose */
+  exampleImageUrl?: string;
+  /** Example image as base64 for reference pose */
+  exampleImageBase64?: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/multi-backend-analyze-response.interface.ts

@@ -0,0 +1,21 @@
+import { AnalyzeResponse } from './analyze-response.interface';
+
+/**
+ * Response from multi-backend analysis
+ */
+export interface MultiBackendAnalyzeResponse {
+  amazon: AnalyzeResponse;
+  openpose: AnalyzeResponse;
+  facetec: AnalyzeResponse;
+  primary: AnalyzeResponse;
+  consensus: {
+    isLive: boolean;
+    confidence: number;
+    votingResults: {
+      liveVotes: number;
+      notLiveVotes: number;
+      agreement: 'unanimous' | 'majority' | 'split';
+    };
+  };
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/multi-backend-liveness-result.interface.ts

@@ -0,0 +1,14 @@
+import { LivenessResult } from './liveness-result.interface';
+import { MultiBackendAnalyzeResponse } from './multi-backend-analyze-response.interface';
+
+/**
+ * Extended liveness result with multi-backend analysis
+ */
+export interface MultiBackendLivenessResult extends Omit<LivenessResult, 'metadata'> {
+  multiBackendResults: MultiBackendAnalyzeResponse;
+  metadata: {
+    timestamp: string;
+    sessionId: string;
+  };
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/pose-definition.interface.ts

@@ -0,0 +1,35 @@
+import { PoseCategory } from '../types/pose-category.type';
+import { PoseDifficulty } from '../types/pose-difficulty.type';
+import { DetectionStrategy } from '../types/detection-strategy.type';
+import { PoseKeypoint } from './pose-keypoint.interface';
+
+/**
+ * Definition of a pose for verification
+ */
+export interface PoseDefinition {
+  id: number;
+  name: string;
+  description: string;
+  category: PoseCategory;
+  imagePath: string;
+  detectionStrategy: DetectionStrategy;
+  difficulty: PoseDifficulty;
+  /**
+   * Static reference keypoints for automatic detection (normalized 0-1)
+   * For MoveNet model: 17 keypoints
+   * 0: nose, 1: left_eye, 2: right_eye, 3: left_ear, 4: right_ear,
+   * 5: left_shoulder, 6: right_shoulder, 7: left_elbow, 8: right_elbow,
+   * 9: left_wrist, 10: right_wrist, 11: left_hip, 12: right_hip,
+   * 13: left_knee, 14: right_knee, 15: left_ankle, 16: right_ankle
+   */
+  poseKeypoints?: PoseKeypoint[];
+  /**
+   * Indicates if this is a custom user-uploaded pose
+   */
+  isCustom?: boolean;
+  /**
+   * Blob URL for custom pose images (used for dynamically uploaded poses)
+   */
+  imageBlobUrl?: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/pose-keypoint.interface.ts

@@ -0,0 +1,12 @@
+/**
+ * Pose keypoint with normalized coordinates
+ */
+export interface PoseKeypoint {
+  /** Normalized x coordinate (0-1) */
+  x: number;
+  /** Normalized y coordinate (0-1) */
+  y: number;
+  /** Confidence score (0-1) */
+  confidence: number;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/pose-match-result.interface.ts

@@ -0,0 +1,9 @@
+/**
+ * Result of a pose match comparison
+ */
+export interface PoseMatchResult {
+  matched: boolean;
+  similarity: number;
+  message: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/pose-verify-response.interface.ts

@@ -0,0 +1,8 @@
+/**
+ * Response from pose verification endpoint
+ */
+export interface PoseVerifyResponse {
+  matchScore: number;
+  similarity: number;
+  keypoints?: any;
+}

package/projects/facecog-liveness-verification/src/lib/interfaces/scan-results.interface.ts

@@ -0,0 +1,29 @@
+/**
+ * FaceTec Scan Result
+ */
+export interface FaceTecScanResult {
+  success: boolean;
+  faceScan: string; // Base64 encoded FaceScan data
+  auditTrailImage?: string;
+  lowQualityAuditTrailImage?: string;
+  error?: string;
+}
+
+/**
+ * AWS Face Liveness Scan Result
+ */
+export interface AwsFaceLivenessScanResult {
+  success: boolean;
+  isLive: boolean;
+  confidence: number;
+  confidencePercent: number;
+  sessionId: string;
+  error?: string;
+  metadata?: unknown;
+  /** Video recording blob captured during the liveness check */
+  videoBlob?: Blob;
+  /** ISO timestamp of when the user clicked "Start video check" */
+  startVideoCheckClickedAt?: string;
+  /** ISO timestamp of when video recording began */
+  recordingStartedAt?: string;
+}

package/projects/facecog-liveness-verification/src/lib/interfaces/verification-plan.interface.ts

@@ -0,0 +1,42 @@
+import { VerificationStepKind } from '../types/verification-step-kind.type';
+
+/**
+ * Single step in the verification plan
+ */
+export interface VerificationStep {
+  kind: VerificationStepKind;
+  pose?: string; // Required if kind is 'gesture' (e.g., 'hello', 'thumbsUp')
+  completed?: boolean;
+  result?: unknown;
+}
+
+/**
+ * Verification plan: array of steps to execute sequentially
+ * Example: [{ kind: 'gesture', pose: 'hello' }, { kind: 'facetec' }, { kind: 'gesture', pose: 'thumbsUp' }]
+ */
+export type VerificationPlan = VerificationStep[];
+
+/**
+ * Result of a single gesture verification step
+ */
+export interface GestureResult {
+  stepIndex: number;
+  pose: string;
+  backend: string; // Which backend was used (amazon, openpose)
+  isLive: boolean;
+  confidence: number;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of a FaceTec verification step
+ */
+export interface FaceTecResult {
+  stepIndex: number;
+  isLive: boolean;
+  confidence: number;
+  faceScanId?: string; // FaceTec's scan ID
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}

package/projects/facecog-liveness-verification/src/lib/interfaces/verification-progress-event.interface.ts

@@ -0,0 +1,12 @@
+import { VerificationFlowStep } from '../types/verification-flow-step.type';
+
+/**
+ * Progress event during verification
+ */
+export interface VerificationProgressEvent {
+  step: VerificationFlowStep;
+  /** Progress value from 0-100 */
+  progress: number;
+  message: string;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/verification-session.interface.ts

@@ -0,0 +1,72 @@
+import { VerificationStep, GestureResult, FaceTecResult } from './verification-plan.interface';
+
+/**
+ * Request to start a new sequential verification session
+ */
+export interface VerificationSessionStartRequest {
+  plan: VerificationStep[];
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Response when starting a verification session
+ */
+export interface VerificationSessionStartResponse {
+  sessionId: string;
+  plan: VerificationStep[];
+  expiresAt: Date;
+}
+
+/**
+ * Request to verify gesture step(s)
+ */
+export interface VerifyGesturesRequest {
+  sessionId: string;
+  stepIndex: number;
+  frames: string[]; // Array of base64-encoded frames
+  pose: string;
+  frameHash?: string;
+}
+
+/**
+ * Response from gesture verification
+ */
+export interface VerifyGesturesResponse {
+  sessionId: string;
+  stepIndex: number;
+  result: GestureResult;
+  frameHash: string;
+}
+
+/**
+ * Request to verify FaceTec step
+ */
+export interface VerifyFaceTecRequest {
+  sessionId: string;
+  stepIndex: number;
+  faceScanBlob: string;
+  frameHash: string;
+}
+
+/**
+ * Response from FaceTec verification
+ */
+export interface VerifyFaceTecResponse {
+  sessionId: string;
+  stepIndex: number;
+  result: FaceTecResult;
+}
+
+/**
+ * Response from finalizing verification
+ */
+export interface VerifyFinalizeResponse {
+  sessionId: string;
+  success: boolean;
+  allPassed: boolean;
+  confidence: number;
+  gestureResults: GestureResult[];
+  facetecResult?: FaceTecResult;
+  failedSteps: number[];
+  completedAt: Date;
+}

package/projects/facecog-liveness-verification/src/lib/interfaces/verification-step-change-event.interface.ts

@@ -0,0 +1,11 @@
+import { VerificationFlowStep } from '../types/verification-flow-step.type';
+
+/**
+ * Event emitted when flow step changes
+ */
+export interface VerificationStepChangeEvent {
+  step: VerificationFlowStep;
+  previousStep?: VerificationFlowStep;
+  timestamp: Date;
+}
+

package/projects/facecog-liveness-verification/src/lib/interfaces/video-recording.interface.ts

@@ -0,0 +1,9 @@
+/**
+ * Video recording data
+ */
+export interface VideoRecording {
+  blob: Blob;
+  sizeMB: number;
+  duration: number;
+}
+