@svrnsec/pulse 0.8.0 → 0.9.0

package/index.d.ts

@@ -893,3 +893,57 @@ export declare function decodeToken(compact: string): object;
  * For logging/debugging only — use verifyEngagementToken for security checks.
  */
 export declare function decodeTokenUnsafe(compact: string): object & { _verified: false };
+
+// =============================================================================
+// Structured Error Codes
+// =============================================================================
+
+export declare const PulseErrorCode: Readonly<{
+  // 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)
+  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';
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svrnsec/pulse",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Physical Turing Test — Idle attestation, population-level Sybil detection, and engagement tokens that defeat click farms at the physics layer.",
   "type": "module",
   "license": "MIT",
@@ -96,6 +96,10 @@
     "./coordination": {
       "import": "./src/analysis/coordinatedBehavior.js",
       "node":   "./src/analysis/coordinatedBehavior.js"
+    },
+    "./errors": {
+      "import": "./src/errors.js",
+      "node":   "./src/errors.js"
     }
   },
   "main":   "dist/pulse.cjs",

package/src/errors.js

@@ -0,0 +1,54 @@
+/**
+ * @svrnsec/pulse — Structured Error Codes
+ *
+ * Use these constants instead of string matching for type-safe error handling.
+ */
+export 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',
+});

package/src/index.js

@@ -317,6 +317,9 @@ export { detectLlmAgent }  from './analysis/llm.js';
 // Terminal utilities — pretty probe results in Node.js server contexts
 export { renderProbeResult, renderError, renderInlineUpdateHint } from './terminal.js';
 
+// Structured error codes
+export { PulseErrorCode } from './errors.js';
+
 // Version introspection
 export { CURRENT_VERSION, checkForUpdate } from './update-notifier.js';