@tindalabs/shield

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 spans and Scent identity risk scoring.

---

Install

npm install @tindalabs/shield

---

Which API do I want?

Shield ships three top-level APIs. Pick by what you want to do with the result:

Goal	API	What it does
Observe / score the session — log signals, gate a feature, feed a risk model	assess()	Detects DevTools / automation / extensions / frame embedding. Returns structured signals + risk.score (0–1) + OTel span attributes. No side effects.
Block devtools / copy / print / screenshots / clipboard / keyboard shortcuts on an element	ContentProtector	Manual control: pass an element + options, get an instance with dispose(). Always-on for everyone who hits the page.
Both — observe first, then activate protections only when the session warrants it	assessAndProtect()	Runs assess(), evaluates a declarative PolicyRule[] (e.g. "watermark when riskScore ≥ 0.3"), activates the matching strategies. Legitimate users see no overhead.

For OTel-instrumented protection (every block / detection becomes a span event), wrap any of the above with attachShieldToSpan().

---

Quick start — assess()

The primary API is a single async call that returns structured signals, a risk summary, and OTel-compatible span attributes:

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

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:

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

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.

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:

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:

{
  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.

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 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.

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

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/. 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.

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	Privacy-first OTel frontend observability
@tindalabs/shield	Tamper detection & active content protection
@tindalabs/scent	Probabilistic identity continuity

---

License

MIT © Tindalabs