@svrnsec/pulse 0.8.0 → 0.9.0

package/SECURITY.md

@@ -1,86 +1,91 @@
-# Security Policy
-
-## Overview
-
-`@svrnsec/pulse` is a hardware-physics fingerprinting library used as a security layer.
-We take vulnerabilities seriously and will respond promptly.
-
-## Supported Versions
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.1.x   | ✅ Current release |
-| < 0.1   | ❌ No longer supported |
-
-## Threat Model
-
-**What pulse protects against:**
-- Automated bots running in cloud VMs / Docker containers with no real hardware
-- Headless browser automation (Puppeteer, Playwright) on virtual machines
-- Credential-stuffing and account-takeover attacks from datacenter IP ranges
-
-**What pulse does NOT claim to protect against:**
-- A determined human attacker on real consumer hardware
-- A physical device farm (phones/laptops in a room)
-- Kernel-level hooks that spoof `performance.now()` at nanosecond precision
-- Server-side replay attacks when `checkNonce` is not wired (always wire it)
-
-## Reporting a Vulnerability
-
-**Please do NOT open a public GitHub issue for security vulnerabilities.**
-
-Report security issues via email:
-
-> **security@sovereign.dev**  *(or open a private GitHub Security Advisory)*
-
-### What to include
-
-1. A description of the vulnerability and the expected vs. actual behavior
-2. Steps to reproduce (PoC code, scripts, or screenshots)
-3. The impact — what can an attacker achieve?
-4. Any suggested mitigation or fix
-
-### Response SLA
-
-| Severity | Initial response | Target fix |
-|----------|-----------------|------------|
-| Critical | 24 hours        | 7 days     |
-| High     | 48 hours        | 14 days    |
-| Medium   | 5 business days | 30 days    |
-| Low      | 10 business days| Next minor |
-
-We follow [coordinated disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
-You will receive credit in the changelog unless you prefer to remain anonymous.
-
-## Cryptographic Primitives
-
-- **Hashing**: BLAKE3 via `@noble/hashes` — audited, constant-time implementation
-- **Nonce generation**: `crypto.getRandomValues()` / Node.js `webcrypto` — 256 bits of entropy
-- **Webhook signatures**: HMAC-SHA256 — standard authenticated integrity check
-
-## Known Limitations & Design Decisions
-
-### Score, not binary gate
-The jitter score is a continuous value `[0, 1]`.  Applications must choose their own
-threshold (`minJitterScore`).  A score of `0.55` (default) is conservative; financial
-applications may want `0.70+`.
-
-### No raw data leaves the browser
-The server receives only a ~1.6 KB statistical summary (means, variances, percentiles).
-Raw timing arrays and mouse coordinates stay on device.  This is intentional — it
-limits what a compromised server can learn about the client.
-
-### Registry is additive
-The VM classification registry (which vendor a VM is from) is separate from detection.
-A VM can be detected by physics even if its vendor is not in the registry.
-
-## Secure Deployment Checklist
-
-- [ ] Set `NODE_ENV=production` to disable verbose error messages
-- [ ] Wire `checkNonce` to a Redis `SET NX` with TTL to prevent replay attacks
-- [ ] Set `PULSE_WEBHOOK_SECRET` to a cryptographically random 32+ character string
-- [ ] Put the API server behind TLS (nginx / Caddy / ALB)
-- [ ] Set `PULSE_CORS_ORIGINS` to your exact domain — not `*`
-- [ ] Set `minJitterScore` ≥ 0.65 for high-value endpoints
-- [ ] Monitor `riskFlags` in webhook payloads for anomaly detection
-- [ ] Rotate `PULSE_API_KEYS` regularly; use different keys per environment
+# Security Policy
+
+## Overview
+
+`@svrnsec/pulse` is a hardware-physics fingerprinting library used as a security layer.
+We take vulnerabilities seriously and will respond promptly.
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.8.x   | :white_check_mark: Security fixes + active development |
+| < 0.8   | :x: Deprecated — critical security vulnerabilities. Upgrade immediately. |
+
+## Threat Model
+
+**What pulse protects against:**
+- Automated bots running in cloud VMs / Docker containers with no real hardware
+- Headless browser automation (Puppeteer, Playwright) on virtual machines
+- Credential-stuffing and account-takeover attacks from datacenter IP ranges
+- Click farms (via proof-of-idle thermal cooling analysis)
+- LLM-controlled browser agents (via behavioral biometrics)
+- Coordinated inauthentic behavior (via population-level statistical analysis)
+- Proof replay attacks (via HMAC-signed challenges + atomic nonce consumption)
+- Payload tampering (via BLAKE3 commitment integrity)
+
+**What pulse does NOT claim to protect against:**
+- A determined human attacker on real consumer hardware
+- A physical device farm where each device genuinely cools between interactions
+- Kernel-level hooks that spoof `performance.now()` at nanosecond precision
+- Server-side replay attacks when `checkNonce` is not wired (always wire it)
+- GPU passthrough VMs with native hardware clock access
+
+## Reporting a Vulnerability
+
+**Please do NOT open a public GitHub issue for security vulnerabilities.**
+
+Report security issues via email:
+
+> **security@sovereign.dev**  *(or open a private GitHub Security Advisory)*
+
+### What to include
+
+1. A description of the vulnerability and the expected vs. actual behavior
+2. Steps to reproduce (PoC code, scripts, or screenshots)
+3. The impact — what can an attacker achieve?
+4. Any suggested mitigation or fix
+
+### Response SLA
+
+| Severity | Initial response | Target fix |
+|----------|-----------------|------------|
+| Critical | 24 hours        | 7 days     |
+| High     | 48 hours        | 14 days    |
+| Medium   | 5 business days | 30 days    |
+| Low      | 10 business days| Next minor |
+
+We follow [coordinated disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
+You will receive credit in the changelog unless you prefer to remain anonymous.
+
+## Cryptographic Primitives
+
+- **Hashing**: BLAKE3 via `@noble/hashes` — audited, constant-time implementation
+- **Challenge signing**: HMAC-SHA256 over `nonce|issuedAt|expiresAt` with timing-safe comparison
+- **Engagement tokens**: HMAC-SHA256 over fraud-relevant fields with 30-second TTL
+- **Nonce generation**: `crypto.getRandomValues()` / Node.js `webcrypto` — 256 bits of entropy
+- **Webhook signatures**: HMAC-SHA256 — standard authenticated integrity check
+- **API key comparison**: `crypto.timingSafeEqual` — constant-time to prevent timing attacks
+
+## Privacy
+
+- Raw timing arrays never leave the device — server receives only a ~1.6 KB statistical summary
+- Mouse coordinates are never stored — only timing deltas between events
+- Keystrokes capture only dwell/flight times — key labels are discarded immediately
+- `hardwareId()` is a 128-bit BLAKE3 hash — stable per device, not reversible, not cross-origin linkable
+- No IP addresses are logged by default — integrators should implement their own IP handling policy
+
+## Secure Deployment Checklist
+
+- [ ] Set `NODE_ENV=production` to enforce secret validation at startup
+- [ ] Set `PULSE_CHALLENGE_SECRET` to a cryptographically random 64-char hex string
+- [ ] Set `WEBHOOK_SECRET` to a separate cryptographically random string
+- [ ] Wire `checkNonce` to Redis `DEL` (returns 1 on first use) for atomic replay prevention
+- [ ] Set `REDIS_URL` for multi-instance deployments (in-memory store is single-instance only)
+- [ ] Put the API server behind TLS (nginx / Caddy / ALB)
+- [ ] Set `CORS_ORIGINS` to your exact domain — not `*`
+- [ ] Set `minJitterScore` >= 0.65 for high-value endpoints
+- [ ] Monitor `riskFlags` in webhook payloads for anomaly detection
+- [ ] Use `/health/ready` (not `/health`) for load balancer health checks
+- [ ] Rotate `PULSE_API_KEYS` regularly; use different keys per environment
+- [ ] Review `webhook.dead_letter` log events for delivery failures

package/dist/pulse.cjs

@@ -6313,6 +6313,61 @@ function renderInlineUpdateHint(latest) {
   );
 }
 
+/**
+ * @svrnsec/pulse — Structured Error Codes
+ *
+ * Use these constants instead of string matching for type-safe error handling.
+ */
+const PulseErrorCode = Object.freeze({
+  // Structural
+  INVALID_PAYLOAD_STRUCTURE: 'INVALID_PAYLOAD_STRUCTURE',
+  PROTOTYPE_POLLUTION_ATTEMPT: 'PROTOTYPE_POLLUTION_ATTEMPT',
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+  INVALID_TYPE: 'INVALID_TYPE',
+  TIMESTAMP_OUT_OF_RANGE: 'TIMESTAMP_OUT_OF_RANGE',
+  UNSUPPORTED_PROOF_VERSION: 'UNSUPPORTED_PROOF_VERSION',
+
+  // Hash integrity
+  INVALID_HASH_FORMAT: 'INVALID_HASH_FORMAT',
+  HASH_MISMATCH_PAYLOAD_TAMPERED: 'HASH_MISMATCH_PAYLOAD_TAMPERED',
+
+  // Timestamp / freshness
+  PROOF_EXPIRED: 'PROOF_EXPIRED',
+  PROOF_FROM_FUTURE: 'PROOF_FROM_FUTURE',
+  NONCE_INVALID_OR_REPLAYED: 'NONCE_INVALID_OR_REPLAYED',
+
+  // Jitter / scoring
+  JITTER_SCORE_TOO_LOW: 'JITTER_SCORE_TOO_LOW',
+  DYNAMIC_THRESHOLD_NOT_MET: 'DYNAMIC_THRESHOLD_NOT_MET',
+
+  // Heuristic / coherence overrides
+  HEURISTIC_HARD_OVERRIDE: 'HEURISTIC_HARD_OVERRIDE',
+  COHERENCE_HARD_OVERRIDE: 'COHERENCE_HARD_OVERRIDE',
+
+  // Renderer
+  SOFTWARE_RENDERER_DETECTED: 'SOFTWARE_RENDERER_DETECTED',
+  BLOCKLISTED_RENDERER: 'BLOCKLISTED_RENDERER',
+
+  // Bio activity
+  NO_BIO_ACTIVITY_DETECTED: 'NO_BIO_ACTIVITY_DETECTED',
+
+  // Cross-signal forgery detection
+  FORGED_SIGNAL_CV_SCORE_IMPOSSIBLE: 'FORGED_SIGNAL:CV_SCORE_IMPOSSIBLE',
+  FORGED_SIGNAL_AUTOCORR_SCORE_IMPOSSIBLE: 'FORGED_SIGNAL:AUTOCORR_SCORE_IMPOSSIBLE',
+  FORGED_SIGNAL_QE_SCORE_IMPOSSIBLE: 'FORGED_SIGNAL:QE_SCORE_IMPOSSIBLE',
+
+  // Risk flags (informational, not rejection reasons)
+  NONCE_FRESHNESS_NOT_CHECKED: 'NONCE_FRESHNESS_NOT_CHECKED',
+  CANVAS_UNAVAILABLE: 'CANVAS_UNAVAILABLE',
+  ZERO_BIO_SAMPLES: 'ZERO_BIO_SAMPLES',
+  NEGATIVE_INTERFERENCE_COEFFICIENT: 'NEGATIVE_INTERFERENCE_COEFFICIENT',
+  INCONSISTENCY_LOW_CV_BUT_HIGH_SCORE: 'INCONSISTENCY:LOW_CV_BUT_HIGH_SCORE',
+  SUSPICIOUS_ZERO_TIMER_GRANULARITY: 'SUSPICIOUS_ZERO_TIMER_GRANULARITY',
+  INCONSISTENCY_FLAT_THERMAL_BUT_HIGH_SCORE: 'INCONSISTENCY:FLAT_THERMAL_BUT_HIGH_SCORE',
+  EXTREME_HURST: 'EXTREME_HURST',
+  AUDIO_JITTER_TOO_FLAT: 'AUDIO_JITTER_TOO_FLAT',
+});
+
 /**
  * @svrnsec/pulse
  *
@@ -6785,6 +6840,7 @@ var pulse_core = /*#__PURE__*/Object.freeze({
 
 exports.CURRENT_VERSION = CURRENT_VERSION;
 exports.Fingerprint = Fingerprint;
+exports.PulseErrorCode = PulseErrorCode;
 exports.checkForUpdate = checkForUpdate;
 exports.collectDramTimings = collectDramTimings;
 exports.collectEnfTimings = collectEnfTimings;