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.tsFetchAuthTransportOptions.security
Supported controls:
requireHttps: reject insecure non-HTTPS URLs (except localhost loopback).allowedHosts: explicit hostname allowlist for transport calls.certificatePinning.mode:disabledreport-onlyenforce
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.
6. Recommended Rollout#
- Enable
requireHttps+allowedHostsin all environments. - Configure pin sets for production hosts.
- Run
report-onlyand monitor mismatches. - Ship native verifier in mobile runtime.
- Promote high-risk endpoints to
enforce.