secure-ui-components 0.1.0-beta.1 → 0.1.2

package/README.md

@@ -1,49 +1,138 @@
 # secure-ui-components
 
-Security-first web component library with zero dependencies.
+Security-first Web Component library with built-in behavioral telemetry. Zero dependencies.
 
 **[Live Demo](https://barryprender.github.io/Secure-UI/)** — Try all components in your browser.
 
-## 🔒 Features
+## Features
 
-- **8 Secure Components**: Input, Textarea, Select, Form, File Upload, DateTime, Table, Submit Button
-- **4-Tier Security System**: PUBLIC, AUTHENTICATED, SENSITIVE, CRITICAL
-- **Progressive Enhancement**: Works without JavaScript
-- **Zero Dependencies**: Pure TypeScript, no runtime dependencies
-- **Fully Customizable**: CSS Design Tokens + CSS Parts API
-- **SSR Friendly**: Components render meaningful markup without JavaScript
-- **Comprehensive Testing**: Unit tests and security tests included
+- **10 Secure Components** — Input, Textarea, Select, Form, File Upload, DateTime, Table, Submit Button, Card, Telemetry Provider
+- **4-Tier Security System** — `public`, `authenticated`, `sensitive`, `critical`
+- **Behavioral Telemetry** — Every field collects typing patterns, paste detection, dwell time, and correction signals automatically
+- **Risk Scoring** — `<secure-form>` aggregates field signals into a session-level risk score at submission
+- **Signed Envelopes** — `<secure-telemetry-provider>` detects automation/headless browsers and signs every submission with HMAC-SHA-256
+- **Zero Dependencies** — Pure TypeScript, no runtime dependencies
+- **Progressive Enhancement** — All components render meaningful markup and work without JavaScript
+- **CSP-Safe** — Styles loaded via `<link>` from `'self'`; no `unsafe-inline` required
+- **SSR Friendly** — Adopts server-rendered markup on upgrade; no document access in constructors
+- **Fully Customisable** — CSS Design Tokens + `::part()` API
+- **Comprehensive Testing** — 869 tests, 80%+ branch coverage
 
-## 📦 Installation
+---
+
+## Philosophy: Security Telemetry as a First-Class Primitive
+
+Traditional form security stops at validation and CSRF protection. Secure-UI goes further — every form submission carries a behavioral fingerprint that travels alongside the user's data, giving the server the context it needs to distinguish real users from bots and credential stuffers in a single atomic request.
+
+```
+Field interaction  →  Behavioral signals  →  Risk score  →  Signed envelope
+(SecureBaseComponent)  (SecureForm)           (SecureForm)    (SecureTelemetryProvider)
+```
+
+**Layer 1 — Field-level signals** (`SecureBaseComponent`)
+Every secure field silently records: dwell time from focus to first keystroke, typing velocity, correction count (backspace/delete), paste detection, autofill detection, focus count, and blur-without-change patterns.
+
+**Layer 2 — Session aggregation** (`<secure-form>`)
+At submission, the form queries `getFieldTelemetry()` from every child field, produces per-field snapshots, and computes a composite risk score from 0–100. The telemetry payload travels alongside form data in a single `fetch` request as `_telemetry`.
+
+**Layer 3 — Environmental signals** (`<secure-telemetry-provider>`)
+An optional overlay that wraps `<secure-form>`. Monitors for WebDriver/headless flags, DOM script injection (via `MutationObserver`), devtools, suspicious screen dimensions, and pointer/keyboard activity. Signs the final envelope with HMAC-SHA-256 so the server can detect replay attacks.
+
+**What the server receives (enhanced submission):**
+
+```json
+{
+  "email": "user@example.com",
+  "password": "...",
+  "_telemetry": {
+    "sessionDuration": 14320,
+    "fieldCount": 2,
+    "riskScore": 5,
+    "riskSignals": [],
+    "submittedAt": "2026-03-12T18:30:00.000Z",
+    "fields": [
+      {
+        "fieldName": "email",
+        "fieldType": "secure-input",
+        "dwell": 420,
+        "completionTime": 3100,
+        "velocity": 4.2,
+        "corrections": 1,
+        "pasteDetected": false,
+        "autofillDetected": false,
+        "focusCount": 1,
+        "blurWithoutChange": 0
+      }
+    ],
+    "_env": {
+      "nonce": "a3f9...",
+      "issuedAt": "2026-03-12T18:30:00.000Z",
+      "environment": {
+        "webdriverDetected": false,
+        "headlessDetected": false,
+        "mouseMovementDetected": true,
+        "pointerType": "mouse"
+      },
+      "signature": "7d3a..."
+    }
+  }
+}
+```
+
+**Risk signals**
+
+| Signal | Condition | Score |
+|--------|-----------|-------|
+| `session_too_fast` | Submitted in under 3 s | +30 |
+| `session_fast` | Submitted in under 8 s | +10 |
+| `all_fields_pasted` | All fields pasted, no keystrokes | +25 |
+| `field_filled_without_focus` | Any field has `focusCount = 0` | +15 |
+| `high_velocity_typing` | Any field velocity > 15 ks/s | +15 |
+| `form_probing` | Field focused/blurred > 1× with no input | +10 |
+| `high_correction_count` | Any field with > 5 corrections | +5 |
+| `autofill_detected` | All fields autofilled (trust signal) | −10 |
+
+---
+
+## Installation
 
 ```bash
 npm install secure-ui-components
 ```
 
-## 🚀 Quick Start
+---
+
+## Quick Start
 
-### Bundler (Vite, Webpack, Rollup, etc.)
+### With telemetry (recommended)
 
-Import the components you need — each import auto-registers its custom element:
+```html
+<secure-telemetry-provider signing-key="your-per-session-secret">
+  <secure-form action="/api/login" method="POST" csrf-token="..." enhance>
+    <secure-input label="Email" name="email" type="email" required security-tier="authenticated"></secure-input>
+    <secure-input label="Password" name="password" type="password" required security-tier="critical"></secure-input>
+    <secure-submit-button label="Sign in" loading-label="Signing in…"></secure-submit-button>
+  </secure-form>
+</secure-telemetry-provider>
+```
 
 ```js
-import 'secure-ui-components/secure-input';
-import 'secure-ui-components/secure-form';
+document.querySelector('secure-form').addEventListener('secure-form-submit', (e) => {
+  const { formData, telemetry } = e.detail;
+  console.log('Risk score:', telemetry.riskScore);
+  console.log('Risk signals:', telemetry.riskSignals);
+});
 ```
 
-Then use them in your HTML:
+### Bundler (Vite, Webpack, Rollup)
 
-```html
-<secure-input
-  label="Email Address"
-  name="email"
-  type="email"
-  required
-  security-tier="authenticated"
-></secure-input>
+```js
+import 'secure-ui-components/secure-input';
+import 'secure-ui-components/secure-form';
+import 'secure-ui-components/secure-telemetry-provider';
 ```
 
-### CDN / Vanilla HTML (no bundler)
+### CDN / Vanilla HTML
 
 ```html
 <!DOCTYPE html>
@@ -52,13 +141,7 @@ Then use them in your HTML:
   <link rel="stylesheet" href="https://unpkg.com/secure-ui-components/dist/styles/tokens.css">
 </head>
 <body>
-  <secure-input
-    label="Email Address"
-    name="email"
-    type="email"
-    required
-    security-tier="authenticated"
-  ></secure-input>
+  <secure-input label="Email" name="email" type="email" required></secure-input>
 
   <script type="module">
     import 'https://unpkg.com/secure-ui-components/dist/index.js';
@@ -67,10 +150,77 @@ Then use them in your HTML:
 </html>
 ```
 
-## 🧩 Available Components
+---
+
+## Security Tiers
 
-### SecureInput
-Text input with security features and validation.
+All components accept a `security-tier` attribute. The default is `critical`.
+
+| Tier | Level | Masking | Autocomplete | Rate Limit | Audit |
+|------|-------|---------|--------------|------------|-------|
+| `public` | 1 | off | on | off | minimal |
+| `authenticated` | 2 | off | on | off | changes + submission |
+| `sensitive` | 3 | partial (last 4 chars) | off | 10/min | full |
+| `critical` | 4 | full | off | 5/min | full |
+
+```html
+<secure-input security-tier="public" label="Username" name="username"></secure-input>
+<secure-input security-tier="sensitive" label="Card Number" name="card"></secure-input>
+<secure-input security-tier="critical" type="password" label="Password" name="password"></secure-input>
+```
+
+The `security-tier` attribute is **immutable after connection** — changes after `connectedCallback` are silently ignored (fail-secure).
+
+---
+
+## Components
+
+### `<secure-input>`
+
+Text input with XSS prevention, masking, password strength validation, rate limiting, and automatic telemetry collection.
+
+**Attributes**
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `label` | string | Visible field label |
+| `name` | string | Form field name |
+| `type` | string | Input type — `text`, `password`, `email`, `tel`, `number`, `url`, `search` |
+| `placeholder` | string | Placeholder text |
+| `required` | boolean | Mark as required |
+| `disabled` | boolean | Disable the field |
+| `readonly` | boolean | Make read-only |
+| `pattern` | string | Regex validation pattern |
+| `minlength` | number | Minimum character length |
+| `maxlength` | number | Maximum character length |
+| `autocomplete` | string | Autocomplete hint (overridden to `off` for sensitive/critical) |
+| `value` | string | Initial value |
+| `security-tier` | string | `public` \| `authenticated` \| `sensitive` \| `critical` |
+
+**Properties & Methods**
+
+```js
+const el = document.querySelector('secure-input');
+
+el.value              // get current value (unmasked)
+el.value = 'foo'      // set value programmatically
+el.valid              // boolean — passes all validation rules
+el.name               // field name string
+el.getAuditLog()      // AuditLogEntry[]
+el.clearAuditLog()
+el.getFieldTelemetry() // FieldTelemetry — behavioral signals for this field
+el.focus()
+el.blur()
+```
+
+**Events**
+
+| Event | Detail |
+|-------|--------|
+| `secure-input` | `{ name, value, masked, tier }` |
+| `secure-audit` | `{ event, tier, timestamp, … }` |
+
+**Example**
 
 ```html
 <secure-input
@@ -82,48 +232,290 @@ Text input with security features and validation.
 ></secure-input>
 ```
 
-### SecureTextarea
-Multi-line text input with character counting.
+---
+
+### `<secure-textarea>`
+
+Multi-line input with real-time character counter, rate limiting, and automatic telemetry collection.
+
+**Attributes:** `label`, `name`, `placeholder`, `required`, `disabled`, `readonly`, `minlength`, `maxlength`, `rows`, `cols`, `wrap`, `value`, `security-tier`
+
+**Properties & Methods:** `value`, `name`, `valid`, `getAuditLog()`, `clearAuditLog()`, `getFieldTelemetry()`, `focus()`, `blur()`
+
+**Events:** `secure-textarea` → `{ name, value, tier }`
 
 ```html
 <secure-textarea
   label="Description"
   name="description"
-  rows="5"
   maxlength="500"
+  rows="5"
 ></secure-textarea>
 ```
 
-### SecureSelect
-Dropdown select with XSS prevention.
+---
+
+### `<secure-select>`
+
+Dropdown with option whitelist validation — prevents value injection. Telemetry collected on `change` events.
+
+**Attributes:** `label`, `name`, `required`, `disabled`, `multiple`, `size`, `value`, `security-tier`
+
+**Properties & Methods**
+
+```js
+el.value              // current value (comma-separated for multiple)
+el.selectedOptions    // string[] of selected values
+el.valid
+el.name
+el.addOption(value, text, selected?)
+el.removeOption(value)
+el.clearOptions()
+el.getAuditLog()
+el.getFieldTelemetry()
+el.focus()
+el.blur()
+```
+
+**Events:** `secure-select` → `{ name, value, tier }`
 
 ```html
-<secure-select
-  label="Country"
-  name="country"
-  required
->
+<secure-select label="Country" name="country" required>
+  <option value="">Select a country</option>
   <option value="us">United States</option>
   <option value="uk">United Kingdom</option>
 </secure-select>
 ```
 
-### SecureForm
-Form container with CSRF protection.
+Light DOM `<option>` children are transferred to the shadow DOM automatically. Only values added via `<option>` or `addOption()` are accepted.
+
+---
+
+### `<secure-form>`
+
+Form container with CSRF protection, field validation, behavioral telemetry aggregation, and optional fetch-enhanced submission.
+
+> `<secure-form>` uses **light DOM** (no Shadow DOM) for native form submission compatibility.
+
+**Attributes**
+
+| Attribute | Description |
+|-----------|-------------|
+| `action` | Form submission URL |
+| `method` | HTTP method (default `POST`) |
+| `enctype` | Encoding type |
+| `csrf-token` | CSRF token value injected as a hidden field |
+| `csrf-field-name` | Hidden field name (default `csrf_token`) |
+| `csrf-header-name` | Also send CSRF token in this request header |
+| `novalidate` | Disable browser constraint validation |
+| `enhance` | Enable fetch-based JSON submission instead of native |
+| `security-tier` | Security tier |
+
+**Properties & Methods**
+
+```js
+el.valid          // true if all secure child fields pass validation
+el.securityTier
+el.getData()      // { fieldName: value, … } including CSRF token
+el.reset()
+el.submit()       // programmatic submit (triggers validation + telemetry)
+```
+
+**Events**
+
+| Event | Detail |
+|-------|--------|
+| `secure-form-submit` | `{ formData, formElement, telemetry, preventDefault() }` — cancelable |
+| `secure-form-success` | `{ formData, response, telemetry }` — only when `enhance` is set |
+
+**`telemetry` shape** (`SessionTelemetry`):
+
+```ts
+{
+  sessionDuration: number;      // ms from form mount to submission
+  fieldCount: number;
+  fields: FieldTelemetrySnapshot[];
+  riskScore: number;            // 0–100
+  riskSignals: string[];        // e.g. ['session_too_fast', 'all_fields_pasted']
+  submittedAt: string;          // ISO 8601
+}
+```
+
+**Submission modes**
+
+- **Without `enhance`** — native browser form submission. Values from shadow DOM inputs are synced to hidden `<input type="hidden">` fields automatically. Telemetry is available in `secure-form-submit` but not sent to the server.
+- **With `enhance`** — intercepts submit, validates all fields, sends `{ ...formData, _telemetry }` as JSON via `fetch`. Full telemetry payload travels to the server in the same request.
+
+**Example**
 
 ```html
-<secure-form
-  action="/api/submit"
-  method="post"
-  csrf-token="your-token"
-  security-tier="sensitive"
->
-  <!-- Your form fields here -->
+<secure-form action="/api/register" method="POST" csrf-token="abc123" enhance>
+  <secure-input label="Email" name="email" type="email" required></secure-input>
+  <secure-input label="Password" name="password" type="password" required security-tier="critical"></secure-input>
+  <secure-submit-button label="Register"></secure-submit-button>
 </secure-form>
 ```
 
-### SecureFileUpload
-File upload with drag-drop and validation.
+```js
+form.addEventListener('secure-form-submit', (e) => {
+  const { formData, telemetry } = e.detail;
+
+  // Block high-risk submissions before they reach your server
+  if (telemetry.riskScore >= 50) {
+    e.detail.preventDefault();
+    showChallenge();
+    return;
+  }
+
+  // Log signals for your fraud pipeline
+  analytics.track('form_submit', {
+    risk: telemetry.riskScore,
+    signals: telemetry.riskSignals,
+  });
+});
+```
+
+---
+
+### `<secure-telemetry-provider>`
+
+Optional overlay that wraps `<secure-form>` to add environmental signals and HMAC-SHA-256 signing to every submission envelope.
+
+> Place this as the outer wrapper. It monitors the entire document for automation markers and DOM tampering during the session.
+
+**Attributes**
+
+| Attribute | Description |
+|-----------|-------------|
+| `signing-key` | HMAC-SHA-256 key — must also be known server-side to verify the signature |
+
+**Properties & Methods**
+
+```js
+const provider = document.querySelector('secure-telemetry-provider');
+
+provider.collectSignals()        // EnvironmentalSignals — point-in-time snapshot
+provider.getEnvironmentalSignals() // alias for collectSignals()
+provider.sign(signals)           // Promise<SignedTelemetryEnvelope>
+```
+
+**What it detects**
+
+| Signal | Description |
+|--------|-------------|
+| `webdriverDetected` | `navigator.webdriver` present or truthy |
+| `headlessDetected` | `HeadlessChrome` in userAgent or missing `window.chrome` |
+| `domMutationDetected` | New `<script>` element injected after page load |
+| `injectedScriptCount` | Count of dynamically added `<script>` elements |
+| `devtoolsOpen` | `outerWidth − innerWidth > 160` or `outerHeight − innerHeight > 160` |
+| `suspiciousScreenSize` | Screen width or height is zero or < 100px |
+| `pointerType` | Last pointer event type: `mouse` \| `touch` \| `pen` \| `none` |
+| `mouseMovementDetected` | Any `mousemove` event fired during session |
+| `keyboardActivityDetected` | Any `keydown` event fired during session |
+
+**How the envelope is injected**
+
+The provider listens for `secure-form-submit` on itself (bubbles from the nested form). It calls `sign()` asynchronously and attaches the result as `detail.telemetry._env`. Since it mutates the same object reference, any handler that awaits a microtask after the event fires will see `_env` populated.
+
+**Signed envelope shape** (`SignedTelemetryEnvelope`):
+
+```ts
+{
+  nonce: string;                   // 32-char random hex — detect replays
+  issuedAt: string;                // ISO 8601
+  environment: EnvironmentalSignals;
+  signature: string;               // HMAC-SHA-256 hex over nonce.issuedAt.JSON(environment)
+}
+```
+
+**Security notes**
+
+- The `signing-key` is a *symmetric* secret. For strong guarantees, rotate it per-session via a server nonce endpoint rather than hardcoding it as an attribute.
+- All signals are heuristic — a determined attacker can spoof them. The value is raising the cost of scripted attacks.
+- In non-secure contexts (`http://`) `SubtleCrypto` is unavailable; the signature will be an empty string. The server should treat unsigned envelopes with reduced trust.
+
+**Example**
+
+```html
+<secure-telemetry-provider signing-key="per-session-server-issued-key">
+  <secure-form action="/api/login" enhance csrf-token="...">
+    <secure-input label="Email" name="email" type="email" required></secure-input>
+    <secure-input label="Password" name="password" type="password" required security-tier="critical"></secure-input>
+    <secure-submit-button label="Sign in"></secure-submit-button>
+  </secure-form>
+</secure-telemetry-provider>
+```
+
+```js
+document.querySelector('secure-form').addEventListener('secure-form-submit', async (e) => {
+  const { telemetry } = e.detail;
+
+  // _env is populated async by the provider — wait a microtask
+  await Promise.resolve();
+
+  if (telemetry._env) {
+    console.log('Nonce:', telemetry._env.nonce);
+    console.log('Signature:', telemetry._env.signature);
+    // Verify signature server-side with the same key
+  }
+});
+```
+
+---
+
+### `<secure-file-upload>`
+
+Drag-and-drop file upload with content validation and optional malware scan hook.
+
+**Attributes**
+
+| Attribute | Description |
+|-----------|-------------|
+| `label` | Visible label |
+| `name` | Field name |
+| `accept` | Accepted MIME types / extensions (e.g. `image/*,.pdf`) |
+| `max-size` | Max file size in bytes |
+| `multiple` | Allow multiple files |
+| `required` | Mark as required |
+| `capture` | Camera capture hint |
+| `security-tier` | Security tier |
+
+**Size limits by tier (when `max-size` is not set)**
+
+| Tier | Limit |
+|------|-------|
+| `public` | 20 MB |
+| `authenticated` | 10 MB |
+| `sensitive` | 5 MB |
+| `critical` | 2 MB |
+
+**Properties & Methods**
+
+```js
+el.files          // FileList | null
+el.valid
+el.name
+el.hasScanHook    // boolean
+el.scanning       // boolean — true while scan hook is running
+el.clear()
+el.setScanHook(async (file) => { return { valid: true } })
+el.getAuditLog()
+```
+
+**Scan hook**
+
+```js
+upload.setScanHook(async (file) => {
+  const result = await myApi.scanFile(file);
+  return { valid: result.clean, reason: result.threat };
+});
+```
+
+**Events:** `secure-file-upload` → `{ name, files: File[], tier }`
+
+**Content validation (critical tier):** Magic number verification for JPEG, PNG, and PDF files.
+
+**Filename validation:** Blocks path traversal (e.g. `../`), null bytes, and dangerous config file names.
 
 ```html
 <secure-file-upload
@@ -131,62 +523,323 @@ File upload with drag-drop and validation.
   name="document"
   accept="image/*,.pdf"
   max-size="5242880"
+  security-tier="sensitive"
 ></secure-file-upload>
 ```
 
-### SecureDateTime
-Date and time picker with range validation.
+---
+
+### `<secure-datetime>`
+
+Date and time picker with format validation, range enforcement, and timezone display.
+
+**Attributes**
+
+| Attribute | Description |
+|-----------|-------------|
+| `label` | Visible label |
+| `name` | Field name |
+| `type` | `date` \| `time` \| `datetime-local` \| `month` \| `week` (default `date`) |
+| `min` | Minimum date/time (ISO format) |
+| `max` | Maximum date/time (ISO format) |
+| `step` | Step value |
+| `value` | Initial value (ISO format) |
+| `required` | Mark as required |
+| `disabled` | Disable the field |
+| `readonly` | Make read-only |
+| `show-timezone` | Display UTC offset alongside the input |
+| `security-tier` | Security tier |
+
+**Properties & Methods**
+
+```js
+el.value                     // ISO string
+el.value = '2025-06-15'      // set value
+el.valid
+el.name
+el.getValueAsDate()          // Date | null
+el.setValueFromDate(date)    // accepts Date object, sets formatted value
+el.getAuditLog()
+el.getFieldTelemetry()
+el.focus()
+el.blur()
+```
+
+**Events:** `secure-datetime` → `{ name, value, type, tier }`
+
+**CRITICAL tier:** Year must be between 1900 and 2100.
 
 ```html
 <secure-datetime
-  label="Birth Date"
-  name="birthdate"
-  type="date"
-  min="1900-01-01"
-  max="2025-12-31"
+  label="Appointment"
+  name="appointment"
+  type="datetime-local"
+  min="2025-01-01T00:00"
+  max="2030-12-31T23:59"
+  required
 ></secure-datetime>
 ```
 
-### SecureSubmitButton
-Accessible submit button with loading state and security integration.
+---
 
-```html
-<secure-submit-button label="Submit"></secure-submit-button>
-```
+### `<secure-table>`
 
-### SecureTable
-Data table with sorting, filtering, and pagination.
+Data table with sorting, filtering, pagination, and column-level data masking.
 
-```javascript
-const table = document.querySelector('secure-table');
+**Properties**
+
+```js
 table.data = [
-  { id: 1, name: 'John', email: 'john@example.com' },
-  { id: 2, name: 'Jane', email: 'jane@example.com' }
+  { id: 1, name: 'Alice', ssn: '123-45-6789' },
 ];
 table.columns = [
-  { key: 'id', label: 'ID', sortable: true },
+  { key: 'id',   label: 'ID',   sortable: true },
   { key: 'name', label: 'Name', sortable: true, filterable: true },
-  { key: 'email', label: 'Email', sortable: true, tier: 'sensitive' }
+  { key: 'ssn',  label: 'SSN',  tier: 'critical' },  // masked
+];
+```
+
+**Column definition**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | string | Data object key |
+| `label` | string | Column header text |
+| `sortable` | boolean | Enable click-to-sort |
+| `filterable` | boolean | Include in global search |
+| `tier` | string | Mask values at this tier level |
+| `width` | string | CSS column width |
+| `render` | `(value, row, key) => string` | Custom cell renderer |
+
+**Column masking**
+
+| Column `tier` | Behaviour |
+|---------------|-----------|
+| `sensitive` | Last 4 characters visible, rest masked (`••••4567`) |
+| `critical` | Fully masked (`••••••••`) |
+
+**Events:** `table-action` → `{ action, …data-attributes }` — fired when an element with `[data-action]` inside a cell is clicked.
+
+**Progressive enhancement:** Place a `<table slot="table">` with `data-key` attributes on `<th>` elements inside `<secure-table>` — the component reads columns and data from the server-rendered markup.
+
+```js
+table.columns = [
+  {
+    key: 'status',
+    label: 'Status',
+    render: (value) => `<span class="badge">${value}</span>`
+  }
 ];
 ```
 
-## 🎨 Customization
+---
+
+### `<secure-card>`
+
+Composite credit card form with a live 3D card preview, automatic card type detection, Luhn validation, expiry checking, and aggregate telemetry across all four fields. All inputs render inside a single closed Shadow DOM.
+
+**Security model:**
+- Full PAN and CVC are never included in events, audit logs, or hidden form inputs
+- CVC uses native `type="password"` masking — never visible on screen
+- Card number is masked to last-4 on blur
+- Security tier is locked to `critical` and cannot be changed
+- All sensitive state is wiped on `disconnectedCallback`
+- Telemetry from all four inputs (number, expiry, CVC, name) is aggregated into one composite behavioral fingerprint
+
+> Raw card data must be passed directly to a PCI-compliant payment processor SDK (e.g. Stripe.js, Braintree). Use `getCardData()` for that handoff — never send raw card numbers or CVCs to your own server.
+
+**Attributes**
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `label` | string | Legend text displayed above the fields |
+| `name` | string | Base name for hidden form inputs |
+| `show-name` | boolean | Show the optional cardholder name field |
+| `disabled` | boolean | Disable all fields |
+| `required` | boolean | Mark fields as required |
+
+**Properties & Methods**
+
+```js
+const card = document.querySelector('secure-card');
+
+card.valid              // true when all visible fields pass validation
+card.cardType           // 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unknown'
+card.last4              // last 4 digits — safe to display and log
+card.name               // value of the name attribute
+card.getCardData()      // { number, expiry, cvc, name } | null — for payment SDK only
+card.getFieldTelemetry() // composite behavioral signals across all 4 card inputs
+card.reset()
+card.focus()
+card.getAuditLog()
+```
+
+**Events**
+
+| Event | Detail |
+|-------|--------|
+| `secure-card` | `{ name, cardType, last4, expiryMonth, expiryYear, cardholderName, valid, tier }` |
+| `secure-audit` | `{ event, tier, timestamp, … }` |
+
+Note: the `secure-card` event detail intentionally omits the full PAN and CVC.
+
+**CSS Parts**
+
+| Part | Element |
+|------|---------|
+| `container` | Outer wrapper |
+| `label` | Legend element |
+| `wrapper` | Input wrapper (per field group) |
+| `number-input` | Card number `<input>` |
+| `expiry-input` | Expiry `<input>` |
+| `cvc-input` | CVC `<input>` |
+| `name-input` | Cardholder name `<input>` |
+| `error` | Error message container (per field) |
+
+**Card type detection**
+
+| Type | Detected prefix |
+|------|----------------|
+| Visa | `4` |
+| Mastercard | `51–55`, `2221–2720` |
+| Amex | `34`, `37` |
+| Discover | `6011`, `65xx` |
+| Diners | `300–305`, `36`, `38` |
+| JCB | `2131`, `1800`, `35xxx` |
+
+**Form participation**
+
+Three hidden inputs are created in the light DOM:
+- `{name}` — last 4 digits only (not full PAN)
+- `{name}-expiry` — MM/YY string
+- `{name}-holder` — cardholder name
+
+No hidden input is created for CVC.
+
+**Example**
+
+```html
+<secure-card name="payment" label="Card details" show-name></secure-card>
+```
+
+```js
+// When the user clicks Pay — pass directly to your payment SDK
+payButton.addEventListener('click', async () => {
+  const data = card.getCardData();
+  if (!data) return;
+  const token = await stripe.createToken({ number: data.number, exp_month: ..., cvc: data.cvc });
+  // Send token.id to your server — never data.number or data.cvc
+});
+```
+
+---
+
+### `<secure-submit-button>`
+
+Accessible submit button with loading state and automatic form-validity gating.
+
+**Attributes:** `label`, `loading-label`, `disabled`, `security-tier`
 
-### Using Design Tokens
+**Properties**
+
+```js
+el.disabled
+el.label
+el.getAuditLog()
+```
+
+**Behaviour**
+
+- For `authenticated`, `sensitive`, and `critical` tiers: button remains disabled until all required `<secure-input>`, `<secure-textarea>`, `<secure-select>`, and `<secure-datetime>` siblings report `valid = true`.
+- Shows a spinner and `loading-label` during form submission.
+- Rate-limited at `sensitive` / `critical` tiers.
+
+```html
+<secure-submit-button label="Submit" loading-label="Submitting…"></secure-submit-button>
+```
+
+---
+
+## Common Attributes
+
+All field components support:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `label` | string | Visible field label |
+| `name` | string | Form field name |
+| `required` | boolean | Mark field as required |
+| `disabled` | boolean | Disable the field |
+| `readonly` | boolean | Make the field read-only |
+| `security-tier` | string | `public` \| `authenticated` \| `sensitive` \| `critical` (default: `critical`) |
+
+## Common Properties & Methods
+
+All field components expose these in addition to component-specific methods:
+
+```js
+el.value             // get/set current value
+el.valid             // boolean — passes all validation rules
+el.name              // field name string
+el.securityTier      // current security tier
+el.getAuditLog()     // AuditLogEntry[]
+el.clearAuditLog()
+el.getFieldTelemetry() // FieldTelemetry — behavioral signals (no raw values)
+el.focus()
+el.blur()
+```
+
+**`FieldTelemetry` shape:**
+
+```ts
+{
+  dwell: number;              // ms from focus to first keystroke
+  completionTime: number;     // ms from first keystroke to blur
+  velocity: number;           // keystrokes per second
+  corrections: number;        // backspace / delete event count
+  pasteDetected: boolean;
+  autofillDetected: boolean;
+  focusCount: number;
+  blurWithoutChange: number;  // focused but left without typing
+}
+```
+
+## Common Events
+
+| Event | Fired by | Detail |
+|-------|----------|--------|
+| `secure-input` | `<secure-input>` | `{ name, value, masked, tier }` |
+| `secure-textarea` | `<secure-textarea>` | `{ name, value, tier }` |
+| `secure-select` | `<secure-select>` | `{ name, value, tier }` |
+| `secure-datetime` | `<secure-datetime>` | `{ name, value, type, tier }` |
+| `secure-file-upload` | `<secure-file-upload>` | `{ name, files, tier }` |
+| `secure-form-submit` | `<secure-form>` | `{ formData, formElement, telemetry, preventDefault() }` |
+| `secure-form-success` | `<secure-form>` | `{ formData, response, telemetry }` |
+| `secure-card` | `<secure-card>` | `{ name, cardType, last4, expiryMonth, expiryYear, cardholderName, valid, tier }` |
+| `secure-audit` | all components | `{ event, tier, timestamp, … }` |
+| `table-action` | `<secure-table>` | `{ action, row }` |
+
+---
+
+## Customisation
+
+### CSS Design Tokens
+
+Override tokens at `:root` to theme all components globally:
 
 ```css
 :root {
-  /* Override global colors */
-  --secure-ui-color-primary: #your-brand-color;
+  --secure-ui-color-primary: #6366f1;
   --secure-ui-input-border-radius: 8px;
-  --secure-ui-font-family-base: 'Your Font', sans-serif;
+  --secure-ui-font-family-base: 'Inter', sans-serif;
 }
 ```
 
-### Using CSS Parts API
+### CSS Parts API
+
+Style internal elements directly:
 
 ```css
-/* Style internal elements */
 secure-input::part(label) {
   font-weight: 700;
   text-transform: uppercase;
@@ -202,109 +855,65 @@ secure-input::part(error) {
 }
 ```
 
-See the [Customization Guide](https://github.com/Barryprender/Secure-UI/blob/main/secure-ui-components/docs/customization.md) for a complete styling guide with examples.
+**Available parts on all components:** `container`, `label`, `wrapper`, `input` / `textarea` / `select`, `error`
 
-## 🔐 Security Tiers
+See the [Customization Guide](https://github.com/Barryprender/Secure-UI/blob/main/secure-ui-components/docs/customization.md) for a full token reference.
 
-```html
-<!-- PUBLIC: Basic validation -->
-<secure-input security-tier="public"></secure-input>
+---
 
-<!-- AUTHENTICATED: Enhanced validation, detailed logging -->
-<secure-input security-tier="authenticated"></secure-input>
+## Per-Component Imports
 
-<!-- SENSITIVE: Strict validation, autocomplete disabled -->
-<secure-input security-tier="sensitive"></secure-input>
+Import only what you need:
 
-<!-- CRITICAL: Maximum security, masking, rate limiting -->
-<secure-input security-tier="critical" type="password"></secure-input>
+```js
+import 'secure-ui-components/secure-input';
+import 'secure-ui-components/secure-textarea';
+import 'secure-ui-components/secure-select';
+import 'secure-ui-components/secure-form';
+import 'secure-ui-components/secure-file-upload';
+import 'secure-ui-components/secure-datetime';
+import 'secure-ui-components/secure-table';
+import 'secure-ui-components/secure-card';
+import 'secure-ui-components/secure-telemetry-provider';
 ```
 
-## 🧪 Testing
-
-All components include comprehensive tests:
-
-```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
+Or import everything at once:
 
-# Run tests with coverage report
-npm run test:coverage
+```js
+import 'secure-ui-components';
 ```
 
-## 📖 Documentation
-
-- [Customization Guide](https://github.com/Barryprender/Secure-UI/blob/main/secure-ui-components/docs/customization.md) - Complete styling guide
-- [Architecture](https://github.com/Barryprender/Secure-UI/blob/main/secure-ui-components/docs/ARCHITECTURE.md) - Technical architecture details
-
-## 📝 API Reference
-
-### Common Attributes
-
-All components support:
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `label` | `string` | Visible field label |
-| `name` | `string` | Form field name |
-| `required` | `boolean` | Mark field as required |
-| `disabled` | `boolean` | Disable the field |
-| `readonly` | `boolean` | Make the field read-only |
-| `security-tier` | `string` | Security level: `public`, `authenticated`, `sensitive`, `critical` (default: `critical`) |
-
-### Common Properties / Methods
+---
 
-```js
-const el = document.querySelector('secure-input');
+## Testing
 
-el.value          // get current value (unmasked)
-el.value = 'foo'  // set value programmatically
-el.valid          // boolean — passes all validation rules
-el.name           // field name string
-el.getAuditLog()  // returns array of security audit log entries
+```bash
+npm test                # run all tests
+npm run test:watch      # watch mode
+npm run test:coverage   # coverage report
 ```
 
-`secure-file-upload` also exposes:
+---
 
-```js
-el.files          // FileList | null
-el.clear()        // clear selected files
-el.hasScanHook    // boolean
-el.scanning       // boolean — true while scan hook is running
-el.setScanHook(async (file) => { return { valid: true } })
-```
+## Documentation
 
-### Common Events
+- [Customization Guide](https://github.com/Barryprender/Secure-UI/blob/main/secure-ui-components/docs/customization.md)
+- [Architecture](https://github.com/Barryprender/Secure-UI/blob/main/secure-ui-components/docs/ARCHITECTURE.md)
+- [Live Demo](https://barryprender.github.io/Secure-UI/)
 
-| Event | Fired by | Detail |
-|-------|----------|--------|
-| `secure-input` | `secure-input` | `{ name, value, masked, tier }` |
-| `secure-textarea` | `secure-textarea` | `{ name, value, tier }` |
-| `secure-select` | `secure-select` | `{ name, value, tier }` |
-| `secure-datetime` | `secure-datetime` | `{ name, value, type, tier }` |
-| `secure-file-upload` | `secure-file-upload` | `{ name, files, tier }` |
-| `secure-form-submit` | `secure-form` | `{ formData, formElement, preventDefault }` |
-| `secure-form-success` | `secure-form` | `{ formData, response }` |
-| `secure-audit` | all components | `{ event, tier, timestamp, … }` |
-| `table-action` | `secure-table` | `{ action, row }` |
+---
 
-## 🤝 Contributing
+## Contributing
 
-Contributions are welcome! Please see the main repository for guidelines.
+Contributions are welcome. Please see the main repository for guidelines.
 
-## 📄 License
+## License
 
-MIT License - see LICENSE file for details.
+MIT — see LICENSE file for details.
 
-## 🔗 Links
+## Links
 
 - [GitHub Repository](https://github.com/Barryprender/Secure-UI)
+- [npm Package](https://www.npmjs.com/package/secure-ui-components)
 - [Live Demo](https://barryprender.github.io/Secure-UI/)
-
-## 🆘 Support
-
 - [Issue Tracker](https://github.com/Barryprender/Secure-UI/issues)
-- [Discussions](https://github.com/Barryprender/Secure-UI/discussions)