<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.
<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().
| Signal | Type | Description |
|---|---|---|
webdriverDetected | boolean | navigator.webdriver present and truthy |
headlessDetected | boolean | User-agent contains HeadlessChrome or Headless |
domMutationDetected | boolean | DOM elements were injected dynamically after page load |
injectedScriptCount | number | Count of <script> elements added after initial snapshot |
suspiciousScreenSize | boolean | Screen dimensions are zero or both under 100px |
pointerType | 'mouse' | 'touch' | 'pen' | 'none' | Input device type from first pointerdown event |
mouseMovementDetected | boolean | At least one mousemove event received |
keyboardActivityDetected | boolean | At 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.
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
| Attribute | Type | Default | Description |
|---|---|---|---|
signing-key | string | - | 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
signing-key HTML attribute in production. The cached CryptoKey is invalidated when the key value changes.collectSignals()Server Verification
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),
)
}