# ADR-0026: OSHUN Studio Session and Device Management

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

## Context and Problem Statement

Studio operators use multiple devices and long-lived workflows while executing
critical actions (approvals, promotions, rollback decisions, and incident
response). Current session controls are shell-oriented and do not fully model
Studio-specific device trust, session visibility, and revocation requirements.

Without a governed Studio session/device model, OSHUN risks:

- weak visibility into active Studio sessions across devices
- inconsistent session revocation and forced sign-out behavior
- unmanaged trusted-device lifecycle for privileged operations
- incomplete auditing for session and device governance actions

## Decision Drivers

- **Operational control**: deterministic session/device governance for Studio.
- **Security assurance**: strict trust and revocation semantics for privileged
  work.
- **Usability**: clear UX for session inventory, trust state, and recovery
  actions.
- **Auditability**: complete evidence for sign-in, trust, and revocation
  decisions.
- **Interoperability**: one model that spans Yemaya, Isis, Hathor, Aja, Bellona,
  and Project Obsidian.

## Considered Options

### Option 1: Reuse Generic Shell Session Controls

Use baseline shell session management without Studio-specific device contracts.

**Pros**:

- Low implementation effort.

**Cons**:

- Insufficient session/device governance for privileged Studio workflows.
- Weak consistency for cross-domain operational actions.

### Option 2: Per-Domain Session and Device Policies

Allow each Studio domain to implement session/device behavior independently.

**Pros**:

- Domain-level customization flexibility.

**Cons**:

- Policy drift and fragmented operator experience.
- Harder cross-domain audits and incident response.

### Option 3: Unified Studio Session and Device Governance Contract (Chosen)

Adopt a unified session inventory, trusted-device lifecycle, and revocation
architecture with deterministic UX and auditable outcomes.

**Pros**:

- Consistent security and operational semantics across Studio surfaces.
- Better revocation safety and incident containment.
- Stronger compliance evidence for session/device actions.

**Cons**:

- Additional contract and policy-management complexity.

## Decision Outcome

**Chosen option**: Option 3.

Session and device management requirements:

1. **Session inventory contract** with active-session identity, device metadata,
   last activity, and assurance state.
2. **Trusted-device lifecycle contract** for register, challenge, trust,
   re-verify, and expire semantics.
3. **Session control contract** for revoke-single, revoke-group, and revoke-all
   behavior.
4. **Security and compatibility contract** for token/session schema versions,
   device attestation metadata, and migration safety.
5. **Release governance** with validation, approval, telemetry/audit, and
   rollback references.

## Normative Rules

### Session Inventory Contract

- Studio must expose all active sessions for the authenticated operator.
- Session records must include device fingerprint summary, platform, IP region,
  and last-activity timestamp.
- Stale or invalid sessions must be flagged and excluded from privileged
  actions.

### Trusted-Device Lifecycle Contract

- Device trust state must be explicit: `unverified`, `trusted`, `expired`,
  `revoked`.
- Trust elevation for privileged operations requires challenge and policy pass.
- Expired/revoked device trust must block privileged action grants.

### Session Control Contract

- Operators can revoke one session, scoped session groups, or all sessions.
- Revocation must be deterministic and eventually consistent across domains.
- Revoked sessions must not continue privileged Studio operations.

### Security and Compatibility Contract

- Session/token and device-attestation schema changes require version checks.
- Breaking changes require migration guidance and rollback references.
- Cross-domain identity handoffs must preserve session assurance metadata.

### Release Validity Contract

A session/device release is valid only when all are true:

- session inventory and device metadata validation checks pass
- trusted-device lifecycle and revocation flows pass deterministic validation
- policy allow/deny correctness checks pass for privileged operations
- telemetry/audit records are complete
- rollback strategy is documented

## Architecture Implications

- Studio web surfaces provide unified session inventory and device-governance
  UI.
- BFF enforces authoritative revocation and trust-policy decisions.
- Shared identity services expose versioned session/device contracts.
- Analytics pipelines capture request, decision, and outcome events for
  session/device actions.

## Acceptance Criteria (OST-00105)

`OST-00105` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0032-oshun-studio-session-and-device-management.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines session inventory, trusted-device lifecycle, session-control,
   compatibility, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0025` 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 control over active Studio sessions and trusted devices.
- Better incident response through deterministic revocation workflows.
- Improved audit/compliance posture for identity governance actions.

### Negative

- Higher operational complexity for trust and revocation policies.
- Requires disciplined schema/version governance across identity services.

## 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-0031-oshun-studio-authentication-architecture.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`