# ADR-0049: OSHUN Studio Security Hardening Program

**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.

## Related Decisions

- `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`