Veridion API Master

description: Veridion API master rules - standalone service, own database, multi-tenant SaaS globs:

• "*/.rs"
• "*/.toml"
• "*/.sql"
• "*/.md"
• "*/.tsx"
• "*/.ts"

VERIDION API - Master Project Rules

You are working on Veridion API, a standalone HTTP service with its own database and migrations. It is not veridion-nexus.

ALWAYS READ FIRST

• PROJECT_REFERENCE.md - the definitive project reference (v3.2, updated 2026-04-07)

WHAT THIS PROJECT IS

• Standalone REST API (Rust/Actix-web) + Sovereign Shield dashboard (Next.js 14, port 3000) + Landing page with signup (Next.js 14, port 3001, veridion-landing/)
• Own PostgreSQL database with own migrations (001–027+)
• No shared code or migration path with veridion-nexus
• Multi-tenant SaaS: one shared instance, all tenants isolated by tenant_id

THREE PILLARS (CORE FEATURES)

1. Sovereign Shield — International data transfer monitoring and enforcement (GDPR Art. 44–49)
2. Evidence Vault — Immutable, cryptographically sealed audit trail (hash chains, Nexus Seals)
3. Human Oversight — EU AI Act Art. 14 human review queue for REVIEW decisions

FEATURE FLOW

• Sovereign Shield → Evaluates transfers, returns ALLOW/BLOCK/REVIEW, creates evidence
• Review Queue → When SS triggers REVIEW, creates review entry for human decision
• Evidence Vault → Stores all evidence (SS decisions + human decisions), append-only

SIX DESIGN DECISIONS (NEVER VIOLATE)

1. Strictest-wins aggregation — Any BLOCK = final BLOCK
2. REVIEW as safe default — Insufficient context = REVIEW, not ALLOW
3. Evidence is immutable — Append-only, never UPDATE or DELETE on evidence_events
4. Hash chain integrity — Every event links to previous via previous_hash
5. Nexus Seal required — SHA-256(payload_hash + previous_hash + salt)
6. Human oversight for REVIEW — All REVIEW decisions go to Review Queue

MULTI-TENANCY RULES (NEVER VIOLATE)

• Every data query MUST filter by tenant_id (evidence_events, scc_registries, compliance_records, human_oversight, system_settings)
• API key auth middleware runs on all /api/v1/* routes
• Exempt from auth: GET /health, GET /api/v1/auth/dev-bypass, POST /api/v1/auth/register
• Admin routes (/api/v1/admin/*) require is_admin = true; they are the ONLY routes that may query without tenant_id filter
• api_key_hash is NEVER returned in any API response
• rate_limit_per_minute is stored in tenants table but NOT enforced until Phase 1
• Dev bypass: RUST_ENV=development + missing auth header → inject admin TenantContext automatically
• Signup exempt: POST /api/v1/auth/register has no tenant auth — it creates the tenant

LANGUAGE RULES (NEVER VIOLATE)

• Never say "compliant", "certified", "guaranteed compliance", "X% compliant"
• Always say "provides structured, time-bound evidence" or "supports demonstrable compliance"

TECHNOLOGY

Backend (Rust)

• Rust 2021, Actix-web 4, PostgreSQL + SQLx, JWT/bcrypt, sha2 crate (SHA-256)
• Pattern: web::Data<PgPool> — no AppState struct
• Middleware: .wrap() — tenant auth middleware wraps all /api/v1/* routes
• TenantContext injected via req.extensions_mut().insert(...), extracted via req.extensions().get::<TenantContext>()

Dashboard (Next.js)

• Next.js 14 (App Router), React 18, Tailwind CSS 3.x, lucide-react, react-simple-maps
• Port 3000; API calls via relative URLs proxied to backend (avoids CORS)
• Theme: dark (slate-900/800/700), emerald accents, Inter + JetBrains Mono fonts

CRITICAL TYPES

• TenantContext in src/tenant.rs — tenant_id, name, mode, plan, is_admin
• EvidenceEventRow in src/models/mod.rs — immutable audit event
• Decision enum: ALLOW, BLOCK, REVIEW
• EventSeverity: L1 (critical), L2 (high), L3 (medium), L4 (low)
• Regulatory tags: GDPR, DORA, NIS2, AI_ACT

SOURCE FILES

Backend (src/)

• main.rs — entry point, route registration, middleware setup
• tenant.rs — TenantContext, TenantRow, sha256_hex helper, load_admin_tenant
• middleware_tenant.rs — API key auth middleware
• models/mod.rs — all domain models
• evidence.rs — Evidence Vault core logic
• shield.rs — Sovereign Shield decision engine
• review_queue.rs — Human Oversight logic
• routes_auth.rs — POST /api/v1/auth/register (signup, rate limiting, tenant+user creation)
• email.rs — SMTP welcome email via lettre (async, graceful degradation)
• routes_evidence.rs — /api/v1/evidence/*
• routes_shield.rs — /api/v1/shield/, /api/v1/scc-registries/, /api/v1/settings
• routes_review_queue.rs — /api/v1/review-queue/, /api/v1/action/
• routes_admin.rs — /api/v1/admin/* (admin only, cross-tenant)
• routes_agents.rs — /api/v1/agents/* (agent registry, per-agent policy)

Dashboard (dashboard/)

• app/utils/api.ts — API client, all fetch functions, types
• app/page.tsx — Sovereign Shield home
• app/transfer-log/page.tsx — Transfer Log
• app/transfer-detail/[id]/page.tsx — Transfer Detail
• app/review-queue/page.tsx — Review Queue
• app/scc-registry/page.tsx — SCC Registry
• app/adequate-countries/page.tsx — Adequate Countries (static)
• app/agents/page.tsx — Agent Registry (registered + unregistered)
• app/evidence-vault/page.tsx — Evidence Vault
• app/components/Sidebar.tsx — Nav (branding: VERIDION nexus / Compliance Dashboard v1.0.0; System: AI System Registry, ACM Overview; /acm/oversight and /acm/transfers not in sidebar)
• app/components/SovereignMap.tsx + WorldMap.tsx — transfer map
• app/config/countries.ts — country classifications, getLegalBasis helpers

MIGRATIONS

• ./migrations/ only, numbered 001–027+
• Key tables: users, tenants, compliance_records, human_oversight, evidence_events, scc_registries, system_settings
• Migration 026 adds: tenants table, tenant_id to all data tables, admin tenant seed
• Migration 027 adds: FK constraint users.company_id → tenants.id
• Never reference paths outside this project

CONFIGURATION

COMPLIANCE FACTORY WORKFLOW

1. REGULUS — Determine applicable regulations and articles, write Regulatory Contract
2. ARCHON — Design technical architecture, write Design Contract
3. FORGER — Implement code following Design Contract
4. AUDITOR — Review code for compliance correctness before merge
5. SENTINEL — Write tests that verify regulatory compliance

API KEY FORMAT

• Production: ss_live_[32-char hex]
• Sandbox/test: ss_test_[32-char hex]
• Only api_key_hash (SHA-256) stored in DB — raw key never persisted or returned