From 7f3f8c617726b3c16b63721243e4e18103ae0a1c Mon Sep 17 00:00:00 2001 From: pythonlearner1025 Date: Fri, 28 Aug 2026 04:22:55 +0000 Subject: [PATCH] docs(entitlements): document the digest the billing service actually computes The README recipe and the only code that verifies corpus.sha256 were two different algorithms over two different file sets, and each was self- consistent, so neither looked wrong. The recipe hashed the .json fixtures with no separator between the parts. The billing service's test/billing.test.ts hashes EVERY file in the directory except corpus.sha256 -- README.md included -- as name\0bytes, joined by \0. The billing test is the only reader, so its algorithm is the definition and the recipe was the thing that was wrong. The recipe is now a transcription of that test, and says so, including that nothing in this repository verifies the file. Including README.md is what lets both copies hold the same digest when they are byte-identical, which is what the billing test claims to check. corpus.sha256 is regenerated under the documented algorithm: ca619ff2ba7597717cfb235effa5014e280e96f020c2bec064eb5a5a1b8fdca6 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01J6fUBY1B27EzvDwbhfBf52 --- .../schema/fixtures/entitlements/README.md | 25 ++++++++++++++----- .../fixtures/entitlements/corpus.sha256 | 2 +- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/packages/schema/fixtures/entitlements/README.md b/packages/schema/fixtures/entitlements/README.md index d4497585..eab65869 100644 --- a/packages/schema/fixtures/entitlements/README.md +++ b/packages/schema/fixtures/entitlements/README.md @@ -112,13 +112,26 @@ authenticates the browser when it returns; nothing in the token grants anything. | `seat-limit-denial.json` | The 402 body, with and without a configured `PAYMENT_URL` | | `handoff-claims.json` | The decoded claims inside that `paymentUrl` | | `usage.json` | `GET /orgs/:id/usage`, with seat gating on and off, and for a subscribed organization | -| `corpus.sha256` | SHA-256 of every other `.json` fixture's filename and exact bytes, in filename order | +| `corpus.sha256` | SHA-256 of every other file in this directory, including this README, by name and exact bytes in filename order | -`corpus.sha256` is `sha256(name₁ ‖ bytes₁ ‖ name₂ ‖ bytes₂ ‖ …)` over the -`.json` files above, sorted by filename, with no separator between the parts: +`corpus.sha256` has exactly one reader: the private billing service keeps a copy +of this directory, and its `test/billing.test.ts` recomputes this digest to prove +the copy is still byte-identical. Nothing in this repository verifies it. The +recipe below is therefore a transcription of that test rather than an +independent definition of the digest — where the two disagree, the test is +right and this section is wrong. + +It is `sha256(name₁ ‖ NUL ‖ bytes₁ ‖ NUL ‖ name₂ ‖ NUL ‖ bytes₂ ‖ …)` over every +file here except `corpus.sha256` itself, sorted by filename, with a NUL between +every part and none at the end. This README is in the digest like any other +file, which is what lets the two copies hold the same value when they match: ```sh -( cd packages/schema/fixtures/entitlements - for f in $(ls *.json | LC_ALL=C sort); do printf '%s' "$f"; cat "$f"; done \ - | sha256sum | cut -d' ' -f1 ) +# Run in the directory that holds these fixtures, in either repository. +python3 -c ' +import hashlib, os +names = sorted(n for n in os.listdir(".") if n != "corpus.sha256") +parts = [n.encode() + b"\0" + open(n, "rb").read() for n in names] +print(hashlib.sha256(b"\0".join(parts)).hexdigest()) +' ``` diff --git a/packages/schema/fixtures/entitlements/corpus.sha256 b/packages/schema/fixtures/entitlements/corpus.sha256 index dac5a1ea..2cf07567 100644 --- a/packages/schema/fixtures/entitlements/corpus.sha256 +++ b/packages/schema/fixtures/entitlements/corpus.sha256 @@ -1 +1 @@ -6d1dc4b930ae17ce9509cbc5ec01bd8379920d421b67bf1915f354ba8137e748 +ca619ff2ba7597717cfb235effa5014e280e96f020c2bec064eb5a5a1b8fdca6