# OSHUN Studio Session and Device Management Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + Platform Identity + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0026-oshun-studio-session-and-device-management.md`

## Purpose

Define dependencies and canonical contracts for Studio session and device
management across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0025-oshun-studio-authentication-architecture.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

- **Session inventory UI and controls**: Studio session/device management
  surfaces (`apps/oshun/web/src/components/studio`).
- **Identity/session authority**: `libs/oshun/auth` + identity services.
- **Trust and challenge orchestration**: security policy engine + challenge
  providers.
- **Session revocation propagation**: BFF orchestration + domain adapters.
- **Telemetry and audit**: `libs/oshun/analytics` + security/data pipelines.

### 1.2 Domain Dependency Graph

- `Session & Device Management -> Yemaya`: creator workflows depend on safe
  multi-device session continuity and targeted session revocation.
- `Session & Device Management -> Isis`: model/review operations require
  trusted-device enforcement for privileged actions.
- `Session & Device Management -> Hathor`: narrative governance requires visible
  active sessions and auditable sign-out events.
- `Session & Device Management -> Aja`: media/timeline approvals require
  assurance-aware trusted-device policies.
- `Session & Device Management -> Bellona`: release/runtime controls require
  deterministic revoke-all and forced re-auth support.
- `Project Obsidian -> all`: central governance for session trust policies,
  revocation controls, and incident ownership.

## 2. Ownership and Contract Matrix

| Area                                | Owner                    | Consumers                   | Artifact             | Contract                        |
| ----------------------------------- | ------------------------ | --------------------------- | -------------------- | ------------------------------- |
| Studio session inventory            | Platform Identity        | Web + BFF + Studio surfaces | Session list payload | `StudioSessionInventory`        |
| Device trust profile                | Security + Identity      | Privileged Studio workflows | Device trust payload | `StudioDeviceTrustProfile`      |
| Session control operations          | Platform Identity + BFF  | Studio governance actions   | Session control API  | `StudioSessionControlRequest`   |
| Revocation propagation and outcomes | BFF + Domain Integrators | Domain adapters + SRE       | Revocation result    | `StudioSessionRevocationResult` |
| Audit and compliance evidence       | Data Platform + Security | Governance + Compliance     | Event stream         | `StudioSessionDeviceAuditEvent` |

## 3. Canonical Contracts

### 3.1 StudioSessionInventory

```ts
export interface StudioSessionInventory {
  userId: string;
  sessions: Array<{
    sessionId: string;
    deviceId: string;
    platform: 'web' | 'ios' | 'android' | 'server';
    ipRegion: string;
    assuranceLevel: 'standard' | 'elevated';
    trustedDevice: boolean;
    lastSeenAt: string;
    status: 'active' | 'stale' | 'revoked';
  }>;
  collectedAt: string;
}
```

### 3.2 StudioDeviceTrustProfile

```ts
export interface StudioDeviceTrustProfile {
  deviceId: string;
  userId: string;
  trustState: 'unverified' | 'trusted' | 'expired' | 'revoked';
  attestationLevel: 'none' | 'basic' | 'strong';
  challengeMethod?: 'totp' | 'webauthn' | 'biometric';
  trustEstablishedAt?: string;
  trustExpiresAt?: string;
}
```

### 3.3 StudioSessionControlRequest

```ts
export interface StudioSessionControlRequest {
  requestId: string;
  actorId: string;
  action: 'revoke_session' | 'revoke_device_sessions' | 'revoke_all_sessions';
  targetSessionId?: string;
  targetDeviceId?: string;
  reason: string;
  requestedAt: string;
}
```

### 3.4 StudioSessionRevocationResult

```ts
export interface StudioSessionRevocationResult {
  requestId: string;
  outcome: 'success' | 'partial' | 'error' | 'denied';
  revokedSessionIds: string[];
  skippedSessionIds?: string[];
  propagatedDomains: Array<'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona'>;
  completedAt: string;
  errorCode?: string;
}
```

### 3.5 StudioSessionDeviceAuditEvent

```ts
export interface StudioSessionDeviceAuditEvent {
  eventId: string;
  action:
    | 'session.inventory.requested'
    | 'session.device.trust.updated'
    | 'session.control.requested'
    | 'session.control.revoked'
    | 'session.control.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  userId: string;
  actorId: string;
  sessionId?: string;
  deviceId?: string;
  role: string;
  assuranceLevel: 'standard' | 'elevated';
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Privileged Studio actions are blocked when session or device trust state is
  stale, expired, or revoked.
- Revoke-all and device-scoped revocations must propagate across all enabled
  Studio domains.
- Trust state transitions must be explicit and challenge-gated.
- All inventory/trust/revocation outcomes must emit
  `StudioSessionDeviceAuditEvent` records.

## 5. Acceptance Criteria (OST-00106)

`OST-00106` 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 session inventory, device trust profile, session control,
   revocation result, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
