# OSHUN Certificate Pinning Strategy

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.

## 6. Recommended Rollout

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`.
