docs consolidation

docs/modules/authority/README.md

@@ -34,6 +34,7 @@ Authority is the platform OIDC/OAuth2 control plane that mints short-lived, send
 - ./operations/key-rotation.md
 - ./operations/monitoring.md
 - ./operations/grafana-dashboard.json
+- ./crypto-provider-contract.md
 - ./gaps/2025-12-04-auth-gaps-au1-au10.md
 - ./gaps/2025-12-04-rekor-receipt-gaps-rr1-rr10.md
 - Sprint/status mirrors: `docs/implplan/SPRINT_0314_0001_0001_docs_modules_authority.md`, `docs/modules/authority/TASKS.md`

docs/modules/authority/crypto-provider-contract.md

@@ -0,0 +1,68 @@
+# 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`
+

docs/modules/authority/prep/2025-11-20-auth-crypto-provider-prep.md

@@ -1,19 +0,0 @@
-# Authority Crypto Provider Contract Prep — PREP-AUTH-CRYPTO-90-001-NEEDS-AUTHORITY-PROVI
-
-Status: Draft (2025-11-20)
-Owners: Authority Core Guild · Security Guild
-Scope: Capture the provider/key/JWKS contract Authority must publish to unblock sovereign crypto enablement.
-
-## Required contract elements
-- Provider registry binding for Authority signing keys (FIPS, GOST, PQ optional): fields `provider_id`, `key_id`, `alg`, `kid`, `usage`, `tenant_scope?`.
-- JWKS export requirements: which keys exposed, `x5u`/`x5c` handling, `kid` format, and rotation cadence.
-- Signing profiles: mapping of Authority API operations to provider profiles (default, ru-gost, pq-experimental).
-- Determinism: canonical JSON for JWKS; stable `kid` composition (hash of public key + profile).
-
-## Acceptance / unblock criteria
-- Publish provider contract in `docs/modules/authority/crypto-provider-contract.md` (or update existing doc) with sample JWKS and provider config snippet.
-- Record schema hash/kid composition rule here and in Sprint 0514 Decisions/Risks.
-- Notify downstream consumers (Scanner, Attestor, Concelier) via sprint links once frozen.
-
-## Handoff
-Use this doc as the prep artefact for PREP-AUTH-CRYPTO-90-001-NEEDS-AUTHORITY-PROVI. Update with the final contract and samples; then set the sprint task to DONE and unblock AUTH-CRYPTO-90-001 implementation.