Skip to content

STE-42: /use never charges for a skill it cannot deliver - #41

Merged
Lin1er merged 7 commits into
mainfrom
fix/42-use-never-charges-undeliverable
Sep 16, 2026
Merged

Lin1er merged 7 commits into
mainfrom
fix/42-use-never-charges-undeliverable

Conversation

@Lin1er

@Lin1er Lin1er commented Sep 16, 2026

Copy link
Copy Markdown
Owner

Linear: STE-42 · ACC by Axel 2026-09-16 · reviewers @axelmatsama @fable

Problem

GET /use settled the payment and minted the licence before checking the artifact could be served. The STE-27 rehearsal reproduced this with real funds: the agent paid 0.1 USDC, got a licence, then 404 ARTIFACT_NOT_FOUND with no receipt.

Fix

  • Artifact check before any 402 or settle. A version with no servable artifact returns 404 ARTIFACT_NOT_FOUND and no payment challenge.
  • Payer comes from the facilitator's /verify, not from X-AGENT-ADDRESS. Before, a request with someone else's address minted the licence to that address while charging the real payer.
  • Settlements ledger (STERISH_PAYMENTS_DB_PATH, /payments volume), written before the mint. If the mint fails after money moved, the API returns 502 LICENSE_MINT_PENDING with the settlement tx, and the next request finishes the mint without charging again.
  • Per-payer lock. Parallel payments settle once, and an agent that already holds the licence is not charged.
  • sterish intake publish-artifacts. Publishes only versions where three hashes agree (corpus, bytes, on-chain) and the chain verdict is SAFE. Default labels are catalog, safe and demo. Runs as the publish-artifacts tools service in deploy/docker-compose.yml.
  • deploy/verify.sh checks every SAFE row is either for sale or not offered.

Tests

  • API: 142 passed, 14 skipped.
  • Pipeline: 599 passed, 9 skipped.
  • ruff clean.

E2E (testnet, real USDC)

api/scripts/e2e_paid_path.py on Registry v2 / Tokens v2:

  • 15 SAFE rows for sale, 0 undeliverable offered.
  • The agent, sending no X-AGENT-ADDRESS, paid exactly 0.1 USDC.
  • has_license true on chain.
  • Served bytes hash to the on-chain content_hash.
  • A second signed payment for the held licence settled nothing.

Settle ea78a034…, mint f73dfdfc…. Evidence: docs/evidence/ste-42-e2e-paid-path-v2-2026-09-16.json.

After merge

Redeploy CT 204 and run publish-artifacts, then deploy/verify.sh and a real purchase against production. Results will be recorded in docs/deployments.md and on Linear.

On the rehearsal contradiction Axel raised: the v2 catalogue artifacts were on CT 204 (STE-45). The rehearsal's 404 was for a skill registered minutes before the purchase, whose artifact was never published. With this fix, that skill is now answered 404 before payment instead of after.

The paid path settled the USDC and minted the licence before it looked for the
artifact. Only one SAFE version had an artifact on disk, so every other one,
including the 12 seeded catalogue skills, offered a 402, took 0.10 USDC, minted,
and answered 404.

Order is now: SAFE on chain -> artifact present and hashing to the on-chain
content_hash -> held licence -> owed settlement -> 402 -> verify -> settle ->
record -> mint. Nothing below the artifact check runs if it fails, so an
undeliverable version is never priced.

Also in the same path:
- the payer is the account /verify names (the `from` of the signed transfer).
  The Stellar exact payload has no payer field, so the old code fell back to
  X-AGENT-ADDRESS: no header meant settled-then-400 with no licence, and a
  foreign header meant a licence minted to someone else;
- a payer who already holds the licence is served `held` without settling;
- settlements are recorded in a separate ledger before the mint. A failed mint
  is 502 LICENSE_MINT_PENDING with the settlement tx, and the next request
  finishes it without charging again. The ledger is not the index cache;
- one purchase per (payer, skill, version) at a time, so parallel payments
  settle once;
- a contract error reading the licence is 502, no longer a 402;
- a `..` path segment cannot walk the artifact read out of its directory.

The shared test app now runs with the rate limiter off: the suite passed 100
requests and later tests were failing with 429 from the outermost middleware.
test_ratelimit.py builds its own app, so the limiter stays covered.
Writes an artifact only when three hashes agree (bytes on disk, corpus index,
on-chain content_hash) and the on-chain verdict is SAFE. A chain hash that
differs from the corpus is a hard failure, not a skip: those bytes were never
audited.

Staged in a sibling temp dir and swapped in, so /use never reads a half-written
artifact and a stale extra file cannot survive a republish. Directories 0755 and
files 0644, including on an unchanged artifact: mkdtemp creates 0700, and a
root-run publish renamed into place was unreadable by the API's uid 10001.

Run against testnet: 14 published (12 catalogue + 2 safe fixtures), price-checker
held back as DANGEROUS on chain, cctp not on chain.
…sh checks deliverability

- /payments is a separate volume from the /data index cache. The runbook says to
  delete the index volume; deleting the payments ledger would erase the only
  record that a buyer paid and is still owed a licence.
- deploy/artifacts stays operator-supplied and gitignored (STE-25). A
  `publish-artifacts` service (profile `tools`) fills it on the host from the
  corpus with the same image. Verified in Docker: written as root 755/644, read
  back by uid 10001, and the containerised API answers 402 for a published skill
  and 404 without a challenge for one that is not.
- verify.sh walks every SAFE row: 402 with a challenge or 404 ARTIFACT_NOT_FOUND
  without one, anything else fails. It sends its own User-Agent because
  Cloudflare answers Python-urllib with 403 error 1010.
- .gitattributes: the `* text=auto` default sat below `pipeline/corpus/** -text`
  and, last match winning, overrode it. `git check-attr` showed `auto` for corpus
  files. Moved to the top; corpus files now read `text: unset`.
api/scripts/e2e_paid_path.py funds a fresh agent (create + trustline + USDC in one
tx), buys through the real x402 client, and verifies from outside the API:
every SAFE row is 402 or 404-without-challenge, DANGEROUS is 403, the purchase
with no X-AGENT-ADDRESS costs exactly the price, has_license is true, the served
bytes hash to the on-chain content_hash, and a second signed payment for the
held licence settles nothing and moves no USDC.

buy.js gains AGENT_HEADER=0 and EXPECT_LICENSE=held for those two cases and
prints the settlement tx.
…stnet evidence

api-spec 3.7 states the check order, where the payer comes from, what happens
when a mint fails after settlement, and the known limit (a verdict flipped
between settle and mint leaves an owed refund). Section 4 lists the new errors;
section 6 marks the payments ledger as not a cache.

deployments.md records the testnet run (settlement 73a5124d..., mint
858c136e...), the redeploy step that must run publish-artifacts on CT 204, and
what verify.sh reads on production before the redeploy: 48 priced, 0 not
offered, although only 15 are deliverable.
STE-18 added demo fixtures, two of them SAFE on chain (release-notes 1.0.0 and
changelog-writer 1.0.0). With catalog and safe as the only default labels the
compose publish step skipped them, so /use would not have sold them. Anything not
SAFE on chain is still skipped whatever its label.
After rebasing onto main (STE-44 v2 addresses, STE-18 demo skills) the e2e was run
again against v2: 15 SAFE rows for sale and none priced without bytes, a purchase
with no agent header paying exactly 0.1 USDC, the licence on Tokens v2, served
bytes matching the on-chain content_hash, and no second settlement for a held
licence. The deploy note now records that v2-verified artifacts were already put
on CT 204 as a mitigation (STE-45).
@vercel

vercel Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sterish Ready Ready Preview Sep 16, 2026 5:08pm UTC

@Lin1er
Lin1er merged commit 03e7e5d into main Sep 16, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — 554d1e3c Deployed Sep 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant