Disciplines · Decisions (ADRs)

ADR-0027: OSHUN Studio RBAC and Permission Policy UX

Studio now includes multiple high-impact operational surfaces where permission decisions determine whether changes can be promoted, rolled back, or executed.

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

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Security, OSHUN Web + BFF Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio now includes multiple high-impact operational surfaces where permission decisions determine whether changes can be promoted, rolled back, or executed. Role and entitlement checks exist in parts of the stack, but policy outcomes are not consistently represented as first-class UX patterns across Studio.

Without a unified RBAC and permission-policy UX model, OSHUN risks:

  • inconsistent allow/deny behavior across Studio surfaces
  • unclear remediation paths when policy denies actions
  • policy drift between domain surfaces and shared governance rules
  • weak operator trust in authorization decisions during critical workflows

Decision Drivers#

  • Consistency: one permission UX contract for all Studio governance flows.
  • Operational safety: denied actions must fail safely without state mutation.
  • Transparency: users need explicit policy rationale and remediation paths.
  • Auditability: allow/deny outcomes must be observable and attributable.
  • Interoperability: policy UX must hold across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian workflows.

Considered Options#

Option 1: Surface-Level Role Checks Per Feature#

Each Studio feature implements role checks and messaging independently.

Pros:

  • Low immediate implementation effort.

Cons:

  • High UX and policy inconsistency risk.
  • Difficult centralized governance and compliance review.

Option 2: Backend-Only Policy Enforcement with Minimal UX Signals#

Enforce permissions in BFF/services and show generic errors in the UI.

Pros:

  • Strong backend control and simpler frontend implementation.

Cons:

  • Poor operator clarity on deny reasons.
  • Weak remediation guidance and reduced workflow efficiency.

Option 3: Unified RBAC + Permission Policy UX Contract (Chosen)#

Adopt a cross-surface UX contract where policy allowlists, deny reasons, resolution guidance, and audit evidence are explicit and deterministic.

Pros:

  • Consistent and explainable authorization behavior.
  • Better operational confidence and faster remediation.
  • Stronger security/compliance evidence quality.

Cons:

  • Additional policy-modeling and UX-governance complexity.

Decision Outcome#

Chosen option: Option 3.

RBAC and permission policy UX requirements:

  1. Role and entitlement contract for consistent role labels and permission scopes across Studio workflows.
  2. Policy decision contract with deterministic allowed/denied outcomes and reason codes.
  3. UX guidance contract for deny-state messaging and recovery actions.
  4. Compatibility contract for policy versioning and migration behavior.
  5. Release governance with validation, approval, telemetry/audit, and rollback controls.

Normative Rules#

Role and Entitlement Contract#

  • Studio surfaces must show active role and allowed role scopes for governed actions.
  • Role metadata must be sourced from authoritative identity/entitlement payloads.
  • Unknown role states must be treated as unauthorized by default.

Policy Decision Contract#

  • Permission checks must evaluate role + entitlement + contextual requirements.
  • Denied outcomes must include explicit, stable reason codes.
  • Denied actions must not mutate governance state.

UX Guidance Contract#

  • Denied states must include concise remediation guidance.
  • Allow/deny transitions must preserve context and avoid destructive resets.
  • Policy status must remain visible within active flow cards and action surfaces.

Compatibility Contract#

  • Policy schema/version changes require compatibility checks.
  • Breaking policy changes require migration guidance and rollback references.
  • Cross-domain actions must preserve policy context and role intent.

Release Validity Contract#

A policy UX release is valid only when all are true:

  • role/entitlement mapping checks pass
  • allow/deny decision behavior is deterministic
  • deny-state remediation guidance passes UX review
  • telemetry/audit policy events are complete
  • rollback strategy is documented

Architecture Implications#

  • Studio web surfaces expose role scopes and policy-deny explanations in all governed workflows.
  • BFF remains authoritative for policy evaluation and deny reason codes.
  • Shared identity and entitlement contracts become direct UX dependencies.
  • Analytics pipelines capture policy requests, decisions, and remediation paths.

Acceptance Criteria (OST-00113)#

OST-00113 is complete only when:

  1. ADR exists at docs/adr/ADR-0033-oshun-studio-rbac-and-permission-policy-ux.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines role/entitlement, policy decision, UX guidance, compatibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0026, 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#

  • More predictable and explainable authorization behavior across Studio.
  • Faster operator recovery from denied actions.
  • Stronger governance and compliance posture for permission decisions.

Negative#

  • Requires stricter policy lifecycle governance and UX consistency checks.
  • Increases integration surface between identity, policy, and frontend layers.
  • 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
  • docs/adr/ADR-0032-oshun-studio-session-and-device-management.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