AIOrouter Security Architecture & PIPEDA Compliance Design

Document Type: Security Architecture Specification (Design-Only) Generated By: P1-W1-005-Adv (AIRO, DeepSeek V4 PRO) Version: 1.0.0 Date: 2026-05-02 Status: Draft for Founder Review Audit Requirement: GPT-5.5 audit for OWASP LLM Top 10 coverage completeness and PIPEDA mapping accuracy Enforcement: Downstream tasks consume machine-readable contracts at src/config/security-*.json

§1 — Threat Model

§1.1 Attack Surface Analysis

AIOrouter exposes the following attack surfaces:

§1.2 OWASP LLM Top 10 Mapping

Source of Truth: src/config/security-threat-model.json — machine-readable threat mapping

Enforcement: P1-W3-003-Adv (AI Firewall & PII Scrubber) MUST read src/config/security-threat-model.json at task start and verify every technique with status "designed" has a corresponding implementation control.

§1.3 MITRE ATLAS v4.0 Mapping

§1.4 API Key Threat Model

Source of Truth: src/config/security-api-key-policy.json — machine-readable API key security contract

§2 — PIPEDA Compliance Mapping

Reference: plans/AIOrouter-Development-Plan.md §0.2 — Two-Layer PIPEDA strategy

§2.1 All 10 PIPEDA Principles → Technical Controls

Execution evidence: P1-W3-005 implements this PIPEDA execution layer via ConsentManager, DsarHandler, BreachNotification, DataAggregator, and migration 002_pipeda_compliance.sql. P1-W1-005 remains the upstream architecture contract; downstream tasks must consume the concrete P1-W3-005 files rather than recreating legacy pre-DSAR route or billing table artifacts.

§2.2 Two-Layer Strategy

Layer 1: PIPEDA 基础合规（Built-in — 所有用户免费享有，Day 1 必须上线）
  ├── PII 自动脱敏 — GCP DLP 扫描 → 转发前自动脱敏/阻断
  ├── 零 prompt 留存 — 技术强制，prompt 仅在内存中转发
  ├── 加拿大数据驻留 — 所有基础设施在 Montreal GCP
  ├── HTTPS 加密传输 — 全程 TLS 1.3
  └── 透明隐私政策 — 清晰说明数据流

Layer 2: Compliance-as-a-Service（$49/月 加购 — 面向受监管行业，Phase 3 开放）
  ├── PIPEDA/Law 25 审计追踪报告
  ├── 数据驻留认证（签名 PDF）
  └── 季度合规报告

Key insight: Layer 1 covers all 10 PIPEDA principles technically. Layer 2 provides formal audit documentation for regulated enterprises.

§3 — Data Flow Diagram with Security Control Points

User/Client
    │
    │  HTTPS (TLS 1.3)
    ▼
┌─────────────────────────────────────────────────────────────┐
│  GCP Cloud Load Balancer + Cloud Armor WAF                  │
│  [CP-1] OWASP Top 10 WAF rules (P1-W1-006)                 │
│  [CP-2] Rate limiting: 120 req/min /v1/chat/completions     │
│  [CP-3] IP reputation check (Adaptive Protection)           │
└─────────────────────────────────────────────────────────────┘
    │
    │  Forwarded to Cloud Run
    ▼
┌─────────────────────────────────────────────────────────────┐
│  API Gateway (Express — src/gateway/)                       │
│  [CP-4] API Key authentication (Bearer token, SHA-256 hash) │
│  [CP-5] Rate limiting (per-user, per-model, Redis counters) │
│  [CP-6] Request validation (model, messages, max_tokens)    │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Security Layer (src/security/)                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ [CP-7] AI Firewall — scanPrompt()                    │   │
│  │   • Prompt injection detection                       │   │
│  │   • Jailbreak heuristics                            │   │
│  │   • Sensitive data regex patterns                   │   │
│  │   → Decision: BLOCK / REDACT / PASS                  │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ [CP-8] Bidirectional PII Handler                    │   │
│  │   • AI Firewall-processed prompt is cache-key input │   │
│  │   • GCP DLP deidentifyContent() with deterministic  │   │
│  │     crypto emits SURROGATE_PII(length):value tokens │   │
│  │   • Tokens are rewritten to [ENTITY_N] for providers│   │
│  │   • Any DLP/KMS runtime failure discards partial     │   │
│  │     results and uses strict redaction/fail-closed    │   │
│  │   • Request-scoped token map is never persisted     │   │
│  │   → Pseudonymized prompt forwarded to router        │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ [CP-9] Budget Circuit Breaker — budget-guard.ts     │   │
│  │   • Daily budget check per user                     │   │
│  │   → Over budget? Return 402 with quota reset time   │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Semantic Cache (src/cache/)                                │
│  [CP-10] Embedding hash lookup (Redis)                      │
│  → Cache HIT? Return cached response (no API call)          │
│  → Cache MISS? Continue to router                           │
│  NOTE: Cache key is derived from the post-firewall,          │
│        pre-pseudonymization prompt and stored as a hash only │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Model Router (src/router/)                                 │
│  [CP-11] Provider selection (price, health, latency)        │
│  [CP-12] Fallback chain on failure                          │
│  [CP-13] Auto Price-Hold on price spike                     │
└─────────────────────────────────────────────────────────────┘
    │
    │  Outbound TLS 1.3
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Provider Adapter (src/providers/)                          │
│  [CP-14] Provider-specific API call                         │
│  [CP-15] Response sanitization before return                │
│  NOTE: PII scrubber also scans responses (reasoning_content)│
└─────────────────────────────────────────────────────────────┘
    │
    │  Response returned to user
    ▼
User/Client

Side Channel — Audit Trail:
  [CP-16] Every request logged to GCS (immutable, append-only):
    • user_id, request_id, model, token_count, cost
    • pii_scan_result (boolean only — no PII content)
    • pseudonymized_entity_count/types, depseudonymized flag
    • privacy_mode and fallback reason when redaction fallback is used
    • streaming_privacy_rejected and unresolved artifact flags
    • firewall_verdict (BLOCK/REDACT/PASS)
    • NO prompt content, NO API keys, NO PII

§4 — Encryption Architecture

Source of Truth: src/config/security-encryption.json — machine-readable encryption requirements

§4.1 Data-in-Transit

§4.2 Data-at-Rest

Enforcement verification (P1-W4-006): "PostgreSQL CMEK: ✓ | Redis TLS+AUTH: ✓ | GCS CMEK+Bucket Lock: ✓"

§4.3 Data-in-Use (Zero Retention)

§5 — Secret Management Architecture

Source of Truth: src/config/security-secret-inventory.json — machine-readable secret inventory

§5.1 Secret Inventory (13 Secrets)

§5.2 IAM Policy

• Secret Accessor: cloud-run-sa@${PROJECT}.iam.gserviceaccount.com (Cloud Run service account)
• Admin Access: Founder only (manual via Cloud Console)
• Audit Logging: All Secret Manager access logs → Cloud Logging; alert on unauthorized access
• Secrets NEVER in: .env (committed), source code, logs, error messages, API responses

§5.3 Rotation Automation

• Task: P3-M3-000 (Secret Rotation Automation) reads this inventory as source of truth
• New Provider Onboarding: Every new provider adapter MUST add its API key entry to this JSON
• Pre-commit Enforcement: tooling/pre-commit.sh scans staged files for aiorouter_ patterns and blocks commits
• Allowlist Note: This file itself is in the pre-commit allowlist (documents names, not values)

§6 — Logging Security

Source of Truth: src/config/security-logging-rules.json — machine-readable logging security rules

§6.1 Forbidden Log Fields

§6.2 Log Separation

§6.3 Runtime Enforcement

• src/gateway/security-headers.ts MUST include a logSanitizer() function
• CI test at tests/security/log-sanitization.test.ts:
  • Spins up server
  • Sends request with simulated aiorouter_ API key
  • Verifies log output contains only masked keys

§7 — Webhook Security

Source of Truth: src/config/security-webhook-policy.json — machine-readable webhook security contract

§7.1 Stripe Webhook

§7.2 Hermes Webhook

§7.3 Common Security Controls

CI Test: tests/security/webhook-security.test.ts verifies:

• Unsigned webhook requests receive 401
• Idempotency key deduplication works correctly
• Non-Stripe IPs are rejected

§8 — AI Firewall Rules Specification

§8.1 Prompt Injection Detection Patterns

The AI Firewall (ai-firewall.ts:scanPrompt()) scans all incoming messages[] content for:

Category A: Direct Injection (BLOCK)

Category B: Encoding Bypass (BLOCK)

Category C: Multi-Stage Injection (REDACT → Log)

§8.2 Jailbreak Detection Heuristics

§8.3 Sensitive Data Regex Patterns

§8.4 Decision Matrix

§8.5 GPT-5.5 Audit Requirement

P1-W3-003-Adv (AI Firewall & PII Scrubber implementation) must be audited by GPT-5.5 against the OWASP LLM01 Prompt Injection attack catalog. Audit must verify:

• All 5 Category A patterns are detected
• Encoding bypass (Base64, ROT13, Unicode) is handled
• Multi-stage injection scoring correctly accumulates across messages
• Jailbreak heuristic threshold tuning is appropriate (not too strict → false positives; not too loose → misses)

§9 — PII Scrubber Specification

§9.1 GCP DLP API Integration Architecture

User Prompt
    │
    ▼
┌─────────────────────────────────────────────────────┐
│  PII Scrubber (pii-scrubber.ts:scan())              │
│                                                     │
│  1. Receive prompt text                             │
│  2. Call GCP DLP API: projects.content.inspect      │
│     • InfoTypes: CANADA_SOCIAL_INSURANCE_NUMBER     │
│     • InfoTypes: CREDIT_CARD_NUMBER                 │
│     • InfoTypes: EMAIL_ADDRESS                      │
│     • InfoTypes: PHONE_NUMBER                       │
│     • InfoTypes: PERSON_NAME                        │
│     • InfoTypes: STREET_ADDRESS                     │
│     • InfoTypes: ONTARIO_HEALTH_INSURANCE_NUMBER    │
│     • Likelihood threshold: LIKELY or higher        │
│  3. GCP DLP returns: findings[] (locations, types)  │
│  4. Apply transformations per finding:              │
│     • SIN → [REDACTED SIN]                          │
│     • Credit Card → [REDACTED CC]                   │
│     • Email → [REDACTED EMAIL]                      │
│     • Phone → [REDACTED PHONE]                      │
│     • Name → [REDACTED NAME]                        │
│     • Address → [REDACTED ADDRESS]                  │
│     • OHIP → [REDACTED OHIP]                        │
│  5. Return sanitized prompt + scan metadata         │
│     • { sanitizedText, hasPII: boolean,             │
│         findingsCount: number, latencyMs: number }  │
└─────────────────────────────────────────────────────┘
    │
    ▼
Sanitized Prompt → Router → Provider Adapter

§9.2 GCP DLP Pre-Flight Setup

Before P1-W3-003-Adv implementation, the following must be provisioned (P1-W1-005 pre-flight step 0):

1. Enable dlp.googleapis.com in GCP project gcp-aiorouter
2. Create DLP service account with roles: roles/dlp.user, roles/dlp.reader
3. Pre-configure Canadian PII infoTypes (listed in §9.1)
4. Create DLP inspection template for AIOrouter prompt scanning (likelihood threshold: LIKELY)
5. Verify DLP API connectivity via gcloud dlp text inspect
6. Store DLP service account credentials in GCP Secret Manager (key: dlp-service-account)

§9.3 Transformation Rules

Note: Silent redaction means the user's prompt is modified before forwarding to the provider, but the user is not explicitly told "we found your SIN and redacted it." The redaction is transparent. Users who need to send PII intentionally are guided to use the Compliance-as-a-Service tier (Layer 2), which provides audited PII handling with explicit consent.

§9.4 Reasoning Output Scanning

Some models (e.g., DeepSeek-R2) expose a reasoning_content field in their response containing chain-of-thought reasoning. This content must be PII-scanned with the same rules as user prompts:

Provider Response
  ├── content → PII scrub (same rules)
  └── reasoning_content → PII scrub (same rules) BEFORE:
      • Returning to user
      • Storing in semantic cache
      • Logging (even at debug level)

Rationale: Reasoning content could inadvertently contain PII from the user's prompt that the model repeats during its chain-of-thought.

§9.5 Latency Budget

Optimization: If the AI Firewall regex scan finds NO matches (which is the common case), skip the GCP DLP API call entirely. Only invoke DLP when the regex scan finds potential PII matches. This reduces the common-case latency to <10ms.

§9.6 Bidirectional Pseudonymization (V2.11.0)

BidirectionalPiiHandler upgrades the one-way scrubber path for provider dispatch:

1. AI Firewall runs first. BLOCK requests stop before cache or provider dispatch.
2. The semantic cache key is computed from the AI Firewall-processed request before pseudonymization. The cache implementation stores a normalized hash, not prompt text. Different PII values intentionally produce different cache keys.
3. GCP DLP deidentifyContent() uses CryptoDeterministicConfig with KMS-wrapped key material and emits official surrogate tokens in the form SURROGATE_PII(length):SURROGATE_VALUE.
4. A request-scoped in-memory map rewrites DLP surrogates to LLM-friendly template tags such as [ENTITY_1]. The map is never written to Redis, PostgreSQL, disk, logs, or audit records.
5. Provider dispatch receives only the pseudonymized request.
6. Before returning to the user or writing a semantic cache entry, reidentifyContent() must include inspectConfig.customInfoTypes[].surrogateType for SURROGATE_PII, then the final response is checked for unresolved template tags or surrogate tokens.
7. Streaming requests with detected PII fail closed with unsupported_streaming_privacy_mode until a dedicated streaming depseudonymization transformer exists.

§10 — Audit Trail Specification

§10.1 Events Captured

Every API request generates an audit event with the following fields:

§10.2 Storage & Immutability

§10.3 Query API

Users can access their own audit trail via the dashboard:

GET /dashboard/audit?from=2026-04-01&to=2026-05-01&page=1&limit=50

Response:
{
  "events": [...],
  "total": 1234,
  "page": 1,
  "has_more": true
}

• Access Control: Users can only query their own events (enforced by user_id from API key)
• No PII in Response: Audit events never contain prompt text, PII values, or API keys
• Export: CSV/JSON export available for compliance purposes

§10.4 Internal Audit Access

For PIPEDA compliance, the Founder (Designated Privacy Officer) can access audit logs for any user to respond to:

• Data access requests (Principle 9)
• Compliance challenges (Principle 10)
• Law 25 breach investigations

Access is logged in a separate admin_audit table for accountability.

§11 — Third-Party Integration Security

§11.1 OpenRouter Provider Integration

When AIOrouter becomes an OpenRouter Provider (Phase 2+), the following security requirements apply:

§11.2 Data Processing Agreement (DPA) Minimum Standards

For any third party that processes AIOrouter user data (e.g., if AIOrouter becomes a customer of another service):

§11.3 External API Security Gating

Before integrating any new external API (provider, monitoring service, etc.):

1. Security Review: Assess API's authentication model, encryption (TLS 1.3+), and data handling
2. ToS Compliance: Verify AIOrouter's use case is permitted by the provider's Terms of Service
3. Credential Storage: API key stored in GCP Secret Manager only — never in .env or source code
4. Access Scoping: Service account has minimum required permissions (least privilege)
5. Audit Logging: All external API calls logged with provider, latency, and error information

§12 — Downstream Contract Registration

The following machine-readable security contracts are registered for downstream task consumption:

§9.7 — Jurisdictional Reality (V2.20.0 — P2-W7a-PIA-PATCH)

Section added 2026-05-12 under owl-mode audit by Claude Opus 4.7 to align public language with technical fact and current European post-Schrems II framing.

§9.7.1 Two-Layer Privacy Boundary

AIOrouter protects cross-border requests with two cooperating layers built and maintained in Canadian-resident infrastructure:

§9.7.2 What Crosses the Border — and What Does Not

                ┌─────────────────────────────────────────┐
                │  Canadian Jurisdiction (GCP Montreal)   │
                │                                          │
   User ──────▶ │  PII Layer + Content Layer              │
                │  (token map, master key — KMS-locked)   │
                └────────────────────┬────────────────────┘
                                     │  Only crosses:
                                     │   • [PERSON_NAME_N], [EMAIL_ADDRESS_N], …
                                     │   • ⧖<aead-ciphertext>⧗
                                     │   • non-sensitive prompt scaffold
                                     ▼
                ┌─────────────────────────────────────────┐
                │  Outside Canada (AI provider)           │
                │  Cannot re-identify; cannot decrypt.    │
                └─────────────────────────────────────────┘

Raw PII never leaves Canada. What crosses the border is irreversible by construction at any party that does not hold the Canadian-resident key material.

§9.7.3 What This Does NOT Claim

In compliance with PIPEDA s.6.1 (accuracy) and CPPA s.62 (transparency), we do not overclaim:

1. Pseudonymised data is still personal data under GDPR Art.4(5) and EDPB Recommendations 01/2020 §85. We do not claim the cross-border transfer is exempt from privacy law.
2. LLM paraphrase / inference linkage is a residual risk. A provider's training prior may produce a plausible transliteration (e.g., pinyin) of a pseudonymised name. This is detected (and optionally replaced) by src/security/inference-leak-scanner.ts (P2-W7-016d).
3. Metadata side-channels exist (token count, request timing, TLS fingerprint). Hardening is sequenced as P2-W7a-HARDEN-001.
4. Multimodal PII (images, audio) is not yet covered — AIOrouter does not currently accept these modalities. Scheduled for P3-M3-008-MM.
5. Memory-resident token map would be exposed by a Cloud Run process compromise. The differentiation roadmap is P4-M12-CC-001 (Sovereign Confidential Computing Tier — AMD SEV-SNP / GCP Confidential Space).

§9.7.4 Public-Facing Canonical Wording

For consistency across docs, site, and marketing, three canonical forms are maintained in plans/AIOrouter-Task-P2-W7a-PIA-PATCH.md §2: long form (PIA, security docs), short form (FAQ, marketing), one-line form (tweets, micro-copy).

§9.7.5 Region-Pin Enforcement (X5 / P2-W7a-GAP-009)

Three layers of defense enforce the Canadian-region commitment in code:

1. Terraform variable validation — infra/modules/cloud-run/main.tf and infra/modules/logging-residency/main.tf reject any gcp_region outside {northamerica-northeast1, northamerica-northeast2}. terraform plan fails before any non-Canadian resource is described.
2. CI residency guard — tooling/check-canadian-residency.mjs scans every *.tf / *.tfvars file under infra/ for region/location assignments and KMS resource paths. Wired into npm run ops:validate as step 5. Pragma # residency-check:allow is available for documentation lines only.
3. Cloud Logging bucket pin — infra/modules/logging-residency/main.tf recreates the _Default Cloud Logging bucket as a region-pinned resource (default location is global, which would silently violate residency) and routes all non-_Required entries to the regional GCS audit bucket.

BETA-Ready State Provisioned via gcloud (2026-05-12):

BETA-Day-1 effect: 100% of AIOrouter-generated logs (request traces, security findings, billing events, gateway metrics) write to Montreal. Only Google-internal Cloud audit logs about the GCP project itself (IAM changes, project metadata, etc.) remain in _Required/global, which is identical for every GCP project worldwide.

Founder-gated (NOT achievable without prerequisite work):

# Prerequisite: This project must be migrated into a Google Cloud Organization
# (created via Cloud Identity or Google Workspace on the aiorouter.ca domain).
# Standalone projects CANNOT receive Org Policies — confirmed via:
#   $ gcloud projects add-iam-policy-binding gcp-aiorouter \
#       --member=user:tayachu@gmail.com --role=roles/orgpolicy.policyAdmin
#   ERROR: Role roles/orgpolicy.policyAdmin is not supported for this resource.

# Once an Organization exists and the project is migrated:
cat > /tmp/canada-only-policy.yaml <<'EOF'
name: projects/gcp-aiorouter/policies/gcp.resourceLocations
spec:
  rules:
    - values:
        allowedValues:
          - in:northamerica-northeast1-locations
          - in:northamerica-northeast2-locations
EOF
gcloud org-policies set-policy /tmp/canada-only-policy.yaml \
  --project=gcp-aiorouter

# Verify after Org Policy is active:
gcloud logging buckets list --project=gcp-aiorouter
gcloud org-policies describe gcp.resourceLocations \
  --project=gcp-aiorouter --effective

Why this is acceptable for BETA: Even without the Org Policy layer, the three-layer code defense (Terraform validation + CI guard + project-level routing sink) prevents drift at every commit and at deploy time. Adding the Org Policy layer hardens the GCP-API surface against manual gcloud calls bypassing Terraform — a meaningful but secondary defense given that only Founder has owner-level access today.

§9.8 — SOTA Gap Register (V2.20.0)

Honest tracker of known residual gaps in the cross-border privacy architecture. Updated whenever a remediation task is created, completed, or its scope changes. Reviewed at each Phase boundary.

Legend: ✅ = remediated this session; 📋 = scheduled in backlog/roadmap; ❌ = accepted residual with documented rationale.

§13 — Scope Note — Account Security

This document covers API-level security:

• AI Firewall rules for prompt content
• PII scrubbing for data privacy
• API key threat model and lifecycle
• Secret management and rotation
• Logging security and redaction
• Webhook security and verification

Account-level security — including MFA/Passkey authentication, session management, dashboard API key security, and the Canada-resident Auth Enclave default customer-auth route — is designed separately in ⚠️ P2-W5-004-Adv (docs/account-security-architecture.md). The two documents together form the complete AIOrouter security architecture.

Next Steps:

1. Founder review gate: Confirm OWASP LLM Top 10 threat coverage, secret inventory completeness, logging security rules
2. P1-W2-001 (API Gateway): Implement API key format and deterministic SHA-256 lookup hashing per security-api-key-policy.json
3. P1-W3-003-Adv (AI Firewall & PII Scrubber): Implement all patterns from this specification
4. P1-W4-003 (Cloud Monitoring): Configure Pino serializers per security-logging-rules.json
5. P1-W4-006 (Container Hardening): Verify all data-at-rest encryption per security-encryption.json
6. GPT-5.5 Audit: Verify threat model completeness and PIPEDA mapping accuracy
7. 🆕 P2-W7-016-Adv (V2.11.0): Bidirectional PII Pseudonymization — upgrade from one-way redaction to GCP DLP CryptoDeterministicConfig round-trip (pseudonymize → LLM → depseudonymize). See plans/AIOrouter-Bidirectional-PII-Retroactive-Fixes.md.