@nice2dev/ui-security 1.0.10

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# @nice2dev/ui-security — Changelog
+
+## [0.1.0] — 2025-06-01
+
+Initial alpha release — 15 source files.
+
+- Security components and utilities
+- **Note**: Zero test coverage — tests needed
+
+All notable changes to `@nice2dev/ui-security` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-06-16
+
+### 🔒 Initial Release
+
+First release of `@nice2dev/ui-security` — frontend-first biometric and security components for React.
+
+### Biometric Components
+
+- **NiceFingerprintScanner** — camera-based fingerprint scanning with crossing-number minutiae extraction, enroll/verify modes, quality indicator, minutiae overlay
+- **NiceIrisScanner** — Daugman's algorithm for iris segmentation, 256-bit Gabor-like iris codes, Hamming distance matching with rotation compensation, liveness detection
+- **NiceFaceRecognition** — camera face detection with skin-color YCbCr segmentation, 128-dimensional embeddings, cosine similarity matching, photo comparison mode, liveness challenges (blink, smile, head turn)
+
+### Authentication Components
+
+- **NicePinKeypad** — numeric PIN entry with configurable length (4–8), scramble mode, lockout after max attempts, SHA-256 hash verification, biometric fallback
+- **NicePatternLock** — Android-style pattern lock with configurable grid (3×3 to 6×6), trail visualization, error animations, touch & mouse support
+- **NicePassphraseInput** — secure passphrase entry with real-time strength meter, show/hide toggle, confirmation mode, copy protection
+- **NiceWebAuthnButton** — FIDO2/Passkey registration and authentication, automatic platform/cross-platform detection, passkey availability check
+
+### Security Management Components
+
+- **NiceSecurityAuditLog** — security event log viewer with method/status filters, risk-score colour coding, pagination, JSON export
+- **NiceSessionManager** — active session viewer with device info, trust badges, session revocation
+- **NiceMfaSelector** — multi-factor authentication method picker with grid/list layout, verified state tracking, required-count enforcement
+- **NiceDeviceTrust** — client-side device fingerprinting with trust-score gauge, factor breakdown (GPU, secure context, credential API, etc.)
+
+### Core
+
+- **BiometricEngine** — pure-frontend biometric processing engine (~500 lines): fingerprint minutiae extraction, iris code generation, face embedding, liveness detection, device fingerprinting, WebAuthn wrappers, optional backend verification
+- **Type system** — comprehensive TypeScript types: SecurityVerificationStatus, BiometricMethod, BiometricTemplate, FingerprintFeatures, IrisFeatures, FaceFeatures, KeypadConfig, PatternLockConfig, WebAuthnConfig, SecurityAuditEntry, DeviceTrustScore
+- **i18n** — NiceI18nProvider/useNiceTranslation pattern with fallback to English defaults
+- **Theme** — full CSS custom properties system with light/dark mode support (--security-* variables)
+
+### Architecture
+
+- All components work **fully frontend** — no backend required
+- Optional backend verification endpoint via `verifyEndpoint` config
+- SHA-256 hash comparison for PIN/pattern/passphrase (never sends plaintext)
+- Camera access via getUserMedia with graceful fallback
+- Zero external dependencies (peer: React ≥ 17)

package/README.md

@@ -0,0 +1,26 @@
+# @nice2dev/ui-security
+
+> Security components for NiceToDev UI — RBAC, audit, token inspection.
+
+> **Alpha** — this package is in early development. API may change.
+
+## Features
+
+- RBAC (Role-Based Access Control) integration
+- Audit log components
+- Token inspection utilities
+- Designed to work with `@nice2dev/auth` and `@nice2dev/erp-adapter`
+
+## Installation
+
+```bash
+npm install @nice2dev/ui-security
+```
+
+## Status
+
+Early alpha — zero test coverage. Use in production at your own risk.
+
+## License
+
+MIT © NiceToDev

package/dist/compliance-utilities.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @file Nice2Dev Compliance Utilities
+ * @description GDPR, HIPAA, SOC 2, WCAG compliance helpers
+ * @packageDocumentation
+ */
+export interface GDPRConfig {
+    /** Data controller info */
+    dataController: {
+        name: string;
+        email: string;
+        address?: string;
+    };
+    /** Data protection officer */
+    dpo?: {
+        name: string;
+        email: string;
+    };
+    /** Cookie consent categories */
+    cookieCategories: CookieCategory[];
+    /** Privacy policy URL */
+    privacyPolicyUrl: string;
+    /** Cookie policy URL */
+    cookiePolicyUrl?: string;
+}
+export interface CookieCategory {
+    key: string;
+    name: string;
+    description: string;
+    required: boolean;
+    cookies: CookieInfo[];
+}
+export interface CookieInfo {
+    name: string;
+    purpose: string;
+    expiry: string;
+    provider: string;
+}
+export interface ConsentPreferences {
+    necessary: boolean;
+    functional?: boolean;
+    analytics?: boolean;
+    marketing?: boolean;
+    [key: string]: boolean | undefined;
+}
+/**
+ * Get stored consent preferences
+ */
+export declare function getConsentPreferences(): ConsentPreferences | null;
+/**
+ * Save consent preferences
+ */
+export declare function saveConsentPreferences(preferences: ConsentPreferences): void;
+/**
+ * Check if consent was given for a category
+ */
+export declare function hasConsent(category: string): boolean;
+/**
+ * Clear all non-essential cookies
+ */
+export declare function clearNonEssentialCookies(essentialCookies: string[]): void;
+/**
+ * Generate GDPR data export
+ */
+export declare function generateDataExport(userId: string, endpoints: {
+    profile: string;
+    activity: string;
+    preferences: string;
+    [key: string]: string;
+}, fetchFn?: typeof fetch): Promise<Record<string, unknown>>;
+/**
+ * Request data deletion
+ */
+export declare function requestDataDeletion(userId: string, endpoint: string, fetchFn?: typeof fetch): Promise<{
+    success: boolean;
+    confirmationId?: string;
+    error?: string;
+}>;
+export interface HIPAAConfig {
+    /** Organization name */
+    organization: string;
+    /** Enable audit logging */
+    auditLogging: boolean;
+    /** Session timeout in minutes */
+    sessionTimeout: number;
+    /** Require MFA */
+    requireMFA: boolean;
+    /** Data encryption requirements */
+    encryption: {
+        atRest: boolean;
+        inTransit: boolean;
+        algorithm: string;
+    };
+}
+export interface PHIAccessLog {
+    id: string;
+    userId: string;
+    action: 'view' | 'create' | 'update' | 'delete' | 'export' | 'print';
+    resourceType: string;
+    resourceId: string;
+    timestamp: Date;
+    ipAddress?: string;
+    userAgent?: string;
+    reason?: string;
+}
+/**
+ * Log PHI access for HIPAA compliance
+ */
+export declare function logPHIAccess(log: Omit<PHIAccessLog, 'id' | 'timestamp'>, endpoint?: string): PHIAccessLog;
+/**
+ * Create HIPAA-compliant session manager
+ */
+export declare function createHIPAASession(config: {
+    timeoutMinutes: number;
+    onTimeout: () => void;
+    onWarning?: (remainingMs: number) => void;
+    warningBeforeMs?: number;
+}): {
+    resetTimer: () => void;
+    destroy: () => void;
+    getTimeRemaining: () => number;
+};
+export interface WCAGIssue {
+    id: string;
+    element: string;
+    level: 'A' | 'AA' | 'AAA';
+    guideline: string;
+    description: string;
+    suggestion: string;
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+}
+/**
+ * Check color contrast ratio
+ */
+export declare function checkColorContrast(foreground: string, background: string): {
+    ratio: number;
+    passesAA: boolean;
+    passesAAA: boolean;
+    passesAALarge: boolean;
+    passesAAALarge: boolean;
+};
+/**
+ * Check if element has accessible name
+ */
+export declare function hasAccessibleName(element: HTMLElement): boolean;
+/**
+ * Check heading hierarchy
+ */
+export declare function checkHeadingHierarchy(container?: HTMLElement): {
+    valid: boolean;
+    issues: {
+        level: number;
+        element: HTMLElement;
+        issue: string;
+    }[];
+};
+export interface AuditLogEntry {
+    id: string;
+    timestamp: Date;
+    userId: string;
+    action: string;
+    resource: string;
+    resourceId?: string;
+    details?: Record<string, unknown>;
+    ipAddress?: string;
+    userAgent?: string;
+    outcome: 'success' | 'failure' | 'error';
+    errorMessage?: string;
+}
+export interface AuditLogConfig {
+    /** API endpoint for sending logs */
+    endpoint: string;
+    /** Batch logs before sending */
+    batchSize?: number;
+    /** Flush interval in ms */
+    flushInterval?: number;
+    /** Include user agent */
+    includeUserAgent?: boolean;
+    /** Include IP (requires server-side) */
+    includeIP?: boolean;
+}
+/**
+ * Create audit logger
+ */
+export declare function createAuditLogger(config: AuditLogConfig): {
+    log: (entry: Omit<AuditLogEntry, "id" | "timestamp" | "userAgent">) => void;
+    flush: () => Promise<void>;
+    destroy: () => void;
+};
+export interface SOC2ControlStatus {
+    controlId: string;
+    name: string;
+    category: 'security' | 'availability' | 'processing_integrity' | 'confidentiality' | 'privacy';
+    status: 'compliant' | 'non_compliant' | 'not_applicable' | 'in_progress';
+    lastAssessed: Date;
+    evidence?: string[];
+    notes?: string;
+}
+/**
+ * Generate SOC 2 readiness checklist
+ */
+export declare function getSOC2Checklist(): SOC2ControlStatus[];

package/dist/components/NiceDeviceTrust.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+import { DeviceTrustScore } from '../core/types';
+export interface NiceDeviceTrustProps {
+    /** Pre-computed trust score. If omitted, computed client-side. */
+    trustScore?: DeviceTrustScore;
+    /** Called when a new score is computed. */
+    onScoreComputed?: (score: DeviceTrustScore) => void;
+    /** Minimum score threshold to be considered "trusted". Default: 60 */
+    trustThreshold?: number;
+    /** Show factor breakdown. Default: true */
+    showFactors?: boolean;
+    /** Show device fingerprint hash. Default: false */
+    showFingerprint?: boolean;
+    className?: string;
+    label?: string;
+}
+export declare const NiceDeviceTrust: React.FC<NiceDeviceTrustProps>;
+export default NiceDeviceTrust;

package/dist/components/NiceFaceRecognition.d.ts

@@ -0,0 +1,25 @@
+import { default as React } from 'react';
+import { BiometricConfig, BiometricTemplate, VerificationResult, FaceFeatures, SecurityVerificationStatus } from '../core/types';
+export interface NiceFaceRecognitionProps extends BiometricConfig {
+    mode: 'enroll' | 'verify' | 'compare';
+    enrolledTemplates?: BiometricTemplate[];
+    /** Reference photo for 'compare' mode (data URL or image element). */
+    referencePhoto?: string | HTMLImageElement;
+    onEnroll?: (template: BiometricTemplate, features: FaceFeatures) => void;
+    onVerify?: (result: VerificationResult) => void;
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    onError?: (error: Error) => void;
+    className?: string;
+    size?: 'sm' | 'md' | 'lg';
+    label?: string;
+    showQuality?: boolean;
+    /** Show detected face bounding box. Default: true */
+    showBoundingBox?: boolean;
+    /** Number of liveness challenges. Default: 1 */
+    livenessSteps?: number;
+    /** Show reference photo side by side in compare mode. Default: true */
+    showReference?: boolean;
+    instructionText?: string;
+}
+export declare const NiceFaceRecognition: React.FC<NiceFaceRecognitionProps>;
+export default NiceFaceRecognition;

package/dist/components/NiceFingerprintScanner.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+import { BiometricConfig, BiometricTemplate, VerificationResult, FingerprintFeatures, FingerPosition, SecurityVerificationStatus } from '../core/types';
+export interface NiceFingerprintScannerProps extends BiometricConfig {
+    /** 'enroll' to capture new template, 'verify' to match against enrolled. */
+    mode: 'enroll' | 'verify';
+    /** Previously enrolled templates to match against (verify mode). */
+    enrolledTemplates?: BiometricTemplate[];
+    /** Which finger to scan. */
+    fingerPosition?: FingerPosition;
+    /** Called with the new template after enrollment. */
+    onEnroll?: (template: BiometricTemplate, features: FingerprintFeatures) => void;
+    /** Called with the verification result. */
+    onVerify?: (result: VerificationResult) => void;
+    /** Called on status change. */
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    /** Called on any error. */
+    onError?: (error: Error) => void;
+    /** Custom CSS class. */
+    className?: string;
+    /** Size variant. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Label for the finger position. */
+    label?: string;
+    /** Show quality indicator. Default: true */
+    showQuality?: boolean;
+    /** Show minutiae overlay. Default: false */
+    showMinutiae?: boolean;
+    /** Instruction text override. */
+    instructionText?: string;
+    /** Camera facing mode. Default: 'environment' */
+    cameraFacing?: 'user' | 'environment';
+}
+export declare const NiceFingerprintScanner: React.FC<NiceFingerprintScannerProps>;
+export default NiceFingerprintScanner;

package/dist/components/NiceIrisScanner.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { BiometricConfig, BiometricTemplate, VerificationResult, IrisFeatures, EyePosition, SecurityVerificationStatus } from '../core/types';
+export interface NiceIrisScannerProps extends BiometricConfig {
+    mode: 'enroll' | 'verify';
+    enrolledTemplates?: BiometricTemplate[];
+    eye?: EyePosition;
+    onEnroll?: (template: BiometricTemplate, features: IrisFeatures) => void;
+    onVerify?: (result: VerificationResult) => void;
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    onError?: (error: Error) => void;
+    className?: string;
+    size?: 'sm' | 'md' | 'lg';
+    label?: string;
+    showQuality?: boolean;
+    /** Show iris segmentation overlay. Default: true */
+    showSegmentation?: boolean;
+    /** Show guide circle for eye alignment. Default: true */
+    showGuide?: boolean;
+    instructionText?: string;
+}
+export declare const NiceIrisScanner: React.FC<NiceIrisScannerProps>;
+export default NiceIrisScanner;

package/dist/components/NiceMfaSelector.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { BiometricMethod } from '../core/types';
+export interface MfaOption {
+    method: BiometricMethod;
+    label?: string;
+    description?: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+    /** If the method was already verified in current flow. */
+    verified?: boolean;
+}
+export interface NiceMfaSelectorProps {
+    options: MfaOption[];
+    /** Minimum number of methods that must be verified. Default: 1 */
+    requiredCount?: number;
+    onSelect?: (method: BiometricMethod) => void;
+    /** Called when the required number of methods have been verified. */
+    onComplete?: (verifiedMethods: BiometricMethod[]) => void;
+    className?: string;
+    label?: string;
+    layout?: 'grid' | 'list';
+}
+export declare const NiceMfaSelector: React.FC<NiceMfaSelectorProps>;
+export default NiceMfaSelector;

package/dist/components/NicePassphraseInput.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { SecurityVerificationStatus, VerificationResult } from '../core/types';
+export interface NicePassphraseInputProps {
+    mode?: 'set' | 'verify';
+    /** SHA-256 hex hash of expected passphrase for verification. */
+    expectedHash?: string;
+    /** Minimum strength (0-4) required for "set" mode. Default: 2 */
+    minStrength?: number;
+    /** Minimum character count. Default: 8 */
+    minLength?: number;
+    onComplete?: (passphrase: string) => void;
+    onVerify?: (result: VerificationResult) => void;
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    onError?: (error: Error) => void;
+    label?: string;
+    placeholder?: string;
+    className?: string;
+    showStrength?: boolean;
+    maxAttempts?: number;
+}
+export declare const NicePassphraseInput: React.FC<NicePassphraseInputProps>;
+export default NicePassphraseInput;

package/dist/components/NicePatternLock.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { PatternLockConfig, SecurityVerificationStatus, VerificationResult } from '../core/types';
+export interface NicePatternLockProps extends Partial<PatternLockConfig> {
+    mode?: 'set' | 'verify';
+    /** SHA-256 hex of the correct pattern sequence (e.g. "0,1,2,5,8"). */
+    expectedHash?: string;
+    /** Direct pattern string comparison (less secure). */
+    expectedPattern?: string;
+    onComplete?: (pattern: number[]) => void;
+    onVerify?: (result: VerificationResult) => void;
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    onError?: (error: Error) => void;
+    label?: string;
+    className?: string;
+    /** Canvas dimension in px. Default auto from gridSize. */
+    canvasSize?: number;
+}
+export declare const NicePatternLock: React.FC<NicePatternLockProps>;
+export default NicePatternLock;

package/dist/components/NicePinKeypad.d.ts

@@ -0,0 +1,20 @@
+import { default as React } from 'react';
+import { KeypadConfig, SecurityVerificationStatus, VerificationResult } from '../core/types';
+export interface NicePinKeypadProps extends Partial<KeypadConfig> {
+    /** Expected PIN hash to verify against (SHA-256 hex of the correct PIN). */
+    expectedHash?: string;
+    /** Direct PIN string comparison (frontend-only, less secure). */
+    expectedPin?: string;
+    mode?: 'set' | 'verify';
+    onComplete?: (pin: string) => void;
+    onVerify?: (result: VerificationResult) => void;
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    onError?: (error: Error) => void;
+    /** Show "Use biometrics" fallback button. */
+    showBiometricFallback?: boolean;
+    onBiometricFallback?: () => void;
+    label?: string;
+    className?: string;
+}
+export declare const NicePinKeypad: React.FC<NicePinKeypadProps>;
+export default NicePinKeypad;

package/dist/components/NiceSecurityAuditLog.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+import { SecurityAuditEntry, BiometricMethod } from '../core/types';
+export interface NiceSecurityAuditLogProps {
+    entries: SecurityAuditEntry[];
+    /** Max entries per page. Default 20. */
+    pageSize?: number;
+    /** Enable export button. Default true. */
+    showExport?: boolean;
+    /** Methods to show in filter dropdown. Default: all. */
+    filterMethods?: BiometricMethod[];
+    onEntryClick?: (entry: SecurityAuditEntry) => void;
+    className?: string;
+    label?: string;
+}
+export declare const NiceSecurityAuditLog: React.FC<NiceSecurityAuditLogProps>;
+export default NiceSecurityAuditLog;

package/dist/components/NiceSessionManager.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+export interface SessionInfo {
+    id: string;
+    device: string;
+    browser?: string;
+    os?: string;
+    ip?: string;
+    location?: string;
+    lastActive: number;
+    current?: boolean;
+    trusted?: boolean;
+}
+export interface NiceSessionManagerProps {
+    sessions: SessionInfo[];
+    onRevoke?: (sessionId: string) => void;
+    onRevokeAll?: () => void;
+    onTrust?: (sessionId: string, trusted: boolean) => void;
+    className?: string;
+    label?: string;
+    /** Show the "Revoke all other sessions" button. Default: true */
+    showRevokeAll?: boolean;
+}
+export declare const NiceSessionManager: React.FC<NiceSessionManagerProps>;
+export default NiceSessionManager;

package/dist/components/NiceWebAuthnButton.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { WebAuthnConfig, SecurityVerificationStatus, VerificationResult } from '../core/types';
+export interface NiceWebAuthnButtonProps extends Partial<WebAuthnConfig> {
+    mode: 'register' | 'authenticate';
+    /** Credential IDs for authentication (base64url strings). */
+    credentialIds?: string[];
+    /** Server-generated challenge (base64url). If omitted a random one is used. */
+    challenge?: string;
+    onRegister?: (credential: PublicKeyCredential) => void;
+    onAuthenticate?: (assertion: PublicKeyCredential) => void;
+    onVerify?: (result: VerificationResult) => void;
+    onStatusChange?: (status: SecurityVerificationStatus) => void;
+    onError?: (error: Error) => void;
+    label?: string;
+    className?: string;
+    variant?: 'primary' | 'outline' | 'ghost';
+    size?: 'sm' | 'md' | 'lg';
+    fullWidth?: boolean;
+    icon?: React.ReactNode;
+}
+export declare const NiceWebAuthnButton: React.FC<NiceWebAuthnButtonProps>;
+export default NiceWebAuthnButton;