@tindalabs/shield 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Iker Laforga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE 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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,357 @@
+# @tindalabs/shield
+
+[![npm version](https://img.shields.io/npm/v/@tindalabs/shield.svg)](https://www.npmjs.com/package/@tindalabs/shield)
+[![CI](https://github.com/tindalabs/shield/actions/workflows/ci.yml/badge.svg)](https://github.com/tindalabs/shield/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Zero runtime dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](./package.json)
+
+**Browser tamper detection for hostile environments.**
+
+Shield detects DevTools, automation drivers, extension injection, and environment spoofing — surfaces findings as structured risk signals composable with [Blindspot](https://github.com/tindalabs/blindspot) spans and [Scent](https://github.com/tindalabs/scent) identity risk scoring.
+
+---
+
+## Install
+
+```bash
+npm install @tindalabs/shield
+```
+
+---
+
+## Quick start — `assess()`
+
+The primary API is a single async call that returns structured signals, a risk summary, and OTel-compatible span attributes:
+
+```ts
+import { assess } from '@tindalabs/shield';
+
+const result = await assess();
+
+console.log(result.signals);
+// {
+//   'shield.devtools.open': false,
+//   'shield.automation.webdriver': false,
+//   'shield.automation.headless': false,
+//   'shield.frame.embedded': false,
+//   'shield.extension.detected': false,
+//   'shield.extension.names': '',
+// }
+
+console.log(result.risk);
+// { score: 0, flags: [] }
+
+// Attach to a Blindspot / OpenTelemetry span
+span.setAttributes(result.spanAttributes);
+```
+
+### With Blindspot
+
+```ts
+import { assess } from '@tindalabs/shield';
+import { useSpan } from '@tindalabs/blindspot-react';
+
+const { setAttribute } = useSpan();
+const shield = await assess();
+Object.entries(shield.spanAttributes).forEach(([k, v]) => setAttribute(k, v));
+```
+
+### With Scent
+
+Shield's signals compose directly with Scent's identity and risk engine:
+
+```ts
+import { assess } from '@tindalabs/shield';
+import { init as initScent } from '@tindalabs/scent-sdk';
+
+const scent = initScent({ apiKey: '...', endpoint: '...' });
+const shield = await assess();
+
+// shield.signals merges into the snapshot alongside browser fingerprint signals
+const obs = await scent.observe({ extraSignals: shield.signals });
+await scent.flush();
+// The server risk engine now sees webdriver/headless/devtools signals
+// alongside canvas, fonts, hardware and all other collected signals.
+```
+
+---
+
+## `assess(options?)` reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `devtools` | `boolean` | `true` | Run DevTools detection (async, timing-based) |
+| `extensions` | `boolean` | `true` | Run browser extension DOM/JS scan |
+| `timeout` | `number` | `400` | Max ms before async detections resolve with `false` |
+| `extensionConfig` | `ExtensionConfig[]` | built-in | Extension signatures to check against |
+
+### `ShieldAssessment`
+
+```ts
+interface ShieldAssessment {
+  signals: {
+    'shield.devtools.open': boolean;
+    'shield.automation.webdriver': boolean;
+    'shield.automation.headless': boolean;
+    'shield.frame.embedded': boolean;
+    'shield.extension.detected': boolean;
+    'shield.extension.names': string; // comma-separated
+  };
+  risk: {
+    score: number;   // 0–1 normalised threat score
+    flags: string[]; // ['webdriver', 'devtools_open', ...]
+  };
+  spanAttributes: Record<string, string | boolean | number>;
+}
+```
+
+### Risk flags and weights
+
+| Flag | Score contribution | Triggered by |
+|---|---|---|
+| `webdriver` | 0.9 | `navigator.webdriver === true` |
+| `headless` | 0.7 | Headless UA string, zero plugins, missing Permissions API |
+| `devtools_open` | 0.4 | Timing/debugger/size detectors |
+| `frame_embedded` | 0.3 | `window.self !== window.top` (cross-origin) |
+| `extension` | 0.2 | DOM selector or JS global signature match |
+
+---
+
+## Risk-gated protection — `assessAndProtect()`
+
+`assessAndProtect()` bridges both APIs with a declarative policy engine. It runs `assess()`, evaluates a set of rules against the result, and activates a `ContentProtector` with exactly the strategies each session warrants — zero overhead for legitimate users, full defence for automation and high-risk sessions.
+
+```ts
+import { assessAndProtect } from '@tindalabs/shield';
+
+const { assessment, protector } = await assessAndProtect(contentEl, {
+  policies: [
+    // Watermark any session with measurable risk — embed score for traceability
+    {
+      when: { riskScore: { gte: 0.2 } },
+      enable: ['enableWatermark'],
+      watermarkOptions: (a) => ({ text: `RISK-${Math.round(a.risk.score * 100)}` }),
+    },
+    // Selection + clipboard lockdown for high-risk sessions
+    {
+      when: { riskScore: { gte: 0.6 } },
+      enable: ['preventSelection', 'preventClipboard', 'preventKeyboardShortcuts'],
+    },
+    // Always block headless browsers regardless of score
+    {
+      when: { signals: { 'shield.automation.headless': true } },
+      enable: ['preventScreenshots', 'preventContextMenu'],
+    },
+  ],
+});
+
+// protector is null when no rules matched (legitimate session — no overhead)
+if (protector) {
+  console.log('Protection active — score:', assessment.risk.score);
+}
+```
+
+All matched rules are merged: a session with score `0.8` triggers watermark + selection + clipboard + keyboard in one pass.
+
+### With OTel / Blindspot
+
+Pass a `spanEmitter` to emit `shield.policy.triggered` events and wire `ContentProtector` callbacks to child spans:
+
+```ts
+import { assessAndProtect } from '@tindalabs/shield';
+import { getTracer, getRouteContext } from '@tindalabs/blindspot';
+
+await assessAndProtect(contentEl, {
+  policies: [/* ... */],
+  spanEmitter: (name, attrs) => {
+    const span = getTracer().startSpan(name, { attributes: attrs }, getRouteContext());
+    span.end();
+  },
+});
+```
+
+### `PolicyEngineOptions`
+
+| Option | Type | Description |
+|---|---|---|
+| `policies` | `PolicyRule[]` | Ordered list of rules. All matching rules are merged. |
+| `targetElement` | `HTMLElement \| null` | Element to protect. Defaults to `document.body`. |
+| `customHandlers` | `CustomEventHandlers` | Forwarded to `ContentProtector`. |
+| `spanEmitter` | `SpanEmitter` | Uses `attachShieldToSpan` and emits policy OTel events. |
+| `assessOptions` | `AssessOptions` | Forwarded to the internal `assess()` call. |
+
+### `PolicyRule`
+
+| Field | Type | Description |
+|---|---|---|
+| `when` | `PolicyCondition` | Conditions that must all match. An empty `{}` always matches. |
+| `enable` | `StrategyKey[]` | Strategies to activate when the condition matches. |
+| `watermarkOptions` | `WatermarkOptions \| (a: ShieldAssessment) => WatermarkOptions` | Static or factory watermark config. Last matched rule wins. |
+
+### `PolicyCondition`
+
+| Field | Type | Description |
+|---|---|---|
+| `riskScore.gte` | `number` | Score must be ≥ this value. |
+| `riskScore.lt` | `number` | Score must be < this value. |
+| `signals` | `Partial<ShieldSignals>` | All listed signal values must match. |
+
+### OTel events emitted
+
+| Event | When |
+|---|---|
+| `shield.policy.triggered` | At least one rule matched — includes `shield.policy.risk_score`, `shield.policy.matched_rules`, `shield.policy.enabled_strategies` |
+| `shield.policy.evaluated` | No rules matched — includes `shield.policy.matched_rules: 0`, `shield.policy.protection_activated: false` |
+
+---
+
+## Use cases — adaptive content protection
+
+`assessAndProtect()` exists for the awkward middle ground: blanket protection breaks the experience for legitimate users, but no protection lets scrapers walk away with everything. The policy engine activates only the strategies the session's risk profile warrants — humans see nothing, automation hits a wall.
+
+### Anti-AI scraping
+
+LLM training crawlers, prompt-based scrapers, and headless research agents share the same signal profile as conventional automation: `shield.automation.webdriver`, `shield.automation.headless`, patched-API heuristics, missing plugin metadata. A single policy rule flips watermarking and selection/clipboard lockdown on those sessions while human visitors get the unmodified page.
+
+The `watermarkOptions` factory receives the full assessment, so anything that *does* get scraped carries a forensic trace back to the session that extracted it:
+
+```ts
+{
+  when: { signals: { 'shield.automation.headless': true } },
+  enable: ['enableWatermark', 'preventSelection', 'preventClipboard'],
+  watermarkOptions: (a) => ({
+    text: `SHIELD-${Math.round(a.risk.score * 100)}-${Date.now().toString(36)}`,
+  }),
+}
+```
+
+Pair with `spanEmitter` and every triggered rule emits `shield.policy.triggered` to your OTel pipeline — operators can see in real time *how often, and by what signal,* their content is being targeted, without instrumenting strategies by hand.
+
+### Risk-proportional DRM
+
+Financial, legal, and media documents need strong protection — but blanket DRM breaks screen readers, accessibility tooling, and developers debugging their own portal. Risk-keyed policy rules flip protection on only when warranted (high risk, automation signals, specific extensions) and leave the long tail of normal sessions completely untouched. The same engine handles both ends of the risk spectrum with one config.
+
+### When *not* to reach for it
+
+If every session needs the same protection (e.g. a known-private internal tool where any visitor is high-trust by definition), skip the engine and use `ContentProtector` directly (next section). `assessAndProtect()` adds an `assess()` round trip and is only worth it when protection should vary per session.
+
+---
+
+## Active protection — `ContentProtector`
+
+Shield also exports the full protection suite for active content defense: blocks DevTools, prevents copy/print/selection, adds watermarks, detects extension injection and iframe embedding.
+
+```ts
+import { ContentProtector } from '@tindalabs/shield';
+
+const protector = new ContentProtector({
+  preventDevTools: true,
+  preventKeyboardShortcuts: true,
+  preventPrinting: true,
+  preventClipboard: true,
+  clipboardOptions: { preventCopy: true, preventCut: true, preventPaste: false },
+  enableWatermark: true,
+  watermarkOptions: { text: 'Confidential', userId: 'user-123' },
+  // …and more (selection, context menu, screenshots, extensions, iframe embedding)
+  // — see REFERENCE.md for the complete options table.
+});
+
+protector.protect();
+
+// Later:
+protector.unprotect();
+protector.dispose();
+```
+
+See [REFERENCE.md](./REFERENCE.md) for the full `ContentProtector` API and all strategy options.
+
+---
+
+## OTel-instrumented protection — `attachShieldToSpan()`
+
+`attachShieldToSpan()` is a thin wrapper around `ContentProtector` that turns every protection event into a span event. Each blocked copy, print, keyboard shortcut, devtools open, or screenshot attempt becomes a `shield.*` event in your tracing pipeline — no manual callback wiring per strategy.
+
+Shield is framework-agnostic about OTel — it doesn't depend on `@opentelemetry/api`. You provide a `SpanEmitter` callback; Shield calls it.
+
+```ts
+import { attachShieldToSpan } from '@tindalabs/shield';
+
+const protector = attachShieldToSpan(
+  { preventClipboard: true, enableWatermark: true, watermarkOptions: { text: 'Confidential' } },
+  (name, attrs) => span.addEvent(name, attrs),
+);
+
+protector.protect();
+```
+
+### With Blindspot
+
+```ts
+import { attachShieldToSpan } from '@tindalabs/shield';
+import { getTracer, getRouteContext } from '@tindalabs/blindspot';
+
+const protector = attachShieldToSpan(
+  { preventClipboard: true, preventScreenshots: true },
+  (name, attrs) => {
+    const span = getTracer().startSpan(name, { attributes: attrs }, getRouteContext());
+    span.end();
+  },
+);
+
+protector.protect();
+```
+
+Emitting each event as a short-lived span (start + immediately end) means findings reach Tempo/Honeycomb/Jaeger without waiting for the long-lived navigation span to close.
+
+### Events emitted
+
+| Event name | Fires when | Attributes |
+|---|---|---|
+| `shield.devtools.opened` / `shield.devtools.closed` | DevTools state changes | — |
+| `shield.selection.attempted` | User tries to select content | — |
+| `shield.context_menu.attempted` | Right-click / long-press | — |
+| `shield.print.attempted` | Print dialog opens | — |
+| `shield.keyboard_shortcut.blocked` | Blocked shortcut fires | `shield.keyboard.key`, `shield.keyboard.code` |
+| `shield.clipboard.copy` / `.cut` / `.paste` | Clipboard action attempted | — |
+| `shield.screenshot.attempted` | PrintScreen / Win+Shift+S / Cmd+Shift+3/4/5 | — |
+| `shield.extension.detected` | Known scraping extension found | `shield.extension.id`, `shield.extension.name`, `shield.extension.risk` |
+| `shield.frame.embedding.detected` | Page rendered inside an iframe | `shield.frame.external` |
+| `shield.protection.bypassed` | A protection strategy was circumvented | `shield.bypass.method` |
+| `shield.content.hidden` / `.restored` | Protected content toggled | `shield.hidden.reason` (hidden only) |
+
+Emitter exceptions are swallowed — telemetry sink failure never crashes the protected page. Any `customHandlers` you also pass in `options` still get called after the emit.
+
+Pair with `assess()` for an end-to-end picture: route-level risk score plus per-interaction protection events, all keyed off the same span.
+
+---
+
+## Demo
+
+A local demo app is included at [`demo/`](./demo). It exercises both APIs in a dark-themed single-page app:
+
+- **Environment Assessment** — runs `assess()` and displays each signal, the risk score bar, and the raw OTel span attributes ready to copy.
+- **Active Content Protection** — full `ContentProtector` controls: every strategy toggle, watermark options, live events log.
+
+```bash
+cd demo
+npm install
+npm run dev   # http://localhost:5175 (or next available port)
+```
+
+---
+
+## The Tindalabs stack
+
+Shield is one of three composable browser-layer packages:
+
+| Package | What it does |
+|---|---|
+| **[@tindalabs/blindspot](https://github.com/tindalabs/blindspot)** | Privacy-first OTel frontend observability |
+| **[@tindalabs/shield](https://github.com/tindalabs/shield)** | Tamper detection & active content protection |
+| **[@tindalabs/scent](https://github.com/tindalabs/scent)** | Probabilistic identity continuity |
+
+---
+
+## License
+
+MIT © [Tindalabs](https://github.com/tindalabs)

package/dist/assess.d.ts

@@ -0,0 +1,16 @@
+import type { AssessOptions, ShieldAssessment } from './types/assessment.js';
+/**
+ * Run a one-shot tamper-detection assessment and return structured signals,
+ * a risk summary, and OTel-compatible span attributes.
+ *
+ * @example
+ * ```ts
+ * import { assess } from '@tindalabs/shield';
+ *
+ * const result = await assess();
+ * if (result.risk.score > 0.5) {
+ *   span.setAttributes(result.spanAttributes);
+ * }
+ * ```
+ */
+export declare function assess(options?: AssessOptions): Promise<ShieldAssessment>;

package/dist/assess.js

@@ -0,0 +1,220 @@
+import { isBrowser } from './utils/environment.js';
+import { DevToolsDetectorManager } from './utils/detectors/devToolsDetectorManager.js';
+// ── Headless detection ────────────────────────────────────────────────────────
+function detectHeadless() {
+    if (!isBrowser())
+        return false;
+    // Headless Chrome/Chromium sets this
+    if (/HeadlessChrome|Headless/i.test(navigator.userAgent))
+        return true;
+    // Chrome with zero plugins is a strong headless signal
+    // (real browsers always have at least one built-in plugin)
+    if ('chrome' in window &&
+        navigator.plugins.length === 0 &&
+        !navigator.userAgent.includes('Mobile'))
+        return true;
+    // Permissions API is absent in many headless environments
+    if (!('permissions' in navigator))
+        return true;
+    return false;
+}
+// ── DevTools detection ────────────────────────────────────────────────────────
+function detectDevTools(timeoutMs) {
+    // DebuggerDetector defers worker init by 100ms via setTimeout; calling
+    // checkDevTools() before that returns immediately (worker null). We wait
+    // 150ms so the worker is ready before triggering the actual check.
+    const WARMUP_MS = 150;
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            manager.dispose();
+            resolve(value);
+        };
+        const manager = new DevToolsDetectorManager({
+            delayInitialCheck: false,
+            // Only settle true on open — the timeout below handles the closed case.
+            onDevToolsChange: (isOpen) => { if (isOpen)
+                settle(true); },
+        });
+        setTimeout(() => {
+            if (settled)
+                return;
+            manager.checkDevTools();
+            // If DevTools are open, the debugger timeout (50ms) fires the callback.
+            // If still no result after the remaining budget, DevTools are closed.
+            setTimeout(() => settle(false), timeoutMs - WARMUP_MS);
+        }, WARMUP_MS);
+    });
+}
+// ── Extension detection ───────────────────────────────────────────────────────
+async function detectExtensions(config) {
+    if (!isBrowser() || !config?.length)
+        return { detected: false, names: [] };
+    const names = [];
+    for (const ext of config) {
+        let found = false;
+        // DOM selector checks
+        if (ext.detectionMethods?.domSelectors) {
+            for (const selector of ext.detectionMethods.domSelectors) {
+                try {
+                    if (document.querySelector(selector)) {
+                        found = true;
+                        break;
+                    }
+                }
+                catch {
+                    // invalid selector — skip
+                }
+            }
+        }
+        // JS global signature checks
+        if (!found && ext.detectionMethods?.jsSignatures) {
+            for (const path of ext.detectionMethods.jsSignatures) {
+                try {
+                    const parts = path.split('.');
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    let obj = window;
+                    for (const part of parts) {
+                        if (obj == null || !(part in obj)) {
+                            obj = undefined;
+                            break;
+                        }
+                        obj = obj[part];
+                    }
+                    if (obj !== undefined) {
+                        found = true;
+                        break;
+                    }
+                }
+                catch {
+                    // property access threw — skip
+                }
+            }
+        }
+        if (found)
+            names.push(ext.name);
+    }
+    return { detected: names.length > 0, names };
+}
+// ── Risk scoring ──────────────────────────────────────────────────────────────
+const FLAG_WEIGHTS = {
+    webdriver: 0.9,
+    headless: 0.7,
+    devtools_open: 0.4,
+    frame_embedded: 0.3,
+    extension: 0.2,
+};
+function computeRisk(flags) {
+    const score = Math.min(1, flags.reduce((sum, f) => sum + (FLAG_WEIGHTS[f] ?? 0.2), 0));
+    return { score: Math.round(score * 1000) / 1000, flags };
+}
+// ── Default extension signatures ─────────────────────────────────────────────
+// A minimal built-in set of high-risk extensions. Consumers can extend this
+// by passing extensionConfig to assess().
+const DEFAULT_EXTENSION_CONFIG = [
+    {
+        name: 'React DevTools',
+        description: 'React component inspector',
+        risk: 'low',
+        detectionMethods: { jsSignatures: ['__REACT_DEVTOOLS_GLOBAL_HOOK__'] },
+    },
+    {
+        name: 'Redux DevTools',
+        description: 'Redux state inspector',
+        risk: 'low',
+        detectionMethods: { jsSignatures: ['__REDUX_DEVTOOLS_EXTENSION__'] },
+    },
+    {
+        name: 'Tampermonkey',
+        description: 'Userscript manager',
+        risk: 'medium',
+        detectionMethods: {
+            jsSignatures: ['GM_info', 'unsafeWindow'],
+            domSelectors: ['[class*="tampermonkey"]'],
+        },
+    },
+    {
+        name: 'Greasemonkey',
+        description: 'Userscript manager',
+        risk: 'medium',
+        detectionMethods: { jsSignatures: ['GM', 'greasemonkey'] },
+    },
+];
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Run a one-shot tamper-detection assessment and return structured signals,
+ * a risk summary, and OTel-compatible span attributes.
+ *
+ * @example
+ * ```ts
+ * import { assess } from '@tindalabs/shield';
+ *
+ * const result = await assess();
+ * if (result.risk.score > 0.5) {
+ *   span.setAttributes(result.spanAttributes);
+ * }
+ * ```
+ */
+export async function assess(options = {}) {
+    const { devtools: runDevtools = true, extensions: runExtensions = true, timeout = 400, extensionConfig = DEFAULT_EXTENSION_CONFIG, } = options;
+    // SSR / non-browser environments return a clean result immediately.
+    if (!isBrowser()) {
+        return {
+            signals: {
+                'shield.devtools.open': false,
+                'shield.automation.webdriver': false,
+                'shield.automation.headless': false,
+                'shield.frame.embedded': false,
+                'shield.extension.detected': false,
+                'shield.extension.names': '',
+            },
+            risk: { score: 0, flags: [] },
+            spanAttributes: {},
+        };
+    }
+    // Run all detections concurrently.
+    const [devtoolsOpen, extensionResult] = await Promise.all([
+        runDevtools ? detectDevTools(timeout) : Promise.resolve(false),
+        runExtensions ? detectExtensions(extensionConfig) : Promise.resolve({ detected: false, names: [] }),
+    ]);
+    const webdriver = Boolean(navigator.webdriver);
+    const headless = detectHeadless();
+    const frameEmbedded = (() => { try {
+        return window.self !== window.top;
+    }
+    catch {
+        return true;
+    } })();
+    const signals = {
+        'shield.devtools.open': devtoolsOpen,
+        'shield.automation.webdriver': webdriver,
+        'shield.automation.headless': headless,
+        'shield.frame.embedded': frameEmbedded,
+        'shield.extension.detected': extensionResult.detected,
+        'shield.extension.names': extensionResult.names.join(','),
+    };
+    const flags = [
+        webdriver ? 'webdriver' : null,
+        headless ? 'headless' : null,
+        devtoolsOpen ? 'devtools_open' : null,
+        frameEmbedded ? 'frame_embedded' : null,
+        extensionResult.detected ? 'extension' : null,
+    ].filter(Boolean);
+    const risk = computeRisk(flags);
+    // Only include non-default values in spanAttributes to keep spans lean.
+    const spanAttributes = {};
+    for (const [key, val] of Object.entries(signals)) {
+        if (val === true)
+            spanAttributes[key] = true;
+        if (typeof val === 'string' && val !== '')
+            spanAttributes[key] = val;
+    }
+    if (risk.score > 0) {
+        spanAttributes['shield.risk.score'] = risk.score;
+        spanAttributes['shield.risk.flags'] = risk.flags.join(',');
+    }
+    return { signals, risk, spanAttributes };
+}