diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b3be917..2bc13b1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -160,10 +160,11 @@ jobs: run: python3 tools/make_claim_fixture.py --check # The template-pinning tool runs exactly once, on the most consequential day of the - # project (#61), against the first real AdSense proof. A tool like that has to be - # known-good before that day, so its self-test derives the template from the signed - # fixture and checks that a window the proof was not signed for is refused. - - name: The template derivation works and refuses a wrong window + # project (#61), against the first real AdSense proof, and once more for AdMob (#96). + # A tool like that has to be known-good before that day, so its self-test derives + # both templates from their fixtures and checks that a window the proof was not + # signed for, or the other source's value order (#94), is refused. + - name: The template derivation works and refuses a wrong window or value order run: python3 tools/pin_template.py --self-test # The evidence pack (#27) is what a reviewer reads. A broken relative path or a diff --git a/be/src/admob/fixture.test.ts b/be/src/admob/fixture.test.ts new file mode 100644 index 0000000..0eef80b --- /dev/null +++ b/be/src/admob/fixture.test.ts @@ -0,0 +1,55 @@ +/** + * Forepay #96: `tools/fixtures/admob-claim.json`, which `tools/pin_template.py --self-test` + * derives the AdMob template from, is the request this relay actually builds. If the + * request changes, this fails, and the fixture has to be regenerated with the change, + * so the Python derivation is never proven against bytes the relay no longer sends. + * + * Regenerate: ADMOB_FIXTURE=write pnpm -C be test + */ +import assert from "node:assert/strict"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { test } from "node:test"; + +import { CONTEXT_MESSAGE } from "../adsense/request.js"; +import { canonicalStringify, getIdentifierFromClaimInfo } from "../reclaim/claim-digest.js"; +import { FIGURE, buildAdmobRequest } from "./request.js"; + +const FILE = join(import.meta.dirname, "..", "..", "..", "tools", "fixtures", "admob-claim.json"); + +function build() { + const pubId = "pub-1234567890123456"; + const borrower = "GA2CD6PMHMBTCFAQDO3R22BSZN5ZSVTAKVNOKXL2SONZBLGRAYIOWWH2"; + const window = { start: { year: 2026, month: 7, day: 1 }, end: { year: 2026, month: 9, day: 30 } }; + const req = buildAdmobRequest({ publisherId: pubId, stellarAddress: borrower, window }); + // The attestor adds its User-Agent and sorts the keys, as the #93 spike proof showed. + const parameters = canonicalStringify({ + body: req.options.body, + headers: { "User-Agent": "reclaim/0.0.1", ...req.options.headers }, + method: req.options.method, + responseMatches: req.secretOptions.responseMatches, + responseRedactions: req.secretOptions.responseRedactions, + url: req.url, + }); + const context = JSON.stringify({ + contextAddress: borrower, + contextMessage: CONTEXT_MESSAGE, + extractedParameters: { [FIGURE]: "12345678" }, + providerHash: `0x${"cd".repeat(32)}`, + }); + return { + _source: "Generated by be/src/admob/fixture.test.ts from the relay's own AdMob request. Made-up account, window and figure.", + pubId, + windowStart: "2026-07-01", + windowEnd: "2026-09-30", + parameters, + context, + identifier: getIdentifierFromClaimInfo({ provider: "http", parameters, context }), + }; +} + +test("the AdMob template fixture is the request the relay builds", () => { + const want = JSON.stringify(build(), null, 2) + "\n"; + if (process.env.ADMOB_FIXTURE === "write") writeFileSync(FILE, want); + assert.equal(readFileSync(FILE, "utf8"), want, "tools/fixtures/admob-claim.json is stale; regenerate it (see the header)"); +}); diff --git a/tools/fixtures/admob-claim.json b/tools/fixtures/admob-claim.json new file mode 100644 index 0000000..b81cf94 --- /dev/null +++ b/tools/fixtures/admob-claim.json @@ -0,0 +1,9 @@ +{ + "_source": "Generated by be/src/admob/fixture.test.ts from the relay's own AdMob request. Made-up account, window and figure.", + "pubId": "pub-1234567890123456", + "windowStart": "2026-07-01", + "windowEnd": "2026-09-30", + "parameters": "{\"body\":\"{\\\"reportSpec\\\":{\\\"dateRange\\\":{\\\"startDate\\\":{\\\"year\\\":2026,\\\"month\\\":7,\\\"day\\\":1},\\\"endDate\\\":{\\\"year\\\":2026,\\\"month\\\":9,\\\"day\\\":30}},\\\"metrics\\\":[\\\"ESTIMATED_EARNINGS\\\"],\\\"localizationSettings\\\":{\\\"currencyCode\\\":\\\"USD\\\"}}}\",\"headers\":{\"User-Agent\":\"reclaim/0.0.1\",\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"method\":\"POST\",\"responseMatches\":[{\"type\":\"regex\",\"value\":\"\\\"localizationSettings\\\":\\\\s*\\\\{\\\\s*\\\"currencyCode\\\":\\\\s*\\\"USD\\\"\\\\s*\\\\}\"},{\"type\":\"regex\",\"value\":\"\\\"row\\\":\\\\s*\\\\{\\\\s*\\\"metricValues\\\":\\\\s*\\\\{\\\\s*\\\"ESTIMATED_EARNINGS\\\":\\\\s*\\\\{\\\\s*\\\"microsValue\\\":\\\\s*\\\"(?\\\\d+)\\\"\\\\s*\\\\}\\\\s*\\\\}\\\\s*\\\\}\"}],\"responseRedactions\":[{\"regex\":\"\\\"localizationSettings\\\":\\\\s*\\\\{\\\\s*\\\"currencyCode\\\":\\\\s*\\\"USD\\\"\\\\s*\\\\}\"},{\"regex\":\"\\\"row\\\":\\\\s*\\\\{\\\\s*\\\"metricValues\\\":\\\\s*\\\\{\\\\s*\\\"ESTIMATED_EARNINGS\\\":\\\\s*\\\\{\\\\s*\\\"microsValue\\\":\\\\s*\\\"(?\\\\d+)\\\"\\\\s*\\\\}\\\\s*\\\\}\\\\s*\\\\}\"}],\"url\":\"https://admob.googleapis.com/v1/accounts/pub-1234567890123456/networkReport:generate\"}", + "context": "{\"contextAddress\":\"GA2CD6PMHMBTCFAQDO3R22BSZN5ZSVTAKVNOKXL2SONZBLGRAYIOWWH2\",\"contextMessage\":\"Forepay advance request\",\"extractedParameters\":{\"revenueMicros\":\"12345678\"},\"providerHash\":\"0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd\"}", + "identifier": "0x4f3b53c4ab1ee8f71e6827166cda154d4a5fc22cb2df30d58c69b15977d8aba6" +} diff --git a/tools/pin_template.py b/tools/pin_template.py index b82a534..2feef0d 100644 --- a/tools/pin_template.py +++ b/tools/pin_template.py @@ -3,6 +3,7 @@ python3 tools/pin_template.py PROOF.json --pub-id pub-… --start 2026-07-01 --end 2026-09-30 python3 tools/pin_template.py PROOF.json ... --contract C… --command + python3 tools/pin_template.py PROOF.json --source admob ... # an AdMob proof (#96) `set_claim_template` takes the literal segments of the request the attestor signed, with seven values interleaved between them (`docs/interface.md` §2). Those bytes can only come @@ -17,14 +18,21 @@ 1. **Round trip.** Interleaving the parts with the values reproduces `parameters` byte for byte. Necessary but weak on its own — a split at the wrong occurrence of a short value like `"1"` also round-trips. -2. **Structure.** Every separator between two values must end with `=`, and the first part - must end with `/`. This is what actually catches a wrong occurrence: a split inside a - publisher id or a regex does not land on a query-parameter boundary. +2. **Structure.** Each value must sit immediately after the one separator it belongs to. For + AdSense, every separator between two values ends with `=` and the first part ends with + `/`. For AdMob, each date number follows its JSON key in the body (`"startDate":{"year":`, + `"month":`, `"day":`) and the publisher id follows `/accounts/`. This is what actually + catches a wrong occurrence: a split inside a publisher id or a regex does not land on + one of those boundaries. 3. **The attestor's own signature.** The identifier is recomputed from the rebuilt `parameters` and the claim's `context` and compared with the identifier the attestor signed. If that matches, the bytes are right because the signature says so, not because this script believes its own string surgery. +**The value order depends on the source** (#94, #96). The attestor sorts the parameters' +keys, so for AdMob `body`, which holds the window, comes before `url`, which holds the +publisher id: the order is `[sy, sm, sd, ey, em, ed, pub_id]`, the reverse of AdSense's. + It writes nothing to chain. With `--command` it prints the `stellar contract invoke` line, for a human to read and run. """ @@ -47,14 +55,33 @@ def unpadded(digits: str) -> str: return str(int(digits)) -def values_for(pub_id: str, start: str, end: str) -> list[str]: +# What each value must immediately follow in the signed parameters, per source, in the order +# the values appear. The AdMob body is a JSON string inside the parameters' JSON, so its +# quotes arrive escaped. +SOURCES = { + "adsense": { + "pub_first": True, + "after": ["/", "=", "=", "=", "=", "=", "="], + }, + "admob": { + "pub_first": False, + "after": [ + '\\"startDate\\":{\\"year\\":', '\\"month\\":', '\\"day\\":', + '\\"endDate\\":{\\"year\\":', '\\"month\\":', '\\"day\\":', + "/accounts/", + ], + }, +} + + +def values_for(pub_id: str, start: str, end: str, source: str = "adsense") -> list[str]: for d in (start, end): if not DATE.match(d): raise SystemExit(f"not a YYYY-MM-DD date: {d}") - out = [pub_id] + dates: list[str] = [] for d in (start, end): - out += [unpadded(p) for p in d.split("-")] - return out + dates += [unpadded(p) for p in d.split("-")] + return [pub_id] + dates if SOURCES[source]["pub_first"] else dates + [pub_id] def read_claim(proof: dict) -> tuple[str, str, str, str]: @@ -90,7 +117,7 @@ def split_parts(parameters: str, values: list[str]) -> list[str]: def check(parts: list[str], values: list[str], parameters: str, - provider: str, context: str, identifier: str) -> None: + provider: str, context: str, identifier: str, source: str = "adsense") -> None: if len(parts) != len(values) + 1: raise SystemExit(f"{len(parts)} parts for {len(values)} values; the contract wants exactly 8 parts") @@ -104,14 +131,12 @@ def check(parts: list[str], values: list[str], parameters: str, # The check that actually matters. A split at the wrong occurrence of "1" or "7" # round-trips perfectly and produces a template that breaks for every other window. problems = [] - if not parts[0].endswith("/"): - problems.append(f"part 0 should end with '/' before the publisher id, ends {parts[0][-12:]!r}") - for i in range(1, len(values)): - if not parts[i].endswith("="): - problems.append(f"part {i} should end with '=' before a date value, ends {parts[i][-14:]!r}") + for i, sep in enumerate(SOURCES[source]["after"]): + if not parts[i].endswith(sep): + problems.append(f"part {i} should end with {sep!r} before value {i}, ends {parts[i][-len(sep) - 8:]!r}") if problems: - raise SystemExit("the split did not land on query-parameter boundaries:\n - " + "\n - ".join(problems)) - print(" structure ........ every value sits immediately after a '=' or the accounts path") + raise SystemExit(f"the split did not land on the {source} boundaries:\n - " + "\n - ".join(problems)) + print(f" structure ........ every value sits immediately after its own {source} separator") got = "0x" + secp.keccak256(f"{provider}\n{parameters}\n{context}".encode()).hex() if got.lower() != identifier.lower(): @@ -130,43 +155,57 @@ def provider_hash_of(context: str) -> str: return m.group(1) -def self_test() -> int: - """Run the whole derivation against the signed fixture, with no real proof needed. - - The point of a tool that only runs once, on the most consequential day of the project, - is that it has to be known-good before that day. So this builds a Reclaim-shaped proof - out of `tools/fixtures/forepay-claim.json` — whose parameters, context and identifier - were produced by the same code path the contract rebuilds — and derives the template - from it exactly as it will from the real one. - - It also checks the failure that matters: a wrong window must be refused, not guessed at. - """ - fx = json.loads((Path(__file__).parent / "fixtures" / "forepay-claim.json").read_text()) - proof = { - "claimInfo": {"provider": "http", "parameters": fx["parameters"], "context": fx["context"]}, - "signedClaim": {"claim": {"identifier": fx["identifier"]}}, - } - values = values_for(fx["pubId"], fx["windowStart"], fx["windowEnd"]) - print("self-test against tools/fixtures/forepay-claim.json") +def self_test_one(name: str, source: str) -> None: + fx = json.loads((Path(__file__).parent / "fixtures" / name).read_text()) + values = values_for(fx["pubId"], fx["windowStart"], fx["windowEnd"], source) + print(f"self-test ({source}) against tools/fixtures/{name}") print(f" values {values}") print("checks:") - parts = split_parts(proof["claimInfo"]["parameters"], values) - check(parts, values, fx["parameters"], "http", fx["context"], fx["identifier"]) + parts = split_parts(fx["parameters"], values) + check(parts, values, fx["parameters"], "http", fx["context"], fx["identifier"], source) if len(parts) != 8: raise SystemExit(f"expected 8 parts, derived {len(parts)}") - print(f" arity ............ 8 parts for 7 values, which is what set_claim_template takes") + print(" arity ............ 8 parts for 7 values, which is what set_claim_template takes") # A window the proof was not signed for must fail loudly rather than produce a # plausible-looking template for the wrong period. try: - wrong = values_for(fx["pubId"], "2025-01-01", "2025-03-31") - split_parts(fx["parameters"], wrong) + wrong = values_for(fx["pubId"], "2025-01-01", "2025-03-31", source) + check(split_parts(fx["parameters"], wrong), wrong, fx["parameters"], "http", fx["context"], fx["identifier"], source) except SystemExit: print(" wrong window ..... refused, as it must be") else: raise SystemExit("a window the proof was not signed for was accepted") - print("\nself-test passed: the derivation works, and refuses a window it was not given") + # The other source's value order must be refused too: that is the #94 mistake, and + # it has to fail here rather than as an unexplained ClaimMismatch on chain. + other = "adsense" if source == "admob" else "admob" + try: + swapped = values_for(fx["pubId"], fx["windowStart"], fx["windowEnd"], other) + check(split_parts(fx["parameters"], swapped), swapped, fx["parameters"], "http", fx["context"], fx["identifier"], source) + except SystemExit: + print(f" {(other + ' order '):.<18} refused, as it must be") + else: + raise SystemExit(f"the {other} value order was accepted for a {source} proof") + + +def self_test() -> int: + """Run the whole derivation against the signed fixture, with no real proof needed. + + The point of a tool that only runs once, on the most consequential day of the project, + is that it has to be known-good before that day. So this builds a Reclaim-shaped proof + out of `tools/fixtures/forepay-claim.json` — whose parameters, context and identifier + were produced by the same code path the contract rebuilds — and derives the template + from it exactly as it will from the real one. + + It also checks the failures that matter: a wrong window, and the other source's value + order, must be refused, not guessed at. The AdMob fixture, `tools/fixtures/admob-claim.json`, + is the relay's own request; `be/src/admob/fixture.test.ts` fails if they drift apart. + """ + self_test_one("forepay-claim.json", "adsense") + print() + self_test_one("admob-claim.json", "admob") + print("\nself-test passed: both derivations work, and refuse a window or a value order they were not given") return 0 @@ -176,7 +215,8 @@ def main() -> int: return self_test() ap.add_argument("--self-test", action="store_true", help="prove the derivation against the signed fixture") ap.add_argument("proof", help="a real Reclaim proof, as JSON") - ap.add_argument("--pub-id", required=True, help="the AdSense publisher id in the signed URL") + ap.add_argument("--source", choices=sorted(SOURCES), default="adsense", help="which product the proof is from") + ap.add_argument("--pub-id", required=True, help="the publisher id in the signed URL") ap.add_argument("--start", required=True, help="window start, YYYY-MM-DD") ap.add_argument("--end", required=True, help="window end, YYYY-MM-DD") ap.add_argument("--contract", help="print the invoke command for this contract") @@ -185,14 +225,14 @@ def main() -> int: proof = json.loads(Path(a.proof).read_text()) provider, parameters, context, identifier = read_claim(proof) - values = values_for(a.pub_id, a.start, a.end) + values = values_for(a.pub_id, a.start, a.end, a.source) - print(f"proof: {a.proof}") + print(f"proof: {a.proof} ({a.source})") print(f" provider {provider}") print(f" values {values}") print("checks:") parts = split_parts(parameters, values) - check(parts, values, parameters, provider, context, identifier) + check(parts, values, parameters, provider, context, identifier, a.source) ph = provider_hash_of(context) print(f"\nprovider_hash: {ph}")