Tenant Isolation

1) Successful login is not isolation proof

A multi-tenant SaaS user can hold a valid JWT, pass role checks, and receive an authorization allow while still reaching another tenant's resource. Tenant Isolation Boundary & Cross-Tenant Access Test Matrix v1 asks a different question: does every access path constrain the resource to the tenant of the current request?

2) Bind SaaS identity at entry

user_id and tenant_id need a controlled source. If an API accepts an arbitrary tenant selector from a query parameter or header and treats it as authority, the boundary is weak. Tenant context should enter with identity and remain available to downstream layers.

3) Enumerate resource planes separately

Isolation is not only a database concern. Data stores, object storage, caches, queues/topics, search indexes, compute jobs, logs/metrics, admin tools, exports and the control plane can all cross tenant boundaries. Each plane needs its own isolation model and policy enforcement point.

4) Name the enforcement point

“We are tenant-aware” is not evidence. State where policy is enforced: API gateway, service handler, repository layer, database policy, IAM/ABAC, cache namespace, queue consumer or admin proxy. UI-only enforcement does not protect backend paths.

5) Align partition keys with tenant scope

In a pooled design, a resource_id may not be sufficient as an access boundary. Data partitions, indexes and cache keys must carry tenant scope explicitly or through an equivalent enforced policy. A cache key that omits tenant_id can return correct data to the wrong tenant even when authentication is valid.

6) Keep asynchronous paths tenant-aware

A queue producer may attach tenant metadata, but the consumer must verify and enforce that context. A shared queue without tenant-scoped consumer checks replaces isolation with trust in the producer. Retries, DLQs and batch workers remain part of the same boundary.

7) Operational tooling is part of the boundary

Exports, support consoles, backfill scripts and admin tools often have more power than normal request paths. If an operations query can accept an arbitrary tenant selector, you have a bypass path. Any exception needs explicit authority, scope and audit evidence; “admins only” is not enough.

8) Require both positive and negative tests

A same-tenant positive test proves that allowed access still works. A cross-tenant negative test proves the boundary denies the wrong tenant. Positive tests alone cannot establish isolation; the state remains HOLD until negative evidence exists.

9) Never strengthen the state beyond evidence

VERIFIED requires complete context, enforcement, partition and test evidence. A real boundary breach is FAILED. Missing evidence is UNKNOWN or HOLD; stale evidence is STALE; material change without recomputation is PARTIAL; conflicting authority is DISPUTED; an explicit owner prohibition is BLOCKED.

10) Separate external facts from MAKNOW design

AWS guidance distinguishes tenant isolation from authentication/authorization, elevates tenant context into SaaS identity, and scopes resource access to the current tenant. MAKNOW's matrix fields, typed states and requirement for explicit negative evidence before VERIFIED are local design choices, not universal AWS thresholds.

11) Build the matrix as auditable evidence

The working table places tenant/user context, resource plane, enforcement point, partition key, positive/negative tests, bypasses and audit events in one reproducible view.

12) Negative case: cache key omits tenant_id

Assume the API and database are correctly tenant-scoped, but the cache key is only product_id. Tenant B can receive a cached response belonging to Tenant A. Authentication still succeeds, yet the cache plane has failed. The overall boundary cannot remain VERIFIED.

13) Negative case: operations export accepts arbitrary tenant_id

An export tool that trusts an operator-supplied tenant parameter creates a bypass. Tenant context must come from controlled authority, or the exception path needs independent scope, authorization and audit controls. An arbitrary override without those controls is FAILED.

14) Transfer: dedicated storage, pooled compute

Move one high-risk tenant to dedicated storage. Only the data plane changed. Pooled compute, cache, queue, logs and operations still require tenant context and negative tests. Do not copy the baseline verdict; rebuild the matrix plane by plane.

15) Completion test

Finish when another reviewer can reproduce the same verdict from visible evidence: tenant/user binding, context source, resource planes, isolation model, enforcement point, authorization context, partition key, same-tenant test, cross-tenant test, bypass path, failure domain, audit event, state and evidence reference. Never mark an important plane green because it is “probably safe.”