From e6ab177a054ee46d63377a65725cec9d04c98f20 Mon Sep 17 00:00:00 2001 From: Inferencebot Date: Thu, 5 Nov 2026 15:54:29 +0000 Subject: [PATCH] credits: make the credit-pack webhook grant idempotent (audit H1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - reference built per-order from the webhook's order.idV2 (the id the amount lookup resolves) instead of the absent data.id that produced the legacy empty-suffix 'oc::' format; legacy ledger rows are neither re-keyed nor rejected (a new-format reference can never match one) - credit_reference_exists() gates add_credits; a re-delivered order returns 'already_credited' with the standing balance - hold path: one hold per purchase via a pre-check plus a UNIQUE index on held_credits.oc_reference (index creation logs CRITICAL and continues if the live table ever carried duplicates — audited: none) - get_order_amount sends the webhook-supplied order id as a GraphQL variable instead of interpolating it into the query (audit L9) - regression test: replay credits exactly once; legacy rows never block a first grant; unique-index semantics incl. NULLs --- app/main.py | 100 ++++++++++++++++- tests/test_credit_pack_idempotence.py | 154 ++++++++++++++++++++++++++ 2 files changed, 249 insertions(+), 5 deletions(-) create mode 100644 tests/test_credit_pack_idempotence.py diff --git a/app/main.py b/app/main.py index b3737a1..8973665 100644 --- a/app/main.py +++ b/app/main.py @@ -232,19 +232,24 @@ async def get_order_amount(order_id_v2: str | None) -> int | None: The webhook's `totalAmount` includes the buyer's optional OC tip, which the co-op never receives — credits must be granted on the tip-free amount. Returns cents, or None if unresolvable. + + The order id arrives from the OC webhook (untrusted input), so it is sent + as a GraphQL VARIABLE, never interpolated into the query string (audit L9, + 2026-11-05 — an interpolated id was a GraphQL injection into the + unauthenticated OC API; the variables form is parameterized by the server). """ if not order_id_v2: return None if order_id_v2 in _order_amount_cache: return _order_amount_cache[order_id_v2] try: - query = ('{ order(order: {id: "%s"}) { amount { valueInCents } ' - 'platformTipAmount { valueInCents } } }' % order_id_v2) + query = ("query OrderAmount($id: String!) { order(order: {id: $id}) " + "{ amount { valueInCents } platformTipAmount { valueInCents } } }") async with httpx.AsyncClient(timeout=15.0) as client: r = await client.post(OC_GRAPHQL_URL, headers={"Content-Type": "application/json", "User-Agent": "Mozilla/5.0 (X11; Linux x86_64)"}, - json={"query": query}) + json={"query": query, "variables": {"id": order_id_v2}}) o = r.json().get("data", {}).get("order") or {} cents = (o.get("amount") or {}).get("valueInCents") if cents is not None: @@ -255,6 +260,33 @@ async def get_order_amount(order_id_v2: str | None) -> int | None: return None +def credit_pack_reference(slug: str, order: dict | None) -> str: + """Stable idempotence key for a credit-pack purchase (audit H1, 2026-11-05). + + Keyed on the OC order id from the webhook payload (`order.idV2` — the id + `get_order_amount` resolves, so a VERIFIED purchase always carries one). + The webhook's top-level `data.id` is absent from real deliveries; building + the reference from it produced the legacy `oc::` empty-suffix + format, which cannot distinguish two purchases by the same member and so + cannot dedupe a re-delivered event. (The shortfall path keys on the OC + transaction publicId — equally unique; the webhook payload does not carry + it, and per this module's contract the collective order list is the + complete source for that shape, so no extra OC query is added here.) + + Legacy ledger rows in the empty-suffix format are neither re-keyed nor + rejected: a new-format reference (non-empty id suffix) can never match + one, so the exists-check never blocks a first real grant, and the + historical rows stay exactly as recorded. + """ + ref_id = str((order or {}).get("idV2") or "").strip() + if not ref_id: + raise ValueError( + "credit pack: webhook payload carries no order idV2; refusing to " + "build an ambiguous credit reference" + ) + return f"oc:{slug}:{ref_id}" + + # Personal token for the "Inference Co-op Bot" account, which is an admin of # the collective. Authenticated as an admin, the GraphQL API exposes member @@ -833,6 +865,20 @@ def get_db() -> sqlite3.Connection: "resolved_at TEXT" ")" ) + # Unique oc_reference (audit H1, 2026-11-05): an OC re-delivery must never + # create a second hold (or, via the webhook grant path's exists-check, a + # second credit) for the same purchase. Holds recorded before the fix used + # the legacy empty-suffix format and are distinct as audited, so the index + # applies cleanly to the live table; multiple NULLs stay legal (SQLite). + # If creation fails there are REAL duplicates — log CRITICAL and keep + # serving unguarded rather than boot-looping the portal. + try: + conn.execute( + "CREATE UNIQUE INDEX IF NOT EXISTS idx_held_credits_oc_reference " + "ON held_credits(oc_reference)" + ) + except sqlite3.OperationalError as e: + logger.error("held_credits.oc_reference unique index NOT created: %s", e) # Member-managed API keys: add a fingerprint (last-4 of the key, shown in # lists) and purge the stored plaintext. Member API keys are revealed ONCE @@ -2544,9 +2590,27 @@ async def opencollective_webhook(request: Request, token: str): "Credit pack: charged $%.2f including tip; granting tip-free $%.2f", charged, amount, ) - oc_ref = f"oc:{slug}:{data.get('id', '')}" + oc_ref = credit_pack_reference(slug, order) if email: + # Idempotence (audit H1, 2026-11-05): OC re-delivers events and + # this handler is slow (OC member fetch + email + Loomio + + # Matrix inside the request), which invites re-delivery. This + # purchase was already recorded once — return the standing + # balance WITHOUT crediting again. The reference is per-order, + # so this never blocks a new purchase, and legacy empty-suffix + # ledger rows can never match a new-format reference. + if credit_reference_exists(oc_ref): + logger.info( + "Credit pack: %s already in the ledger (OC re-delivery) " + "— not crediting again", oc_ref, + ) + return JSONResponse({ + "status": "already_credited", "email": email, + "credits_added": 0.0, + "credit_balance": get_credit_balance(email), + "reference": oc_ref, + }) # Member purchase → credits land immediately. new_balance = add_credits( email, amount, @@ -2580,12 +2644,38 @@ async def opencollective_webhook(request: Request, token: str): logger.warning("Credit-pack hold: payer lookup failed for %s: %s", slug, e) conn = get_db() + # Idempotence (audit H1, 2026-11-05): one hold per purchase. The + # unique index on oc_reference is the hard stop; this pre-check + # returns a calm response on re-delivery instead of a 500 (which + # would make OC re-deliver again). + existing = conn.execute( + "SELECT id FROM held_credits WHERE oc_reference = ?", (oc_ref,) + ).fetchone() + if existing: + conn.close() + logger.info( + "Credit pack HOLD: %s already recorded (hold #%s); not duplicating", + oc_ref, existing[0], + ) + return JSONResponse({ + "status": "hold_already_recorded", "slug": slug, + "hold_id": existing[0], + }) conn.execute( "INSERT INTO held_credits (slug, email, name, amount, oc_reference) " "VALUES (?, ?, ?, ?, ?)", (slug, buyer_email or None, buyer_name, amount, oc_ref), ) - conn.commit() + try: + conn.commit() + except sqlite3.IntegrityError: + # Lost a race with a concurrent delivery of the same order; + # the unique index kept us from double-holding. + conn.close() + logger.warning( + "Credit pack HOLD: %s raced an existing hold; not duplicating", oc_ref, + ) + return JSONResponse({"status": "hold_already_recorded", "slug": slug}) conn.close() logger.warning( diff --git a/tests/test_credit_pack_idempotence.py b/tests/test_credit_pack_idempotence.py new file mode 100644 index 0000000..7663e6c --- /dev/null +++ b/tests/test_credit_pack_idempotence.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +"""Regression tests for credit-pack webhook idempotence (audit H1, 2026-11-05). + +Runnable: + * from the repo root: python3 tests/test_credit_pack_idempotence.py + * inside the portal app: PORTAL_CODE_DIR=/app/code python3 /tmp/test_credit_pack_idempotence.py + (the container has the app's own dependencies; the host usually does not) + +WHY THIS EXISTS + The webhook credit-pack grant used to key its dedupe on `data.get('id')`, + which is absent from real OC deliveries — every recorded reference came out + `oc::` (empty suffix), so the key could not distinguish two purchases + by the same member, and NO exists-check guarded the grant at all. One + re-delivered (or replayed, or forged-but-OC-resolvable) event then credits + the pack a second time. + + Covered: + - the reference is built per-ORDER (per-purchase), non-empty + - a replayed order credits exactly once, even though the handler runs + twice (simulated by replaying the same grant sequence) + - a NEW order from the same member is never blocked by an earlier one + - a LEGACY empty-suffix ledger row neither matches nor rejects a new + grant (no re-shaping of historical rows — the invariant the fix + must respect) + - held_credits.oc_reference carries a UNIQUE index (one hold per + purchase; NULLs and distinct legacy refs stay legal) + - the DB starts with the unique index present even though legacy + rows exist (no duplicate live rows to violate it) +""" +import os +import sqlite3 +import sys +import tempfile + +_TEST_DB = os.path.join(tempfile.mkdtemp(prefix="creditpack-test-"), "members.db") +os.environ["DB_PATH"] = _TEST_DB # must exist BEFORE app.main is imported + +# Locate the app package: explicit env, the deployed path, or the repo root. +for _cand in (os.environ.get("PORTAL_CODE_DIR"), "/app/code", + os.path.dirname(os.path.dirname(os.path.abspath(__file__)))): + if _cand and os.path.isfile(os.path.join(_cand, "app", "main.py")): + sys.path.insert(0, _cand) + break + +from app.main import ( # noqa: E402 + add_credits, credit_pack_reference, credit_reference_exists, get_credit_balance, get_db, +) + +failures = 0 + + +def check(name, got, want): + global failures + ok = got == want + if not ok: + failures += 1 + print(f"[{'PASS' if ok else 'FAIL'}] {name}") + if not ok: + print(f" got {got!r}\n want {want!r}") + + +def grant_once(email, amount, ref): + """The exact grant sequence the webhook now runs (exists-check gates add).""" + if credit_reference_exists(ref): + return "already_credited" + add_credits(email, amount, reason="credit pack purchase (Open Collective)", reference=ref) + return "credits_added" + + +# --- reference building: per-order, non-empty, distinct per purchase --- +check("reference keyed on the order id", + credit_pack_reference("caseyg", {"idV2": "or_abc123"}), "oc:caseyg:or_abc123") +check("two purchases differ even from one member", + credit_pack_reference("caseyg", {"idV2": "or_1"}) != credit_pack_reference("caseyg", {"idV2": "or_2"}), + True) +try: + credit_pack_reference("caseyg", {}) + check("missing order idV2 refused (no ambiguous/empty reference)", False, True) + credit_pack_reference("caseyg", {"idV2": ""}) + check("empty order idV2 refused", False, True) +except ValueError: + check("missing/empty order idV2 refused (no ambiguous/empty reference)", True, True) + +# --- replay on a real (temporary) DB: one replay = exactly one credit --- +conn = get_db() # initializes schema (incl. the unique index) on the temp db +conn.execute("INSERT INTO members (email, key_token, active) VALUES ('p@example.com', '', 1)") +conn.commit() + +ref_a = credit_pack_reference("p", {"idV2": "or_test_a"}) +r1 = grant_once("p@example.com", 10.0, ref_a) # first delivery +r2 = grant_once("p@example.com", 10.0, ref_a) # re-delivery of the SAME order +check("first delivery grants", r1, "credits_added") +check("replay of the same order is refused", r2, "already_credited") +n = conn.execute("SELECT COUNT(*) FROM credit_ledger WHERE reference = ?", (ref_a,)).fetchone()[0] +check("exactly ONE ledger row for the replayed order", n, 1) +check("balance credited once (10, not 20)", get_credit_balance("p@example.com"), 10.0) + +# --- a NEW purchase from the same member is never blocked --- +ref_b = credit_pack_reference("p", {"idV2": "or_test_b"}) +r3 = grant_once("p@example.com", 5.0, ref_b) +check("a different order still credits normally", r3, "credits_added") +check("balance includes the second purchase", get_credit_balance("p@example.com"), 15.0) + +# --- legacy empty-suffix rows: never matched, never reshaped --- +grant_once("legacy@example.com", 23.0, "oc:caseyg:") # simulate a pre-fix ledger row +legacy_rows = conn.execute( + "SELECT COUNT(*) FROM credit_ledger WHERE reference = 'oc:caseyg:'").fetchone()[0] +check("legacy row stored exactly as it was written", legacy_rows, 1) +new_from_legacy_member = credit_pack_reference("caseyg", {"idV2": "or_new"}) +check("a new purchase does NOT match the legacy empty-suffix row", + credit_reference_exists(new_from_legacy_member), False) +check("a new purchase by the legacy member credits normally", + grant_once("legacy@example.com", 15.0, new_from_legacy_member), "credits_added") +still = conn.execute( + "SELECT COUNT(*) FROM credit_ledger WHERE reference = 'oc:caseyg:'").fetchone()[0] +check("the legacy row was neither rejected nor re-shaped", still, 1) + +# --- held_credits.oc_reference: UNIQUE index semantics --- +idx = conn.execute( + "SELECT name FROM sqlite_master WHERE type='index' AND name='idx_held_credits_oc_reference'" +).fetchone() +check("unique index exists on a fresh (and the live-shaped) db", bool(idx), True) + +conn.execute( + "INSERT INTO held_credits (slug, email, name, amount, oc_reference, status) " + "VALUES ('buyer-a', NULL, 'Buyer A', 20.0, 'oc:buyer-a:or_h1', 'held')") +try: + conn.execute( + "INSERT INTO held_credits (slug, email, name, amount, oc_reference, status) " + "VALUES ('buyer-a', NULL, 'Buyer A', 20.0, 'oc:buyer-a:or_h1', 'held')") + conn.commit() + check("second hold for the SAME order rejected by the unique index", False, True) +except sqlite3.IntegrityError: + conn.rollback() + check("second hold for the SAME order rejected by the unique index", True, True) + +conn.execute( + "INSERT INTO held_credits (slug, email, name, amount, oc_reference, status) " + "VALUES ('buyer-b', NULL, 'Buyer B', 10.0, 'oc:buyer-b:or_h2', 'held')") +conn.commit() +check("a different purchase still gets its own hold", True, True) + +conn.execute( + "INSERT INTO held_credits (slug, email, name, amount, oc_reference, status) " + "VALUES ('unknown', NULL, NULL, 10.0, NULL, 'held')") +conn.execute( + "INSERT INTO held_credits (slug, email, name, amount, oc_reference, status) " + "VALUES ('unknown', NULL, NULL, 10.0, NULL, 'held')") +conn.commit() +check("NULL oc_reference rows stay legal (index does not overblock)", True, True) + +conn.close() +print(f"\n{'FAILED' if failures else 'OK'} — {failures} failure(s)") +sys.exit(1 if failures else 0)