Evidence-First Multi-Persona Web Journey Comparison & Differential Audit Platform
Execute identical bounded web journeys across isolated browser personas, capture cryptographic evidence, and compute explainable comparison metrics without claiming causation.
Quick Start • Key Features • Architecture • Metrics Engine • Security • Documentation
Comparison Runs Dashboard — Real-time execution cards, status filters, and historical runs overview across isolated Playwright contexts.
Audit Launch Wizard — Target presets, custom journey script builder, and regional persona matrix. |
Cross-Persona Divergence Analysis — Cryptographic side-by-side comparison with automated content divergence alerts. |
Evidence Forensic Replay — Targetless replay inspector to review captured DOM timeline snapshots. |
- 🔍 Overview
- ✨ Key Features
- 🏗️ System Architecture
- 🚀 Quick Start
- 🔌 API Usage & Role-Based Tokens
- 📐 Comparison Engine & Metrics
- 🛡️ Security & Ethical Boundaries
- 📂 Repository Layout
- 🧪 Testing & Verification
- 👨💻 Author & Developer
- 📚 Documentation Index
Modern web platforms dynamically alter content, geo-pricing, feature availability, and localization based on user signals: geography, language preference, viewport dimensions, authentication status, or request headers. Auditing these discrepancies responsibly demands absolute browser isolation, cryptographic provenance, and statistically honest diffing.
PersonaDiff is a production-grade differential web auditing system that allows operators and researchers to:
-
Orchestrate Parallel Journeys: Execute identical navigation scripts across 2 to
$N$ isolated personas simultaneously with zero cross-context leakage. - Capture Cryptographic Evidence: Collect full-resolution screenshots, raw DOM snapshots, and network traces with pre-storage PII redaction and SHA-256 hash chaining.
- Compute Deterministic Diffs: Calculate structural DOM similarity, text cosine distance, ranking permutations, numeric deltas, and redirect routes.
- Replay Without Live Targets: Reconstruct and inspect past runs step-by-step from immutable storage without generating outbound network requests.
- Enforce Ethical & Security Boundaries: Enforce strict surface allowlisting, pre-navigation SSRF IP checks, and non-causal reporting standards.
💡 100% Self-Contained Local Mode: PersonaDiff includes a built-in deterministic fixture service (
http://localhost:4300) pre-approved for local testing, demo recordings, and offline evaluations with zero third-party consent required.
| Feature | Description |
|---|---|
| 🛡️ Zero-Leakage Isolation | Launches dedicated Playwright contexts per persona with strict lifecycle teardown, ensuring cookies, localStorage, and caches never cross boundaries. |
| 🔒 Defense-in-Depth SSRF Guard | Validates target URLs against strict surface allowlists and blocks loopback, private RFC-1918 subnets, and cloud metadata IPs (169.254.169.254). |
| 🧹 Pre-Storage PII Redaction | Automatically strips auth tokens, passwords, session cookies, and sensitive parameters before persisting evidence artifacts. |
| 📊 Deterministic Comparison Engine | Evaluates element presence, tokenized text cosine similarity, rank shift, numeric deltas, and redirect routes with confidence scoring. |
| 🤖 AI-Assisted Divergence Insights | Provides explainable, non-causal visual and regional pricing analysis powered by Google Gemini. |
| ⏰ Continuous Monitoring | Schedules recurring background audits with configurable intervals and real-time execution countdowns. |
| 🎥 Targetless Replay Mode | Reconstructs captured journeys offline directly from stored DOM snapshots and screenshots without contacting external hosts. |
| 📦 Tamper-Evident Export Bundles | Generates verifiable export packages with cryptographic SHA-256 checksums and immutable audit manifests. |
┌────────────────────────┐
│ Web Operator UI │
│ (React 18 + Vite) │
└───────────┬────────────┘
│ HTTP / REST
┌───────────▼────────────┐
│ Fastify REST API │
│ (RBAC, Rate Limits) │
└─────┬────────────┬─────┘
│ │
┌──────────────▼─┐ ┌─▼──────────────┐
│ PostgreSQL DB │ │ Redis Queue │
│ (Runs, Audit) │ │ (Broker) │
└────────────────┘ └─┬────────────┬─┘
│ │
┌───────────────────────▼──┐ ┌─▼────────────────────────┐
│ Playwright Browser Worker│ │ Comparison Worker │
│ • Isolated Contexts │ │ • Normalization Engine │
│ • SSRF & Route Guards │ │ • Jaccard / Cosine Diff │
│ • Pre-Storage Redaction │ │ • Rank / Delta Metrics │
└───────────┬──────────────┘ └───────────┬──────────────┘
│ │
└─────────────┬────────────────────┘
│
┌─────────────▼────────────┐
│ S3 / MinIO Object Store │
│ (Immutable Artifacts) │
└──────────────────────────┘
- Request Ingestion: REST API validates tenant permissions, idempotency keys, and registers the comparison run.
- Worker Dispatch: Parallel job requests are queued via Redis for both browser execution and differential analysis.
- Isolated Capture: Worker spawns ephemeral, isolated Playwright contexts, enforces SSRF rules, redacts PII, and streams assets to MinIO/S3.
- Metric Computation: Worker Compare calculates deterministic text, DOM, and visual similarity scores.
- Cryptographic Manifest: SHA-256 hashes are computed for all artifacts and saved into PostgreSQL for tamper-evident provenance.
- Node.js 24+ & npm 10+
- Docker Compose v2
# 1. Clone the repository
git clone https://github.com/omerfarooq223/ParallelWeb.git
cd ParallelWeb
# 2. Install dependencies & Playwright Chromium
npm install
npx playwright install chromium
# 3. Start local backing infrastructure (PostgreSQL, Redis, MinIO, OTel)
npm run stack:up# Start the web client development server
npm run dev --workspace=@ai-parallel-web/webOpen http://localhost:5173 in your browser to access the operator dashboard.
- API Health Readiness:
http://localhost:3000/health/ready - Local Deterministic Fixtures:
http://localhost:4300/fixture
PersonaDiff includes pre-seeded development tokens for role-based access control (RBAC):
| Role | Development Bearer Token | Permissions & Scope |
|---|---|---|
admin |
pw-admin-token-dev-only-0001 |
Full tenant management, runs, policy updates, and system metrics |
operator |
pw-operator-token-dev-only-001 |
Audit creation, live execution triggers, cancel, and diff inspection |
viewer |
pw-viewer-token-dev-only-0001 |
Read-only access to completed audit manifests and offline replays |
curl --request POST http://localhost:3000/v1/runs \
--header "Authorization: Bearer pw-operator-token-dev-only-001" \
--header "Idempotency-Key: audit-run-$(date +%s)" \
--header "Content-Type: application/json" \
--data '{
"surfaceId": "00000000-0000-4000-8000-000000000010",
"journeyVersionId": "00000000-0000-4000-8000-000000000020",
"personaVersionIds": [
"00000000-0000-4000-8000-000000000030",
"00000000-0000-4000-8000-000000000031"
]
}'PersonaDiff uses mathematically rigorous, deterministic algorithms to compare captures without bias:
| Metric | Algorithm / Formula | Flag Threshold | Purpose |
|---|---|---|---|
| DOM Element Presence | Jaccard Similarity on Element Sets | Detects missing or extra rendered UI containers | |
| Text Content Similarity | Tokenized Cosine & Jaccard Overlap | Identifies copy, title, and descriptive text changes | |
| Rank / Order Shift | Detects personalized sorting or item substitution | ||
| Numeric Delta | Detects price, fee, or quantity adjustments | ||
| Redirect Path Diff | Normalized URL Path Matching | Non-Identical | Flags routing or localized redirect discrepancies |
| Timing Delta |
|
Measures load duration and latency variance |
⚖️ Non-Causal Reporting Standard: All observations are reported as "Observed differences under recorded conditions". PersonaDiff strictly avoids inferring algorithmic intent, discriminatory motive, or causal mechanism.
Security and ethical guardrails are deeply embedded into the platform architecture:
- Strict Egress Containment: Restrictive route interception blocks network calls outside registered surface domains.
- SSRF Defense-in-Depth: Pre-navigation DNS resolution and CIDR filtering block intranet IPs (
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1,::1,169.254.169.254). - Automated Data Minimization: 30-day retention policies with cascading artifact deletion workflows.
- Sandboxed Replay: Targetless replay executes untrusted historical HTML within secure, sandboxed iframes.
ParallelWeb/
├── apps/
│ ├── api/ # Fastify REST API service (auth, routes, orchestration)
│ ├── browser-spike/ # Spike runner & surface policy testing harness
│ ├── fixture/ # Deterministic local target fixture service
│ ├── web/ # React 18 + Vite operator interface
│ ├── worker-browser/ # Playwright browser automation worker pool
│ └── worker-compare/ # Asynchronous comparison & metric worker
├── packages/
│ ├── auth/ # RBAC roles and permission evaluators
│ ├── capture/ # PII redaction engine, manifests & retention workflows
│ ├── comparison/ # Deterministic metric algorithms & normalization
│ ├── contracts/ # OpenAPI 3.1 specs, JSON schemas & TypeScript types
│ ├── db/ # PostgreSQL client pool, migrations & repositories
│ ├── domain/ # State machine, reconciliation & export builders
│ ├── observability/ # OpenTelemetry, Prometheus metrics & structured logger
│ ├── storage/ # S3 / MinIO immutable artifact adapter
│ └── test-fixtures/ # Shared golden test payloads
├── config/ # Surface policies & tooling configurations
├── docs/ # Architecture, security, specifications & runbooks
│ └── screenshots/ # UI showcase screenshots & evidence captures
├── infra/ # Docker compose stack & database migration scripts
└── tests/ # Contract, integration, failure-injection & security tests
PersonaDiff maintains high test coverage across unit, integration, contract, and security layers:
# Run the full automated test suite
npm test
# Run comprehensive workspace verification (Formatting + Lint + TypeCheck + Tests)
npm run check
# Run execution isolation tests (Playwright context separation)
npm test -- tests/integration/execution-isolation.test.ts
# Run security & SSRF defense test suites
npm test -- tests/security
# Validate OpenAPI contracts against schemas
npm run contracts:validate| Topic | Reference Document | Description |
|---|---|---|
| 🏛️ Architecture Decisions | docs/adr/ |
ADR-0001 through ADR-0005 documenting key technical decisions |
| 🔒 Security & Threat Model | docs/security/threat-model.md |
Comprehensive STRIDE threat model & attack surface mitigations |
| 📋 Privacy & Data Map | docs/security/privacy-data-map.md |
Field-by-field lifecycle, PII masking, and retention rules |
| 📜 Acceptable Use Policy | docs/security/acceptable-use-policy.md |
Responsible research guidelines and operational guardrails |
| 📊 Metric Specifications | docs/spec/comparison-metrics.md |
Metric algorithms, normalization logic, and thresholds |
| 🛠️ Operations & Runbooks | docs/operations/operations-handoff.md |
Production deployment, monitoring, and operational handoff |
PersonaDiff • Developed by Muhammad Umar Farooq • Built with ❤️ for deterministic, evidence-first web auditing.