@bdking71/spsignature 1.0.5 → 1.2.0

package/README.md

@@ -1,84 +1,148 @@
 # @bdking71/spsignature
-# NOT READY FOR PRODUCTION USE! Please do not use at this time. #
-@bdking71/spsignature provides a secure, lightweight, and framework-agnostic digital signature module engineered specifically for Microsoft 365 environments. Built to run inside custom SPFx Web Parts and Extension Application Customizers, it delivers tamper-evident signature collection, automated base64 image encoding, and structured payload generation directly integrated with SharePoint Online list infrastructure.
 
-Key Capabilities & Business Value
+[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/bdking71/spsignature)
+[![npm version](https://img.shields.io/npm/v/@bdking71/spsignature.svg)](https://www.npmjs.com/package/@bdking71/spsignature)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-- Zero Infrastructure Overhead: Operates entirely within client-side M365 contexts—no external APIs, azure functions, or third-party storage backends required.
+> ⚠️ **NOT READY FOR PRODUCTION USE!** This module is currently under active development. Please do not use it in production environments at this time.
 
-- Cross-Platform M365 Integration: Designed for seamless deployment across SharePoint Online, Microsoft Teams, and Viva Connections desktop/mobile experiences.
+`@bdking71/spsignature` provides a secure, lightweight, and framework-agnostic digital signature module engineered specifically for Microsoft 365 environments. Built to run inside custom SPFx Web Parts and Extension Application Customizers, it delivers tamper-evident signature collection, automated base64 image encoding, and structured payload generation directly integrated with SharePoint Online list infrastructure.
 
-- Integrity & Non-Repudiation: Generates cryptographic SHA-256 hashes bound to user identities, timestamps, and target record IDs to prevent signature tampering.
+---
 
-- Standardized JSON Payload: Encapsulates complete signing metadata inside standard SharePoint Multiline Text columns (Plain Text / JSON formatted) for effortless integration with Power Automate and Power BI.
+## Source Code & Repository
 
-## Two-Factor Authentication (2FA / TFA) Architecture
+* **GitHub Repository:** [https://github.com/bdking71/spsignature](https://github.com/bdking71/spsignature)
+* **Issues & Feedback:** [https://github.com/bdking71/spsignature/issues](https://github.com/bdking71/spsignature/issues)
+* **NPM Package:** [@bdking71/spsignature](https://www.npmjs.com/package/@bdking71/spsignature)
 
-To enforce non-repudiation and meet compliance standards, @bdking71/spsignature includes a flexible Two-Factor Authentication engine. Rather than relying on rigid third-party SMS gateways, it delegates code delivery to Power Automate, allowing organizations to route standard 6-digit verification codes via Microsoft Teams, Outlook Email, or both.
+---
 
-![Diagram illustrating the 2FA workflow between SPFx, SharePoint, and Power Automate](./img/tfa.jpg)
+## Key Capabilities & Business Value
+
+- **Zero Infrastructure Overhead**: Operates entirely within client-side M365 contexts — no external APIs, Azure Functions, or third-party storage backends required.
+- **Cross-Platform M365 Integration**: Designed for seamless deployment across SharePoint Online, Microsoft Teams, and Viva Connections desktop/mobile experiences.
+- **Integrity & Non-Repudiation**: Generates cryptographic SHA-256 hashes bound to user identities, timestamps, and target record IDs to prevent signature tampering.
+- **Standardized JSON Payload**: Encapsulates complete signing metadata inside standard SharePoint Multiline Text columns (Plain Text / JSON formatted) for effortless integration with Power Automate and Power BI.
+- **LZW Compression**: Automatically compresses signature image payloads to minimize SharePoint storage footprint.
+- **Signature Caching**: Optional local device caching so users don't have to re-draw their signature on every transaction.
+
+---
 
-## How The 2FA Workflow Operates-
-- Code Generation: When a user initiates a signing transaction, the component generates a cryptographically secure, time-sensitive verification code (e.g., 849204) and registers a pending transaction state.
+## Two-Factor Authentication (2FA) Architecture
 
-- Power Automate Trigger: The component triggers a light HTTP webhook or writes a record to a dedicated SharePoint verification list.
+To enforce non-repudiation and meet compliance standards, `@bdking71/spsignature` includes a flexible Two-Factor Authentication engine. Rather than relying on rigid third-party SMS gateways, it delegates code delivery to **Power Automate**, allowing organizations to route standard **5-digit** verification codes via Microsoft Teams, Outlook Email, or both.
 
-- Multi-Channel Delivery: The Power Automate flow instantly dispatches the code to the signer via:
+![Diagram illustrating the 2FA workflow between SPFx, SharePoint, and Power Automate](./img/tfa.jpg)
 
-- Microsoft Teams: Direct Adaptive Card or Activity Feed notification.
+### How the 2FA Workflow Operates
 
-- Outlook Email: High-priority internal notification.
+1. **Code Generation**: When a user initiates a signing transaction, the component generates a cryptographically secure 5-digit verification code (e.g., `84920`) using the Web Crypto API.
+2. **SharePoint Queue**: The component writes a record to the dedicated `PendingVerifications` SharePoint list, secured with item-level permissions so users can only see their own codes.
+3. **Power Automate Trigger**: A Power Automate flow monitors the list and instantly dispatches the code to the signer via:
+   - **Microsoft Teams**: Direct Adaptive Card or Activity Feed notification.
+   - **Outlook Email**: High-priority internal notification.
+4. **Validation & Signing**: The signer enters the 5-digit code into the `@bdking71/spsignature` UI component. Upon successful validation, the final signed JSON payload is generated and stored in the target record.
 
-- Validation & Signing: The signer enters the 6-digit code into the @bdking71/spsignature UI component. Upon successful validation, the final signed JSON payload is generated and stored in the target record.
+---
 
 ## Signature Data Schema
 
-The module returns a single, structured JSON object designed to be stored directly inside a SharePoint Multiple lines of text field (Plain Text format):
+The module returns a single, structured JSON object designed to be stored directly inside a SharePoint **Multiple lines of text** field (Plain Text format):
 
-```JSON
+```json
 {
-  "signatureHash": "e3b0c4429 ...",
-  "signatureData": "data:image/png;base64,iVB....",
+  "signatureHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "signatureData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
   "signatureTimestamp": "2026-08-31T19:55:06.121Z",
-  "verificationItemId": 1
+  "verificationItemId": 42
 }
 ```
 
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `signatureHash` | `string` | SHA-256 hex digest of the canonical audit envelope (payload + signer + timestamp). |
+| `signatureData` | `string` | LZW-compressed data-URI of the signature image (PNG). |
+| `signatureTimestamp` | `string` | ISO-8601 timestamp captured at the moment of signing. |
+| `verificationItemId` | `number` | ID of the corresponding record in the `PendingVerifications` list. |
+
+---
 
 ## Toolchain & Compatibility Matrix
 
 This project requires a precise local environment build. Strict adherence to the versioning matrix is mandatory to prevent toolchain compilation errors.
 
-* **SPFx Version:** `v1.22.1`
-* **Node.js:** `v18.17.1` (Recommended use of `nvm` or `nvs`)
-* **Gulp CLI:** `v4.x`
-* **Primary UI Framework:** React `v17.0.1` / Fluent UI `v8.x`
+| Component | Version |
+| :--- | :--- |
+| **SPFx** | `v1.22.1` |
+| **Node.js** | `v18.17.1` (Recommended use of `nvm` or `nvs`) |
+| **Gulp CLI** | `v4.x` |
+| **React** | `v17.0.1` |
+| **Fluent UI** | `v8.x` |
+| **TypeScript** | `v4.7+` |
+
+---
 
-## Quick Start & Local Development
+## Installation
 
-Execute these commands in sequence to establish your local development runtime:
+Install the package into your SPFx solution:
+
+```bash
+npm install @bdking71/spsignature --save
+```
+
+### Peer Dependencies
+
+Ensure the following peer dependencies are installed in your SPFx project:
+
+```bash
+npm install @pnp/sp @microsoft/sp-webpart-base --save
+```
+
+---
 
 ## Integration & Usage Guide
 
-### Provision Infrastructure
-Call `ensurePendingVerificationsList` during the WebPart lifecycle (e.g., inside `onInit()`) to automatically ensure the required `PendingVerifications` SharePoint list and columns exist on the site collection[cite: 2].
+### Step 1: Provision SharePoint Infrastructure
+
+Call `ensurePendingVerificationsList` during the web part lifecycle (inside `onInit()`) to automatically ensure the `PendingVerifications` SharePoint list, columns, and item-level security settings exist on the current site collection.
+
+> **Note:** This method is fully **idempotent**—it can be safely called on every web part load without failing or duplicating columns.
 
 ```typescript
 import { ensurePendingVerificationsList } from "@bdking71/spsignature";
 
-public async onInit(): Promise<void> {
-  await super.onInit();
+export default class MySignatureWebPart extends BaseClientSideWebPart<IMySignatureWebPartProps> {
+
+  public async onInit(): Promise<void> {
+    await super.onInit();
 
-  // Ensures 'PendingVerifications' list with 'Passcode' and 'Channel' fields exists
-  await ensurePendingVerificationsList({ context: this.context });
+    // Provisions the 'PendingVerifications' list with 'Passcode' and 'Channel' columns
+    await ensurePendingVerificationsList({ context: this.context });
+  }
 }
 ```
 
-### Launch Signature Modal & Capture Audit
+### Step 2: Configure Your Power Automate Flow
+
+Create a Power Automate flow that triggers on **"When an item is created"** for the `PendingVerifications` list. The flow should:
+
+1. Read the `Title` (signer email), `Passcode`, and `Channel` columns.
+2. Route notification based on the `Channel` value:
+   - `"email"` → Send an Outlook email with the passcode.
+   - `"teams"` → Post an Adaptive Card to the user in Microsoft Teams.
+   - `"both"` → Dispatch through both channels simultaneously.
+3. Optionally delete the item after dispatch (or use a scheduled cleanup flow to purge expired codes).
 
-Execute promptAndGenerateSecureAudit within your component or event handler. This renders an enterprise modal overlay that handles draw, upload, or cached signature selection, triggers 2FA code delivery, validates the 5-digit passcode, and outputs a cryptographic audit payload.
+### Step 3: Launch Signature Modal & Capture Audit
 
-```TypeScript
+Execute `promptAndGenerateSecureAudit` within your component or event handler. This renders an enterprise modal overlay that:
+- Handles drawn, uploaded, or cached signature selection.
+- Triggers 2FA code delivery through the configured channel.
+- Validates the 5-digit passcode.
+- Outputs a cryptographic audit payload.
+
+```typescript
 import {
   promptAndGenerateSecureAudit,
   SharePointAuditRecord
@@ -108,11 +172,18 @@ private handleSignAction = async (): Promise<void> => {
     console.log("Compressed Image Data:", auditRecord.signatureData);
     console.log("Timestamp:", auditRecord.signatureTimestamp);
     console.log("Verification Log ID:", auditRecord.verificationItemId);
+
+    // Example: Persist to a SharePoint list column named "SignatureAudit"
+    await sp.web.lists.getByTitle("Requisitions").items.getById(1042).update({
+      SignatureAudit: JSON.stringify(auditRecord)
+    });
+  } else {
+    console.log("User cancelled the signature workflow.");
   }
 };
 ```
 
-### Verification & Image Reconstruction
+### Step 4: Verification & Image Reconstruction
 
 To verify non-repudiation or render the stored LZW-compressed signature image back into a view or report, use the built-in helper utilities.
 
@@ -124,22 +195,88 @@ import {
 
 // 1. Re-calculate SHA-256 hash to verify record integrity
 const isValid: boolean = await verifySecureAuditRecord(
-  payload,
-  signerEmail,
-  timestamp,
-  compressedSignatureData,
-  storedHash
+  payload,                  // Original payload object
+  signerEmail,              // Signer's email address
+  timestamp,                // ISO-8601 timestamp from the audit record
+  compressedSignatureData,  // Retained for API symmetry
+  storedHash                // The stored signatureHash to compare against
 );
 
+if (isValid) {
+  console.log("✓ Signature is authentic and untampered.");
+} else {
+  console.warn("✗ Signature verification failed - record may be tampered.");
+}
+
 // 2. Decompress LZW signature string into a standard PNG base64 Data-URI
 const renderableImageSrc: string = getReportableSignature(compressedSignatureData);
+
+// Use directly in an <img> tag:
+// <img src={renderableImageSrc} alt="Signature" />
 ```
 
-# License
+---
+
+## API Reference
+
+### Exported Functions
+
+| Function | Purpose |
+| :--- | :--- |
+| `ensurePendingVerificationsList(props)` | Idempotently provisions the `PendingVerifications` SharePoint list, its required columns, and item-level security. |
+| `promptAndGenerateSecureAudit(context, title?, msg?)` | Launches the signature modal, dispatches the OTP, validates entry, and returns a `SharePointAuditRecord`. |
+| `verifySecureAuditRecord(payload, signer, timestamp, sigData, hash)` | Re-computes the SHA-256 hash to verify audit-record integrity. |
+| `getReportableSignature(compressedSignatureData)` | Decompresses an LZW-compressed signature back into a viewable `data:image/png` URI. |
+
+### Exported Types
+
+| Type | Description |
+| :--- | :--- |
+| `SharePointAuditRecord` | Structured JSON audit payload returned after successful signing. |
+| `SignerContext` | Input parameters for the signature workflow. |
+| `AuditEnvelopeRecord` | Canonical envelope structure used for hashing (payload + signer + timestamp). |
+| `DeliveryChannel` | `"email" \| "teams" \| "both"` — Supported OTP delivery channels. |
+
+---
+
+## Security Considerations
+
+- **Client-Side Passcode Generation**: The 5-digit OTP is generated and validated in the browser using the Web Crypto API. This is well-suited for **enterprise workflow enforcement** (approvals, sign-offs, SOP compliance) but is not intended to replace hardened server-side MFA solutions for high-risk financial transactions.
+- **Item-Level Security**: The `PendingVerifications` list is automatically configured with `ReadSecurity = 2` and `WriteSecurity = 2`, meaning users can only view and edit records they created. This prevents users from inspecting other users' active passcodes.
+- **SHA-256 Non-Repudiation**: The signature hash binds the payload, signer identity, and timestamp together. Any modification to the stored record can be detected through `verifySecureAuditRecord()`.
+- **Signature Caching**: Cached signatures are stored in browser `localStorage` after LZW compression. Consumers should clearly communicate this caching behavior to end users to meet compliance and privacy requirements (GDPR, CCPA, etc.).
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+| :--- | :--- |
+| Modal never appears | Ensure `spContext` is a valid `WebPartContext` and the DOM is fully loaded. |
+| OTP never arrives | Verify the Power Automate flow is active and listening on the correct list. Check the flow run history. |
+| "Field name already exists" | This shouldn't happen due to idempotency, but ensure you're on the latest version of the module. |
+| SHA-256 verification fails on nested objects | Note: Only top-level payload keys are sorted. Deeply nested objects should have consistent key ordering. |
+| Signature not caching | Verify browser `localStorage` isn't in private/incognito mode or blocked by browser policy. |
+
+---
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+1. Fork the Project: [https://github.com/bdking71/spsignature](https://github.com/bdking71/spsignature)
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
+
+## License
 
 MIT License
 
-Copyright (C) 2012 Veselin Todorov
+Copyright (c) 2025 bdking71
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/lib/OtpService.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file OtpService.ts
+ * Provides methods for dispatching One-Time Passcodes (OTP) for
+ * Two-Factor Authentication via SharePoint and external channels.
+ */
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/items";
+import { WebPartContext } from "@microsoft/sp-webpart-base";
+export type DeliveryChannel = "email" | "teams" | "both";
+export interface IOtpDispatchRequest {
+    title: string;
+    passcode: string;
+    channel: DeliveryChannel;
+}
+export interface IOtpDispatchResult {
+    success: boolean;
+    itemId?: number;
+    error?: string;
+}
+/**
+ * Queues an OTP dispatch request in SharePoint to notify the user via Email/Teams.
+ */
+export declare function dispatchOtpPasscode(context: WebPartContext, request: IOtpDispatchRequest, listTitle?: string): Promise<IOtpDispatchResult>;

package/lib/OtpService.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * @file OtpService.ts
+ * Provides methods for dispatching One-Time Passcodes (OTP) for
+ * Two-Factor Authentication via SharePoint and external channels.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchOtpPasscode = void 0;
+const sp_1 = require("@pnp/sp");
+require("@pnp/sp/webs");
+require("@pnp/sp/lists");
+require("@pnp/sp/items");
+const DEFAULT_OTP_LIST_NAME = "PendingVerifications";
+/**
+ * Queues an OTP dispatch request in SharePoint to notify the user via Email/Teams.
+ */
+async function dispatchOtpPasscode(context, request, listTitle = DEFAULT_OTP_LIST_NAME) {
+    var _a, _b, _c, _d;
+    try {
+        if (!context) {
+            throw new Error("Execution restricted: Valid WebPartContext is required.");
+        }
+        if (!request || !((_a = request.title) === null || _a === void 0 ? void 0 : _a.trim())) {
+            throw new Error("Invalid request: Signer/Title identifier is required.");
+        }
+        if (!((_b = request.passcode) === null || _b === void 0 ? void 0 : _b.trim())) {
+            throw new Error("Invalid request: Passcode must be provided.");
+        }
+        const sp = (0, sp_1.spfi)().using((0, sp_1.SPFx)(context));
+        const addedItem = await sp.web.lists.getByTitle(listTitle).items.add({
+            Title: request.title.trim(),
+            Passcode: request.passcode.trim(),
+            Channel: request.channel || "email",
+        });
+        // DEBUG: Log the entire response structure
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const debugItem = addedItem;
+        console.log("=== PnPjs Add Item Response ===");
+        console.log("Full Response:", debugItem);
+        console.log("Response Keys:", Object.keys(debugItem || {}));
+        if (debugItem === null || debugItem === void 0 ? void 0 : debugItem.data) {
+            console.log("Data Object:", debugItem.data);
+            console.log("Data Keys:", Object.keys(debugItem.data));
+        }
+        // Try multiple extraction paths
+        let itemId;
+        // Path 1: addedItem.data.Id (most common in PnPjs v3/v4)
+        if ((_c = addedItem === null || addedItem === void 0 ? void 0 : addedItem.data) === null || _c === void 0 ? void 0 : _c.Id) {
+            itemId = addedItem.data.Id;
+            console.log("✓ Found ID in addedItem.data.Id:", itemId);
+        }
+        // Path 2: addedItem.data.ID (alternative casing)
+        else if ((_d = addedItem === null || addedItem === void 0 ? void 0 : addedItem.data) === null || _d === void 0 ? void 0 : _d.ID) {
+            itemId = addedItem.data.ID;
+            console.log("✓ Found ID in addedItem.data.ID:", itemId);
+        }
+        // Path 3: addedItem.Id (direct property)
+        else if (debugItem === null || debugItem === void 0 ? void 0 : debugItem.Id) {
+            itemId = debugItem.Id;
+            console.log("✓ Found ID in addedItem.Id:", itemId);
+        }
+        // Path 4: addedItem.ID (direct property, alternate casing)
+        else if (debugItem === null || debugItem === void 0 ? void 0 : debugItem.ID) {
+            itemId = debugItem.ID;
+            console.log("✓ Found ID in addedItem.ID:", itemId);
+        }
+        // Path 5: addedItem.id (lowercase)
+        else if (debugItem === null || debugItem === void 0 ? void 0 : debugItem.id) {
+            itemId = debugItem.id;
+            console.log("✓ Found ID in addedItem.id:", itemId);
+        }
+        // Validate the extracted ID
+        if (!itemId || typeof itemId !== "number" || itemId <= 0) {
+            console.error("❌ Item ID extraction failed. Extracted value:", itemId);
+            throw new Error(`Item created but ID extraction failed. Got: ${JSON.stringify(itemId)}`);
+        }
+        console.log(`✓ OTP Record created successfully with ID: ${itemId}`);
+        return {
+            success: true,
+            itemId,
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.error("❌ dispatchOtpPasscode Error:", errorMsg);
+        console.error("Full Error Object:", error);
+        return {
+            success: false,
+            error: errorMsg,
+        };
+    }
+}
+exports.dispatchOtpPasscode = dispatchOtpPasscode;

package/lib/ProvisioningService.d.ts

@@ -1,9 +1,58 @@
+/**
+ * @file EnsurePendingVerificationsList.ts
+ *
+ * Utility module responsible for idempotent provisioning and configuration
+ * of the SharePoint list used for Two-Factor Authentication (2FA) / OTP queueing.
+ *
+ * This utility ensures:
+ *   1. The target SharePoint list exists (creates it if missing).
+ *   2. The required custom schema fields ('Passcode' and 'Channel') are provisioned.
+ *   3. Item-level security settings are hardened (ReadSecurity=2, WriteSecurity=2)
+ *      so non-admin users cannot read or tamper with other users' verification codes.
+ *
+ * @module EnsurePendingVerificationsList
+ */
 import "@pnp/sp/webs";
 import "@pnp/sp/lists";
 import "@pnp/sp/fields";
-import "@pnp/sp/views";
 import { WebPartContext } from "@microsoft/sp-webpart-base";
+/**
+ * Default SharePoint list title used for queuing 2FA verification requests.
+ */
+export declare const DEFAULT_VERIFICATION_LIST_NAME = "PendingVerifications";
+/**
+ * Default SharePoint list description.
+ */
+export declare const DEFAULT_VERIFICATION_LIST_DESC = "Stores temporary verification passcode records for digital signature workflows.";
+/**
+ * Configuration properties for provisioning the pending verifications list.
+ */
 export interface IEnsurePendingVerificationsListProps {
+    /** The SPFx WebPartContext used to initialize the PnPjs client. */
     context: WebPartContext;
+    /** Optional custom title for the SharePoint list (defaults to `"PendingVerifications"`). */
+    listTitle?: string;
+    /** Optional custom description for the list. */
+    listDescription?: string;
 }
+/**
+ * Ensures that the SharePoint list for pending verification codes exists,
+ * has the required fields (`Passcode` and `Channel`), and enforces item-level
+ * read/write security.
+ *
+ * This function is fully **idempotent**: it can be safely executed multiple times
+ * without failing or duplicating columns.
+ *
+ * @param props - Configuration properties containing context and optional list overrides.
+ * @returns A promise that resolves when the list schema and security are verified.
+ *
+ * @throws {Error} If `context` is invalid or if permissions prevent list provisioning.
+ *
+ * @example
+ * ```ts
+ * await ensurePendingVerificationsList({
+ *   context: this.context
+ * });
+ * ```
+ */
 export declare const ensurePendingVerificationsList: (props: IEnsurePendingVerificationsListProps) => Promise<void>;

package/lib/ProvisioningService.js

@@ -1,62 +1,120 @@
 "use strict";
+/**
+ * @file EnsurePendingVerificationsList.ts
+ *
+ * Utility module responsible for idempotent provisioning and configuration
+ * of the SharePoint list used for Two-Factor Authentication (2FA) / OTP queueing.
+ *
+ * This utility ensures:
+ *   1. The target SharePoint list exists (creates it if missing).
+ *   2. The required custom schema fields ('Passcode' and 'Channel') are provisioned.
+ *   3. Item-level security settings are hardened (ReadSecurity=2, WriteSecurity=2)
+ *      so non-admin users cannot read or tamper with other users' verification codes.
+ *
+ * @module EnsurePendingVerificationsList
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensurePendingVerificationsList = void 0;
+exports.ensurePendingVerificationsList = exports.DEFAULT_VERIFICATION_LIST_DESC = exports.DEFAULT_VERIFICATION_LIST_NAME = void 0;
 const sp_1 = require("@pnp/sp");
 require("@pnp/sp/webs");
 require("@pnp/sp/lists");
 require("@pnp/sp/fields");
-require("@pnp/sp/views");
+/**
+ * Default SharePoint list title used for queuing 2FA verification requests.
+ */
+exports.DEFAULT_VERIFICATION_LIST_NAME = "PendingVerifications";
+/**
+ * Default SharePoint list description.
+ */
+exports.DEFAULT_VERIFICATION_LIST_DESC = "Stores temporary verification passcode records for digital signature workflows.";
+/**
+ * Ensures that the SharePoint list for pending verification codes exists,
+ * has the required fields (`Passcode` and `Channel`), and enforces item-level
+ * read/write security.
+ *
+ * This function is fully **idempotent**: it can be safely executed multiple times
+ * without failing or duplicating columns.
+ *
+ * @param props - Configuration properties containing context and optional list overrides.
+ * @returns A promise that resolves when the list schema and security are verified.
+ *
+ * @throws {Error} If `context` is invalid or if permissions prevent list provisioning.
+ *
+ * @example
+ * ```ts
+ * await ensurePendingVerificationsList({
+ *   context: this.context
+ * });
+ * ```
+ */
 const ensurePendingVerificationsList = async (props) => {
     if (!props.context) {
         throw new Error("Execution restricted: Valid WebPartContext is required.");
     }
+    const listTitle = props.listTitle || exports.DEFAULT_VERIFICATION_LIST_NAME;
+    const listDescription = props.listDescription || exports.DEFAULT_VERIFICATION_LIST_DESC;
     const sp = (0, sp_1.spfi)().using((0, sp_1.SPFx)(props.context));
-    const LIST_NAME = "PendingVerifications";
-    const LIST_DESCRIPTION = "Stores temporary PIN verification codes for document signatures.";
-    const list = sp.web.lists.getByTitle(LIST_NAME);
-    let listCreated = false;
+    let list = sp.web.lists.getByTitle(listTitle);
+    // ---------------------------------------------------------------------------
+    // 1. Ensure the List Exists
+    // ---------------------------------------------------------------------------
     try {
         await list();
     }
     catch (_a) {
-        await sp.web.lists.add(LIST_NAME, LIST_DESCRIPTION, 100, true);
-        listCreated = true;
-    }
-    if (!listCreated) {
-        return;
+        // 100 = Generic List template, true = enable content approval/visibility
+        await sp.web.lists.add(listTitle, listDescription, 100, true);
+        list = sp.web.lists.getByTitle(listTitle);
     }
+    // ---------------------------------------------------------------------------
+    // 2. Helper: Ensure Field Exists (Idempotent Field Creation)
+    // ---------------------------------------------------------------------------
+    /**
+     * Checks if a field exists by internal name or title; if missing, calls the creation callback.
+     *
+     * @param fieldName     - Internal name or title of the field.
+     * @param createFieldFn - Async callback to execute if the field does not exist.
+     */
     const ensureField = async (fieldName, createFieldFn) => {
         try {
-            await createFieldFn();
+            await list.fields.getByInternalNameOrTitle(fieldName)();
         }
-        catch (creationErr) {
-            throw creationErr;
+        catch (_a) {
+            // Field does not exist, provision it
+            await createFieldFn();
         }
     };
+    // ---------------------------------------------------------------------------
+    // 3. Ensure 'Passcode' Field
+    // ---------------------------------------------------------------------------
     await ensureField("Passcode", async () => {
         await list.fields.addText("Passcode", {
             Required: true,
-            Description: "Temporary 6-digit signature verification code."
+            Description: "Temporary 5-digit signature verification passcode.",
         });
     });
+    // ---------------------------------------------------------------------------
+    // 4. Ensure 'Channel' Field
+    // ---------------------------------------------------------------------------
     await ensureField("Channel", async () => {
         await list.fields.addChoice("Channel", {
             Choices: ["email", "teams", "both"],
             Required: true,
             FillInChoice: false,
-            Description: "Target notification delivery route."
+            Description: "Target notification delivery route (email, teams, or both).",
         });
         const channelField = list.fields.getByInternalNameOrTitle("Channel");
-        await channelField.update({ DefaultValue: "teams" });
+        await channelField.update({ DefaultValue: "email" });
+    });
+    // ---------------------------------------------------------------------------
+    // 5. Enforce Item-Level Security Settings
+    // ---------------------------------------------------------------------------
+    // ReadSecurity: 2  -> Users can only read items that were created by themselves.
+    // WriteSecurity: 2 -> Users can only edit/delete items created by themselves.
+    // This prevents end-users from inspecting or hijacking other users' OTP codes.
+    await list.update({
+        ReadSecurity: 2,
+        WriteSecurity: 2,
     });
-    try {
-        await list.update({
-            ReadSecurity: 2,
-            WriteSecurity: 2
-        });
-    }
-    catch (secErr) {
-        throw secErr;
-    }
 };
 exports.ensurePendingVerificationsList = ensurePendingVerificationsList;