# OSHUN Studio RBAC and Permission Policy UX Journeys and Edge Cases

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Security + Platform Identity + OSHUN
Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0027-oshun-studio-rbac-and-permission-policy-ux.md`
- `docs/releases/v1/specs/studio-rbac-and-permission-policy-ux-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio RBAC and
permission policy UX governance.

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

## Personas

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

## Journey Principles

1. Permission outcomes must be explicit, explainable, and auditable.
2. Denied actions must fail safely without mutating governance state.
3. Role and policy context must remain visible during action execution.
4. Deny-state remediation must be clear and actionable.

## 1. Primary Journeys

### J1. Policy-Aware Action Evaluation

**Goal**: Evaluate a Studio governance action against role and policy contracts.

**Entry**: `Governed action trigger`

**Steps**:

1. Load actor role and entitlement context.
2. Resolve applicable policy definition for the action.
3. Evaluate allow/deny decision.
4. Present policy outcome with reason metadata.
5. Execute action only on allow.

**Success State**:

- Action execution is policy-consistent and deterministic.

### J2. Permission Denial with Remediation Guidance

**Goal**: Provide clear remediation when an action is denied.

**Entry**: `Policy deny outcome`

**Steps**:

1. Surface deny reason code and human-readable explanation.
2. Show required role/entitlement or assurance delta.
3. Present remediation steps and escalation channel.
4. Preserve current context and pending action intent.
5. Emit deny/remediation audit evidence.

**Success State**:

- Operator understands why the action was denied and what to do next.

### J3. Role Context Switch and Re-Evaluation

**Goal**: Re-evaluate policy outcomes after role or entitlement changes.

**Entry**: `Role update, elevated grant, or entitlement refresh`

**Steps**:

1. Detect updated role/entitlement payload.
2. Recompute policy eligibility for pending action.
3. Compare previous and current outcomes.
4. Allow action when requirements are satisfied.
5. Record transition evidence.

**Success State**:

- Policy outcomes update correctly when role/entitlement context changes.

### J4. Cross-Domain Permission Continuity

**Goal**: Preserve policy intent and permission outcomes across domain handoffs.

**Entry**: `Cross-domain workflow transition`

**Steps**:

1. Carry role/policy context into target domain flow.
2. Evaluate target-domain action policy.
3. Surface allow/deny outcome with domain-specific reason mapping.
4. Block disallowed transitions safely.
5. Emit cross-domain permission audit evidence.

**Success State**:

- Permission behavior remains consistent across domain boundaries.

### J5. Policy UX Release Promotion and Rollback

**Goal**: Promote policy UX changes safely and roll back regressions.

**Entry**: `Review & Approvals` or `Permission incident alert`

**Steps**:

1. Review validation evidence for policy UX changes.
2. Promote release candidate.
3. Monitor deny-rate, false-deny, and false-allow indicators.
4. Roll back on regression thresholds.
5. Publish mitigation and prevention actions.

**Success State**:

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

## 2. Critical Edge Cases

### E1. Missing Role Context

- Trigger: action evaluation starts without role payload.
- Required behavior: default deny with `ROLE_CONTEXT_MISSING`.

### E2. Unknown Role Identifier

- Trigger: actor role id not found in role catalog.
- Required behavior: deny action and require role catalog refresh.

### E3. Stale Policy Version

- Trigger: policy version in client differs from authoritative version.
- Required behavior: refresh policy definitions before evaluation.

### E4. Missing Deny Reason Mapping

- Trigger: deny outcome produced without mapped reason guidance.
- Required behavior: block action and surface generic secure fallback guidance.

### E5. Entitlement Drift During Pending Action

- Trigger: entitlement payload changes while action is pending.
- Required behavior: re-evaluate policy before commit.

### E6. Unauthorized Remediation Bypass Attempt

- Trigger: actor attempts action retry without resolving deny conditions.
- Required behavior: deny again with unchanged reason code.

### E7. Cross-Domain Permission Mismatch

- Trigger: source domain allow but target domain deny for same intent.
- Required behavior: apply target-domain policy and preserve source context.

### E8. Multi-Tab Policy Race

- Trigger: concurrent tabs evaluate against different policy snapshots.
- Required behavior: deduplicate and enforce latest authoritative decision.

### E9. Telemetry/Audit Emission Failure

- Trigger: policy request/allow/deny events fail to emit.
- Required behavior: buffer/retry and show degraded observability warning.

### E10. Missing Rollback Reference for Policy UX Release

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

## 3. Journey-to-Surface Mapping

| Journey                                        | Primary Surface             | Supporting Surfaces      |
| ---------------------------------------------- | --------------------------- | ------------------------ |
| J1 Policy-Aware Action Evaluation              | RBAC & Permission Policy UX | Governance workspaces    |
| J2 Permission Denial with Remediation Guidance | RBAC & Permission Policy UX | Security policy services |
| J3 Role Context Switch and Re-Evaluation       | RBAC & Permission Policy UX | Identity services        |
| J4 Cross-Domain Permission Continuity          | RBAC & Permission Policy UX | Domain adapters          |
| J5 Policy UX Release Promotion and Rollback    | Review & Approvals          | Observability, Security  |

## 4. Instrumentation Requirements

Required events:

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

Required dimensions:

- `actorId`, `actorRole`, `policyId`
- `journeyId`, `stepId`, `action`, `reasonCode`
- `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00115)

`OST-00115` is complete only when:

1. At least five RBAC/permission UX 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.
