@stratametriq/id-card-designer 1.16.0 → 1.17.0

package/README.md

@@ -2,7 +2,7 @@
 
 A universal, dynamic, and highly customizable **ID Card Designer & Batch Print Dashboard** for React, Vue, Angular, and Vanilla JS.
 
-> **Current release:** 1.15.0
+> **Current release:** 1.17.0
 
 ---
 
@@ -10,8 +10,13 @@ A universal, dynamic, and highly customizable **ID Card Designer & Batch Print D
 
 - [Overview](#overview)
 - [Live Demo](#live-demo)
+- [Pricing / License](#pricing--licensing-important)
+- [What's New in v1.17.0](#whats-new-in-v1170)
+- [What's New in v1.16.0](#whats-new-in-v1160)
 - [What's New in v1.15.0](#whats-new-in-v1150)
 - [Features](#features)
+- [Enterprise Roles & Permissions (RBAC)](#enterprise-roles--permissions-rbac)
+- [Enterprise Audit Logs & Access Trail](#enterprise-audit-logs--access-trail)
 - [ID Card Verification & Card Lifecycle](#id-card-verification--card-lifecycle)
 - [How It Works](#how-it-works)
 - [Import Data](#import-data)
@@ -22,7 +27,6 @@ A universal, dynamic, and highly customizable **ID Card Designer & Batch Print D
 - [Privacy](#privacy)
 - [Developer Docs](#developer-docs)
 - [NPM](#npm)
-- [Pricing / License](#pricing--license)
 - [FAQ](#faq)
 
 ---
@@ -39,7 +43,7 @@ It is designed for applications such as:
 - Membership systems
 - Internal identity-card workflows
 
-The package combines **visual card design** with **structured data, batch generation, card lifecycle management, and live digital verification** so developers do not need to build an ID-card production workflow from scratch.
+The package combines **visual card design** with **structured data, batch generation, card lifecycle management, enterprise role-based access control, and live digital verification** so developers do not need to build an ID-card production workflow from scratch.
 
 ---
 
@@ -72,7 +76,30 @@ Free for personal projects, students, open-source initiatives, and non-profit or
 
 ---
 
-## What's New in v1.15.0
+## What's New in v1.17.0
+- **👥 Enterprise Role-Based Access Control (RBAC):** Complete, modular RBAC architecture designed for institutional ERPs, healthcare portals, universities, and enterprise identity deployments.
+  - **15 Granular Permissions:** Structured across Card Templates (`templates:read`, `templates:write`, `templates:history`), Cardholder Rosters (`records:read`, `records:create`, `records:edit`, `records:delete`, `records:import`, `records:export`), Production & Issuance (`issuance:export`), Physical Security (`security:verify`, `security:revoke`), Organization & Branch Management (`org:manage`), and Compliance Audit Trails (`audit:view`, `audit:clear`).
+  - **6 Pre-Configured Personas:** Complete with avatars, departments, colors, and badge tokens:
+    - 🛡️ **Super Admin** (`Dr. Arthur Pendelton`): Full unrestricted authority across all features, settings, and purge actions.
+    - 🎨 **Template Designer** (`Maya Lin`): Visual canvas drafting, element styling, watermark management, and revision history. Rosters and batch printing are locked.
+    - 📋 **Data Registrar** (`Rahul Mehta`): Cardholder profiles, CSV/Excel/ZIP data imports, and webcam photo capture. Template layouts and record deletions are locked.
+    - 🖨️ **Issuance Officer** (`Carlos Mendez`): High-resolution 300 DPI batch PDF rendering and ZIP package downloads. Template layouts and record deletions are locked.
+    - 🔍 **Security Verifier** (`Officer David Briggs`): Physical gate checkpoint scanning, barcode validation, and credential lifecycle status management (`active`, `suspended`, `revoked`, `lost`).
+    - 📊 **Compliance Auditor** (`Evelyn Vance`): Read-only inspection of templates and rosters, paired with full access to inspect diffs and export audit trails. Log purging is permanently disabled.
+  - **100% Backward Compatibility:** If no user or role prop is provided, `<IdCardManager />` automatically defaults to full unrestricted mode (`super_admin`), ensuring zero breaking changes for existing library consumers.
+  - **Per-User Custom Overrides:** Supports `user.customPermissions` arrays to augment base role privileges without altering global role matrices.
+- **🛡️ Declarative Action Gating (`<PermissionGate />`):** Seamless conditional rendering, hiding, or disabled state rendering with custom security explanation tooltips (`disabledTooltip`).
+- **🎛️ Interactive Persona Simulator (`<RoleSwitcherModal />`):** Built-in modal featuring an interactive Permission Matrix Inspector organized across Templates, Rosters, Issuance/Security, and Audit Logs for 1-click persona switching in demo and QA environments.
+- **🔒 Read-Only Template Inspector Mode (`<IdCardDesignerModal />`):** When users possess `templates:read` but lack `templates:write`, the designer launches in read-only mode with visual warnings, locking canvas edits and template saves.
+- **🚨 Non-Repudiation Security Audit Trails:** Every authorization denial automatically logs an `ACCESS_DENIED` event under `AUDIT_CATEGORIES.SECURITY` with actor identity and required permissions.
+
+## What's New in v1.16.0
+- **📜 Enterprise Audit Logs & Access Trail System (`<AuditLogModal />`):**
+  - Enterprise audit trail cockpit equipped with KPI metrics counters (Total Events, Issuance / Prints, Record Modifications, Security Flags).
+  - Multi-dimensional filtering across full-text search, action categories (`issuance`, `record`, `template`, `security`, `organization`), severity levels (`info`, `warning`, `critical`), and departments.
+  - Interactive timeline cards featuring expandable visual **Before vs. After Field Diffs** with syntax-highlighted values and a collapsible Raw JSON inspector for technical compliance auditors.
+  - One-click **Export CSV** generating an official audit certificate spreadsheet formatted with UTF-8 BOM encoding for Microsoft Excel.
+  - Offline-first IndexedDB persistence paired with an `onAuditLog` callback prop for real-time synchronization with enterprise SIEM and database backends (Node.js, Laravel, Supabase, Postgres).
 - **⚡ Massive Bundle Size Reduction (75%+ Smaller):** Implemented aggressive code-splitting and dynamic `import()` across all heavy modules (`jspdf`, `exceljs`, `jszip`, `html2canvas`, `@imgly/background-removal`, `canvas-confetti`). The core bundle footprint shrank from ~3.35MB to ~785KB, drastically speeding up initial page load and rendering in host apps.
 - **🔒 Zero-Vulnerability Security Architecture:** Fully eliminated the deprecated `xlsx` library, resolving all high/critical prototype pollution and ReDoS CVEs. Standardized on secure, lightweight `exceljs` and `papaparse`.
 - **📑 Clean Template Generation & Smart Import Mapping:** Fixed duplicate and repetitive column headers in generated Excel/CSV templates. Intelligent synonym normalization prevents redundant columns (e.g., `Class`, `classSec`, `Phone`, `Phone_no`) and automatically binds incoming data seamlessly.
@@ -111,12 +138,238 @@ Free for personal projects, students, open-source initiatives, and non-profit or
 - **🧠 Conditional Rendering:** Text elements can use JavaScript expressions for conditional output (e.g., `{{ department === 'HR' ? 'Red' : 'Blue' }}`).
 - **🛡️ Digital ID Card Verification:** Built-in `<IdCardVerificationModal />` with real-time status banners, anti-tampering photo match, HTML5 camera scanner, and public verification URLs.
 - **🔄 Full Card Lifecycle Management:** Complete state machine tracking (`Active`, `Issued`, `Draft`, `Suspended`, `Revoked`, `Lost`), interactive table status pills, batch status transitions, and automatic issuance logging on print.
+- **👥 Enterprise Role-Based Access Control (RBAC):** Built-in 15 granular permissions across templates, rosters, batch printing, security, organization, and compliance. Pre-configured with 6 operator roles (`Super Admin`, `Template Designer`, `Data Registrar`, `Issuance Officer`, `Security Verifier`, `Compliance Auditor`), declarative `<PermissionGate />`, and interactive `<RoleSwitcherModal />`.
+- **📜 Enterprise Audit Trail & SIEM Integration:** Built-in `<AuditLogModal />` featuring real-time event recording, before-and-after field diffs, Excel UTF-8 BOM CSV export, non-repudiation actor tracking, and an `onAuditLog` callback for external SIEM / database synchronization.
 - **🛡️ Brand & Security Watermark Suite:** Add customizable text watermarks (`STRATAMETRIQ`, `CONFIDENTIAL`, `SAMPLE`), uploaded brand seal logos, and repeating security tile patterns with live opacity, rotation, and layer controls.
 - **🔲 Smart Alignment Guides:** Snap elements to the center of the card or align them with other elements using visual color-coded guides (Purple for center, Red for edges).
 - **⌨️ Keyboard Shortcuts:** Navigate the editor faster using Undo/Redo (`Ctrl+Z`, `Ctrl+Y`), Duplicate (`Ctrl+C`, `Ctrl+V`), Delete, and Arrow Key nudging.
 
 ---
 
+## Enterprise Roles & Permissions (RBAC)
+
+Modern universities, hospitals, corporate security departments, and government facilities enforce **Segregation of Duties (SoD)**:
+- **Card Designers** should only style badge layouts and watermarks, not access confidential student/patient rosters.
+- **Data Registrars** should enter student or employee profiles, but cannot alter card dimensions or delete historical records.
+- **Print Officers** should execute high-resolution batch PDF printing, but cannot change data or templates.
+- **Security Officers** at turnstiles require verification scanner tools, but should not be allowed to purge audit histories.
+- **Compliance Auditors** require read-only access with before/after diff inspection, but zero modification authority.
+
+`@stratametriq/id-card-designer` provides an **enterprise-grade RBAC engine** out of the box with zero additional configuration required.
+
+### 1. Granular Permission Matrix (15 Permissions)
+
+| Category | Permission Key | Description |
+| :--- | :--- | :--- |
+| **Templates** | `templates:read` | View and inspect card design templates |
+| | `templates:write` | Create, modify, and save card designs and element styles |
+| | `templates:history` | Restore or delete previous template version snapshots |
+| **Rosters** | `records:read` | View the cardholder directory and record details |
+| | `records:create` | Add new cardholder records manually or via webcam |
+| | `records:edit` | Update existing cardholder profile data or photos |
+| | `records:delete` | Delete individual cardholder records or perform bulk deletion |
+| | `records:import` | Upload bulk spreadsheets (`.xlsx`, `.csv`) and photo ZIP archives |
+| | `records:export` | Export directory rosters to formatted Excel or CSV files |
+| **Issuance** | `issuance:export` | Generate 300 DPI batch print PDFs and high-res ZIP archives |
+| **Security** | `security:verify` | Access gate verification scanner and optical barcode validation |
+| | `security:revoke` | Alter credential lifecycle status (`Active`, `Suspended`, `Revoked`, `Lost`) |
+| **Organization** | `org:manage` | Manage institutional assets, brand logos, signatories, and branches |
+| **Audit Trails** | `audit:view` | Inspect compliance event history, diff timelines, and export audit CSV |
+| | `audit:clear` | Purge audit history logs (restricted to Super Administrators) |
+
+### 2. Standard Pre-Configured Personas
+
+| Persona Role | Key Operator Persona | Badge | Authorized Capabilities |
+| :--- | :--- | :--- | :--- |
+| `super_admin` | Dr. Arthur Pendelton | 🛡️ `Super Admin` | Unrestricted authority across all features, settings, and purge actions. |
+| `template_designer` | Maya Lin | 🎨 `Designer` | Template drafting, element styling, watermarks, version history. Rosters locked. |
+| `data_registrar` | Rahul Mehta | 📋 `Registrar` | Cardholder data entry, CSV/Excel/ZIP bulk imports, webcam capture. Templates locked. |
+| `issuance_officer` | Carlos Mendez | 🖨️ `Production` | Batch 300 DPI PDF rendering, single card print, ZIP archive generation. |
+| `security_verifier` | Officer David Briggs | 🔍 `Verifier` | Gate checkpoint scanning, barcode lookups, credential status changes (`revoked`, `lost`). |
+| `compliance_auditor` | Evelyn Vance | 📊 `Auditor` | Read-only inspection of templates, rosters, and audit diff timelines. Purging locked. |
+
+### 3. Usage with `<IdCardManager />`
+
+```jsx
+import React, { useState } from 'react';
+import { IdCardManager, ROLES, DEFAULT_DEMO_USERS } from '@stratametriq/id-card-designer';
+import '@stratametriq/id-card-designer/dist/index.css';
+
+export default function EnterpriseCardPortal() {
+  // Pass active authenticated operator from your backend or state manager
+  const [operator, setOperator] = useState({
+    id: 'usr-corp-991',
+    name: 'Carlos Mendez',
+    email: 'carlos.mendez@enterprise.com',
+    role: ROLES.ISSUANCE_OFFICER,
+    title: 'Print Bureau Officer',
+    avatar: 'https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=100'
+  });
+
+  return (
+    <IdCardManager
+      currentUser={operator}
+      onRoleChange={(newOperator) => {
+        console.log('Operator switched:', newOperator);
+        setOperator(newOperator);
+      }}
+      onPermissionDenied={(actionName, requiredPermission) => {
+        console.warn(`Denied: ${actionName} requires ${requiredPermission}`);
+      }}
+      showRoleSwitcher={true} // Shows Persona Switcher pill in header (ideal for QA & staging)
+    />
+  );
+}
+```
+
+> [!NOTE]
+> **100% Backward Compatible:** If `currentUser` is omitted, `<IdCardManager />` automatically runs in unrestricted Super Admin mode. Existing implementations will experience zero disruptions.
+
+### 4. Declarative Component Gating with `<PermissionGate />`
+
+Protect your own custom application buttons, sections, or actions using `<PermissionGate />`:
+
+```jsx
+import { PermissionGate, PERMISSIONS } from '@stratametriq/id-card-designer';
+
+function AdminToolbar({ activeUser, onBatchPrint, onClearData }) {
+  return (
+    <div className="toolbar">
+      {/* Conditionally rendered only if user can generate print batches */}
+      <PermissionGate user={activeUser} permission={PERMISSIONS.ISSUANCE_EXPORT}>
+        <button onClick={onBatchPrint}>
+          🖨️ Batch Export A4 PDF
+        </button>
+      </PermissionGate>
+
+      {/* Rendered as disabled with security tooltip explaining why it is locked */}
+      <PermissionGate
+        user={activeUser}
+        permission={PERMISSIONS.RECORDS_DELETE}
+        showDisabled={true}
+        disabledTooltip="Restricted: Only Administrators can purge roster records."
+      >
+        <button onClick={onClearData} className="btn-danger">
+          🗑️ Delete All Records
+        </button>
+      </PermissionGate>
+    </div>
+  );
+}
+```
+
+### 5. Programmatic Permission Helpers
+
+Check permissions directly within your event handlers or routing logic:
+
+```javascript
+import { hasPermission, canAny, canAll, PERMISSIONS } from '@stratametriq/id-card-designer';
+
+// Single permission check
+if (hasPermission(currentUser, PERMISSIONS.TEMPLATES_WRITE)) {
+  console.log('User can edit design layouts');
+}
+
+// Any matching permission (OR logic)
+if (canAny(currentUser, [PERMISSIONS.RECORDS_CREATE, PERMISSIONS.RECORDS_IMPORT])) {
+  console.log('User can add cardholders');
+}
+
+// All matching permissions (AND logic)
+if (canAll(currentUser, [PERMISSIONS.TEMPLATES_WRITE, PERMISSIONS.ORG_MANAGE])) {
+  console.log('User has full branding and template authority');
+}
+```
+
+### 6. Interactive Persona Simulator (`<RoleSwitcherModal />`)
+
+Test permissions in development and staging environments using the built-in modal:
+
+```jsx
+import React, { useState } from 'react';
+import { RoleSwitcherModal, DEFAULT_DEMO_USERS } from '@stratametriq/id-card-designer';
+
+function DevSandbox() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeUser, setActiveUser] = useState(DEFAULT_DEMO_USERS[0]);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>
+        🎭 Switch Operator Role ({activeUser.role})
+      </button>
+
+      <RoleSwitcherModal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        currentUser={activeUser}
+        onSelectUser={(newUser) => setActiveUser(newUser)}
+        theme="dark"
+      />
+    </>
+  );
+}
+```
+
+---
+
+## Enterprise Audit Logs & Access Trail
+
+Every action taken inside the ID card studio is recorded into an **immutable, traceable audit log** with full non-repudiation:
+- **Batch Issuance Runs**: Tracks number of cards printed, orientation, sheet configuration, and time.
+- **Record Modifications**: Captures granular **Before-vs-After Diffs** highlighting exact changed field values.
+- **Template Layouts**: Logs template saves and version restoration timestamps.
+- **Physical Security & Gate Checks**: Records badge verification events, QR scans, and credential revocations.
+- **Security Denials**: Automatically audits unauthorized access attempts (`ACCESS_DENIED`) with actor credentials.
+
+### Synchronizing Audit Events to Backend / SIEM
+
+Use the `onAuditLog` prop to pipe live audit telemetry into your database (PostgreSQL, Supabase, MySQL) or SIEM log aggregator (Datadog, Splunk):
+
+```jsx
+<IdCardManager
+  onAuditLog={(auditEntry) => {
+    // Send to your backend API
+    fetch('/api/v1/compliance/audit-logs', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(auditEntry)
+    });
+  }}
+/>
+```
+
+```json
+{
+  "id": "aud-1726485921-9921",
+  "timestamp": "2026-09-16T11:25:21.000Z",
+  "action": "RECORD_UPDATED",
+  "category": "record",
+  "severity": "info",
+  "actor": {
+    "id": "usr-reg-03",
+    "name": "Rahul Mehta",
+    "role": "data_registrar",
+    "title": "Admissions Officer",
+    "email": "r.mehta@admissions.edu"
+  },
+  "details": {
+    "summary": "Updated cardholder profile for Rahul Sharma",
+    "recordId": "ADM-2026-104",
+    "diff": [
+      {
+        "field": "classSec",
+        "label": "Class & Section",
+        "before": "Class IX [B]",
+        "after": "Class X [A]"
+      }
+    ]
+  }
+}
+```
+
+---
+
 ## ID Card Verification & Card Lifecycle
 
 ### 1. Card Lifecycle State Machine
@@ -329,21 +582,87 @@ Your application remains responsible for compliance with applicable privacy and
 ## Developer Docs
 
 ### Components
-- `<IdCardManager />`: Complete dashboard experience. Use this when you want the complete import → design → preview → batch-export workflow.
-- `<IdCardDesigner />`: Standalone visual designer.
+- `<IdCardManager />`: Complete dashboard experience. Use this when you want the complete import → design → preview → batch-export workflow with RBAC safeguards and audit trails.
+- `<IdCardDesignerModal />`: Open the drag-and-drop designer modal (supports `readOnly` inspector mode for non-designer roles).
 - `<IdCardPreview />`: Embed a live ID-card preview inside another application screen.
-- `<IdCardDesignerModal />`: Open the designer inside your application's modal/dialog workflow.
-
-### Props (IdCardManager)
+- `<IdCardCanvas />`: Core vector canvas supporting element selection, drag, resize, and zoom.
+- `<ElementPropertyEditor />`: Property inspector for text styling, barcode configurations, colors, and watermarks.
+- `<PresetsSidebar />`: Template preset browser and gallery.
+- `<WatermarkLayer />`: Security and brand watermark overlay engine.
+- `<IdCardVerificationModal />`: Turnkey credential verification screen with HTML5 camera QR scanner and anti-tampering photo match.
+- `<AuditLogModal />`: Full enterprise compliance cockpit with KPI counters, event filters, diff timelines, and Excel CSV export.
+- `<PermissionGate />`: Declarative permission barrier component (`showDisabled`, `disabledTooltip`, fallback).
+- `<RoleSwitcherModal />`: Interactive persona simulator and permission matrix inspector for testing.
+
+### Props (`<IdCardManager />`)
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `sampleRecords` | `object` | Default data | Records used to populate the dashboard |
-| `categories` | `object` | Default config | Custom ID-card categories |
-| `onBatchExportComplete` | `function` | `undefined` | Callback after batch PDF generation |
+| `sampleRecords` | `object` | Default data | Records used to populate the dashboard (`{ student: [], employee: [], ... }`) |
+| `categories` | `object` | Default config | Custom ID-card categories and field definitions |
+| `onBatchExportComplete` | `function` | `undefined` | Callback `(category, records) => void` after batch PDF generation |
 | `organization` | `object` | `DEFAULT_ORGANIZATION` | Institution profile (Name, Code, Logo, Signatory, Signature, Verification Base URL) |
-| `onSaveOrganization` | `function` | `undefined` | Callback when organization profile or brand assets are updated |
+| `onSaveOrganization` | `function` | `undefined` | Callback `(orgData) => void` when organization profile or brand assets are updated |
 | `workspaces` | `array` | `DEFAULT_WORKSPACES` | List of branch workspaces/campuses (`[{ id, name, code, location }]`) |
-| `onSwitchWorkspace` | `function` | `undefined` | Callback when active branch workspace changes |
+| `onSwitchWorkspace` | `function` | `undefined` | Callback `(workspace) => void` when active branch workspace changes |
+| `currentUser` | `object` | `null` | Active operator persona (`{ id, name, role, title, email, avatar, customPermissions }`). Defaults to full unrestricted access (`super_admin`) |
+| `onRoleChange` | `function` | `undefined` | Callback `(newUser) => void` triggered when operator persona changes |
+| `onPermissionDenied` | `function` | `undefined` | Callback `(actionName, permission) => void` triggered when an unauthorized action is attempted |
+| `showRoleSwitcher` | `boolean` | `true` | Toggle display of the header operator persona switcher pill / modal |
+| `initialAuditLogs` | `array` | `null` | Array of historical audit entries to populate `<AuditLogModal />` |
+| `onAuditLog` | `function` | `undefined` | Callback `(auditEntry) => void` fired whenever an auditable action occurs (ideal for SIEM / database sync) |
+
+### Public Package Exports
+
+```javascript
+// Components
+import {
+  IdCardManager,
+  IdCardDesignerModal,
+  IdCardPreview,
+  IdCardCanvas,
+  ElementPropertyEditor,
+  PresetsSidebar,
+  WatermarkLayer,
+  IdCardVerificationModal,
+  AuditLogModal,
+  PermissionGate,
+  RoleSwitcherModal
+} from '@stratametriq/id-card-designer';
+
+// PDF & Print Utilities
+import { generateIdCardsPdf } from '@stratametriq/id-card-designer';
+
+// Enterprise RBAC Helpers & Constants
+import {
+  hasPermission,
+  canAny,
+  canAll,
+  getRoleDefinition,
+  PERMISSIONS,
+  ROLES,
+  ROLE_DEFINITIONS,
+  DEFAULT_DEMO_USERS
+} from '@stratametriq/id-card-designer';
+
+// Enterprise Audit Logging Utilities & Constants
+import {
+  createAuditEntry,
+  calculateRecordDiff,
+  exportAuditLogsToCsv,
+  SEED_AUDIT_LOGS,
+  AUDIT_CATEGORIES,
+  AUDIT_SEVERITIES
+} from '@stratametriq/id-card-designer';
+
+// Starter Presets & Utilities
+import {
+  VERTICAL_PRESETS,
+  HORIZONTAL_PRESETS,
+  ALL_PRESETS,
+  getDefaultPreset,
+  getPresetsByOrientation
+} from '@stratametriq/id-card-designer';
+```
 
 ### Templates
 Designs are represented as JSON-compatible template structures.