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.mddocs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.mdapps/oshun/bff/src/middleware/authz.tsapps/oshun/bff/src/middleware/entitlements.tsapps/oshun/bff/src/middleware/device-integrity.tsapps/oshun/bff/src/middleware/abuse-protection.tsapps/oshun/bff/src/routes/entitlements.tslibs/oshun/auth/src/transport-security.tsdocs/releases/v1/runbooks/certificate-pinning-strategy.mddocs/releases/v1/runbooks/on-call-runbook.mddocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.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#
- 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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for identity, authorization, device integrity, abuse protection, transport policy, and hardening audits are documented.
- Ownership boundaries and validation rules are explicit.