Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 55 additions & 0 deletions be/src/admob/fixture.test.ts
Original file line number Diff line number Diff line change
@@ -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)");
});
9 changes: 9 additions & 0 deletions tools/fixtures/admob-claim.json
Original file line number Diff line number Diff line change
@@ -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*\\\"(?<revenueMicros>\\\\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*\\\"(?<revenueMicros>\\\\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"
}
126 changes: 83 additions & 43 deletions tools/pin_template.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
"""
Expand All @@ -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]:
Expand Down Expand Up @@ -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")

Expand All @@ -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():
Expand All @@ -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


Expand All @@ -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")
Expand All @@ -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}")
Expand Down