# OSHUN Studio RBAC and Permission Policy UX Dependency and Data Contract Map

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`

## Purpose

Define dependencies and canonical contracts for Studio RBAC and permission
policy UX across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0025-oshun-studio-authentication-architecture.md`
- `docs/adr/ADR-0027-oshun-studio-rbac-and-permission-policy-ux.md`
- `libs/oshun/auth/src/index.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `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`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Policy-aware UX surfaces**: Studio governance workspaces in
  `apps/oshun/web/src/components/studio`.
- **Identity and role authority**: `libs/oshun/auth` + entitlement services.
- **Permission policy decisioning**: security policy engine + BFF middleware.
- **Cross-domain permission propagation**: domain adapters + policy
  orchestration.
- **Telemetry and audit**: `libs/oshun/analytics` + security/data pipelines.

### 1.2 Domain Dependency Graph

- `RBAC/Permission UX -> Yemaya`: content and asset governance actions require
  explicit role scopes and deny-state guidance.
- `RBAC/Permission UX -> Isis`: model/workflow operations require deterministic
  permission decisions and remediation feedback.
- `RBAC/Permission UX -> Hathor`: narrative/publishing controls require
  transparent allow/deny policy outcomes.
- `RBAC/Permission UX -> Aja`: media/timeline approvals require role-aware
  transition permissions and deny handling.
- `RBAC/Permission UX -> Bellona`: runtime/release controls require strict
  permission gating and policy consistency.
- `Project Obsidian -> all`: central governance for policy catalogs, role
  definitions, and escalation ownership.

## 2. Ownership and Contract Matrix

| Area                                | Owner                         | Consumers                        | Artifact              | Contract                           |
| ----------------------------------- | ----------------------------- | -------------------------------- | --------------------- | ---------------------------------- |
| Studio role catalog                 | Platform Identity + Security  | Web + BFF + Studio surfaces      | Role model payload    | `StudioRoleCatalog`                |
| Permission policy definitions       | Security + Program Governance | Studio workspaces                | Policy config payload | `StudioPermissionPolicyDefinition` |
| Runtime decision envelope           | OSHUN BFF                     | Studio actions + audit pipelines | Decision payload      | `StudioPermissionDecisionEnvelope` |
| Deny guidance and remediation model | OSHUN Web + Security UX       | Operators                        | UX guidance payload   | `StudioPolicyDenyGuidance`         |
| Audit/compliance evidence           | Data Platform + Security      | Governance + Compliance          | Event stream          | `StudioPermissionAuditEvent`       |

## 3. Canonical Contracts

### 3.1 StudioRoleCatalog

```ts
export interface StudioRoleCatalog {
  roles: Array<{
    roleId: string;
    label: string;
    permissions: string[];
    managedBy: 'security' | 'identity' | 'program';
  }>;
  version: string;
  publishedAt: string;
}
```

### 3.2 StudioPermissionPolicyDefinition

```ts
export interface StudioPermissionPolicyDefinition {
  policyId: string;
  action: string;
  allowedRoles: string[];
  requiredEntitlements: string[];
  requiredAssuranceLevel?: 'standard' | 'elevated';
  denyReasonCodes: string[];
  version: string;
}
```

### 3.3 StudioPermissionDecisionEnvelope

```ts
export interface StudioPermissionDecisionEnvelope {
  decisionId: string;
  action: string;
  actorId: string;
  actorRole: string;
  policyId: string;
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  evaluatedAt: string;
}
```

### 3.4 StudioPolicyDenyGuidance

```ts
export interface StudioPolicyDenyGuidance {
  reasonCode: string;
  title: string;
  description: string;
  remediationSteps: string[];
  escalationChannel?: string;
}
```

### 3.5 StudioPermissionAuditEvent

```ts
export interface StudioPermissionAuditEvent {
  eventId: string;
  action:
    | 'studio_permission.requested'
    | 'studio_permission.allowed'
    | 'studio_permission.denied'
    | 'studio_permission.remediation.viewed'
    | 'studio_permission.policy.updated';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  actorId: string;
  actorRole: string;
  actionName: string;
  policyId: string;
  reasonCode?: string;
  traceId: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Governed actions must resolve against an explicit policy definition before
  execution.
- Denied outcomes must include stable reason codes and remediation guidance.
- Unknown or stale role states must default to deny.
- All request/allow/deny/remediation outcomes must emit
  `StudioPermissionAuditEvent` records.

## 5. Acceptance Criteria (OST-00114)

`OST-00114` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for role catalog, policy definition, decision envelope, deny
   guidance, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
