From 42bc5b37ab5d2cab9c0121f408ced818752480d6 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 14 Sep 2026 10:12:30 +0200 Subject: [PATCH] Seed application-clock intent, specification and staged workplans Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a09cbc-910e-77a0-b336-3130194350b3 --- .custodian-brief.md | 10 + .gitignore | 5 + .repo-classification.yaml | 12 ++ AGENTS.md | 55 +++++ CLAUDE.md | 3 + INTENT.md | 82 +++++++ README.md | 21 +- SCOPE.md | 27 +++ docs/ecosystem.md | 53 +++++ history/2026-09-14-genesis.md | 21 ++ specs/acceptance-v0.1.md | 35 +++ specs/railiance-clock-v0.1.md | 200 ++++++++++++++++++ workplans/RCLK-WP-0001-foundation.md | 44 ++++ workplans/RCLK-WP-0002-contract-review.md | 56 +++++ .../RCLK-WP-0003-reference-implementation.md | 46 ++++ workplans/RCLK-WP-0004-deployment-adoption.md | 56 +++++ 16 files changed, 725 insertions(+), 1 deletion(-) create mode 100644 .custodian-brief.md create mode 100644 .gitignore create mode 100644 .repo-classification.yaml create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 INTENT.md create mode 100644 SCOPE.md create mode 100644 docs/ecosystem.md create mode 100644 history/2026-09-14-genesis.md create mode 100644 specs/acceptance-v0.1.md create mode 100644 specs/railiance-clock-v0.1.md create mode 100644 workplans/RCLK-WP-0001-foundation.md create mode 100644 workplans/RCLK-WP-0002-contract-review.md create mode 100644 workplans/RCLK-WP-0003-reference-implementation.md create mode 100644 workplans/RCLK-WP-0004-deployment-adoption.md diff --git a/.custodian-brief.md b/.custodian-brief.md new file mode 100644 index 0000000..f4042b9 --- /dev/null +++ b/.custodian-brief.md @@ -0,0 +1,10 @@ +# Custodian Brief — railiance-clock + +2026-09-14: specification/planning seed. No runtime, endpoint, SDK or production +admission. Prefix RCLK-WP; tooling/infotech. Source remote already points to +Coulomb Forgejo. Registration pending foundation T03. + +Start with INTENT → SCOPE → specs → docs/ecosystem.md → workplans. +0001 establishes the repository; 0002 reviews trust/ownership/consumer contracts; +0003 implements an isolated reference; 0004 owns native deployment/adoption. +Corporate clocks remain untouched. Forgejo records history, not UTC accuracy. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1367fc7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +__pycache__/ +*.py[cod] +.venv/ +.runtime/ +.evidence-private/ diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..2920e95 --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,12 @@ +repo_classification: + standard: Repo Classification Standard + version: '1.1' + classified_at: '2026-09-14' + classified_by: codex + category: tooling + domain: infotech + secondary_domains: [] + capability_tags: [application-time, clock-translation, uncertainty, provenance] + business_stake: [technology, operations, automation] + business_mechanics: [control, coordination, operation] + notes: Railiance application time capability; source ownership repository, not a rail, rapp, reef or security decision engine. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2d2eacf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,55 @@ +# railiance-clock — Agent Instructions + +Purpose: authenticated, uncertainty-aware application time across independently +managed hosts. Domain: infotech. Repo slug: railiance-clock. Prefix: `RCLK-WP-`. + +## Orientation + +Read INTENT.md → SCOPE.md → specs/railiance-clock-v0.1.md → specs/acceptance-v0.1.md +→ docs/ecosystem.md → .custodian-brief.md → workplans/. Check unread Statehub +messages to railiance-clock and relevant human-needed tasks. Mark read only after +processing. Inspect local Git changes before editing. + +## State Hub + +Use REST/CLI; MCP is opt-in. Local primary tunnel: http://127.0.0.1:8000; +remote tunnel alternative: http://127.0.0.1:18000. Verify `/state/health` identity +before writes: expected primary/railiance01. Explicitly configured relay receipts +are pending until replay/readback. Retry sandbox-related loopback failures with +escalated execution before declaring an outage. Do not copy work records into a +second database or treat Statehub as time authority. + +Workplans are source files in workplans/RCLK-WP-NNNN-.md. Use frontmatter +id, type: workplan, title, domain: infotech, repo: railiance-clock, status, +owner, created and updated. Statuses: proposed, ready, active, blocked, backlog, +finished, archived. One task block per `##` section; task id RCLK-WP-NNNN-TNN, +status wait/todo/progress/done/cancel and priority high/medium/low. Repo Manager +assigns only missing deterministic bridge UUIDs; do not fabricate them. + +Before finishing a plan, hand residuals to live work records. Log meaningful +progress to POST /progress/ with author and workplan/task UUID when applicable. +After source changes, commit then run: + +```bash +uv run --project ~/repo-manager rmgr sync --path . --push +``` + +Require exact pushed-commit applied/noop receipt from primary/railiance01. A queued +receipt is pending. Use statehub fix-consistency only for a separate deep audit. + +## Engineering boundaries + +- This seed is not a deployed service or adopted security contract. +- Do not change corporate host clocks, time configuration or artifact validity + fields as a workaround. Adoption belongs to the consumer and security owners. +- Forgejo preserves history; Git dates and HTTP Date headers are not trusted time samples. +- Never equate signature validity with clock accuracy or a nonce with delay bounds. +- Never weaken TLS verification, accept future/expired credentials on guessed time, + or silently fall back to OS wall time when the Railiance clock is unusable. +- No security engine roles, policies, keys or public listeners are created by registration. +- Test with fake clocks and disposable infrastructure first. Native tests must + preserve expiry, wrong-identity and failure-path checks. +- Before credential work run `warden plan "" --json`, then route find/show. + Use admitted owner transports; never print or commit secret values. +- Use the canonical security-layer model and Railiance owner contracts linked in + docs/ecosystem.md. Record undecided layer/PEP mapping as open review, not compliance. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ad429d2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# railiance-clock + +Read and follow [AGENTS.md](AGENTS.md). Shared instructions have one source. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..9ebf7d6 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,82 @@ +# INTENT — Railiance Clock + +Status: founding intent, adopted for repository development on 2026-09-14. +Runtime and cross-owner security adoption are not yet approved. + +## Purpose + +Railiance Clock provides an authenticated, uncertainty-aware estimate of Railiance +UTC to services and attached workstations without taking control of clocks owned +by another organization. It makes time-dependent operations explainable across +independently managed environments. + +Railiance must work with corporate Windows hosts, Linux/WSL guests, roaming +laptops, suspended sessions and remote services. A workstation may be forbidden +or unable to synchronize its OS clock to Railiance. Requiring it to do so is not +a viable application contract. + +## Intended outcome + +A consumer can ask what time Railiance currently has reason to believe it is, +learn the estimate's uncertainty, freshness and authority, and use that evidence +under the consumer's own reviewed validity policy. A historical event can retain +its original local timestamp alongside a separately attributed Railiance receipt +or estimated event time. Uncertainty is visible rather than hidden in a timestamp. + +The initial authority is intended to run on railiance01, disciplined to external +UTC sources. Railiance time is a trusted estimate of UTC, not a new time zone or +an arbitrary counter. Authority health, upstream independence and rollback must +be observed; a host name alone does not establish trustworthy time. + +Forgejo is the durable home for reviewed source, policies, work records and +selected evidence. Forgejo commit dates, request headers and commit ordering do +not establish UTC accuracy, credential lifetime or the occurrence time of an event. +This distinction refines the founding idea of Forgejo as timekeeper. + +## Principles + +1. Preserve corporate OS time management. Offer a process-local clock interface; + never silently set Windows, WSL or Linux wall clocks. +2. Report a time interval, provenance and quality state. Precision of formatting + must not imply accuracy. Every claimed bound states its assumptions. +3. Anchor accepted time samples to a monotonic clock; use elapsed time for local + durations. Detect or invalidate clock domains across restart and suspend. +4. Authenticate the authority and freshness of each sample. A signed old sample + is not fresh time, and a valid TLS channel does not prove the server clock is right. +5. Preserve signed validity fields and original observations. Translation appends + an estimate; it does not rewrite an artifact or retroactively make it valid. +6. Keep privileged validity decisions and execution on disciplined Railiance + hosts where practical. Local consumer adoption is an explicit owner contract. +7. Never become an identity provider, policy decision point, approval issuer, + credential broker, causal-order authority or a replacement for audit-core. +8. Respect independent authority: discovery, repository registration, deployment + admission, authorization and proven operational readiness are different facts. + +## Service boundaries + +This repository owns the time-sample protocol, uncertainty semantics, application +clock interface, reference implementation and conformance tests. Host discipline +and networking remain with infrastructure owners. Keys and trust distribution +consume existing NetKingdom ownership. Deployment packaging and exposure follow +Railiance architecture. Security consumers own the decision to accept this clock +and the lifetime policy applied to artifacts. + +## Success criteria + +- Managed corporate workstation and deliberately skewed guest obtain a usable + Railiance clock without any OS time change. +- Loss of authority, stale/replayed samples, uncertainty overflow, reboot, + suspend/resume and authority clock discontinuities produce explicit states. +- A supported consumer accepts or refuses boundary cases conservatively under + an adopted contract, while wrong signatures and expired artifacts still fail. +- Event records preserve local provenance and receipt time without inventing + exact occurrence time or global ordering. +- A railiance01 pilot publishes measured behavior, authority health and recovery + evidence; unresolved assumptions remain in live workplans. + +## Non-goals + +Changing corporate AD/NTP policy; bypassing TLS/Kerberos/browser checks; widening +JWT leeway to hide bad time; trusting a timestamp just because it came from +Forgejo; rewriting Git history; executing paid model trials; deploying a public +NTP reflector; inventing a new security engine or universal total event order. diff --git a/README.md b/README.md index 7ad56ac..d0e056c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,22 @@ # railiance-clock -Timeservice for application clock timestamps that need to be mapped to official railiance time. \ No newline at end of file +Authenticated application time for Railiance services and attached workstations +whose operating-system clocks are managed independently. + +Status: specification and planning baseline; no service is deployed. + +Read [INTENT](INTENT.md), [scope](SCOPE.md), the [draft specification](specs/railiance-clock-v0.1.md), +[acceptance criteria](specs/acceptance-v0.1.md), and [ecosystem ownership](docs/ecosystem.md). + +Workplan prefix: `RCLK-WP-`. Classification: tooling / infotech. Source is hosted +in the Coulomb Forgejo organization; repository registration does not admit a runtime. + +## Workplans + +- [0001 — Foundation and registration](workplans/RCLK-WP-0001-foundation.md) +- [0002 — Contract and trust review](workplans/RCLK-WP-0002-contract-review.md) +- [0003 — Reference implementation](workplans/RCLK-WP-0003-reference-implementation.md) +- [0004 — Deployment and consumer adoption](workplans/RCLK-WP-0004-deployment-adoption.md) + +No installation is required to review these documents. Runtime commands and +examples will be added only with their implementation and verification. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..0414fb4 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,27 @@ +# Scope + +## Established in this seed + +Founding intent, draft v0.1 specification, threat/acceptance model, owner boundaries, +registration procedure and staged workplans. This is a specification repository +baseline: no runtime, time endpoint, SDK, signing key or deployment is delivered. + +## Planned v0.1 + +One monitored UTC authority on railiance01; authenticated fresh sample exchange; +process-local monotonic clock with uncertainty and explicit unusable states; +append-only timestamp attribution; one explicitly reviewed consumer pilot. + +## Deferred live work + +Distributed authority consensus, active/active failover, public NTP/NTS service, +long offline holdover and additional language clients remain RCLK-WP-0004 review +items. No high-availability, external timestamp notarization or production-security +adoption claim is made by the single-host pilot. + +## Authority boundary + +The local specification proposes a contract. RCLK-WP-0002 owns cross-repository +review before its security use. RCLK-WP-0003 owns reference implementation and +RCLK-WP-0004 owns admitted deployment and consumer evidence. Statehub indexes +source records; it is not a time source. Forgejo hosts records, not a UTC oracle. diff --git a/docs/ecosystem.md b/docs/ecosystem.md new file mode 100644 index 0000000..2e7b25a --- /dev/null +++ b/docs/ecosystem.md @@ -0,0 +1,53 @@ +# Ecosystem placement and registration + +Status: proposed owner relationships; registration is repository discovery, not +production admission or owner assent. + +| Concern | Existing owner / intended interaction | +| --- | --- | +| Railiance repository/runtime architecture | railiance-master; confirm source ownership and future rapp/reef packaging | +| Initial authority host | railiance-hosts / railiance-platform / reef-railiance; confirm operational responsibility and UTC discipline | +| Source/history | Coulomb organization on Forgejo, operated through railiance-forge; retain policy/source/evidence without assigning clock truth to Git dates | +| Shared discovery/work records | Repo Manager + primary Statehub; derive exact pushed source and stable identifiers | +| Security architecture | net-kingdom / gate-house; review layer role and trust/validity semantics | +| Identity and trust material | key-cape / secrets-engine / platform through existing admitted paths; no local credential broker | +| Decisions / human approvals | flex-auth (access-engine role) / approval-engine; retain their protocols and lifetime authority | +| Evidence | audit-core; distinguish receipt from event occurrence and bounded translation | +| Initial consumers | secrets-engine, ops-warden, intelligence-radar; explicitly review adoption rather than substitute local clocks silently | +| Operational monitoring | railiance-telemetry; quality/uncertainty/epoch metrics | + +## Source contracts to consume + +- `railiance-master/docs/repository-axes.md` +- `railiance-master/docs/repo-family-bootstrap-contract.md` +- `railiance-master/docs/netkingdom-security-consumption-contract.md` +- `net-kingdom/canon/standards/security-layer-model_v0.7.md` and the current + adopted successor/companion, verified at implementation time +- `the-custodian/canon/standards/repo-classification-standard_v1.0.md` +- `the-custodian/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md` +- `secrets-engine/docs/approval-consumption.md` +- `flex-auth/docs/decision-record-contract.md` + +Paths are ecosystem repository references, not vendored copies. Review current +versions and pin consumed contracts before implementation. This seed publishes +no speculative layer.yaml, PEP stance-map, capability readiness or runtime grants. +The role declaration is a named RCLK-WP-0002 task, not implied compliance. + +## Registration sequence + +1. Establish intent/specification and future work in source; validate identity, + links, workplan shape and clean Git state. Select unique RCLK-WP prefix. +2. Commit this baseline in the existing Coulomb Forgejo repository. +3. Register repository and workstation path through `statehub register --no-llm`, + domain infotech, topic custodian, explicit slug/prefix; preserve authored files. +4. Commit generated integration artifacts; run Repo Manager sync --push and require + applied/noop exact-commit evidence from primary/railiance01. +5. Send bounded owner handoffs to railiance-master, net-kingdom/gate-house, + repo-manager/the-custodian and initial consumers. Store returned message IDs. + Request prefix-index reservation and ownership review, without claiming assent. +6. Record final registration receipt in docs/registration.md. Foundation can finish + because implementation/review/deployment residuals already live in 0002–0004. + +The Coulomb source location and common discovery entry establish ecosystem +visibility. Railiance production admission and NetKingdom security adoption remain +unresolved until their owners return evidence under RCLK-WP-0002/0004. diff --git a/history/2026-09-14-genesis.md b/history/2026-09-14-genesis.md new file mode 100644 index 0000000..0727dd6 --- /dev/null +++ b/history/2026-09-14-genesis.md @@ -0,0 +1,21 @@ +# Genesis — 2026-09-14 + +Origin: intelligence-radar IR-WP-0004 OpenRouter native access investigation. +Windows host and WSL guest clocks differed; the corporate Windows host could not +discover its domain time peer. Human approvals existed but native execution still +had login/time prerequisites. This does not prove clock skew caused every login +failure. A single resync did not establish stable clock health. + +The operator reframed the problem: railiance01 and its Forgejo-centered estate +must support workstations attached to different corporate environments without +requiring their clocks to be synchronized to Railiance time. The proposed solution +separates UTC authority, process-local translation and causal/receipt provenance. + +The operator requested INTENT, specification and workplans before repository +registration. Source origin already exists as forgejo-remote:coulomb/railiance-clock. +Forgejo's timekeeper role is resolved here as durable source/policy/history, with +a separate monitored UTC service proposed on railiance01. + +This seed supersedes any assumption that corporate OS clock synchronization is +a universal Railiance application prerequisite. It does not change existing +consumer security contracts or unblock the paid trial by itself. diff --git a/specs/acceptance-v0.1.md b/specs/acceptance-v0.1.md new file mode 100644 index 0000000..f35f3ce --- /dev/null +++ b/specs/acceptance-v0.1.md @@ -0,0 +1,35 @@ +# Acceptance and threat model — draft v0.1 + +No tests below are claimed executed by the specification seed. IDs are future +behavioral acceptance obligations, not a count of implementation coverage. + +| ID | Scenario | Required evidence | +| --- | --- | --- | +| C01 | Corporate Windows/WSL wall clock ±5 minutes, wrong zone and wall-clock step | Process-local interval remains correct under supported bootstrap; OS settings unchanged | +| C02 | Asymmetric delay and deliberately delayed authentic response | True test time stays within computed interval or sample is refused; no symmetry assumption | +| C03 | Wrong key, nonce, authority, version, signature or modified uncertainty | Refusal before any consumer validity check | +| C04 | Replay, duplicate nonce, response after timeout/restart | Old response cannot establish a fresh anchor | +| C05 | Authority upstream outage, large dispersion, restart or UTC rollback | Explicit unusable/holdover policy; no unearned healthy state or rollback acceptance | +| C06 | Client reboot, suspend/resume, monotonic discontinuity and virtual clock drift | Old mapping invalidated; no frozen-clock lifetime extension | +| C07 | Expiry/not-before boundary overlaps uncertainty | Refresh/wait/refuse; entirely valid interval accepted; signed fields unchanged | +| C08 | Offline drift/sample-age budget exhausted | Protected use refuses; no wall-clock fallback | +| C09 | TLS bootstrap fails due to OS time; unknown/revoked authority key | No insecure transport or circular trust acceptance | +| C10 | Concurrent approval consume and delayed side effect | Existing CAS and action/lifetime binding still enforced by consumer | +| C11 | Local event before calibration or across clock step | Original retained, translation unknown unless supported by evidence | +| C12 | Two event intervals overlap / arrival order differs | No fabricated total occurrence ordering | +| C13 | Bad numeric units, nonfinite/overflow, malformed/oversized requests | Bounded parsing and stable refusal without sensitive output | +| C14 | Key rotation/revocation, stale trust cache and authority compromise drill | Adopted trust recovery evidenced; old samples cannot resurrect trust | +| C15 | Authority inaccessible/slow and sustained request load | Bounded resources and honest unavailable state; liveness distinct from usability | +| C16 | Consumer migration | Native positive plus wrong caller/owner/tenant/signature/expiry negatives; no wider access grant | + +Threats include compromised authority/upstream, network delay/replay, malicious +producer timestamps, privileged local clock manipulation and configuration rollback. +A fully compromised client process can falsify its own evidence; server-side owners +must not treat client-supplied time as authority. One-host deployment does not +provide Byzantine consensus. Host administrator trust and upstream error assumptions +must be stated with results. No microsecond-accuracy or universal offline guarantee. + +RCLK-WP-0002 reviews the matrix. RCLK-WP-0003 supplies fake-clock/property tests and +an isolated authority/client exercise. RCLK-WP-0004 supplies measured native evidence, +consumer acceptance and failure/recovery drills. Performance thresholds become +versioned, measured policies before production admission. diff --git a/specs/railiance-clock-v0.1.md b/specs/railiance-clock-v0.1.md new file mode 100644 index 0000000..e117fbc --- /dev/null +++ b/specs/railiance-clock-v0.1.md @@ -0,0 +1,200 @@ +# Railiance Clock specification — draft v0.1 + +Status: proposed protocol and consumer contract, 2026-09-14. Normative words +MUST/SHOULD describe the proposed acceptance contract; no runtime or cross-owner +adoption is implied. RCLK-WP-0002 must resolve the named review gates before +implementation is used for security decisions. + +## 1. Time domains + +- Authority UTC: railiance01's externally disciplined estimate with measured + health and conservative error bound. A platform-approved leap/UTC convention + must match upstreams and consumers; no silent mixture of smeared and unsmeared time. +- Local wall time: OS-reported timestamp, zone/offset and clock-domain identity; + descriptive only until attributed. A timezone conversion does not fix clock skew. +- Local monotonic time: elapsed-time measurement in one boot/process domain. +- Receipt time: the receiving service's time interval at ingestion, not occurrence. +- Causal order: explicit event IDs, sequence numbers and predecessor references; + overlapping time intervals are not a total order. + +UTC output uses RFC3339 with Z. Wire numerical units, precision and representation +must be fixed in the reviewed schema; integers/decimal strings are preferred over +unbounded binary float timestamps. Reject NaN, infinity, overflow and unknown units. + +## 2. Authority and deployment boundary + +The initial authority is one service on railiance01. It MUST obtain host clock +health through a reviewed adapter and expose upstream error/holdover state. It +MUST stop advertising usable bounded time if its clock is unsynchronized or its +error bound is unsupported. Multiple upstreams SHOULD be independent; a majority +of endpoints is not proof of independence or accuracy. + +A process restart, detected UTC step or authority continuity break invalidates +the previous mapping and changes an authority epoch. Epochs are continuity labels, +not a license for rollback. Clients must reacquire live evidence and enforce any +persisted rollback floor before using a new epoch. A claimed epoch change alone +cannot justify accepting arbitrarily older time. Exact rollback recovery is a +review gate; v0.1 must fail closed until reviewed recovery if continuity is unknown. + +Host synchronization/NTP configuration remains platform/host-owner work. Service +packaging, private exposure and production admission follow Railiance contracts. +A dedicated rapp/reef placement declaration is deferred until the runtime exists. + +## 3. Sample exchange proposal + +Candidate transport: bounded HTTPS POST `/v1/time-samples`, no redirects or cache. +The final endpoint/schema and signing profile are RCLK-WP-0002 deliverables. + +Request binds protocol version, a cryptographically random single-use nonce and +requested authority. It carries no bearer secrets or arbitrary caller URLs. +Client records monotonic send and receive instants itself; it MUST NOT trust its +wall clock to establish sample freshness. + +Response binds version, nonce, authority ID, epoch, key ID, server UTC receive and +send instants, upstream uncertainty, clock-quality state and maximum sample age. +All those fields MUST be authenticated as one statement with unambiguous encoding, +domain separation and algorithm/key allowlists. Select an established signing +format/profile during review; do not invent custom crypto or reuse a provider key. +The client maintains outstanding nonces and discards them after one response, +timeout or restart. A replay with a new locally invented receive time is refused. + +TLS authenticates transport using the supported trust store. A signature proves +who made the statement, not UTC truth; quality/uncertainty checks remain mandatory. +Pin authority and key scope through an admitted bootstrap; do not fetch an +untrusted key from the same response and thereby trust it. + +No-cache headers are defense in depth. Fresh nonces, elapsed-time bounds and +strict parsing provide freshness. Limit request/response size and sample rate; +serve health metadata without exposing host topology or secret material. + +## 4. Conservative sample interval + +Let m0/m1 be client monotonic send/receive values, R = m1 - m0; s2/s3 server +receive/send UTC values; and e the accepted server UTC error bound. +Reject negative/oversized R, backwards s2/s3, epoch changes during the request, +unusable quality and any unbounded error. Account for client timer error and +drift over the round trip in R's upper bound Rmax. + +At receipt, a deliberately conservative bound is: + + lower = s3 - e + upper = s3 + e + Rmax + +This assumes true time of server send is within s3 ± e and the response transit +cannot exceed the bounded whole exchange. It does NOT assume symmetric routes. +Do not subtract server processing time to tighten the bound without validating +its own clock/error assumptions. Midpoint estimation may be offered, but its +reported uncertainty must enclose the interval above. A delayed authentic response +widens the interval or times out; a nonce does not eliminate delay attacks. + +For elapsed monotonic d after receipt, propagate both bounds by d and widen by a +reviewed oscillator/timer drift bound rho*d plus resolution/scheduling error. +No generic drift coefficient is assumed proven on all WSL/VM hosts. Unsupported +monotonic behavior yields unusable state. Multiple samples may improve availability; +intersection is permitted only if all required continuity/error assumptions hold. +Contradictory intervals trigger reacquisition/diagnosis, not averaging away conflict. + +## 5. Client interface and lifecycle + +Proposed `Clock.read()` returns: + +- status: usable, holdover, unavailable or untrusted; +- lower_utc, upper_utc and optional midpoint; +- authority ID, epoch, policy version and sample ID; +- monotonic sample age, uncertainty and clock-domain identifier; +- reason code and next refresh requirement. + +Only usable or explicitly admitted bounded holdover can reach time checks. There +is no implicit fallback to OS wall time. `Clock.elapsed()` is separate from UTC. +The client exposes local-to-authority offset as an observation with capture window, +not a permanent global correction. Wall-clock steps do not move an established +monotonic mapping, but invalidate local-wall event translations across the step. + +v0.1 MUST invalidate on process restart, boot-domain change, suspend/resume, +monotonic discontinuity, sample expiry, authority revocation or unbounded drift. +Suspend detection/appropriate OS clock selection is a platform-specific proof +obligation. If undetectable, that platform is unsupported for offline/security +use; periodically querying is not evidence that suspension cannot occur. +Offline holdover is disabled for the first protected-use pilot unless the owner +accepts measured drift and maximum age. Authenticated but unhealthy is not usable. + +## 6. Validity and authorization consumers + +The clock supplies evidence, not an allow/deny authorization verdict. A reviewed +consumer can conservatively require lower_utc >= not_before and upper_utc < +expires_at, subject to its artifact's exact boundary semantics. Unknown/overlapping +bounds require refresh, bounded wait or refusal. Never alter signed fields, +backdate an observation, enlarge expiry, or resurrect a consumed approval. + +Approval Engine's atomic consume and execution-time checks remain authoritative. +A correct timestamp does not resolve replay, revocation or check-to-use races. +Bind the complete action using existing owner protocols and recheck validity at +the protected side effect. Prefer issuer/validator/executor colocated on disciplined +infrastructure; the workstation initiates an operation without impersonating the +server's time authority or decision identity. + +Current secrets-engine explicitly refuses shifted validation clocks. Adoption of +this interface requires a reviewed contract change plus native positive/negative +proof; this specification cannot be used as a local bypass. Third-party JWT, +TLS, browser, SSH and Kerberos validators are unaffected unless explicitly adapted. +Small artifact-specific leeway is separate from measurement uncertainty and must +not be counted twice or treated as unlimited drift tolerance. + +## 7. Trust bootstrap, offline use and failure + +An application clock cannot by itself repair TLS validation when OS time makes +certificates appear invalid. v0.1 requires functioning transport trust at bootstrap +or a separately admitted authenticated transport with its own validity handling. +Do not disable certificate dates/verification or use an HTTP Date header as authority. +Trust-key provisioning, expiry, rotation, revocation and freshness under wrong OS +time must be designed together. Static public keys without a bounded revocation +story do not solve offline trust. On unavailable revocation evidence, security +consumers follow their adopted fail-closed policy. + +Trusting a live service on one host creates a single failure/compromise domain. +A nonce protects against replay, not authority compromise or a dishonest upstream. +Compromise requires revocation and an explicit new trust admission; rollback of +service code alone is not recovery. A previous signed sample must not become fresh +because its verifier restarted. + +## 8. Event attribution + +Retain immutable original local timestamp, UTC offset/timezone when known, producer +identity, clock domain, event ID and local sequence/causal references. Append a +separate mapping record with sample reference, estimated UTC interval, translation +method/version and assumptions. Store receiver-assigned UTC interval separately. + +Mapping applies only within its evidenced clock domain and time interval. A sample +obtained now cannot calibrate an arbitrary event from yesterday. Uncalibrated events +remain unknown. Report intervals as overlapping when their order is uncertain. +Clock corrections append observations; do not rewrite originals or Git history. +Git author/committer dates remain provenance supplied under Git's own semantics. + +## 9. Operations and observability + +Metrics: authority quality, upstream dispersion/age, epoch changes, usable client +interval width, sample RTT/age, refresh failures and invalidation reasons. Logs +contain sample identifiers and sanitized reasons; no tokens, keys or callback URLs. +Separate service liveness from time usability and security-consumer admission. + +Failure exercises cover source outage, wrong source time, service restart, bad +signature/nonce, delayed responses, drift, suspend and authority rollback. Retain +measured thresholds and evidence in versioned policies. No production SLO or ppm +bound is claimed until RCLK-WP-0004 measurements justify it. + +## 10. Open decisions before implementation admission + +RCLK-WP-0002 owns transport/signature schema, trust bootstrap/revocation, leap +convention, authority health/error model, per-platform monotonic semantics, +consumer policy interface and exact NetKingdom role/PEP classification. +RCLK-WP-0003 implements the adopted contract in isolation; RCLK-WP-0004 owns +production placement, thresholds and native consumer migration. These are explicit +dependencies, not placeholders to bypass while shipping. + +## References + +- NTP timestamps/offset/delay: https://www.rfc-editor.org/rfc/rfc5905 +- JWT validity/leeway: https://www.rfc-editor.org/rfc/rfc7519 +- Authenticated NTP option for infrastructure review (not v0.1 wire protocol): https://www.rfc-editor.org/rfc/rfc8915 +- Corporate domain time: https://learn.microsoft.com/en-us/windows-server/networking/windows-time-service/how-the-windows-time-service-works +- Internal ownership links: ../docs/ecosystem.md. diff --git a/workplans/RCLK-WP-0001-foundation.md b/workplans/RCLK-WP-0001-foundation.md new file mode 100644 index 0000000..591fd89 --- /dev/null +++ b/workplans/RCLK-WP-0001-foundation.md @@ -0,0 +1,44 @@ +--- +id: RCLK-WP-0001 +type: workplan +title: "Establish intent, specification and ecosystem registration" +domain: infotech +repo: railiance-clock +status: active +owner: codex +topic_slug: custodian +created: "2026-09-14" +updated: "2026-09-14" +--- + +Seed requested by the operator. Runtime and cross-owner adoption are deliberately future work in RCLK-WP-0002–0004. + +## Establish founding intent and specification + +```task +id: RCLK-WP-0001-T01 +status: done +priority: high +``` + +Write INTENT, scope, draft sample/clock specification, threat model, behavioral acceptance matrix and ecosystem boundary. Validate document links and workplan shape before registration. + +## Establish staged implementation and adoption work + +```task +id: RCLK-WP-0001-T02 +status: done +priority: high +``` + +Create live 0002–0004 workplans with acceptance gates and dependencies. No unfinished implementation is hidden in a finished foundation plan. + +## Register and verify ecosystem discovery + +```task +id: RCLK-WP-0001-T03 +status: progress +priority: high +``` + +Register tooling/infotech repository and workstation path after baseline commit; synchronize deterministic IDs and exact pushed commit on primary/railiance01. Record repo identity and receipt. Send owner handoffs and prefix reservation request; pending assent remains in 0002. diff --git a/workplans/RCLK-WP-0002-contract-review.md b/workplans/RCLK-WP-0002-contract-review.md new file mode 100644 index 0000000..acedc11 --- /dev/null +++ b/workplans/RCLK-WP-0002-contract-review.md @@ -0,0 +1,56 @@ +--- +id: RCLK-WP-0002 +type: workplan +title: "Review time authority, trust and consumer contracts" +domain: infotech +repo: railiance-clock +status: ready +owner: codex +topic_slug: custodian +created: "2026-09-14" +updated: "2026-09-14" +depends_on_workplans: + - RCLK-WP-0001 +--- + +Ready to perform review of the completed draft, not ready for production security adoption. Resolve every cross-owner decision before accepting implementation as normative. + +## Confirm ecosystem ownership and security role + +```task +id: RCLK-WP-0002-T01 +status: todo +priority: high +``` + +Obtain Railiance architecture and NetKingdom/gate-house review. Resolve authority host operation, Forgejo evidence role, source/runtime packaging and time-provider layer/PEP classification. Publish adopted role declaration only after review. Confirm RCLK-WP prefix ownership. + +## Specify authenticated samples and trust lifecycle + +```task +id: RCLK-WP-0002-T02 +status: todo +priority: high +``` + +Choose established signing profile, canonical encoding and wire schema; trust bootstrap, key distribution/rotation/revocation, replay/nonce scope, authority epoch and rollback recovery. Pin upstream UTC/leap convention and defend delayed authentic samples. Satisfy C02–C05/C09/C14. + +## Specify measured clock bounds and platform lifecycle + +```task +id: RCLK-WP-0002-T03 +status: todo +priority: high +``` + +Review interval arithmetic with explicit timer/upstream assumptions, drift/age policies and unsupported-platform behavior. Define Windows/Linux/WSL suspend/reboot detection and telemetry. No guessed ppm or offline lifetime as proven policy. Satisfy C01/C06/C08/C13/C15. + +## Adopt consumer and audit time semantics + +```task +id: RCLK-WP-0002-T04 +status: todo +priority: high +``` + +Agree with flex-auth, approval-engine, secrets-engine and audit-core on clock injection/server-side execution, validity boundaries, CAS/check-to-use semantics and event attribution. Preserve current refusal until reviewed replacement. Pin accepted contract versions and update acceptance matrix C07/C10–C12/C16. Record disagreements as decisions/live work. diff --git a/workplans/RCLK-WP-0003-reference-implementation.md b/workplans/RCLK-WP-0003-reference-implementation.md new file mode 100644 index 0000000..38b3747 --- /dev/null +++ b/workplans/RCLK-WP-0003-reference-implementation.md @@ -0,0 +1,46 @@ +--- +id: RCLK-WP-0003 +type: workplan +title: "Implement isolated authority and application clock" +domain: infotech +repo: railiance-clock +status: proposed +owner: codex +topic_slug: custodian +created: "2026-09-14" +updated: "2026-09-14" +depends_on_workplans: + - RCLK-WP-0002 +--- + +Implement only the reviewed contract. Runtime language selection, API schema and dependency policy follow RCLK-WP-0002; no live secrets needed for fake-clock development. + +## Implement authority sample and health adapter + +```task +id: RCLK-WP-0003-T01 +status: wait +priority: high +``` + +Depends on 0002 adopted sample/trust/UTC contract. Implement bounded sample exchange, nonce binding, health/error state and epoch handling with disposable signing keys. Verify C02–C05/C13–C15. + +## Implement application clock and attribution interface + +```task +id: RCLK-WP-0003-T02 +status: wait +priority: high +``` + +Depends on adopted interval/platform contract. Provide explicit quality states, monotonic mapping, sample-age policy, restart/suspend invalidation and immutable event attribution. Verify C01/C06–C09/C11/C12. + +## Prove isolated consumer integration and package review + +```task +id: RCLK-WP-0003-T03 +status: wait +priority: high +``` + +Run deterministic boundary/property tests plus adversarial delay/replay and real platform lifecycle probes. Demonstrate +/− local clock skew with no OS changes. Preserve consumer approval/CAS failures with fixtures; publish dependency/SBOM and reproducible build evidence. No native production claim from synthetic fixtures. diff --git a/workplans/RCLK-WP-0004-deployment-adoption.md b/workplans/RCLK-WP-0004-deployment-adoption.md new file mode 100644 index 0000000..d722665 --- /dev/null +++ b/workplans/RCLK-WP-0004-deployment-adoption.md @@ -0,0 +1,56 @@ +--- +id: RCLK-WP-0004 +type: workplan +title: "Admit railiance01 pilot and migrate one consumer" +domain: infotech +repo: railiance-clock +status: proposed +owner: codex +topic_slug: custodian +created: "2026-09-14" +updated: "2026-09-14" +depends_on_workplans: + - RCLK-WP-0003 +--- + +Native operation is a separate production-admission decision. This plan also owns explicit later-scale scope so foundation has no untracked residuals. + +## Prepare private placement and trust custody + +```task +id: RCLK-WP-0004-T01 +status: wait +priority: high +``` + +Depends on 0002/0003. Obtain reviewed rapp/reef placement, host UTC health/error evidence, private exposure, resource budget, signing trust custody and monitoring. Existing owner authorities apply; repository registration grants none of these. + +## Measure and verify the native authority/client pilot + +```task +id: RCLK-WP-0004-T02 +status: wait +priority: high +``` + +Exercise skewed corporate workstation without OS changes, bootstrap limitations, source outage, restart/rollback, delayed samples and suspend/resume. Measure interval coverage/width, latency and holdover; agree versioned thresholds. Verify cleanup, rollback and authority-key revocation. Retain audit evidence, not secrets. + +## Migrate one explicitly admitted security consumer + +```task +id: RCLK-WP-0004-T03 +status: wait +priority: high +``` + +Choose server-side native execution where feasible. With consumer-owner approval, test correct use and wrong-caller/owner/tenant/signature/expiry negatives, uncertain boundaries and concurrent consume. Update the consumer contract before replacing its clock. IR-WP-0004/SECRETS-WP-0010 remain independently open until their own return gates pass. + +## Review operational scope and hand off later capabilities + +```task +id: RCLK-WP-0004-T04 +status: wait +priority: high +``` + +Review availability/SLO, independent backup authorities, long offline holdover, additional languages and optional authenticated NTP/NTS infrastructure offering. Keep single-host limitations explicit. Any actionable work not delivered becomes live successor records before this plan finishes.