# Authority Crypto Provider and JWKS Contract

This document defines the minimum contract Authority must satisfy to support sovereign crypto providers (FIPS, GOST, SM, PQ-ready modes where enabled) while keeping exports deterministic and offline-verifiable.

## 1) Scope
- Provider registry binding for Authority signing keys.
- JWKS export rules (which keys are exposed and how `kid` is computed).
- Signing profile selection rules (how Authority chooses keys/algorithms for different operations).
- Determinism requirements for JWKS JSON and key identifiers.

This contract is written so downstream consumers (Gateway, services, CLI, Offline Kit tooling) can validate tokens and rotate trust roots without depending on Authority's internal database schema.

## 2) Terms
- Provider: a crypto implementation or backend (software, HSM, KMS) identified by `provider_id`.
- Key: a signing key (or key handle) identified by `key_id` within a provider.
- Profile: a named signing policy that constrains algorithm choices and key selection.
- `kid`: the key identifier exposed in JWT headers and JWKS entries.

## 3) Provider registry (required fields)

Each registered Authority signing key MUST have, at minimum:
- `provider_id`: stable provider identifier (string).
- `key_id`: stable key identifier within the provider (string).
- `alg`: signing algorithm identifier as used by JWT/JWS (string).
- `usage`: at least `sig` (signing). If other usages are supported, they must be explicit.
- `tenant_scope` (optional): when set, the key is only valid for the specified tenant(s); when absent, it is platform-wide.

## 4) JWKS export rules

### 4.1 Which keys are exported
- JWKS MUST include only keys usable for token verification by downstream services.
- Exported keys MUST be filtered by:
  - profile rules (do not export keys that cannot be selected by any active profile), and
  - tenant scope (do not export tenant-scoped keys into other tenants' JWKS views if per-tenant JWKS is supported).

### 4.2 `kid` composition (deterministic)
`kid` MUST be stable across restarts and across equivalent deployments.

Recommended minimum rule:
- Compute `kid` from the public key material plus the profile discriminator:
  - `kid = sha256(public_key_spki_bytes || ":" || profile_id)`

If Authority exposes both an all-profiles JWKS and a per-profile JWKS, the `kid` value must remain stable in both views.

### 4.3 Canonical JWKS JSON (deterministic)
- JWKS JSON MUST be canonicalized for reproducible hashing and offline verification:
  - stable key ordering (sort by `kid` ascending),
  - stable field ordering within a key object,
  - no incidental whitespace dependence for hashing or signatures.

## 5) Signing profiles

Authority SHOULD define named profiles (examples: `default`, `ru-gost`, `pq-experimental`) that map:
- allowed algorithms (`alg` allowlist),
- allowed providers (provider allowlist),
- selection precedence when multiple keys match.

Profile selection MUST be deterministic given the same registry and request context.

## 6) Rotation and revocation expectations
- Rotation MUST preserve the ability to verify previously issued (unexpired) tokens.
- Revocation exports and JWKS exports MUST be consumable offline (cacheable and distributable in Offline Kit bundles).

## 7) Related docs
- Authority module dossier: `docs/modules/authority/architecture.md`
- Authority operations (key rotation, backup/restore): `docs/modules/authority/operations/`
- Gateway tenant/auth header contract: `docs/api/gateway/tenant-auth.md`