Harden production authorization and service auth

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0217e-8c4c-7383-be6b-f50a6e485306

docs/service-auth.md

@@ -0,0 +1,28 @@
+# KeyCape service-auth consumer boundary
+
+secrets-engine now implements the consumer half of KeyCape's accepted
+`secrets-engine-openbao` service-auth contract. It performs one explicit HTTPS
+`client_credentials` exchange, keeps the resulting JWT in memory, and validates
+the non-cryptographic contract before any future OpenBao login:
+
+- subject `service:secrets-engine`, audience/client `secrets-engine-openbao`;
+- service principal in `tenant:coulomb`, role `secrets-engine`;
+- exact `openbao:login` scope and KeyCape AAL1 client-secret assurance;
+- RS256 declaration, bounded issue/expiry timestamps, maximum 15-minute life,
+  and renewal when no more than three minutes remain;
+- no ID token, refresh token, implicit retry provider, or fallback identity.
+
+The confidential-client secret must be an explicitly selected mode-0600 file
+outside every Git worktree. It is sent with HTTP Basic authentication and never
+placed in a request body, command argument, evidence record, or object
+representation.
+
+This is a scaffold, not a live OpenBao authentication path. JWT payload parsing
+does not prove a signature. railiance-platform still owns the exact OpenBao JWT
+auth mount/role, issuer keys, claim bindings, token policy, TTL/use limits, and
+cryptographic verification. Until that contract is materialized, the provider
+is not selected by the CLI and bootstrap/AppRole behavior is not used as an
+implicit fallback.
+
+Canonical provider contract:
+`key-cape/docs/openbao-service-auth-contract.md` (reviewed 2026-08-23).