# OSHUN Studio Session and Device Management Journeys and Edge Cases

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`
- `docs/releases/v1/specs/studio-session-and-device-management-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio session
and device management governance.

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

## Personas

- Program Operator
- Security Reviewer
- Domain Integrator
- Reliability Engineer
- Compliance Auditor

## Journey Principles

1. Active session and device state must always be visible and verifiable.
2. Trust and revocation actions must be deterministic and auditable.
3. Privileged operations must block on stale, revoked, or untrusted contexts.
4. Recovery paths must preserve user intent while restoring secure state.

## 1. Primary Journeys

### J1. Active Session Inventory and Device Visibility

**Goal**: Inspect all active Studio sessions and associated device trust state.

**Entry**: `Studio -> Session & Device Management -> Inventory`

**Steps**:

1. Load current user session inventory.
2. Display platform, location, assurance, and last activity metadata.
3. Highlight stale or suspicious sessions.
4. Surface trust state per device.
5. Present next-action controls (revoke, re-verify, challenge).

**Success State**:

- Operator sees a complete and accurate view of active sessions/devices.

### J2. Trusted-Device Enrollment for Privileged Operations

**Goal**: Elevate a device to trusted state for privileged Studio workflows.

**Entry**: `Privileged action requires trusted device`

**Steps**:

1. Initiate trust enrollment on selected device.
2. Execute challenge/attestation flow.
3. Validate challenge outcome and policy eligibility.
4. Update device trust state to `trusted`.
5. Emit trust-elevation audit evidence.

**Success State**:

- Device trust is established and privileged actions may proceed.

### J3. Session Revocation for Suspected Compromise

**Goal**: Revoke one or more active sessions quickly and deterministically.

**Entry**: `Security alert or suspicious activity detection`

**Steps**:

1. Identify target session(s) from inventory.
2. Select revoke scope (single/device/all).
3. Execute revocation request.
4. Confirm revocation propagation across domains.
5. Surface completion status and residual risk guidance.

**Success State**:

- Target sessions are revoked and blocked from further privileged operations.

### J4. Device Trust Expiry and Re-Verification Recovery

**Goal**: Recover securely when previously trusted device state expires.

**Entry**: `Trust expiry event during privileged workflow`

**Steps**:

1. Detect expired device trust state.
2. Pause pending privileged action.
3. Prompt re-verification challenge.
4. Re-establish trust or deny privileged continuation.
5. Resume flow only on successful re-verification.

**Success State**:

- Expired trust is handled safely and privileged continuation is controlled.

### J5. Session/Device Governance Promotion and Rollback

**Goal**: Promote session/device policy changes safely and roll back on
regressions.

**Entry**: `Review & Approvals` or `Identity/Security alert`

**Steps**:

1. Review validation evidence for trust/revocation contracts.
2. Promote release candidate.
3. Monitor trust, revocation, and deny-rate telemetry.
4. Roll back on regression indicators.
5. Publish post-incident mitigation and prevention actions.

**Success State**:

- Policy release is stable or safely rolled back with full evidence.

## 2. Critical Edge Cases

### E1. Session Inventory Payload Missing Required Fields

- Trigger: session record omits `sessionId`, `deviceId`, or `lastSeenAt`.
- Required behavior: mark inventory degraded and block privileged controls.

### E2. Duplicate Session IDs in Inventory

- Trigger: inventory response contains duplicate `sessionId`.
- Required behavior: quarantine invalid records and request inventory refresh.

### E3. Unauthorized Actor Tries Revoke-All

- Trigger: role lacks entitlement for global revocation.
- Required behavior: deny action and preserve all active sessions.

### E4. Revocation Partial Failure

- Trigger: some domain adapters fail revocation propagation.
- Required behavior: mark outcome `partial`, retry propagation, and escalate.

### E5. Device Trust Attestation Failure

- Trigger: challenge/attestation fails validation.
- Required behavior: keep device untrusted and deny privileged continuation.

### E6. Device Trust Expires Mid-Action

- Trigger: trust TTL expires while privileged action is in-flight.
- Required behavior: pause action and require re-verification.

### E7. Session Revoked Mid-Workflow

- Trigger: active session revoked from another surface/device.
- Required behavior: stop privileged pipeline and require re-authentication.

### E8. Multi-Tab Revocation Race

- Trigger: concurrent tabs issue overlapping revoke requests.
- Required behavior: deduplicate by request id and keep deterministic outcomes.

### E9. Telemetry/Audit Emission Failure

- Trigger: session/device events fail to emit.
- Required behavior: buffer/retry and surface degraded observability warning.

### E10. Missing Rollback Reference for Policy Release

- Trigger: release candidate has no certified rollback contract.
- Required behavior: block production promotion.

## 3. Journey-to-Surface Mapping

| Journey                                                | Primary Surface             | Supporting Surfaces         |
| ------------------------------------------------------ | --------------------------- | --------------------------- |
| J1 Active Session Inventory and Device Visibility      | Session & Device Management | Identity services           |
| J2 Trusted-Device Enrollment for Privileged Operations | Session & Device Management | Authentication Architecture |
| J3 Session Revocation for Suspected Compromise         | Session & Device Management | Security operations         |
| J4 Device Trust Expiry and Re-Verification Recovery    | Session & Device Management | Challenge services          |
| J5 Session/Device Governance Promotion and Rollback    | Review & Approvals          | Observability, Security     |

## 4. Instrumentation Requirements

Required events:

- `studio_session_device.journey.started`
- `studio_session_device.journey.step.completed`
- `studio_session_device.journey.blocked`
- `studio_session_device.journey.recovered`
- `studio_session_device.journey.completed`

Required dimensions:

- `userId`, `sessionId`, `deviceId`
- `journeyId`, `stepId`, `action`, `trustState`
- `actorRole`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00107)

`OST-00107` is complete only when:

1. At least five session/device management journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
