Define the boundary before choosing the mechanism
The manager decides which parties may share an application, database, queue, cache, index, logs, backups, operators, and providers, and which require stronger separation. Only then can logical tenants, organizations, separate deployments, or a hybrid model be evaluated.
Evidence boundary
Logical controls are a foundation; isolation is a tested system property
Current source provides logical tenant records, hierarchical organizations, RBAC-derived scope, scoped helpers, API-key context, cache and derived-data conventions, schedule scope, and mapped-field encryption. A deployment still has to prove every custom, background, physical, external, privileged, and legal boundary.
- Reviewed
- 2026-07-14
- Product revision
- 01911d00e28f44cf484d0b1d04860dcfef5370bf
- Latest public tag and package
- v0.6.5 / 0.6.5
- Current-source distance
- 234 relevant paths changed since v0.6.5; current observations are not release claims.
Independent editorial guide. Not the product owner, host, security assessor, compliance authority, KMS provider, or implementation supplier.
Eleven boundaries that must not be collapsed
Deployment or application instance
A running application and its configured infrastructure. One deployment can hold multiple logical tenants.
Logical tenant
A Tenant record and primary partition key used by product conventions; not automatically a database, region, legal entity, or key root.
Organization
A tenant-owned hierarchical business unit. Parent and descendant expansion can affect authorized views.
Allowed organizations
The authorization set derived from RBAC, potentially expanded to descendants.
Selected organization
A current view choice. It can narrow authorized data but cannot grant wider access.
Tenant-wide or global row
A deliberately organization-null row or a distinct scope contract; null must be policy, not a bypass.
Super-admin
A privileged identity able to bypass ordinary checks in specified paths; not an ordinary tenant administrator.
Machine identity
An API key, schedule, worker, subscriber, integration credential, or AI tool context with explicit scope.
Physical boundary
Separation of process, database, schema, network, region, cache, queue, object store, logs, or backups.
Cryptographic boundary
Keys, key hierarchy, mapped fields, rotation, recovery, and operator access; complementary to authorization.
Legal or residency boundary
Controller and processor duties, lawful basis, contracts, retention, geography, and transfers across every store.
Architecture prose sometimes uses tenant as deployment shorthand. Current entities support multiple Tenant records in one application and database. This guide therefore says logical tenant for the row and scope contract, and deployment for physical topology.
Boundary map
| Layer | Current evidence | Remaining decision or gap | Scope key | Owner |
|---|---|---|---|---|
| Application and process | Current source can carry logical tenant context. | Topology and process separation are deployment choices. | Named tenant, organization, identity, or deployment boundary | Platform owner |
| Database and schema | Standard entities use tenant and organization fields. | No reviewed invariant creates one database or schema per tenant. | Named tenant, organization, identity, or deployment boundary | Data architect |
| Logical tenant | Tenant records exist with lifecycle and soft deletion. | A record does not define a legal or physical boundary. | Named tenant, organization, identity, or deployment boundary | Product owner |
| Organization tree | Tenant-owned hierarchy stores ancestors and descendants. | Business meaning, delegation, reporting, and ownership remain policy. | Named tenant, organization, identity, or deployment boundary | Business owner |
| User and session | Authenticated identity carries tenant and home organization. | Cookie or selected scope is not authorization. | Named tenant, organization, identity, or deployment boundary | Identity owner |
| Role and ACL | Per-user overrides, role aggregation, feature grants, organization sets, and super-admin exist. | Wildcard and unrestricted grants need governance and negative tests. | Named tenant, organization, identity, or deployment boundary | Access owner |
| API key | Keys carry tenant, optional organization, roles, expiry, and encrypted session material. | Rotation, revocation, ownership, and external custody remain operational. | Named tenant, organization, identity, or deployment boundary | Integration owner |
| Field-encryption key | Tenant DEKs and mapped-field encryption helpers exist; encryption defaults on unless disabled. | KMS availability, map coverage, migration, rotation, and recovery require proof. | Named tenant, organization, identity, or deployment boundary | Security owner |
| Cache | Tenant context prefixes keys and tags; cross-request org-scope cache is opt-in. | Context propagation, invalidation, process, and strategy behavior need tests. | Named tenant, organization, identity, or deployment boundary | Platform owner |
| Query index and search | Records and operations carry tenant and optional organization scope. | Drivers, reindex, purge, enrichment, and source-row fetch must remain scoped. | Named tenant, organization, identity, or deployment boundary | Search owner |
| Event and queue | Trusted event options carry scope to subscribers. | Every subscriber and worker must use that context correctly. | Named tenant, organization, identity, or deployment boundary | Integration owner |
| Scheduler | System, tenant, and organization schedule scopes have distinct invariants. | Tenant-wide jobs need explicit row policy and command authorization. | Named tenant, organization, identity, or deployment boundary | Operations owner |
| Object and file storage | Attachments may preserve application scope metadata. | Buckets, object keys, signed URLs, deletion, and backups are project-specific. | Named tenant, organization, identity, or deployment boundary | Storage owner |
| Logs and audit | Application events can record actor and scope context. | Collection, redaction, tenant routing, access, and retention are operational choices. | Named tenant, organization, identity, or deployment boundary | Security operations |
| Backups and replicas | No row-scoping mechanism alone separates recovery media. | Restore, deletion, geography, and administrator access require deployment evidence. | Named tenant, organization, identity, or deployment boundary | Recovery owner |
| Integration and provider | Webhooks, APIs, exports, and providers can receive scoped payloads. | External account, routing, retention, reconciliation, and deletion remain contractual and technical. | Named tenant, organization, identity, or deployment boundary | Integration owner |
| Region | Application configuration can select infrastructure locations. | Logical tenant identifiers do not prove residency or transfer controls. | Named tenant, organization, identity, or deployment boundary | Hosting owner |
| Legal controller | Product scope can support a chosen operating model. | Controller, processor, lawful basis, contracts, and duties are not inferred from code. | Named tenant, organization, identity, or deployment boundary | Privacy owner |
Selection is not authorization
selectedId
The effective current view. It can narrow the allowed set and may expand to authorized descendants.
filterIds
The organization ids applied to the current query or view.
allowedIds
The authorization set from ACL rules, potentially expanded by hierarchy. Selection cannot widen it.
null / [] / __all__
Null may mean unrestricted in a specific contract; an empty restricted set means no organizations; explicit all and __all__ are handled only in their defined paths. Never infer one universal meaning.
Cross-request organization-scope caching remains off by default unless OM_ORG_SCOPE_CACHE_TTL_MS opts in; request memoization remains. Enabling it adds stale-authorization and invalidation acceptance work.
Choose a tenancy pattern without a score
One tenant, one organization
Use when: A bounded application with no required hierarchy.
Shared resources and blast radius: Shared application resources; simple authorization model.
Acceptance evidence: Negative isolation tests, owner approval, recovery exercise, and documented blast radius.
Stop: Stop if legal or residency rules require stronger separation.
One tenant, many organizations
Use when: Divisions or locations share a tenant and need hierarchy-aware views.
Shared resources and blast radius: Shared tenant resources; descendant expansion and global-row policy matter.
Acceptance evidence: Negative isolation tests, owner approval, recovery exercise, and documented blast radius.
Stop: Stop until parent visibility, delegation, and reporting semantics are accepted.
Many logical tenants, shared deployment
Use when: Unrelated customers share application infrastructure but require logical separation.
Shared resources and blast radius: Shared process, database, caches, queues, logs, backups, and operators unless separately designed.
Acceptance evidence: Negative isolation tests, owner approval, recovery exercise, and documented blast radius.
Stop: Stop if shared blast radius or privileged operations are prohibited.
Separate deployment per boundary
Use when: A customer, legal, regional, or risk boundary requires physical separation.
Shared resources and blast radius: Higher operating cost and duplicated infrastructure; cross-deployment reporting becomes integration work.
Acceptance evidence: Negative isolation tests, owner approval, recovery exercise, and documented blast radius.
Stop: Stop until provisioning, updates, observability, recovery, and aggregation ownership are funded.
Hybrid model
Use when: Most scopes share infrastructure while selected boundaries receive separate deployments.
Shared resources and blast radius: Two operating models and explicit data-movement contracts.
Acceptance evidence: Negative isolation tests, owner approval, recovery exercise, and documented blast radius.
Stop: Stop until placement rules and exceptions are deterministic.
Human, privileged, machine, and support identities
Ordinary user
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Tenant administrator
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Super-admin / break glass
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Break-glass class: named owner, strong authentication, least population, restricted cases, action and session evidence, alerts, periodic review, tested revocation, and incident handling.
API key
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Scheduled actor
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Event or queue worker
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Integration or AI credential
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Support operator
Authenticate; bind tenant and organization scope; grant least roles; log use; review; revoke; exercise incident response.
Break-glass class: named owner, strong authentication, least population, restricted cases, action and session evidence, alerts, periodic review, tested revocation, and incident handling.
Isolation-control matrix
CRUD defaults can inject tenant and organization filters and short-circuit an empty allowed set. orgField or tenantField opt-outs, custom filters, direct ORM, and custom routes remain explicit escape hatches. withScopedPayload can reject a tenant mismatch, but the caller can choose whether organization is required. Command scope can log and continue without resolved organization scope unless strict enforcement is enabled, so no universal fail-closed command claim is justified.
| Path | Scope source | Enforcement | Bypass or unresolved risk | Negative test | Owner |
|---|---|---|---|---|---|
| UI selection | Selected view plus server-resolved allowed set | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization ui selection operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| Server session | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization server session operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| CRUD list | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization crud list operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| Item read | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization item read operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| Create, update, delete | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization create, update, delete operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| Direct ORM query | Trusted actor, tenant, organization, and path-specific policy | Explicit filters in custom code | Missing filter or exceptional direct access | Attempt a cross-tenant and cross-organization direct orm query operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| Custom command | Trusted actor, tenant, organization, and path-specific policy | Tenant and organization command guards; strict unscoped enforcement is configurable | Scope-less compatibility path unless strict mode denies | Attempt a cross-tenant and cross-organization custom command operation; require denial or the documented bounded result and no derived side effects. | Application owner |
| Custom fields | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization custom fields operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Export and report | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization export and report operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Attachment and file | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization attachment and file operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Audit and logging | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization audit and logging operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Cache | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization cache operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Query index | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization query index operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Full-text or vector search | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization full-text or vector search operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Event | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization event operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Queue worker | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization queue worker operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Schedule | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization schedule operation; require denial or the documented bounded result and no derived side effects. | Platform owner |
| Webhook and integration | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization webhook and integration operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
| API key | Key tenant, optional organization, and roles | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization api key operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
| AI tool | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization ai tool operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
| Analytics | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization analytics operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
| Backup and replica | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization backup and replica operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
| Support access | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization support access operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
| Local download | Trusted actor, tenant, organization, and path-specific policy | Path-specific server guard, filter, context, or provider contract | Privileged identity, null/global policy, opt-out, stale cache, or external store | Attempt a cross-tenant and cross-organization local download operation; require denial or the documented bounded result and no derived side effects. | Service and integration owner |
Where scope can be lost
Trace file and object storage, logs, audit, backups, replicas, analytics, warehouses, email, full-text and vector stores, model providers, webhooks, exports, support tools, and local downloads. For each, record scope fields, authorization, routing, retention, deletion, reconciliation, incident evidence, contract owner, and stronger-boundary trigger.
Hosting owns topology and region decisions; security owns broad assurance. This guide retains the scope-tracing method: residency is not established until every copy, processor, transfer, operator, recovery path, and deletion route is evidenced.
Negative-test and acceptance pack
Cross-tenant list and item read
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- ordinary user
- Attempt
- request another tenant label
- Expected
- deny and return no rows
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Cross-organization update and delete
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- ordinary user
- Attempt
- target an unauthorized sibling organization
- Expected
- deny with no write or event
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Empty allowed set
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- restricted user
- Attempt
- list scoped records
- Expected
- return an empty bounded result
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Invalid selected cookie
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- ordinary user
- Attempt
- select an unauthorized organization
- Expected
- clamp or deny without widening access
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Parent and descendant view
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- authorized parent user
- Attempt
- select a parent organization
- Expected
- include only authorized descendants
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Ancestor navigation
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- restricted child user
- Attempt
- select a visible but non-selectable ancestor
- Expected
- deny selection
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Null-organization row
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- restricted user
- Attempt
- read a tenant-wide row
- Expected
- apply the explicit global-row policy
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Inactive organization
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- ordinary user
- Attempt
- read or write inactive scope
- Expected
- deny or follow documented lifecycle policy
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Soft-deleted tenant or organization
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- ordinary user
- Attempt
- address deleted scope
- Expected
- exclude it and create no derived data
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Hierarchy reparent
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- organization manager
- Attempt
- move a branch
- Expected
- rebuild hierarchy atomically and refresh authorization
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Hierarchy cycle
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- organization manager
- Attempt
- make a node its descendant
- Expected
- reject with no partial rebuild
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Undo and redo hierarchy
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- organization manager
- Attempt
- undo and redo a valid move
- Expected
- restore consistent hierarchy and scope
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Direct ORM omission
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- custom module actor
- Attempt
- query without tenant or organization filter
- Expected
- test must detect leakage and block promotion
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Custom command mismatch
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- ordinary user
- Attempt
- send another tenant or organization target
- Expected
- deny and record bounded evidence
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Unscoped command compatibility
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- worker actor
- Attempt
- call an organization command without resolved scope
- Expected
- warn by default or deny when strict mode is enabled
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Payload-spoofed event scope
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- publisher
- Attempt
- put false tenant data in payload
- Expected
- subscriber receives trusted option scope
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Subscriber ignores context
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- event worker
- Attempt
- load data without received filters
- Expected
- negative test detects and blocks the path
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Tenant-wide schedule
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- scheduled actor
- Attempt
- run an organization-bound command
- Expected
- require explicit tenant-wide row policy
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Organization schedule
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- scheduled actor
- Attempt
- run in one organization
- Expected
- use only the scheduled organization scope
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Cache collision and invalidation
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- two scoped actors
- Attempt
- read identical keys across scopes and change ACL
- Expected
- separate keys and invalidate stale authorization
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Query-index mismatch
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- index worker
- Attempt
- publish payload scope different from source row
- Expected
- reject the mismatch
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
All-tenant reindex
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- operator
- Attempt
- omit tenant without explicit opt-in
- Expected
- reject the operation
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Search purge and enrichment
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- search operator
- Attempt
- purge one organization then enrich results
- Expected
- affect and fetch only allowed scope
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Export and attachment URL
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- restricted user
- Attempt
- export or sign another scope
- Expected
- deny and create no file, link, or audit side effect
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
API key compromise
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- machine identity
- Attempt
- use expired or revoked key across scope
- Expected
- deny, alert, and preserve revocation evidence
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Super-admin misuse
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- break-glass actor
- Attempt
- widen scope outside approved case
- Expected
- alert, record action, revoke session, and review incident
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
KMS outage and map change
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- encryption service
- Attempt
- write mapped data or add a mapped field
- Expected
- follow explicit fail policy and migrate historical rows before acceptance
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Backup restore and deletion
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- recovery operator
- Attempt
- restore or delete one boundary
- Expected
- prove scope, retention, and no unintended tenant disclosure
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
External provider and AI tool
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- integration identity
- Attempt
- send or retrieve scoped data
- Expected
- route, retain, reconcile, and delete under an approved contract
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Release-upgrade regression
- Setup
- Create only synthetic labels for two unrelated tenants and authorized/unauthorized organizations; capture the intended policy first.
- Actor
- release owner
- Attempt
- promote a new framework revision
- Expected
- rerun route, custom-code, worker, cache, index, key, and negative-test inventory
- Prohibited side effects
- No unauthorized write, event, cache entry, index document, file, export, provider call, or log payload.
- Evidence
- Request/result trace, denial or bounded-result assertion, derived-store inspection, and owner sign-off.
- Cleanup
- Remove synthetic records, revoke temporary access, clear derived artifacts, and retain only the approved evidence reference.
- Owner
- Named control owner and independent reviewer
Three synthetic boundary examples
Synthetic example 1
Example North: one logical tenant with three regional organizations. Parent reporting is allowed only for two descendants; the third remains outside the role grant. A hierarchy test and cache invalidation are required before acceptance.
Evidence: policy record, negative tests, access review, recovery observation, and named owner.
Synthetic example 2
Example Cedar: two unrelated customers share one deployment as separate logical tenants. Process, database, queue, logs, backups, and super-admin remain shared, so the design stops if either customer prohibits shared infrastructure.
Evidence: policy record, negative tests, access review, recovery observation, and named owner.
Synthetic example 3
Example Harbor: regulated records use a separate regional deployment while lower-risk operations use shared logical tenancy. Data movement needs an explicit integration contract, reconciliation, deletion, and dual operating ownership.
Evidence: policy record, negative tests, access review, recovery observation, and named owner.
Local planning tool
Tenant boundary register
Record safe structural labels only. The register organizes decisions and evidence references; it does not score isolation, certify compliance, or approve readiness.
Do not enter real data: Do not enter tenant or organization ids, personal data, customer names, secrets, credentials, real architecture details, provider account numbers, incident details, or production evidence.
Privacy: this page does not submit worksheet content, place it in the URL, or store it in cookies.
Stop or defer when a load-bearing boundary is unresolved
- Stop: tenant definition is unresolved.
- Stop: shared infrastructure is prohibited.
- Stop: residency conflicts with topology.
- Stop: super-admin ownership or monitoring is missing.
- Stop: a custom query lacks scope.
- Stop: negative tests are missing.
- Stop: an export can widen scope.
- Stop: authorization cache can become stale.
- Stop: search or index scope is unverified.
- Stop: key recovery is unproved.
- Stop: an external provider boundary is unknown.
- Stop: no accountable owner is named.
Manager FAQ
Tenant or organization?
Use a logical tenant as the primary partition contract and organizations for tenant-owned hierarchy only when that model matches the business boundary.
Tenant or deployment?
They are distinct: current source can hold multiple logical tenants in one deployment.
One database or separate database?
That is a physical architecture decision. Tenant fields do not create a separate database.
Can a parent see children?
Only when authorization and descendant expansion allow it; navigation visibility is not selection authority.
What means all organizations?
Null, empty, explicit all, and __all__ are context-specific. Test the exact contract.
What is super-admin?
A privileged bypass class that needs break-glass governance, monitoring, review, revocation, and incident evidence.
Are API keys scoped?
They can carry tenant, optional organization, roles, and expiry, but their ACL and lifecycle need separate testing.
Does encryption isolate tenants?
Mapped-field encryption is a complementary control; it is not row authorization, a separate database, or residency.
Does self-hosting prove residency?
No. Every store, backup, provider, support path, and transfer still needs evidence.
Do background jobs keep scope?
Only when schedule, event, queue, worker, command, and query paths preserve and enforce it.
Are custom routes safe automatically?
No. CRUD helpers reduce risk, while opt-outs and direct ORM remain explicit escape hatches.
Can reporting cross organizations?
Only under an approved authorization and aggregation policy with bounded source and result fetches.
Do backups preserve deletion?
Backup retention and restoration are deployment controls and need their own deletion evidence.
What proof is required?
Negative tests across primary, derived, background, external, privileged, lifecycle, and recovery paths.
When choose a stronger boundary?
When shared blast radius, legal, residency, contractual, key-custody, or operator-access constraints cannot be accepted.
Evidence and limitations
Reviewed against the exact revision above, current directory, authorization, scoped CRUD and command helpers, cache, events, scheduler, query-index, search, API-key, and encryption sources. The relevant source set contains 234 changed paths after v0.6.5, so current-source observations are dated and kept separate from the public release baseline.
This is not an isolation audit, security assurance, legal opinion, residency promise, provider recommendation, or production approval. Re-test the exact application, custom modules, infrastructure, external systems, operators, and recovery paths.
Method, assumptions and limitations
Reviewed 14 July 2026. Product facts were checked against both the public code at the cited repository revision and official documentation. Where documentation and code differ, this guide describes behavior supported by code. Interpretations and recommendations concern implementation work, not product guarantees.
This material is not a quote, audit, certification, or legal, tax, or accounting advice. Edition, enabled modules, configuration, custom code, infrastructure, data, third-party providers, and operating practices affect the outcome.
Primary source collections: code repository, documentation, public releases.