Repository navigation
Four service pages arrive, with four citations corrected that resolved to a plausible wrong line and one licence claim the LICENSE file contradicts - #1
Merged
Conversation
added 2 commits
September 13, 2026 15:31
…olved to a plausible wrong line and one licence claim the LICENSE file contradicts These pages were written in heliograph-io/heliograph-cloud, private, because this repository did not exist. They are public because the security page's whole argument is that each claim is checkable without trusting us, and a security page whose own source is private and takes no corrections is weaker for no gain. Every citation was re-read against fresh clones of heliograph 59d43ef and heliograph-relay 3756eb7 before publishing. citecheck.py resolved all 99 and exited zero, which is the point: not one of these was a broken link. Six had drifted and four landed on a neighbouring line about the same subject, which reads as correct. The worst was site/content/relay.md:42-43, cited twice on the boundary page as the source for "the fingerprint comparison that pairs two ends happens out of band between two people". It now resolves to "### Free, with limits, and not a promise for ever", a paragraph about relay pricing. The real lines are :96-97. That clause is the load-bearing one in the whole broker argument - a broker that could substitute a key during pairing would be fatal rather than merely opaque - so a reviewer following the citation would have found pricing copy under it. The others: heliograph-relay/relay.go:49 -> :57 for the `Body []byte` comment; authlease_test.go:131 -> :149 and :163 -> :181; caplib.sh:372-380 -> :385-393 twice on the threat model; worker.ts:250 -> :1128-1135. One test name was simply wrong and never existed: TestASignedLeaseIsStillValidatedWithNoNetworkCall is TestALeaseIsValidatedWithNoNetworkCall at authlease_test.go:86. The threat model and the security page contradicted each other about the trust root, and they are published side by side. The threat model said "owed, none, always today. It is a discipline you cannot check" and cited internal/wire/status.go:15-30 as having no field for the trusted set; the security page said it is a mechanism in four parts. The security page is right and the threat model was reading a stale range: status.go:41-43 carries the digest, the serial and the members, apply.go:116 verifies a change document against the set as it stands, apply.go:22 keeps the anchor changeable only on the machine, authorship_test.go:69 proves the control plane cannot author a change. The row is now conditional rather than holds, for two reasons stated on the page: the mechanism makes an unauthorised key detectable and nothing can make anybody look, and the third criterion the page itself set - an event per key rather than configuration drift - landed as a serial to compare rather than as a notification. The boundary page led with "the CLI, the station, the wire format, the crypto and the interfaces are open source under Apache 2.0" in the present tense. heliograph/LICENSE:1 and heliograph-relay/LICENSE:1 both say "MIT License" and both READMEs carry an MIT badge. Published as written, that is a false claim on a page whose entire subject is licensing, and it is the failure heliograph-io/heliograph-cloud#79 is the record of. The licence set now reads as what the announcement applies, with the MIT citations at the top of the page, and the two things true today are marked: the old MIT grant, which cannot be withdrawn, and this documentation's own CC BY 4.0. Cost: the boundary page is weaker to read until the licence announcement ships, which is correct, because a reader who opens one file finds it says MIT. The three claims these pages carry are unchanged and were checked line by line against the source they came from. The cloud reads your logs in plaintext, stated at the top of the security page beside the mitigations rather than in a footnote. Reproducible builds are stated at exactly half: both implementations build reproducibly and CI proves it per pull request, nothing is signed, nothing is deployed, and no deployed hash has ever been compared to a build. The no-cryptography sentence is retired with its reasoning rather than its summary, including that a public key is not a secret, that HMAC-SHA256 would have passed the old rule and was rejected for being symmetric because a relay able to verify could mint, that the narrowing is held by the linker reading the built binary's symbol table, and what it cost the reader, which is that one grep no longer confirms it. Signed-off-by: Daniel Grimes <dan@dcgnet.co.uk>
…epository holds its wording and this repository has nowhere to run it Reverted from this pull request before merge. The move was scoped as four pages and the directory held five, so the fifth was included on the operating model's test: it describes a trust boundary, names no price, tier, allowance, customer or live topology, and the reason it had been held - that it describes a service nobody can buy - had already been overruled for the security page. That reasoning was right about the content and wrong about the cost, and grepping for what referenced the directory is what found it. `cloud/test/transport-capability-document.test.ts:14` imports the page as raw text and asserts six things about it: that it contains "You do not get gone-quiet alerting", that the limit appears BEFORE the list of what the beacon path does give you, that the answer is in the summary table and not only in the prose, that "no key material whatsoever" is never written without "what we receive is plaintext" within eight paragraphs of it, that it says absence is not proof of absence, and that it never tells a reader the service cannot see their logs. That last pair is the point. The test's own comment records why it exists: "A page carrying the first sentence without the second is the overclaim an adversarial review caught in this repository on 2026-09-12." Moving the page here deletes that test, because this repository has no test runner, no npm and no vitest. The guard would be gone and the page it guards would be public. The three options were: port six assertions to shell in this repository's style.yml tonight, unreviewed, and risk a weaker guard replacing a working one; delete the guard and publish anyway; or leave the page where its guard is and say so. The third is the only one that does not trade a working check for a published page. Cost: one page of the five is still private, in a repository whose own operating model says it should not be. That is a real cost and it is smaller than the one it avoids. The README says the page is owed and why, rather than leaving a reader to notice the gap. Signed-off-by: Daniel Grimes <dan@dcgnet.co.uk>
grinidx
changed the title
Contributor
Author
|
Correction to the section above headed "The five pages, not four": it is four, and the fifth is reverted from this branch. The reasoning there was right about the content and wrong about the cost. Grepping for what referenced the directory is what found it: This repository has no test runner, no npm and no vitest. Moving the page here deletes that guard. The choice was to port six assertions to shell tonight and risk a weaker guard replacing a working one, to delete the guard and publish anyway, or to leave the page where its guard is. The third is the only one that does not trade a working check for a published page. So four pages arrive. The README says the fifth is owed and why, rather than leaving a reader to notice the gap. Everything else in the body above stands, including every citation correction, both of which applied to pages that are in this pull request. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The public documentation for heliograph cloud. Written in
heliograph-io/heliograph-cloud, private, because this repository did not exist; public now because the security page's whole argument is that each claim is checkable without trusting us, and a security page whose own source is private and takes no corrections is weaker for no gain.Advances heliograph-io/heliograph-cloud#43, #44, #22, #56 and #60. It closes none of them: each still has boxes only a person can tick, and
docs.heliograph.ioserves nothing, because nothing can be deployed without a Cloudflare login.What arrived
content/boundary.mdcontent/security.mdcontent/threat-model.mdcontent/what-this-record-establishes.mdcontent/what-each-transport-gives-you.mdPlus
README.md,CONTRIBUTING.md, the CC BY 4.0 legal code, and two workflows, which landed in the bootstrap commit onmain.The five pages, not four
The move was scoped as four pages. The directory held five.
what-each-transport-gives-you.mdwas the fifth and it moves too, on the operating model's own test: it describes a trust boundary, it names no price, tier, allowance, customer or live topology, and the reason it had been held back - that it describes a service nobody can buy yet - is the same reason that was already overruled forsecurity.md. Leaving one page behind in a directory that is being replaced by a pointer needed a reason and there was not one.Citations: all 99 resolve, and six of them were wrong
tools/citecheck.pyin the private repository was run against fresh clones ofheliograph59d43efandheliograph-relay3756eb7, before and after.That exit code is the trap, not the reassurance. Every citation resolved to a line both times. Six had drifted, and four of those landed on a neighbouring line about the same subject, which reads as correct to anybody who follows it.
site/content/relay.md:42-43(twice, boundary page)### Free, with limits, and not a promise for ever:96-97heliograph-relay/relay.go:49:57, theBody []bytelineheliograph-relay/authlease_test.go:131}:149heliograph-relay/authlease_test.go:163:181station/bash/caplib.sh:372-380,:375(threat model):385-393,:388heliograph-relay/edge/src/worker.ts:250The first one is the one that mattered. It was the source for "the fingerprint comparison that pairs two ends happens out of band between two people", which is the load-bearing clause in the entire broker argument, because a broker that could substitute a key during pairing would be fatal rather than merely opaque. It pointed at a paragraph about relay pricing.
One test name was not drift, it was wrong and never existed:
TestASignedLeaseIsStillValidatedWithNoNetworkCall. The test isTestALeaseIsValidatedWithNoNetworkCallatheliograph-relay/authlease_test.go:86. Every other named test was checked to exist bygrep -rn "func Test...", and all twelve do.Smaller range corrections:
seal.go:301-305to:302-307,verify.go:55to:51-57,server.go:126-147to:126-146,run.sh:270-290to:270-288.Two pages disagreed with each other, and they publish side by side
The threat model's trust-root row said owed, mechanism none, fails "always, today. It is a discipline you cannot check", and cited
internal/wire/status.go:15-30as having no field for the trusted set. The security page said the same constraint is a mechanism in four parts.The security page is right. The threat model was reading a stale range: the struct now runs to
internal/wire/status.go:45, and:41-43carries the digest, the serial and name-to-fingerprint pairs. Verified in the clone:The row is now conditional, not holds, and the page says why in two parts rather than one. The mechanism makes an unauthorised key detectable and nothing on our side can make anybody read the published set. And the third criterion the page itself had set - a change visible as an event per key rather than as configuration drift - landed only partly: a reader gets a serial that advances and a member list that differs, so a change is found by comparison rather than delivered as a notification. The page says that rather than rounding it up. The tally line moved with it: four conditional, one owed, where it read three and two.
The boundary page claimed a licence that the LICENSE file contradicts
It opened with "The CLI, the station, the wire format, the crypto and the interfaces are open source under Apache 2.0, permanently", present tense.
Published as written that is a false claim on a page whose entire subject is licensing, and the exact failure heliograph-io/heliograph-cloud#79 is the record of. The page now states the set as what the announcement applies, carries those citations at the top under "Read the tense before you read the table", and marks the two things that are true today: the old MIT grant, which cannot be withdrawn, and this documentation's own CC BY 4.0, which is in this repository.
What it costs: the boundary page is weaker to read until the licence announcement ships. That is correct. A reader who opens one file finds it says MIT, and a page that had told them otherwise would have spent the trust it exists to protect.
The three claims, carried intact
Checked line by line rather than assumed.
The cloud reads your logs.
content/security.mdline 7 is the first section heading on the page: "It reads your logs in plaintext", followed by "That is the trade. It is at the top of this page rather than in a footnote, because it is the thing you are actually deciding about." The mitigations follow it and each is weighted:REDACTis "a safety net, not a guarantee", self-hosting the relay "does not remove the archive", customer-managed keys are "not committed and there is no date".Reproducible builds at exactly half. Both implementations build reproducibly, CI proves it per pull request,
GET /healthreports the version and the SHA-256 of the artefact serving (heliograph-relay/server.go:44-56). And then: nothing is signed because no tag has been pushed, nothing is deployed so no running hash has been compared to a build, and a Worker cannot read its own code so its hash is a number the deploy workflow computed. The sentence the page permits is "the bundle a tag produces is a number you can check, and the deployment says it is serving that number", never "the relay is provably the source you read".The no-cryptography sentence, retired with its reasoning. All of it survived the move: that the relay now verifies Ed25519 lease signatures; that a public key is not a secret, so an attacker who takes everything the relay holds gets a key that checks signatures and makes none; that HMAC-SHA256 would have passed the old rule as written and was rejected for being symmetric, because a relay able to verify would be able to mint; that the narrowing is held by the linker rather than by a comment, via
TestTheRelayBinaryCannotSignALeasereading the built binary's symbol table; and what it cost the reader, which is that the old sentence can no longer be confirmed with onegrep.The checks, each watched failing first
.github/workflows/style.ymland.github/workflows/dco.ymllanded in the bootstrap commit. Every assertion was broken on purpose and watched catch it before being kept.Smoke test
The rendered pages rather than the markdown, which is what the brief asks for on a docs change. The site generator does not read this repository yet - that is the
upstream: heliographhalf of heliograph-io/heliograph-cloud#56 - so the render checked is GitHub's, which is what a reader gets today:content/security.mdlinksthreat-model.mdandwhat-this-record-establishes.md,content/boundary.mdlinkssecurity.md, all same-directory and all presentcontent/*.mdis linked fromREADME.md, which is now a CI step rather than a claimWhat is deliberately not here
The design specs stay private.
docs/specs/is design working rather than the answer, and2026-09-12-cloud-threat-model-design.mdis the working behindthreat-model.md.No private issue is cited by bare number anywhere in
content/. Checked with a grep across all five pages: zero hits. A bare#43on a public page resolves to this repository's issue 43, which is a different issue or none, and that reads as concealment rather than as a reference. The one place the private tracker is named, it is named in full asheliograph-io/heliograph-cloud#NN, which a reader cannot follow and which is correct.Nothing about pricing, tiers, allowances, customers, pilots, live topology or an unfixed weakness.
The human step
docs.heliograph.ioserves nothing. It cannot:wrangler whoamion this machine reports not authenticated, there is no Cloudflare account, and the site generator has to learn to build one site from two content repositories first. Both halves are recorded on heliograph-io/heliograph-cloud#56 and #147.