@bdking71/spsignature 1.0.5 → 1.1.0

package/lib/TransactionSigner.js

@@ -1,14 +1,78 @@
 "use strict";
+/**
+ * @file SecureAuditSignature.ts
+ *
+ * Provides a secure, auditable digital-signature workflow for SharePoint
+ * web parts.  The module renders a modal dialog that supports:
+ *
+ *   • Drawing a signature on an HTML canvas
+ *   • Uploading a signature image (PNG / JPG, ≤ 5 MB)
+ *   • Re-using a previously cached (LZW-compressed) signature from
+ *     localStorage
+ *   • Optional two-factor authentication via a 5-digit passcode
+ *     dispatched through email or Microsoft Teams
+ *
+ * After the user signs, the module hashes the audit envelope
+ * (payload + signer + timestamp) with SHA-256 so that the record can
+ * later be verified without exposing the original payload.
+ *
+ * @module SecureAuditSignature
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifySecureAuditRecord = exports.getReportableSignature = exports.promptAndGenerateSecureAudit = void 0;
-const VerificationService_1 = require("./VerificationService");
+const OtpService_1 = require("./OtpService");
+/** localStorage key used to persist a compressed signature across sessions. */
 const STORAGE_KEY = "secure_audit_cached_signature_v1";
+/** Maximum upload file size in bytes (5 MB). */
+const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Helpers – passcode generation
+// ---------------------------------------------------------------------------
+/**
+ * Generates a cryptographically random 5-digit passcode (10 000 – 99 999)
+ * using the Web Crypto API.
+ *
+ * @returns A string representation of the 5-digit code.
+ */
 function generateFiveDigitPasscode() {
     const array = new Uint32Array(1);
     window.crypto.getRandomValues(array);
     const code = (array[0] % 90000) + 10000;
     return code.toString();
 }
+// ---------------------------------------------------------------------------
+// Main public function – modal signing ceremony
+// ---------------------------------------------------------------------------
+/**
+ * Opens a full-screen modal dialog that walks the user through:
+ *
+ * 1. (Optional) Two-factor passcode verification
+ * 2. Providing a digital signature (cached / drawn / uploaded)
+ * 3. Generating a tamper-evident SHA-256 audit record
+ *
+ * The returned promise resolves with a `SharePointAuditRecord` on
+ * success or `undefined` if the user cancels.
+ *
+ * @param context        - Signer metadata and SPFx context.
+ * @param modalTitle     - Title shown in the modal header.
+ * @param warningMessage - Instructional HTML rendered above the
+ *                         signature area.
+ * @returns A promise that resolves to the audit record or `undefined`.
+ *
+ * @throws {Error} If `context.spContext` is falsy.
+ *
+ * @example
+ * ```ts
+ * const record = await promptAndGenerateSecureAudit({
+ *   itemID: 42,
+ *   signer: currentUser.email,
+ *   payload: { amount: 1500, vendor: "Contoso" },
+ *   spContext: this.context,
+ *   channel: "email",
+ *   requireTFA: true,
+ * });
+ * ```
+ */
 async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purchase Requisition", warningMessage = "Please review your entry and apply your signature to finalize this record.") {
     if (!context.spContext) {
         throw new Error("Execution restricted: Valid WebPartContext must be supplied.");
@@ -16,7 +80,10 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
     return new Promise((resolve) => {
         const requireTFA = context.requireTFA !== false;
         const generatedPasscode = generateFiveDigitPasscode();
-        let storedVerificationItemId = context.itemID;
+        let storedVerificationItemId = undefined;
+        // -----------------------------------------------------------------
+        // Overlay
+        // -----------------------------------------------------------------
         const overlay = document.createElement("div");
         overlay.style.position = "fixed";
         overlay.style.top = "0";
@@ -28,8 +95,12 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         overlay.style.display = "flex";
         overlay.style.alignItems = "center";
         overlay.style.justifyContent = "center";
-        overlay.style.fontFamily = "'Segoe UI', Tahoma, Geneva, Verdana, sans-serif";
+        overlay.style.fontFamily =
+            "'Segoe UI', Tahoma, Geneva, Verdana, sans-serif";
         overlay.style.backdropFilter = "blur(3px)";
+        // -----------------------------------------------------------------
+        // Modal container
+        // -----------------------------------------------------------------
         const modalBox = document.createElement("div");
         modalBox.style.backgroundColor = "#ffffff";
         modalBox.style.padding = "0";
@@ -41,6 +112,9 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         modalBox.style.maxHeight = "90vh";
         modalBox.style.display = "flex";
         modalBox.style.flexDirection = "column";
+        // -----------------------------------------------------------------
+        // Header
+        // -----------------------------------------------------------------
         const headerSection = document.createElement("div");
         headerSection.style.backgroundColor = "#0078d4";
         headerSection.style.padding = "20px 24px";
@@ -53,6 +127,9 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         title.style.fontWeight = "600";
         title.style.letterSpacing = "0.3px";
         headerSection.appendChild(title);
+        // -----------------------------------------------------------------
+        // Content wrapper
+        // -----------------------------------------------------------------
         const contentSection = document.createElement("div");
         contentSection.style.padding = "24px";
         contentSection.style.backgroundColor = "#fafafa";
@@ -64,6 +141,9 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         body.style.color = "#323130";
         body.style.lineHeight = "1.6";
         body.style.margin = "0 0 20px 0";
+        // -----------------------------------------------------------------
+        // Sign button (footer)
+        // -----------------------------------------------------------------
         const signButton = document.createElement("button");
         signButton.innerText = "I Agree and Sign";
         signButton.style.padding = "10px 24px";
@@ -75,14 +155,23 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         signButton.style.fontWeight = "600";
         signButton.style.borderRadius = "4px";
         signButton.style.transition = "all 0.2s ease";
+        // -----------------------------------------------------------------
+        // Two-factor verification panel
+        // -----------------------------------------------------------------
         const verificationContainer = document.createElement("div");
+        /** Direct reference to the passcode <input> (avoids fragile querySelector). */
+        let verificationInput = null;
+        /** Direct reference to the "Resend Code" button. */
+        let sendCodeButton = null;
         if (requireTFA) {
             verificationContainer.style.marginBottom = "20px";
             verificationContainer.style.padding = "16px";
             verificationContainer.style.backgroundColor = "#fff8e1";
             verificationContainer.style.border = "1px solid #ffd54f";
             verificationContainer.style.borderRadius = "6px";
-            verificationContainer.style.boxShadow = "0 2px 4px rgba(0,0,0,0.05)";
+            verificationContainer.style.boxShadow =
+                "0 2px 4px rgba(0,0,0,0.05)";
+            /* Header row with lock icon */
             const verificationHeader = document.createElement("div");
             verificationHeader.style.display = "flex";
             verificationHeader.style.alignItems = "center";
@@ -106,10 +195,11 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             verificationDescription.style.color = "#605e5c";
             verificationDescription.style.margin = "0 0 12px 0";
             verificationDescription.style.lineHeight = "1.5";
+            /* Input + Resend row */
             const verificationRow = document.createElement("div");
             verificationRow.style.display = "flex";
             verificationRow.style.gap = "10px";
-            const verificationInput = document.createElement("input");
+            verificationInput = document.createElement("input");
             verificationInput.type = "text";
             verificationInput.maxLength = 5;
             verificationInput.placeholder = "Enter 5-digit code";
@@ -124,13 +214,14 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             verificationInput.style.textAlign = "center";
             verificationInput.style.letterSpacing = "2px";
             verificationInput.style.fontWeight = "600";
-            verificationInput.onfocus = () => {
-                verificationInput.style.borderColor = "#0078d4";
+            const vInput = verificationInput; // capture for closures
+            vInput.onfocus = () => {
+                vInput.style.borderColor = "#0078d4";
             };
-            verificationInput.onblur = () => {
-                verificationInput.style.borderColor = "#d1d1d1";
+            vInput.onblur = () => {
+                vInput.style.borderColor = "#d1d1d1";
             };
-            const sendCodeButton = document.createElement("button");
+            sendCodeButton = document.createElement("button");
             sendCodeButton.innerText = "Resend Code";
             sendCodeButton.type = "button";
             sendCodeButton.style.padding = "10px 16px";
@@ -143,14 +234,15 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             sendCodeButton.style.borderRadius = "4px";
             sendCodeButton.style.fontWeight = "600";
             sendCodeButton.style.transition = "all 0.2s ease";
-            sendCodeButton.onmouseover = () => {
-                sendCodeButton.style.backgroundColor = "#0078d4";
-                sendCodeButton.style.color = "#ffffff";
+            const scBtn = sendCodeButton; // capture for closures
+            scBtn.onmouseover = () => {
+                scBtn.style.backgroundColor = "#0078d4";
+                scBtn.style.color = "#ffffff";
             };
-            sendCodeButton.onmouseout = () => {
-                if (!sendCodeButton.disabled) {
-                    sendCodeButton.style.backgroundColor = "#ffffff";
-                    sendCodeButton.style.color = "#0078d4";
+            scBtn.onmouseout = () => {
+                if (!scBtn.disabled) {
+                    scBtn.style.backgroundColor = "#ffffff";
+                    scBtn.style.color = "#0078d4";
                 }
             };
             verificationRow.appendChild(verificationInput);
@@ -159,11 +251,17 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             verificationContainer.appendChild(verificationDescription);
             verificationContainer.appendChild(verificationRow);
         }
+        // -----------------------------------------------------------------
+        // Cached-signature detection
+        // -----------------------------------------------------------------
         const cachedCompressedSig = localStorage.getItem(STORAGE_KEY);
-        const hasCachedSignature = cachedCompressedSig !== null && cachedCompressedSig.trim() !== "";
-        const decompressedCachedDataUri = (hasCachedSignature && cachedCompressedSig)
+        let hasCachedSignature = cachedCompressedSig !== null && cachedCompressedSig.trim() !== "";
+        const decompressedCachedDataUri = hasCachedSignature && cachedCompressedSig
             ? lzwDecompress(cachedCompressedSig)
             : "";
+        // -----------------------------------------------------------------
+        // Signature section wrapper
+        // -----------------------------------------------------------------
         const signatureSection = document.createElement("div");
         signatureSection.style.marginBottom = "20px";
         signatureSection.style.padding = "16px";
@@ -180,12 +278,16 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         signatureLabel.style.color = "#323130";
         signatureLabel.style.margin = "0 0 4px 0";
         const signatureSubtext = document.createElement("p");
-        signatureSubtext.innerText = "Choose how you'd like to provide your signature";
+        signatureSubtext.innerText =
+            "Choose how you'd like to provide your signature";
         signatureSubtext.style.fontSize = "12px";
         signatureSubtext.style.color = "#605e5c";
         signatureSubtext.style.margin = "0";
         signatureHeader.appendChild(signatureLabel);
         signatureHeader.appendChild(signatureSubtext);
+        // -----------------------------------------------------------------
+        // "Remember signature" checkbox
+        // -----------------------------------------------------------------
         const cacheControlBox = document.createElement("div");
         cacheControlBox.style.marginTop = "16px";
         cacheControlBox.style.padding = "12px";
@@ -205,19 +307,25 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         cacheCheckbox.style.width = "16px";
         cacheCheckbox.style.height = "16px";
         const cacheCheckboxText = document.createElement("span");
-        cacheCheckboxText.innerText = "Remember my signature on this device for future transactions";
+        cacheCheckboxText.innerText =
+            "Remember my signature on this device for future transactions";
         cacheCheckboxText.style.color = "#323130";
         cacheCheckboxText.style.fontSize = "12px";
         cacheCheckboxLabel.appendChild(cacheCheckbox);
         cacheCheckboxLabel.appendChild(cacheCheckboxText);
         cacheControlBox.appendChild(cacheCheckboxLabel);
+        // -----------------------------------------------------------------
+        // Cached-signature notice panel
+        // -----------------------------------------------------------------
         const cachedNoticeContainer = document.createElement("div");
         cachedNoticeContainer.style.marginBottom = "16px";
         cachedNoticeContainer.style.padding = "16px";
         cachedNoticeContainer.style.backgroundColor = "#e6f4ff";
         cachedNoticeContainer.style.border = "1px solid #0078d4";
         cachedNoticeContainer.style.borderRadius = "6px";
-        cachedNoticeContainer.style.display = hasCachedSignature ? "block" : "none";
+        cachedNoticeContainer.style.display = hasCachedSignature
+            ? "block"
+            : "none";
         const cachedNoticeText = document.createElement("div");
         cachedNoticeText.innerText = "✓ Saved signature on file";
         cachedNoticeText.style.fontSize = "13px";
@@ -259,11 +367,21 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         cachedNoticeContainer.appendChild(cachedNoticeText);
         cachedNoticeContainer.appendChild(cachedPreviewImage);
         cachedNoticeContainer.appendChild(removeCachedBtn);
+        // -----------------------------------------------------------------
+        // Tab bar (Saved / Draw New / Upload Image)
+        // -----------------------------------------------------------------
         const modeContainer = document.createElement("div");
         modeContainer.style.display = "flex";
         modeContainer.style.gap = "8px";
         modeContainer.style.marginBottom = "16px";
         modeContainer.style.borderBottom = "2px solid #edebe9";
+        /**
+         * Factory that creates a styled tab button.
+         *
+         * @param text      - Label for the tab.
+         * @param isActive  - Whether the tab should appear selected initially.
+         * @returns The constructed `<button>` element.
+         */
         const createTab = (text, isActive) => {
             const tab = document.createElement("button");
             tab.innerText = text;
@@ -274,23 +392,35 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             tab.style.backgroundColor = "transparent";
             tab.style.color = isActive ? "#0078d4" : "#605e5c";
             tab.style.border = "none";
-            tab.style.borderBottom = isActive ? "3px solid #0078d4" : "3px solid transparent";
+            tab.style.borderBottom = isActive
+                ? "3px solid #0078d4"
+                : "3px solid transparent";
             tab.style.transition = "all 0.2s ease";
             tab.style.outline = "none";
+            /* Hover handlers check current activeMode so they remain correct
+               after the user switches tabs. */
             tab.onmouseover = () => {
-                if (!isActive) {
+                const tabIsCurrentlyActive = (tab === cachedTabBtn && activeMode === "cached") ||
+                    (tab === drawTabBtn && activeMode === "draw") ||
+                    (tab === uploadTabBtn && activeMode === "upload");
+                if (!tabIsCurrentlyActive) {
                     tab.style.color = "#0078d4";
                 }
             };
             tab.onmouseout = () => {
-                if (!isActive) {
+                const tabIsCurrentlyActive = (tab === cachedTabBtn && activeMode === "cached") ||
+                    (tab === drawTabBtn && activeMode === "draw") ||
+                    (tab === uploadTabBtn && activeMode === "upload");
+                if (!tabIsCurrentlyActive) {
                     tab.style.color = "#605e5c";
                 }
             };
             return tab;
         };
         const cachedTabBtn = createTab("Saved", hasCachedSignature);
-        cachedTabBtn.style.display = hasCachedSignature ? "inline-block" : "none";
+        cachedTabBtn.style.display = hasCachedSignature
+            ? "inline-block"
+            : "none";
         const drawTabBtn = createTab("Draw New", !hasCachedSignature);
         const uploadTabBtn = createTab("Upload Image", false);
         if (hasCachedSignature) {
@@ -298,9 +428,15 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         }
         modeContainer.appendChild(drawTabBtn);
         modeContainer.appendChild(uploadTabBtn);
+        // -----------------------------------------------------------------
+        // Cached panel
+        // -----------------------------------------------------------------
         const cachedPanel = document.createElement("div");
         cachedPanel.style.display = hasCachedSignature ? "block" : "none";
         cachedPanel.appendChild(cachedNoticeContainer);
+        // -----------------------------------------------------------------
+        // Draw panel (canvas)
+        // -----------------------------------------------------------------
         const drawPanel = document.createElement("div");
         drawPanel.style.display = hasCachedSignature ? "none" : "block";
         const canvasContainer = document.createElement("div");
@@ -324,6 +460,7 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         canvas.style.width = "100%";
         canvas.style.borderRadius = "4px";
         canvas.style.boxShadow = "inset 0 1px 3px rgba(0,0,0,0.1)";
+        /** Button to clear the drawing canvas. */
         const clearButton = document.createElement("button");
         clearButton.innerText = "Clear Canvas";
         clearButton.style.marginTop = "10px";
@@ -346,6 +483,9 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         canvasContainer.appendChild(canvas);
         canvasContainer.appendChild(clearButton);
         drawPanel.appendChild(canvasContainer);
+        // -----------------------------------------------------------------
+        // Upload panel
+        // -----------------------------------------------------------------
         const uploadPanel = document.createElement("div");
         uploadPanel.style.display = "none";
         uploadPanel.style.padding = "32px 24px";
@@ -355,7 +495,6 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         uploadPanel.style.borderRadius = "6px";
         uploadPanel.style.transition = "all 0.2s ease";
         uploadPanel.style.minHeight = "200px";
-        uploadPanel.style.display = "none";
         uploadPanel.style.flexDirection = "column";
         uploadPanel.style.alignItems = "center";
         uploadPanel.style.justifyContent = "center";
@@ -396,7 +535,12 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         uploadPanel.appendChild(uploadSubtext);
         uploadPanel.appendChild(fileInput);
         uploadPanel.appendChild(uploadPreview);
-        let activeMode = hasCachedSignature ? "cached" : "draw";
+        // -----------------------------------------------------------------
+        // State
+        // -----------------------------------------------------------------
+        let activeMode = hasCachedSignature
+            ? "cached"
+            : "draw";
         let compressedUploadBase64 = "";
         const ctx = canvas.getContext("2d");
         let isDrawing = false;
@@ -409,19 +553,30 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             ctx.lineCap = "round";
             ctx.lineJoin = "round";
         }
+        // -----------------------------------------------------------------
+        // Button-state helper
+        // -----------------------------------------------------------------
+        /**
+         * Re-evaluates whether the "I Agree and Sign" button should be
+         * enabled, based on the current TFA code entry and selected
+         * signature mode.
+         */
         const updateButtonState = () => {
             let isCodeValid = true;
-            if (requireTFA) {
-                const verificationInput = verificationContainer.querySelector("input");
+            if (requireTFA && verificationInput) {
                 const codeValue = verificationInput.value.trim();
-                isCodeValid = codeValue.length === 5 && codeValue === generatedPasscode;
+                isCodeValid =
+                    codeValue.length === 5 && codeValue === generatedPasscode;
             }
             let isSignatureValid = false;
             if (activeMode === "cached") {
                 isSignatureValid = hasCachedSignature;
             }
             else if (activeMode === "draw") {
-                isSignatureValid = hasDrawnContent && ctx !== null && !isCanvasEmpty(ctx, canvas.width, canvas.height);
+                isSignatureValid =
+                    hasDrawnContent &&
+                        ctx !== null &&
+                        !isCanvasEmpty(ctx, canvas.width, canvas.height);
             }
             else {
                 isSignatureValid = compressedUploadBase64.trim() !== "";
@@ -439,6 +594,15 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                 signButton.style.opacity = "0.6";
             }
         };
+        // -----------------------------------------------------------------
+        // Tab-switching logic
+        // -----------------------------------------------------------------
+        /**
+         * Activates the given tab, hiding the other panels and updating
+         * visual tab styles.
+         *
+         * @param mode - Which panel to show.
+         */
         const setActiveTab = (mode) => {
             activeMode = mode;
             cachedPanel.style.display = mode === "cached" ? "block" : "none";
@@ -448,7 +612,11 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                 btn.style.color = "#605e5c";
                 btn.style.borderBottom = "3px solid transparent";
             });
-            const activeBtn = mode === "cached" ? cachedTabBtn : mode === "draw" ? drawTabBtn : uploadTabBtn;
+            const activeBtn = mode === "cached"
+                ? cachedTabBtn
+                : mode === "draw"
+                    ? drawTabBtn
+                    : uploadTabBtn;
             activeBtn.style.color = "#0078d4";
             activeBtn.style.borderBottom = "3px solid #0078d4";
             updateButtonState();
@@ -458,50 +626,63 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         }
         drawTabBtn.onclick = () => setActiveTab("draw");
         uploadTabBtn.onclick = () => setActiveTab("upload");
+        /** Removes the cached signature and switches to the draw tab. */
         removeCachedBtn.onclick = () => {
             localStorage.removeItem(STORAGE_KEY);
+            hasCachedSignature = false;
             cachedTabBtn.style.display = "none";
             setActiveTab("draw");
         };
-        if (requireTFA && context.channel) {
-            const sendCodeButton = verificationContainer.querySelector("button");
-            const verificationInput = verificationContainer.querySelector("input");
+        // -----------------------------------------------------------------
+        // Two-factor: send-code logic
+        // -----------------------------------------------------------------
+        if (requireTFA && context.channel && sendCodeButton && verificationInput) {
             let cooldownTimer = null;
+            const scBtnRef = sendCodeButton;
+            const vInputRef = verificationInput;
+            /**
+             * Starts a 60-second cooldown on the "Resend Code" button to
+             * prevent rapid re-sends.
+             */
             const startCooldownTimer = () => {
                 let secondsLeft = 60;
-                sendCodeButton.disabled = true;
-                sendCodeButton.style.backgroundColor = "#f3f2f1";
-                sendCodeButton.style.color = "#a19f9d";
-                sendCodeButton.style.borderColor = "#d1d1d1";
-                sendCodeButton.style.cursor = "not-allowed";
-                sendCodeButton.innerText = `Resend (${secondsLeft}s)`;
+                scBtnRef.disabled = true;
+                scBtnRef.style.backgroundColor = "#f3f2f1";
+                scBtnRef.style.color = "#a19f9d";
+                scBtnRef.style.borderColor = "#d1d1d1";
+                scBtnRef.style.cursor = "not-allowed";
+                scBtnRef.innerText = `Resend (${secondsLeft}s)`;
                 if (cooldownTimer) {
                     clearInterval(cooldownTimer);
                 }
                 cooldownTimer = window.setInterval(() => {
                     secondsLeft -= 1;
                     if (secondsLeft > 0) {
-                        sendCodeButton.innerText = `Resend (${secondsLeft}s)`;
+                        scBtnRef.innerText = `Resend (${secondsLeft}s)`;
                     }
                     else {
                         if (cooldownTimer) {
                             clearInterval(cooldownTimer);
                         }
-                        sendCodeButton.disabled = false;
-                        sendCodeButton.style.backgroundColor = "#ffffff";
-                        sendCodeButton.style.color = "#0078d4";
-                        sendCodeButton.style.borderColor = "#0078d4";
-                        sendCodeButton.style.cursor = "pointer";
-                        sendCodeButton.innerText = "Resend Code";
+                        scBtnRef.disabled = false;
+                        scBtnRef.style.backgroundColor = "#ffffff";
+                        scBtnRef.style.color = "#0078d4";
+                        scBtnRef.style.borderColor = "#0078d4";
+                        scBtnRef.style.cursor = "pointer";
+                        scBtnRef.innerText = "Resend Code";
                     }
                 }, 1000);
             };
+            /**
+             * Dispatches the verification passcode through the configured
+             * channel (email / Teams) and starts the cooldown timer.
+             */
             const triggerSendCode = async () => {
-                sendCodeButton.innerText = "Sending...";
-                sendCodeButton.disabled = true;
+                scBtnRef.innerText = "Sending...";
+                scBtnRef.disabled = true;
                 try {
                     if (context.spContext && context.channel) {
-                        const vResult = await (0, VerificationService_1.createPendingVerification)(context.spContext, {
+                        const vResult = await (0, OtpService_1.dispatchOtpPasscode)(context.spContext, {
                             title: context.signer,
                             passcode: generatedPasscode,
                             channel: context.channel,
@@ -522,23 +703,50 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                     startCooldownTimer();
                 }
             };
-            sendCodeButton.onclick = async () => {
+            scBtnRef.onclick = async () => {
                 await triggerSendCode();
             };
-            verificationInput.oninput = () => {
+            vInputRef.oninput = () => {
                 updateButtonState();
             };
             void triggerSendCode();
         }
+        // -----------------------------------------------------------------
+        // Canvas drawing helpers
+        // -----------------------------------------------------------------
+        /**
+         * Translates a mouse or touch event into canvas-relative
+         * coordinates, accounting for CSS scaling.
+         *
+         * @param e - The originating mouse or touch event.
+         * @returns `{ x, y }` in canvas-pixel space.
+         */
         const getPos = (e) => {
             const rect = canvas.getBoundingClientRect();
-            const clientX = "touches" in e ? e.touches[0].clientX : e.clientX;
-            const clientY = "touches" in e ? e.touches[0].clientY : e.clientY;
+            let clientX;
+            let clientY;
+            if ("touches" in e && e.touches.length > 0) {
+                clientX = e.touches[0].clientX;
+                clientY = e.touches[0].clientY;
+            }
+            else if ("changedTouches" in e && e.changedTouches.length > 0) {
+                clientX = e.changedTouches[0].clientX;
+                clientY = e.changedTouches[0].clientY;
+            }
+            else {
+                clientX = e.clientX;
+                clientY = e.clientY;
+            }
             return {
                 x: (clientX - rect.left) * (canvas.width / rect.width),
-                y: (clientY - rect.top) * (canvas.height / rect.height)
+                y: (clientY - rect.top) * (canvas.height / rect.height),
             };
         };
+        /**
+         * Begins a new drawing stroke at the pointer position.
+         *
+         * @param e - The initiating mouse/touch event.
+         */
         const startDraw = (e) => {
             isDrawing = true;
             hasDrawnContent = true;
@@ -547,6 +755,11 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             ctx === null || ctx === void 0 ? void 0 : ctx.moveTo(pos.x, pos.y);
             e.preventDefault();
         };
+        /**
+         * Extends the current stroke to the pointer's new position.
+         *
+         * @param e - The move event.
+         */
         const drawLine = (e) => {
             if (!isDrawing || !ctx)
                 return;
@@ -556,6 +769,7 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             updateButtonState();
             e.preventDefault();
         };
+        /** Ends the current drawing stroke. */
         const stopDraw = () => {
             isDrawing = false;
             updateButtonState();
@@ -563,9 +777,10 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
         canvas.addEventListener("mousedown", startDraw);
         canvas.addEventListener("mousemove", drawLine);
         window.addEventListener("mouseup", stopDraw);
-        canvas.addEventListener("touchstart", startDraw);
-        canvas.addEventListener("touchmove", drawLine);
+        canvas.addEventListener("touchstart", startDraw, { passive: false });
+        canvas.addEventListener("touchmove", drawLine, { passive: false });
         window.addEventListener("touchend", stopDraw);
+        /** Clears the drawing canvas back to a blank white rectangle. */
         clearButton.onclick = () => {
             if (ctx) {
                 ctx.fillStyle = "#ffffff";
@@ -574,10 +789,23 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                 updateButtonState();
             }
         };
+        // -----------------------------------------------------------------
+        // File upload handler
+        // -----------------------------------------------------------------
+        /**
+         * Handles image file selection: validates size, resizes if needed,
+         * and stores the result as a data-URI.
+         */
         fileInput.onchange = (e) => {
             const target = e.target;
             if (target.files && target.files[0]) {
                 const file = target.files[0];
+                /* Enforce the advertised 5 MB limit. */
+                if (file.size > MAX_UPLOAD_BYTES) {
+                    alert(`File size exceeds 5 MB (${(file.size / 1024 / 1024).toFixed(1)} MB). Please choose a smaller image.`);
+                    target.value = "";
+                    return;
+                }
                 const reader = new FileReader();
                 reader.onload = (uploadEvent) => {
                     var _a;
@@ -604,7 +832,8 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                                 tCtx.fillStyle = "#ffffff";
                                 tCtx.fillRect(0, 0, w, h);
                                 tCtx.drawImage(img, 0, 0, w, h);
-                                compressedUploadBase64 = tempCanvas.toDataURL("image/png");
+                                compressedUploadBase64 =
+                                    tempCanvas.toDataURL("image/png");
                                 uploadPreview.src = compressedUploadBase64;
                                 uploadPreview.style.display = "block";
                                 updateButtonState();
@@ -616,6 +845,9 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                 reader.readAsDataURL(file);
             }
         };
+        // -----------------------------------------------------------------
+        // Footer (Cancel + Sign buttons)
+        // -----------------------------------------------------------------
         const footerSection = document.createElement("div");
         footerSection.style.padding = "20px 24px";
         footerSection.style.backgroundColor = "#ffffff";
@@ -650,16 +882,33 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                 signButton.style.backgroundColor = "#0078d4";
             }
         };
+        // -----------------------------------------------------------------
+        // Cleanup helper
+        // -----------------------------------------------------------------
+        /**
+         * Removes the modal overlay from the DOM and unregisters window-
+         * level event listeners to prevent memory leaks.
+         */
         const cleanup = () => {
+            window.removeEventListener("mouseup", stopDraw);
+            window.removeEventListener("touchend", stopDraw);
             document.body.removeChild(overlay);
         };
+        /** Cancel button dismisses the dialog and resolves with `undefined`. */
         cancelButton.onclick = () => {
             cleanup();
             resolve(undefined);
         };
+        // -----------------------------------------------------------------
+        // Sign button handler
+        // -----------------------------------------------------------------
+        /**
+         * Validates the TFA code (if required), extracts the signature
+         * data from the active panel, compresses it, optionally caches it,
+         * then generates the SHA-256 audit record.
+         */
         signButton.onclick = async () => {
-            if (requireTFA) {
-                const verificationInput = verificationContainer.querySelector("input");
+            if (requireTFA && verificationInput) {
                 const enteredCode = verificationInput.value.trim();
                 if (enteredCode !== generatedPasscode) {
                     alert("Invalid verification code. Please enter the correct 5-digit code.");
@@ -675,14 +924,16 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
                 finalDataUrl = lzwDecompress(cachedCompressedSig);
             }
             else if (activeMode === "draw") {
-                if (!ctx || isCanvasEmpty(ctx, canvas.width, canvas.height)) {
+                if (!ctx ||
+                    isCanvasEmpty(ctx, canvas.width, canvas.height)) {
                     alert("Please draw your signature before proceeding.");
                     return;
                 }
                 finalDataUrl = downscaleCanvas(canvas, 560, 160);
             }
             else {
-                if (!compressedUploadBase64 || compressedUploadBase64.trim() === "") {
+                if (!compressedUploadBase64 ||
+                    compressedUploadBase64.trim() === "") {
                     alert("Please upload a signature image before proceeding.");
                     return;
                 }
@@ -699,7 +950,7 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             try {
                 const fullContext = Object.assign(Object.assign({}, context), { signatureData: compressedString });
                 const result = await generateSecureAuditRecordInternal(fullContext);
-                if (storedVerificationItemId) {
+                if (storedVerificationItemId !== undefined) {
                     result.verificationItemId = storedVerificationItemId;
                 }
                 resolve(result);
@@ -710,6 +961,9 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
             }
         };
         updateButtonState();
+        // -----------------------------------------------------------------
+        // Assemble DOM tree
+        // -----------------------------------------------------------------
         footerSection.appendChild(cancelButton);
         footerSection.appendChild(signButton);
         contentSection.appendChild(body);
@@ -731,6 +985,20 @@ async function promptAndGenerateSecureAudit(context, modalTitle = "Approve Purch
     });
 }
 exports.promptAndGenerateSecureAudit = promptAndGenerateSecureAudit;
+// ---------------------------------------------------------------------------
+// Signature decompression for reports
+// ---------------------------------------------------------------------------
+/**
+ * Decompresses an LZW-compressed signature string back into its
+ * original `data:image/…` data-URI for display in reports or
+ * print views.
+ *
+ * @param compressedSignatureData - The LZW-compressed string stored
+ *                                  in SharePoint.
+ * @returns The original data-URI, or an empty string if
+ *          decompression fails or the result is not an image
+ *          data-URI.
+ */
 function getReportableSignature(compressedSignatureData) {
     const decompressed = lzwDecompress(compressedSignatureData);
     if (!decompressed || !decompressed.startsWith("data:image")) {
@@ -739,6 +1007,22 @@ function getReportableSignature(compressedSignatureData) {
     return decompressed;
 }
 exports.getReportableSignature = getReportableSignature;
+// ---------------------------------------------------------------------------
+// LZW compression / decompression
+// ---------------------------------------------------------------------------
+/**
+ * Compresses a string using the LZW (Lempel-Ziv-Welch) algorithm.
+ *
+ * **Caveat:** When the dictionary grows past 65 535 entries,
+ * `String.fromCharCode` will produce values that may not survive
+ * a round-trip through `localStorage` or JSON.  For very large
+ * inputs consider chunking or switching to a Uint16Array-backed
+ * encoding.
+ *
+ * @param input - The raw string to compress.
+ * @returns The compressed string (each character encodes one
+ *          dictionary index).
+ */
 function lzwCompress(input) {
     const dictionary = {};
     let c = "";
@@ -764,8 +1048,17 @@ function lzwCompress(input) {
     if (w !== "") {
         result.push(dictionary[w]);
     }
-    return result.map((n) => String.fromCharCode(n)).join("");
+    return result
+        .map((n) => String.fromCharCode(n))
+        .join("");
 }
+/**
+ * Decompresses a string that was compressed with {@link lzwCompress}.
+ *
+ * @param compressed - The LZW-compressed string.
+ * @returns The original string, or an empty string if the input is
+ *          empty or contains an unrecognised dictionary reference.
+ */
 function lzwDecompress(compressed) {
     const dictionary = {};
     const result = [];
@@ -780,13 +1073,14 @@ function lzwDecompress(compressed) {
     let entry = "";
     for (let i = 1; i < compressed.length; i += 1) {
         const k = compressed.charCodeAt(i);
-        if (dictionary[k]) {
+        if (dictionary[k] !== undefined) {
             entry = dictionary[k];
         }
         else if (k === dictionarySize) {
             entry = w + w.charAt(0);
         }
         else {
+            console.warn(`lzwDecompress: unrecognised dictionary index ${k} at position ${i}.`);
             return "";
         }
         result.push(entry);
@@ -795,6 +1089,18 @@ function lzwDecompress(compressed) {
     }
     return result.join("");
 }
+// ---------------------------------------------------------------------------
+// Canvas utilities
+// ---------------------------------------------------------------------------
+/**
+ * Draws the contents of `sourceCanvas` onto a new canvas at the
+ * specified dimensions and returns the result as a PNG data-URI.
+ *
+ * @param sourceCanvas - The canvas element to read from.
+ * @param targetWidth  - Desired output width in pixels.
+ * @param targetHeight - Desired output height in pixels.
+ * @returns A `data:image/png;base64,…` string.
+ */
 function downscaleCanvas(sourceCanvas, targetWidth, targetHeight) {
     const tempCanvas = document.createElement("canvas");
     tempCanvas.width = targetWidth;
@@ -807,6 +1113,16 @@ function downscaleCanvas(sourceCanvas, targetWidth, targetHeight) {
     }
     return tempCanvas.toDataURL("image/png");
 }
+/**
+ * Determines whether every pixel on the canvas is pure white
+ * (`rgb(255, 255, 255)`), which indicates that the user has not
+ * drawn anything yet.
+ *
+ * @param ctx    - The 2D rendering context of the canvas.
+ * @param width  - Canvas width in pixels.
+ * @param height - Canvas height in pixels.
+ * @returns `true` if the canvas contains only white pixels.
+ */
 function isCanvasEmpty(ctx, width, height) {
     const pixelBuffer = ctx.getImageData(0, 0, width, height).data;
     for (let i = 0; i < pixelBuffer.length; i += 4) {
@@ -818,7 +1134,31 @@ function isCanvasEmpty(ctx, width, height) {
     }
     return true;
 }
-async function verifySecureAuditRecord(payloadToVerify, signer, timestamp, compressedSignatureData, storedHash) {
+// ---------------------------------------------------------------------------
+// Audit-record verification
+// ---------------------------------------------------------------------------
+/**
+ * Re-computes the SHA-256 hash of the audit envelope constructed from
+ * the supplied parameters and compares it to `storedHash`.
+ *
+ * This allows any consumer to independently verify that a signed
+ * record has not been tampered with, without needing access to the
+ * original signature image.
+ *
+ * **Note:** Only top-level payload keys are sorted.  If your payload
+ * contains nested objects whose key order may vary, consider using a
+ * deep-sort utility before calling this function.
+ *
+ * @param payloadToVerify         - The payload that was originally signed.
+ * @param signer                  - The signer identifier used at sign time.
+ * @param timestamp               - The ISO-8601 timestamp captured at sign
+ *                                  time.
+ * @param _compressedSignatureData - The compressed signature (unused by the
+ *                                  hash, retained for API symmetry).
+ * @param storedHash              - The SHA-256 hex digest to compare against.
+ * @returns `true` if the recomputed hash matches `storedHash`.
+ */
+async function verifySecureAuditRecord(payloadToVerify, signer, timestamp, _compressedSignatureData, storedHash) {
     try {
         if (!payloadToVerify || !storedHash)
             return false;
@@ -831,7 +1171,8 @@ async function verifySecureAuditRecord(payloadToVerify, signer, timestamp, compr
         const auditEnvelopeJson = JSON.stringify(auditEnvelope);
         const encoder = new TextEncoder();
         const encodedBytes = encoder.encode(auditEnvelopeJson);
-        const hashBuffer = await window.crypto.subtle.digest("SHA-256", encodedBytes);
+        // Fixed BufferSource type incompatibility:
+        const hashBuffer = await window.crypto.subtle.digest("SHA-256", encodedBytes.buffer);
         const hashArray = Array.from(new Uint8Array(hashBuffer));
         const recomputedHash = hashArray
             .map((b) => b.toString(16).padStart(2, "0"))
@@ -843,29 +1184,50 @@ async function verifySecureAuditRecord(payloadToVerify, signer, timestamp, compr
     }
 }
 exports.verifySecureAuditRecord = verifySecureAuditRecord;
+// ---------------------------------------------------------------------------
+// Internal – audit-record generation
+// ---------------------------------------------------------------------------
+/**
+ * Constructs the canonical audit envelope from the signer context,
+ * hashes it with SHA-256, and returns a `SharePointAuditRecord`
+ * ready for persistence.
+ *
+ * This is an internal function and is not exported.
+ *
+ * @param context - The full signer context, extended with the
+ *                  compressed signature data string.
+ * @returns A fully populated `SharePointAuditRecord`.
+ *
+ * @throws {Error} If the payload is empty or the signer is blank.
+ */
 async function generateSecureAuditRecordInternal(context) {
     const { payload, signer, signatureData } = context;
-    if (!payload || Object.keys(payload).length === 0)
+    if (!payload || Object.keys(payload).length === 0) {
         throw new Error("Payload cannot be empty.");
-    if (!signer || signer.trim() === "")
+    }
+    if (!signer || signer.trim() === "") {
         throw new Error("Signer identifier is required for sealing.");
+    }
     const signatureTimestamp = new Date().toISOString();
     const sortedPayloadString = JSON.stringify(payload, Object.keys(payload).sort());
     const auditEnvelope = {
         payload: JSON.parse(sortedPayloadString),
         signer: signer.toLowerCase().trim(),
-        timestamp: signatureTimestamp.trim()
+        timestamp: signatureTimestamp.trim(),
     };
     const auditEnvelopeJson = JSON.stringify(auditEnvelope);
     const encoder = new TextEncoder();
     const encodedBytes = encoder.encode(auditEnvelopeJson);
-    const hashBuffer = await window.crypto.subtle.digest("SHA-256", encodedBytes);
+    // Passing `encodedBytes.buffer as ArrayBuffer` satisfies the DOM BufferSource definition
+    const hashBuffer = await window.crypto.subtle.digest("SHA-256", encodedBytes.buffer);
     const hashArray = Array.from(new Uint8Array(hashBuffer));
-    const signatureHash = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    const signatureHash = hashArray
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
     return {
         signatureHash,
         signatureData,
         signatureTimestamp,
-        verificationItemId: context.itemID
+        verificationItemId: context.itemID,
     };
 }