From 0aea776afd6c6ab0ce41f4f2355cb3e16ee64551 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 20 Oct 2026 10:27:19 +0700 Subject: [PATCH 1/5] feat(#17): proof relay, POST /proofs and GET /proofs/:id MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The relay takes the borrower's G… and a Google access token with adsense.readonly, proves the trailing AdSense revenue with zkFetch, and returns request_advance's arguments. The G… goes into contextAddress before the attestor signs, so the binding is inside the signed claim (#9). Proving takes about ten minutes of CPU with snarkjs, so the request answers 202 with a job id and the front end polls. One proof runs at a time; one job per borrower; a short queue. Jobs live in memory and the token only in the running job's closure: never stored, logged or returned, and scrubbed from errors. The pre-flight checks (account, READY, response shape) move from the prove:adsense CLI to adsense/account.ts and relay/prove.ts, so the CLI and the relay run the same code. Failures carry a code that says whose move it is: token, account, provider, prove, audit. The browser flow and the API are in docs/api.md. --- be/.env.example | 2 + be/src/adsense/account.ts | 117 +++++++++++++++++++++++++++ be/src/api/app.test.ts | 136 +++++++++++++++++++++++++++++++- be/src/api/app.ts | 64 ++++++++++++++- be/src/api/server.ts | 36 ++++++++- be/src/cli/prove-adsense.ts | 147 +++++++--------------------------- be/src/relay/fake-reclaim.ts | 107 +++++++++++++++++++++++++ be/src/relay/jobs.test.ts | 124 +++++++++++++++++++++++++++++ be/src/relay/jobs.ts | 137 ++++++++++++++++++++++++++++++++ be/src/relay/prove.test.ts | 112 ++++++++++++++++++++++++++ be/src/relay/prove.ts | 148 +++++++++++++++++++++++++++++++++++ docs/api.md | 117 ++++++++++++++++++++++++++- 12 files changed, 1116 insertions(+), 131 deletions(-) create mode 100644 be/src/adsense/account.ts create mode 100644 be/src/relay/fake-reclaim.ts create mode 100644 be/src/relay/jobs.test.ts create mode 100644 be/src/relay/jobs.ts create mode 100644 be/src/relay/prove.test.ts create mode 100644 be/src/relay/prove.ts diff --git a/be/.env.example b/be/.env.example index 8f18170..563cc1a 100644 --- a/be/.env.example +++ b/be/.env.example @@ -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 diff --git a/be/src/adsense/account.ts b/be/src/adsense/account.ts new file mode 100644 index 0000000..f44e1ab --- /dev/null +++ b/be/src/adsense/account.ts @@ -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; + +/** 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 { + 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 { + 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).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 { + 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)}`, + ); + } + } +} diff --git a/be/src/api/app.test.ts b/be/src/api/app.test.ts index 073bb8f..99801b4 100644 --- a/be/src/api/app.test.ts +++ b/be/src/api/app.test.ts @@ -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"; @@ -74,6 +77,7 @@ test("with no overrides, /config reports exactly the recorded addresses", async advance: "recorded", }, recorded: true, + relay: false, }); }); @@ -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 () => { @@ -237,3 +241,129 @@ 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) { + return createApp({ + loaded: loadConfig({ CORS_ORIGINS: FRONT_END }), + rpc: healthy, + chain: fixtureChain, + prover, + jobs: new ProofJobs({ log: () => {} }), + }); +} + +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, 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: 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", 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); + assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 409); + await new Promise((r) => setTimeout(r, 0)); + release(); +}); + +test("without a prover the relay is off: 503, and /config says so", async () => { + const api = relayApp(); + assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 503); + 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); +}); diff --git a/be/src/api/app.ts b/be/src/api/app.ts index 0a82178..38731eb 100644 --- a/be/src/api/app.ts +++ b/be/src/api/app.ts @@ -9,6 +9,9 @@ * the contract's current record of each (principal, repaid, window). * GET /transactions?borrower=G… advances, repayments and the USDC trustline, * newest first, failed ones included. + * POST /proofs the relay (#17): prove the creator's AdSense revenue, bound to their + * `G…`. Answers 202 with a job id at once; proving takes minutes. + * GET /proofs/:id the job's stage, then `request_advance`'s arguments or an error. * * Amounts are stroops and times are seconds, both as decimal strings: JSON numbers * lose precision past 2^53 and an i128 can exceed that. @@ -16,13 +19,17 @@ * The app is built from injected config and chain access so tests run without a network. */ import { Hono, type Context } from "hono"; +import { bodyLimit } from "hono/body-limit"; import { cors } from "hono/cors"; import { secureHeaders } from "hono/secure-headers"; import { StrKey } from "@stellar/stellar-sdk"; +import { ProveError } from "../adsense/account.js"; import type { AdvanceRecord } from "../chain/advance.js"; import { advanceCalls, ledgerTransactions, type HorizonOperation } from "../chain/history.js"; +import { BorrowerBusyError, ProofJobs, QueueFullError } from "../relay/jobs.js"; +import type { AdvanceRequestJson, ProveInput, ProveStep } from "../relay/prove.js"; import type { LoadedConfig } from "./config.js"; /** The slice of the Stellar RPC client the API uses. */ @@ -36,15 +43,20 @@ export interface ChainLike { readAdvance(contract: string, nullifierHex: string): Promise; } +/** Makes one proof (relay/prove.ts with zkFetch bound). Absent when the relay is not configured. */ +export type Prover = (input: ProveInput, onStep: (s: ProveStep) => void) => Promise; + export interface AppDeps { loaded: LoadedConfig; rpc: RpcLike; chain: ChainLike; + prover?: Prover; + jobs?: ProofJobs; /** Readiness check timeout. */ readyTimeoutMs?: number; } -export function createApp({ loaded, rpc, chain, readyTimeoutMs = 5000 }: AppDeps) { +export function createApp({ loaded, rpc, chain, prover, jobs = new ProofJobs(), readyTimeoutMs = 5000 }: AppDeps) { const { config, sources, recorded } = loaded; const allowed = new Set(config.corsOrigins); const app = new Hono(); @@ -56,7 +68,8 @@ export function createApp({ loaded, rpc, chain, readyTimeoutMs = 5000 }: AppDeps // Echo only an exact, configured origin. An unknown origin gets no // Access-Control-Allow-Origin at all, so the browser refuses the response. origin: (origin) => (allowed.has(origin) ? origin : null), - allowMethods: ["GET", "OPTIONS"], + allowMethods: ["GET", "POST", "OPTIONS"], + allowHeaders: ["Content-Type"], maxAge: 600, }), ); @@ -85,6 +98,7 @@ export function createApp({ loaded, rpc, chain, readyTimeoutMs = 5000 }: AppDeps contracts: config.contracts, sources, recorded, + relay: prover !== undefined, }), ); @@ -146,6 +160,52 @@ export function createApp({ loaded, rpc, chain, readyTimeoutMs = 5000 }: AppDeps ); }); + app.post( + "/proofs", + // A borrower and a token. Anything bigger is not a proof request. + bodyLimit({ maxSize: 8 * 1024, onError: (c) => c.json({ error: "request body too large" }, 413) }), + async (c) => { + c.header("Cache-Control", "no-store"); + if (!prover) return c.json({ error: "the proof relay is not configured on this server" }, 503); + let body: { borrower?: unknown; accessToken?: unknown; publisherId?: unknown }; + try { + body = await c.req.json(); + } catch { + return c.json({ error: "expected a JSON body" }, 400); + } + const { borrower, accessToken, publisherId } = body ?? {}; + if (typeof borrower !== "string" || !StrKey.isValidEd25519PublicKey(borrower)) { + return c.json({ error: "borrower must be a Stellar account address (G…)" }, 400); + } + if (typeof accessToken !== "string" || !accessToken || accessToken.length > 4096) { + return c.json({ error: "accessToken must be a Google OAuth access token with adsense.readonly" }, 400); + } + if (publisherId !== undefined && (typeof publisherId !== "string" || !/^pub-\d{16}$/.test(publisherId))) { + return c.json({ error: "publisherId, when given, must be pub- and 16 digits" }, 400); + } + try { + const job = jobs.submit(borrower, (onStep) => + prover({ borrower, accessToken, publisherId }, onStep).catch((e: unknown) => { + // Whatever failed, its message must not carry this job's token. + if (e instanceof ProveError) throw new ProveError(e.code, e.message.split(accessToken).join("[redacted]")); + throw new Error(String((e as Error)?.stack ?? e).split(accessToken).join("[redacted]")); + }), + ); + return c.json(job, 202, { Location: `/proofs/${job.id}` }); + } catch (e) { + if (e instanceof BorrowerBusyError) return c.json({ error: "a proof for this borrower is already in progress" }, 409); + if (e instanceof QueueFullError) return c.json({ error: "the relay is busy; try again in a few minutes" }, 503, { "Retry-After": "120" }); + throw e; + } + }, + ); + + app.get("/proofs/:id", (c) => { + c.header("Cache-Control", "no-store"); + const job = jobs.get(c.req.param("id")); + return job ? c.json(job) : c.json({ error: "no such proof job (they are kept for an hour)" }, 404); + }); + app.notFound((c) => c.json({ error: "not found" }, 404)); app.onError((err, c) => { console.error(err); diff --git a/be/src/api/server.ts b/be/src/api/server.ts index 2c3fb20..3dabd79 100644 --- a/be/src/api/server.ts +++ b/be/src/api/server.ts @@ -5,14 +5,23 @@ * be/.env.example. With NODE_ENV=production the server refuses to start without * CORS_ORIGINS: a deployed API that allows no origin fails every request from the * front end, and the time to find that out is at startup, not at the demo. + * + * The proof relay (#17) is on when RECLAIM_APP_ID and RECLAIM_APP_SECRET are set and + * the circuit files are present (`pnpm -C be zk:files`). Without them the read routes + * still serve and POST /proofs answers 503, which /config reports as `relay: false`. */ import { serve } from "@hono/node-server"; +import { ReclaimClient } from "@reclaimprotocol/zk-fetch"; import { rpc } from "@stellar/stellar-sdk"; -import { die, loadEnv } from "../cli/env.js"; +import { googleGet } from "../adsense/account.js"; +import { die, keepSecret, loadEnv, optional, scrub } from "../cli/env.js"; import { readAdvance } from "../chain/advance.js"; import { fetchOperations } from "../chain/history.js"; -import { createApp } from "./app.js"; +import { ZK_ENGINE, hasZkFiles } from "../reclaim/zk-files.js"; +import { ProofJobs } from "../relay/jobs.js"; +import { proveRevenue, toAdvanceRequest } from "../relay/prove.js"; +import { createApp, type Prover } from "./app.js"; import { loadConfig } from "./config.js"; loadEnv(false); @@ -34,6 +43,27 @@ if (!loaded.recorded) { ); } +function relay(): Prover | undefined { + const appId = optional("RECLAIM_APP_ID"); + const appSecret = keepSecret(optional("RECLAIM_APP_SECRET")); + if (!appId || !appSecret) { + console.warn("⚠ proof relay off: RECLAIM_APP_ID / RECLAIM_APP_SECRET are not set"); + return undefined; + } + if (!hasZkFiles()) { + console.warn("⚠ proof relay off: the ZK circuit files are missing. Run: pnpm -C be zk:files"); + return undefined; + } + const client = new ReclaimClient(appId, appSecret, false, 2); + const deps = { + google: googleGet, + zkFetch: ((url, options, secretOptions) => client.zkFetch(url, { ...options, zkEngine: ZK_ENGINE }, secretOptions)) as Parameters< + typeof proveRevenue + >[0]["zkFetch"], + }; + return async (input, onStep) => toAdvanceRequest(await proveRevenue(deps, input, onStep)); +} + const server = new rpc.Server(loaded.config.rpcUrl); const { horizonUrl, networkPassphrase } = loaded.config; const app = createApp({ @@ -43,6 +73,8 @@ const app = createApp({ operations: (account) => fetchOperations(account, { horizonUrl }), readAdvance: (contract, nullifier) => readAdvance(server, networkPassphrase, contract, nullifier), }, + prover: relay(), + jobs: new ProofJobs({ scrub }), }); serve({ fetch: app.fetch, port: loaded.config.port }, (info) => { console.log(`Forepay API on :${info.port} (${loaded.config.network}, CORS: ${loaded.config.corsOrigins.join(", ") || "none"})`); diff --git a/be/src/cli/prove-adsense.ts b/be/src/cli/prove-adsense.ts index 3cb7292..00718a3 100644 --- a/be/src/cli/prove-adsense.ts +++ b/be/src/cli/prove-adsense.ts @@ -7,7 +7,7 @@ * Reads be/.env (see be/.env.example). The file must be chmod 600, per the working * agreement; this script refuses to run otherwise. * - * Order matters: + * The steps are relay/prove.ts, the same code the relay (#17) runs. Order matters: * 1. A plain, local fetch of the same report runs the provider's regexes against the * real response first. If AdSense's shape differs from what the provider expects, * that shows up here in seconds, with the response's structure (keys only, never @@ -26,18 +26,12 @@ import { join } from "node:path"; import { ReclaimClient } from "@reclaimprotocol/zk-fetch"; -import { auditRevenueProof, formatFieldReport, type RevenueProof } from "../adsense/audit.js"; -import { - ADSENSE_API, - ADSENSE_SCOPE, - DEFAULT_TRAILING_MONTHS, - assertPublisherId, - buildRevenueRequest, - trailingMonths, - withAccessToken, -} from "../adsense/request.js"; +import { ProveError, googleGet } from "../adsense/account.js"; +import { formatFieldReport } from "../adsense/audit.js"; +import { DEFAULT_TRAILING_MONTHS } from "../adsense/request.js"; import { prepareVerification } from "../reclaim/claim-digest.js"; import { ZK_ENGINE, hasZkFiles } from "../reclaim/zk-files.js"; +import { isoDate, proveRevenue, type ProveStep, type Proven } from "../relay/prove.js"; import { BE_ROOT, die, keepSecret, loadEnv, need, optional } from "./env.js"; function readConfig() { @@ -53,123 +47,36 @@ function readConfig() { }; } -async function googleGet(url: string, accessToken: string): Promise { - const res = await fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, accept: "application/json" } }); - const text = await res.text(); - if (!res.ok) { - const hint = - res.status === 401 - ? " The access token is missing, expired (they last an hour) or lacks the scope " + ADSENSE_SCOPE - : res.status === 403 - ? " The Google account has no AdSense access, or the AdSense Management API is not enabled for the OAuth client." - : ""; - die(`AdSense API returned ${res.status} for ${url.split("?")[0]}.${hint}\n${text.slice(0, 500)}`); - } - return JSON.parse(text); -} - -/** The JSON's structure with every leaf value replaced by its type, for diagnostics. */ -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).map(([k, x]) => [k, shapeOf(x)])); - } - return typeof v; -} - -async function resolvePublisherId(configured: string, accessToken: string): Promise { - if (configured) { - assertPublisherId(configured); - return configured; - } - const body = (await googleGet(`${ADSENSE_API}/accounts`, accessToken)) as { accounts?: { name: string }[] }; - const ids = (body.accounts ?? []).map((a) => a.name.replace(/^accounts\//, "")); - if (ids.length === 1) { - console.log(` publisher id: ${ids[0]} (the only AdSense account this token can read)`); - return ids[0]; - } - die( - ids.length === 0 - ? "this Google account has no AdSense account." - : `this token can read ${ids.length} AdSense accounts (${ids.join(", ")}). Set ADSENSE_PUBLISHER_ID in be/.env.`, - ); -} - -/** - * 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. - */ -async function assertAccountReady(publisherId: string, accessToken: string): Promise { - const acct = (await googleGet(`${ADSENSE_API}/accounts/${publisherId}`, accessToken)) as { - state?: string; - pendingTasks?: string[]; - }; - const pending = acct.pendingTasks?.length ? ` Pending tasks: ${acct.pendingTasks.join(", ")}.` : ""; - if (acct.state !== "READY") { - die( - `AdSense account ${publisherId} is ${acct.state ?? "in an unknown state"}, not READY.${pending}\n` + - "Google does not serve reports for it, so no proof can be made from it. Use an approved AdSense account " + - "(state READY) with earnings in the window.", - ); - } - console.log(` account state: READY${pending}`); -} +const STEPS: Record = { + checking: "[1/3] Checking the account and the provider against the live AdSense response…", + proving: "[2/3] Proving through Reclaim's attestor (this takes a while)…", + auditing: "[3/3] Auditing the claim field by field…", +}; async function main() { const env = readConfig(); console.log("Forepay #4: AdSense revenue proof\n"); - const publisherId = await resolvePublisherId(env.publisherId, env.accessToken); - await assertAccountReady(publisherId, env.accessToken); - const window = trailingMonths(new Date(), env.months); - const fmt = (d: { year: number; month: number; day: number }) => - `${d.year}-${String(d.month).padStart(2, "0")}-${String(d.day).padStart(2, "0")}`; - console.log(` window: ${fmt(window.start)} → ${fmt(window.end)} (${env.months} complete months)`); console.log(` borrower: ${env.stellarAddress}`); - - const request = buildRevenueRequest({ publisherId, stellarAddress: env.stellarAddress, window }); - - // 1. Dry run: the provider's regexes against the real response, locally. - console.log("\n[1/3] Checking the provider against the live AdSense response…"); - const live = await googleGet(request.url, env.accessToken); - const pretty = JSON.stringify(live, null, 2); - for (const m of request.secretOptions.responseMatches) { - if (!new RegExp(m.value).test(pretty)) { - die( - `the live response does not match ${m.value}\n` + - `Response structure (values hidden):\n${JSON.stringify(shapeOf(live), null, 2)}`, - ); - } - } - console.log(" every match holds on the live response."); - - // 2. The proof. - console.log("\n[2/3] Proving through Reclaim's attestor (this takes a while)…"); const client = new ReclaimClient(env.appId, env.appSecret, false, 2); - const call = withAccessToken(request, env.accessToken); - let proof: RevenueProof | undefined; - try { - proof = (await client.zkFetch(call.url, { ...call.options, zkEngine: ZK_ENGINE }, call.secretOptions)) as RevenueProof | undefined; - } catch (e) { - die(`zkFetch failed: ${(e as Error).message}`); - } - if (!proof) die("zkFetch returned no proof"); - - // 3. Audit before anything touches the disk. - console.log("\n[3/3] Auditing the claim field by field…"); - let result; + let proven: Proven; try { - result = auditRevenueProof(proof, { - publisherId, - stellarAddress: env.stellarAddress, - window, - accessToken: env.accessToken, - maxAgeS: 3600, - }); + proven = await proveRevenue( + { + google: googleGet, + zkFetch: (url, options, secretOptions) => client.zkFetch(url, { ...options, zkEngine: ZK_ENGINE }, secretOptions), + months: env.months, + }, + { borrower: env.stellarAddress, accessToken: env.accessToken, publisherId: env.publisherId }, + (step) => console.log(`\n${STEPS[step]}`), + ); } catch (e) { - die(`${(e as Error).message}\n\nThe proof was NOT saved.`); + const notSaved = e instanceof ProveError && e.code === "audit" ? "\n\nThe proof was NOT saved." : ""; + die(`${(e as Error).message}${notSaved}`); } + const { proof, publisherId, window, audit } = proven; + console.log(` publisher id: ${publisherId} (READY)`); + console.log(` window: ${isoDate(window.start)} → ${isoDate(window.end)} (${env.months} complete months)`); const dir = join(BE_ROOT, "proofs"); mkdirSync(dir, { recursive: true }); @@ -182,9 +89,9 @@ async function main() { proof.signatures[0], ); - console.log(`\n✔ Audit passed. Proven revenue: ${result.revenueUsd} USD`); + console.log(`\n✔ Audit passed. Proven revenue: ${audit.revenueUsd} USD`); console.log(` saved: ${file}\n`); - console.log(formatFieldReport(result.fields)); + console.log(formatFieldReport(audit.fields)); console.log("\nverify_proof inputs (for #5):"); console.log(` message_digest: ${v.messageDigest.toString("hex")}`); console.log(` signature: ${v.sig64.toString("hex")}`); diff --git a/be/src/relay/fake-reclaim.ts b/be/src/relay/fake-reclaim.ts new file mode 100644 index 0000000..8f4fd32 --- /dev/null +++ b/be/src/relay/fake-reclaim.ts @@ -0,0 +1,107 @@ +/** + * Test support for #17: a Google AdSense API and a zkFetch that behave like the real + * ones for one account, with claims signed by a throwaway key standing in for the + * attestor. Not imported by the relay itself. + */ +import { secp256k1 } from "@noble/curves/secp256k1"; + +import { ProveError, type GoogleGet } from "../adsense/account.js"; +import { ADSENSE_API, CONTEXT_MESSAGE, type RevenueWindow } from "../adsense/request.js"; +import { canonicalStringify, createSignDataForClaim, getIdentifierFromClaimInfo, messageDigest } from "../reclaim/claim-digest.js"; +import { recoverSigner } from "../adsense/audit.js"; +import type { ZkFetch } from "./prove.js"; + +export const PUB = "pub-1234567890123456"; +export const ALICE = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"; +export const BOB = "GAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQDZ7H"; +export const TOKEN = "ya29.a0-this-is-a-test-token-not-a-real-one"; +/** Q3 2026 is the trailing window as of this date. */ +export const NOW = new Date("2026-10-10T00:00:00Z"); +export const Q3: RevenueWindow = { start: { year: 2026, month: 7, day: 1 }, end: { year: 2026, month: 9, day: 30 } }; + +const KEY = new Uint8Array(32).fill(0x22); +export const ATTESTOR = (() => { + const digest = messageDigest("probe"); + const sig = secp256k1.sign(digest, KEY); + return recoverSigner(digest, sig.toCompactRawBytes(), sig.recovery); +})(); + +export interface FakeGoogle { + state?: string; + accounts?: string[]; + report?: unknown; +} + +/** The report AdSense returns for one metric over `w`, in the shape the provider matches. */ +export function report(w: RevenueWindow, total = "1234.56") { + return { + totalMatchedRows: "3", + headers: [{ name: "ESTIMATED_EARNINGS", type: "METRIC_CURRENCY", currencyCode: "USD" }], + totals: { cells: [{ value: total }] }, + averages: { cells: [{ value: "411.52" }] }, + startDate: w.start, + endDate: w.end, + }; +} + +export function fakeGoogle(o: FakeGoogle = {}): GoogleGet & { calls: string[] } { + const calls: string[] = []; + const get = async (url: string, token: string) => { + calls.push(url); + if (token !== TOKEN) throw new ProveError("token", "Google refused the access token (401)."); + const path = url.slice(ADSENSE_API.length).split("?")[0]; + if (path === "/accounts") return { accounts: (o.accounts ?? [PUB]).map((p) => ({ name: `accounts/${p}` })) }; + if (path === `/accounts/${PUB}`) return { name: `accounts/${PUB}`, state: o.state ?? "READY" }; + if (path === `/accounts/${PUB}/reports:generate`) return o.report ?? report(Q3); + throw new Error(`unexpected Google call ${url}`); + }; + return Object.assign(get, { calls }); +} + +export interface FakeZk { + /** Overrides applied to the signed context, e.g. another contextAddress. */ + context?: Record; + revenueUsd?: string; + timestampS?: number; + fail?: Error; +} + +/** + * zkFetch as the attestor would answer it: the claim is built from the request it was + * given, so what the relay put in (URL, matches, context) is what gets signed. + */ +export function fakeZkFetch(o: FakeZk = {}): ZkFetch & { calls: Parameters[] } { + const calls: Parameters[] = []; + const zk: ZkFetch = async (url, options, secretOptions) => { + calls.push([url, options, secretOptions]); + if (o.fail) throw o.fail; + const parameters = canonicalStringify({ + body: "", + headers: { "User-Agent": "reclaim/0.0.1", ...options.headers }, + method: options.method, + responseMatches: secretOptions.responseMatches, + responseRedactions: secretOptions.responseRedactions, + url, + }); + const context = JSON.stringify({ + contextAddress: options.context.contextAddress, + contextMessage: options.context.contextMessage ?? CONTEXT_MESSAGE, + extractedParameters: { revenueUsd: o.revenueUsd ?? "1234.56" }, + providerHash: `0x${"ab".repeat(32)}`, + ...o.context, + }); + const owner = "0x96faf173bb7171a530b3e44f35f32d1307bda4fa"; + const timestampS = o.timestampS ?? Math.floor(NOW.getTime() / 1000) - 60; + const identifier = getIdentifierFromClaimInfo({ provider: "http", parameters, context }); + const digest = messageDigest(createSignDataForClaim({ identifier, owner, timestampS, epoch: 1 })); + const sig = secp256k1.sign(digest, KEY); + const signature = `0x${Buffer.from(sig.toCompactRawBytes()).toString("hex")}${(27 + sig.recovery).toString(16)}`; + return { + identifier, + claimData: { provider: "http", parameters, owner, timestampS, context, identifier, epoch: 1 }, + signatures: [signature], + witnesses: [{ id: ATTESTOR, url: "wss://attestor.example/ws" }], + }; + }; + return Object.assign(zk, { calls }); +} diff --git a/be/src/relay/jobs.test.ts b/be/src/relay/jobs.test.ts new file mode 100644 index 0000000..1ac4234 --- /dev/null +++ b/be/src/relay/jobs.test.ts @@ -0,0 +1,124 @@ +/** + * Forepay #17: proof jobs run one at a time, one per borrower, and a failure never + * shows more than it should. + */ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { ProveError } from "../adsense/account.js"; +import { BorrowerBusyError, ProofJobs, QueueFullError, type Run } from "./jobs.js"; +import type { AdvanceRequestJson } from "./prove.js"; + +const A = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"; +const B = "GAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQDZ7H"; +const C = "GA2CD6PMHMBTCFAQDO3R22BSZN5ZSVTAKVNOKXL2SONZBLGRAYIOWWH2"; + +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: 0, +}; + +/** A run that waits until released, reporting `proving` meanwhile. */ +function gated() { + let release!: (v: AdvanceRequestJson) => void; + let fail!: (e: unknown) => void; + let started = false; + const run: Run = (onStep) => { + started = true; + onStep("proving"); + return new Promise((res, rej) => { + release = res; + fail = rej; + }); + }; + return { run, release: (v = REQUEST) => release(v), fail: (e: unknown) => fail(e), started: () => started }; +} + +const quiet = { log: () => {} }; +const tick = () => new Promise((r) => setTimeout(r, 0)); + +test("one proof at a time; the rest wait with their place in line", async () => { + const jobs = new ProofJobs(quiet); + const first = gated(); + const second = gated(); + const a = jobs.submit(A, first.run); + const b = jobs.submit(B, second.run); + await tick(); + assert.equal(jobs.get(a.id)?.stage, "proving"); + assert.deepEqual([jobs.get(b.id)?.stage, jobs.get(b.id)?.position], ["queued", 1]); + assert.equal(second.started(), false); + + first.release(); + await tick(); + assert.deepEqual(jobs.get(a.id)?.request, REQUEST); + assert.equal(jobs.get(a.id)?.stage, "done"); + assert.equal(jobs.get(b.id)?.stage, "proving"); + second.release(); + await jobs.idle(); + assert.equal(jobs.get(b.id)?.stage, "done"); +}); + +test("a borrower with a proof in progress cannot start another; after it ends, they can", async () => { + const jobs = new ProofJobs(quiet); + const g = gated(); + jobs.submit(A, g.run); + assert.throws(() => jobs.submit(A, gated().run), BorrowerBusyError); + g.release(); + await jobs.idle(); + const again = gated(); + jobs.submit(A, again.run); + again.release(); + await jobs.idle(); +}); + +test("past the queue limit, new jobs are refused", async () => { + const jobs = new ProofJobs({ ...quiet, maxQueued: 1 }); + const running = gated(); + jobs.submit(A, running.run); + await tick(); + const waiting = gated(); + jobs.submit(B, waiting.run); + assert.throws(() => jobs.submit(C, gated().run), QueueFullError); + running.release(); + await tick(); + waiting.release(); + await jobs.idle(); +}); + +test("a ProveError keeps its code and scrubbed message; anything else says nothing about why", async () => { + const jobs = new ProofJobs({ ...quiet, scrub: (t) => t.split("SECRET").join("[redacted]") }); + const known = gated(); + const k = jobs.submit(A, known.run); + await tick(); + known.fail(new ProveError("account", "account SECRET is CLOSED")); + await jobs.idle(); + assert.deepEqual(jobs.get(k.id)?.error, { code: "account", message: "account [redacted] is CLOSED" }); + + const unknown = gated(); + const u = jobs.submit(B, unknown.run); + await tick(); + unknown.fail(new Error("ENOENT /home/someone/.cache/circuit.wasm")); + await jobs.idle(); + assert.equal(jobs.get(u.id)?.stage, "failed"); + assert.deepEqual(jobs.get(u.id)?.error, { code: "internal", message: "the relay failed while proving; try again" }); +}); + +test("a finished job is readable for an hour, then gone; unknown ids are null", async () => { + let now = 1_000_000; + const jobs = new ProofJobs({ ...quiet, now: () => now, keepMs: 3_600_000 }); + const g = gated(); + const j = jobs.submit(A, g.run); + g.release(); + await jobs.idle(); + now += 3_599_000; + assert.equal(jobs.get(j.id)?.stage, "done"); + now += 2_000; + assert.equal(jobs.get(j.id), null); + assert.equal(jobs.get("not-a-job"), null); +}); diff --git a/be/src/relay/jobs.ts b/be/src/relay/jobs.ts new file mode 100644 index 0000000..d99a2fa --- /dev/null +++ b/be/src/relay/jobs.ts @@ -0,0 +1,137 @@ +/** + * Proof jobs (#17): a proof takes about ten minutes, longer than any HTTP request + * should stay open, so the relay takes the request, answers with a job id at once, + * and the front end polls. + * + * One proof runs at a time. snarkjs proving saturates the CPU; two at once would + * each take twice as long and both risk the claim's one-hour freshness. + * The rest wait in a short queue, and the front end shows their place in it. + * + * Kept in memory on purpose. A job holds nothing worth keeping: the access token + * lives only in the closure of the running job and is gone when it ends, and a + * finished proof is stale within the hour. A restart loses the queue, and the creator + * proves again. + * + * Ids are random UUIDs: knowing one is what lets you read the result, so they are + * not guessable or sequential. + */ +import { randomUUID } from "node:crypto"; + +import { ProveError, type ProveErrorCode } from "../adsense/account.js"; +import type { AdvanceRequestJson, ProveStep } from "./prove.js"; + +export type JobStage = "queued" | ProveStep | "done" | "failed"; + +export interface JobView { + id: string; + stage: JobStage; + /** Jobs ahead of this one, while queued. */ + position?: number; + /** When the job was accepted, seconds. */ + createdAt: number; + /** Present when `stage` is `done`. */ + request?: AdvanceRequestJson; + /** Present when `stage` is `failed`. */ + error?: { code: ProveErrorCode | "internal"; message: string }; +} + +/** Runs one job. The token is in this closure and nowhere else. */ +export type Run = (onStep: (s: ProveStep) => void) => Promise; + +interface Job { + view: JobView; + borrower: string; + run?: Run; + finishedAt?: number; +} + +export interface JobsOptions { + /** Jobs waiting behind the running one. Past this, new jobs are refused. */ + maxQueued?: number; + /** How long a finished job can still be read. The proof is stale after an hour anyway. */ + keepMs?: number; + now?: () => number; + /** Strip secrets from a failure message before anyone can read it. */ + scrub?: (text: string) => string; + log?: (msg: string) => void; +} + +export class QueueFullError extends Error {} +export class BorrowerBusyError extends Error {} + +export class ProofJobs { + private readonly jobs = new Map(); + private readonly queue: Job[] = []; + private running: Job | null = null; + private readonly maxQueued: number; + private readonly keepMs: number; + private readonly now: () => number; + private readonly scrub: (text: string) => string; + private readonly log: (msg: string) => void; + + constructor(opts: JobsOptions = {}) { + this.maxQueued = opts.maxQueued ?? 5; + this.keepMs = opts.keepMs ?? 3_600_000; + this.now = opts.now ?? Date.now; + this.scrub = opts.scrub ?? ((t) => t); + this.log = opts.log ?? ((m) => console.log(m)); + } + + /** Accept a job. One unfinished job per borrower: a second would only race the first. */ + submit(borrower: string, run: Run): JobView { + this.sweep(); + if ([...this.jobs.values()].some((j) => j.borrower === borrower && !j.finishedAt)) throw new BorrowerBusyError(); + if (this.queue.length >= this.maxQueued) throw new QueueFullError(); + const job: Job = { borrower, run, view: { id: randomUUID(), stage: "queued", createdAt: Math.floor(this.now() / 1000) } }; + this.jobs.set(job.view.id, job); + this.queue.push(job); + void this.pump(); + return this.get(job.view.id) as JobView; + } + + get(id: string): JobView | null { + this.sweep(); + const job = this.jobs.get(id); + if (!job) return null; + const i = this.queue.indexOf(job); + return i >= 0 ? { ...job.view, position: i + (this.running ? 1 : 0) } : { ...job.view }; + } + + /** Resolves once nothing is running or queued. For tests and shutdown. */ + async idle(): Promise { + while (this.running || this.queue.length) await new Promise((r) => setTimeout(r, 5)); + } + + private async pump(): Promise { + if (this.running) return; + const job = this.queue.shift(); + if (!job) return; + this.running = job; + const run = job.run as Run; + job.run = undefined; // drop the token's closure from the record as soon as it starts + const started = this.now(); + try { + job.view.request = await run((s) => { + job.view.stage = s; + }); + job.view.stage = "done"; + } catch (e) { + job.view.stage = "failed"; + job.view.error = + e instanceof ProveError + ? { code: e.code, message: this.scrub(e.message) } + : { code: "internal", message: "the relay failed while proving; try again" }; + if (!(e instanceof ProveError)) this.log(`proof job ${job.view.id} failed: ${this.scrub(String((e as Error).stack ?? e))}`); + } finally { + job.finishedAt = this.now(); + this.log(`proof job ${job.view.id} ${job.view.stage} in ${Math.round((job.finishedAt - started) / 1000)} s`); + this.running = null; + void this.pump(); + } + } + + private sweep(): void { + const cutoff = this.now() - this.keepMs; + for (const [id, job] of this.jobs) if (job.finishedAt !== undefined && job.finishedAt < cutoff) this.jobs.delete(id); + } +} diff --git a/be/src/relay/prove.test.ts b/be/src/relay/prove.test.ts new file mode 100644 index 0000000..85e31fc --- /dev/null +++ b/be/src/relay/prove.test.ts @@ -0,0 +1,112 @@ +/** + * Forepay #17: from an access token to `request_advance`'s arguments, with the + * borrower inside the signed claim, and every way it can stop before the attestor. + */ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { ProveError } from "../adsense/account.js"; +import { recoverSigner } from "../adsense/audit.js"; +import { CONTEXT_MESSAGE } from "../adsense/request.js"; +import { createSignDataForClaim, messageDigest } from "../reclaim/claim-digest.js"; +import { ALICE, ATTESTOR, BOB, NOW, PUB, Q3, TOKEN, fakeGoogle, fakeZkFetch, report } from "./fake-reclaim.js"; +import { proveRevenue, toAdvanceRequest, type ProveDeps, type ProveStep } from "./prove.js"; + +function deps(o: Partial = {}): ProveDeps { + return { google: fakeGoogle(), zkFetch: fakeZkFetch(), now: () => NOW, attestor: ATTESTOR, ...o }; +} + +async function code(p: Promise): Promise { + try { + await p; + } catch (e) { + assert.ok(e instanceof ProveError, String(e)); + return e.code; + } + assert.fail("expected a ProveError"); +} + +test("a proof comes back as request_advance's arguments, signed by the attestor", async () => { + const steps: ProveStep[] = []; + const zk = fakeZkFetch(); + const proven = await proveRevenue(deps({ zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN }, (s) => steps.push(s)); + assert.deepEqual(steps, ["checking", "proving", "auditing"]); + + const req = toAdvanceRequest(proven); + assert.deepEqual({ ...req, signature: "…" }, { + revenueUsd: "1234.56", + pubId: PUB, + windowStart: "2026-07-01", + windowEnd: "2026-09-30", + timestampS: String(Math.floor(NOW.getTime() / 1000) - 60), + epoch: "1", + signature: "…", + recoveryId: req.recoveryId, + }); + // The signature and recovery id are the ones verify_proof takes: they recover the attestor. + const c = proven.proof.claimData; + const digest = messageDigest(createSignDataForClaim({ identifier: c.identifier, owner: c.owner, timestampS: c.timestampS, epoch: c.epoch })); + assert.equal(recoverSigner(digest, Buffer.from(req.signature, "hex"), req.recoveryId), ATTESTOR); + assert.match(req.signature, /^[0-9a-f]{128}$/); +}); + +test("the borrower goes into the claim before signing, and the token only into the secret headers", async () => { + const zk = fakeZkFetch(); + await proveRevenue(deps({ zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN }); + const [url, options, secretOptions] = zk.calls[0]; + assert.deepEqual(options.context, { contextAddress: ALICE, contextMessage: CONTEXT_MESSAGE }); + assert.deepEqual(secretOptions.headers, { Authorization: `Bearer ${TOKEN}` }); + assert.ok(!JSON.stringify([url, options, secretOptions.responseMatches, secretOptions.responseRedactions]).includes(TOKEN)); +}); + +test("a proof whose signed context names someone else is refused, not returned", async () => { + const zk = fakeZkFetch({ context: { contextAddress: BOB } }); + assert.equal(await code(proveRevenue(deps({ zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN })), "audit"); +}); + +test("a proof that carries the token is refused", async () => { + const zk = fakeZkFetch({ context: { leaked: `Bearer ${TOKEN}` } }); + assert.equal(await code(proveRevenue(deps({ zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN })), "audit"); +}); + +test("an account Google will not report for stops before the attestor", async () => { + const zk = fakeZkFetch(); + const google = fakeGoogle({ state: "CLOSED" }); + assert.equal(await code(proveRevenue(deps({ google, zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN })), "account"); + assert.equal(zk.calls.length, 0); + assert.ok(!google.calls.some((u) => u.includes("reports:generate"))); +}); + +test("no AdSense account, or several, is the creator's to resolve", async () => { + assert.equal(await code(proveRevenue(deps({ google: fakeGoogle({ accounts: [] }) }), { borrower: ALICE, accessToken: TOKEN })), "account"); + const two = fakeGoogle({ accounts: [PUB, "pub-6543210987654321"] }); + assert.equal(await code(proveRevenue(deps({ google: two }), { borrower: ALICE, accessToken: TOKEN })), "account"); + // Naming one resolves it. + await proveRevenue(deps({ google: two }), { borrower: ALICE, accessToken: TOKEN, publisherId: PUB }); +}); + +test("an expired token stops at the first read", async () => { + const zk = fakeZkFetch(); + assert.equal(await code(proveRevenue(deps({ zkFetch: zk }), { borrower: ALICE, accessToken: "ya29.expired" })), "token"); + assert.equal(zk.calls.length, 0); +}); + +test("a report in another shape is caught locally, before minutes of proving", async () => { + const zk = fakeZkFetch(); + const { totals: _dropped, ...noTotals } = report(Q3); + void _dropped; + const google = fakeGoogle({ report: noTotals }); + assert.equal(await code(proveRevenue(deps({ google, zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN })), "provider"); + assert.equal(zk.calls.length, 0); +}); + +test("an attestor failure is a retryable prove error", async () => { + const zk = fakeZkFetch({ fail: new Error("invalid proof (ZK proof 0, startIdx 0, record 1)") }); + assert.equal(await code(proveRevenue(deps({ zkFetch: zk }), { borrower: ALICE, accessToken: TOKEN })), "prove"); +}); + +test("a C… or malformed borrower is refused before anything is read", async () => { + const google = fakeGoogle(); + await assert.rejects(proveRevenue(deps({ google }), { borrower: "GABC", accessToken: TOKEN }), /not a Stellar account/); + assert.equal(google.calls.length, 0); +}); diff --git a/be/src/relay/prove.ts b/be/src/relay/prove.ts new file mode 100644 index 0000000..178a478 --- /dev/null +++ b/be/src/relay/prove.ts @@ -0,0 +1,148 @@ +/** + * One AdSense revenue proof, from an access token to the arguments `request_advance` + * takes (#17). The relay runs this per request; `prove:adsense` runs it once. + * + * Why the proof is made here and not in the creator's browser: zkFetch with the + * snarkjs engine (the one Reclaim's attestor accepts, see #5) needs ~330 MB of circuit + * files and takes about ten minutes of CPU. Neither belongs in a browser tab. + * + * Where the binding comes from (#9, #17): the borrower's `G…` goes into + * `context.contextAddress` before zkFetch runs, so it is inside the bytes the attestor + * signs. The relay never attaches it afterwards, and the audit refuses a proof whose + * signed context names anyone else. + * + * The access token is used for the pre-flight reads and inside zkFetch's secret + * headers, and nowhere else. It is not stored, logged or returned; the audit fails a + * proof that contains it. + */ +import { auditRevenueProof, type AuditResult, type RevenueProof } from "../adsense/audit.js"; +import { ProveError, assertAccountReady, checkLiveResponse, resolvePublisherId, type GoogleGet } from "../adsense/account.js"; +import { + DEFAULT_TRAILING_MONTHS, + assertStellarAccount, + buildRevenueRequest, + trailingMonths, + withAccessToken, + type CivilDate, + type RevenueWindow, +} from "../adsense/request.js"; +import { prepareVerification } from "../reclaim/claim-digest.js"; + +/** `ReclaimClient.zkFetch`, bound to an engine. Returns the proof or nothing. */ +export type ZkFetch = ( + url: string, + options: ReturnType["options"], + secretOptions: ReturnType["secretOptions"], +) => Promise; + +export interface ProveDeps { + google: GoogleGet; + zkFetch: ZkFetch; + now?: () => Date; + months?: number; + /** Expected signer. Defaults to the production attestor; tests pass a throwaway key. */ + attestor?: string; +} + +export interface ProveInput { + borrower: string; + accessToken: string; + /** Optional; the only account the token can read when empty. */ + publisherId?: string; +} + +/** `checking`: the pre-flight reads. `proving`: zkFetch, minutes. `auditing`: local, instant. */ +export type ProveStep = "checking" | "proving" | "auditing"; + +export interface Proven { + proof: RevenueProof; + publisherId: string; + window: RevenueWindow; + audit: AuditResult; +} + +/** A proof made less than this long ago is accepted by the audit; the contract allows 1 h. */ +const MAX_AGE_S = 3600; + +export async function proveRevenue(deps: ProveDeps, input: ProveInput, onStep: (s: ProveStep) => void = () => {}): Promise { + assertStellarAccount(input.borrower); + if (!input.accessToken) throw new ProveError("token", "an access token is required"); + const { google } = deps; + + onStep("checking"); + const publisherId = await resolvePublisherId(google, input.accessToken, input.publisherId); + await assertAccountReady(google, input.accessToken, publisherId); + const window = trailingMonths((deps.now ?? (() => new Date()))(), deps.months ?? DEFAULT_TRAILING_MONTHS); + const request = buildRevenueRequest({ publisherId, stellarAddress: input.borrower, window }); + await checkLiveResponse(google, input.accessToken, request); + + onStep("proving"); + const call = withAccessToken(request, input.accessToken); + let proof: RevenueProof | undefined; + try { + proof = (await deps.zkFetch(call.url, call.options, call.secretOptions)) as RevenueProof | undefined; + } catch (e) { + throw new ProveError("prove", `zkFetch failed: ${(e as Error).message}`); + } + if (!proof) throw new ProveError("prove", "zkFetch returned no proof"); + + onStep("auditing"); + let audit: AuditResult; + try { + audit = auditRevenueProof(proof, { + publisherId, + stellarAddress: input.borrower, + window, + accessToken: input.accessToken, + now: deps.now?.(), + maxAgeS: MAX_AGE_S, + attestor: deps.attestor, + }); + } catch (e) { + throw new ProveError("audit", (e as Error).message); + } + return { proof, publisherId, window, audit }; +} + +/** + * `request_advance`'s arguments after the borrower's own, as the front end's + * `AdvanceRequest` takes them. `timestampS` and `epoch` are u64 on chain, so they are + * decimal strings here: JSON numbers lose precision past 2^53. + */ +export interface AdvanceRequestJson { + revenueUsd: string; + pubId: string; + windowStart: string; + windowEnd: string; + timestampS: string; + epoch: string; + /** 64 bytes, hex, no 0x. */ + signature: string; + recoveryId: number; +} + +export function isoDate(d: CivilDate): string { + return `${d.year}-${String(d.month).padStart(2, "0")}-${String(d.day).padStart(2, "0")}`; +} + +export function toAdvanceRequest({ proof, publisherId, window, audit }: Proven): AdvanceRequestJson { + const c = proof.claimData; + if (proof.signatures.length !== 1) throw new ProveError("audit", "expected exactly one attestor signature"); + // Rebuilds the identifier from the claim info: a claim info that is not what was + // signed is refused here rather than handed to the contract. + const v = prepareVerification( + { provider: c.provider, parameters: c.parameters, context: c.context }, + { identifier: c.identifier, owner: c.owner, timestampS: c.timestampS, epoch: c.epoch }, + proof.signatures[0], + ); + return { + revenueUsd: audit.revenueUsd, + pubId: publisherId, + windowStart: isoDate(window.start), + windowEnd: isoDate(window.end), + timestampS: String(c.timestampS), + epoch: String(c.epoch), + signature: v.sig64.toString("hex"), + recoveryId: v.recoveryId, + }; +} diff --git a/docs/api.md b/docs/api.md index 262e6ee..31d0b50 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,9 +1,9 @@ -# Forepay API (#16) +# Forepay API (#16, #17) -What the front end reads. Run it with `pnpm -C be start` (port 8787 by default). Configuration is in -`be/.env.example`. +What the front end reads, and the proof relay. Run it with `pnpm -C be start` (port 8787 by default). +Configuration is in `be/.env.example`. -Every route is `GET` and returns JSON. +Every route returns JSON. All are `GET` except `POST /proofs`. - **Amounts** are stroops: USDC has 7 decimals, so `10000000` = 1 USDC. - **Times** are seconds since the epoch. @@ -17,6 +17,8 @@ Every route is `GET` and returns JSON. | `/config` | The network, RPC, Horizon and contract addresses in use, where each came from, and whether they match `docs/deployments.md`. | | `/advances?borrower=G…` | Every advance the wallet took, newest first. | | `/transactions?borrower=G…` | Advances, repayments and the USDC trustline, newest first. Failed transactions are included. | +| `POST /proofs` | The relay (#17): prove the creator's AdSense revenue, bound to their `G…`. `202` with a job. See [the relay](#the-proof-relay-17). | +| `/proofs/:id` | The job's stage, then `request_advance`'s arguments, or why it failed. | ## Errors @@ -86,3 +88,110 @@ in the grant outlives that. A call counts as the borrower's only when the borrower's own wallet submitted it. That is how the front end submits every call. + +## The proof relay (#17) + +### The browser flow + +1. The creator connects their wallet (#19). That gives the `G…` the claim is bound to. +2. The front end opens **Google's own sign-in popup** with Google Identity Services (the token client, + `google.accounts.oauth2.initTokenClient`). It asks for one scope, + `https://www.googleapis.com/auth/adsense.readonly`, and gets back an access token that lasts an hour. + **No Reclaim SDK runs in the browser.** +3. The front end sends `POST /proofs` with the `G…` and the token, then polls `GET /proofs/:id`. +4. When the job is `done`, its `request` goes straight into `request_advance`, signed by the creator's + wallet. The relay never submits on the creator's behalf: `request_advance` requires the borrower's own + authorization (`docs/interface.md`). + +Why the proof is made on the relay and not in the browser: the proving engine Reclaim's attestor accepts +(`snarkjs`, see #5) needs about 330 MB of circuit files and takes about ten minutes of CPU. Reclaim's +browser SDKs (popup, QR, redirect) need a provider published in Reclaim's portal and a login inside +Reclaim's app; the AdSense provider (#4) is a zkFetch request to the AdSense Management API, which takes +an OAuth token instead. + +For `fe/src/lib/reclaim`'s `ProveStage`: `waiting` is while Google's popup is open; `reading` is from +`POST /proofs` until the job ends. + +The Google OAuth client is a **Web application** client, with the front end's origins as authorized +JavaScript origins. While the consent screen is in testing, only the test users listed on it can sign in. + +### What happens to the token + +It travels once, over HTTPS, in the body of `POST /proofs`. The relay uses it for three reads (which +account, is it `READY`, does the live report have the expected shape) and inside zkFetch's secret +headers, which stay out of the claim. It lives in memory for the length of the job: it is not written to +disk, logged, returned or kept after the job ends. A proof that contains it anywhere fails the audit and +is not returned. Error messages are scrubbed of it. + +### Where the binding comes from + +The `G…` is written into the claim's `context.contextAddress` **before** the attestor signs it, so it is +inside the signed bytes (#9). The relay checks the signed context names the requester before returning +anything, and the contract reads the borrower from that context, never from an argument. + +### `POST /proofs` + +```json +{ "borrower": "GA2C…WWH2", "accessToken": "ya29.…", "publisherId": "pub-1234567890123456" } +``` + +`publisherId` is optional: without it, the relay uses the only AdSense account the token can read. + +`202`, with `Location: /proofs/`: + +```json +{ "id": "423a114a-01d2-4a88-aa32-442fa961818f", "stage": "queued", "position": 0, "createdAt": 1792466795 } +``` + +| Status | When | +| --- | --- | +| `400` | Not JSON, a borrower that is not a `G…`, no token, or a malformed `publisherId` | +| `409` | A proof for this borrower is already in progress | +| `413` | Body over 8 KB | +| `503` | The relay is busy (`Retry-After: 120`), or not configured on this server (`/config` says `"relay": false`) | + +### `GET /proofs/:id` + +Poll every few seconds. `stage` goes `queued` → `checking` → `proving` → `auditing` → `done` or +`failed`. `position` is how many jobs are ahead while `queued`. One proof runs at a time. + +```json +{ + "id": "423a114a-…", + "stage": "done", + "createdAt": 1792466795, + "request": { + "revenueUsd": "1234.56", + "pubId": "pub-1234567890123456", + "windowStart": "2026-07-01", + "windowEnd": "2026-09-30", + "timestampS": "1792467390", + "epoch": "1", + "signature": "<64 bytes, hex>", + "recoveryId": 1 + } +} +``` + +`request` is `AdvanceRequest` in `fe/src/lib/stellar/contract.ts`, except that `timestampS` and +`epoch` are strings: pass them through `BigInt()`. The contract accepts the proof for an hour after +`timestampS`. + +A failed job has `error: { code, message }`. The code says whose move it is: + +| `code` | Meaning | What the creator can do | +| --- | --- | --- | +| `token` | Google refused the token: expired, or without `adsense.readonly` | Sign in again | +| `account` | No AdSense account, several (pass `publisherId`), or one that is not `READY` | Use an approved account | +| `provider` | AdSense answered in a shape the provider does not expect | Nothing; ours to fix | +| `prove` | The attestor or zkFetch failed | Try again | +| `audit` | The proof came back but failed the audit, so it was not returned | Nothing; ours to fix | +| `internal` | Anything else | Try again | + +`404` for an unknown id. Jobs are kept for an hour after they finish; a restart of the relay loses them. + +### Running it + +The relay is on when `RECLAIM_APP_ID` and `RECLAIM_APP_SECRET` are set and the circuit files are +present (`pnpm -C be zk:files`, about 330 MB). Otherwise the read routes still serve and `POST /proofs` +answers `503`. From c0b1cb413c8fd260a2aea4372f6a39db02791b65 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 20 Oct 2026 10:57:53 +0700 Subject: [PATCH 2/5] docs(#17): the API and the relay, public at api-forepay.jameshub.fun Deployed from feat/17-proof-relay with #74 merged in. /config reports the recorded addresses and relay: true; /ready answers. A smoke proof made on the host was signed by the production attestor in 54 s and passes verify_proof in simulation, with the one-byte flip refused as #5. --- docs/deployments.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/deployments.md b/docs/deployments.md index 6fd0ddf..1b6bed9 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -834,3 +834,45 @@ tests would have kept passing against bytes that described nothing. It is now pr The real attestor vector, `tools/fixtures/real-reclaim-proof.json`, is untouched. That one is signed by Reclaim's production attestor and proves the digest chain itself; this one proves the contract rebuilds the Forepay-specific bytes. + +--- + +## #16 / #17 — the API and the proof relay, public (2026-10-20) + +`https://api-forepay.jameshub.fun` runs `pnpm -C be start`: the read routes (#16) and the proof relay +(#17), as documented in `docs/api.md`. + +| | | +| --- | --- | +| Deployed tree | `feat/17-proof-relay` (`62d2cff`, which carries #16) merged with `feat/4-adsense-provider` (`eb6e078`, #74) | +| Host | Node 24, one LXC (2 cores, 2 GB), behind a Cloudflare Tunnel; a systemd unit restarts it on failure | +| `/config` | the recorded addresses, `"recorded": true`, `"relay": true` | +| `/ready` | `{"status":"ok"}` against `https://soroban-testnet.stellar.org` | +| CORS | `http://localhost:3000` only, until the front end's deployed origin is known (#22) | +| Secrets | the Reclaim app id and secret, in `be/.env`, `chmod 600`, owned by the service user. No Stellar secret key is on the host: the relay never signs. | + +Checked from outside: + +``` +GET /health 200 {"status":"ok"} +GET /config recorded: true, relay: true, advance CCQFL2…I2HS +GET /transactions?borrower=GA2CD6…WWH2 the USDC trustline (17a0d45d…); its advances went to the dev contract +GET /ready {"status":"ok","latestLedger":5288882} +``` + +The proving path works on this host. `prove:smoke` (#5's smoke request, Horizon's root, bound to +`GA2CD6…WWH2`) produced a claim in **54 s**, signed by the production attestor +`0x244897572368eadf65bfbc5aec98d8e5443a9072`. `verify:proof` simulated against Reclaim's verifier +`CA3EMXR6…H54DU5`: genuine digest **Ok**, one byte flipped `Error(Contract, #5) SignatureMismatch`. +The node process stayed under 500 MB. + +### What is not claimed yet + +- No AdSense proof has gone through it: there is no `READY` AdSense account (#5, #77). +- The tree is not `main`. Redeploy from `main` once #66, #73 and #74 merge. + +> **Updated while merging this (2026-10-20).** The second half of the first bullet — *"the contract +> cannot rebuild a real AdSense claim until the contract side of #6 lands"* — was true when written +> and is not now: #76 landed in #79, and #74 landed too. What is left is only the account. The +> deployed wasm carrying the new encoding is still behind its 24-hour timelock; `execute_upgrade` +> is not before 2026-10-21 08:50 UTC. From f867f36f809c5c3881c151b9870f8f34f09b7013 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 20 Oct 2026 10:58:18 +0700 Subject: [PATCH 3/5] docs(#17): proving takes about a minute on the relay host, not ten --- be/src/relay/jobs.ts | 2 +- be/src/relay/prove.ts | 3 ++- docs/api.md | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/be/src/relay/jobs.ts b/be/src/relay/jobs.ts index d99a2fa..703cd56 100644 --- a/be/src/relay/jobs.ts +++ b/be/src/relay/jobs.ts @@ -1,5 +1,5 @@ /** - * Proof jobs (#17): a proof takes about ten minutes, longer than any HTTP request + * Proof jobs (#17): a proof takes one to ten minutes, longer than any HTTP request * should stay open, so the relay takes the request, answers with a job id at once, * and the front end polls. * diff --git a/be/src/relay/prove.ts b/be/src/relay/prove.ts index 178a478..890bb7d 100644 --- a/be/src/relay/prove.ts +++ b/be/src/relay/prove.ts @@ -4,7 +4,8 @@ * * Why the proof is made here and not in the creator's browser: zkFetch with the * snarkjs engine (the one Reclaim's attestor accepts, see #5) needs ~330 MB of circuit - * files and takes about ten minutes of CPU. Neither belongs in a browser tab. + * files and minutes of CPU (about one on the relay host, ten on a laptop). Neither + * belongs in a browser tab. * * Where the binding comes from (#9, #17): the borrower's `G…` goes into * `context.contextAddress` before zkFetch runs, so it is inside the bytes the attestor diff --git a/docs/api.md b/docs/api.md index 31d0b50..f751c54 100644 --- a/docs/api.md +++ b/docs/api.md @@ -104,7 +104,7 @@ end submits every call. authorization (`docs/interface.md`). Why the proof is made on the relay and not in the browser: the proving engine Reclaim's attestor accepts -(`snarkjs`, see #5) needs about 330 MB of circuit files and takes about ten minutes of CPU. Reclaim's +(`snarkjs`, see #5) needs about 330 MB of circuit files and minutes of CPU (about one on the relay host, ten on a laptop). Reclaim's browser SDKs (popup, QR, redirect) need a provider published in Reclaim's portal and a login inside Reclaim's app; the AdSense provider (#4) is a zkFetch request to the AdSense Management API, which takes an OAuth token instead. From ef874c9cbd270b43ce176c897af9f44e7f4d0def Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 20 Oct 2026 22:21:59 +0700 Subject: [PATCH 4/5] feat(#17): relay errors carry a code: running, busy, unconfigured The front end has to tell "your proof is still running" from "the relay is full" from "the relay is not set up here", and the status alone cannot: 503 means two of them. Each refusal now says which in `code`. 409 deliberately does not return the running job's id. A borrower's address is public, and the id is what reads their revenue, so the front end keeps the id it was given with the 202 (review on #75). --- be/src/api/app.test.ts | 37 +++++++++++++++++++++++++++++++------ be/src/api/app.ts | 9 ++++++--- docs/api.md | 4 ++-- 3 files changed, 39 insertions(+), 11 deletions(-) diff --git a/be/src/api/app.test.ts b/be/src/api/app.test.ts index 99801b4..e5c8ceb 100644 --- a/be/src/api/app.test.ts +++ b/be/src/api/app.test.ts @@ -256,13 +256,13 @@ const REQUEST: AdvanceRequestJson = { }; const TOKEN = "ya29.a0-test-token"; -function relayApp(prover?: Prover) { +function relayApp(prover?: Prover, maxQueued?: number) { return createApp({ loaded: loadConfig({ CORS_ORIGINS: FRONT_END }), rpc: healthy, chain: fixtureChain, prover, - jobs: new ProofJobs({ log: () => {} }), + jobs: new ProofJobs({ log: () => {}, maxQueued }), }); } @@ -330,7 +330,7 @@ test("POST /proofs refuses what is not a proof request", async () => { } }); -test("a second proof for the same borrower while one runs is 409", async () => { +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( () => @@ -339,14 +339,39 @@ test("a second proof for the same borrower while one runs is 409", async () => { }), ); assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 202); - assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 409); + 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("without a prover the relay is off: 503, and /config says so", async () => { +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(); - assert.equal((await api.request(post({ borrower: BORROWER, accessToken: TOKEN }))).status, 503); + 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); }); diff --git a/be/src/api/app.ts b/be/src/api/app.ts index 38731eb..6b29cdc 100644 --- a/be/src/api/app.ts +++ b/be/src/api/app.ts @@ -166,7 +166,7 @@ export function createApp({ loaded, rpc, chain, prover, jobs = new ProofJobs(), bodyLimit({ maxSize: 8 * 1024, onError: (c) => c.json({ error: "request body too large" }, 413) }), async (c) => { c.header("Cache-Control", "no-store"); - if (!prover) return c.json({ error: "the proof relay is not configured on this server" }, 503); + if (!prover) return c.json({ error: "the proof relay is not configured on this server", code: "unconfigured" }, 503); let body: { borrower?: unknown; accessToken?: unknown; publisherId?: unknown }; try { body = await c.req.json(); @@ -193,8 +193,11 @@ export function createApp({ loaded, rpc, chain, prover, jobs = new ProofJobs(), ); return c.json(job, 202, { Location: `/proofs/${job.id}` }); } catch (e) { - if (e instanceof BorrowerBusyError) return c.json({ error: "a proof for this borrower is already in progress" }, 409); - if (e instanceof QueueFullError) return c.json({ error: "the relay is busy; try again in a few minutes" }, 503, { "Retry-After": "120" }); + // No job id here: a borrower's address is public, and the id is what reads their revenue. + if (e instanceof BorrowerBusyError) return c.json({ error: "a proof for this borrower is already in progress", code: "running" }, 409); + if (e instanceof QueueFullError) { + return c.json({ error: "the relay is busy; try again in a few minutes", code: "busy" }, 503, { "Retry-After": "120" }); + } throw e; } }, diff --git a/docs/api.md b/docs/api.md index f751c54..dfa8476 100644 --- a/docs/api.md +++ b/docs/api.md @@ -146,9 +146,9 @@ anything, and the contract reads the borrower from that context, never from an a | Status | When | | --- | --- | | `400` | Not JSON, a borrower that is not a `G…`, no token, or a malformed `publisherId` | -| `409` | A proof for this borrower is already in progress | +| `409` | A proof for this borrower is already in progress (`code: "running"`). The running job's id is not returned: a borrower's address is public, and the id reads their revenue. Keep the id from the `202` | | `413` | Body over 8 KB | -| `503` | The relay is busy (`Retry-After: 120`), or not configured on this server (`/config` says `"relay": false`) | +| `503` | The relay is busy (`code: "busy"`, `Retry-After: 120`), or not configured on this server (`code: "unconfigured"`; `/config` says `"relay": false`) | ### `GET /proofs/:id` From 4ceae582352b6412dd6fa23c38562f51653e6dd6 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 20 Oct 2026 22:25:52 +0700 Subject: [PATCH 5/5] fix(#17): refuse an access token too short to be Google's Scrubbing a one-character token out of a failure message cut that character out of every word ("e[redacted]pired"), seen live on the relay. Google's tokens run to hundreds of characters; under 16 is a 400. --- be/src/api/app.test.ts | 1 + be/src/api/app.ts | 4 +++- docs/api.md | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/be/src/api/app.test.ts b/be/src/api/app.test.ts index e5c8ceb..f8ef8e5 100644 --- a/be/src/api/app.test.ts +++ b/be/src/api/app.test.ts @@ -321,6 +321,7 @@ test("POST /proofs refuses what is not a proof request", async () => { [{ 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], ]; diff --git a/be/src/api/app.ts b/be/src/api/app.ts index 6b29cdc..547cb57 100644 --- a/be/src/api/app.ts +++ b/be/src/api/app.ts @@ -177,7 +177,9 @@ export function createApp({ loaded, rpc, chain, prover, jobs = new ProofJobs(), if (typeof borrower !== "string" || !StrKey.isValidEd25519PublicKey(borrower)) { return c.json({ error: "borrower must be a Stellar account address (G…)" }, 400); } - if (typeof accessToken !== "string" || !accessToken || accessToken.length > 4096) { + // Google's tokens run to hundreds of characters. A short string is not one, and scrubbing it out + // of error messages would cut every word it appears in. + if (typeof accessToken !== "string" || accessToken.length < 16 || accessToken.length > 4096) { return c.json({ error: "accessToken must be a Google OAuth access token with adsense.readonly" }, 400); } if (publisherId !== undefined && (typeof publisherId !== "string" || !/^pub-\d{16}$/.test(publisherId))) { diff --git a/docs/api.md b/docs/api.md index dfa8476..4535230 100644 --- a/docs/api.md +++ b/docs/api.md @@ -145,7 +145,7 @@ anything, and the contract reads the borrower from that context, never from an a | Status | When | | --- | --- | -| `400` | Not JSON, a borrower that is not a `G…`, no token, or a malformed `publisherId` | +| `400` | Not JSON, a borrower that is not a `G…`, no token or one too short to be Google's, or a malformed `publisherId` | | `409` | A proof for this borrower is already in progress (`code: "running"`). The running job's id is not returned: a borrower's address is public, and the id reads their revenue. Keep the id from the `202` | | `413` | Body over 8 KB | | `503` | The relay is busy (`code: "busy"`, `Retry-After: 120`), or not configured on this server (`code: "unconfigured"`; `/config` says `"relay": false`) |