fieldshield 1.0.0

package/dist/components/FieldShieldInput.d.ts

@@ -0,0 +1,330 @@
+/**
+ * @file FieldShieldInput.tsx
+ * @description FieldShield input component — protects sensitive text fields
+ * from browser extension DOM scraping, automated screen scrapers, and
+ * accidental clipboard exfiltration to LLMs.
+ *
+ * @example Standard mode
+ * ```tsx
+ * const ref = useRef<FieldShieldHandle>(null);
+ *
+ * const handleSubmit = async () => {
+ *   const value = await ref.current?.getSecureValue();
+ *   await fetch("/api/save", { body: JSON.stringify({ value }) });
+ *   ref.current?.purge();
+ * };
+ *
+ * <FieldShieldInput
+ *   ref={ref}
+ *   label="Patient Notes"
+ *   onSensitiveCopyAttempt={(e) =>
+ *     toast.warning(`Blocked ${e.findings.join(", ")} from clipboard`)
+ *   }
+ * />
+ * ```
+ *
+ * @example Textarea
+ * ```tsx
+ * <FieldShieldInput ref={ref} label="Clinical Notes" type="textarea" />
+ * ```
+ *
+ * @example Accessibility mode (WCAG 2.1 AA / Section 508)
+ * ```tsx
+ * <FieldShieldInput ref={ref} label="SSN" a11yMode />
+ * ```
+ *
+ * @module FieldShieldInput
+ */
+import React from "react";
+import { type CustomPattern } from "../hooks/useFieldShield";
+import "../styles/fieldshield.css";
+/**
+ * Imperative methods exposed to a parent component via `ref`.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<FieldShieldHandle>(null);
+ * <FieldShieldInput ref={ref} label="Notes" />
+ *
+ * // On submit:
+ * const value = await ref.current?.getSecureValue();
+ * ```
+ */
+export interface FieldShieldHandle {
+    /**
+     * Retrieves the real, unmasked value from the worker's isolated memory.
+     * @see {@link UseFieldShieldReturn.getSecureValue}
+     */
+    getSecureValue: () => Promise<string>;
+    /**
+     * Zeros out the stored value in worker memory.
+     * @see {@link UseFieldShieldReturn.purge}
+     */
+    purge: () => void;
+}
+/**
+ * Payload delivered to `onSensitiveCopyAttempt` and `onSensitivePaste`
+ * callbacks whenever a clipboard event involves sensitive data.
+ */
+export interface SensitiveClipboardEvent {
+    /** ISO 8601 timestamp of when the event occurred. */
+    timestamp: string;
+    /** The `label` prop of the field that triggered the event. */
+    fieldLabel: string;
+    /**
+     * Pattern names that were active at the time of the event.
+     * Example: `["SSN", "PHONE"]`
+     */
+    findings: string[];
+    /**
+     * The masked text written to (copy/cut) or read from (paste) the clipboard.
+     * Sensitive spans replaced by `█`. The real value is never included here.
+     */
+    masked: string;
+    /** Whether the event originated from a copy, cut, or paste action. */
+    eventType: "copy" | "cut" | "paste";
+}
+/**
+ * Props accepted by {@link FieldShieldInput}.
+ */
+export interface FieldShieldInputProps {
+    /**
+     * Visible label text linked to the input via `htmlFor`/`id`.
+     * Also used as the field identifier in clipboard event payloads.
+     * When omitted, no `<label>` element is rendered — the field falls back
+     * to `"Protected field"` for screen reader announcements.
+     */
+    label?: string;
+    /**
+     * Renders either a single-line `<input>` or a multi-line `<textarea>`.
+     * Textarea mode also enables auto-grow behaviour — the field expands
+     * vertically as the user types past the initial height.
+     *
+     * @defaultValue "text"
+     */
+    type?: "text" | "textarea";
+    /** Native `placeholder` attribute forwarded to the underlying element. */
+    placeholder?: string;
+    /**
+     * Additional sensitive-data patterns to layer on top of the built-in
+     * defaults. See `FIELDSHIELD_PATTERNS` for the full list. Opt-in patterns
+     * from `OPT_IN_PATTERNS` can be added here when the field context warrants them.
+     *
+     * @example
+     * ```tsx
+     * customPatterns={[{ name: "EMPLOYEE_ID", regex: "EMP-\\d{6}" }]}
+     * ```
+     */
+    customPatterns?: CustomPattern[];
+    /**
+     * Additional CSS class applied to the outermost container `<div>`.
+     * Merged with the internal `fieldshield-container` class.
+     */
+    className?: string;
+    /** Inline styles applied to the outermost container `<div>`. */
+    style?: React.CSSProperties;
+    /**
+     * Fires whenever the masked value or findings change — after each Worker
+     * UPDATE response. Gives the parent visibility into field state WITHOUT
+     * exposing the real value. The real value is only available via
+     * `ref.current.getSecureValue()`.
+     *
+     * @param masked   - Current masked display string (e.g. `"SSN: ███-██-████"`).
+     * @param findings - Deduplicated list of matched pattern names.
+     */
+    onChange?: (masked: string, findings: string[]) => void;
+    /**
+     * When `true`, disables DOM scrambling and renders a native
+     * `type="password"` input instead. Pattern detection and clipboard
+     * protection remain active.
+     *
+     * Use this mode for WCAG 2.1 AA / Section 508 compliance — screen readers
+     * handle `type="password"` fields natively and cannot interact with the
+     * scrambled overlay used in standard mode.
+     *
+     * @defaultValue false
+     */
+    a11yMode?: boolean;
+    /**
+     * Fired when the user copies or cuts from the field while sensitive
+     * patterns are present. The clipboard receives the masked text instead
+     * of the real value.
+     *
+     * Use this to surface a toast notification or write a security audit log.
+     *
+     * @param event - Details of the blocked clipboard operation.
+     */
+    onSensitiveCopyAttempt?: (event: SensitiveClipboardEvent) => void;
+    /**
+     * Fired when the user pastes content into the field that contains sensitive
+     * patterns.
+     *
+     * Return `false` to block the paste entirely — the field reverts to its
+     * previous value and the clipboard content is discarded. Return nothing
+     * (or `true`) to allow the paste to proceed.
+     *
+     * Use the block behavior for fields where sensitive data should never be
+     * pasted — for example a "reason for visit" field that should not accept
+     * SSNs. Use the allow behavior (default) for fields where the user is
+     * legitimately entering their own sensitive data.
+     *
+     * @param event - Details of the detected paste content.
+     * @returns `false` to block the paste, `void` or `true` to allow it.
+     *
+     * @example
+     * ```tsx
+     * // Block sensitive pastes
+     * onSensitivePaste={(e) => {
+     *   logAuditEvent(e);
+     *   return false; // revert the paste
+     * }}
+     *
+     * // Allow sensitive pastes but log them
+     * onSensitivePaste={(e) => {
+     *   logAuditEvent(e);
+     *   // return nothing — paste proceeds
+     * }}
+     * ```
+     */
+    onSensitivePaste?: (event: SensitiveClipboardEvent) => boolean | void;
+    /**
+     * Fired when the field receives focus. Forwarded directly from the
+     * underlying `<input>` or `<textarea>` element.
+     */
+    onFocus?: (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /**
+     * Fired when the field loses focus. Forwarded directly from the
+     * underlying `<input>` or `<textarea>` element.
+     */
+    onBlur?: (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /**
+     * Disables the field when `true`. Forwarded to the underlying element and
+     * reflected on the container via the `data-disabled` attribute for CSS
+     * styling hooks.
+     *
+     * @defaultValue false
+     */
+    disabled?: boolean;
+    /**
+     * Marks the field as required. Sets `aria-required` on the underlying
+     * element so screen readers announce the field as mandatory.
+     *
+     * @defaultValue false
+     */
+    required?: boolean;
+    /**
+     * Maximum number of characters the field will accept. Forwarded to the
+     * underlying element's native `maxLength` attribute. Also caps the amount
+     * of text the worker processes on each keystroke.
+     */
+    maxLength?: number;
+    /**
+     * Maximum number of characters sent to the worker for pattern detection.
+     * If the user types or pastes beyond this limit the input is blocked —
+     * the field reverts to its previous value and `onMaxLengthExceeded` fires.
+     *
+     * Blocking rather than truncating is intentional: truncation would create
+     * a blind spot where sensitive data beyond the limit is never scanned.
+     *
+     * This is distinct from `maxLength` which restricts the HTML input at the
+     * browser level. Use `maxLength` for structured fields with known lengths
+     * (SSN, credit card). Use `maxProcessLength` to cap worker processing for
+     * free-text fields where longer input is valid but should be bounded.
+     *
+     * @defaultValue 100000
+     */
+    maxProcessLength?: number;
+    /**
+     * Called when input is blocked because it exceeds `maxProcessLength`.
+     * Use this to surface a character count warning or error message to the user.
+     *
+     * @param length - The actual input length that triggered the block.
+     * @param limit  - The `maxProcessLength` limit that was exceeded.
+     *
+     * @example
+     * ```tsx
+     * onMaxLengthExceeded={(length, limit) =>
+     *   setError(`Input too long — maximum ${limit} characters allowed`)
+     * }
+     * ```
+     */
+    onMaxLengthExceeded?: (length: number, limit: number) => void;
+    /**
+     * Called when the Web Worker encounters a runtime error.
+     *
+     * When this fires, FieldShieldInput has already reset `masked` and
+     * `findings` to empty so the field does not freeze showing stale warnings.
+     * The worker is NOT terminated — a transient error may not affect subsequent
+     * messages. If the error is persistent, consider displaying a warning and
+     * asking the user to refresh.
+     *
+     * If the worker fails to initialize entirely (e.g. due to a strict CSP),
+     * the component automatically falls back to `a11yMode` — this callback is
+     * NOT called in that case. Listen for the `a11yMode` fallback by providing
+     * `onWorkerError` and checking whether `e.message` contains "initialize".
+     *
+     * @param error - The ErrorEvent from the worker's onerror handler.
+     *
+     * @example
+     * ```tsx
+     * onWorkerError={(e) =>
+     *   console.error("FieldShield worker error:", e.message)
+     * }
+     * ```
+     */
+    onWorkerError?: (error: ErrorEvent) => void;
+    /**
+     * Initial number of visible text rows. Only applies when `type="textarea"`.
+     * Sets a minimum height — the field still auto-grows beyond this value as
+     * the user types.
+     *
+     * @defaultValue 3
+     */
+    rows?: number;
+    /**
+     * Hint to the browser about which virtual keyboard to display on mobile.
+     * Does not affect input behaviour or value handling — the field always
+     * operates as `type="text"` internally, preserving scrambling and worker
+     * isolation regardless of this value.
+     *
+     * Use this instead of `type="number"` or `type="email"` — those change
+     * browser validation and value parsing in ways that break DOM scrambling.
+     * `inputMode` gives the correct mobile keyboard without any side effects.
+     *
+     * @example
+     * ```tsx
+     * // Numeric keypad for SSN / credit card fields
+     * <FieldShieldInput inputMode="numeric" label="SSN" />
+     *
+     * // Phone keypad with +, *, # keys
+     * <FieldShieldInput inputMode="tel" label="Phone" />
+     *
+     * // Email keyboard with @ key prominent
+     * <FieldShieldInput inputMode="email" label="Email" />
+     * ```
+     *
+     * @defaultValue "text"
+     */
+    inputMode?: "text" | "numeric" | "decimal" | "tel" | "email" | "search" | "url" | "none";
+}
+/**
+ * A drop-in replacement for `<input>` or `<textarea>` in contexts where
+ * sensitive data is typed or pasted by users.
+ *
+ * **Threat model (what this protects against)**
+ * - Browser extensions reading `input.value` via DOM inspection
+ * - Session recording tools (FullStory, LogRocket) capturing field content
+ * - Automated scrapers walking the DOM
+ * - Users accidentally copying sensitive text into LLMs via clipboard
+ *
+ * **Out of scope**
+ * - Extensions with kernel-level or debugger access
+ * - OS-level keyloggers
+ * - Network interception (use TLS)
+ *
+ * @remarks
+ * Uses `forwardRef` so parent components can hold a {@link FieldShieldHandle}
+ * ref and call `getSecureValue()` on form submission without maintaining a
+ * separate copy of the real value on the main thread.
+ */
+export declare const FieldShieldInput: React.ForwardRefExoticComponent<FieldShieldInputProps & React.RefAttributes<FieldShieldHandle>>;