Multi-Tenant Isolation & Tamper-Evident Audit

Isolation you can't forget to apply

Most cross-tenant breaches aren't exotic. They're an endpoint that forgot a WHERE tenant_id = ?, a tenant identifier trusted from the request body, or a connection that leaked one customer's context into another's query because it was pooled. The defining idea of this blueprint is to make those mistakes structurally impossible rather than relying on every developer remembering every time.

Two principles do the heavy lifting. First, the tenant, the acting user and their role are resolved once, from the cryptographically verified session, and flow down through the request — they are never accepted from client-controlled input. Second, isolation is layered: even if the application layer slips, a second independent mechanism in the database refuses to return another tenant's data.

Four layers of the same guarantee

Where each control lives

flowchart TB
    C["Client"] -->|"token (bearer)"| GW["Gateway / middleware"]
    GW --> V["Verify token
extract tenant · user · roles"]
    V --> CHK{"Tenant in
provisioned registry?"}
    CHK -->|no| DENY["Reject"]
    CHK -->|yes| CTX["Request context
(server-trusted)"]
    CTX --> RBAC["RBAC guard
default-deny"]
    RBAC --> H["Handler / domain"]
    H --> SESS["DB session:
set tenant scope (per-tx)
drop to non-privileged role"]
    SESS --> DB[("Database
schema-per-tenant + row-level security")]
    H --> AUD["Append audit entry
hash chained to previous"]
    AUD --> DB
        

Isolation strategies, compared

Change and audit commit together

sequenceDiagram
    participant C as Client
    participant M as Middleware
    participant H as Handler
    participant DB as Database
    C->>M: Mutating request + token
    M->>M: Verify · resolve tenant/role · validate registry
    M->>H: Context (tenant, user, role)
    H->>DB: BEGIN
    H->>DB: SET LOCAL tenant scope + role
    H->>DB: Apply change (RLS active)
    H->>DB: Append audit entry (hash = H(prev || change))
    H->>DB: COMMIT
    DB-->>H: OK (or rollback both)
    H-->>C: Result
        

Five alternate use cases

Where isolation quietly fails

The non-negotiables

• Bind tokens tightly: verify issuer and audience so a valid token for a different client or service account in the same realm is rejected.
• Keep any token-free development shortcut hard-gated to both an explicit dev auth-mode and a development environment, so it can never grant access in staging or production.
• Prefer bearer tokens over cookies where you can, so cross-origin rules are a backstop rather than a primary control; keep CORS an explicit allowlist and refuse wildcards in production.
• Log sensitive reads, not just writes, when the domain requires it — a separate access log answers "who looked at this record," which write audits alone cannot.
• Encrypt the most sensitive fields with authenticated encryption and a rotatable, versioned key (see Blueprint 03's key-provider seam), so a database leak is not automatically a data leak.

When to reach for it — and when not to