Overview
Static secrets create risk and operational burden. Loxation automates rotation of OAuth2 client_secrets and X‑API keys using standards‑aligned components and a secure distribution model. External clients continue to use client_id + client_secret — no protocol changes — while you gain deterministic verification, seamless cutovers, and complete auditability.
- Two‑Phase Promotion: prepare → promote with not_before scheduling and grace windows.
- Operator Assurance: App Attest + TOTP + MLS membership bind requests to real administrators.
- No Plaintext at Rest: Only HMACs + metadata persist; secrets are MLS‑only.
- Auditability: Immutable records of who, when, what version, and why — without exposing secrets.
Key Benefits
- Zero‑downtime cutovers with configurable grace
- Least‑privilege IAM; non‑exportable KMS MAC keys
- Fast rollback and immediate revoke options
- No plaintext in infra or logs — MLS E2EE only
Architecture
Planes & Roles
- Control Plane (rust‑nostr‑relay): verifies authorization, generates secrets, computes HMACs via KMS, writes metadata/pointers, distributes messages via MLS, records audits.
- Validation Plane (loxation‑server): validates presented secrets against current/previous hashes with KMS MACVerify.
- Admin App (MLS): initiates rotations, receives messages via MLS, provides approvals (quorum as policy).
- Store (Firestore): versioned secret metadata and rotation audit records (no plaintext).
Security Properties
- Plaintext Restriction: secrets appear only in MLS payloads to authorized admins; never stored server‑side.
- KMS MAC: HMAC‑SHA‑256 with non‑exportable keys; server stores only secret_hash with mac_key_ref and metadata.
- Strong Admin Auth: short‑lived jwt_proof (App Attest + TOTP + PoP) plus MLS membership checks.
- Grace Windows: configurable overlap where both current and previous are valid for zero‑downtime cutover.
Canonical MAC Input
Deterministic MACs ensure cross‑system verification. All inputs are UTF‑8 and length‑prefixed (32‑bit big‑endian):
data = len(client_id) || client_id
|| len(version_id) || version_id
|| len(secret) || secret
secret_hash = base64url_no_padding( HMAC_SHA256(mac_key_ref, data) )
Two‑Phase Rotation Workflow
Prepare → Promote with Grace
- Prepare: Relay creates new secret/version_id, computes secret_hash via KMS MACSign, writes metadata with state=pending and not_before ≥ Δ (policy minimum), and distributes messages via MLS to authorized admins.
- Approve: Optional quorum approvals by admins; deadline enforced (policy). If unmet, rotation cancels.
- Promote: At/after not_before, atomically set current_version to new; set previous to state=grace with not_after = not_before + grace.
- Validate: loxation‑server validates against current; if fail and within grace, validates against previous; tokens can embed client_version_id for fine‑grained revoke.
For emergency cases, set grace=0 to revoke immediately; for rollbacks within grace, promote previous_version back to current.
Operational Notes
Server Validation
- MACVerify against current; fallback to previous if within grace (with small clock‑skew tolerance).
- Access tokens can embed client_version_id to enable immediate revoke semantics.
- Observability: metrics and structured logs without secrets or MAC values.
Data Model Highlights
oauth2_clients/{clientId}: current_version, previous_version, status, admin_groups.secrets/{versionId}: secret_hash, algo, mac_key_ref, not_before, not_after, state.oauth2_rotations/{rotationId}: who, when, new/old versions, quorum, outcome.
Disaster Recovery (Optional)
If policy enables DR, an encrypted_secret blob can be stored alongside metadata, sealed under a separate KMS key. Access requires quorum approval and elevated audit, and is not used in normal code paths. Default: disabled.