Eve library

OSHUN Certificate Pinning Strategy

Runbook

Revision 1

On this page

Status: Active
Owner: OSHUN Security + Platform
Last Updated: February 16, 2026

1. Goal#

Define a certificate pinning strategy for OSHUN network traffic used by auth and high-risk API surfaces.

This strategy is policy-driven:

  • If policy does not require pinning, run standard TLS + host allowlist checks.
  • If policy does require pinning, enable report/enforce modes with native pin verification.

2. Current Implementation#

@oshun/auth-client now supports transport security policy enforcement via:

  • transport-security.ts
  • FetchAuthTransportOptions.security

Supported controls:

  • requireHttps: reject insecure non-HTTPS URLs (except localhost loopback).
  • allowedHosts: explicit hostname allowlist for transport calls.
  • certificatePinning.mode:
    • disabled
    • report-only
    • enforce
  • certificatePinning.pins: host -> SPKI SHA-256 pin set.
  • certificatePinning.verifier: native verifier hook for runtime pin matching.
  • certificatePinning.onReport: telemetry callback for mismatch reporting.

3. Operational Modes#

3.1 Disabled#

  • Use TLS + host allowlist only.
  • No pin verification call is attempted.

3.2 Report-Only#

  • Evaluate configured pins with verifier when available.
  • Never block requests due to mismatch.
  • Emit report payload for monitoring and rollout readiness.

3.3 Enforce#

  • Verifier is required.
  • Missing pins, missing verifier, or pin mismatch fails the request.

4. Required Native Integration#

JavaScript fetch cannot inspect peer certificates directly.
To enforce real pinning in production, mobile platforms must provide a native verifier implementation that returns:

  • matched/not matched
  • observed pins
  • optional failure reason

Until native verifier is wired, use report-only mode in production.

5. Pin Set Requirements#

  • Maintain at least two valid pins per host: primary + backup.
  • Rotate pins before cert rollover windows.
  • Validate pin updates in report-only mode first.
  • Promote to enforce mode only after clean report telemetry.
  1. Enable requireHttps + allowedHosts in all environments.
  2. Configure pin sets for production hosts.
  3. Run report-only and monitor mismatches.
  4. Ship native verifier in mobile runtime.
  5. Promote high-risk endpoints to enforce.