# 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`