# OSHUN Studio Authentication Architecture Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Security + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0025-oshun-studio-authentication-architecture.md`

## Purpose

Define dependencies and canonical contracts for Studio authentication
architecture across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for `OST-00098`.

## Sources Used

- `docs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.md`
- `libs/oshun/auth/src/index.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `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`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Identity/session primitives**: `libs/oshun/auth`.
- **Studio auth enforcement surfaces**: Studio web routes and BFF middleware.
- **Entitlement and domain scope metadata**: `libs/oshun/domain-registry` +
  policy services.
- **Risk/challenge orchestration**: auth challenge services and session risk
  signals.
- **Telemetry and audit**: `libs/oshun/analytics` + security pipelines.

### 1.2 Domain Dependency Graph

- `Authentication Architecture -> Yemaya`: privileged content and pipeline
  actions require high-assurance auth decisions.
- `Authentication Architecture -> Isis`: model/workflow governance actions
  require deterministic challenge policies.
- `Authentication Architecture -> Hathor`: world/lore publication requires
  auditable privileged auth outcomes.
- `Authentication Architecture -> Aja`: media timeline approvals require
  policy-consistent assurance levels.
- `Authentication Architecture -> Bellona`: build/release controls require
  strict privileged auth gating.
- `Project Obsidian -> all`: central governance for challenge policy, privileged
  action rules, and audit obligations.

## 2. Ownership and Contract Matrix

| Area                               | Owner                         | Consumers                   | Artifact             | Contract                         |
| ---------------------------------- | ----------------------------- | --------------------------- | -------------------- | -------------------------------- |
| Studio auth context                | Security + Platform Identity  | Web + BFF + Studio surfaces | Auth context payload | `StudioAuthContext`              |
| Risk-based challenge orchestration | Security Engineering          | Privileged workflows        | Challenge payload    | `StudioAuthChallengeRequest`     |
| Privileged policy decisions        | Security + Program Governance | Studio governance actions   | Decision payload     | `StudioPrivilegedPolicyDecision` |
| Session risk signals               | Identity Platform             | Security + SRE              | Risk profile         | `StudioSessionRiskSignal`        |
| Audit/compliance evidence          | Data Platform + Security      | Governance + Compliance     | Event stream         | `StudioAuthAuditEvent`           |

## 3. Canonical Contracts

### 3.1 StudioAuthContext

```ts
export interface StudioAuthContext {
  userId: string;
  sessionId: string;
  role: string;
  entitlements: string[];
  assuranceLevel: 'standard' | 'elevated';
  issuedAt: string;
  expiresAt: string;
}
```

### 3.2 StudioAuthChallengeRequest

```ts
export interface StudioAuthChallengeRequest {
  challengeId: string;
  action: string;
  userId: string;
  sessionId: string;
  requiredAssuranceLevel: 'standard' | 'elevated';
  reason: 'privileged_action' | 'risk_signal' | 'policy_requirement';
  requestedAt: string;
}
```

### 3.3 StudioPrivilegedPolicyDecision

```ts
export interface StudioPrivilegedPolicyDecision {
  decisionId: string;
  action: string;
  userId: string;
  role: string;
  entitlements: string[];
  assuranceLevel: 'standard' | 'elevated';
  outcome: 'allowed' | 'denied';
  reason?: string;
  decidedAt: string;
}
```

### 3.4 StudioSessionRiskSignal

```ts
export interface StudioSessionRiskSignal {
  signalId: string;
  userId: string;
  sessionId: string;
  riskLevel: 'low' | 'medium' | 'high';
  indicators: string[];
  challengeRequired: boolean;
  observedAt: string;
}
```

### 3.5 StudioAuthAuditEvent

```ts
export interface StudioAuthAuditEvent {
  eventId: string;
  action:
    | 'studio_auth.requested'
    | 'studio_auth.challenge.prompted'
    | 'studio_auth.challenge.completed'
    | 'studio_auth.policy.allowed'
    | 'studio_auth.policy.denied'
    | 'studio_auth.session.revoked';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  userId: string;
  sessionId: string;
  role: string;
  assuranceLevel: 'standard' | 'elevated';
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Privileged Studio actions are blocked unless auth context is complete and
  session is valid.
- Step-up challenge workflows must pass before elevated assurance actions are
  committed.
- Policy-denied outcomes must not mutate Studio governance state.
- All challenge/policy/deny/revocation outcomes must emit `StudioAuthAuditEvent`
  records.

## 5. Acceptance Criteria (OST-00098)

`OST-00098` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for auth context, challenge request, policy decision, session-risk
   signal, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
