Canary hardening + honest first-party attribution (first mainnet settlement)

Post-settlement fixes for tx 0x1052fa51aa1412119581194acc1011c51786a59538f46bb5f9d593f1ad16d802 (0.01 USDC, Base mainnet, independently confirmed).

Canary hardening (GPT engineer, CTO-verified): did:web receipt verification resolves the kid ONLY via the trusted configured origin's /.well-known/did.json (hostile-but-valid did:web signers refused; legacy did:key kids still resolvable; receipt payer must match settled payer); payment-state file 0600; idempotent recovery may observe zero-or-one new settlements on replay, first send still requires exactly one; evidence artifact updated with the real settlement + idempotent_replay flag.

Attribution fix (root cause of the unverified_payer mislabel: the canary paid with NO first-party tagging): (1) canary now tags every request via X-Agent-Guild-First-Party — token from GUILD_FIRST_PARTY_TOKEN env or the gitignored live/secrets/first_party_token — and REFUSES --execute untagged unless --allow-untagged; evidence records first_party_tagged. (2) effective_payer_attribution(): read-time, config-aware attribution for /billing/revenue + funnel; a record STORED unverified_payer whose payer is in GUILD_X402_FIRST_PARTY_PAYERS (or first_party_payer=True) reads as verified_first_party_canary. Upgrades move TOWARD first-party only (can only weaken an externality claim); bound/attested records never relabeled; append-only stored labels untouched.

Tests: attribution-honesty +2, canary +4; full suites green in JSON and SQLite store modes (905 passed / 9 skipped each), verified in a clean cloud env.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PogUzTjFFU7P4Q9EoY1Nrm

Author: AgentTanuki

artifacts/first_party_mainnet_canary_evidence.json

@@ -1,26 +1,95 @@
 {
   "label": "first_party_mainnet_canary",
-  "mode": "dry_run",
-  "disclaimer": "First-party canary DRY RUN. Preconditions + signed offer verified; NO signature produced, NO funds moved. NOT a payment, NOT revenue, NOT external adoption.",
+  "disclaimer": "First-party canary. A successful settlement is proof the machine-payment loop works end-to-end; it is NOT external adoption and NOT customer revenue.",
   "target": "https://agent-guild-5d5r.onrender.com",
-  "requested_resource": "https://agent-guild-5d5r.onrender.com/check?capability=code-review",
-  "canonical_resource": "https://agent-guild-5d5r.onrender.com/check?capability=code-review&signed=false&ttl_seconds=3600",
+  "production_sha": "",
+  "resource": "https://agent-guild-5d5r.onrender.com/check?capability=code-review&signed=false&ttl_seconds=3600",
+  "request_hash": null,
   "network": "eip155:8453",
   "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
   "recipient": "0xaa4E3ba0Eb5f564cAb54dDC08f5BaAfb3D4cA8E5",
-  "chain_id": 8453,
   "amount_atomic": "10000",
   "amount_usdc": 0.01,
   "lifetime_cap_usdc": 0.01,
-  "signed_offer_verified": true,
   "revenue_before": {
-    "transactions": 0,
-    "revenue_usd": 0.0,
-    "networks": [],
-    "transaction_hashes": [],
-    "note": "zero: no independently confirmed mainnet settlement exists (testnet/sandbox/unconfirmed activity is value-less and listed under testnet_settlement)"
+    "transactions": 1,
+    "revenue_usd": 0.01,
+    "networks": [
+      "eip155:8453"
+    ],
+    "transaction_hashes": [
+      "0x1052fa51aa1412119581194acc1011c51786a59538f46bb5f9d593f1ad16d802"
+    ],
+    "attribution": {
+      "verified_first_party_canary": {
+        "transactions": 0,
+        "revenue_usd": 0.0
+      },
+      "cryptographically_bound_machine_payer": {
+        "transactions": 0,
+        "revenue_usd": 0.0
+      },
+      "independently_attested_external_machine": {
+        "transactions": 0,
+        "revenue_usd": 0.0
+      },
+      "unverified_payer": {
+        "transactions": 1,
+        "revenue_usd": 0.01
+      }
+    },
+    "cryptographically_bound_machine_revenue_usd": 0.0,
+    "independently_attested_external_revenue_usd": 0.0,
+    "note": "counts ONLY mainnet settlements independently CONFIRMED on-chain; `attribution` splits them into verified_first_party_canary (Guild identity, never external), cryptographically_bound_machine_payer (valid caller proof + exact (address, network) wallet binding \u2014 identity proven, ownership/externality UNPROVEN), independently_attested_external_machine (a SEPARATE allowlisted issuer attests externality) and unverified_payer (missing proof is UNKNOWN, never external). Unknown ownership is never called verified external."
   },
-  "generation_note": "Produced against a LOCAL mainnet-shaped stack with a fake RPC (chainId 8453) \u2014 no real network call, no signing, no key. Illustrates the artifact shape --execute would emit with real settlement fields added.",
-  "result": "DRY RUN CLEAN \u2014 refused to sign",
-  "timestamp": "2026-07-15T03:53:31Z"
+  "mode": "execute",
+  "timestamp": "2026-07-21T07:30:25Z",
+  "result": "settled_and_confirmed",
+  "payer": "0x6904b3E1a5007C94b195d054CF2ca06B43a5C45c",
+  "transaction": "0x1052fa51aa1412119581194acc1011c51786a59538f46bb5f9d593f1ad16d802",
+  "block_number": "0x2ea6123",
+  "payment_response": {
+    "success": true,
+    "network": "eip155:8453",
+    "transaction": "0x1052fa51aa1412119581194acc1011c51786a59538f46bb5f9d593f1ad16d802",
+    "payer": "0x6904b3E1a5007C94b195d054CF2ca06B43a5C45c"
+  },
+  "independent_confirmation": {
+    "confirmed": true,
+    "reason": "confirmed",
+    "block_number": "0x2ea6123"
+  },
+  "revenue_after": {
+    "transactions": 1,
+    "revenue_usd": 0.01,
+    "networks": [
+      "eip155:8453"
+    ],
+    "transaction_hashes": [
+      "0x1052fa51aa1412119581194acc1011c51786a59538f46bb5f9d593f1ad16d802"
+    ],
+    "attribution": {
+      "verified_first_party_canary": {
+        "transactions": 0,
+        "revenue_usd": 0.0
+      },
+      "cryptographically_bound_machine_payer": {
+        "transactions": 0,
+        "revenue_usd": 0.0
+      },
+      "independently_attested_external_machine": {
+        "transactions": 0,
+        "revenue_usd": 0.0
+      },
+      "unverified_payer": {
+        "transactions": 1,
+        "revenue_usd": 0.01
+      }
+    },
+    "cryptographically_bound_machine_revenue_usd": 0.0,
+    "independently_attested_external_revenue_usd": 0.0,
+    "note": "counts ONLY mainnet settlements independently CONFIRMED on-chain; `attribution` splits them into verified_first_party_canary (Guild identity, never external), cryptographically_bound_machine_payer (valid caller proof + exact (address, network) wallet binding \u2014 identity proven, ownership/externality UNPROVEN), independently_attested_external_machine (a SEPARATE allowlisted issuer attests externality) and unverified_payer (missing proof is UNKNOWN, never external). Unknown ownership is never called verified external."
+  },
+  "idempotent_replay": true,
+  "result_sha256": "defeee4e141c49b42b38134da858ca734fb0af4057b899bcb549fcb74b6892a2"
 }

live/guild/app/payments.py

@@ -996,6 +996,35 @@ def normalize_payer_attribution(label: Any) -> str:
     return _LEGACY_ATTRIBUTION.get(str(label), "unverified_payer")
 
 
+def effective_payer_attribution(record: dict) -> str:
+    """Read-time attribution for a stored settlement record.
+
+    Normalizes the stored label, then applies EXACTLY ONE conservative
+    upgrade: a record stored as `unverified_payer` ("unknown, never
+    external") whose payer address is in the CONFIGURED Guild canary wallet
+    allowlist (GUILD_X402_FIRST_PARTY_PAYERS) — or whose token-gated
+    first_party_payer flag is True — is read as
+    `verified_first_party_canary`. Configuration supplies knowledge the
+    server lacked at settlement time (the 2026-07-21 canary settled before
+    its wallet was configured), and the upgrade only ever moves a record
+    TOWARD first-party, i.e. it can only WEAKEN an externality claim.
+
+    Never applied to bound/attested records, never downgrades, never
+    invents externality; append-only history stays untouched."""
+    import os as _os
+    cls = normalize_payer_attribution(record.get("payer_attribution"))
+    if cls != "unverified_payer":
+        return cls
+    if record.get("first_party_payer") is True:
+        return "verified_first_party_canary"
+    payer = str(record.get("payer") or "").lower()
+    fp_payers = {p.strip().lower() for p in (_os.environ.get(
+        "GUILD_X402_FIRST_PARTY_PAYERS") or "").split(",") if p.strip()}
+    if payer and payer in fp_payers:
+        return "verified_first_party_canary"
+    return cls
+
+
 def classify_payer_attribution(store: Any, *, payer: str,
                                network: str = "",
                                caller_did: str = "",

live/guild/app/store.py

@@ -2945,11 +2945,10 @@ def _class_of(e: dict[str, Any]) -> str:
                 mainnet["external"] += 1
             else:
                 mainnet["unknown"] += 1
-            att = b.get("payer_attribution")
-            if att is None and (fp_flag is True
-                                or (payer and payer in fp_payers)):
-                att = "verified_first_party_canary"
-            crypto_att[_payments.normalize_payer_attribution(att)] += 1
+            # read-time, config-aware (effective_): a configured canary
+            # wallet stored as unverified_payer reads as
+            # verified_first_party_canary — upgrades toward first-party only.
+            crypto_att[_payments.effective_payer_attribution(b)] += 1
 
         endpoint_verified_now = sum(
             1 for a in self.agents.values()
@@ -4696,8 +4695,10 @@ def _usd(rows: list) -> float:
         att_classes: dict[str, list] = {
             c: [] for c in _payments.ATTRIBUTION_CLASSES}
         for b in x402_mainnet:
-            att_classes[_payments.normalize_payer_attribution(
-                b.get("payer_attribution"))].append(b)
+            # effective_: read-time, config-aware, upgrade-toward-first-party
+            # only (a configured canary wallet stored as unverified_payer
+            # reads as verified_first_party_canary; never the reverse).
+            att_classes[_payments.effective_payer_attribution(b)].append(b)
         out["real_settlement"] = {
             # real_settlement counts ALL independently confirmed money,
             # regardless of attribution (money is money).

live/guild/tests/test_attribution_honesty.py

@@ -290,6 +290,74 @@ def test_legacy_verified_external_records_reinterpreted_conservatively():
     assert att["cryptographically_bound_machine_payer"]["transactions"] >= 1
 
 
+def test_configured_canary_wallet_upgrades_unverified_at_read(monkeypatch):
+    """The 2026-07-21 defect: the first real mainnet canary settled WITHOUT
+    first-party tagging and was stored `unverified_payer` (honest: unknown).
+    Configuring that wallet in GUILD_X402_FIRST_PARTY_PAYERS re-reads the
+    stored record as verified_first_party_canary — configuration supplies
+    the knowledge missing at settlement time. The upgrade moves records
+    TOWARD first-party only; it is read-time and reversible with the
+    config, and the append-only stored label is untouched."""
+    from app.main import app
+    canary_wallet = "0x" + "77" * 20
+    tx = "0x" + "cd" * 32
+    store.billing_log.append({
+        "key": "x402", "type": "x402_payment", "endpoint": "check",
+        "network": MAINNET, "amount_atomic": "10000",
+        "payer": canary_wallet, "transaction": tx,
+        "status": "settled_confirmed", "mainnet": True, "confirmed": True,
+        "payer_attribution": "unverified_payer",
+        "first_party_payer": None, "at": "2026-07-21T05:00:00Z"})
+
+    def _read():
+        with TestClient(app) as client:
+            return client.get("/billing/revenue").json()["real_settlement"]
+
+    before = _read()["attribution"]
+    assert before["verified_first_party_canary"]["transactions"] == 0
+    assert before["unverified_payer"]["transactions"] >= 1
+
+    monkeypatch.setenv("GUILD_X402_FIRST_PARTY_PAYERS",
+                       canary_wallet.upper())        # case-insensitive
+    after = _read()
+    att = after["attribution"]
+    assert att["verified_first_party_canary"]["transactions"] == 1
+    assert att["verified_first_party_canary"]["revenue_usd"] == \
+        pytest.approx(0.01)
+    assert att["unverified_payer"]["transactions"] == \
+        before["unverified_payer"]["transactions"] - 1
+    # stored label untouched (append-only history)
+    assert store.billing_log[-1]["payer_attribution"] == "unverified_payer"
+
+
+def test_effective_attribution_upgrades_toward_first_party_only(monkeypatch):
+    """effective_payer_attribution never relabels proven classes, never
+    downgrades, and never moves any record toward external."""
+    canary_wallet = "0x" + "77" * 20
+    monkeypatch.setenv("GUILD_X402_FIRST_PARTY_PAYERS", canary_wallet)
+    # a BOUND record for the configured wallet stays bound (proof wins)
+    assert payments.effective_payer_attribution({
+        "payer_attribution": "cryptographically_bound_machine_payer",
+        "payer": canary_wallet}) == "cryptographically_bound_machine_payer"
+    # token-gated flag upgrades a stored-unknown record
+    assert payments.effective_payer_attribution({
+        "payer_attribution": "unverified_payer", "payer": "0x" + "88" * 20,
+        "first_party_payer": True}) == "verified_first_party_canary"
+    # unknown wallet, no flag: stays unverified
+    assert payments.effective_payer_attribution({
+        "payer_attribution": None,
+        "payer": "0x" + "99" * 20}) == "unverified_payer"
+    # legacy retired label still reinterprets as bound, config or not
+    assert payments.effective_payer_attribution({
+        "payer_attribution": "verified_external_machine",
+        "payer": canary_wallet}) == "cryptographically_bound_machine_payer"
+    monkeypatch.delenv("GUILD_X402_FIRST_PARTY_PAYERS")
+    # without config the same stored-unknown record reads unverified again
+    assert payments.effective_payer_attribution({
+        "payer_attribution": "unverified_payer",
+        "payer": canary_wallet}) == "unverified_payer"
+
+
 # ---------------------------------------------------------------------------
 # the independent-attestation mechanism: real, but honestly zero by default
 # ---------------------------------------------------------------------------

live/guild/tests/test_first_party_canary.py

@@ -7,8 +7,10 @@
 pay-before-state-is-impossible one-shot file.
 """
 import importlib.util
+import base64
 import json
 import pathlib
+import stat
 import types
 
 import pytest
@@ -308,6 +310,65 @@ def test_state_roundtrip_is_atomic(tmp_path):
                            "signed_payload": "xyz"})
     assert canary._load_state(p)["status"] == "signed"
     assert canary._load_state(p)["signed_payload"] == "xyz"
+    assert stat.S_IMODE(p.stat().st_mode) == 0o600
+
+
+def test_signed_receipt_resolves_trusted_did_web(monkeypatch):
+    monkeypatch.setenv("GUILD_PUBLIC_HOST", "https://guild.example")
+    from app.state import store
+    identity = store.guild_identity()
+    resource = _resource()
+    payer = "0x" + "12" * 20
+    tx = "0x" + "34" * 32
+    payload = artifacts.receipt_payload(
+        network="eip155:8453", resource_url=resource, payer=payer,
+        transaction=tx, issued_at=1,
+    )
+    receipt = artifacts.signed_receipt(identity, payload)
+    raw = {
+        "extensions": {
+            "offer-receipt": artifacts.offer_receipt_settle_extension(receipt)
+        }
+    }
+
+    class Response:
+        headers = {
+            x402.PAYMENT_RESPONSE_HEADER:
+                base64.b64encode(json.dumps(raw).encode()).decode()
+        }
+
+    assert canary._verify_settle_receipt(
+        Response(), resource, payer, tx, http=_did_http(),
+    )
+    assert not canary._verify_settle_receipt(
+        Response(), resource, "0x" + "99" * 20, tx, http=_did_http(),
+    )
+
+
+def test_revenue_transition_allows_idempotent_recovery_only():
+    tx = "0x" + "56" * 32
+    before = {"transactions": 1, "transaction_hashes": [tx]}
+    unchanged = {"transactions": 1, "transaction_hashes": [tx]}
+    increased = {"transactions": 2, "transaction_hashes": [tx]}
+
+    canary._verify_revenue_transition(
+        before, unchanged, tx, replayed_signed_payload=True,
+    )
+    canary._verify_revenue_transition(
+        before, increased, tx, replayed_signed_payload=True,
+    )
+    canary._verify_revenue_transition(
+        before, increased, tx, replayed_signed_payload=False,
+    )
+    with pytest.raises(canary.Refuse, match="exactly one"):
+        canary._verify_revenue_transition(
+            before, unchanged, tx, replayed_signed_payload=False,
+        )
+    with pytest.raises(canary.Refuse, match="not in real_settlement"):
+        canary._verify_revenue_transition(
+            before, {"transactions": 2, "transaction_hashes": []}, tx,
+            replayed_signed_payload=False,
+        )
 
 
 def test_discovery_falls_back_to_canonical_check():
@@ -324,3 +385,34 @@ def test_evidence_is_labelled_first_party_and_secretless(tmp_path):
     canary._write_evidence(p, ev)
     loaded = json.loads(p.read_text())
     assert loaded["label"] == "first_party_mainnet_canary"
+
+
+def test_execute_refuses_without_first_party_tagging(monkeypatch, tmp_path):
+    """--execute without GUILD_FIRST_PARTY_TOKEN would settle a payment the
+    server can only classify unverified_payer (the 2026-07-21 mislabel) —
+    refuse BEFORE any network traffic unless --allow-untagged."""
+    monkeypatch.delenv("GUILD_FIRST_PARTY_TOKEN", raising=False)
+    monkeypatch.setattr(canary, "DEFAULT_FP_TOKEN_FILE",
+                        tmp_path / "absent_token")
+    args = types.SimpleNamespace(
+        base="https://guild.example", execute=True, dry_run=False,
+        allow_untagged=False, state=str(tmp_path / "state.json"),
+        evidence=str(tmp_path / "ev.json"), key_file=None, expect_sha=None)
+    with pytest.raises(canary.Refuse, match="first-party tagging"):
+        canary.run(args)
+    assert not (tmp_path / "state.json").exists()
+
+
+def test_first_party_headers_env_then_token_file(monkeypatch, tmp_path):
+    monkeypatch.delenv("GUILD_FIRST_PARTY_TOKEN", raising=False)
+    missing = tmp_path / "absent_token"
+    monkeypatch.setattr(canary, "DEFAULT_FP_TOKEN_FILE", missing)
+    assert canary._first_party_headers() == {}
+    token_file = tmp_path / "first_party_token"
+    token_file.write_text("file-secret\n")
+    monkeypatch.setattr(canary, "DEFAULT_FP_TOKEN_FILE", token_file)
+    assert canary._first_party_headers() == {
+        "X-Agent-Guild-First-Party": "file-secret"}
+    monkeypatch.setenv("GUILD_FIRST_PARTY_TOKEN", "env-secret")  # env wins
+    assert canary._first_party_headers() == {
+        "X-Agent-Guild-First-Party": "env-secret"}