fix(samples): fail closed in x402 PSP when agent-provider key is missing

[chopmob-cloud]

Summary

The x402 PSP settle_payment skipped SD-JWT mandate verification when the agent-provider public key could not be loaded, and then continued to binding, ecrecover and settlement. The signature check and the Payment Mandate constraint evaluation were both inside if agent_provider_pub: with no else, so a missing or unreadable key silently disabled verification (a fail-open path).

Two sibling roles already fail closed on exactly this condition:

• merchant_agent_mcp/server.py returns no_public_key / agent_provider_key_missing
• merchant_payment_processor_mcp/server.py returns agent_provider_key_missing

This change makes the settlement role consistent: it returns agent_provider_key_missing when the key cannot be loaded, before any binding or settlement step. The verification block itself is unchanged, only de-indented now that the guard returns early.

Verification

Reproduced the branch directly against settle_payment (it is a plain function under @mcp.tool()):

• key present, malformed mandate: returns mandate_verification_failed (verification runs).
• key absent, before this change: verification is skipped and execution reaches Step 1 binding.
• key absent, after this change: returns agent_provider_key_missing, binding is never reached.

Tests

Adds code/samples/python/tests/:

• settle_payment_failclosed_tests.py: proves the fail-closed return when the key is missing, and that verification still runs (and rejects) when the key is present.
• conftest.py: puts the samples src on sys.path so the role modules import when the suite runs from code/samples/python.

Both pass locally on Python 3.12. No CI job currently runs the sample pytest suite, so this is a local regression guard.

Notes

• Also adds domain terms already present in x402_psp_mcp/server.py (fastmcp, sdjwt, keccak, toggleable, usdc, gwei, levelname, sepolia) to .cspell/custom-words.txt so the touched file passes the spellcheck job, which checks the whole changed file.
• Filed in response to the observation in [Bug]: x402 PSP continues without mandate verification when the agent-provider key is unavailable, while two other roles refuse #309. Whether the sample intended to tolerate a missing verification key for local demonstration is a maintainer call; either way this keeps the three verifying roles consistent and avoids a silent skip of signature verification.

Refs #309

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[giorgioroth]

Thanks for picking this up. Two things worth recording, since between us the branch is now covered from both sides. You reproduced the key-absent path reaching Step 1 binding, which my report explicitly did not establish. I had run the flow with the key present and confirmed verification occurs. It is no longer a source observation.

The diff reads correctly to me. Both loss paths leave agent_provider_pub as None — the missing file and the read error — and the early return keys on the variable rather than on the failure mode, so it catches both. The verification block is unchanged, only de-indented. The second test is the one that matters: it proves verification still runs and rejects when the key is present, which is what stops a fail-closed fix from quietly becoming a fail-always one.

One thing you fixed that was not in my report: the except branch previously logged "key not found — skipping" for a corrupt or unreadable file, which was inaccurate, and used warning rather than exception, which lost the traceback. _logger.exception("Failed to load agent-provider public key") is the right message for that path.

On the failing check — BIOME_LINT is the only one red, and this PR touches three Python files. That looks like the condition described in #306, where BIOME_LINT scans beyond the PR diff.

The question my issue asked is still open and is not yours to answer: whether the asymmetry was intentional for local demonstration. The fix is right either way.

[Silentpartnercoding]

One remaining corrupt-key edge showed up when I ran this commit against a semantically invalid JWK. With AGENT_PROVIDER_PUB_PATH containing {}, JWK.from_json() raises jwcrypto.jwk.InvalidJWKType; that is a JWException, not a ValueError or JSONDecodeError, so it escapes the new guard before agent_provider_key_missing is returned.

I verified that importing JWException from jwcrypto.common and including it in the key-load exception tuple makes this case fail closed. A regression case using {} (rather than non-JSON text) would cover the library-level key-validation branch. The missing-key and valid-key tests otherwise look right.

[chopmob-cloud]

Thanks @Silentpartnercoding, confirmed and fixed. JWK.from_json("{}") does raise jwcrypto.jwk.InvalidJWKType (a JWException), which escaped the (OSError, ValueError, JSONDecodeError) guard.

While adding that, an adversarial pass over the key-load path turned up a related family: a key file that is valid JSON but not an object ([], null, 123) makes JWK.from_json raise TypeError, which also escaped and propagated. Rather than enumerate library exception types (which this shows is leaky), I changed the key-load except to catch broadly, so any failure to load or validate the key (missing, unreadable, malformed JSON, wrong JSON type, or invalid JWK) fails closed via the existing agent_provider_key_missing guard.

The regression test is now parametrized over invalid-JWK, non-object-JSON and empty-file inputs. Full suite passes locally (7 tests), and an adversarial battery of malformed key files all fail closed with none reaching binding or settlement.

Thanks also @giorgioroth for the review. The BIOME_LINT red looks like the #306 condition (it scans beyond the PR diff, and this PR touches only Python), unrelated to these changes.