fieldshield 1.0.0

package/dist/fieldshield.umd.cjs

@@ -0,0 +1,4 @@
+(function(f,t){typeof exports=="object"&&typeof module<"u"?t(exports,require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react"],t):(f=typeof globalThis<"u"?globalThis:f||self,t(f.FieldShield={},f.ReactJSXRuntime,f.React))})(this,(function(f,t,s){"use strict";var B=typeof document<"u"?document.currentScript:null;const j=Object.freeze({AI_API_KEY:"(sk-[a-zA-Z0-9][a-zA-Z0-9-]{19,}|ant-api-[a-z0-9-]{20,}|AIza[0-9A-Za-z_-]{35})",AWS_ACCESS_KEY:"\\b(AKIA|ASIA)[0-9A-Z]{16}\\b",SSN:"\\b\\d{3}[-\\s.]?\\d{2}[-\\s.]?\\d{4}\\b",EMAIL:"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",PHONE:"\\b(?:\\+?1[-. ]?)?\\(?[2-9]\\d{2}\\)?[-. ]?\\d{3}[-. ]?\\d{4}\\b|\\+[1-9][\\s.-]?(?:\\d[\\s.-]?){6,14}\\d\\b",CREDIT_CARD:["\\b4\\d{3}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b","\\b5[1-5]\\d{2}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b","\\b3[47]\\d{2}[-\\s]?\\d{6}[-\\s]?\\d{5}\\b"].join("|"),DATE_OF_BIRTH:"\\b(?:0?[1-9]|1[0-2])[-/.](?:0?[1-9]|[12]\\d|3[01])[-/.](?:19|20)\\d{2}\\b|\\b(?:19|20)\\d{2}[-/.](?:0?[1-9]|1[0-2])[-/.](?:0?[1-9]|[12]\\d|3[01])\\b",TAX_ID:"\\b\\d{2}-\\d{7}\\b|\\b\\d{9}\\b",GITHUB_TOKEN:"\\b(ghp|gho|ghs|ghu|github_pat)_[a-zA-Z0-9_]{20,}\\b",STRIPE_KEY:"\\b(sk|pk|rk)_(live|test)_[a-zA-Z0-9]{20,}\\b",JWT:"\\beyJ[a-zA-Z0-9_-]+\\.[a-zA-Z0-9_-]+\\.[a-zA-Z0-9_-]+\\b",PRIVATE_KEY_BLOCK:"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----",UK_NIN:"\\b[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z]\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\s?[A-D]\\b"}),ce=Object.freeze({IBAN:"\\b[A-Z]{2}\\d{2}[-\\s]?(?:[A-Z0-9]{1,4}[-\\s]?){3,}[A-Z0-9]{1,4}\\b",DEA_NUMBER:"\\b[ABCDEFGHJKLMPRSTUX][A-Z]\\d{7}\\b",SWIFT_BIC:"\\b[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?\\b",NPI_NUMBER:"\\b[12]\\d{9}\\b",PASSPORT_NUMBER:"\\b[A-Z]{1,2}[0-9]{6,9}\\b"}),ee=3e3,oe=1e5,te=d=>Object.fromEntries(d.map(l=>[l.name,l.regex])),se=(d=[],l=oe,A,b)=>{const[y,S]=s.useState(""),[R,$]=s.useState([]),[P,v]=s.useState(!1),r=s.useRef(null),w=JSON.stringify(d);s.useEffect(()=>{let m=!1;try{r.current=new Worker(new URL("/assets/fieldshield.worker.js",typeof document>"u"&&typeof location>"u"?require("url").pathToFileURL(__filename).href:typeof document>"u"?location.href:B&&B.tagName.toUpperCase()==="SCRIPT"&&B.src||new URL("fieldshield.umd.cjs",document.baseURI).href),{type:"module"})}catch(c){console.error("[FieldShield] Worker failed to initialize — falling back to a11yMode.",c),queueMicrotask(()=>v(!0));return}return r.current.onmessage=c=>{m||c.data?.type==="UPDATE"&&typeof c.data.masked=="string"&&Array.isArray(c.data.findings)&&(S(c.data.masked),$(c.data.findings))},r.current.onerror=c=>{m||(console.error(`[FieldShield] Worker runtime error: ${c.message??"unknown error"}`),S(""),$([]),b?.(c))},r.current.postMessage({type:"CONFIG",payload:{defaultPatterns:j,customPatterns:te([])}}),()=>{m=!0,r.current?.terminate(),r.current=null}},[]),s.useEffect(()=>{r.current&&r.current.postMessage({type:"CONFIG",payload:{defaultPatterns:j,customPatterns:te(d)}})},[w]);const D=s.useCallback(m=>m.length>l?(console.warn(`[FieldShield] Input length ${m.length} exceeds maxProcessLength (${l}). Keystroke blocked to prevent unprotected data beyond the limit. Raise maxProcessLength if this field requires longer input.`),A?.(m.length,l),!1):(r.current?.postMessage({type:"PROCESS",payload:{text:m}}),!0),[l,A]),k=s.useCallback(()=>new Promise((m,c)=>{if(!r.current){m("");return}const{port1:I,port2:V}=new MessageChannel,G=setTimeout(()=>{I.close(),c(new Error(`[FieldShield] getSecureValue timed out after ${ee}ms.`))},ee);I.onmessage=W=>{clearTimeout(G),I.close(),m(W.data.text)},r.current.postMessage({type:"GET_TRUTH"},[V])}),[]),x=s.useCallback(()=>{r.current?.postMessage({type:"PURGE"})},[]);return{masked:y,findings:R,processText:D,getSecureValue:k,purge:x,workerFailed:P}},ae=s.forwardRef(({label:d,type:l="text",placeholder:A,customPatterns:b=[],className:y,style:S,onChange:R,a11yMode:$=!1,onSensitiveCopyAttempt:P,onSensitivePaste:v,onFocus:r,onBlur:w,disabled:D=!1,required:k=!1,maxLength:x,rows:m=3,inputMode:c="text",maxProcessLength:I=1e5,onMaxLengthExceeded:V,onWorkerError:G},W)=>{const{masked:K,findings:Z,processText:z,getSecureValue:ne,purge:re,workerFailed:he}=se(b,I,V,G),ge=$||he,u=Z.length>0,F=d??"Protected field",J=s.useRef(null),le=s.useRef(null),L=s.useRef(null),p=s.useRef(""),_=s.useId(),N=`${_}-warning`,H=`${_}-desc`;s.useImperativeHandle(W,()=>({getSecureValue:ne,purge:()=>{re(),z(""),p.current="";const e=J.current??le.current;e&&(e.value="",L.current&&(L.current.textContent=`
+`))}}),[ne,re,z]),s.useEffect(()=>{R?.(K,Z)},[K,Z,R]);const Y=(e,a,n)=>{if(!z(a)){const E=p.current.replace(/[^\n]/g,"x");e.value=E;const g=Math.min(n,p.current.length);e.setSelectionRange(g,g);return}p.current=a;const i=a.replace(/[^\n]/g,"x");e.value=i,e.setSelectionRange(n,n),L.current&&(L.current.textContent=i+`
+`)},ie=e=>{const a=e.target,n=a.value,h=a.selectionStart??n.length,i=p.current,E=n.length-i.length;let g;if(E>0){const o=Math.max(0,h-E),T=n.slice(o,h);g=i.slice(0,o)+T+i.slice(o)}else if(E<0){const o=h,T=o-E;g=i.slice(0,o)+i.slice(T)}else{let o=-1,T=-1;for(let C=0;C<n.length;C++)n[C]!=="x"&&n[C]!==`
+`&&(o===-1&&(o=C),T=C+1);if(o!==-1){const C=n.slice(o,T);g=i.slice(0,o)+C+i.slice(T)}else g=i}Y(a,g,h)},be=e=>{const a=e.target.value;p.current=a,z(a)},X=e=>{e.preventDefault();const a=e.clipboardData.getData("text/plain"),n=e.target,h=n.selectionStart??0,i=n.selectionEnd??0,E=p.current,g=E.length-(i-h)+a.length;if(g>I){console.warn(`[FieldShield] Paste blocked — result length ${g} would exceed maxProcessLength (${I}). DOM unchanged.`),V?.(g,I);return}const o=E.slice(0,h)+a+E.slice(i),T=h+a.length;if(Y(n,o,T),v&&a){const C=[...Object.entries(j),...b.map(O=>[O.name,O.regex])],de=[];for(const[O,U]of C)try{de.push([O,new RegExp(U,"gi")])}catch{}const q=[];let Q=a;for(const[O,U]of de)U.lastIndex=0,U.test(a)&&(q.push(O),U.lastIndex=0,Q=Q.replace(U,Se=>"█".repeat(Se.length)));q.length>0&&v({timestamp:new Date().toISOString(),fieldLabel:F,findings:[...new Set(q)],masked:Q,eventType:"paste"})===!1&&Y(n,E,h)}},M=e=>{e.preventDefault();const a=e.target,n=a.selectionStart??0,h=a.selectionEnd??p.current.length,i=K.slice(n,h),E=i.includes("█");if(u&&E?(e.clipboardData.setData("text/plain",i),P?.({timestamp:new Date().toISOString(),fieldLabel:F,findings:[...Z],masked:i,eventType:e.type==="cut"?"cut":"copy"})):e.clipboardData.setData("text/plain",p.current.slice(n,h)),e.type==="cut"){const g=p.current.slice(0,n),o=p.current.slice(h);p.current=g+o,z(p.current);const T="x".repeat(p.current.length);a.value=T,a.setSelectionRange(n,n)}};return ge?t.jsxs("div",{className:`fieldshield-container${y?` ${y}`:""}`,style:S,role:"group","aria-labelledby":_,"data-disabled":D||void 0,children:[d&&t.jsx("label",{htmlFor:_,className:"fieldshield-label",children:d}),t.jsx("span",{id:H,className:"fieldshield-sr-only",children:"This field is protected. Sensitive data patterns will be detected and blocked from copying."}),t.jsx("input",{id:_,ref:J,type:"password",className:"fieldshield-a11y-input",placeholder:A,onChange:be,onCopy:M,onCut:M,onPaste:X,onFocus:r,onBlur:w,disabled:D,required:k,maxLength:x,inputMode:c,spellCheck:!1,autoComplete:"off","aria-required":k,"aria-label":d?void 0:F,"aria-describedby":`${H} ${u?N:""}`.trim(),"aria-invalid":u?"true":"false","aria-errormessage":u?N:void 0}),t.jsx("div",{id:N,role:"status","aria-live":"polite","aria-atomic":"true",className:"fieldshield-findings",children:u&&t.jsxs(t.Fragment,{children:[t.jsx("span",{className:"fieldshield-warning-icon","aria-hidden":"true",children:"⚠"}),t.jsxs("span",{className:"fieldshield-warning-text",children:["Sensitive data detected. Clipboard blocked for:"," "]}),Z.map(e=>t.jsx("span",{className:"fieldshield-tag","aria-label":`pattern: ${e}`,children:e},e))]})})]}):t.jsxs("div",{className:`fieldshield-container${y?` ${y}`:""}`,style:S,role:"group","aria-labelledby":_,"data-disabled":D||void 0,children:[d&&t.jsx("label",{htmlFor:_,className:"fieldshield-label",children:d}),t.jsx("span",{id:H,className:"fieldshield-sr-only",children:"Sensitive field. Input is protected. Sensitive data patterns will be detected and blocked from copying."}),t.jsxs("div",{className:"fieldshield-field-wrapper",children:[t.jsx("div",{className:`fieldshield-mask-layer${u?" fieldshield-mask-unsafe":""}`,"aria-hidden":"true",children:K||t.jsx("span",{className:"fieldshield-placeholder",children:A})}),l==="textarea"&&t.jsx("div",{ref:L,className:"fieldshield-grow","aria-hidden":"true"}),l==="textarea"?t.jsx("textarea",{ref:le,id:_,className:"fieldshield-real-input",placeholder:A,onChange:ie,onPaste:X,onCopy:M,onCut:M,onFocus:r,onBlur:w,disabled:D,required:k,maxLength:x,rows:m,inputMode:c,spellCheck:!1,autoComplete:"off","aria-required":k,"aria-label":u?`${F} — sensitive data detected`:`${F} — protected input`,"aria-describedby":`${H} ${u?N:""}`.trim(),"aria-invalid":u?"true":"false","aria-errormessage":u?N:void 0}):t.jsx("input",{ref:J,id:_,type:"text",className:"fieldshield-real-input",placeholder:A,onChange:ie,onPaste:X,onCopy:M,onCut:M,onFocus:r,onBlur:w,disabled:D,required:k,maxLength:x,inputMode:c,spellCheck:!1,autoComplete:"off","aria-required":k,"aria-label":u?`${F} — sensitive data detected`:`${F} — protected input`,"aria-describedby":`${H} ${u?N:""}`.trim(),"aria-invalid":u?"true":"false","aria-errormessage":u?N:void 0})]}),t.jsx("div",{id:N,role:"status","aria-live":"polite","aria-atomic":"true",className:"fieldshield-findings",children:u&&t.jsxs(t.Fragment,{children:[t.jsx("span",{className:"fieldshield-warning-icon","aria-hidden":"true",children:"⚠"}),t.jsxs("span",{className:"fieldshield-warning-text",children:["Sensitive data detected. Clipboard blocked for:"," "]}),Z.map(e=>t.jsx("span",{className:"fieldshield-tag","aria-label":`pattern: ${e}`,children:e},e))]})})]})});ae.displayName="FieldShieldInput";const ue=(d={})=>{const{maxEvents:l=20}=d,[A,b]=s.useState([]),y=s.useRef(0),S=s.useCallback(P=>{const v=++y.current,r=new Date().toLocaleTimeString();b(w=>[{...P,id:v,timestamp:r},...w].slice(0,l))},[l]),R=s.useCallback(P=>v=>{const r=P==="paste"?"PASTE_DETECTED":v.eventType==="cut"?"CUT_BLOCKED":"COPY_BLOCKED";S({field:v.fieldLabel,type:r,findings:v.findings,detail:`${v.masked.slice(0,32)}${v.masked.length>32?"…":""}`})},[S]),$=s.useCallback(()=>{b([]),y.current=0},[]);return{events:A,pushEvent:S,makeClipboardHandler:R,clearLog:$}},fe=async d=>{const l=Object.entries(d),A=await Promise.allSettled(l.map(([,b])=>b.current?.getSecureValue()??Promise.resolve("")));return Object.fromEntries(l.map(([b],y)=>{const S=A[y];return S.status==="rejected"?(console.warn(`[FieldShield] collectSecureValues: field "${String(b)}" failed to retrieve value.`,S.reason),[b,""]):[b,S.value]}))},pe=d=>{Object.values(d).forEach(l=>l.current?.purge())};f.FIELDSHIELD_PATTERNS=j,f.FieldShieldInput=ae,f.OPT_IN_PATTERNS=ce,f.collectSecureValues=fe,f.purgeSecureValues=pe,f.useFieldShield=se,f.useSecurityLog=ue,Object.defineProperty(f,Symbol.toStringTag,{value:"Module"})}));

package/dist/hooks/useFieldShield.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @file useFieldShield.ts
+ * @description React hook that manages the lifecycle of the FieldShield Web Worker,
+ * exposes masked output and pattern findings for rendering, and provides
+ * imperative methods for secure value retrieval and memory purging.
+ *
+ * @example
+ * ```tsx
+ * const { masked, findings, processText, getSecureValue, purge } =
+ *   useFieldShield([{ name: "EMPLOYEE_ID", regex: "EMP-\\d{6}" }]);
+ * ```
+ *
+ * @module useFieldShield
+ */
+/**
+ * A custom sensitive-data pattern supplied by the consuming application.
+ *
+ * @remarks
+ * The public API intentionally uses an array of objects rather than a plain
+ * Record for two reasons:
+ *
+ * 1. **Order is preserved** — arrays have guaranteed iteration order. Developers
+ *    who want to prioritise certain patterns can control the order they are
+ *    applied.
+ * 2. **Duplicate detection** — two entries with the same `name` are visible in
+ *    an array and can be warned about. In a Record the second key silently
+ *    overwrites the first.
+ *
+ * The array is converted to a `Record<string, string>` by {@link toPatternRecord}
+ * before being sent to the worker, so the worker remains agnostic to the
+ * public API shape.
+ *
+ * @example
+ * ```ts
+ * { name: "EMPLOYEE_ID", regex: "EMP-\\d{6}" }
+ * ```
+ */
+export interface CustomPattern {
+    /** Human-readable label shown in the findings list (e.g. `"EMPLOYEE_ID"`). */
+    name: string;
+    /**
+     * Regular expression source string. Do **not** include delimiters (`/`) or
+     * flags — the worker applies `gi` automatically.
+     *
+     * Use double backslashes for escape sequences since this is a string, not a
+     * regex literal. For example: `"\\d{6}"` not `"\d{6}"`.
+     */
+    regex: string;
+}
+/**
+ * Return value of {@link useFieldShield}.
+ */
+export interface UseFieldShieldReturn {
+    /**
+     * A copy of the current input value with sensitive spans replaced by
+     * `█` characters. Safe to render directly in the UI.
+     */
+    masked: string;
+    /**
+     * Deduplicated list of pattern names that matched the current value
+     * (e.g. `["SSN", "EMAIL"]`). Empty array when the field is clean.
+     */
+    findings: string[];
+    /**
+     * Send the current real value to the worker for pattern analysis.
+     * Call this on every input change.
+     *
+     * Returns `true` if the input was accepted and sent to the worker,
+     * or `false` if it was blocked because it exceeded `maxProcessLength`.
+     * The caller (e.g. `handleChange` in `FieldShieldInput`) must revert
+     * the DOM to the previous value when `false` is returned.
+     *
+     * @param text - The unmasked text to evaluate.
+     * @returns `true` if accepted, `false` if blocked.
+     */
+    processText: (text: string) => boolean;
+    /**
+     * Retrieve the real, unmasked value from the worker's isolated memory
+     * via a private `MessageChannel`. Use this on form submission rather than
+     * maintaining a separate copy of the real value in the main thread.
+     *
+     * @returns A promise that resolves to the current unmasked value, or
+     *   rejects with a timeout error if the worker does not respond within
+     *   3 seconds.
+     *
+     * @example
+     * ```ts
+     * const handleSubmit = async () => {
+     *   const realValue = await getSecureValue();
+     *   await fetch("/api/save", { body: JSON.stringify({ value: realValue }) });
+     * };
+     * ```
+     */
+    getSecureValue: () => Promise<string>;
+    /**
+     * Zero out the stored value in the worker's memory and confirm deletion.
+     * Call this after successful form submission or on session logout.
+     *
+     * @remarks
+     * Useful for compliance environments (HIPAA, PCI-DSS, SOC 2) that require
+     * demonstrable cleanup of sensitive data from application memory.
+     */
+    purge: () => void;
+    /**
+     * `true` if the Web Worker failed to initialize and the hook has fallen
+     * back to no-op mode. The consuming component should switch to `a11yMode`
+     * when this is `true` to ensure the field remains usable.
+     *
+     * Common causes: strict CSP blocking worker initialization, unsupported
+     * browser context (some sandboxed iframes), or browser memory pressure.
+     */
+    workerFailed: boolean;
+}
+/**
+ * Default maximum number of characters sent to the worker for processing.
+ * Large enough for legitimate clinical notes and free-text fields while
+ * protecting against denial-of-service via adversarially crafted input.
+ * Consumers can raise or lower this via the `maxProcessLength` parameter.
+ */
+export declare const DEFAULT_MAX_PROCESS_LENGTH = 100000;
+/**
+ * Manages a {@link fieldshield.worker | FieldShield Web Worker} for the lifetime of
+ * the consuming component, keeping the worker alive across pattern updates to
+ * avoid losing `internalTruth`.
+ *
+ * @param customPatterns - Optional additional patterns to layer on top of the
+ *   built-in defaults. Changing this array reconfigures the worker without
+ *   terminating it, preserving any value already in memory.
+ *
+ * @returns {@link UseFieldShieldReturn}
+ *
+ * @remarks
+ * **Two-effect design** — worker creation and pattern configuration are
+ * intentionally split into separate `useEffect` calls:
+ *
+ * - Effect 1 (`[]` deps): Creates the worker once on mount, immediately sends
+ *   the built-in default patterns from `patterns.ts` via CONFIG, and terminates
+ *   only on unmount. The worker's `internalTruth` survives prop changes.
+ * - Effect 2 (`[patternsString]` deps): Sends an updated CONFIG message
+ *   whenever `customPatterns` changes. Sends both default and custom patterns
+ *   together so the worker always has the full active set. No teardown occurs,
+ *   so stored values are preserved.
+ *
+ * Combining these into one effect would destroy and recreate the worker —
+ * and its stored `internalTruth` — on every pattern update.
+ *
+ * **Cancelled flag** — a boolean closed over by the `onmessage` handler
+ * guards against stale worker responses arriving after the component unmounts.
+ * The cleanup function flips it to `true` before terminating the worker. Any
+ * message that arrives after that point is discarded, preventing a state update
+ * on an unmounted component.
+ *
+ * React 18 no longer warns on unmounted state updates, but the race condition
+ * still exists. The flag makes the hook correct by definition rather than
+ * correct by luck.
+ */
+export declare const useFieldShield: (customPatterns?: CustomPattern[], maxProcessLength?: number, onMaxLengthExceeded?: (length: number, limit: number) => void, onWorkerError?: (error: ErrorEvent) => void) => UseFieldShieldReturn;

package/dist/hooks/useSecurityLog.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @file useSecurityLog.ts
+ * @description Hook that maintains a typed, auto-timestamped log of FieldShield
+ * security events — copy blocks, cut blocks, paste detections, submissions,
+ * and memory purges.
+ *
+ * @example
+ * ```tsx
+ * const { events, makeClipboardHandler, pushEvent, clearLog } = useSecurityLog();
+ *
+ * <FieldShieldInput
+ *   label="SSN"
+ *   onSensitiveCopyAttempt={makeClipboardHandler("copy_cut")}
+ *   onSensitivePaste={makeClipboardHandler("paste")}
+ * />
+ *
+ * <ol>
+ *   {events.map(ev => <li key={ev.id}>{ev.field} — {ev.type}</li>)}
+ * </ol>
+ * ```
+ *
+ * @module useSecurityLog
+ */
+import type { SensitiveClipboardEvent } from "../components/FieldShieldInput";
+/**
+ * Discriminated union of all event types the log can record.
+ *
+ * - `COPY_BLOCKED`    — user attempted to copy sensitive data; clipboard received masked text.
+ * - `CUT_BLOCKED`     — user attempted to cut sensitive data; clipboard received masked text.
+ * - `PASTE_DETECTED`  — user pasted content containing sensitive patterns.
+ * - `SUBMIT`          — form was submitted via `collectSecureValues`.
+ * - `PURGE`           — worker memory was zeroed after submission.
+ * - `CUSTOM`          — application-defined event pushed via `pushEvent` directly.
+ */
+export type SecurityEventType = "COPY_BLOCKED" | "CUT_BLOCKED" | "PASTE_DETECTED" | "SUBMIT" | "PURGE" | "CUSTOM";
+/**
+ * A single entry in the security event log.
+ */
+export interface SecurityEvent {
+    /** Auto-incrementing unique identifier — safe to use as a React key. */
+    id: number;
+    /**
+     * Human-readable time string derived from the event timestamp.
+     * Formatted via `Date.toLocaleTimeString()` at the moment the event is pushed.
+     */
+    timestamp: string;
+    /**
+     * The field that produced the event. Sourced from `SensitiveClipboardEvent.fieldLabel`
+     * for clipboard events, or supplied directly for SUBMIT / PURGE events.
+     */
+    field: string;
+    /** Discriminated event type. See {@link SecurityEventType}. */
+    type: SecurityEventType;
+    /**
+     * Pattern names active at the time of the event (e.g. `["SSN", "EMAIL"]`).
+     * Empty array for SUBMIT, PURGE, and CUSTOM events that carry no findings.
+     */
+    findings: string[];
+    /**
+     * Optional human-readable detail string for display in the log UI.
+     * For clipboard events this is a truncated preview of the masked value.
+     */
+    detail?: string;
+}
+/**
+ * Options accepted by {@link useSecurityLog}.
+ */
+export interface UseSecurityLogOptions {
+    /**
+     * Maximum number of events retained in the log. Oldest events are dropped
+     * when the limit is exceeded.
+     *
+     * @defaultValue 20
+     */
+    maxEvents?: number;
+}
+/**
+ * Return value of {@link useSecurityLog}.
+ */
+export interface UseSecurityLogReturn {
+    /**
+     * The current list of security events, newest first.
+     * Safe to map directly as React children — each entry has a stable `id`.
+     */
+    events: SecurityEvent[];
+    /**
+     * Push any event into the log manually. Use this for SUBMIT and PURGE events
+     * that are not produced by a clipboard callback.
+     *
+     * @example
+     * ```ts
+     * pushEvent({ field: "All fields", type: "SUBMIT", findings: [], detail: "3 fields submitted" });
+     * ```
+     */
+    pushEvent: (event: Omit<SecurityEvent, "id" | "timestamp">) => void;
+    /**
+     * Returns a `SensitiveClipboardEvent` handler ready to wire directly into
+     * `onSensitiveCopyAttempt` or `onSensitivePaste`.
+     *
+     * Pass `"copy_cut"` for `onSensitiveCopyAttempt` — the handler inspects
+     * `e.eventType` internally to distinguish copy from cut.
+     * Pass `"paste"` for `onSensitivePaste`.
+     *
+     * @example
+     * ```tsx
+     * <FieldShieldInput
+     *   onSensitiveCopyAttempt={makeClipboardHandler("copy_cut")}
+     *   onSensitivePaste={makeClipboardHandler("paste")}
+     * />
+     * ```
+     */
+    makeClipboardHandler: (context: "copy_cut" | "paste") => (e: SensitiveClipboardEvent) => void;
+    /**
+     * Clears all events from the log, resetting it to an empty state.
+     * Resets the internal ID counter.
+     */
+    clearLog: () => void;
+}
+/**
+ * Maintains a capped, auto-timestamped log of FieldShield security events.
+ *
+ * @param options - Optional configuration. See {@link UseSecurityLogOptions}.
+ * @returns {@link UseSecurityLogReturn}
+ *
+ * @remarks
+ * **ID counter** — the counter lives in a `useRef`.
+ * It is only ever incremented inside `pushEvent` and read to generate IDs —
+ * nothing renders based on its value.
+ *
+ * **Stable callbacks** — `pushEvent` and `makeClipboardHandler` are both
+ * wrapped in `useCallback`. `makeClipboardHandler` depends on `pushEvent`
+ * which is itself stable, so the returned handler references are stable across
+ * renders and safe to pass as props without triggering child re-renders.
+ *
+ * **Newest-first ordering** — events are prepended (`[newEvent, ...prev]`)
+ * so index 0 is always the most recent. This matches the expected rendering
+ * order for audit log UIs.
+ */
+export declare const useSecurityLog: (options?: UseSecurityLogOptions) => UseSecurityLogReturn;

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+/**
+ * @file index.ts
+ * @description Public API barrel for the FieldShield library.
+ *
+ * Import from "fieldshield" to access all public components, hooks,
+ * utilities, types, and built-in patterns.
+ *
+ * @example
+ * ```tsx
+ * import { FieldShieldInput, FIELDSHIELD_PATTERNS, collectSecureValues } from "fieldshield";
+ * ```
+ *
+ * @module fieldshield
+ */
+export { FieldShieldInput } from "./components/FieldShieldInput";
+export type { FieldShieldHandle, FieldShieldInputProps, SensitiveClipboardEvent, } from "./components/FieldShieldInput";
+export { useFieldShield } from "./hooks/useFieldShield";
+export type { CustomPattern, UseFieldShieldReturn } from "./hooks/useFieldShield";
+export { useSecurityLog } from "./hooks/useSecurityLog";
+export type { SecurityEvent, SecurityEventType, UseSecurityLogOptions, UseSecurityLogReturn, } from "./hooks/useSecurityLog";
+export { collectSecureValues, purgeSecureValues } from "./utils/collectSecureValue";
+export type { FieldShieldRefMap, SecureValues } from "./utils/collectSecureValue";
+export { FIELDSHIELD_PATTERNS, OPT_IN_PATTERNS } from "./patterns";

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file index.ts
+ * @description Public API barrel for the FieldShield library.
+ *
+ * Import from "fieldshield" to access all public components, hooks,
+ * utilities, types, and built-in patterns.
+ *
+ * @example
+ * ```tsx
+ * import { FieldShieldInput, FIELDSHIELD_PATTERNS, collectSecureValues } from "fieldshield";
+ * ```
+ *
+ * @module fieldshield
+ */
+export { FieldShieldInput } from "./components/FieldShieldInput";
+export type { FieldShieldHandle, FieldShieldInputProps, SensitiveClipboardEvent, } from "./components/FieldShieldInput";
+export { useFieldShield } from "./hooks/useFieldShield";
+export type { CustomPattern, UseFieldShieldReturn } from "./hooks/useFieldShield";
+export { useSecurityLog } from "./hooks/useSecurityLog";
+export type { SecurityEvent, SecurityEventType, UseSecurityLogOptions, UseSecurityLogReturn, } from "./hooks/useSecurityLog";
+export { collectSecureValues, purgeSecureValues } from "./utils/collectSecureValue";
+export type { FieldShieldRefMap, SecureValues } from "./utils/collectSecureValue";
+export { FIELDSHIELD_PATTERNS, OPT_IN_PATTERNS } from "./patterns";

package/dist/patterns.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file patterns.ts
+ * @description Single source of truth for all built-in and opt-in sensitive data
+ * patterns shipped with FieldShield.
+ *
+ * @remarks
+ * Patterns are stored as plain regex source strings — no delimiters (`/`) and
+ * no flags. This is intentional for two reasons:
+ *
+ * 1. **Main thread consumers** (`FieldShieldInput.tsx`, `useFieldShield.ts`) import
+ *    this file directly and construct `RegExp` objects with whatever flags they
+ *    need for their specific use case.
+ *
+ * 2. **The Web Worker** (`fieldshield.worker.ts`) cannot safely import from a
+ *    relative path when the library is consumed via npm — the bundler of the
+ *    consuming application may not resolve worker imports correctly. Instead,
+ *    `useFieldShield.ts` sends these patterns to the worker via a `CONFIG` message
+ *    on mount, keeping the worker completely self-contained with no imports.
+ *
+ * **Updating patterns:**
+ * Change a pattern here and it automatically propagates to every consumer —
+ * the worker, the component paste handler, and the hook config message. There
+ * is no second place to update.
+ *
+ * **Adding a new pattern:**
+ * Add a new key/value pair to `FIELDSHIELD_PATTERNS`. The string must be a valid
+ * regex source. Use double backslashes for escape sequences since this is a
+ * string not a regex literal — `"\\d"` not `"\d"`.
+ *
+ * **Opt-in patterns:**
+ * Three patterns are exported separately in {@link OPT_IN_PATTERNS} because they
+ * produce unacceptably high false positive rates in free-text fields such as
+ * clinical notes. Use them via `customPatterns` only on fields where the specific
+ * data type is expected — see the JSDoc on each pattern for details.
+ *
+ * **Built-in pattern count: 13**
+ *
+ * @example
+ * ```ts
+ * import { FIELDSHIELD_PATTERNS } from "../patterns";
+ *
+ * // Build a RegExp from a pattern string
+ * const regex = new RegExp(FIELDSHIELD_PATTERNS.SSN, "gi");
+ * regex.test("372-84-1950"); // true
+ * ```
+ *
+ * @module patterns
+ */
+/**
+ * Built-in sensitive data patterns shipped with FieldShield (13 total).
+ *
+ * Keys are the pattern names surfaced in `findings` arrays and callback
+ * payloads (e.g. `"SSN"`, `"EMAIL"`). Values are regex source strings.
+ *
+ * Five additional patterns ({@link OPT_IN_PATTERNS}) are excluded from this
+ * set due to high false positive rates in free-text and clinical note fields.
+ * Use them via `customPatterns` only on fields where that data type is expected.
+ */
+export declare const FIELDSHIELD_PATTERNS: Readonly<Record<string, string>>;
+/**
+ * High false positive patterns — opt-in only.
+ *
+ * These five patterns were evaluated for inclusion in {@link FIELDSHIELD_PATTERNS}
+ * and excluded because they produce unacceptably high false positive rates in
+ * free-text fields, clinical notes, and general-purpose input fields.
+ *
+ * **Use via `customPatterns`** only on fields where the specific data type is
+ * known to be expected. Do not add these to free-text or clinical note fields.
+ *
+ * @example
+ * ```tsx
+ * import { OPT_IN_PATTERNS } from "fieldshield";
+ *
+ * // Only on a payment or banking field
+ * <FieldShieldInput
+ *   label="IBAN"
+ *   customPatterns={[{ name: "IBAN", regex: OPT_IN_PATTERNS.IBAN }]}
+ * />
+ *
+ * // Only on a DEA number entry field (prescriber credentialing)
+ * <FieldShieldInput
+ *   label="DEA Number"
+ *   customPatterns={[{ name: "DEA_NUMBER", regex: OPT_IN_PATTERNS.DEA_NUMBER }]}
+ * />
+ *
+ * // Only on a dedicated wire transfer form field
+ * <FieldShieldInput
+ *   label="Bank (SWIFT/BIC)"
+ *   customPatterns={[{ name: "SWIFT_BIC", regex: OPT_IN_PATTERNS.SWIFT_BIC }]}
+ * />
+ *
+ * // Only on a provider lookup field
+ * <FieldShieldInput
+ *   label="Provider NPI"
+ *   customPatterns={[{ name: "NPI_NUMBER", regex: OPT_IN_PATTERNS.NPI_NUMBER }]}
+ * />
+ *
+ * // Only on a passport / identity verification field
+ * <FieldShieldInput
+ *   label="Passport Number"
+ *   customPatterns={[{ name: "PASSPORT_NUMBER", regex: OPT_IN_PATTERNS.PASSPORT_NUMBER }]}
+ * />
+ * ```
+ */
+export declare const OPT_IN_PATTERNS: Readonly<Record<string, string>>;

package/dist/utils/collectSecureValue.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @file collectSecureValues.ts
+ * @description Utility for securely retrieving values from multiple
+ * FieldShieldInput fields simultaneously on form submission.
+ *
+ * @example
+ * ```tsx
+ * const refs = { ssn: ssnRef, apiKey: apiKeyRef, notes: notesRef };
+ *
+ * const handleSubmit = async () => {
+ *   const values = await collectSecureValues(refs);
+ *   await fetch("/api/submit", { body: JSON.stringify(values) });
+ *
+ *   purgeSecureValues(refs);
+ * };
+ * ```
+ *
+ * @module collectSecureValues
+ */
+import type { RefObject } from "react";
+import type { FieldShieldHandle } from "../components/FieldShieldInput";
+/**
+ * A map of field names to their FieldShieldHandle refs.
+ * Keys become the property names in the resolved values object.
+ *
+ * @example
+ * ```ts
+ * const refs: FieldShieldRefMap = {
+ *   ssn: ssnRef,
+ *   apiKey: apiKeyRef,
+ *   notes: notesRef,
+ * };
+ * ```
+ */
+export type FieldShieldRefMap = Record<string, RefObject<FieldShieldHandle | null>>;
+/**
+ * The resolved values object returned by {@link collectSecureValues}.
+ * Keys mirror the input `FieldShieldRefMap` — values are the retrieved
+ * plaintext strings, or `""` if the ref was unmounted or null.
+ */
+export type SecureValues<T extends FieldShieldRefMap> = Record<keyof T, string>;
+/**
+ * Retrieves real values from multiple FieldShieldInput fields in parallel
+ * via `Promise.allSettled`. Each value is fetched from the field's isolated Web
+ * Worker memory — no plaintext ever exists on the main thread until this
+ * call resolves.
+ *
+ * Null or unmounted refs resolve to `""` rather than throwing, so a missing
+ * optional field never blocks form submission.
+ *
+ * @param refs - Named map of FieldShieldHandle refs to collect from.
+ * @returns A promise resolving to an object with the same keys as `refs`,
+ *   each containing the retrieved plaintext string.
+ *
+ * @example
+ * ```tsx
+ * const ssnRef    = useRef<FieldShieldHandle>(null);
+ * const notesRef  = useRef<FieldShieldHandle>(null);
+ *
+ * const handleSubmit = async () => {
+ *   const { ssn, notes } = await collectSecureValues({ ssn: ssnRef, notes: notesRef });
+ *   await fetch("/api/patient", { body: JSON.stringify({ ssn, notes }) });
+ * };
+ * ```
+ *
+ * @remarks
+ * **Why named keys instead of an array?** An array of refs would resolve to
+ * an array of strings in positional order — callers would have to remember
+ * which index corresponds to which field. A named map produces a typed object
+ * where the field name is explicit at the call site and in the resolved value,
+ * making accidental field-order bugs impossible.
+ *
+ * **Why not a hook?** This function has no React state, no side effects, and
+ * no lifecycle dependency. Making it a hook would require consumers to call it
+ * inside `useCallback` and follow Rules of Hooks unnecessarily. A plain async
+ * function is the correct primitive here.
+ */
+export declare const collectSecureValues: <T extends FieldShieldRefMap>(refs: T) => Promise<SecureValues<T>>;
+/**
+ * Calls `purge()` on every ref in the map, zeroing out worker memory for all
+ * fields simultaneously. Call this immediately after `collectSecureValues`
+ * resolves and the data has been sent to your backend.
+ *
+ * Null or unmounted refs are silently skipped.
+ *
+ * @param refs - Named map of FieldShieldHandle refs to purge.
+ *
+ * @example
+ * ```ts
+ * const values = await collectSecureValues(refs);
+ * await sendToBackend(values);
+ * purgeSecureValues(refs); // fire-and-forget, no await needed
+ * ```
+ *
+ * @remarks
+ * `purge()` is synchronous — it posts a PURGE message to the worker with no
+ * response awaited. Calling `purgeSecureValues` immediately after
+ * `collectSecureValues` is safe because both the real value retrieval and
+ * the purge message travel through the same worker message queue in order.
+ * The PURGE message will always be processed after the GET_TRUTH reply.
+ */
+export declare const purgeSecureValues: (refs: FieldShieldRefMap) => void;