Technical Overview

Overview

WebCrux is the interface layer that connects users to the CueCrux Engine. It handles authentication, rendering, and secure communication between the browser and the backend systems while maintaining the trust, provenance, and verification standards defined by the Engine and the CROWN model.

Evidence itself lives as artefacts in Perofant™ (the CueCrux evidence database), selected into MiSES via QUORUM (MiSES) and sealed into CROWN receipts for replay and audit.

Purpose

WebCrux provides a secure, responsive interface for users to query, view, and manage evidence-backed answers generated by the CueCrux Engine. It serves as the Backend-for-Frontend (BFF) that safely interacts with the Engine without ever exposing Engine credentials to browsers.

Design Principles

1. Proof over presentation: every answer displayed by CueCrux must include its evidence, provenance, and mode (Light, Verified, or Audit).
2. Security by boundary: Engine keys, tokens, and secrets are injected server-side only; the browser never has direct access.
3. Performance by intent: server-side rendering (SSR) and island architecture reduce latency and maintain a p95 TTFB ≤ 300 ms.
4. Observability and recovery: health, readiness, and metric endpoints ensure graceful degradation during Engine downtime.

Protocol

Core Flow

Request lifecycle & security context: WebCrux is a secure Backend-for-Frontend (BFF) layer that mediates all communication between user-facing clients and the CueCrux Engine. The BFF keeps Engine credentials off the browser, applies C³ cost envelopes, and preserves CROWN receipts so results remain replayable and auditable.

Request Lifecycle Phases

Contracts Consumed (API Interfaces)

WebCrux communicates exclusively with CueCrux Engine endpoints defined and version-locked through SDKCrux.
These contracts guarantee consistent data structures, schema validation, and interoperability across all CueCrux planes.

Authentication & Session Policy

Authentication follows CueCrux’s unified security posture, combining Vault-managed secrets, short-lived JWTs, and DSAR-compliant session management.
This ensures every credential is both verifiable and ephemeral, reducing attack surface while preserving traceability.

Tokens & Lifetimes

All token creation and signing keys are handled centrally by Vault Transit layer, following InfraCrux rotation policy (quarterly with overlap for validity). Sessions are bound to devices and logged within WebCrux’s session ledger for full traceability, supporting DSAR export and revocation workflows.

Boundary Enforcement

No direct Engine exposure: All calls are proxied through the Nitro BFF; CORS policies disallow external origins.

Header isolation: The browser never holds any Engine-scoped credentials.

Cookie scope: Domain-restricted to *.cuecrux.com with Secure and SameSite policies.

Vault Integration: Signing keys and JWKS are served via HashiCorp Vault Transit; rotation occurs quarterly, overlapping previous versions for token grace periods.

Failure & Recovery Behaviour Graceful degradation: If Engine authentication fails, WebCrux displays cached history and saved answers.

Auto-revocation: Invalidated refresh tokens are hashed and blacklisted server-side in the session ledger.

Incident logging: Auth anomalies raise a WatchCrux system finding (category = security).

Trust Enforcement via CROWN & C³

WebCrux inherits CueCrux’s trust and cost governance models: CROWN and C³: ensuring that every interaction is both provable and economically bounded. These two frameworks work together to balance evidence depth, verification strength, and operational efficiency.

CROWN - Counterfactual, Reputation-Weighted, Origin-Verified, Workflow-Encoded

Every Engine response returned to WebCrux carries a CROWN trust payload, embedding cryptographic provenance and evidence metadata that can be independently verified.
This payload is not just a record of what was retrieved it encodes why that evidence was accepted and how it was assembled.

Core principles:

1. Counterfactual search: The Engine probes for dissenting or contradictory evidence to confirm claim robustness.
2. Reputation-Weighted retrieval: Each source domain is scored for reliability, recency, and licensing; these weights directly affect ranking.
3. Origin-Verified artefacts: Every citation includes a BLAKE3 hash of the quoted text and the crawl timestamp to prove integrity.
4. Workflow-Encoded receipts: In Audit mode, CueCrux issues a signed receipt (ed25519 signature) capturing query, parameters, and evidence lineage for replay.

The result is an evidence-first trust chain where every displayed claim can be re-examined, and every contradiction is surfaced rather than hidden.

⚖️ C³ - Cost-Conditioned Cascades

C³ defines the resource and cost boundaries for each operational mode Light, Verified, and Audit ensuring predictable performance and budget control across the platform.

C³ routing ensures WebCrux automatically chooses the appropriate trust path based on the user’s mode and entitlement level.
When system load or spend thresholds are exceeded, the router gracefully downgrades mode or defers heavy computation to maintain fairness and uptime.

Why It Matters

Together, CROWN and C³ make every WebCrux answer:

• Verifiable: supported by reproducible evidence and cryptographic receipts.
• Replayable: every decision path can be reconstructed from provenance data.
• Economically bounded: compute, latency, and cost stay within predictable envelopes.

This combination of proof integrity and operational control forms the foundation of CueCrux’s promise “Know with certainty.”

Layers in the System

The WebCrux stack is split into three tightly coupled layers Presentation, Application, and Data: each responsible for a distinct part of the trust, performance, and session flow.
This architecture ensures that no single layer can compromise the system’s cryptographic integrity or cross-domain security.

1. Presentation Layer - UI / UX

Stack:

• Nuxt 3 (SSR + Islands architecture) for server-rendered, reactive interfaces.
• Vue 3 for declarative components, hydration control, and reactivity isolation.
• Tailwind CSS tokens sourced from @cuecrux/ui-theme for consistent colour, font, and contrast ratios across accessibility modes.

Behaviour:

• Dynamic “Ask with Citations” experience using island hydration to load results incrementally without reloading the entire page.
• Interactive Answer Cards that display Engine-provided claims, quotes, timestamps, and provenance icons.
• Inline “Why Trust” panels surface CROWN metadata domain diversity, quote hashes, and recency with hover and expand transitions.
• Mode badges (Light / Verified / Audit) adjust both UI state and API behaviour, dynamically binding mode to Engine queries through BFF-controlled parameters.

Client Logic:

• Provenance tooltips are rendered client-side via hydration hooks that fetch evidence details from cached SSR payloads.
• Collapsible evidence panes use lazy hydration to defer DOM updates until user interaction.
• Nuxt composables provide reactive state (useAnswer, useSession, useTrustMode) synchronised with backend mode enforcement.
• All outbound requests are routed through Nitro API routes, avoiding direct browser-to-Engine calls.

Performance Optimisation:

• Route-level code-splitting and island hydration maintain a TTFB ≤ 300 ms (p95).
• Fonts and tokens are preloaded using the Nuxt head manager; non-critical scripts are deferred.
• Client hydration boundaries align with Engine mode complexity light answers hydrate instantly, while verified/audit answers hydrate progressively to prevent UI blocking.

2. Application Layer - Backend-for-Frontend (BFF) / Server

Framework:

• Nitro (Fastify v5) runtime for high-concurrency, type-safe server routes.
• Zod schema validation for all request and response bodies, with OpenAPI generation for SDKCrux parity.
• Node 22 LTS + pnpm 9 for deterministic builds and modern ESM support.

Responsibilities:

1. Authentication & Session Management
   • Implements JWT + refresh cookie model (RS256 tokens via Vault Transit).
   • Maintains a sessions and refresh_tokens ledger in Postgres with device fingerprints.
   • Provides middleware to validate, renew, and revoke tokens securely.
2. Proxy to CueCrux Engine
   • Handles /v1/answers and /v1/search requests server-side.
   • Injects X-WebCrux-User and X-WebCrux-Org headers for audit correlation.
   • Adds X-Request-ID for distributed tracing between WebCrux, Engine, and WatchCrux.
   • Applies C³ routing logic; automatically adjusts mode or freshness to match quota and latency targets.
3. Input/Output Enforcement
   • Uses Zod schemas for runtime contract validation; mismatches trigger 422 validation_error responses.
   • Ensures all Engine responses comply with expected evidence shape (claims[], citations[], provenance).
   • Serialises timestamps, domain lists, and mode badges consistently for SSR hydration.
4. Security & Boundary Policies
   • Implements strict CORS (same-origin by default) and CSRF protection for cookie-based flows.
   • Signs JWTs using Vault Transit RSA keys; rotates quarterly.
   • Masks internal headers (Authorization, X-Service-Key) before serialisation to the browser.
   • Detects anomalies (replay, invalid signature, rate abuse) and flags them for WatchCrux via audit events.
5. Graceful Degradation & Error Recovery
   • If the Engine is unreachable, the BFF serves cached results from the queries and answers_saved tables.
   • Returns clear degradation banners in the UI (“Read-only mode: Engine offline”).
   • Logs structured errors to Prometheus and ClickHouse via InfraCrux ingestion.
   • Maintains SLO targets: retry budgets capped, latency < 2 s (p95), and zero unbounded retries per the No-Hammer policy.
6. Observability Integration
   • Exposes /healthz, /readyz, and /metrics endpoints.
   • /healthz returns build version, commit hash, and SDK compat fields for WatchCrux drift detection.
   • /metrics publishes Prometheus histograms (answers_latency_ms_bucket, model_cost_usd_total) and per-mode request counters.
   • Structured logs stream to InfraCrux (via Loki/ClickHouse) with unique trace_id for cross-plane correlation.

3. Data Layer - Persistence & Ledger

The Data Layer anchors all session, identity, and provenance relationships between WebCrux, the Engine, and the wider CueCrux ecosystem.
It relies on PostgreSQL as the primary datastore (managed via InfraCrux) and is replicated for read resilience and PITR recovery.
All schema migrations follow SDKCrux versioning to maintain backward compatibility across service updates.

Architecture Guarantees

• Security Boundary: Engine credentials never cross into the browser context; only BFF-scoped tokens exist in memory.
• Auditability: Every /v1/answers request emits a provenance record linking WebCrux session → Engine receipt → CROWN ledger.
• Observability: Prometheus metrics and structured logs ensure visibility across WebCrux, WatchCrux, and OpsCrux.
• Resilience: Automated downgrades under C³ envelopes prevent overloads, keeping latency predictable even during heavy load or Engine degradation.

Security Overview

CueCrux services operate under a unified security and trust framework that combines strong cryptography, least-privilege design, and independent auditability.
This section outlines the five core layers of protection that keep user data, credentials, and provenance secure across all planes.

Authentication

• Argon2id password hashing ensures credentials are stored using state-of-the-art, memory-hard encryption.
• Rate limiting at the per-IP and per-account level prevents brute-force and credential-stuffing attempts.
• Access tokens: short-lived JWTs (RS256-signed) are rotated automatically, with refresh tokens stored as httpOnly, Secure, and SameSite=Strict cookies.
• Vault integration: all signing keys (JWT and provenance receipts) are stored and rotated via HashiCorp Vault Transit, keeping private keys off disk.

Transport Security

• TLS 1.3 is enforced across all services, supported by HSTS and forward secrecy to block downgrade attacks.
• CSP (Content-Security-Policy) headers restrict script sources to verified, version-pinned origins-no inline scripts or wildcard domains.
• All cross-plane calls (e.g., WebCrux → Engine, WatchCrux → InfraCrux) are authenticated via mutual TLS or server-side JWT injection.

Key Management

• Public keys are published through JWKS at /.well-known/jwks.json, allowing verifiers to check signatures without exposing private material.
• Keys are rotated quarterly using Vault Transit’s versioned key mechanism. Older keys remain valid until all dependent tokens expire.
• Engine receipts use ed25519 signatures and BLAKE3 hashes for proof integrity, making every claim append-only and tamper-evident.
• WebCrux JWTs are signed via Transit RSA keys with overlap policy; JWKS updates include both current and previous kids for zero downtime verification.

Abuse Controls

• Login throttling: exponential back-off after N failed attempts; optional CAPTCHA challenge on persistent failure.
• Session management: device ledger with active session tracking and one-click revoke.
• Anomaly detection: WatchCrux monitors metric spikes (answers_requests_total, auth_fail_total) and flags unusual velocity patterns.
• ATAM alignment: suspicious or collusive behaviour (e.g., repeated citation loops) is down-weighted, not censored, preserving transparency.

Privacy & Compliance

• DSAR workflows: full export and delete procedures ensure users can obtain or erase their data within statutory windows (UK GDPR / DPA 2018).
• Consent & lawful basis: cookie consent and tracking options are surfaced at login; marketing and analytics are opt-in by default.
• Data minimisation: only the hashes, timestamps, and evidence metadata required for verification are stored; raw artefacts remain encrypted in place.
• Retention policy: operational logs 12 months default; receipts and provenance data immutable and retained under the legal “proof” category.
• Independent audit: WatchCrux executes read-only audits of all services’ /healthz and /metrics endpoints, publishing PASS/WARN/FAIL artefacts for public verification.

Summary Table

Together, these layers form a defence-in-depth posture: credentials are transient, proofs are cryptographically verifiable.

Performance & Reliability

WebCrux maintains strict performance budgets to ensure that users receive fast, trustworthy answers even under load or during partial outages.
All targets align with the broader CueCrux SLOs defined in the Engine, InfraCrux, and Integration master plans.

Key Metrics & Targets

How These Budgets Are Achieved

1. SSR + Islands Architecture

• Nuxt 3’s island hydration only loads interactive components once the core SSR HTML is delivered.
• Reduces CPU cost on mid-tier devices and improves TTFB consistency.

2. Hybrid Retrieval Budgeting

• WebCrux mirrors the Engine’s C³ (Cost-Conditioned Cascades) envelopes:
  • Light → speed prioritised; minimal provenance checks.
  • Verified → provenance enforced; budget ≈ 1.6 s for model work.
  • Audit → receipts + counterfactuals; higher but bounded latency.
• Ensures predictable performance even as evidence depth increases.

3. Optimised BFF Proxying

• Nitro/Fastify server performs header injection, schema validation, and caching at the edge.
• Short-lived connections, strict timeouts, and jittered retries prevent “hammering” under outage conditions (Integration Plan No-Hammer Policy).

4. Observability Pipeline

• All latency histograms (answers_latency_ms_bucket, webcrux_ssr_ms_bucket) are scraped by Prometheus and surfaced in Grafana via InfraCrux.
• WatchCrux monitors failure ratios and anomaly spikes independently.

Degraded-Mode Behaviour

When the Engine is offline, WebCrux automatically transitions to read-only mode:

• Still accessible:
  • User history
  • Saved answers
  • Profile & organisation data
  • Session management
• Temporarily disabled:
  • New /v1/answers requests
  • Verified/Audit mode calls
  • Fresh search queries
• UI clearly displays a “Degraded Mode” banner, and BFF uses cached metadata to keep navigation instant.
• No tokens or requests are retried aggressively-honouring the No-Hammer policy defined in the Integration Plan.

This guarantees continuity without compromising security, provenance integrity, or user trust.

Summary

WebCrux enforces strict performance envelopes, graceful failover paths, and evidence-first reliability guarantees.
Every interaction respects CueCrux’s principle: fast answers, never at the expense of trust.

Observability & Operations

WebCrux is fully instrumented to support CueCrux’s unified observability plane, giving operators clear, real-time insight into system health, latency, cost, and trust signals.
All observability contracts align with the standards defined in InfraCrux and enforced independently by WatchCrux.

Core Endpoints

These endpoints form the contract that all CueCrux services must honour before shipping.

Structured Logging

• Logs emitted as structured JSON, including:
  • request_id: unique correlation ID shared across WebCrux → Engine → WatchCrux.
  • trace_id: W3C Trace Context for distributed tracing.
  • latency_ms: per-request latency.
  • mode: Light / Verified / Audit.
  • user / org correlation fields (server-generated only; never from browser).
• Default logging behaviour:
  • Captured centrally via InfraCrux Loki.
  • Enriched with error categories for easier triage: validation_error, upstream_down, provenance_fail, etc.
  • Safe-by-design redactions applied before writing logs (no secrets, token values, or PII).

Metrics Emitted

WebCrux exports a minimum set of standardised metrics across all CueCrux planes:

• p95 latency:
  webcrux_request_duration_ms_bucket
  Mirrors Engine’s latency goals for /v1/answers and /search.
• Error rate:
  webcrux_errors_total{type}
  Type may include: engine_unavailable, validation_error, timeout, circuit_open.
• Cache behaviour:
  webcrux_cache_hits_total
  Used to monitor BFF caching and SSR response reuse.
• Mode distribution:
  webcrux_answer_mode_total{mode="light|verified|audit"}
  Helps track spend and trust posture in line with C³ budgets.
• Engine availability:
  Derived from /readyz probes and circuit_breaker_state{service="engine"} counters.

InfraCrux scrapes these every 10–15 seconds and stores rollups in ClickHouse for product analytics and capacity planning.

Alerts & Operator Signals

Alerts are defined in InfraCrux Prometheus and surfaced to operators via WatchCrux:

• Latency p95 > threshold (300ms SSR, 2.0s answers)
• Error ratio spikes
• Budget-overrun warnings (C³ envelopes breached)
• Circuit-breaker open > 30s (No-Hammer event)
• Snapshot freshness outside SLA (verified > 7 days; audit > 24h)
• Drift warnings from missing/incorrect build_info, sdkVersion, or compat.requires

WatchCrux converts these into machine-readable PASS / WARN / FAIL findings on its operator panel.

Maintenance & Operational Safety

WebCrux adheres to the No-Hammer policy from the Integration Master Plan:

• All retry logic uses capped exponential backoff with jitter.
• BFF will not flood the Engine when it is down; instead it degrades gracefully and notifies WatchCrux.
• Start/stop scripts enforce:
  • Bounded wait times
  • Readiness verification
  • Safe shutdown with connection draining
  • Zero-impact restarts (SSR cache warming + dependency checks)

This ensures deployments, rollouts, and maintenance windows run predictably without causing platform-wide instability.

Summary

WebCrux provides deep, reliable observability through:

• Standardised /healthz, /readyz, /metrics
• Strong structured logging
• Rich Prometheus/Grafana metrics and WatchCrux audits
• Safe operational behaviour via the No-Hammer policy

Together, these guarantees make WebCrux transparent, diagnosable, and resilient under load or failure.