Repository navigation
docs(TC-887): at-rest interfaces in the repo, one generation ceiling, harness follow-ups - #331
Merged
Merged
Conversation
…ceiling docs/at-rest/INTERFACES.md carries the normative TCE1 format, the TCE2 versioning rule, the fail-closed and header-trust notes and the KV storage decisions; the module docs now point to it. PayloadEncoding reads 2..=9 as an unsupported later generation (the range the header can express) and anything above 9 as invalid.
Review notes on #324 (N2, N3): - Every blob that must hold a plaintext (each KV put's objects in total, every SQL payload and delta) must be at least that large: TCE1 never shrinks data, so a smaller blob is compressed, not sealed. Catches xz/bz2-style compression of a salted WAL delta that the shared-run and compressibility checks miss. - KV cross-space comparison requires equal object counts per put and compares every pair, instead of zipping objects sorted by name. - The offline selftest also proves a salted deflate-9 blob is flagged by the floor and sealed-like blobs pass it.
Review notes on #324 (N1, N4): - TC887_AT_REST_ESCROW_NONE=true|false maps to S1's boolean TINYCLOUD_AT_REST__ESCROW_NONE (replaces the scalar ESCROW, which S1's deny_unknown_fields section rejects); mode is validated as off|encrypt|strict. State schema v3. - test --expect takes green|red or kv=green|red,sql=green|red. Each check runs alone and is judged on its own; exit 0 only if all match, 3 per mismatch (KV/SQL-specific UNEXPECTEDLY PASSED / still RED), 4 if any check errored. With mode encrypt|strict, test red defaults to kv=green,sql=red (S3 before S4); CI stays --expect red. - README: SIGKILL of up can't be trapped; run down STATE.
Contributor
Author
|
APPROVE: see TC-887 (head efe1f85) |
This was referenced Oct 17, 2026
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
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.
Part of TC-887 (encryption at rest): follow-ups to #322 and #324. Nothing here changes node behaviour.
Includes
126adcb(theworkflow_dispatchtrigger), which is also #330 on its own. Whichever merges first, the other picks it up as a no-op.What changed
docs/at-rest/INTERFACES.md(new): the normative interface and format fortinycloud_core::at_restand sealed KV storage. It covers the key types,DataKeyProvider, the envelope API, the TCE1 format, the TCE2 versioning rule, legacy-vs-sealed detection, notes for storage callers (header fields are unverified until a segment decrypts;Unsupportedis unauthenticated and must fail closed), accepted key-material residuals, and the KV storage decisions. Theenvelope.rsandprovider.rsdocs now point to it.PayloadEncoding::from_columnreads 2..=9 as an unsupported later generation, the same range the header's ASCII digit can express. 0, negative values and anything above 9 are invalid. Previously 10..=255 also mapped toUnsupported.scripts/at-rest-harness/,tests/at_rest_harness.rs):TC887_AT_REST_ESCROW_NONE=true|false→TINYCLOUD_AT_REST__ESCROW_NONE, the node's real config name, replacing the scalar…__ESCROW. Mode and escrow values are validated before anything starts.payload/delta_payload) must be at least that large, because TCE1 never shrinks data. This catches a compress-only transform.test red --expect kv=green,sql=red STATE(green/redstill mean both). Each check is judged and reported separately; exit 0 = all matched, 3 = a per-check mismatch, 4 = errored. WithTC887_AT_REST_MODE=encrypt|strictthe default iskv=green,sql=red. CI still runs--expect red..github/workflows/rust.yml: theworkflow_dispatchtrigger, and a comment in the at-rest-harness job.How it's tested
cargo test -p tinycloud-core --lib at_rest: 30 pass. ThePayloadEncodingtest covers 2, 3, 9 →Unsupportedand 0, −1, 10, 255, 256, i16 limits → invalid.cargo test -p tinycloud-node --test at_rest_harness: the offline self-test passes. It now also shows that a salted deflate-9 of the 64 KiB value is caught by the size floor, while sealed-like blobs pass.up→test green(0) →test red --expect red(0, "RED as expected": 20 KV + 16 SQL findings) →--expect kv=red,sql=red(0) →--expect kv=green,sql=red(3, KV-specific "still RED"; SQL as expected) →down --purge(0, nothing left running). Invalid--expect, mode or escrow values exit 2. WithMODE=encryptandESCROW_NONE=true, node.env carries both variables andtest reddefaults tokv=green,sql=red.cargo fmt --all -- --check,cargo clippy -p tinycloud-node --test at_rest_harness -- -D warnings,bash -n: clean. The workflow YAML parses (triggers: push, pull_request, workflow_dispatch).