Disciplines · Decisions (ADRs)

ADR-0028: OSHUN Studio Enterprise Tenant Isolation

Studio is expanding into enterprise operating models where multiple tenant organizations run isolated governance workflows on shared platform infrastructure.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Security, OSHUN Web + BFF Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio is expanding into enterprise operating models where multiple tenant organizations run isolated governance workflows on shared platform infrastructure. Current Studio patterns assume shared program context and need explicit tenant-boundary contracts for policy, data, and action safety.

Without first-class tenant isolation architecture, OSHUN risks:

  • cross-tenant data visibility or mutation leaks
  • inconsistent policy enforcement at tenant boundaries
  • weak auditability of tenant-scoped actions and decisions
  • operational incidents with broad blast radius across organizations

Decision Drivers#

  • Security boundaries: strict tenant-level data and action isolation.
  • Operational safety: deterministic tenant-scoped policy outcomes.
  • Compliance readiness: auditable tenant lineage and access evidence.
  • Scalability: support enterprise tenancy without workflow regression.
  • Interoperability: preserve consistent behavior across all Studio domains.

Considered Options#

Option 1: Logical Segmentation Only in UI#

Represent tenants in UI but rely on shared backend data access paths.

Pros:

  • Lower immediate implementation effort.

Cons:

  • Insufficient isolation guarantees.
  • Higher risk of cross-tenant leakage.

Option 2: Per-Domain Tenant Isolation Implementations#

Each Studio domain owns separate tenant isolation logic.

Pros:

  • Domain-level flexibility.

Cons:

  • Policy drift and inconsistent enforcement.
  • Harder centralized governance and auditing.

Option 3: Unified Enterprise Tenant Isolation Contract Model (Chosen)#

Adopt one tenant-boundary contract model across Studio surfaces and services, with explicit tenant-scoped identity, policy, data, and observability controls.

Pros:

  • Consistent and strong tenant isolation semantics.
  • Better governance, incident containment, and compliance evidence.
  • Reduced cross-domain policy drift.

Cons:

  • Higher contract-management complexity and migration overhead.

Decision Outcome#

Chosen option: Option 3.

Enterprise tenant isolation requirements:

  1. Tenant context contract with immutable tenant identity and scope.
  2. Tenant policy contract for allow/deny behavior on tenant-scoped actions.
  3. Tenant data-boundary contract for read/write partition enforcement.
  4. Compatibility contract for tenant schema/policy version evolution.
  5. Release governance with validation, approval, telemetry/audit, and rollback controls.

Normative Rules#

Tenant Context Contract#

  • Every governed Studio request must include tenant identity and scope metadata.
  • Tenant context must remain immutable during single action execution.
  • Missing or invalid tenant context defaults to deny for privileged actions.

Tenant Policy Contract#

  • Tenant-scoped actions must evaluate role + entitlement + tenant policy.
  • Denied outcomes must not mutate tenant or shared governance state.
  • Cross-tenant requests must be blocked unless explicitly authorized.

Tenant Data-Boundary Contract#

  • Read/write paths must resolve within tenant partitions only.
  • Cross-tenant joins are prohibited unless explicitly approved and audited.
  • Tenant boundary violations must trigger hard fail and incident signal.

Compatibility Contract#

  • Tenant schema and policy changes require compatibility checks.
  • Breaking changes require migration guidance and rollback references.
  • Tenant identifiers and lineage fields must remain backward compatible.

Release Validity Contract#

A tenant-isolation release is valid only when all are true:

  • tenant context validation checks pass
  • tenant policy allow/deny checks pass
  • tenant data-boundary enforcement checks pass
  • telemetry/audit records are complete
  • rollback strategy is documented

Architecture Implications#

  • Studio web surfaces expose explicit tenant context and boundary diagnostics.
  • BFF and downstream services enforce authoritative tenant partition controls.
  • Shared identity/policy services become tenant-scoped dependencies.
  • Analytics and audit pipelines track tenant-scoped policy and boundary events.

Acceptance Criteria (OST-00121)#

OST-00121 is complete only when:

  1. ADR exists at docs/adr/ADR-0034-oshun-studio-enterprise-tenant-isolation.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines tenant context, tenant policy, tenant data-boundary, compatibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0027, especially ADR-0010.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, libs/oshun/auth, and libs/oshun/domain-registry.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Stronger tenant isolation and reduced cross-tenant blast radius.
  • Better policy consistency and operational clarity for enterprise workflows.
  • Improved compliance/audit readiness for tenant-governed operations.

Negative#

  • Increased tenancy contract complexity and migration overhead.
  • Requires stricter enforcement and validation discipline across services.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0019-oshun-studio-information-architecture.md
  • docs/adr/ADR-0032-oshun-studio-session-and-device-management.md
  • docs/adr/ADR-0033-oshun-studio-rbac-and-permission-policy-ux.md

References#

  • libs/oshun/auth/src/index.ts
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/design/ux-principles.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md