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.
Short answer
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.
This editorial guide supports evaluation. Product owners, hosts, security assessors, compliance authorities, KMS providers and implementation suppliers remain responsible for their decisions.
Eleven boundaries to keep separate
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. A logical Tenant record does not create a separate database, region, legal entity or key-root boundary.
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 only narrows authorized data and grants no wider access.
Tenant-wide or global row
A deliberately organization-null row or a distinct scope contract. Null requires an explicit policy and must never serve as a bypass.
Super-admin
A privileged identity able to bypass ordinary checks in specified paths. Keep it separate from 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. | The deployment sets restore, deletion, geography, and administrator-access controls. | 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 and authorization are separate controls
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 completes payload fields and checks required presence; parseScopedCommandInput adds the tenant-mismatch rejection for non-superadmins. Neither helper checks organization authorization. Command scope can log and continue without resolved organization scope unless strict enforcement is enabled. Reviewed evidence does not justify a universal fail-closed claim.
| 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. Establish residency only after documenting every copy, processor, transfer, operator, recovery path, and deletion route.
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 role grant excludes the third. 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 provide an isolation score, compliance certification or readiness approval.
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: The page does not send worksheet content, put 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 affects presentation; authorization controls selection.
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. Test their ACL and lifecycle.
Does encryption isolate tenants?
Mapped-field encryption complements row authorization. It does not create separate databases or prove residency.
Does self-hosting prove residency?
No. Residency requires evidence for every store, backup, provider, support path, and transfer.
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. 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?
Deployment controls determine backup retention and restoration. Test deletion behavior.
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.
Reviewed evidence does not provide 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.