secrets-engine/docs/railiance-clock-consumer-review.md

Railiance Clock lifecycle-consumer review

SECRETS-IN-0003, reviewed 2026-09-27. This completes the requested consumer review. It does not admit a new authority, key, deployment or execution window.

Reviewed inputs: railiance-clock 61e86a6e01c2e93a9af923a46772a41d080a5743, specs/sample-profile-v0.1.md, docs/implementation-review-2026-09-15.md, src/railiance_clock/{protocol,client,admission}.py, and this repository's application_time.py, approval validators and consume guard. The earlier intake describes a proposal, but consumer implementation and scoped native acceptance already exist in the approval contract and the September 16 receipt.

Signing compatibility and custody

The reviewed implementation delegates ES256 to PyJWT/cryptography, pinned by railiance-clock's dependency range (PyJWT[crypto]>=2.10,<3). It verifies the original compact envelope, restricts the algorithm to ES256, and requires an admitted P-256 public key and exact key ID. Closed headers, 64-byte signatures, canonical base64url, strict JSON, nonce and authority/environment/epoch/policy checks accompany signature verification. Secrets-engine uses that library; it has no independent signing or verification implementation.

The signing private key belongs to the platform's admitted custody and the clock authority runtime. It must not share an approval, KeyCape, SSH or engine credential. No signing key is delivered to this engine: its input is a public trust binding. The clock's explicit private-file deployment interface is not proof of OpenBao custody, renewal or fleet-wide admission. Those owner proofs remain in existing RCLK-WP-0002/0004/0005; no new custody task or lane is created.

Bootstrap, rotation and revocation

Admit the authority, environment, public-key fingerprint, key ID, epoch, policy, transport and finite lifetime over an independently authenticated owner path. The sample under verification cannot establish its own trust. HTTPS verification must work already; the reviewed alternative is explicitly admitted SSH-backed loopback transport. Neither permits disabling TLS checks or adjusting OS time.

The current trust admission is client-boot-bound, with a maximum 15-minute BOOTTIME deadline. Every read obtains a fresh sample and checks the trust file before and after exchange; cached usable-time holdover is absent. Missing or changed trust, expiration, an unknown epoch, rollback-state failure or excessive uncertainty must refuse. The engine's cached client intentionally remains refused after its trust file changes; restart/reacquisition requires a separately admitted replacement, not automatic trust discovery.

For rotation, platform/clock owners admit the replacement key and invalidate old client trust bindings, then consumers reacquire under the new binding. For revocation, invalidate every affected binding and stop the old authority before accepting further samples. File-change detection is local enforcement, not an automatic estate-wide revocation distribution system. A consumer whose old file is not invalidated can retain trust until its bounded deadline. Native rotation, revocation propagation and snapshot/recovery acceptance must be proved by the owners before claiming those operational guarantees. The library does not grant permission to reset the persisted rollback floor.

Consumer acceptance and limits

SECRETS_ENGINE_CLOCK_TRUST_FILE remains explicit opt-in. When configured, unavailable or untrusted time refuses; it never falls back to workstation time. An unconfigured engine retains its existing OS-clock path. Claim validity and freshness and PDP decision lifetime must contain the whole interval: the lower bound reaches not-before and the upper bound remains strictly before expiry. Nanosecond-to-microsecond conversion rounds outward. Decision validity is checked before and after CAS consume, with the existing actor/tenant/action/field/digest and policy checks unchanged. A refusal after consume prevents backend access, although the approval may already be consumed and needs a new request.

This is a check at the engine's consume boundary, not an atomic transaction spanning OpenBao or a proof that a long-running child remains within the decision lifetime. The library provides bounded time evidence, not authorization, spend admission, complete audit custody or provider-session revocation. Server-side issuers/approval storage retain their own validity enforcement.

The September 16 native receipt records three bounded samples, wrong-key-ID refusal, independent host cross-checks and a 900-second trust admission during one exact OpenRouter acceptance. It does not prove universal UTC accuracy, all-platform suspend behavior or a rotation/revocation exercise. Existing RCLK-WP-0002-T04 and RCLK-WP-0004 retain those owner acceptance boundaries. tests/test_application_time.py covers interval boundaries, missing trust, no shifted-time mixing and consume expiry refusal. This review accepts the explicit bounded-time consumer contract within those stated limits; it grants no new production use.