🔎

<secure-telemetry-provider>

Wraps a <secure-form> to collect environmental security signals and attach a HMAC-SHA-256 signed envelope to every submission. Raises the cost of automated attacks without blocking legitimate users.

Overview

Place <secure-telemetry-provider> as a wrapper around any <secure-form>. On submission, it intercepts the secure-form-submit event, snapshots all environmental signals, signs them with HMAC-SHA-256, and attaches the envelope to detail.telemetry._env before the event completes its bubbling path to your handler.

Basic usage HTML
<secure-telemetry-provider id="provider">
  <secure-form action="/submit" method="POST"
    security-tier="sensitive">
    <secure-input type="email" label="Email"
      name="email" security-tier="sensitive"
      required>
    </secure-input>
    <button type="submit">Submit</button>
  </secure-form>
</secure-telemetry-provider>

<script type="module">
  // Inject the key via JS — never as an HTML attribute in production.
  document.getElementById('provider').setSigningKey('YOUR_SECRET');
</script>

Environmental Signals

A point-in-time snapshot of all signals collected since connectedCallback().

SignalTypeDescription
webdriverDetectedbooleannavigator.webdriver present and truthy
headlessDetectedbooleanUser-agent contains HeadlessChrome or Headless
domMutationDetectedbooleanDOM elements were injected dynamically after page load
injectedScriptCountnumberCount of <script> elements added after initial snapshot
suspiciousScreenSizebooleanScreen dimensions are zero or both under 100px
pointerType'mouse' | 'touch' | 'pen' | 'none'Input device type from first pointerdown event
mouseMovementDetectedbooleanAt least one mousemove event received
keyboardActivityDetectedbooleanAt least one keydown event received

Signing

When a signing key is provided, signals are signed with HMAC-SHA-256 via the Web Crypto API (SubtleCrypto). Supply the key via setSigningKey() — the key is stored in a private JS field and is never readable from the DOM. The signing-key HTML attribute is supported for backward compatibility: it is automatically migrated to the private field and removed from the DOM on connectedCallback.

In non-secure contexts (http://), SubtleCrypto is unavailable and the signature will be an empty string — treat such envelopes as lowest-trust submissions.

Tamper-evidence, not cryptographic proof
The signing key lives in client-side JS memory. Any same-page XSS, compromised browser extension, or privileged script can read the key from the heap and forge envelopes. Treat the signature as a low-effort-forgery deterrent and the signals as heuristic inputs to a server-side risk model — not as ground truth. For stronger guarantees, rotate the key per-session via a server nonce endpoint.
Signed envelope shape TypeScript
interface SignedTelemetryEnvelope {
  nonce: string;                 // 32-char random hex
  issuedAt: string;              // ISO 8601 timestamp
  environment: EnvironmentalSignals;
  signature: string;             // HMAC-SHA-256 hex
                                 // (empty on http://)
}

The signed payload is: nonce + "." + issuedAt + "." + JSON(environment). The same key must be available server-side to verify the signature.

API Reference

Attributes

AttributeTypeDefaultDescription
signing-keystring-Backward-compatible HTML attribute. On mount, the value is migrated to a private JS field and the attribute is removed from the DOM. Prefer the setSigningKey() method for production use — the key never appears in the DOM at all.

Methods

setSigningKey(key: string): void
Supplies the HMAC-SHA-256 signing key programmatically. The key is stored in a private JS field only — it never appears in the DOM. Prefer this over the signing-key HTML attribute in production. The cached CryptoKey is invalidated when the key value changes.
collectSignals(): EnvironmentalSignals
Returns a point-in-time snapshot of all environmental signals
getEnvironmentalSignals(): EnvironmentalSignals
Alias for collectSignals()
sign(signals: EnvironmentalSignals): Promise<SignedTelemetryEnvelope>
Signs a signals snapshot and returns the full envelope. Called automatically on form submission.

Server Verification

Go verification example Go
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "time"
)

type EnvironmentalSignals struct {
    WebdriverDetected      bool   `json:"webdriverDetected"`
    HeadlessDetected       bool   `json:"headlessDetected"`
    DomMutationDetected    bool   `json:"domMutationDetected"`
    InjectedScriptCount    int    `json:"injectedScriptCount"`
    SuspiciousScreenSize   bool   `json:"suspiciousScreenSize"`
    PointerType            string `json:"pointerType"`
    MouseMovementDetected  bool   `json:"mouseMovementDetected"`
    KeyboardActivityDetected bool  `json:"keyboardActivityDetected"`
}

type TelemetryEnvelope struct {
    Nonce       string               `json:"nonce"`
    IssuedAt    time.Time            `json:"issuedAt"`
    Environment EnvironmentalSignals `json:"environment"`
    Signature   string               `json:"signature"`
}

func VerifyTelemetry(env TelemetryEnvelope, key []byte) bool {
    envJSON, err := json.Marshal(env.Environment)
    if err != nil {
        return false
    }
    payload := fmt.Sprintf("%s.%s.%s",
        env.Nonce,
        env.IssuedAt.UTC().Format(time.RFC3339),
        string(envJSON),
    )
    mac := hmac.New(sha256.New, key)
    mac.Write([]byte(payload))
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal(
        []byte(expected),
        []byte(env.Signature),
    )
}