docs(egress): state truncation/deletion of the ledger are out of scope

gstack-egress verify catches in-place edits, reordering, and mid-chain deletion
(the hash chain breaks) but not tail-truncation, whole-file re-fabrication, or
deletion — a same-user local actor who owns the ledger defeats those and verify
still exits 0. That matches the stated threat model (forensic observability, not
an exfiltration control). Document it in the header threat model and the usage
text rather than adding a count-sidecar, which would false-positive on every
legitimate rotation and barely raise the bar. Head-anchoring stays the tracked
rotation TODO in lib/egress-receipt.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-08-16 10:14:33 -07:00
co-authored by Claude Fable 5
parent 33a55562f7
commit b029fbf80f
+12 -1
View File
@@ -9,6 +9,13 @@
*
* THREAT MODEL: the ledger is forensic observability — it records ATTEMPTED
* egress so accidents are auditable; it is not an exfiltration control.
* `verify` detects in-place edits, reordering, and mid-chain deletion (the
* chain breaks). It does NOT detect tail-truncation, whole-file re-fabrication,
* or deletion of the ledger — a local actor with write access to the ledger can
* do those and `verify` still exits 0. That is by design: guarding against the
* same-machine same-user actor who owns the file is out of scope for a forensic
* log. Head-anchoring (a separate rotation-aware genesis chain) is tracked at
* lib/egress-receipt.ts (rotation TODO), not implemented here.
*
* The ledger is written by lib/egress-receipt.ts at every enumerated sink
* (see test/egress-receipt-wiring.test.ts for the pinned list).
@@ -48,7 +55,11 @@ function usage(message: string): never {
process.stderr.write(
'Usage: gstack-egress list [--since <ISO>] [--host <host>] [--sink <sink>] [--json]\n' +
' gstack-egress verify [--json]\n' +
' gstack-egress grants [--json]\n',
' gstack-egress grants [--json]\n' +
'\n' +
'verify detects edits/reordering/mid-chain deletion; it does NOT detect\n' +
'tail-truncation or deletion of the whole ledger (out of scope — the ledger\n' +
'is forensic observability against accidents, not the same-user local actor).\n',
);
process.exit(2);
}