Eve library

OSHUN Studio RBAC and Permission Policy UX Journeys and Edge Cases

Spec

Revision 1

On this page

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.