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.mddocs/adr/ADR-0025-oshun-studio-authentication-architecture.mddocs/adr/ADR-0027-oshun-studio-rbac-and-permission-policy-ux.mdlibs/oshun/auth/src/index.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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
StudioPermissionAuditEventrecords.
5. Acceptance Criteria (OST-00114)#
OST-00114 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for role catalog, policy definition, decision envelope, deny guidance, and audit events are documented.
- Ownership boundaries and validation rules are explicit.