@jodetx_dev/secureshield-web 0.0.0-stage → 4.0.0

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,595 @@
+# 🛡️ SecureShield Web SDK — Universal Integration Guide
+
+> **Enterprise Zero-Trust Client Runtime Defense**  
+> Compatible with **ANY version** of Angular, React, Next.js, Vue, Nuxt, Svelte, Remix, Solid, Astro, Blazor, and Vanilla JavaScript.
+
+---
+
+## 🌐 Universal Framework Compatibility Guarantee
+
+SecureShield Web SDK (`@secureshield/web`) is compiled into clean, self-contained ECMAScript Modules (ESM), Universal Browser IIFE scripts, and an AST-Hardened Enterprise Edition. 
+* **Zero Runtime Dependencies**: The SDK has `0` external npm dependencies. It will **never** cause peer-dependency conflicts with your framework, bundler, or package manager.
+* **Forward & Backward Compatible**: Whether your project runs on legacy builds or next-generation compilers, SecureShield integrates seamlessly.
+
+| Framework | Supported Versions | Architectural Patterns Supported |
+| :--- | :--- | :--- |
+| **Angular** | **Angular 2 through 22+ (All versions & future releases)** | Modern Standalone (`provideAppInitializer`, Signals) & Classic NgModule (`APP_INITIALIZER`, RxJS) |
+| **React** | **React 15 through 19+ (All versions & future releases)** | Modern Hooks (`useContext`, `useEffect`, React Compiler) & Legacy Class Components (`HOC`) |
+| **Next.js** | **Next.js 9 through 15+ (App Router & Pages Router)** | Modern App Router (`'use client'`, `app/layout.tsx`) & Classic Pages Router (`pages/_app.tsx`) |
+| **Vue.js** | **Vue 2.0 through Vue 3.5+** | Vue 3 Composition API (`ref`, `<script setup>`) & Vue 2 Options API (`Vue.prototype`) |
+| **Nuxt** | **Nuxt 2 & Nuxt 3+** | Nuxt 3 Nitro Client Plugins (`.client.ts`) & Nuxt 2 Client Plugins |
+| **Svelte** | **Svelte 3, 4, and Svelte 5+** | Svelte 5 Runes (`$state`), SvelteKit & Classic Svelte Stores |
+| **Vite / Webpack** | **Vite 2 through 6+, Webpack 4 & 5, Turbopack, Rollup, esbuild, Bun** | Native ESM imports, resolve aliases, and bundled single-file formats |
+| **Vanilla Web** | **HTML5 / ES5 / ES6+** | Single-script `<script src="secureshield.js">` or `<script src="secureshield.hardened.js">` with Subresource Integrity (SRI) |
+
+---
+
+## 📦 What's Inside the Release ZIP
+
+When you extract `SecureShield_Web_SDK_Release.zip`, you get a complete, self-contained distribution package:
+
+```
+SecureShield_Web_SDK_Release/
+├── package.json               <-- 📦 NPM package descriptor (@secureshield/web)
+├── index.js                   <-- 🚀 Primary ESM entry point
+├── index.d.ts                 <-- 📘 TypeScript definitions (interfaces, types, configs)
+├── secureshield.js            <-- 🛡️ Option A: Drop-in IIFE for classic <script src="secureshield.js"> tags
+├── secureshield.iife.js       <-- 📦 Option A: Standalone IIFE build
+├── secureshield.esm.js        <-- ⚡ Option A: Standalone ES Module build
+├── secureshield.hardened.js   <-- 🛡️ Option B: Hardened AST-Obfuscated IIFE (drop-in <script> compatible)
+├── secureshield.wasm.js       <-- 🛡️ Option B: Drop-in alias for secureshield.hardened.js
+├── secureshield.hardened.esm.js <-- ⚡ Option B: Hardened AST-Obfuscated ES Module
+├── secureshield.js.sha256     <-- 🔒 Published SHA-256 Checksum (Option A Drop-in)
+├── secureshield.js.sri        <-- 🛡️ Subresource Integrity (SRI) Hash for <script> tags
+├── secureshield.esm.js.sha256 <-- 🔒 Published SHA-256 Checksum (Option A ESM)
+├── secureshield.esm.js.sri    <-- 🛡️ Subresource Integrity (SRI) Hash (Option A ESM)
+├── secureshield.iife.js.sha256<-- 🔒 Published SHA-256 Checksum (Option A IIFE)
+├── secureshield.iife.js.sri   <-- 🛡️ Subresource Integrity (SRI) Hash (Option A IIFE)
+├── secureshield.hardened.js.sha256 <-- 🔒 Published SHA-256 Checksum (Option B Hardened)
+├── secureshield.hardened.js.sri    <-- 🛡️ Subresource Integrity (SRI) Hash (Option B Hardened)
+├── secureshield.wasm.js.sha256<-- 🔒 Published SHA-256 Checksum (Option B alias)
+├── secureshield.wasm.js.sri   <-- 🛡️ Subresource Integrity (SRI) Hash for <script> tags
+├── SECURESHIELD_WEB_SDK_SPECIFICATION.md <-- 📑 Technical Specification
+├── INTEGRATION_GUIDE.md       <-- 📖 This Guide
+└── README.md                  <-- 📋 Quick Overview
+```
+
+### 🧪 Independent Verification Kit (`SecureShield_Verification_Kit.zip`)
+
+For security auditors and enterprise compliance teams requiring independent verification of the test suite and benchmark execution against compiled bundles:
+- **Download**: [`SecureShield_Verification_Kit.zip`](/downloads/SecureShield_Verification_Kit.zip)
+- **Published SHA-256**: `61129e02f00c24018900587d0de75d04ee4b52006fb93324bd6bb2042ce14025`
+- **Execution**: Zero-dependency air-gapped test runner (`npm test`) and latency benchmark (`npm run benchmark`).
+
+---
+
+## 🚀 Quick Setup: Extract & Install in 2 Minutes
+
+### Step 1: Extract into your project
+Extract the ZIP archive directly into your project's source tree (recommended location: `src/secureshield-sdk/`):
+
+```
+my-project/
+├── src/
+│   ├── secureshield-sdk/
+│   │   ├── package.json       <-- Ensure this is directly inside src/secureshield-sdk/
+│   │   ├── index.js
+│   │   ├── index.d.ts
+│   │   ├── secureshield.js
+│   │   └── secureshield.wasm.js
+```
+> [!IMPORTANT]
+> If Windows *"Extract All..."* created an extra folder named `SecureShield_Web_SDK_Release`, move the files out so that `package.json` is located directly at `src/secureshield-sdk/package.json`.
+
+### Step 2: Link the SDK package
+In your project terminal root, run:
+
+```bash
+npm install ./src/secureshield-sdk
+```
+*(Or for Yarn: `yarn add file:./src/secureshield-sdk` | PNPM: `pnpm add ./src/secureshield-sdk` | Bun: `bun add ./src/secureshield-sdk`)*
+
+Alternatively, add it directly to your `package.json`:
+```json
+{
+  "dependencies": {
+    "@secureshield/web": "file:src/secureshield-sdk"
+  }
+}
+```
+
+---
+
+## 🅰️ 1. Angular Integration (Universal: Any Version)
+
+### Pattern A: Modern Standalone & Signals (Angular 17, 18, 19, 20, 21, 22+ and Future)
+
+#### 1. Security Service (`src/app/services/secureshield.service.ts`):
+```typescript
+import { Injectable, signal, inject, PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { SecureShield, SecurityAuditReport } from '@secureshield/web';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class SecureShieldService {
+  private platformId = inject(PLATFORM_ID);
+  private sdkInstance: any = null;
+
+  // 🚦 Reactive Signals for UI bindings
+  public isShieldActive = signal<boolean>(false);
+  public trustScore = signal<number>(100);
+  public lastReport = signal<SecurityAuditReport | null>(null);
+
+  async initSecureShield(): Promise<void> {
+    // 🛡️ SSR Safety Guard
+    if (!isPlatformBrowser(this.platformId)) return;
+    if (this.sdkInstance) return;
+
+    try {
+      this.sdkInstance = await SecureShield.init({
+        tenantId: 'YOUR_TENANT_ID',
+        appId: 'YOUR_APP_ID',
+        serverUrl: 'https://security.yourcompany.com/api/v1/telemetry/ingest',
+        environment: 'production',
+        enableRuntimeIntegrityWatchdog: true,
+        enablePrototypeFreezing: false,
+        enableStorageLeakScrubber: true,
+        enableTabBlurShield: false,
+        onTamperDetected: (apiName: string, reason?: string) => {
+          console.warn(`[SecureShield Tamper Alert] ${apiName}: ${reason}`);
+        }
+      });
+
+      // Evaluate security state in background without stalling main render
+      setTimeout(async () => {
+        try {
+          const report = await this.sdkInstance.evaluateSecurityState();
+          this.lastReport.set(report);
+          this.trustScore.set(report.trustScore ?? 100);
+          this.isShieldActive.set(true);
+        } catch (e) {
+          console.warn('[SecureShield] Scan notice:', e);
+        }
+      }, 50);
+    } catch (error) {
+      console.error('[SecureShield] Initialization error:', error);
+    }
+  }
+
+  public isCleanForTransaction(): boolean {
+    return this.isShieldActive() && this.trustScore() >= 60;
+  }
+}
+```
+
+#### 2. App Initializer Bootloader (`src/app/app.config.ts`):
+```typescript
+import { ApplicationConfig, provideZonelessChangeDetection, provideAppInitializer, inject } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { routes } from './app.routes';
+import { SecureShieldService } from './services/secureshield.service';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes),
+    // 🛡️ Non-blocking startup hook (Angular 19, 20, 21, 22+)
+    provideAppInitializer(() => {
+      const shield = inject(SecureShieldService);
+      shield.initSecureShield().catch(err => console.warn('[SecureShield] Startup notice:', err));
+      return Promise.resolve(true); // Renders UI immediately in 0ms
+    })
+  ]
+};
+```
+*(For Angular 17 & 18 using `APP_INITIALIZER`: provide `{ provide: APP_INITIALIZER, useFactory: (s) => () => s.initSecureShield(), deps: [SecureShieldService], multi: true }`)*
+
+#### 3. Functional Route Security Guard (`src/app/guards/security.guard.ts`):
+```typescript
+import { inject } from '@angular/core';
+import { CanActivateFn, Router } from '@angular/router';
+import { SecureShieldService } from '../services/secureshield.service';
+
+export const securityGuard: CanActivateFn = async (route, state) => {
+  const shield = inject(SecureShieldService);
+  const router = inject(Router);
+
+  if (shield.isShieldActive() && !shield.isCleanForTransaction()) {
+    console.warn('[SecureShield Guard] Compromised environment — route blocked');
+    return router.parseUrl('/security-lockout');
+  }
+  return true;
+};
+```
+
+---
+
+### Pattern B: Classic NgModule & RxJS (Angular 2 through 16)
+
+#### 1. Module Provider (`src/app/app.module.ts`):
+```typescript
+import { NgModule, APP_INITIALIZER } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { AppComponent } from './app.component';
+import { SecureShieldService } from './services/secureshield.service';
+
+export function initSecurityFactory(shield: SecureShieldService) {
+  return () => shield.initSecureShield();
+}
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule],
+  providers: [
+    SecureShieldService,
+    {
+      provide: APP_INITIALIZER,
+      useFactory: initSecurityFactory,
+      deps: [SecureShieldService],
+      multi: true
+    }
+  ],
+  bootstrap: [AppComponent]
+})
+export class AppModule {}
+```
+
+---
+
+## ⚛️ 2. React Integration (Universal: React 15 → 19+)
+
+### Modern Pattern: Functional Components & Hooks (`src/providers/SecurityProvider.tsx`)
+*Compatible with React 16.8, 17, 18, 19+, Vite, Next.js, CRA, Remix, and React Compiler:*
+
+```tsx
+import React, { createContext, useContext, useEffect, useState } from 'react';
+import { SecureShield, SecurityAuditReport } from '@secureshield/web';
+
+interface SecurityContextType {
+  isShieldActive: boolean;
+  trustScore: number;
+  report: SecurityAuditReport | null;
+  shield: any;
+}
+
+const SecurityContext = createContext<SecurityContextType>({
+  isShieldActive: false,
+  trustScore: 100,
+  report: null,
+  shield: null
+});
+
+export function SecurityProvider({ children }: { children: React.ReactNode }) {
+  const [isShieldActive, setIsShieldActive] = useState(false);
+  const [trustScore, setTrustScore] = useState(100);
+  const [report, setReport] = useState<SecurityAuditReport | null>(null);
+  const [shield, setShield] = useState<any>(null);
+
+  useEffect(() => {
+    async function boot() {
+      try {
+        const instance = await SecureShield.init({
+          tenantId: 'YOUR_TENANT_ID',
+          appId: 'YOUR_APP_ID',
+          serverUrl: 'https://security.yourcompany.com/api/v1/telemetry/ingest',
+          environment: 'production',
+          enableRuntimeIntegrityWatchdog: true
+        });
+
+        setShield(instance);
+        const evalReport = await instance.evaluateSecurityState();
+        setReport(evalReport);
+        setTrustScore(evalReport.trustScore ?? 100);
+        setIsShieldActive(true);
+      } catch (err) {
+        console.error('[SecureShield] Boot failure:', err);
+      }
+    }
+    boot();
+  }, []);
+
+  return (
+    <SecurityContext.Provider value={{ isShieldActive, trustScore, report, shield }}>
+      {children}
+    </SecurityContext.Provider>
+  );
+}
+
+export const useSecurity = () => useContext(SecurityContext);
+```
+
+Wrap your root element in `src/App.tsx` or `src/main.tsx`:
+```tsx
+export function App() {
+  return (
+    <SecurityProvider>
+      <MainDashboard />
+    </SecurityProvider>
+  );
+}
+```
+
+---
+
+## ⚡ 3. Next.js Integration (Universal: Next.js 9 → 15+)
+
+### App Router (Next.js 13, 14, 15+ / React 18 & 19)
+
+#### 1. Configure `next.config.mjs`:
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@secureshield/web'],
+  webpack: (config, { isServer }) => {
+    if (!isServer) {
+      config.resolve.fallback = { ...config.resolve.fallback, fs: false, crypto: false };
+    }
+    return config;
+  }
+};
+export default nextConfig;
+```
+
+#### 2. Create Client Boundary (`src/app/providers/SecurityProvider.tsx`):
+```tsx
+'use client';
+
+import React from 'react';
+import { SecurityProvider } from './SecurityContext';
+
+export function NextSecurityProvider({ children }: { children: React.ReactNode }) {
+  return <SecurityProvider>{children}</SecurityProvider>;
+}
+```
+
+#### 3. Root Layout (`src/app/layout.tsx`):
+```tsx
+import { NextSecurityProvider } from './providers/SecurityProvider';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <NextSecurityProvider>
+          {children}
+        </NextSecurityProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Pages Router (Next.js 9 through 15+)
+In `pages/_app.tsx`:
+```tsx
+import type { AppProps } from 'next/app';
+import { SecurityProvider } from '../src/providers/SecurityProvider';
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <SecurityProvider>
+      <Component {...pageProps} />
+    </SecurityProvider>
+  );
+}
+```
+
+---
+
+## 🟢 4. Vue.js & Nuxt Integration (Universal: Vue 2 & 3+, Nuxt 2 & 3+)
+
+### Vue 3 Composition API (`src/plugins/secureshield.ts`):
+```typescript
+import { App, ref } from 'vue';
+import { SecureShield } from '@secureshield/web';
+
+export const isShieldActive = ref(false);
+export const trustScore = ref(100);
+
+export const SecureShieldPlugin = {
+  async install(app: App) {
+    if (typeof window === 'undefined') return; // SSR Guard
+    try {
+      const sdk = await SecureShield.init({
+        headerKey: 'YOUR_HEADER_KEY',
+        encryptionKey: 'YOUR_ENCRYPTION_KEY',
+        initializationKey: 'YOUR_INIT_KEY',
+        tenantId: 'YOUR_TENANT_ID',
+        appId: 'YOUR_APP_ID',
+        serverUrl: 'https://security.yourcompany.com/api/v1/telemetry/ingest'
+      });
+
+      const report = await sdk.evaluateSecurityState();
+      trustScore.value = report.trustScore ?? 100;
+      isShieldActive.value = true;
+    } catch (e) {
+      console.error('[SecureShield Vue Plugin] Error:', e);
+    }
+  }
+};
+```
+
+Mount in `src/main.ts`:
+```typescript
+import { createApp } from 'vue';
+import App from './App.vue';
+import { SecureShieldPlugin } from './plugins/secureshield';
+
+const app = createApp(App);
+app.use(SecureShieldPlugin);
+app.mount('#app');
+```
+
+---
+
+## 🌐 5. Vanilla HTML / JavaScript with Subresource Integrity (SRI)
+
+For websites without bundlers or package managers:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Secured Banking Portal</title>
+
+  <!-- Load SecureShield with SRI Hash Verification -->
+  <script 
+    src="./secureshield.js" 
+    integrity="sha384-01wWPFe5yTKeRD+REEsyC1+DsSbLaVqCdxcvB0hATty8z3cEN4wpczfO3rK049qL" 
+    crossorigin="anonymous">
+  </script>
+</head>
+<body>
+  <h1>Secure Dashboard</h1>
+  <script>
+    window.addEventListener('DOMContentLoaded', async () => {
+      const sdk = await window.SecureShield.init({
+        tenantId: 'YOUR_TENANT_ID',
+        appId: 'YOUR_APP_ID',
+        serverUrl: 'https://security.yourcompany.com/api/v1/telemetry/ingest'
+      });
+      const verdict = await sdk.evaluateSecurityState();
+      console.log('SecureShield Status:', verdict.verdict, 'Trust Score:', verdict.trustScore);
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 🛠️ Build Tooling & Version Troubleshooting Guide
+
+### Issue 1: Angular Build Version Mismatch
+**Error**:
+```
+Error: The current version of "@angular/build" supports Angular versions ^21.0.0,
+but detected Angular version 22.1.6 instead.
+```
+**Cause**: In Angular CLI, `@angular-devkit/build-angular` or `@angular/build` major version must match `@angular/core`.  
+**Fix**: Install the matching build package for your Angular version:
+```bash
+npm install --save-dev @angular-devkit/build-angular@^<YOUR_ANGULAR_MAJOR>.0.0 @angular/build@^<YOUR_ANGULAR_MAJOR>.0.0
+```
+
+### Issue 2: NPM `ENOENT: no such file or directory, open '...package.json'`
+**Cause**: When unzipping using Windows *"Extract All..."*, the files were placed inside an extra nested folder (e.g. `src/secureshield-sdk/SecureShield_Web_SDK_Release/package.json`).  
+**Fix**: Ensure all files are placed directly in `src/secureshield-sdk/` so `src/secureshield-sdk/package.json` exists, then re-run `npm install ./src/secureshield-sdk`.
+
+### Issue 3: Vite `Failed to resolve import "@secureshield/web"`
+**Fix**: Add an alias in `vite.config.ts`:
+```typescript
+import { fileURLToPath, URL } from 'node:url';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@secureshield/web': fileURLToPath(new URL('./src/secureshield-sdk', import.meta.url))
+    }
+  }
+});
+```
+
+### Issue 4: SSR / Hydration Mismatch
+**Fix**: Wrap initialization in browser guards (`isPlatformBrowser(this.platformId)` in Angular, `typeof window !== 'undefined'` in React/Vue/Svelte/Next.js).
+
+### Issue 5: Local Development Tunnel (ngrok) Interstitial Warning Page
+**Cause**: Free ngrok tunnels (`*.ngrok-free.dev` or `*.ngrok.app`) serve an HTML interstitial warning page on initial browser requests that lack the `ngrok-skip-browser-warning` header or bypass query parameter. Because production SDK releases do not attach non-standard tunneling headers to outbound HTTP requests, initial SDK handshake or telemetry requests routed to a free ngrok URL will receive an HTML warning page resulting in JSON parse errors.  
+**Fix**: When developing locally using free ngrok tunnels, use one of the following methods:
+1. Open the ngrok tunnel URL once in your browser and click **Visit Site** to set the bypass cookie for your browser session; or
+2. Upgrade to a paid ngrok account / custom domain which does not inject the interstitial page; or
+3. Append `?ngrok-skip-browser-warning=true` to your local development `serverUrl` endpoint (e.g. `serverUrl: 'https://<subdomain>.ngrok-free.dev/api/v1/telemetry/ingest?ngrok-skip-browser-warning=true'`).
+
+---
+
+## 🔒 Configuration Reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `headerKey` | `string` | Optional | Base64-encoded primary header cryptographic attestation key (legacy envelope auth). |
+| `encryptionKey` | `string` | Optional | AES-256 telemetry payload encryption key. |
+| `initializationKey` | `string` | Optional | Handshake signature authentication token. |
+| `tenantId` | `string` | **Required** | Tenant UUID registered in your SecureShield portal. |
+| `appId` | `string` | **Required** | Unique Application Identifier registered in your tenant portal. |
+| `serverUrl` | `string` | **Required** | Portal telemetry ingestion gateway endpoint (required in `production` and `staging`). |
+| `environment` | `'production' \| 'staging' \| 'development'` | `'production'` | Operational security policy environment (defaults to `'production'` fail-closed). |
+| `enablePrototypeFreezing` | `boolean` | `false` | When enabled, freezes built-in ECMAScript prototypes against tampering. Note: Prototype freezing is irreversible for the session once invoked, even if initialization fails. |
+| `enableRuntimeIntegrityWatchdog` | `boolean` | `true` | Real-time prototype tamper and hook interceptor. |
+| `enableStorageLeakScrubber` | `boolean` | `true` | Scans and purges exposed tokens from `localStorage`/`sessionStorage`. |
+| `enableTabBlurShield` | `boolean` | `false` | Automatically blurs sensitive content when the browser tab loses focus. |
+| `onTamperDetected` | `Function` | `undefined` | Callback invoked immediately when memory/DOM/prototype tampering is detected. |
+| `onRemediationTriggered` | `Function` | `undefined` | Callback invoked when server security remediation actions are executed. |
+
+---
+
+### ⚠️ Synchronous Configuration Validation & Error Handling (N-7)
+
+Both `new SecureShield(config)` and `SecureShield.init(config)` perform synchronous validation before initiating any asynchronous network requests. If any parameter is invalid (e.g. unrecognized `environment` string, or missing `serverUrl` in `production` mode), the SDK throws a synchronous `[SecureShield Configuration Error]`.
+
+Always wrap initialization in a `try...catch` block:
+
+```typescript
+try {
+  const sdk = await SecureShield.init({
+    tenantId: 'TEN-ENTERPRISE-01',
+    appId: 'my_app',
+    serverUrl: 'https://security.example.com/api/v1/telemetry/ingest',
+    environment: 'production'
+  });
+} catch (error) {
+  console.error('[SecureShield] Configuration or initialization error:', error);
+}
+```
+
+> [!NOTE]
+> When `enablePrototypeFreezing: true` is configured, ECMAScript prototypes are sealed immediately during the initialization pipeline to prevent malicious scripts from modifying built-ins. Once applied, prototype freezing remains permanent for the lifetime of the browser session regardless of whether the backend handshake succeeds or encounters a network failure.
+
+### 🛑 Runtime Pause State & Anti-Tamper Security (`setPaused`) (Finding R3-003)
+
+Direct invocation of `sdk.setPaused(boolean)` is restricted exclusively to local debugging in `'development'` mode.
+- In `production` or `staging`, calling `setPaused()` throws `[SecureShield Security Error] setPaused() is restricted in '<environment>'.` fail-closed to prevent client-side bypass of RASP threat detection.
+- In `development`, calling `setPaused()` emits `[SecureShield Deprecation] setPaused() is deprecated.`
+- To pause threat detection in production or staging, operators must issue server-signed Over-The-Air (OTA) remediation directives via the SecureShield portal (`signed_remediation` with ES256 cryptographic envelope).
+
+### 🔑 Cryptographic Policy & Offline Lease Verification (N-13 & N-3)
+
+SecureShield enforces hardware-grade WebCrypto cryptographic verification for all dynamic policies and offline leases:
+- **JWS Detached Envelopes**: All policies and leases are delivered inside JWS detached envelopes (`alg: "ES256"`, ECDSA P-256).
+- **Separated Key Architecture (G-N3-1, RO-1)**: Policy signing and offline lease signing employ independent cryptographic keypairs:
+  - Policy signing key ID: `secureshield_policy_p256_v3` (`typ: "secureshield-policy+jwt"`).
+  - Offline lease signing key ID: `secureshield_lease_p256_v3` (`typ: "secureshield-lease+jwt"`).
+  - *Legacy Key Revocation*: Compromised `v1` and `v2` keys are strictly revoked and rejected fail-closed in `production`.
+  Cross-envelope validation attempts fail immediately.
+- **Clock Skew Compensation & Reload Persistence (NI-3, G-N13-7)**: Server-provided timestamps calibrate the client clock with an asymmetric clamp of `[-300s, +3600s]` (+1 hour allowance for slow client device clocks, and -300s clamp to prevent expired replay via forged server time), persisted in `localStorage` across reloads to prevent expired envelope replay.
+- **Monotonic Anti-Replay (G-N13-6, NI-6)**: The SDK retains `#lastPolicyTimestamp` monotonically throughout the browser lifecycle (including across `clearSession()`), rejecting replayed configurations with earlier timestamps.
+- **Offline Grace Lease Security (N-3, G-N3-8)**:
+  - All legacy unsigned leases are revoked fail-closed.
+  - Server leases default to 24-hour expiration (`exp = iat + 86400s`), capped at a maximum of 7 days client-side.
+  - Encrypted at rest using non-exportable WebCrypto AES-GCM 256 keys in IndexedDB with graceful in-memory fallback upon storage quota rejection (`QuotaExceededError`).
+  - Monotonic clock check includes a 60-second backward NTP skew tolerance (`NI-4`).
+  - Explicit session termination via `sdk.clearSession()`, `sdk.logout()`, or `sdk.revokeSession()` wipes both the IndexedDB lease vault and volatile `sessionStorage` while retaining monotonic policy timestamps to prevent replay (`G-N3-7`).
+
+### 🛡️ Client-Side DOM Lockout Overlay Defense-in-Depth Disclaimer (N-9, RO-7, G-N9-3, G-N9-2)
+
+The `SecurityLockoutOverlay` provides active defense-in-depth UI friction against interactive tampering and unauthorized screen interaction during security lockouts:
+- **Active Tamper Watchdogs**: `MutationObserver` instances continuously monitor the DOM, tracking child removals and attribute/style modifications on `document.documentElement` and `document.body` (e.g. attempting to hide the lockout with `opacity: 0`, `visibility: hidden`, or `display: none`). Any suppression attempt triggers immediate automated restoration and re-mounting.
+- **Client-Side Friction Limitation**: Client-side DOM lockout overlays are designed to impede interactive attackers; they do not form an impenetrable security boundary against an adversary who has complete control over browser DevTools or runs unauthorized browser extensions.
+- **Definitive Security Enforcement**: Absolute lockout enforcement relies on the cryptographic purge performed by `RemediationManager.wipeLocalKeys()`, which purges non-exportable IndexedDB lease keys, session tokens, and cached credentials, coupled with server-side session revocation on the SecureShield gateway.
+
+### 🌐 Supported Browser Matrix & ES2020 Runtime Baseline (NI-8)
+
+The SecureShield Web SDK requires native ECMAScript 2020 (ES2020) language and runtime capabilities. Specifically, the SDK relies on native ECMAScript private class fields (`#privateField`), standard WebCrypto API (`crypto.subtle`), and IndexedDB:
+
+| Browser | Minimum Version | Platform Support | Status |
+| :--- | :--- | :--- | :--- |
+| **Google Chrome / Chromium** | **74+** | Windows, macOS, Linux, Android | Fully Supported |
+| **Mozilla Firefox** | **90+** | Windows, macOS, Linux, Android | Fully Supported |
+| **Apple Safari** | **14.1+** | macOS, iOS, iPadOS | Fully Supported |
+| **Microsoft Edge** | **79+** | Windows, macOS | Fully Supported |
+
+> [!WARNING]
+> Legacy browsers lacking support for ES2020 private class fields (e.g. Internet Explorer 11, legacy Edge < 79, Chrome < 74, Safari < 14.1) will fail during script parsing and are not supported. If legacy enterprise browser support is mandated, application build pipelines must transpile dependencies via Babel or SWC with private-field transforms enabled.
+
+

package/LICENSE

@@ -0,0 +1,36 @@
+SECURESHIELD COMMERCIAL SOFTWARE LICENSE AGREEMENT
+==================================================
+
+Notice to Users: This software is proprietary and confidential commercial software.
+Copyright (c) 2026 SecureShield Enterprise. All Rights Reserved.
+
+1. GRANT OF LICENSE
+Subject to the terms and conditions of an active Enterprise Master Services Agreement
+("MSA") or commercial software license subscription with SecureShield, you are granted
+a non-exclusive, non-transferable, revocable license to incorporate the compiled client
+SDK files into your web applications solely for the purpose of communicating with
+authorized SecureShield backend gateways and services.
+
+2. RESTRICTIONS
+Except as expressly permitted by your commercial license agreement, you shall not:
+(a) Reverse engineer, decompile, decrypt, disassemble, or derive the source code
+    of this SDK or any of its detection algorithms;
+(b) Sub-license, resell, rent, lease, or distribute standalone SDK binaries;
+(c) Modify, adapt, translate, or create derivative works of the SDK;
+(d) Remove, alter, or obscure any proprietary copyright notices, credentials,
+    or identification marks affixed to or contained within the SDK;
+(e) Bypass, disable, or circumvent any runtime protection or policy verification
+    checks implemented by the SDK.
+
+3. DISCLAIMER OF WARRANTY
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+4. TERMINATION
+This license terminates immediately upon expiration, termination, or cancellation
+of your commercial contract with SecureShield.
+
+For licensing inquiries, enterprise subscriptions, or compliance questions, contact:
+legal@secureshield.com
+