Skip to content

docs: B13 says what a receiver enforces; doctor names read grants - #97

Open
karauda wants to merge 6 commits into
mainfrom
feat/s24-e
Open

karauda wants to merge 6 commits into
mainfrom
feat/s24-e

Conversation

@karauda

@karauda karauda commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Reading a plane is not a roster capability. The health socket answers a peer by its uid against health.socket_uid, and a file is read by whoever its modes let read it. The roster's read level parses and is reserved: it grants nothing yet. This change says so where an operator looks, and adds a table of every signed file a plane takes in, with the check and the test behind each.

  • doctor's trust line names every file the signed start checked, the roster among them, from the same list the start uses (signedStartFiles, extracted from checkSignedStart with no change in behaviour). When the roster holds read grants, it adds that they grant nothing yet.
  • docs/contracts.md, new section "Signed files and their project checks": one row per receiver, giving what it takes, the tenant and project it holds the file to, the function that checks it, and the test that refuses another project's.
    • Answers and pauses are held to tenant_id.
    • Runs, routes and stops are held to the listener's tenant (listener.principal.tenant_id where set). Where the two differ, an operator needs a grant over each.
    • The page's covers names every cited file, so a change to one of those checks flags it.
  • A docscheck test fails when a cited test, file or function does not exist, or the table is empty. Its negative controls cover a missing test, a missing function or file, no rows and no table.
  • B13 in docs/backlog.md keeps only open work: reads and operations of another project refused at every receiver, a stop naming its agent or principal scope, and adversarial tests of two users and overlapping runs.
  • ADR-0071 is amended for the reserved read level. The status trust row and CHANGELOG are updated.

Verified:

  • Each new test failed before the change.
  • Each of these mutants fails a test: the read level counted as operate, the old fixed text, runs.dir always named, and each docscheck existence check turned off.
  • Test binaries for cmd/guardana-gateway (whole), internal/docscheck, internal/console, internal/core/approval, internal/metrics and internal/core.
  • make vet, check-imports, check-brand, check-sizes, golangci-lint.

Not covered:

  • The docscheck test would count a cited test that sits in a build-excluded file or inside a comment; no cited test is in one today.
  • The read-grant count is tested with one grant per key, so counting keys instead of grants would pass.

docs-impact: 0 uncovered surfaces; frozen paths ADR-0071, contracts.md (the new section) and status. Suspect pages read; none made false.

Under the signed authority the plane now refuses to start when its own
account can write trust.roster or a directory on its path, as it already
does for the configuration, the root key, the pause file, the route, the
stop list and the run records. A test classifies every file key the signed
authority reads as checked or plane-writable, so a new one cannot be missed.

The operator commands that judge with --roster say on standard error which
roster they judged, its serial and its expiry, before they sign or list.
Doctor's signed route and stop list reads get a test, and stops init
--carry runs as a command in a test.

Signed-off-by: Konrad Karauda <konrad@karauda.com>
…he seam

The plane's account still writes trust.floor_dir: raising the roster floor
withholds a newer roster until the held one expires. The pages now say
so, and that what the placement check adds is that the plane's account can
no longer put an older roster in place.

Doctor's signed stop list read is a method with its own test run with the
plane-owned switch off, so a doctor that takes a list the plane's own
account owns fails a test. react's guard against the plane's account is a
variable, so a test on one account reaches the roster line it prints. The
classification test also runs over a minimal signed tree, so a check that
depends on another key being set fails it.

Signed-off-by: Konrad Karauda <konrad@karauda.com>
…grant

Reading is not a roster capability: the health socket answers a peer by
its uid against health.socket_uid, and a file is read by whoever its
modes let read it. The roster's read level parses and is reserved; it
grants nothing yet. doctor now says so when a roster holds a read grant,
and its trust line names every file the signed start checked, from the
same list the start uses, the roster included.

B13 keeps only open work: cross-project reads and operations refused at
every receiver, a stop naming its agent or principal scope, and
adversarial tests of two users and overlapping runs.

docs/contracts.md gains a table of every signed file and answer a plane
takes in, with its tenant and project check and the test that pins it;
a docscheck test fails when a cited test, file or function does not
exist, or the table is empty.

ADR-0071 is amended for the reserved read level.

Signed-off-by: Konrad Karauda <konrad@karauda.com>
Answers and pauses are judged under tenant_id; runs, routes and stops
under the listener's tenant, which is listener.principal.tenant_id where
set. The table names it per row and says an operator needs a grant over
each tenant where the two differ. The route rows cite the route's tenant
check, the floors are named as unsigned state, and the page covers every
file the table cites, so changing one of those checks flags it.

Signed-off-by: Konrad Karauda <konrad@karauda.com>
Signed-off-by: Konrad Karauda <konrad@karauda.com>
@karauda
karauda requested a review from a team November 10, 2026 21:11
@karauda
karauda requested a review from a team as a code owner November 10, 2026 21:11
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Failed ❌

View logs ↗
ba439cb 2026-11-11T07:21:22.625Z View logs ↗
  • Build: Failed ❌

View logs ↗
72aa943 2026-11-10T21:11:41.427Z View logs ↗

Signed-off-by: Konrad Karauda <konrad@karauda.com>
karauda added a commit that referenced this pull request Nov 11, 2026
GO-2026-6859 (a race on `MaxBytesReader`'s header that can crash an HTTP/1 server) is fixed in go1.27.4. `govulncheck` finds it reachable from the plane's HTTP servers under go1.27.3, so the quality gate and "Known Go vulnerabilities" fail on every pull request (first seen on #97). Both modules move to Go 1.27.4, and the pages that name the toolchain follow: README, the filesystem-server guide and status. CHANGELOG gets a Security line.

Verified:
- `go tool govulncheck ./...` under go1.27.4: no vulnerabilities, both in the root module and in `examples/evidence-report`.
- Negative control: under go1.27.3 on main, the same scan reports GO-2026-6859 (exit 3).
- Test binaries for `internal/docscheck`, `internal/console`, `internal/core/approval`, `internal/metrics` and `internal/core` under go1.27.4.
- `make vet`, `check-imports`, `check-brand`, `check-sizes`, golangci-lint, docs-gen.

The whole suite under go1.27.4 is this pull request's quality gate.

Signed-off-by: Konrad Karauda <konrad@karauda.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant