User Journey Hashed-Chain Tracking

Event Object

Each event sent by the client MUST be a JSON object:

{
  "v": 1,
  "curr": "<hex-encoded hash>",
  "prev": "<hex-encoded hash or empty string>",
  "payload": {
    "path": "/example",
    "event": "view",
    "ts": 1734373200000,
    "ref": "https://example.org",
    "x-step": "onboarding.enter_email@v3",
    "x-journey": "onboarding",
    "x-catalog": "2025-08-04T12:00Z",
    "x-variant": "A"
  }
}

Fields

• v — protocol version (this spec defines 1).
• curr — lowercase hex of current event hash hi. For v = 1, this MUST be 64 hexadecimal characters (HMAC-SHA-256 output).
• prev — lowercase hex of previous event hash hi-1 or empty string for root events; for v = 1 this MUST be empty or 64 hexadecimal characters.
• payload — minimal event data. Required members:
  • path — normalized page path or route identifier; MUST NOT include PII.
  • event — event type token (e.g., "view", "action:signup").
  • ts — Unix epoch ms; SHOULD be rounded (see § Privacy Requirements).
  • ref — referrer origin or empty string. Clients MUST NOT include path, query, or fragment components.

Additional namespaced members under payload whose keys begin with x- are permitted; servers MUST ignore unknown members. When a Journey Catalog is enabled (§ Journey Catalog), clients SHOULD include:

• x-step — step key for this event. MUST be included if the deployment enforces catalog validation.
• x-journey — optional journey/funnel name.
• x-catalog — catalog version identifier (e.g., timestamp or semantic version).
• x-variant — optional experiment or variant label.

Values of x-* members SHOULD be short, low-cardinality ASCII tokens (max 256 chars) and MUST NOT contain PII, hashed or encrypted PII, or per-user stable identifiers.

Canonicalization

Clients MUST canonicalize payload using the JSON Canonicalization Scheme (JCS) or an equivalent scheme that produces a stable byte sequence for the same semantic JSON object.

CANON(payload) || "|" || prev

Hash Algorithm

For protocol version v = 1, clients MUST compute hi = HMAC_SHA256(S, CANON(payload) || "|" || hi-1) and encode the 32-byte output as lowercase hex (64 characters). The initial predecessor h-1 is defined as the empty string (""), and the corresponding root event MUST set prev to "".

Seeds MUST be generated with at least 128 bits of entropy (256 bits recommended) using a cryptographically secure random source (for example, crypto.getRandomValues() in Web Crypto), and MUST NOT be transmitted, persisted, or shared across sessions.

This specification fixes the hash construction for v = 1 to HMAC-SHA-256. Future protocol versions MAY define additional constructions with distinct v values and corresponding schema updates.

Session semantics and edge cases

Clients define a UJHT session as the lifetime of a single browsing context (for example, a tab or window). In practice, user agents and frameworks may perform back/forward cache restores, reloads, and process restarts that affect client state.

• If sessionStorage is unavailable or a client cannot recover a valid prev value after navigation or restart, it MUST start a new chain by setting prev = "" and computing a new root event.
• If a page is restored from a back/forward cache with stale or inconsistent state, clients SHOULD prefer starting a new chain rather than attempting to reuse an old prev that no longer reflects the actual journey.
• Implementations MUST NOT attempt to bridge chains across independent browsing contexts (for example, separate tabs or windows) by sharing seeds or prev values.

TLS and HTTP Versions

• All UJHT transmissions MUST use TLS (HTTPS) with TLS 1.2 or newer. Clear-text HTTP MUST NOT be used in production. For development, http://localhost is permitted.
• HTTP/1.1, HTTP/2, and HTTP/3 are supported. Implementations SHOULD prefer HTTP/2 or HTTP/3 where available.

HTTP Interface

Method: POST • Headers: Content-Type: application/ujht+json • Body: Event object (see Event Object). Servers MUST treat curr as an idempotency key within a given collection endpoint. Responses: 204 on success; 400, 413, 429, 5xx as appropriate.

Batching

Clients MAY send a batch envelope with media type application/ujht-batch+json containing an array of events, ordered or unordered. Servers MUST accept out-of-order events and deduplicate by curr.

{
  "v": 1,
  "events": [ { /* event */ }, { /* event */ } ]
}

Streaming

Clients MAY stream events using NDJSON over HTTP with Content-Type: application/ujht-ndjson. For HTTP/1.1, Transfer-Encoding: chunked MAY be used; HTTP/2 and HTTP/3 provide native data framing. Each line MUST contain a single event JSON object.

Optional Server Hints (Non-authoritative)

Servers MAY include response headers that provide non-authoritative hints to clients:

• UJHT-Step, UJHT-Journey, UJHT-Catalog, UJHT-Variant — suggest step metadata for the next client emission.
• UJHT-Expected-Next — a comma-separated list of likely next step keys for QA/observability.

Clients MUST NOT rely on hints for hashing or identity; they are advisory only.

WebSocket Subprotocol

Implementations MAY use secure WebSockets (wss://) with a subprotocol token ujht.v1. Messages are UTF-8 JSON; both single events and batches are allowed. Clear-text ws:// MUST NOT be used in production. Clients MUST NOT open a WebSocket when a Do Not Track or equivalent opt-out signal is enabled.

Validation

• Servers MUST validate version, types, and formats; SHOULD detect and mitigate payloads containing obvious PII patterns (for example, email addresses, telephone numbers, or account identifiers) by rejecting the event (e.g., with 400) or sanitizing offending fields and annotating them; and MUST index prev for stitching.
• Servers MUST NOT derive or require access to the session seed, or mint surrogate hashes intended to replace curr/prev. The construction of the hash chain is a client responsibility.
• Servers MAY normalize payload.ref to origin-only when misconfigured clients send full URLs.

Storage vs. Streaming

• Servers MAY store raw events as edges (curr, prev, path, event, ts, ref, received_at).
• Servers MAY stream events to downstream processors (for example, OTLP/HTTP, Kafka). Controllers MUST ensure downstream processors adhere to § Privacy Requirements and do not perform cross-session or cross-site re-identification using UJHT data.
• When streaming without storage, servers SHOULD implement back-pressure and transient buffering to avoid data loss.

Stitching

To reconstruct a journey, start from any event with prev = "" and follow successive events where prev equals the predecessor’s curr, ordered by ts (tie-break by received_at). Servers MUST tolerate out-of-order arrival and ignore duplicates by curr.

If a predecessor event is missing (that is, there is no event whose curr matches a given prev), servers MUST treat the first seen event as the start of a new reconstructable chain for analytics purposes and MAY annotate such events with an anomaly token (for example, missing_predecessor).

Catalog Validation & Anomalies

When a Journey Catalog is enabled and x-step is present:

• Servers MUST verify that x-step exists in the active catalog version.
• For non-root events, servers SHOULD verify that the transition from the predecessor’s x-step to the current x-step is allowed by the catalog. If the predecessor x-step is unknown or missing, validation MAY be skipped for that edge.
• Servers MUST NOT drop events solely due to catalog mismatches; instead they SHOULD annotate with an anomaly flag and proceed.

Recommended anomaly tokens (attached as an implementation-defined note, for example, x-anomaly): catalog_unknown_step, invalid_transition, catalog_version_mismatch, missing_predecessor.

Structure

{
  "version": "2025-08-04T12:00Z",
  "steps": {
    "onboarding.enter_email@v3": {
      "name": "Enter Email",
      "allowNext": ["onboarding.verify_email@v2"]
    },
    "onboarding.verify_email@v2": {
      "name": "Verify Email",
      "allowNext": ["onboarding.welcome@v1"]
    },
    "onboarding.welcome@v1": {
      "name": "Welcome"
    }
  }
}

Requirements

• Controllers MUST maintain a version identifier and SHOULD publish signed snapshots via CI.
• Servers MAY load the catalog from code, config, or a service. Clients MUST NOT fetch or rely on the catalog directly.
• If catalog validation is enforced, clients MUST include x-step and SHOULD include x-catalog.
• Step keys, journey names, catalog versions, and related control-plane identifiers MUST NOT embed application-specific user identifiers, hashed or encrypted PII, or per-user unique tokens. They SHOULD be low-cardinality tokens defined at design or release time, not per user.

Media Types

• application/ujht+json — single event.
• application/ujht-batch+json — batch envelope.
• application/ujht-ndjson — line-delimited stream of events.