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.mddocs/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#
- Permission outcomes must be explicit, explainable, and auditable.
- Denied actions must fail safely without mutating governance state.
- Role and policy context must remain visible during action execution.
- 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:
- Load actor role and entitlement context.
- Resolve applicable policy definition for the action.
- Evaluate allow/deny decision.
- Present policy outcome with reason metadata.
- 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:
- Surface deny reason code and human-readable explanation.
- Show required role/entitlement or assurance delta.
- Present remediation steps and escalation channel.
- Preserve current context and pending action intent.
- 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:
- Detect updated role/entitlement payload.
- Recompute policy eligibility for pending action.
- Compare previous and current outcomes.
- Allow action when requirements are satisfied.
- 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:
- Carry role/policy context into target domain flow.
- Evaluate target-domain action policy.
- Surface allow/deny outcome with domain-specific reason mapping.
- Block disallowed transitions safely.
- 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:
- Review validation evidence for policy UX changes.
- Promote release candidate.
- Monitor deny-rate, false-deny, and false-allow indicators.
- Roll back on regression thresholds.
- 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.startedstudio_permission_ux.journey.step.completedstudio_permission_ux.journey.blockedstudio_permission_ux.journey.recoveredstudio_permission_ux.journey.completed
Required dimensions:
actorId,actorRole,policyIdjourneyId,stepId,action,reasonCodeoutcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00115)#
OST-00115 is complete only when:
- At least five RBAC/permission UX journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.