Correct the security claims in docs and comments, and record the accepted risks (closes #171)
check / check (pull_request) Successful in 2m32s

Docs and comments only; no behaviour change. Corrects ten overclaims the
security review found: snapshot names are hashed but the hash uses no
secret, so a guessed hostname and name can be confirmed; a blob is named
by hex(SHA256(SHA256(uncompressed contents))), stated once in
docs/REPOSTRUCTURE.md and referenced elsewhere; double hashing does not
hide known content (blob packing does); age uses ChaCha20-Poly1305, not
XChaCha20; encryption is required, not optional; a snapshot is marked
complete before its metadata is uploaded; the export comment now matches
its only caller; deep verify detects corruption, not authorship; adding a
recipient does not reach existing data; restore examples target a
user-owned directory.

Adds an Accepted Risks subsection under Security Considerations with the
seven documented risks, cross-referenced from the README.

Model: opus-4-8
This commit is contained in:
2026-09-22 17:04:01 +00:00
parent c3bec7d3aa
commit ae06beb2c4
14 changed files with 108 additions and 67 deletions
+2 -2
View File
@@ -90,7 +90,7 @@ Stores information about packed, compressed, and encrypted blob files.
**Columns:**
- `id` (TEXT PRIMARY KEY) - UUID assigned when blob creation starts
- `blob_hash` (TEXT UNIQUE) - SHA256 hash of final blob (NULL until finalized)
- `blob_hash` (TEXT UNIQUE) - `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (NULL until finalized); see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs-directory-blobs)
- `created_ts` (INTEGER NOT NULL) - Creation timestamp
- `finished_ts` (INTEGER) - Finalization timestamp (NULL if in progress)
- `uncompressed_size` (INTEGER NOT NULL DEFAULT 0) - Total size of chunks before compression
@@ -216,7 +216,7 @@ After a snapshot is completed:
5. Upload to S3 as `metadata/{remote-key}/db.zst.age`
6. Generate blob manifest and upload as `metadata/{remote-key}/manifest.json.zst`
The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so the ID is never written to the store in plaintext; see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation).
The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so the ID is never written to the store in plaintext. The hash uses no secret, so a guessed hostname and snapshot name can still be confirmed against a listing; see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation) and its [Accepted Risks](REPOSTRUCTURE.md#accepted-risks).
### 4. Restore Process