Disciplines · Decisions (ADRs)

ADR-0049: OSHUN Studio Security Hardening Program

Studio now orchestrates critical cross-domain workflows across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

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

Context and Problem Statement#

Studio now orchestrates critical cross-domain workflows across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian. Capabilities include release gates, automation callbacks, SDK/documentation publication, and sensitive governance actions.

Security controls exist across multiple layers (auth scopes, entitlement checks, device-integrity headers, abuse protection, transport policy, and policy-gated approvals), but the hardening strategy is not yet unified as one Studio program.

Without a canonical security hardening program, Studio risks:

  • inconsistent enforcement across workflow surfaces and domains
  • weaker defense against account/session abuse and privileged misuse
  • gaps between runtime controls and auditable governance evidence
  • delayed response to hardening regressions and emergent threats

Decision Drivers#

  • Defense in depth: layered controls across identity, transport, runtime, and operations.
  • Consistency: one hardening contract model for all Studio domains.
  • Governance: policy decisions and security events must remain auditable.
  • Reliability: controls must fail safely and preserve deterministic behavior.
  • Scalability: secure expansion to additional integrations and operators.

Considered Options#

Option 1: Domain-Local Security Hardening#

Each domain defines and enforces its own hardening controls independently.

Pros:

  • High domain autonomy and local iteration speed.

Cons:

  • Control drift and uneven security posture across Studio workflows.
  • Harder to audit and operate cross-domain security incidents.

Option 2: Perimeter-Only Hardening#

Rely primarily on edge/network controls with minimal workflow-level policy governance.

Pros:

  • Lower short-term implementation complexity.

Cons:

  • Insufficient protection for privileged workflow actions.
  • Weak visibility for policy-denial and control-bypass attempts.

Option 3: Canonical Studio Security Hardening Program (Chosen)#

Adopt one policy-aware hardening framework spanning identity/session, authorization/entitlements, device integrity, abuse protection, transport security, and telemetry/audit operations.

Pros:

  • Stronger and more consistent security posture across Studio.
  • Better governance traceability and incident response readiness.
  • Safer evolution of advanced workflows and integrations.

Cons:

  • Requires central governance and sustained control hygiene.

Decision Outcome#

Chosen option: Option 3.

Studio security hardening requirements:

  1. Identity and authorization assurance for all privileged actions.
  2. Runtime trust controls (device integrity, abuse/rate protection, entitlement checks).
  3. Transport and secret protections (HTTPS/host policy, certificate pinning, secret governance).
  4. Policy-aware decision governance with explicit deny-path semantics.
  5. Telemetry/audit continuity for hardening lifecycle and incident forensics.

Normative Rules#

Identity and Session Assurance Rule#

  • Sensitive Studio actions require authenticated actor identity and valid authorization scopes.
  • Session/token checks must fail closed on invalid, missing, or expired tokens.
  • Domain-scoped authorization decisions must be explicit and reason-coded.

Entitlement and Policy Enforcement Rule#

  • Entitlement evaluation must occur server-side for domain-critical decisions.
  • Role/tier/approval checks must gate sensitive publish, release, and recovery actions.
  • Unauthorized attempts must emit audit events with deterministic denial reasons.

Device Integrity and Runtime Trust Rule#

  • High-risk routes must enforce device-integrity status and attestation freshness.
  • Invalid integrity, platform, or attestation signals must be hard-denied.
  • Integrity policy changes require explicit rollout controls and validation.

Abuse Protection Rule#

  • Security-sensitive endpoints must apply bounded rate-limiting and retry-after semantics.
  • Abuse controls must be deterministic and route-aware.
  • Repeated abuse conditions must trigger operational visibility and escalation.

Transport Security and Secret Handling Rule#

  • Transport must enforce HTTPS and host allowlist policy.
  • Certificate pinning rollout must support report-only and enforce modes with auditable transition criteria.
  • Secret rotation, revocation, and signature metadata must be traceable and policy-governed.

Audit, Telemetry, and Incident Readiness Rule#

  • Hardening outcomes must emit structured telemetry and audit events.
  • Missing telemetry/audit continuity must trigger degraded-observability status.
  • Incident playbooks must include hardening-specific diagnostics and rollback controls.

Architecture Implications#

  • Studio introduces dedicated security-hardening governance surfaces and cross-domain policy views.
  • BFF middleware stack (authz, entitlements, abuse protection, device integrity) becomes a first-class hardening boundary.
  • Auth client transport security policy (including certificate pinning controls) becomes required for high-risk flows.
  • Operational dashboards and runbooks must include security-hardening SLOs and evidence links.

Acceptance Criteria (OST-00289)#

OST-00289 is complete only when:

  1. ADR exists at docs/adr/ADR-0055-oshun-studio-security-hardening-program.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines identity/session, entitlement/policy, runtime trust, abuse protection, transport/secret, and telemetry/audit rules.
  4. ADR aligns with ADR-0007 through ADR-0048, especially ADR-0010, ADR-0012, ADR-0047, and ADR-0048.
  5. ADR aligns with existing security control implementations in BFF and auth client surfaces.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Stronger defense-in-depth posture for Studio workflow operations.
  • More consistent policy and runtime control behavior across domains.
  • Better forensic and compliance readiness through explicit audit evidence.

Negative#

  • Increased governance and operational overhead for control lifecycle updates.
  • Requires disciplined coordination between platform, security, and domain teams.
  • 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-0053-oshun-studio-webhooks-and-external-automation.md
  • docs/adr/ADR-0054-oshun-studio-sdk-and-documentation-integration.md

References#

  • apps/oshun/bff/src/middleware/authz.ts
  • apps/oshun/bff/src/middleware/entitlements.ts
  • apps/oshun/bff/src/middleware/device-integrity.ts
  • apps/oshun/bff/src/middleware/abuse-protection.ts
  • apps/oshun/bff/src/routes/entitlements.ts
  • libs/oshun/auth/src/transport-security.ts
  • docs/releases/v1/runbooks/certificate-pinning-strategy.md
  • docs/releases/v1/runbooks/on-call-runbook.md