White Paper 1: The Sovereign Security Architecture of see7

Executive Summary

The see7 platform is engineered on a Sovereign Security Framework, moving beyond traditional perimeter defense to a zero-trust, identity-centric architecture. By leveraging high-stability providers (Google Cloud, Firebase) and custom-hardened Edge middleware, see7 ensures that data integrity, multi-tenant isolation, and administrative sovereignty are maintained at every layer of the stack. This architecture is designed to meet and exceed the rigorous standards of SOC 2 Type 2, ISO 27001, and GDPR.

1. Identity Sovereignty & Access Management (IAM)

1.1 The Sovereign Handshake (Firebase + Edge)

see7 utilizes Firebase Authentication as its primary Identity Provider (IdP), offloading sensitive credential storage to audited infrastructure. However, see7 enforces a "Clean Room" session model:

• HTTP-only Session Cookies: Upon successful authentication, the system issues an __session cookie. Because it is HttpOnly, it is inaccessible to client-side JavaScript, neutralizing XSS risks.
• The Intelligent Porter (middleware.ts): Following see7 Standard #1 (Root Cause), authentication is verified at the Vercel Edge Runtime. This prevents "ghost jitters"—where a page loads partially before realizing a user is unauthenticated.
• Trust Signals (v and bypass_loop): To prevent Infinite Redirect Loops during complex auth handshakes, see7 uses internal parameters. The v signal acts as a cryptographic "trust stamp" from the Gateway, while bypass_loop allows the Edge to pass a request once the core has validated the session.

1.2 Multi-Factor Authentication (MFA) via TOTP

To exceed SOC 2 requirements, see7 enforces TOTP for sensitive roles.

• The Enrollment Gate: If a user's Prisma record indicates mfaEnabled, but the session lacks a verification timestamp, the middleware intercepts the request and forces a redirect to /auth/mfa-setup.
• Administrative Bypass: In emergency recovery scenarios, the mfaBypass flag (Standard #4) allows for controlled, audited access recovery without compromising the global security posture.

2. Multi-Tenant Hardening & Isolation

2.1 Prisma-First Authority & Repository Gating

Multi-tenancy in see7 is not a "soft" filter; it is a database-level requirement.

• The UserRepositoryAccess Guard: see7 utilizes a join-table architecture. A user does not simply belong to a company; they must have an explicit record in UserRepositoryAccess to see a specific Repository.
• Database-Level Scoping: Following Standard #1, every query is programmatically injected with a customerId and repositoryId predicate. This ensures that even if a UI component is compromised, the API will return null for any data outside the user's sovereign boundary.

2.2 Sovereign Role Switching

In alignment with Least Privilege (ISO 27001) principle, see7 implements Dynamic Role Contexts.

• ActiveRole Overrides: Users can switch "hats" (e.g., from Administrator to Searcher).
• Authority Logic: The permissions-server.ts prioritizes the Prisma activeRole over the Firebase JWT claim. This allows for Instantaneous Permission Updates, as database changes take effect faster than globally distributed JWT propagation.

3. Ingestion & Visual Fidelity Security

3.1 The Sovereign Mirror Proxy

To maintain 100% visual fidelity while viewing external intelligence, see7 uses an Active Proxy (/api/content/proxy).

• Path Rewriting: The proxy rewrites relative HTML paths to absolute URLs, preventing the browser from making unauthorized requests to foreign domains while inside the see7 vault.
• Header Sanitization: Dangerous security headers from source documents are stripped to prevent Clickjacking or CSP interference.

3.2 Content Integrity (Standard #3)

Every ingested document undergoes SHA-256 Hashing. Idempotency: If a document is re-crawled, see7 compares the new hash. If identical, the system suppresses the update, maintaining a "Single Source of Truth" and preventing version bloat.

4. Forensic Traceability & Hybrid Alignment

4.1 The Correlation ID Framework (Standard #6)

Every request generates a unique $UUID_v4$ at the Edge. End-to-End Auditability: This ID is injected into every [Forensic Log] ([SEARCH:FORCED], [RAG:REFLECT], [THEME:UPDATE]). Impersonation Transparency: Administrative impersonation sessions are tagged with isImpersonation: true, ensuring that every action taken by an admin on behalf of a user is traceable to the original actor.

4.2 Normalized Similarity Scoring (Standard #34.2)

see7 bridges the gap between raw vector math and human decision-making via Hybrid Alignment. The Logic: Raw Cosine Similarity scores from pgvector (typically 0.4 to 0.8) are linearly normalized into a 0–100% scale.

Relevance Badges: These scores drive the see7 Relevance Badge (Green/Yellow/Gray), allowing users to immediately gauge fact-confidence without needing to understand high-dimensional mathematics.

5. Compliance & Sovereign Deletion

GDPR Article 17: see7 supports the "Right to be Forgotten" via the gdpr-service.ts. Deletions trigger a cascading purge across PostgreSQL, pgvector, and Google Cloud Storage.

Data at Rest: All embeddings and metadata are stored within private Google Cloud VPCs, encrypted via Google-managed keys.