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
2 changes: 2 additions & 0 deletions be/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
# Reclaim Developer Portal (https://dev.reclaimprotocol.org): an application's id and secret.
RECLAIM_APP_ID=
RECLAIM_APP_SECRET=
# With both set and the circuit files present (pnpm -C be zk:files), `pnpm -C be start`
# also runs the proof relay (#17): POST /proofs. See docs/api.md.

# Google OAuth access token with ONLY the scope
# https://www.googleapis.com/auth/adsense.readonly
Expand Down
117 changes: 117 additions & 0 deletions be/src/adsense/account.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
/**
* The checks that run before a proof is attempted (#4, #17): which AdSense account the
* token reads, whether Google will report for it, and whether the live response has
* the shape the provider's regexes expect.
*
* Shared by `prove:adsense` and the relay. Each failure is a `ProveError` whose code
* says whose move it is (the creator's token, the creator's account, or ours), so the
* relay can tell the front end something a creator can act on.
*
* Proving takes minutes; each of these takes well under a second. A token that expired
* or an account Google will not report for is found here, not after the attestor.
*/
import { ADSENSE_API, ADSENSE_SCOPE, assertPublisherId, type RevenueRequest } from "./request.js";

export type ProveErrorCode =
/** The token is missing, expired or lacks adsense.readonly. Sign in again. */
| "token"
/** The Google account has no AdSense account, several, or one that is not READY. */
| "account"
/** AdSense answered with a shape the provider does not match. Ours to fix. */
| "provider"
/** The attestor or zkFetch failed. Worth retrying. */
| "prove"
/** The proof came back but failed the audit. Ours to fix; nothing was returned. */
| "audit";

export class ProveError extends Error {
constructor(
readonly code: ProveErrorCode,
message: string,
) {
super(message);
this.name = "ProveError";
}
}

export type GoogleGet = (url: string, accessToken: string) => Promise<unknown>;

/** GET an AdSense API URL with the token. Errors never carry the token. */
export const googleGet: GoogleGet = async (url, accessToken) => {
const res = await fetch(url, {
headers: { Authorization: `Bearer ${accessToken}`, accept: "application/json" },
signal: AbortSignal.timeout(15_000),
});
const text = await res.text();
if (res.ok) return JSON.parse(text);
const where = url.split("?")[0];
if (res.status === 401) {
throw new ProveError("token", `Google refused the access token (401). It is missing, expired (they last an hour) or lacks ${ADSENSE_SCOPE}.`);
}
if (res.status === 403) {
throw new ProveError(
"account",
`Google answered 403 for ${where}: the account has no AdSense access, or the AdSense Management API is not enabled for the OAuth client.`,
);
}
throw new ProveError("prove", `AdSense API returned ${res.status} for ${where}: ${text.slice(0, 300)}`);
};

/** The configured publisher id, or the only one the token can read. */
export async function resolvePublisherId(get: GoogleGet, accessToken: string, configured = ""): Promise<string> {
if (configured) {
assertPublisherId(configured);
return configured;
}
const body = (await get(`${ADSENSE_API}/accounts`, accessToken)) as { accounts?: { name: string }[] };
const ids = (body.accounts ?? []).map((a) => a.name.replace(/^accounts\//, ""));
if (ids.length === 1) return ids[0];
throw new ProveError(
"account",
ids.length === 0
? "This Google account has no AdSense account."
: `This Google account can read ${ids.length} AdSense accounts (${ids.join(", ")}); choose one.`,
);
}

/**
* Refuse an account that cannot report. AdSense answers reports:generate with a bare
* 403 "The caller does not have permission" for an account that is CLOSED or was never
* approved, which reads like a token problem and is not one. accounts.get says why.
*/
export async function assertAccountReady(get: GoogleGet, accessToken: string, publisherId: string): Promise<void> {
const acct = (await get(`${ADSENSE_API}/accounts/${publisherId}`, accessToken)) as { state?: string; pendingTasks?: string[] };
if (acct.state === "READY") return;
const pending = acct.pendingTasks?.length ? ` Pending tasks: ${acct.pendingTasks.join(", ")}.` : "";
throw new ProveError(
"account",
`AdSense account ${publisherId} is ${acct.state ?? "in an unknown state"}, not READY.${pending} Google does not serve reports for it.`,
);
}

/** The JSON's structure with every leaf value replaced by its type, for diagnostics. */
export function shapeOf(v: unknown): unknown {
if (Array.isArray(v)) return v.slice(0, 1).map(shapeOf);
if (v && typeof v === "object") {
return Object.fromEntries(Object.entries(v as Record<string, unknown>).map(([k, x]) => [k, shapeOf(x)]));
}
return typeof v;
}

/**
* Run the provider's regexes against the live report, locally. A mismatch shows up here
* in a second, with the response's structure (keys only, never values), instead of as
* an opaque attestor failure minutes later.
*/
export async function checkLiveResponse(get: GoogleGet, accessToken: string, request: RevenueRequest): Promise<void> {
const live = await get(request.url, accessToken);
const pretty = JSON.stringify(live, null, 2);
for (const m of request.secretOptions.responseMatches) {
if (!new RegExp(m.value).test(pretty)) {
throw new ProveError(
"provider",
`the live response does not match ${m.value}\nResponse structure (values hidden):\n${JSON.stringify(shapeOf(live), null, 2)}`,
);
}
}
}
162 changes: 159 additions & 3 deletions be/src/api/app.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,13 @@ import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";

import { ProveError } from "../adsense/account.js";
import type { AdvanceRecord } from "../chain/advance.js";
import type { HorizonOperation } from "../chain/history.js";
import { RECORDED } from "../network.js";
import { createApp, type ChainLike, type RpcLike } from "./app.js";
import { ProofJobs } from "../relay/jobs.js";
import type { AdvanceRequestJson } from "../relay/prove.js";
import { createApp, type ChainLike, type Prover, type RpcLike } from "./app.js";
import { loadConfig, parseOrigin } from "./config.js";

const FRONT_END = "https://app.forepay.example";
Expand Down Expand Up @@ -74,6 +77,7 @@ test("with no overrides, /config reports exactly the recorded addresses", async
advance: "recorded",
},
recorded: true,
relay: false,
});
});

Expand Down Expand Up @@ -116,14 +120,14 @@ test("any other origin gets no CORS grant at all", async () => {
}
});

test("a preflight from the front end succeeds, for GET only", async () => {
test("a preflight from the front end succeeds, for GET and the relay's POST only", async () => {
const res = await app().request("/config", {
method: "OPTIONS",
headers: { Origin: FRONT_END, "Access-Control-Request-Method": "GET" },
});
assert.equal(res.status, 204);
assert.equal(res.headers.get("access-control-allow-origin"), FRONT_END);
assert.match(res.headers.get("access-control-allow-methods") ?? "", /^GET,OPTIONS$/);
assert.match(res.headers.get("access-control-allow-methods") ?? "", /^GET,POST,OPTIONS$/);
});

test("/health is up without touching the RPC", async () => {
Expand Down Expand Up @@ -237,3 +241,155 @@ test("history routes answer 502 when the chain cannot be read, without leaking w
console.error = original;
}
});

// --- the proof relay (#17) ---

const REQUEST: AdvanceRequestJson = {
revenueUsd: "1234.56",
pubId: "pub-1234567890123456",
windowStart: "2026-07-01",
windowEnd: "2026-09-30",
timestampS: "1791590340",
epoch: "1",
signature: "ab".repeat(64),
recoveryId: 1,
};
const TOKEN = "ya29.a0-test-token";

function relayApp(prover?: Prover, maxQueued?: number) {
return createApp({
loaded: loadConfig({ CORS_ORIGINS: FRONT_END }),
rpc: healthy,
chain: fixtureChain,
prover,
jobs: new ProofJobs({ log: () => {}, maxQueued }),
});
}

function post(body: unknown, origin = FRONT_END) {
return new Request("http://api/proofs", {
method: "POST",
headers: { "Content-Type": "application/json", Origin: origin },
body: typeof body === "string" ? body : JSON.stringify(body),
});
}

async function finished(api: ReturnType<typeof relayApp>, id: string) {
for (let i = 0; i < 100; i++) {
const job = (await (await api.request(`/proofs/${id}`)).json()) as { stage: string };
if (job.stage === "done" || job.stage === "failed") return job;
await new Promise((r) => setTimeout(r, 5));
}
assert.fail("job did not finish");
}

test("POST /proofs answers 202 with a job; polling it ends in request_advance's arguments", async () => {
const seen: unknown[] = [];
const api = relayApp(async (input, onStep) => {
seen.push(input);
onStep("proving");
return REQUEST;
});
const res = await api.request(post({ borrower: BORROWER, accessToken: TOKEN }));
assert.equal(res.status, 202);
assert.equal(res.headers.get("access-control-allow-origin"), FRONT_END);
assert.equal(res.headers.get("cache-control"), "no-store");
const job = (await res.json()) as { id: string; stage: string };
assert.match(job.id, /^[0-9a-f-]{36}$/);
assert.equal(res.headers.get("location"), `/proofs/${job.id}`);

const done = await finished(api, job.id);
assert.deepEqual({ ...done, createdAt: 0 }, { id: job.id, stage: "done", createdAt: 0, request: REQUEST });
assert.deepEqual(seen, [{ borrower: BORROWER, accessToken: TOKEN, publisherId: undefined }]);
assert.ok(!JSON.stringify(done).includes(TOKEN));
});

test("a failed proof reports its code, and the token never appears in it", async () => {
const api = relayApp(async () => {
throw new ProveError("token", `Google refused ${TOKEN}`);
});
const job = (await (await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).json()) as { id: string };
const done = (await finished(api, job.id)) as { error?: { code: string; message: string } };
assert.deepEqual(done.error, { code: "token", message: "Google refused [redacted]" });
});

test("POST /proofs refuses what is not a proof request", async () => {
const api = relayApp(async () => REQUEST);
const cases: [unknown, number][] = [
["not json", 400],
[{ accessToken: TOKEN }, 400],
[{ borrower: DEV, accessToken: TOKEN }, 400],
[{ borrower: BORROWER }, 400],
[{ borrower: BORROWER, accessToken: "" }, 400],
[{ borrower: BORROWER, accessToken: "x" }, 400],
[{ borrower: BORROWER, accessToken: TOKEN, publisherId: "pub-1" }, 400],
[{ borrower: BORROWER, accessToken: "x".repeat(9000) }, 413],
];
for (const [body, status] of cases) {
const res = await api.request(post(body));
assert.equal(res.status, status, JSON.stringify(body).slice(0, 80));
}
});

test("a second proof for the same borrower while one runs is 409 running, without the running job's id", async () => {
let release!: () => void;
const api = relayApp(
() =>
new Promise((res) => {
release = () => res(REQUEST);
}),
);
assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 202);
const res = await api.request(post({ borrower: BORROWER, accessToken: TOKEN }));
assert.equal(res.status, 409);
const body = (await res.json()) as { code: string; id?: string };
assert.equal(body.code, "running");
assert.equal(body.id, undefined);
await new Promise((r) => setTimeout(r, 0));
release();
});

test("a full queue is 503 busy, with Retry-After", async () => {
let release!: () => void;
const api = relayApp(
() =>
new Promise((res) => {
release = () => res(REQUEST);
}),
1,
);
const [SECOND, THIRD] = ["GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H", "GB4L3CM64YHTTOKQDLQHFM4G6L5V6H3TNFZZW44SYRHJUIFOOE4RGWQS"];
assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 202);
assert.equal((await api.request(post({ borrower: SECOND, accessToken: TOKEN }))).status, 202);
const res = await api.request(post({ borrower: THIRD, accessToken: TOKEN }));
assert.equal(res.status, 503);
assert.equal(res.headers.get("Retry-After"), "120");
assert.equal(((await res.json()) as { code: string }).code, "busy");
release();
});

test("without a prover the relay is off: 503 unconfigured, and /config says so", async () => {
const api = relayApp();
const res = await api.request(post({ borrower: BORROWER, accessToken: TOKEN }));
assert.equal(res.status, 503);
assert.equal(((await res.json()) as { code: string }).code, "unconfigured");
assert.equal(((await (await api.request("/config")).json()) as { relay: boolean }).relay, false);
assert.equal(((await (await relayApp(async () => REQUEST).request("/config")).json()) as { relay: boolean }).relay, true);
});

test("unknown proof jobs are 404", async () => {
assert.equal((await relayApp(async () => REQUEST).request("/proofs/00000000-0000-0000-0000-000000000000")).status, 404);
});

test("CORS preflight allows the front end to POST JSON, and nobody else", async () => {
const preflight = (origin: string) =>
relayApp(async () => REQUEST).request("/proofs", {
method: "OPTIONS",
headers: { Origin: origin, "Access-Control-Request-Method": "POST", "Access-Control-Request-Headers": "content-type" },
});
const ok = await preflight(FRONT_END);
assert.equal(ok.headers.get("access-control-allow-origin"), FRONT_END);
assert.match(ok.headers.get("access-control-allow-methods") ?? "", /POST/);
assert.match((ok.headers.get("access-control-allow-headers") ?? "").toLowerCase(), /content-type/);
assert.equal((await preflight("https://evil.example")).headers.get("access-control-allow-origin"), null);
});
Loading