railiance-clock/docs/implementation-review-2026-09-15.md

Online Clock implementation and consumer review — 2026-09-15

The operator requested time infrastructure and relevant consumer integration in the SECRETS-WP-0010 session. This document specifies the concrete implementation for review and deployment. No expiry field, human approval or OS clock is changed.

Implemented profile

The existing ES256/JWS profile is implemented with PyJWT/cryptography, closed schemas, exact key/authority/environment/epoch/policy/nonce binding, bounded HTTP bodies, disabled redirects/proxies and a fresh online exchange for every read. The client uses Linux CLOCK_MONOTONIC and CLOCK_BOOTTIME; elapsed bounds include the extrema of both observations and configured drift/resolution allowances. Suspend disagreement beyond policy tolerance refuses; smaller disagreement is included in uncertainty. A boot-bound local trust admission expires by BOOTTIME, including across process restart. New processes cannot reset that deadline.

The private authority is proposed as a host systemd service for the initial pilot: it needs a root-owned host-health export, existing SSH transport and no cluster capacity. This avoids a privileged pod or host DBus mount and uses the existing S1 owner, not a new execution rail. It listens only on 127.0.0.1:8787, has no capabilities and cannot change the host clock. The health exporter is separately sandboxed, has no capabilities, and reads adjtimex with modes=0.

A fresh random epoch is generated for every authority process. Clients pin the admitted epoch and refuse a restart until a new owner admission. Persistent client rollback state is required, privately owned and flock-serialized; missing, corrupted or older state refuses. Admission recreates that state only through an explicit reviewed recovery; the runtime never repairs it automatically.

UTC and timer assumptions requiring native acceptance

The proposed initial model trusts the existing Linux discipline and the explicitly admitted ntp.ubuntu.com source. It requires TIME_OK, no UNSYNC or pending leap, timesyncd synchronization and a nonignored normal-leap source observation. Kernel maxerror/esterror plus a 10ms measurement margin and collection/sample aging supply a conservative bound conditional on the discipline's accounting and trusted upstream. This is not independent-source consensus or proof against a compromised host/upstream. It deliberately does not call endpoint count or a synchronization flag an independently measured accuracy bound.

Candidate online limits: kernel-derived error <=500ms, health age <10s, sample age <5s, RTT <2s, interval width <=3s, timer allowance 1000ppm plus 5ms resolution, suspend disagreement <=5ms and trust admission <=15 minutes. The 1000ppm allowance is a declared platform assumption, not a proven bound for every VM. Native pilot acceptance must record timer behavior and the supported platform. Unknown/frozen VM timer behavior is not licensed for protected offline use. No holdover is enabled. The authority's continuity monitor latches refusal after a 50ms wall/monotonic mapping change. Leap or continuity ambiguity requires fresh health and new epoch admission; old trust cannot make it usable.

The host role retains timesyncd. Clock configuration management and authority activation are separate explicit opt-ins; default inclusion in bootstrap changes nothing. The proposed 32–64s poll interval improves health recency; introducing new upstream operators is outside this initial source-preserving rollout.

Consumer adoption

Secrets Engine uses SECRETS_ENGINE_CLOCK_TRUST_FILE as an explicit configuration. A configured but missing/unusable Clock refuses. Its validators require the lower bound to reach not-before and upper bound to remain strictly before expiry and claim freshness. It rechecks decision validity before and after CAS consumption. Wrong actor/tenant/binding/policy checks and server-side CAS remain unchanged. No configured clock means the existing disciplined-host OS validation path. The optional wheel is reusable; no vendored second clock implementation.

Authority-side Flex Auth, Approval Engine, KeyCape and OpenBao already run on the host's disciplined clock: they should continue validating locally rather than adding a dependency on their own Clock endpoint. Third-party TLS, Kerberos, browser/OIDC and SSH validity checks are not rewritten by this adapter.

Ops Warden local audit timestamps and Intelligence Radar ingestion/trial timestamps are observations. Their relevant adoption is additive interval attribution; retain original local timestamps and monotonic durations. Authentication and spending contracts stay with their current owners. Native activation is separate from the existence of an optional adapter.

Custody and activation boundary

The authority key must arrive through platform-owned admitted custody; the Ansible role accepts only an explicit private source file with no_log and requires a source hash plus an admission reference. It never generates a production key or widens a KV grant. A disposable native test key establishes test evidence only. Client public-key/epoch admission uses an authenticated owner transport, not the untrusted sample under examination. Signing-key rotation/revocation invalidates all affected trust files; maximum trust lifetime is 15 minutes and no clock read renews it. Runtime liveness is separate from /readyz time usability.

Live deployment still needs exact source/artifact/custody receipts, native failure and recovery checks, idempotent convergence and explicit supported-platform acceptance. RCLK-WP-0002/0004/0005 remain open until those records exist.