@modernman00/shared-js-lib 1.2.89 → 1.6.2

package/WebAuthnClient.js

@@ -0,0 +1,470 @@
+/**
+ * WebAuthnClient.js
+ * 
+ * Handles client-side WebAuthn interactions (FaceID, TouchID, Passcodes).
+ * Implements David's Gatewatcher mandate: Defensive Degradation.
+ */
+
+export class WebAuthnClient {
+    /**
+     * Checks if the device supports WebAuthn (Biometrics/Passkeys)
+     * @returns {boolean}
+     */
+    static isSupported() {
+        return window.PublicKeyCredential !== undefined 
+            && typeof window.PublicKeyCredential === 'function';
+    }
+
+    /**
+     * Base64URL to ArrayBuffer converter
+     */
+    static base64URLStringToBuffer(base64URLString) {
+        const base64 = base64URLString.replace(/-/g, '+').replace(/_/g, '/');
+        const padLength = (4 - (base64.length % 4)) % 4;
+        const padded = base64.padEnd(base64.length + padLength, '=');
+        const binary = atob(padded);
+        const buffer = new ArrayBuffer(binary.length);
+        const bytes = new Uint8Array(buffer);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return buffer;
+    }
+
+    /**
+     * ArrayBuffer to Base64URL converter
+     */
+    static bufferToBase64URLString(buffer) {
+        const bytes = new Uint8Array(buffer);
+        let str = '';
+        for (let i = 0; i < bytes.byteLength; i++) {
+            str += String.fromCharCode(bytes[i]);
+        }
+        return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+    }
+
+    /**
+     * Initiates the registration of a new Passkey
+     * @param {Object} optionsFromServer JSON options from /webauthn/register/options
+     */
+    static async registerDevice(optionsFromServer) {
+        if (!this.isSupported()) {
+            throw new Error("Device does not support biometrics/passkeys.");
+        }
+
+        try {
+            const publicKey = {
+                ...optionsFromServer,
+                challenge: this.base64URLStringToBuffer(optionsFromServer.challenge),
+                user: {
+                    ...optionsFromServer.user,
+                    id: this.base64URLStringToBuffer(optionsFromServer.user.id)
+                }
+            };
+
+            if (Array.isArray(publicKey.excludeCredentials)) {
+                publicKey.excludeCredentials = publicKey.excludeCredentials.map(cred => ({
+                    ...cred,
+                    id: typeof cred.id === 'string' ? this.base64URLStringToBuffer(cred.id) : cred.id
+                }));
+            }
+
+            const credential = await navigator.credentials.create({ publicKey });
+            
+            return {
+                id: credential.id,
+                rawId: this.bufferToBase64URLString(credential.rawId),
+                type: credential.type,
+                response: {
+                    attestationObject: this.bufferToBase64URLString(credential.response.attestationObject),
+                    clientDataJSON: this.bufferToBase64URLString(credential.response.clientDataJSON),
+                }
+            };
+        } catch (error) {
+            // David's Rule: Defensive Degradation. If it fails or is canceled, log and swallow politely.
+            console.warn("WebAuthn Registration failed or was canceled:", error);
+            const wrapped = new Error("Passkey registration was canceled or failed.");
+            wrapped.code = error && error.name ? error.name : 'UnknownError';
+            wrapped.originalError = error;
+            throw wrapped;
+        }
+    }
+
+    /**
+     * Initiates login using an existing Passkey
+     * @param {Object} optionsFromServer JSON options from /webauthn/login/options
+     */
+    static async loginWithDevice(optionsFromServer) {
+        if (!this.isSupported()) {
+            throw new Error("Device does not support biometrics/passkeys.");
+        }
+
+        try {
+            const publicKey = {
+                ...optionsFromServer,
+                challenge: this.base64URLStringToBuffer(optionsFromServer.challenge)
+            };
+
+            // Convert allowed credentials to buffers if they exist
+            if (publicKey.allowCredentials) {
+                publicKey.allowCredentials = publicKey.allowCredentials.map(cred => ({
+                    ...cred,
+                    id: this.base64URLStringToBuffer(cred.id)
+                }));
+            }
+
+            const assertion = await navigator.credentials.get({ publicKey });
+            
+            return {
+                id: assertion.id,
+                rawId: this.bufferToBase64URLString(assertion.rawId),
+                type: assertion.type,
+                response: {
+                    authenticatorData: this.bufferToBase64URLString(assertion.response.authenticatorData),
+                    clientDataJSON: this.bufferToBase64URLString(assertion.response.clientDataJSON),
+                    signature: this.bufferToBase64URLString(assertion.response.signature),
+                    userHandle: assertion.response.userHandle ? this.bufferToBase64URLString(assertion.response.userHandle) : null,
+                }
+            };
+        } catch (error) {
+            // David's Rule: Defensive Degradation.
+            console.warn("WebAuthn Login failed or was canceled:", error);
+            throw new Error("Passkey login was canceled or failed. Please use your password.");
+        }
+    }
+
+    /**
+     * Checks if a user-verifying platform authenticator (Face ID, Touch ID, Fingerprint, Windows Hello) is available.
+     * Uses PublicKeyCredential.getClientCapabilities() with fallback to isUserVerifyingPlatformAuthenticatorAvailable().
+     * @returns {Promise<boolean>}
+     */
+    static async isPlatformAuthenticatorAvailable() {
+        if (!this.isSupported()) {
+            return false;
+        }
+        try {
+            if (typeof window.PublicKeyCredential.getClientCapabilities === 'function') {
+                const caps = await window.PublicKeyCredential.getClientCapabilities();
+                if (caps && typeof caps.userVerifyingPlatformAuthenticator === 'boolean') {
+                    return caps.userVerifyingPlatformAuthenticator;
+                }
+            }
+            if (typeof window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function') {
+                return await window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+            }
+        } catch (e) {
+            console.warn("WebAuthn capability check failed:", e);
+        }
+        return false;
+    }
+
+    /**
+     * Detects the platform-appropriate biometric label in British English.
+     * @param {string} [ua]
+     * @returns {string}
+     */
+    static detectBiometricLabel(ua = (typeof navigator !== 'undefined' ? navigator.userAgent : '')) {
+        const agent = String(ua || '');
+        if (/iPhone|iPad|iPod|Macintosh|Mac OS X/i.test(agent)) {
+            return 'Face ID or Touch ID';
+        }
+        if (/Android/i.test(agent)) {
+            return 'Fingerprint or Face Unlock';
+        }
+        if (/Windows/i.test(agent)) {
+            return 'Windows Hello';
+        }
+        return 'Biometric Passkey';
+    }
+
+    /**
+     * Determines if the post-login Biometric Passkey Activation UI should appear.
+     * @param {Object} state
+     * @returns {boolean}
+     */
+    static shouldShowActivationPrompt(state) {
+        if (!state || state.authenticated !== true || state.hasPasskey === true) {
+            return false;
+        }
+        const key = state.userKey || state.userId || 'default';
+        try {
+            if (localStorage.getItem('biometric_enrolled_' + key) === '1') {
+                return false;
+            }
+            const snoozeUntil = Number(localStorage.getItem('biometric_snooze_' + key) || '0');
+            if (snoozeUntil > Date.now()) {
+                return false;
+            }
+        } catch (_) {
+            // Ignore storage access errors in strict private modes
+        }
+        return true;
+    }
+
+    /**
+     * Snoozes the activation prompt for the specified number of hours (default 72h).
+     * @param {string} userKey
+     * @param {number} [hours=72]
+     */
+    static snoozeActivationPrompt(userKey, hours = 72) {
+        if (!userKey) return;
+        try {
+            const until = Date.now() + hours * 3600 * 1000;
+            localStorage.setItem('biometric_snooze_' + userKey, String(until));
+        } catch (_) {}
+    }
+
+    /**
+     * Marks the current device + user pair as enrolled in localStorage.
+     * @param {string} userKey
+     */
+    static markEnrolled(userKey) {
+        if (!userKey) return;
+        try {
+            localStorage.setItem('biometric_enrolled_' + userKey, '1');
+            localStorage.removeItem('biometric_snooze_' + userKey);
+        } catch (_) {}
+    }
+
+    /**
+     * Renders and mounts the native Biometric Passkey Activation UI modal / bottom-sheet.
+     * @param {Object} state
+     * @param {Object} [options]
+     * @returns {HTMLElement|null}
+     */
+    static renderPromptModal(state = {}, options = {}) {
+        if (typeof document === 'undefined' || !document.body) {
+            return null;
+        }
+        const existing = document.getElementById('universal-passkey-prompt-backdrop');
+        if (existing) {
+            return existing;
+        }
+
+        const appName = state.appName || 'this app';
+        const userKey = state.userKey || state.userId || 'default';
+        const userEmail = state.userEmail || state.userName || 'Verified Account';
+        const bioLabel = this.detectBiometricLabel();
+
+        const backdrop = document.createElement('div');
+        backdrop.id = 'universal-passkey-prompt-backdrop';
+        backdrop.setAttribute('role', 'dialog');
+        backdrop.setAttribute('aria-modal', 'true');
+        backdrop.setAttribute('aria-labelledby', 'universal-passkey-prompt-title');
+        backdrop.style.cssText = 'position:fixed;inset:0;z-index:99998;background:rgba(15,23,42,0.68);backdrop-filter:blur(8px);-webkit-backdrop-filter:blur(8px);display:flex;align-items:flex-end;justify-content:center;padding:0;opacity:0;transition:opacity 0.22s ease-out;font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;';
+
+        const styleTag = document.createElement('style');
+        styleTag.textContent = `
+            @media (min-width: 640px) {
+                #universal-passkey-prompt-backdrop { align-items: center !important; padding: 16px !important; }
+                #universal-passkey-prompt-card { border-radius: 24px !important; max-width: 420px !important; transform: translateY(8px); }
+            }
+            @keyframes passkeySpin { to { transform: rotate(360deg); } }
+        `;
+        backdrop.appendChild(styleTag);
+
+        const card = document.createElement('div');
+        card.id = 'universal-passkey-prompt-card';
+        card.style.cssText = 'width:100%;max-width:480px;background:linear-gradient(180deg,#0f172a 0%,#1e293b 100%);color:#f8fafc;border:1px solid rgba(148,163,184,0.22);border-radius:24px 24px 0 0;padding:24px 24px calc(24px + env(safe-area-inset-bottom,0px));box-shadow:0 25px 50px -12px rgba(0,0,0,0.65);transform:translateY(16px);transition:transform 0.25s cubic-bezier(0.16,1,0.3,1);box-sizing:border-box;';
+
+        card.innerHTML = `
+            <div style="width:40px;height:4px;background:rgba(148,163,184,0.35);border-radius:999px;margin:0 auto 16px;"></div>
+            <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:16px;">
+                <div style="display:inline-flex;align-items:center;gap:10px;background:rgba(16,185,129,0.14);border:1px solid rgba(16,185,129,0.35);padding:6px 12px;border-radius:999px;">
+                    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#34d399" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                        <path d="M12 10a2 2 0 0 0-2 2c0 1.02-.1 2.51-.26 4"/><path d="M14 13.12c0 2.38 0 6.38-1 8.88"/><path d="M17.29 21.02c.12-.6.43-2.3.5-3.02"/><path d="M2 12a10 10 0 0 1 18-6"/><path d="M2 16h.01"/><path d="M21.8 16c.2-2 .131-5.354 0-6"/><path d="M5 19.5C5.5 18 6 15 6 12a6 6 0 0 1 .34-2"/><path d="M8.65 22c.21-.66.45-1.32.57-2"/><path d="M9 6.8a6 6 0 0 1 9 5.2v2"/>
+                    </svg>
+                    <span style="font-size:12px;font-weight:700;letter-spacing:0.04em;text-transform:uppercase;color:#6ee7b7;white-space:nowrap;">Biometric Security</span>
+                </div>
+                <span id="universal-passkey-account-pill" style="font-size:12px;color:#94a3b8;max-width:180px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;"></span>
+            </div>
+            <h2 id="universal-passkey-prompt-title" style="margin:0 0 8px;font-size:22px;line-height:1.25;font-weight:800;letter-spacing:-0.02em;color:#ffffff;">Activate Biometric Sign-In</h2>
+            <p id="universal-passkey-prompt-desc" style="margin:0 0 16px;font-size:14px;line-height:1.55;color:#cbd5e1;"></p>
+            <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:8px;margin-bottom:18px;">
+                <div style="background:rgba(30,41,59,0.75);border:1px solid rgba(148,163,184,0.16);border-radius:12px;padding:10px 8px;text-align:center;">
+                    <div style="font-size:12px;font-weight:700;color:#f8fafc;">1-Tap Access</div>
+                    <div style="font-size:11px;color:#94a3b8;margin-top:2px;">Instant sign-in</div>
+                </div>
+                <div style="background:rgba(30,41,59,0.75);border:1px solid rgba(148,163,184,0.16);border-radius:12px;padding:10px 8px;text-align:center;">
+                    <div style="font-size:12px;font-weight:700;color:#f8fafc;">Device-Bound</div>
+                    <div style="font-size:11px;color:#94a3b8;margin-top:2px;">Private enclave</div>
+                </div>
+                <div style="background:rgba(30,41,59,0.75);border:1px solid rgba(148,163,184,0.16);border-radius:12px;padding:10px 8px;text-align:center;">
+                    <div style="font-size:12px;font-weight:700;color:#f8fafc;">Phishing-Proof</div>
+                    <div style="font-size:11px;color:#94a3b8;margin-top:2px;">FIDO2 standard</div>
+                </div>
+            </div>
+            <div id="universal-passkey-prompt-feedback" role="status" aria-live="polite" style="display:none;margin-bottom:14px;padding:10px 12px;border-radius:12px;font-size:13px;line-height:1.4;"></div>
+            <div style="display:flex;flex-direction:column;gap:10px;">
+                <button type="button" id="universal-passkey-activate-btn" style="min-height:48px;min-width:44px;width:100%;display:inline-flex;align-items:center;justify-content:center;gap:10px;padding:12px 20px;border-radius:14px;border:none;background:linear-gradient(135deg,#10b981 0%,#059669 100%);color:#ffffff;font-size:15px;font-weight:700;cursor:pointer;white-space:nowrap;flex-shrink:0;box-shadow:0 10px 20px -5px rgba(16,185,129,0.4);transition:transform 0.15s ease,filter 0.15s ease;">
+                    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                        <path d="M12 10a2 2 0 0 0-2 2c0 1.02-.1 2.51-.26 4"/><path d="M14 13.12c0 2.38 0 6.38-1 8.88"/><path d="M2 12a10 10 0 0 1 18-6"/><path d="M5 19.5C5.5 18 6 15 6 12a6 6 0 0 1 .34-2"/><path d="M9 6.8a6 6 0 0 1 9 5.2v2"/>
+                    </svg>
+                    <span id="universal-passkey-activate-label"></span>
+                </button>
+                <button type="button" id="universal-passkey-later-btn" style="min-height:44px;min-width:44px;width:100%;display:inline-flex;align-items:center;justify-content:center;padding:10px 16px;border-radius:12px;border:1px solid rgba(148,163,184,0.22);background:transparent;color:#cbd5e1;font-size:14px;font-weight:600;cursor:pointer;white-space:nowrap;flex-shrink:0;transition:background 0.15s ease,color 0.15s ease;">
+                    Maybe Later
+                </button>
+            </div>
+        `;
+
+        backdrop.appendChild(card);
+        document.body.appendChild(backdrop);
+
+        const accountPill = card.querySelector('#universal-passkey-account-pill');
+        if (accountPill) {
+            accountPill.textContent = userEmail;
+            accountPill.setAttribute('title', userEmail);
+        }
+        const descEl = card.querySelector('#universal-passkey-prompt-desc');
+        if (descEl) {
+            descEl.textContent = `Sign in to ${appName} instantly next time using your device's recognised biometric sensor (${bioLabel}). Your biometric data never leaves this device.`;
+        }
+        const activateLabelEl = card.querySelector('#universal-passkey-activate-label');
+        if (activateLabelEl) {
+            activateLabelEl.textContent = `Activate ${bioLabel}`;
+        }
+
+        requestAnimationFrame(() => {
+            backdrop.style.opacity = '1';
+            card.style.transform = 'translateY(0)';
+        });
+
+        const closePrompt = () => {
+            backdrop.style.opacity = '0';
+            card.style.transform = 'translateY(16px)';
+            setTimeout(() => {
+                if (backdrop.parentNode) {
+                    backdrop.parentNode.removeChild(backdrop);
+                }
+            }, 220);
+        };
+
+        const showFeedback = (msg, isSuccess = false) => {
+            const fb = card.querySelector('#universal-passkey-prompt-feedback');
+            if (!fb) return;
+            fb.style.display = 'block';
+            fb.style.background = isSuccess ? 'rgba(16,185,129,0.18)' : 'rgba(245,158,11,0.16)';
+            fb.style.border = isSuccess ? '1px solid rgba(16,185,129,0.4)' : '1px solid rgba(245,158,11,0.38)';
+            fb.style.color = isSuccess ? '#a7f3d0' : '#fde68a';
+            fb.textContent = msg;
+        };
+
+        const activateBtn = card.querySelector('#universal-passkey-activate-btn');
+        const laterBtn = card.querySelector('#universal-passkey-later-btn');
+
+        if (laterBtn) {
+            laterBtn.addEventListener('click', () => {
+                this.snoozeActivationPrompt(userKey, 72);
+                closePrompt();
+            });
+        }
+
+        if (activateBtn) {
+            const originalHTML = activateBtn.innerHTML;
+            activateBtn.addEventListener('click', async () => {
+                if (activateBtn.disabled) return;
+                activateBtn.disabled = true;
+                activateBtn.style.opacity = '0.85';
+                activateBtn.style.cursor = 'wait';
+                activateBtn.innerHTML = `
+                    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" style="animation:passkeySpin 0.8s linear infinite;" aria-hidden="true">
+                        <path d="M21 12a9 9 0 1 1-6.219-8.56"/>
+                    </svg>
+                    <span>Authorising Biometrics...</span>
+                `;
+
+                const csrfMeta = document.querySelector('meta[name="csrf-token"]');
+                const headers = {
+                    'Accept': 'application/json',
+                    'Content-Type': 'application/json',
+                    'X-Requested-With': 'XMLHttpRequest'
+                };
+                if (csrfMeta && csrfMeta.content) {
+                    headers['X-CSRF-TOKEN'] = csrfMeta.content;
+                }
+
+                try {
+                    const optRes = await fetch(options.optionsEndpoint || '/webauthn/register/options', {
+                        method: 'POST',
+                        headers,
+                        credentials: 'same-origin',
+                        body: JSON.stringify({ role: state.userRole || 'users' })
+                    });
+                    const optJson = await optRes.json();
+                    const creationOptions = optJson.token || optJson.data || optJson;
+                    if (!optRes.ok || !creationOptions || !creationOptions.challenge) {
+                        throw new Error(optJson.message || 'Unable to initialise biometric challenge.');
+                    }
+
+                    const credentialPayload = await this.registerDevice(creationOptions);
+                    credentialPayload.role = state.userRole || 'users';
+                    credentialPayload.deviceName = bioLabel;
+
+                    const verifyRes = await fetch(options.registerEndpoint || '/webauthn/register', {
+                        method: 'POST',
+                        headers,
+                        credentials: 'same-origin',
+                        body: JSON.stringify(credentialPayload)
+                    });
+                    const verifyJson = await verifyRes.json();
+                    if (!verifyRes.ok && verifyJson.status !== 'success') {
+                        throw new Error(verifyJson.message || 'Failed to verify biometric passkey.');
+                    }
+
+                    this.markEnrolled(userKey);
+                    showFeedback('Biometric Passkey activated! You can now sign in with 1 tap.', true);
+                    setTimeout(closePrompt, 1100);
+                } catch (err) {
+                    if (err && err.code === 'InvalidStateError') {
+                        // Self-healing: authenticator already holds a credential for this user/RP
+                        this.markEnrolled(userKey);
+                        showFeedback('Biometric Passkey is already active on this device.', true);
+                        setTimeout(closePrompt, 1100);
+                        return;
+                    }
+                    activateBtn.disabled = false;
+                    activateBtn.style.opacity = '1';
+                    activateBtn.style.cursor = 'pointer';
+                    activateBtn.innerHTML = originalHTML;
+                    const rehydratedLabel = activateBtn.querySelector('#universal-passkey-activate-label');
+                    if (rehydratedLabel) {
+                        rehydratedLabel.textContent = `Activate ${bioLabel}`;
+                    }
+
+                    let msg = 'Biometric verification was cancelled or did not complete. Tap Activate whenever you are ready to try again.';
+                    if (err) {
+                        if (err.name === 'SecurityError' || err.code === 'SecurityError') {
+                            msg = 'Passkey registration requires HTTPS or a valid domain origin.';
+                        } else if (err.name === 'NotSupportedError' || err.code === 'NotSupportedError') {
+                            msg = 'Biometric authentication is not supported or enabled on this browser.';
+                        } else if (err.message && err.name !== 'NotAllowedError' && err.code !== 'NotAllowedError') {
+                            msg = `${err.message}. Tap Activate to try again.`;
+                        }
+                    }
+                    showFeedback(msg, false);
+                }
+            });
+        }
+
+        return backdrop;
+    }
+
+    /**
+     * Automatically evaluates post-login state and shows the Biometric Passkey Activation UI if eligible.
+     * @param {Object} [customState]
+     * @returns {Promise<boolean>}
+     */
+    static async initPostLoginPrompt(customState = null) {
+        const state = customState || (typeof window !== 'undefined' ? window.__WEBAUTHN_PROMPT_STATE__ : null);
+        if (!this.shouldShowActivationPrompt(state)) {
+            return false;
+        }
+        const available = await this.isPlatformAuthenticatorAvailable();
+        if (!available) {
+            return false;
+        }
+        this.renderPromptModal(state);
+        return true;
+    }
+}