Disciplines · Decisions (ADRs)

ADR-0026: OSHUN Studio Session and Device Management

Studio operators use multiple devices and long-lived workflows while executing critical actions (approvals, promotions, rollback decisions, and incident response).

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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