# OSHUN Studio Security Hardening Program Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Security Engineering + OSHUN BFF +
OSHUN Web + Platform SRE + OSHUN Data/Analytics Engineering  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0049-oshun-studio-security-hardening-program.md`

## Purpose

Define dependencies and canonical contracts for the Studio security hardening
program across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0049-oshun-studio-security-hardening-program.md`
- `docs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.md`
- `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`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.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

- **Identity and authorization controls**: bearer-token parsing, scope checks,
  and domain authorization pre-handlers.
- **Entitlement and tier controls**: domain-tier evaluation and suspension
  enforcement.
- **Device integrity controls**: high-risk pre-handler checks for integrity
  status, platform, and attestation freshness.
- **Abuse protection controls**: request-rate windows, block duration, and
  retry-after signaling.
- **Transport hardening controls**: HTTPS enforcement, host allowlists, and
  certificate pinning modes.
- **Telemetry and governance controls**: hardening outcomes, denials, and
  incident evidence streams.

### 1.2 Domain Dependency Graph

- `Security Hardening -> Yemaya`: release automation security and privileged
  execution controls.
- `Security Hardening -> Isis`: generation/inference authorization and runtime
  trust controls.
- `Security Hardening -> Hathor`: editorial/publishing governance and policy
  hardening controls.
- `Security Hardening -> Aja`: rendering/timeline security boundaries and abuse
  controls.
- `Security Hardening -> Bellona`: runtime/release safety controls and incident
  enforcement.
- `Project Obsidian -> all`: cross-domain security posture governance and
  coordinated hardening operations.

## 2. Ownership and Contract Matrix

| Area                                       | Owner                          | Consumers                            | Artifact                         | Contract                                |
| ------------------------------------------ | ------------------------------ | ------------------------------------ | -------------------------------- | --------------------------------------- |
| Identity/session and scope validation      | Security + BFF                 | Studio workflow services             | Auth context and scope decisions | `StudioSecurityIdentityContext`         |
| Domain entitlement evaluation              | Security + BFF                 | Domain bootstrap and access controls | Entitlement decision payload     | `StudioSecurityAuthorizationDecision`   |
| Device integrity and attestation checks    | Security + Platform Runtime    | High-risk route handlers             | Device attestation envelope      | `StudioSecurityDeviceIntegrityEnvelope` |
| Abuse/rate limiting controls               | Platform SRE + BFF             | Edge and route middleware            | Abuse protection state records   | `StudioSecurityAbuseProtectionRecord`   |
| Transport policy and certificate pinning   | Security + Auth Platform       | Auth and high-risk clients           | Transport policy records         | `StudioSecurityTransportPolicyRecord`   |
| Hardening incident and governance evidence | Security + Data Platform + SRE | Compliance + incident responders     | Hardening incident/audit stream  | `StudioSecurityHardeningAuditEvent`     |

## 3. Canonical Contracts

### 3.1 StudioSecurityIdentityContext

```ts
export interface StudioSecurityIdentityContext {
  actorId: string;
  sessionId?: string;
  scopes: string[];
  tokenExpiryAt?: string;
  authenticated: boolean;
  requestId: string;
  traceId: string;
}
```

### 3.2 StudioSecurityAuthorizationDecision

```ts
export interface StudioSecurityAuthorizationDecision {
  decisionId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  action: string;
  allowed: boolean;
  reasonCode:
    | 'missing_bearer_token'
    | 'invalid_token'
    | 'expired_token'
    | 'domain_scope_missing'
    | 'domain_suspended'
    | 'tier_insufficient';
  requiredTier?: 'free' | 'pro' | 'premium';
  effectiveTier?: 'free' | 'pro' | 'premium';
  decidedAt: string;
}
```

### 3.3 StudioSecurityDeviceIntegrityEnvelope

```ts
export interface StudioSecurityDeviceIntegrityEnvelope {
  envelopeId: string;
  platform: 'ios' | 'android' | 'web' | 'unknown';
  integrityStatus: 'verified' | 'browser_verified' | 'compromised' | 'unknown';
  attestedAt: string;
  maxAgeMs: number;
  acceptedStatuses: Array<
    'verified' | 'browser_verified' | 'compromised' | 'unknown'
  >;
  validated: boolean;
  reasonCode?:
    | 'invalid_integrity_status'
    | 'missing_attestation_timestamp'
    | 'stale_attestation'
    | 'invalid_platform';
}
```

### 3.4 StudioSecurityAbuseProtectionRecord

```ts
export interface StudioSecurityAbuseProtectionRecord {
  recordId: string;
  requestKey: string;
  windowMs: number;
  maxRequests: number;
  requestCount: number;
  blockedUntil?: string;
  retryAfterSeconds?: number;
  rateLimited: boolean;
  evaluatedAt: string;
}
```

### 3.5 StudioSecurityTransportPolicyRecord

```ts
export interface StudioSecurityTransportPolicyRecord {
  policyId: string;
  requireHttps: boolean;
  allowedHosts: string[];
  pinningMode: 'disabled' | 'report-only' | 'enforce';
  hostPins: Record<string, string[]>;
  verifierConfigured: boolean;
  lastEvaluatedAt: string;
}
```

### 3.6 StudioSecurityHardeningAuditEvent

```ts
export interface StudioSecurityHardeningAuditEvent {
  eventId: string;
  action:
    | 'security.identity.validated'
    | 'security.authorization.denied'
    | 'security.device_integrity.denied'
    | 'security.abuse_rate_limited'
    | 'security.transport_policy.blocked'
    | 'security.hardening_incident.opened'
    | 'security.hardening_incident.resolved';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  actorId?: string;
  domain?: string;
  reasonCode?: string;
  requestId?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Identity context must contain actor/scopes and deterministic request tracing.
- Authorization decisions must encode explicit reason codes for denied outcomes.
- Device integrity envelopes must validate status/platform/attestation
  freshness.
- Abuse protection records must include bounded window, threshold, and block
  metadata.
- Transport policy records must define HTTPS/host controls and pinning mode
  behavior.
- Hardening audit events must capture identity, authorization, runtime trust,
  transport, and incident lifecycle outcomes.

## 5. Acceptance Criteria (OST-00290)

`OST-00290` 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 identity, authorization, device integrity, abuse protection,
   transport policy, and hardening audits are documented.
4. Ownership boundaries and validation rules are explicit.
