Eve library

OSHUN Studio Security Hardening Program Dependency and Data Contract Map

Spec

Revision 1

On this page

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.