This specification defines the event pipeline: event lifecycle (creation → enrichment → persistence → delivery → archival), immutability guarantees, delivery semantics, and schema contracts.
Audience: Backend engineers, integration architects.
The current workspace implements only a subset of this target pipeline. In particular, the cloud event store is currently in-memory, the local prototype agent does not implement the documented encrypted/chained store, and several retention/archive guarantees below remain target-state documentation rather than confirmed runtime behavior.
In-Scope Out-of-Scope Event lifecycle and state machine Detection logic and scoring Schema contracts (Event, Threat, Device, Policy, Alert) Policy evaluation rules Delivery guarantees (API, webhooks) Cloud Enrichment processing Retention and redaction GUI/dashboard implementation
Stage Description Storage Created Policy Engine emits action decision with full context In-memory Enriched Metadata added: agent version, model version, platform, tenant ID In-memory Persisted Written to local Event Store. AES-256 encrypted. Append-only, cryptographically chained. Device (encrypted) Delivered Pushed via webhook (HMAC-SHA256 signed) or pulled via REST API (cursor-based) Cloud relay (transient) Archived Local retention expired. Cloud copy retained per retention policy. Cloud (EU — Frankfurt) Deleted Hard removal after retention period. Irreversible. None
Append-only: Events cannot be modified after creationCryptographic chaining: Each event contains a hash of the previous event, forming a tamper-evident chainNo updates: Corrections are recorded as new events with a reference to the original event IDEncryption at rest: AES-256. Keys stored in secure enclave (iOS) or keystore (Android)
Documented product target: SHA-256 event chaining with periodic integrity verification. The current workspace code does not yet implement cryptographic chaining.
Every detection decision is logged as an event — including Allow decisions. This ensures a complete audit trail.
Decision Recorded? Delivered? Allow Yes Visible in the canonical GET /events feed; no derived alert created by current workspace logic Warn Yes Visible in GET /events; may create derived alerts/webhooks depending on integration path Block Yes Visible in GET /events; creates derived alerts in current workspace logic
Field Type Required Description event_idstring Yes Format: evt_.... Globally unique. timestampstring (ISO 8601) Yes Policy decision timestamp device_idstring Yes Format: dev_.... Associated device. threat_categoryenum Yes phone_scam, social_engineering, malicious_app, phishing, remote_control, deepfakeconfidencefloat (0.0–1.0) Yes Detection confidence action_takenenum Yes allow, warn, blockpolicy_idstring Yes Format: pol_.... Applied policy. severityenum Yes low, medium, high, criticaldescriptionstring No Human-readable, redacted for external delivery indicatorsarray[string] No IOCs: SHA-256 hashes, signature IDs metadataobject No See Metadata object below
Field Type Description agent_versionstring Device Agent version (target-state metadata; optional in current workspace) model_versionstring ML model version (target-state metadata; not emitted by current workspace prototype) device_platformenum ios, android, windows, macos, linuxtenant_idstring Legacy or target-state metadata copy; current workspace uses top-level tenant_id as the canonical authorization field
Field Type Required Description threat_idstring Yes Format: thr_... threat_categoryenum Yes Canonical threat category confidencefloat (0.0–1.0) Yes Highest confidence from related events severityenum Yes low, medium, high, criticaldevice_idstring Yes Associated device detected_atstring (ISO 8601) Yes First detection timestamp descriptionstring No Human-readable indicatorsarray[string] No IOCs statusenum Yes active, resolved, dismissed
Field Type Required Description device_idstring Yes Format: dev_... tenant_idstring Yes Tenant binding used for event authorization platformenum Yes ios, android, windows, macos, linuxstatusenum Yes active, revokedpublic_key_b64string Yes Base64-encoded DER public key used for signature verification agent_versionstring No Current agent version last_seenstring (ISO 8601) No Last contact timestamp namestring No User-assigned display name
Field Type Required Description policy_idstring Yes Format: pol_... namestring Yes Display name threat_categoriesarray[enum] Yes Applicable categories actionenum Yes allow, warn, blockconfidence_thresholdfloat No Minimum confidence to trigger enabledboolean Yes Active/inactive
Field Type Required Description alert_idstring Yes Unique ID tenant_idstring Yes Tenant associated with the alert device_idstring Yes Device associated with the alert severityenum Yes low, medium, high, criticaltitlestring Yes Human-readable alert title event_idsarray[string] Yes Referenced event IDs statusenum Yes Current workspace currently uses open
Workspace note: schema contracts are still under reconciliation with the current implementation and should not be treated as final API-version guarantees.
Property Value Semantics At-least-once (duplicates possible) Ordering No ordering guarantee (use timestamp for sorting) Signing HMAC-SHA256 (X-Superheld-Signature) Replay protection X-Superheld-Timestamp header; consumer should reject events > 5 min oldIdempotency X-Superheld-Idempotency-Key header + event_id for deduplicationRetry policy Current workspace: 3 total attempts with exponential backoff (1s, 2s, 4s) for 429, 5xx, and transport failures Dead Letter Queue Failed events queued for manual replay (dashboard, 7-day retention)
Current workspace behavior:
X-Superheld-Timestamp — Unix timestamp of webhook dispatch (use for replay protection instead of payload timestamp)X-Superheld-Idempotency-Key — Unique key per delivery attempt (use alongside event_id for deduplication)Webhook-Konfigurationen speichern pro Endpoint die zuletzt bekannte Delivery-Beobachtung (last_delivery_status, last_delivery_error, last_delivery_at, last_delivery_attempts) im In-Memory-Store
Current workspace note: code includes DLQ retention logic for 7 days, but no dashboard/manual replay surface is implemented in this workspace.
Property Value Method GET /eventsPagination Cursor-based (cursor + limit parameters) Filtering since (ISO 8601 timestamp), severity, threat_categoryResponse JSON array with has_more and cursor fields
Data Type Location Retention Status Detection events (local) Device Target: 90 days Not confirmed by current workspace Detection events (cloud) Cloud Target: 180 days Not confirmed by current workspace Audit logs Cloud Target: 12 months Not confirmed by current workspace Aggregated metrics Cloud Target: 24 months (then anonymized) Not confirmed by current workspace
Deletion: Irreversible. Can be requested early via dashboard or API. Account deletion triggers full data removal within 30 days, backup overwrite within 90 days.
Data Type Redaction Method PII (email, name, phone) Replaced with placeholder Message content Not included in telemetry URLs Transmitted as SHA-256 hashes (full URL stays local) IP addresses Truncated to /24 (IPv4) or /48 (IPv6)
Applies to cloud transmission and external delivery only. Local Event Store retains full unredacted data (AES-256 encrypted).
Failure Impact Mitigation Event Store full Cannot persist new events Ring buffer: oldest events overwritten. High-severity events prioritized. Webhook endpoint unreachable Events not delivered Current workspace retries with exponential backoff and moves failed deliveries to DLQ after 3 total attempts. API unavailable Integrators cannot poll Current workspace has no durable cloud event queue; recovery semantics remain a target-state concern. Encryption key unavailable Cannot read/write Event Store Agent enters safe mode. New events buffered in memory until key available. Chain integrity violation Tamper detected Agent logs integrity error. Affected events flagged. Re-chaining from last verified event.
