ADR-0025: OSHUN Studio Authentication Architecture

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 governance workflows now include high-impact operations (release promotions, policy changes, rollback actions, cross-project orchestration) and require stronger authentication guarantees than generic shell browsing flows.

Without a Studio-specific authentication architecture, OSHUN risks:

• unauthorized access to privileged operational surfaces
• weak assurance for critical approvals and destructive actions
• inconsistent identity/session behavior across Studio domains
• poor auditability of authentication decisions in incidents and compliance

Decision Drivers#

• Security assurance: strong authentication for privileged Studio actions.
• Consistency: one Studio auth model across web/BFF/domain surfaces.
• Operational safety: deterministic auth outcomes during critical workflows.
• Compliance: complete auditability of auth grants/denials/challenges.
• Interoperability: align with shared OSHUN identity/session model.

Considered Options#

Option 1: Reuse Generic Shell Auth Without Studio Hardening#

Use baseline shell auth behavior unchanged for Studio operations.

Pros:

• Low immediate effort.

Cons:

• Insufficient assurance for privileged workflows.
• Inconsistent challenge policies for critical actions.

Option 2: Domain-Specific Studio Authentication Policies#

Each domain implements its own Studio auth requirements.

Pros:

• Domain autonomy.

Cons:

• Policy drift and fragmented user experience.
• Harder centralized governance and auditing.

Option 3: Unified Studio Authentication Architecture with Risk-Based Challenge Controls (Chosen)#

Adopt one Studio authentication contract layered on shared OSHUN identity, including risk-based step-up challenges and explicit privileged-action policies.

Pros:

• Consistent strong assurance across Studio workflows.
• Better operational safety and auditing.
• Easier policy governance and incident response.

Cons:

• Additional policy/risk orchestration complexity.

Decision Outcome#

Chosen option: Option 3.

Studio authentication architecture requirements:

1. Studio auth context contract with identity/session/entitlement claims.
2. Risk-based challenge contract for step-up auth on sensitive actions.
3. Privileged action policy contract with deterministic allow/deny outcomes.
4. Compatibility contract for token/session schema and policy versions.
5. Release governance with validation, approval, telemetry/audit, and rollback controls.

Normative Rules#

StudioAuthContext Contract#

• Every Studio request must include authenticated user/session context.
• Context must include user identity, session id, role/entitlement scope, and auth assurance level.
• Missing or stale context is treated as unauthenticated for privileged flows.

Risk-Based Challenge Contract#

• Sensitive actions require step-up challenge when risk policy demands it.
• Challenge outcomes must be explicit (passed, failed, expired).
• Failed/expired challenges must deny privileged action commit.

Privileged Action Policy Contract#

• Privileged actions must evaluate role + entitlement + assurance level.
• Policy decisions must be deterministic and auditable.
• Denied actions must not mutate Studio governance state.

Compatibility Contract#

• Auth token/session schema changes require compatibility checks and versioning.
• Breaking changes require migration guidance and rollback references.

Release Validity Contract#

A Studio authentication release is valid only when all are true:

• auth context validation checks pass
• step-up challenge workflows pass deterministic validation
• privileged policy decisions pass allow/deny correctness checks
• telemetry/audit records are complete
• rollback strategy is documented

Architecture Implications#

• Studio surfaces consume one shared Studio auth contract over base OSHUN identity/session architecture.
• BFF enforces authoritative privileged policy checks.
• Navigation and context handoff preserve auth assurance metadata.
• Analytics pipelines capture auth challenge and policy outcomes for operations.

Acceptance Criteria (OST-00097)#

OST-00097 is complete only when:

1. ADR exists at docs/adr/ADR-0031-oshun-studio-authentication-architecture.md.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines Studio auth context, risk-based challenge, privileged-action policy, compatibility, and release-validity contracts.
4. ADR aligns with ADR-0007 through ADR-0024 and 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 protection for privileged Studio operations.
• More consistent and predictable auth behavior across Studio surfaces.
• Improved audit/compliance readiness for operational decisions.

Negative#

• Higher policy/risk orchestration complexity.
• Requires strict governance of assurance-level changes.

Related Decisions#

• 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-0030-oshun-studio-multi-project-operations.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