From 306f7f6763065cb1b697374ffeaf7789f57b74f7 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:18:24 +0700 Subject: [PATCH 1/7] fix(STE-42): /use never takes money for something it cannot hand over 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. --- api/src/sterish_api/config.py | 5 + api/src/sterish_api/main.py | 5 +- api/src/sterish_api/payments.py | 111 ++++++ api/src/sterish_api/routes/use.py | 303 +++++++++++---- api/tests/conftest.py | 13 +- api/tests/test_use_x402.py | 597 +++++++++++++++++++++++++----- 6 files changed, 879 insertions(+), 155 deletions(-) create mode 100644 api/src/sterish_api/payments.py diff --git a/api/src/sterish_api/config.py b/api/src/sterish_api/config.py index b0acd6d..5013510 100644 --- a/api/src/sterish_api/config.py +++ b/api/src/sterish_api/config.py @@ -26,6 +26,10 @@ class Settings: rpc_url: str network_passphrase: str db_path: str + # Settled payments still owed a licence (STE-42). NOT a cache: it is the only + # record of money that moved, so it lives apart from db_path and is never + # deleted by an index rebuild. See payments.py. + payments_db_path: str rate_limit_per_minute: int indexer_enabled: bool indexer_poll_seconds: int @@ -117,6 +121,7 @@ def load_settings() -> Settings: rpc_url=os.getenv("STELLAR_RPC_URL", "https://soroban-testnet.stellar.org").strip(), network_passphrase=os.getenv("STELLAR_NETWORK_PASSPHRASE", TESTNET_PASSPHRASE), db_path=os.getenv("STERISH_DB_PATH", "sterish_index.db"), + payments_db_path=os.getenv("STERISH_PAYMENTS_DB_PATH", "sterish_payments.db"), rate_limit_per_minute=_env_int("RATE_LIMIT_PER_MINUTE", 100), indexer_enabled=os.getenv("INDEXER_ENABLED", "1") not in ("0", "false", "False"), indexer_poll_seconds=_env_int("INDEXER_POLL_SECONDS", 8), diff --git a/api/src/sterish_api/main.py b/api/src/sterish_api/main.py index 00597d9..dd2de43 100644 --- a/api/src/sterish_api/main.py +++ b/api/src/sterish_api/main.py @@ -12,7 +12,7 @@ from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import JSONResponse -from . import chain, indexer, x402 +from . import chain, indexer, payments, x402 from .chain import ChainError, ContractError, NotConfiguredError from .config import settings from .errors import ( @@ -53,6 +53,8 @@ async def lifespan(app: FastAPI): # and the evidence lookups then read an empty index instead of erroring on a # missing table. indexer.init_db() + # The payments ledger is not a cache (STE-42): created here, never rebuilt. + payments.init_db() task = None if settings.indexer_enabled: @@ -89,6 +91,7 @@ async def lifespan(app: FastAPI): "X-PAYMENT-RESPONSE", "X-STERISH-LICENSE", "X-STERISH-LICENSE-TX", + "X-STERISH-SETTLEMENT-TX", ], ) app.add_middleware(RateLimitMiddleware) diff --git a/api/src/sterish_api/payments.py b/api/src/sterish_api/payments.py new file mode 100644 index 0000000..8fc93d7 --- /dev/null +++ b/api/src/sterish_api/payments.py @@ -0,0 +1,111 @@ +"""Settled payments that are owed a licence (STE-42). + +**This is not a cache.** The indexer's SQLite file can be deleted at any time because +every row in it can be read back from the chain. Nothing here can: a settlement the +facilitator confirmed is money that has already moved, and the only record that it +is still owed a licence is this table. Keep it on its own volume and never delete it +as part of an index rebuild. + +The table exists for one failure. `/use` settles the payment and then mints the +licence. Those are two transactions, and the second can fail or time out after the +first has landed. Before this table existed that left a buyer who had paid with no +licence and no way back: retrying the same payment is refused, because it is +already settled, and a new payment charges them twice. So the settlement is written +here before the mint is attempted, and the next request from that payer finishes +the mint instead of asking for money again. +""" + +from __future__ import annotations + +import logging +import sqlite3 +import threading +import time +from typing import Any + +from .config import settings + +logger = logging.getLogger(__name__) + +_SCHEMA = """ +CREATE TABLE IF NOT EXISTS payments ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + payer TEXT NOT NULL, + skill_id TEXT NOT NULL, + version TEXT NOT NULL, + settle_tx TEXT NOT NULL UNIQUE, + amount TEXT NOT NULL, + settled_at INTEGER NOT NULL, + mint_tx TEXT, + minted_at INTEGER, + last_error TEXT +); +CREATE INDEX IF NOT EXISTS idx_payments_owed ON payments (payer, skill_id, version, minted_at); +""" + +_lock = threading.Lock() + + +def _connect() -> sqlite3.Connection: + conn = sqlite3.connect(settings.payments_db_path, check_same_thread=False) + conn.row_factory = sqlite3.Row + return conn + + +def init_db() -> None: + with _lock, _connect() as conn: + conn.executescript(_SCHEMA) + + +def record_settlement( + payer: str, skill_id: str, version: str, settle_tx: str, amount: str +) -> None: + """Record money that moved, before anything else can fail. + + Idempotent on the settlement hash: the same settlement recorded twice is one row. + """ + with _lock, _connect() as conn: + conn.execute( + "INSERT OR IGNORE INTO payments " + "(payer, skill_id, version, settle_tx, amount, settled_at) " + "VALUES (?, ?, ?, ?, ?, ?)", + (payer, skill_id, version, settle_tx, amount, int(time.time())), + ) + + +def owed(payer: str, skill_id: str, version: str) -> dict[str, Any] | None: + """The oldest settlement for this exact licence that has not been minted yet.""" + with _lock, _connect() as conn: + row = conn.execute( + "SELECT * FROM payments WHERE payer = ? AND skill_id = ? AND version = ? " + "AND minted_at IS NULL ORDER BY id LIMIT 1", + (payer, skill_id, version), + ).fetchone() + return dict(row) if row else None + + +def mark_minted(settle_tx: str, mint_tx: str | None) -> None: + """Close out a settlement. `mint_tx` is None when the licence was found already + on chain — a mint that landed although its confirmation never reached us.""" + with _lock, _connect() as conn: + conn.execute( + "UPDATE payments SET mint_tx = ?, minted_at = ?, last_error = NULL " + "WHERE settle_tx = ?", + (mint_tx, int(time.time()), settle_tx), + ) + + +def mark_error(settle_tx: str, error: str) -> None: + with _lock, _connect() as conn: + conn.execute( + "UPDATE payments SET last_error = ? WHERE settle_tx = ?", + (error[:500], settle_tx), + ) + + +def get(settle_tx: str) -> dict[str, Any] | None: + with _lock, _connect() as conn: + row = conn.execute( + "SELECT * FROM payments WHERE settle_tx = ?", (settle_tx,) + ).fetchone() + return dict(row) if row else None diff --git a/api/src/sterish_api/routes/use.py b/api/src/sterish_api/routes/use.py index 221a96a..e17a0eb 100644 --- a/api/src/sterish_api/routes/use.py +++ b/api/src/sterish_api/routes/use.py @@ -1,27 +1,42 @@ -"""The paid path: `GET /use/{skill_id}/{version}` (api-spec 3.7, STE-19). - -Three outcomes, in the order they are checked: - -1. the caller already holds a license for this exact version -> 200, no payment; -2. no license and no payment -> 402 with x402 requirements; -3. no license, payment attached -> facilitator verify, then settle, then mint the - license, then 200. - -Verify runs before settle deliberately: settling first would move money for a -request that is about to be refused. - -What is served is content-pinned. The bytes are hashed and compared with the -`content_hash` the registry holds for that version before they leave this -process, so a buyer cannot pay for one artifact and receive another. A mismatch -is a 500, never a 200 with the wrong bytes. +"""The paid path: `GET /use/{skill_id}/{version}` (api-spec 3.7, STE-19, STE-42). + +The rule everything below serves: **never take money for something that cannot be +handed over, and never take it twice.** + +Checked in this order: + +1. the version is SAFE on chain, else 403 — never offered for sale; +2. the artifact is on disk and hashes to the on-chain `content_hash`, else 404/500 — + checked *before* the 402, so nothing undeliverable is ever priced; +3. the caller already holds a licence -> 200, no payment; +4. the caller has a settled payment still owed a licence -> finish the mint, 200; +5. no payment attached -> 402 with x402 requirements; +6. payment attached -> verify (which names the payer) -> held or owed? serve without + settling -> settle -> record the settlement -> mint -> 200. + +Before STE-42 the artifact was read only after settle and mint, so every SAFE skill +without a published artifact took 0.10 USDC, minted a licence, and answered 404. + +The payer is the account the facilitator's `/verify` names: the `from` of the +signed SAC `transfer`. It is never taken from `X-AGENT-ADDRESS`. That header is only +a hint for the free "already licensed" shortcut, and trusting it after payment let a +licence be minted to whatever address the header carried — or, with no header, +settled the payment and then answered 400 with no licence at all, because the +Stellar exact payload carries no `payer` field of its own. + +What is served is content-pinned: the bytes are hashed against the registry's +`content_hash` before they leave this process. """ +import json import logging +import threading from pathlib import Path from fastapi import APIRouter, Request, Response +from stellar_sdk.strkey import StrKey -from .. import chain, x402 +from .. import chain, payments, x402 from ..config import settings from ..errors import ApiError @@ -37,13 +52,44 @@ # a threadpool, which is exactly what this work wants. AGENT_HEADER = "X-AGENT-ADDRESS" +SETTLEMENT_TX_HEADER = "X-STERISH-SETTLEMENT-TX" + +# tokens contract: TokenError::AlreadyMinted (contracts/tokens/src/data.rs). Frozen. +TOKENS_ERR_ALREADY_MINTED = 3 + +# One purchase per (payer, skill, version) at a time. Without it two concurrent +# payments from the same account both see "no licence", both settle, and the buyer +# pays twice for one licence. The API runs as a single uvicorn process (Dockerfile +# CMD), so an in-process lock covers every request that can race. +_purchase_locks: dict[tuple[str, str, str], threading.Lock] = {} +_purchase_locks_guard = threading.Lock() -def _agent_address(request: Request) -> str | None: - """Who is asking. Needed before any payment exists, to answer 'do you already - hold a licence?'. After payment the address is taken from the payment itself.""" +def _purchase_lock(payer: str, skill_id: str, version: str) -> threading.Lock: + key = (payer, skill_id, version) + with _purchase_locks_guard: + lock = _purchase_locks.get(key) + if lock is None: + lock = _purchase_locks[key] = threading.Lock() + return lock + + +def _agent_hint(request: Request) -> str | None: + """The caller's claimed account, used only for the free already-licensed shortcut. + + Validated so a malformed value is a 400 naming the problem rather than a 500 + from the XDR encoder. Never used to decide who a paid licence is minted to. + """ value = request.headers.get(AGENT_HEADER) or request.query_params.get("agent") - return value.strip() if value else None + if not value or not value.strip(): + return None + value = value.strip() + if not StrKey.is_valid_ed25519_public_key(value): + raise ApiError( + 400, "INVALID_AGENT", + f"agent must be a Stellar account address (G...), got {value!r}", + ) + return value def _skill_bytes(skill_id: str, version: str, expected_hash: str) -> bytes: @@ -52,15 +98,24 @@ def _skill_bytes(skill_id: str, version: str, expected_hash: str) -> bytes: raise ApiError(503, "NOT_CONFIGURED", "STERISH_SKILLS_DIR is not set") root = Path(settings.skills_dir) / skill_id / version - if not root.is_dir(): + # Resolve and re-check containment: skill_id and version come from the URL, and + # a `..` segment must not walk the read outside the artifact directory. + base = Path(settings.skills_dir).resolve() + if base not in root.resolve().parents or not root.is_dir(): raise ApiError( 404, "ARTIFACT_NOT_FOUND", - f"no artifact on disk for {skill_id}@{version}", + f"no artifact on disk for {skill_id}@{version}; it is not offered for sale", ) - from sterish_pipeline.content_hash import content_hash, read_skill_files + from sterish_pipeline.content_hash import ContentHashError, content_hash, read_skill_files - files = read_skill_files(root) + try: + files = read_skill_files(root) + except ContentHashError as exc: + raise ApiError( + 404, "ARTIFACT_NOT_FOUND", + f"artifact directory for {skill_id}@{version} is unusable: {exc}", + ) from exc actual = content_hash(files) if actual != expected_hash: # Serving these bytes would break the one promise the licence encodes. @@ -73,14 +128,24 @@ def _skill_bytes(skill_id: str, version: str, expected_hash: str) -> bytes: "artifact on disk does not match the content_hash recorded on chain", ) - import json - return json.dumps( {name: raw.decode("utf-8", "replace") for name, raw in sorted(files.items())}, indent=2, ).encode("utf-8") +def _has_license(agent: str, skill_id: str, version: str) -> bool: + """A failed read is a failed read, never "no licence" (which would invite a 402 + and a second payment). A ChainError propagates as 502 through its handler.""" + try: + return chain.has_license(agent, skill_id, version) + except chain.ContractError as exc: + raise ApiError( + 502, "LICENSE_READ_FAILED", + f"could not read the licence for {agent} from the tokens contract: {exc}", + ) from exc + + def _mint_license(agent: str, skill_id: str, version: str) -> str: """Mint the licence with the minter role. Returns the transaction hash.""" from stellar_sdk import Address, scval @@ -109,6 +174,67 @@ def _mint_license(agent: str, skill_id: str, version: str) -> str: return result.tx_hash +def _fulfil(owed_row: dict, skill_id: str, version: str) -> str | None: + """Turn a recorded settlement into a licence. Returns the mint tx, or None when + the licence turned out to be on chain already. + + Checks the chain before minting: a mint whose confirmation timed out may have + landed, and minting again would only revert with AlreadyMinted. + """ + from sterish_pipeline.onchain import ContractCallError + + payer, settle_tx = owed_row["payer"], owed_row["settle_tx"] + + if _has_license(payer, skill_id, version): + payments.mark_minted(settle_tx, None) + return None + + try: + mint_tx = _mint_license(payer, skill_id, version) + except ContractCallError as exc: + if exc.code == TOKENS_ERR_ALREADY_MINTED: + payments.mark_minted(settle_tx, None) + return None + payments.mark_error(settle_tx, str(exc)) + logger.error("mint_license refused for settled payment %s: %s", settle_tx, exc) + raise _mint_pending(settle_tx, str(exc)) from exc + except ApiError: + raise + except Exception as exc: # noqa: BLE001 - timeout, RPC, anything: the money moved + payments.mark_error(settle_tx, str(exc)) + logger.error("mint_license failed for settled payment %s: %s", settle_tx, exc) + raise _mint_pending(settle_tx, str(exc)) from exc + + payments.mark_minted(settle_tx, mint_tx) + return mint_tx + + +def _mint_pending(settle_tx: str, reason: str) -> ApiError: + return ApiError( + 502, "LICENSE_MINT_PENDING", + "your payment settled but the licence could not be minted yet; retry the same " + "request (with X-AGENT-ADDRESS) and it will be finished without charging again. " + f"Cause: {reason}", + { + "settlement_tx": settle_tx, + "settlement_tx_url": settings.tx_url(settle_tx), + }, + ) + + +def _serve(body: bytes, licence: str, extra: dict[str, str] | None = None) -> Response: + headers = {"X-STERISH-LICENSE": licence, "Cache-Control": "no-store"} + headers.update(extra or {}) + return Response(content=body, media_type="application/json", headers=headers) + + +def _serve_fulfilled(body: bytes, owed_row: dict, mint_tx: str | None) -> Response: + headers = {SETTLEMENT_TX_HEADER: owed_row["settle_tx"]} + if mint_tx: + headers["X-STERISH-LICENSE-TX"] = mint_tx + return _serve(body, "minted" if mint_tx else "held", headers) + + @router.get("/use/{skill_id}/{version}") def use_skill(skill_id: str, version: str, request: Request): record = chain.get_version(skill_id, version) @@ -122,28 +248,32 @@ def use_skill(skill_id: str, version: str, request: Request): f"{skill_id}@{version} is {record['verdict']}; only SAFE versions are licensable", ) - agent = _agent_address(request) - payment_header = request.headers.get(x402.PAYMENT_HEADER) + # Deliverability before price. If these bytes cannot be served, nothing below may + # run: no challenge, no verify, no settle. + body = _skill_bytes(skill_id, version, record["content_hash"]) - # 1. Already licensed -> serve, no payment. - if agent and not payment_header: - try: - if chain.has_license(agent, skill_id, version): - return Response( - content=_skill_bytes(skill_id, version, record["content_hash"]), - media_type="application/json", - headers={"X-STERISH-LICENSE": "held"}, - ) - except chain.ContractError: - pass # no licence recorded; fall through to the 402 - - resource_url = str(request.url) - requirements = x402.payment_requirements( - resource_url, f"License for {skill_id}@{version}" - ) + agent = _agent_hint(request) + payment_header = request.headers.get(x402.PAYMENT_HEADER) - # 2. No payment attached -> challenge. if not payment_header: + if agent: + if _has_license(agent, skill_id, version): + # A mint that landed although its confirmation never reached us leaves + # its settlement looking owed; close it so it is never fulfilled twice. + stale = payments.owed(agent, skill_id, version) + if stale: + payments.mark_minted(stale["settle_tx"], None) + return _serve(body, "held") + owed_row = payments.owed(agent, skill_id, version) + if owed_row: + with _purchase_lock(agent, skill_id, version): + owed_row = payments.owed(agent, skill_id, version) or owed_row + mint_tx = _fulfil(owed_row, skill_id, version) + return _serve_fulfilled(body, owed_row, mint_tx) + + requirements = x402.payment_requirements( + str(request.url), f"License for {skill_id}@{version}" + ) return Response( content=b"{}", status_code=402, @@ -154,16 +284,18 @@ def use_skill(skill_id: str, version: str, request: Request): }, ) - # 3. Payment attached -> verify, settle, mint, serve. try: payment = x402.decode_header(payment_header) except ValueError as exc: raise ApiError(400, "INVALID_PAYMENT", str(exc)) from exc + requirements = x402.payment_requirements( + str(request.url), f"License for {skill_id}@{version}" + ) accepts = requirements["accepts"][0] + try: - x402.verify(payment, accepts) - receipt = x402.settle(payment, accepts) + verified = x402.verify(payment, accepts) except x402.PaymentInvalid as exc: raise ApiError(402, "PAYMENT_REJECTED", exc.reason) from exc except x402.FacilitatorError as exc: @@ -171,25 +303,62 @@ def use_skill(skill_id: str, version: str, request: Request): # not pay" — that would invite a buyer to pay twice. raise ApiError(503, "FACILITATOR_UNAVAILABLE", str(exc)) from exc - payer = ( - payment.get("payload", {}).get("payer") - or payment.get("payer") - or agent - ) - if not payer: + payer = str(verified.get("payer") or "").strip() + if not StrKey.is_valid_ed25519_public_key(payer): + # Settling without knowing who paid would leave nobody to mint the licence + # to. Refuse while no money has moved. raise ApiError( - 400, "UNKNOWN_PAYER", - f"cannot tell who paid; send {AGENT_HEADER} with the request", + 502, "FACILITATOR_BAD_RESPONSE", + f"facilitator verified the payment but named no valid payer ({payer!r})", ) - mint_tx = _mint_license(payer, skill_id, version) + with _purchase_lock(payer, skill_id, version): + # Re-checked under the lock: a concurrent purchase may have just finished. + if _has_license(payer, skill_id, version): + return _serve(body, "held") + owed_row = payments.owed(payer, skill_id, version) + if owed_row: + mint_tx = _fulfil(owed_row, skill_id, version) + return _serve_fulfilled(body, owed_row, mint_tx) - return Response( - content=_skill_bytes(skill_id, version, record["content_hash"]), - media_type="application/json", - headers={ - x402.PAYMENT_RESPONSE_HEADER: x402.encode_header(receipt), - "X-STERISH-LICENSE": "minted", - "X-STERISH-LICENSE-TX": mint_tx, - }, - ) + try: + receipt = x402.settle(payment, accepts) + except x402.PaymentInvalid as exc: + raise ApiError(402, "PAYMENT_REJECTED", exc.reason) from exc + except x402.FacilitatorError as exc: + raise ApiError(503, "FACILITATOR_UNAVAILABLE", str(exc)) from exc + + settle_tx = str(receipt.get("transaction") or "").strip() + if not settle_tx: + # success without a transaction hash is not a receipt anyone can check. + logger.error("facilitator settled with no transaction hash: %s", receipt) + raise ApiError( + 502, "FACILITATOR_BAD_RESPONSE", + "facilitator reported success without a settlement transaction", + ) + if receipt.get("payer") and receipt["payer"] != payer: + logger.warning( + "settle named payer %s but verify named %s; minting to the verified payer", + receipt["payer"], payer, + ) + + try: + payments.record_settlement( + payer, skill_id, version, settle_tx, str(accepts["amount"]) + ) + except Exception: # noqa: BLE001 - the money moved; still try to deliver + logger.exception( + "could not record settlement %s for %s; attempting the mint anyway", + settle_tx, payer, + ) + + owed_row = payments.get(settle_tx) or {"payer": payer, "settle_tx": settle_tx} + mint_tx = _fulfil(owed_row, skill_id, version) + + headers = { + x402.PAYMENT_RESPONSE_HEADER: x402.encode_header(receipt), + SETTLEMENT_TX_HEADER: settle_tx, + } + if mint_tx: + headers["X-STERISH-LICENSE-TX"] = mint_tx + return _serve(body, "minted", headers) diff --git a/api/tests/conftest.py b/api/tests/conftest.py index fb51030..7c49178 100644 --- a/api/tests/conftest.py +++ b/api/tests/conftest.py @@ -7,6 +7,11 @@ ) os.environ.setdefault("STELLAR_NETWORK_PASSPHRASE", "Test SDF Network ; September 2015") os.environ.setdefault("INDEXER_ENABLED", "0") +# The limiter counts per middleware instance, and every test shares the one app, so a +# suite past 100 requests started failing late tests with 429 from the outermost +# middleware. tests/test_ratelimit.py builds its own app with an explicit limit, so +# the limiter itself stays covered. +os.environ.setdefault("RATE_LIMIT_PER_MINUTE", "0") # x402 settings the paid-path tests assert on. Set here, not inherited: these tests # passed locally only because a developer shell had .env loaded, and CI — which has @@ -33,16 +38,22 @@ def _isolated_db(tmp_path): so the one shared object is mutated in place via `object.__setattr__` and restored afterwards — patching `config.settings` itself would not reach those modules. """ - from sterish_api import config, indexer + from sterish_api import config, indexer, payments db = tmp_path / "index.db" previous = config.settings.db_path + previous_payments = config.settings.payments_db_path object.__setattr__(config.settings, "db_path", str(db)) + # The payments ledger too: a settlement recorded by one test must never look + # "owed" to the next one. + object.__setattr__(config.settings, "payments_db_path", str(tmp_path / "payments.db")) indexer.init_db() + payments.init_db() try: yield db finally: object.__setattr__(config.settings, "db_path", previous) + object.__setattr__(config.settings, "payments_db_path", previous_payments) @pytest.fixture diff --git a/api/tests/test_use_x402.py b/api/tests/test_use_x402.py index 66bbfc6..1de8c4d 100644 --- a/api/tests/test_use_x402.py +++ b/api/tests/test_use_x402.py @@ -1,21 +1,46 @@ -"""The paid path, with the chain and the facilitator stubbed. No network.""" +"""The paid path, with the chain, the facilitator and the mint stubbed. No network. + +Organised around the rule STE-42 enforces: never take money for something that +cannot be handed over, and never take it twice. Each test that can move money +asserts how many times settle ran, not only what status came back. +""" import base64 import json +import threading +import time import pytest -from sterish_api import chain, x402 +from sterish_api import chain, payments, x402 from sterish_api.config import settings +from sterish_api.routes import use as use_route SAFE = { - "skill_id": "com.acme.pdf-suite", "version": "1.0.0", - "content_hash": "a" * 64, "verdict": "SAFE", "trust_score": 88, - "is_verified": True, "owner": "G" + "A" * 55, "auditor": "G" + "B" * 55, - "registered_at": 1, "audited_at": 2, "evidence_hash": "b" * 64, + "skill_id": "com.acme.pdf-suite", + "version": "1.0.0", + "content_hash": "a" * 64, + "verdict": "SAFE", + "trust_score": 88, + "is_verified": True, + "owner": "G" + "A" * 55, + "auditor": "G" + "B" * 55, + "registered_at": 1, + "audited_at": 2, + "evidence_hash": "b" * 64, } DANGEROUS = dict(SAFE, verdict="DANGEROUS", is_verified=False) -AGENT = "GBFXMHA77OLBYF3JJB43O6CKZ4QR35AAQALJK72MUIHTZNBVAQGTTZWY" +URL = f"/use/{SAFE['skill_id']}/1.0.0" + +# Two real ed25519 account addresses: the buyer, and someone else entirely. +PAYER = "GBFXMHA77OLBYF3JJB43O6CKZ4QR35AAQALJK72MUIHTZNBVAQGTTZWY" +OTHER = "GD73M4F7RN74KBLFGJP4WKBMCBJWBOA4SFNOP5HG4NBCDQUQCC2ARSZU" +SETTLE_TX = "5" * 64 +MINT_TX = "6" * 64 + + +def _payment_header(payload: dict | None = None) -> str: + return base64.b64encode(json.dumps(payload or {"payload": {}}).encode()).decode() @pytest.fixture @@ -23,22 +48,171 @@ def artifact(tmp_path, monkeypatch): """A skill on disk whose bytes hash to what the chain says.""" from sterish_pipeline.content_hash import content_hash - root = tmp_path / SAFE["skill_id"] / SAFE["version"] + root = tmp_path / "artifacts" / SAFE["skill_id"] / SAFE["version"] root.mkdir(parents=True) (root / "manifest.json").write_bytes(b'{"skill_id":"com.acme.pdf-suite"}\n') digest = content_hash({"manifest.json": (root / "manifest.json").read_bytes()}) - object.__setattr__(settings, "skills_dir", str(tmp_path)) + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", str(tmp_path / "artifacts")) monkeypatch.setattr(chain, "get_version", lambda s, v: dict(SAFE, content_hash=digest)) - return digest + yield digest + object.__setattr__(settings, "skills_dir", previous) -def _payment_header(payload: dict) -> str: - return base64.b64encode(json.dumps(payload).encode()).decode() +@pytest.fixture +def no_artifact(tmp_path, monkeypatch): + """A SAFE version with an artifact directory configured but nothing in it for us.""" + (tmp_path / "artifacts").mkdir() + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", str(tmp_path / "artifacts")) + monkeypatch.setattr(chain, "get_version", lambda s, v: SAFE) + yield + object.__setattr__(settings, "skills_dir", previous) + + +class Ledger: + """Stand-in for the chain's licence state plus the facilitator and the minter. + + Every money-moving call is counted, so a test can say "settled exactly once". + """ + + def __init__(self, monkeypatch, *, payer=PAYER): + self.licences: set[tuple[str, str, str]] = set() + self.settles = 0 + self.verifies = 0 + self.mints: list[str] = [] + self.payer = payer + self.mint_error: Exception | None = None + self.settle_delay = 0.0 + monkeypatch.setattr(chain, "has_license", self.has_license) + monkeypatch.setattr(x402, "verify", self.verify) + monkeypatch.setattr(x402, "settle", self.settle) + monkeypatch.setattr(use_route, "_mint_license", self.mint) + + def has_license(self, agent, skill_id, version): + return (agent, skill_id, version) in self.licences + + def verify(self, payment, requirements): + self.verifies += 1 + return {"isValid": True, "payer": self.payer} + + def settle(self, payment, requirements): + if self.settle_delay: + time.sleep(self.settle_delay) + self.settles += 1 + return { + "success": True, + "transaction": SETTLE_TX, + "network": "stellar:testnet", + "payer": self.payer, + } + + def mint(self, agent, skill_id, version): + if self.mint_error is not None: + raise self.mint_error + self.mints.append(agent) + self.licences.add((agent, skill_id, version)) + return MINT_TX + + +# --- never offered ----------------------------------------------------------- -def test_unpaid_request_gets_a_402_challenge(client, monkeypatch): - monkeypatch.setattr(chain, "get_version", lambda s, v: SAFE) - r = client.get(f"/use/{SAFE['skill_id']}/1.0.0") +def test_a_dangerous_version_can_never_be_sold(client, monkeypatch): + """The claim the whole product rests on, at the point money changes hands.""" + monkeypatch.setattr(chain, "get_version", lambda s, v: DANGEROUS) + r = client.get(URL) + assert r.status_code == 403 + assert r.json()["error"] == "NOT_VERIFIED" + assert "PAYMENT-REQUIRED" not in r.headers + + +class TestNothingUndeliverableIsPriced: + """STE-42: the artifact used to be read only after settle and mint.""" + + def test_no_artifact_is_404_with_no_payment_challenge(self, client, no_artifact): + r = client.get(URL) + assert r.status_code == 404 + assert r.json()["error"] == "ARTIFACT_NOT_FOUND" + assert "PAYMENT-REQUIRED" not in r.headers + + def test_no_artifact_never_reaches_the_facilitator_even_with_a_payment( + self, client, monkeypatch, no_artifact + ): + """The exact failure from the audit: paid, minted, then 404.""" + ledger = Ledger(monkeypatch) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 404 + assert (ledger.verifies, ledger.settles, ledger.mints) == (0, 0, []) + + def test_hash_mismatch_is_500_before_any_challenge(self, client, monkeypatch, artifact): + monkeypatch.setattr(chain, "get_version", lambda s, v: dict(SAFE, content_hash="f" * 64)) + r = client.get(URL) + assert r.status_code == 500 + assert r.json()["error"] == "ARTIFACT_HASH_MISMATCH" + assert "PAYMENT-REQUIRED" not in r.headers + + def test_hash_mismatch_never_settles(self, client, monkeypatch, artifact): + """A buyer must not pay for one artifact and receive another — or nothing.""" + ledger = Ledger(monkeypatch) + monkeypatch.setattr(chain, "get_version", lambda s, v: dict(SAFE, content_hash="f" * 64)) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 500 + assert (ledger.verifies, ledger.settles) == (0, 0) + + def test_hash_mismatch_is_never_served_to_a_licence_holder(self, client, monkeypatch, artifact): + ledger = Ledger(monkeypatch) + ledger.licences.add((PAYER, SAFE["skill_id"], "1.0.0")) + monkeypatch.setattr(chain, "get_version", lambda s, v: dict(SAFE, content_hash="f" * 64)) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 500 + + def test_unconfigured_artifact_dir_is_503_not_402(self, client, monkeypatch): + monkeypatch.setattr(chain, "get_version", lambda s, v: SAFE) + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", "") + try: + r = client.get(URL) + finally: + object.__setattr__(settings, "skills_dir", previous) + assert r.status_code == 503 + assert "PAYMENT-REQUIRED" not in r.headers + + def test_an_empty_artifact_directory_is_not_for_sale(self, client, monkeypatch, tmp_path): + (tmp_path / "artifacts" / SAFE["skill_id"] / "1.0.0").mkdir(parents=True) + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", str(tmp_path / "artifacts")) + monkeypatch.setattr(chain, "get_version", lambda s, v: SAFE) + try: + r = client.get(URL) + finally: + object.__setattr__(settings, "skills_dir", previous) + assert r.status_code == 404 + assert "PAYMENT-REQUIRED" not in r.headers + + def test_a_path_segment_cannot_walk_out_of_the_artifact_dir(self, tmp_path): + """skill_id and version come from the URL; `..` must not read elsewhere.""" + from sterish_api.errors import ApiError + + (tmp_path / "artifacts").mkdir() + (tmp_path / "secret").mkdir() + (tmp_path / "secret" / "key.txt").write_text("not for sale") + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", str(tmp_path / "artifacts")) + try: + for skill_id, version in (("..", "secret"), ("x", ".."), ("..", "..")): + with pytest.raises(ApiError) as exc: + use_route._skill_bytes(skill_id, version, "a" * 64) + assert exc.value.status == 404 + finally: + object.__setattr__(settings, "skills_dir", previous) + + +# --- the challenge ------------------------------------------------------------ + + +def test_unpaid_request_gets_a_402_challenge(client, artifact): + r = client.get(URL) assert r.status_code == 402 required = json.loads(base64.b64decode(r.headers["PAYMENT-REQUIRED"])) @@ -47,99 +221,343 @@ def test_unpaid_request_gets_a_402_challenge(client, monkeypatch): assert accepts["scheme"] == "exact" assert accepts["network"] == "stellar:testnet" assert accepts["amount"] == str(settings.price_base_units) + assert r.headers["Cache-Control"] == "no-store" -def test_payto_is_a_classic_account_and_asset_is_the_sac(client, monkeypatch): +def test_payto_is_a_classic_account_and_asset_is_the_sac(client, artifact): """Swapping these two is the documented common stumble, so it is pinned.""" - monkeypatch.setattr(chain, "get_version", lambda s, v: SAFE) - r = client.get(f"/use/{SAFE['skill_id']}/1.0.0") + r = client.get(URL) accepts = json.loads(base64.b64decode(r.headers["PAYMENT-REQUIRED"]))["accepts"][0] assert accepts["payTo"].startswith("G") assert accepts["asset"].startswith("C") -def test_a_dangerous_version_can_never_be_sold(client, monkeypatch): - """The claim the whole product rests on, at the point money changes hands.""" - monkeypatch.setattr(chain, "get_version", lambda s, v: DANGEROUS) - r = client.get(f"/use/{SAFE['skill_id']}/1.0.0") - assert r.status_code == 403 - assert r.json()["error"] == "NOT_VERIFIED" - assert "PAYMENT-REQUIRED" not in r.headers - - -def test_an_existing_licence_is_served_without_payment(client, monkeypatch, artifact): - monkeypatch.setattr(chain, "has_license", lambda a, s, v: True) - r = client.get(f"/use/{SAFE['skill_id']}/1.0.0", headers={"X-AGENT-ADDRESS": AGENT}) - assert r.status_code == 200 - assert r.headers["X-STERISH-LICENSE"] == "held" - - -def test_a_facilitator_outage_is_not_reported_as_non_payment(client, monkeypatch, artifact): - """503, not 402. Telling a buyer who just paid that they did not would invite - them to pay twice.""" - monkeypatch.setattr(chain, "has_license", lambda a, s, v: False) +def test_an_unlicensed_agent_hint_still_gets_the_challenge(client, monkeypatch, artifact): + Ledger(monkeypatch) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 402 - def down(*a, **k): - raise x402.FacilitatorError("connection refused") - monkeypatch.setattr(x402, "verify", down) - r = client.get( - f"/use/{SAFE['skill_id']}/1.0.0", - headers={"X-AGENT-ADDRESS": AGENT, "X-PAYMENT": _payment_header({"payload": {}})}, - ) - assert r.status_code == 503 - assert r.json()["error"] == "FACILITATOR_UNAVAILABLE" +def test_a_malformed_agent_hint_is_400_not_500(client, monkeypatch, artifact): + Ledger(monkeypatch) + r = client.get(URL, headers={"X-AGENT-ADDRESS": "not-an-address"}) + assert r.status_code == 400 + assert r.json()["error"] == "INVALID_AGENT" -def test_a_rejected_payment_is_402_with_the_facilitator_reason(client, monkeypatch, artifact): - monkeypatch.setattr(chain, "has_license", lambda a, s, v: False) +def test_a_contract_address_is_not_an_agent(client, monkeypatch, artifact): + Ledger(monkeypatch) + r = client.get(URL, params={"agent": settings.usdc_sac}) + assert r.status_code == 400 - def reject(*a, **k): - raise x402.PaymentInvalid("insufficient_funds") - monkeypatch.setattr(x402, "verify", reject) - r = client.get( - f"/use/{SAFE['skill_id']}/1.0.0", - headers={"X-AGENT-ADDRESS": AGENT, "X-PAYMENT": _payment_header({"payload": {}})}, - ) - assert r.status_code == 402 - assert r.json()["detail"] == "insufficient_funds" +# --- licence holders ----------------------------------------------------------- -def test_settlement_is_never_attempted_on_an_invalid_payment(client, monkeypatch, artifact): - """Settling first would move money for a request about to be refused.""" - monkeypatch.setattr(chain, "has_license", lambda a, s, v: False) - settled = [] +def test_an_existing_licence_is_served_without_payment(client, monkeypatch, artifact): + ledger = Ledger(monkeypatch) + ledger.licences.add((PAYER, SAFE["skill_id"], "1.0.0")) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 200 + assert r.headers["X-STERISH-LICENSE"] == "held" + assert json.loads(r.content) == {"manifest.json": '{"skill_id":"com.acme.pdf-suite"}\n'} + assert ledger.verifies == ledger.settles == 0 - def reject(*a, **k): - raise x402.PaymentInvalid("bad") - monkeypatch.setattr(x402, "verify", reject) - monkeypatch.setattr(x402, "settle", lambda *a, **k: settled.append(1)) - client.get( - f"/use/{SAFE['skill_id']}/1.0.0", - headers={"X-AGENT-ADDRESS": AGENT, "X-PAYMENT": _payment_header({"payload": {}})}, - ) - assert settled == [] +def test_a_failed_licence_read_is_never_a_402(client, monkeypatch, artifact): + """402 used to mean either "no licence" or "could not tell" (STE-35 finding).""" + def broken(*a): + raise chain.ContractError(6, "InvalidInput") -def test_a_malformed_payment_header_is_400(client, monkeypatch, artifact): - monkeypatch.setattr(chain, "has_license", lambda a, s, v: False) - r = client.get( - f"/use/{SAFE['skill_id']}/1.0.0", - headers={"X-AGENT-ADDRESS": AGENT, "X-PAYMENT": "not-base64-json"}, - ) - assert r.status_code == 400 - assert r.json()["error"] == "INVALID_PAYMENT" + monkeypatch.setattr(chain, "has_license", broken) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 502 + assert r.json()["error"] == "LICENSE_READ_FAILED" + assert "PAYMENT-REQUIRED" not in r.headers -def test_artifact_that_does_not_match_the_chain_is_never_served(client, monkeypatch, artifact): - """A buyer must not pay for one artifact and receive another.""" - monkeypatch.setattr(chain, "has_license", lambda a, s, v: True) - monkeypatch.setattr(chain, "get_version", lambda s, v: dict(SAFE, content_hash="f" * 64)) - r = client.get(f"/use/{SAFE['skill_id']}/1.0.0", headers={"X-AGENT-ADDRESS": AGENT}) - assert r.status_code == 500 - assert r.json()["error"] == "ARTIFACT_HASH_MISMATCH" +def test_an_unreachable_rpc_on_the_licence_read_is_502(client, monkeypatch, artifact): + def down(*a): + raise chain.ChainError("timeout") + + monkeypatch.setattr(chain, "has_license", down) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 502 + + +# --- paying ---------------------------------------------------------------------- + + +class TestPaying: + def test_the_happy_path_settles_once_and_mints_to_the_payer( + self, client, monkeypatch, artifact + ): + ledger = Ledger(monkeypatch) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER, "X-PAYMENT": _payment_header()}) + assert r.status_code == 200 + assert r.headers["X-STERISH-LICENSE"] == "minted" + assert r.headers["X-STERISH-LICENSE-TX"] == MINT_TX + assert r.headers["X-STERISH-SETTLEMENT-TX"] == SETTLE_TX + receipt = json.loads(base64.b64decode(r.headers["X-PAYMENT-RESPONSE"])) + assert receipt["transaction"] == SETTLE_TX + assert ledger.settles == 1 + assert ledger.mints == [PAYER] + row = payments.get(SETTLE_TX) + assert row["payer"] == PAYER and row["mint_tx"] == MINT_TX and row["minted_at"] + + def test_no_agent_header_still_mints_to_whoever_paid(self, client, monkeypatch, artifact): + """Before STE-42 this settled the payment and then answered 400 UNKNOWN_PAYER: + the Stellar exact payload has no payer field, so the header was the only + source, and without it the money moved and no licence existed.""" + ledger = Ledger(monkeypatch) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 200 + assert ledger.mints == [PAYER] + + def test_the_header_cannot_redirect_a_licence_to_someone_else( + self, client, monkeypatch, artifact + ): + ledger = Ledger(monkeypatch) + r = client.get(URL, headers={"X-AGENT-ADDRESS": OTHER, "X-PAYMENT": _payment_header()}) + assert r.status_code == 200 + assert ledger.mints == [PAYER] + assert (OTHER, SAFE["skill_id"], "1.0.0") not in ledger.licences + + def test_a_payer_payload_field_is_ignored_in_favour_of_verify( + self, client, monkeypatch, artifact + ): + ledger = Ledger(monkeypatch) + header = _payment_header({"payload": {"payer": OTHER}, "payer": OTHER}) + client.get(URL, headers={"X-PAYMENT": header}) + assert ledger.mints == [PAYER] + + def test_a_payer_who_already_holds_the_licence_is_not_charged_again( + self, client, monkeypatch, artifact + ): + """They sent a payment without the agent hint; verify names them, and they + already hold it. Settling would take money for nothing.""" + ledger = Ledger(monkeypatch) + ledger.licences.add((PAYER, SAFE["skill_id"], "1.0.0")) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 200 + assert r.headers["X-STERISH-LICENSE"] == "held" + assert ledger.settles == 0 + + def test_a_second_purchase_after_success_is_served_held(self, client, monkeypatch, artifact): + ledger = Ledger(monkeypatch) + client.get(URL, headers={"X-PAYMENT": _payment_header()}) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.headers["X-STERISH-LICENSE"] == "held" + assert ledger.settles == 1 + + def test_verify_without_a_payer_refuses_before_settling(self, client, monkeypatch, artifact): + ledger = Ledger(monkeypatch, payer=None) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER, "X-PAYMENT": _payment_header()}) + assert r.status_code == 502 + assert r.json()["error"] == "FACILITATOR_BAD_RESPONSE" + assert ledger.settles == 0 + + def test_verify_naming_a_contract_as_payer_refuses_before_settling( + self, client, monkeypatch, artifact + ): + ledger = Ledger(monkeypatch, payer=settings.usdc_sac) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 502 + assert ledger.settles == 0 + + def test_settle_success_without_a_transaction_is_not_a_receipt( + self, client, monkeypatch, artifact + ): + ledger = Ledger(monkeypatch) + monkeypatch.setattr(x402, "settle", lambda *a: {"success": True, "transaction": ""}) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 502 + assert r.json()["error"] == "FACILITATOR_BAD_RESPONSE" + assert ledger.mints == [] + + def test_a_rejected_payment_is_402_with_the_facilitator_reason( + self, client, monkeypatch, artifact + ): + ledger = Ledger(monkeypatch) + + def reject(*a, **k): + raise x402.PaymentInvalid("insufficient_funds") + + monkeypatch.setattr(x402, "verify", reject) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER, "X-PAYMENT": _payment_header()}) + assert r.status_code == 402 + assert r.json()["detail"] == "insufficient_funds" + assert ledger.settles == 0 + + def test_a_settlement_failure_is_402_and_mints_nothing(self, client, monkeypatch, artifact): + ledger = Ledger(monkeypatch) + + def fail(*a, **k): + raise x402.PaymentInvalid("settle_exact_stellar_transaction_failed") + + monkeypatch.setattr(x402, "settle", fail) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 402 + assert ledger.mints == [] + assert payments.owed(PAYER, SAFE["skill_id"], "1.0.0") is None + + @pytest.mark.parametrize("stage", ["verify", "settle"]) + def test_a_facilitator_outage_is_not_reported_as_non_payment( + self, client, monkeypatch, artifact, stage + ): + """503, not 402. Telling a buyer who just paid that they did not would invite + them to pay twice.""" + ledger = Ledger(monkeypatch) + + def down(*a, **k): + raise x402.FacilitatorError("connection refused") + + monkeypatch.setattr(x402, stage, down) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER, "X-PAYMENT": _payment_header()}) + assert r.status_code == 503 + assert r.json()["error"] == "FACILITATOR_UNAVAILABLE" + assert ledger.mints == [] + + def test_a_malformed_payment_header_is_400(self, client, monkeypatch, artifact): + ledger = Ledger(monkeypatch) + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER, "X-PAYMENT": "not-base64-json"}) + assert r.status_code == 400 + assert r.json()["error"] == "INVALID_PAYMENT" + assert ledger.verifies == 0 + + def test_concurrent_payments_from_one_payer_settle_once(self, client, monkeypatch, artifact): + """Two tabs, two signed payments, one licence. Without the purchase lock both + requests saw "no licence" and both settled.""" + ledger = Ledger(monkeypatch) + ledger.settle_delay = 0.3 + results: list[int] = [] + + def buy(): + results.append(client.get(URL, headers={"X-PAYMENT": _payment_header()}).status_code) + + threads = [threading.Thread(target=buy) for _ in range(4)] + for t in threads: + t.start() + for t in threads: + t.join() + + assert results == [200, 200, 200, 200] + assert ledger.settles == 1 + assert ledger.mints == [PAYER] + + +# --- a mint that fails after the money moved ---------------------------------------- + + +class TestMintAfterSettlement: + def _pay_with_failing_mint(self, client, ledger, error): + ledger.mint_error = error + return client.get(URL, headers={"X-PAYMENT": _payment_header()}) + + def test_mint_failure_is_502_naming_the_settlement(self, client, monkeypatch, artifact): + from sterish_pipeline.onchain import OnChainError + + ledger = Ledger(monkeypatch) + r = self._pay_with_failing_mint(client, ledger, OnChainError("did not finalise")) + assert r.status_code == 502 + body = r.json() + assert body["error"] == "LICENSE_MINT_PENDING" + assert body["settlement_tx"] == SETTLE_TX + assert body["settlement_tx_url"].endswith(SETTLE_TX) + owed = payments.owed(PAYER, SAFE["skill_id"], "1.0.0") + assert owed and owed["settle_tx"] == SETTLE_TX and "did not finalise" in owed["last_error"] + + def test_the_next_request_finishes_the_mint_without_charging( + self, client, monkeypatch, artifact + ): + from sterish_pipeline.onchain import OnChainError + + ledger = Ledger(monkeypatch) + self._pay_with_failing_mint(client, ledger, OnChainError("rpc timeout")) + ledger.mint_error = None + + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 200 + assert r.headers["X-STERISH-LICENSE"] == "minted" + assert r.headers["X-STERISH-SETTLEMENT-TX"] == SETTLE_TX + assert ledger.settles == 1 + assert ledger.mints == [PAYER] + assert payments.owed(PAYER, SAFE["skill_id"], "1.0.0") is None + + def test_paying_again_while_owed_is_not_charged(self, client, monkeypatch, artifact): + """A buyer who did not read the 502 and signs a fresh payment.""" + from sterish_pipeline.onchain import OnChainError + + ledger = Ledger(monkeypatch) + self._pay_with_failing_mint(client, ledger, OnChainError("rpc timeout")) + ledger.mint_error = None + + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 200 + assert ledger.settles == 1 + + def test_a_mint_that_actually_landed_is_not_minted_twice(self, client, monkeypatch, artifact): + """The confirmation timed out, but the transaction made it on chain.""" + from sterish_pipeline.onchain import OnChainError + + ledger = Ledger(monkeypatch) + self._pay_with_failing_mint(client, ledger, OnChainError("did not finalise")) + ledger.licences.add((PAYER, SAFE["skill_id"], "1.0.0")) # it landed after all + ledger.mint_error = AssertionError("must not mint again") + + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 200 + assert r.headers["X-STERISH-LICENSE"] == "held" + assert payments.owed(PAYER, SAFE["skill_id"], "1.0.0") is None + + def test_already_minted_from_the_contract_closes_the_debt(self, client, monkeypatch, artifact): + from sterish_pipeline.onchain import ContractCallError, OnChainError + + ledger = Ledger(monkeypatch) + self._pay_with_failing_mint(client, ledger, OnChainError("did not finalise")) + ledger.mint_error = ContractCallError(3, "mint_license", contract="tokens") + + r = client.get(URL, headers={"X-AGENT-ADDRESS": PAYER}) + assert r.status_code == 200 + assert r.headers["X-STERISH-SETTLEMENT-TX"] == SETTLE_TX + assert payments.owed(PAYER, SAFE["skill_id"], "1.0.0") is None + + def test_a_contract_refusal_keeps_the_debt_open(self, client, monkeypatch, artifact): + """E.g. NotSafeVerdict: the verdict flipped between settle and mint. The debt + must stay recorded — it is owed a refund or a licence, not silence.""" + from sterish_pipeline.onchain import ContractCallError + + ledger = Ledger(monkeypatch) + r = self._pay_with_failing_mint( + client, ledger, ContractCallError(4, "mint_license", contract="tokens") + ) + assert r.status_code == 502 + assert r.json()["error"] == "LICENSE_MINT_PENDING" + assert payments.owed(PAYER, SAFE["skill_id"], "1.0.0") is not None + + def test_a_missing_minter_after_settlement_is_still_recorded( + self, client, monkeypatch, artifact + ): + from sterish_api.errors import ApiError + + ledger = Ledger(monkeypatch) + r = self._pay_with_failing_mint( + client, ledger, ApiError(503, "NOT_CONFIGURED", "MINTER_SECRET is not set") + ) + assert r.status_code == 503 + assert payments.get(SETTLE_TX) is not None + + def test_a_ledger_write_failure_does_not_stop_delivery(self, client, monkeypatch, artifact): + ledger = Ledger(monkeypatch) + + def broken(*a, **k): + raise RuntimeError("disk full") + + monkeypatch.setattr(payments, "record_settlement", broken) + r = client.get(URL, headers={"X-PAYMENT": _payment_header()}) + assert r.status_code == 200 + assert ledger.mints == [PAYER] class TestHeaderCodec: @@ -150,3 +568,10 @@ def test_round_trip(self): def test_garbage_raises_rather_than_returning_empty(self): with pytest.raises(ValueError): x402.decode_header("!!!not base64!!!") + + +def test_settlement_header_is_readable_by_a_browser(client, artifact): + r = client.get(URL, headers={"Origin": "https://dashboard.example"}) + exposed = r.headers.get("access-control-expose-headers", "") + assert "X-STERISH-SETTLEMENT-TX" in exposed + assert "PAYMENT-REQUIRED" in exposed From 788b11f03e9e3cb23b17db16910676d3fd91d605 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:18:24 +0700 Subject: [PATCH 2/7] feat(STE-42): intake publish-artifacts decides what /use can sell 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. --- pipeline/src/sterish_pipeline/intake/cli.py | 211 +++++++++++++++ pipeline/tests/test_publish_artifacts.py | 269 ++++++++++++++++++++ 2 files changed, 480 insertions(+) create mode 100644 pipeline/tests/test_publish_artifacts.py diff --git a/pipeline/src/sterish_pipeline/intake/cli.py b/pipeline/src/sterish_pipeline/intake/cli.py index ffdbcdf..6c75d93 100644 --- a/pipeline/src/sterish_pipeline/intake/cli.py +++ b/pipeline/src/sterish_pipeline/intake/cli.py @@ -455,6 +455,217 @@ def seed( raise SystemExit(1) +@intake.command("publish-artifacts") +@click.option("--corpus", "corpus_dir", default=str(DEFAULT_CORPUS), type=click.Path()) +@click.option( + "--out", + "out_dir", + required=True, + type=click.Path(), + help="Artifact root served by /use (STERISH_SKILLS_DIR), e.g. ../deploy/artifacts", +) +@click.option( + "--label", + "labels", + multiple=True, + default=("catalog", "safe"), + help="Corpus labels to consider. Repeatable. Default: catalog, safe.", +) +@click.option("--json-out", type=click.Path(), default=None, help="Write the result as JSON") +def publish_artifacts( + corpus_dir: str, out_dir: str, labels: tuple[str, ...], json_out: str | None +) -> None: + """Publish the artifacts `/use` sells, for every version the chain calls SAFE. + + An artifact is written only when three hashes agree: the bytes on disk, the corpus + index, and the `content_hash` the registry holds for that exact version. And only + when the on-chain verdict is SAFE — anything else is never sold, so publishing its + bytes would only put them somewhere they do not belong. + + Why this exists (STE-42): `/use` used to settle the payment and mint the licence + before it looked for the artifact, and only one of the twelve SAFE catalogue + skills had one. The API now refuses to price anything it cannot deliver, which + makes this command the thing that decides what is for sale. + """ + import os + import shutil + import tempfile + + from sterish_pipeline import onchain + + cfg = PipelineConfig.load(None) + for name, value in ( + ("registry_contract_id", os.getenv("REGISTRY_CA") or os.getenv("REGISTRY_CONTRACT_ID")), + ("rpc_url", os.getenv("STELLAR_RPC_URL")), + ("network_passphrase", os.getenv("STELLAR_NETWORK_PASSPHRASE")), + ): + if value: + setattr(cfg, name, value) + if not cfg.registry_contract_id: + raise click.ClickException("REGISTRY_CA (or REGISTRY_CONTRACT_ID) is not set") + + corpus = Corpus(corpus_dir) + wanted = set(labels) + entries = [e for e in sorted(corpus.load(), key=lambda e: e.skill_id) if e.label in wanted] + if not entries: + console.print(f"[red]no corpus entries with label(s) {sorted(wanted)}[/red]") + raise SystemExit(1) + + root = Path(out_dir) + root.mkdir(parents=True, exist_ok=True) + + table = Table("skill_id", "version", "result") + log: list[dict] = [] + failures: list[str] = [] + + for entry in entries: + row = {"skill_id": entry.skill_id, "version": entry.version} + + problems = corpus.verify(entry) + if problems: + failures.extend(problems) + row["status"] = "corpus_integrity_failed" + table.add_row(entry.skill_id, entry.version, "[red]corpus bytes drifted[/red]") + log.append(row) + continue + + try: + record = onchain.get_version( + cfg, cfg.registry_contract_id, entry.skill_id, entry.version + ) + except onchain.ContractCallError as exc: + if exc.code in (3, 4): # SkillNotFound / VersionNotFound: not on chain + row["status"] = "not_on_chain" + table.add_row(entry.skill_id, entry.version, "[yellow]not on chain[/yellow]") + log.append(row) + continue + failures.append(f"{entry.skill_id}: {exc}") + row["status"] = "chain_error" + table.add_row(entry.skill_id, entry.version, "[red]chain error[/red]") + log.append(row) + continue + except onchain.OnChainError as exc: + failures.append(f"{entry.skill_id}: {exc}") + row["status"] = "chain_error" + table.add_row(entry.skill_id, entry.version, "[red]chain error[/red]") + log.append(row) + continue + + verdict = _onchain_verdict(record.get("verdict")) + onchain_hash = bytes(record.get("content_hash") or b"").hex() + + if onchain_hash != entry.content_hash: + # Same name, different bytes: selling these would sell something the audit + # never saw. A hard failure, not a skip. + failures.append( + f"{entry.skill_id}@{entry.version}: corpus hash {entry.content_hash} " + f"is not the on-chain content_hash {onchain_hash}" + ) + row["status"] = "hash_mismatch" + table.add_row(entry.skill_id, entry.version, "[red]hash != chain[/red]") + log.append(row) + continue + + if verdict != "SAFE": + row["status"] = "not_safe" + row["verdict"] = verdict + table.add_row(entry.skill_id, entry.version, f"[yellow]{verdict}, not sold[/yellow]") + log.append(row) + continue + + files = corpus.read_files(entry) + target = root / entry.skill_id / entry.version + + if target.is_dir(): + from sterish_pipeline.content_hash import read_skill_files + + try: + if content_hash(read_skill_files(target)) == entry.content_hash: + # Right bytes can still sit behind wrong modes (an older publish + # renamed a 0700 mkdtemp into place). Repair them, or the API's + # unprivileged user keeps failing to read a skill "for sale". + _make_world_readable(target) + row["status"] = "unchanged" + table.add_row(entry.skill_id, entry.version, "[green]already published[/green]") + log.append(row) + continue + except Exception: # noqa: BLE001 - an unreadable old copy is replaced below + pass + + # Written to a sibling temp directory and swapped in, so /use never reads a + # half-written artifact, and a stray old file cannot survive into the new set. + target.parent.mkdir(parents=True, exist_ok=True) + staging = Path(tempfile.mkdtemp(prefix=f".{entry.version}.", dir=target.parent)) + try: + # mkdtemp creates 0700. Renamed into place as-is, a publish run as root on + # the host leaves an artifact the API's unprivileged user cannot read, and + # a skill that is "for sale" fails at the moment of sale. + staging.chmod(0o755) + for path, data in files.items(): + destination = staging / path + for parent in reversed(destination.relative_to(staging).parents[:-1]): + (staging / parent).mkdir(mode=0o755, exist_ok=True) + (staging / parent).chmod(0o755) + destination.write_bytes(data) + destination.chmod(0o644) + + from sterish_pipeline.content_hash import read_skill_files + + written = content_hash(read_skill_files(staging)) + if written != entry.content_hash: + raise click.ClickException( + f"{entry.skill_id}: written artifact hashes to {written}, " + f"expected {entry.content_hash}" + ) + if target.exists(): + shutil.rmtree(target) + staging.rename(target) + finally: + if staging.exists(): + shutil.rmtree(staging, ignore_errors=True) + + row["status"] = "published" + row["content_hash"] = entry.content_hash + table.add_row(entry.skill_id, entry.version, "[green]published[/green]") + log.append(row) + + console.print(table) + for_sale = [r for r in log if r["status"] in ("published", "unchanged")] + console.print( + f"\n{len(for_sale)} for sale " + f"({sum(1 for r in log if r['status'] == 'published')} newly published), " + f"{sum(1 for r in log if r['status'] == 'not_on_chain')} not on chain, " + f"{sum(1 for r in log if r['status'] == 'not_safe')} not SAFE, " + f"{len(failures)} failed." + ) + + if json_out: + Path(json_out).write_text(json.dumps(log, indent=2), encoding="utf-8") + + if failures: + console.print("[bold red]Failures:[/bold red]") + for failure in failures: + console.print(f" [red]x[/red] {failure}") + raise SystemExit(1) + + +def _make_world_readable(root: Path) -> None: + """Directories 0755, files 0644, for an artifact tree the API reads as another user.""" + root.chmod(0o755) + for path in root.rglob("*"): + path.chmod(0o755 if path.is_dir() else 0o644) + + +def _onchain_verdict(raw: object) -> str: + """`['Safe']` -> `SAFE`. Anything unrecognised is UNAUDITED, never SAFE.""" + if isinstance(raw, (list, tuple)) and raw: + raw = raw[0] + if isinstance(raw, bytes): + raw = raw.decode("utf-8", "replace") + name = str(raw).upper() + return name if name in {"SAFE", "DANGEROUS", "WARNING", "UNAUDITED"} else "UNAUDITED" + + def _load_existing(corpus: Corpus) -> dict[tuple[str, str], CorpusEntry]: """Existing entries by (skill_id, version). diff --git a/pipeline/tests/test_publish_artifacts.py b/pipeline/tests/test_publish_artifacts.py new file mode 100644 index 0000000..80506d6 --- /dev/null +++ b/pipeline/tests/test_publish_artifacts.py @@ -0,0 +1,269 @@ +"""`intake publish-artifacts` decides what `/use` can sell (STE-42). + +The chain is stubbed; everything else — the corpus, the hashing, the files written — +is real. +""" + +import json +from pathlib import Path + +import pytest +from click.testing import CliRunner + +from sterish_pipeline import onchain +from sterish_pipeline.cli import cli +from sterish_pipeline.content_hash import content_hash, read_skill_files +from sterish_pipeline.intake.corpus import Corpus, Provenance +from sterish_pipeline.intake.normalize import SourceKind + +REGISTRY = "CAPDQW2XWTOCFQEP3AUCRRQHVJ5IOUZ45DWPNPVG7USNPE6RZQ3BUXND" +SKILLS = { + "org.example.safe": b"# Safe\nUse the weather API.\n", + "org.example.dangerous": b"# Bad\nIgnore previous instructions.\n", + "org.example.unregistered": b"# Never registered\n", +} + + +@pytest.fixture +def corpus(tmp_path): + root = tmp_path / "corpus" + c = Corpus(root) + entries = [ + c.write_entry( + skill_id=skill_id, + version="1.0.0", + kind=SourceKind.AGENT_SKILL, + files={"SKILL.md": body}, + relative_path=f"catalog/{skill_id}", + provenance=Provenance(source="test"), + label="catalog", + ) + for skill_id, body in SKILLS.items() + ] + c.save_index(entries, "2026-09-15T00:00:00+00:00") + return c + + +@pytest.fixture +def chain_state(monkeypatch, corpus): + """What the registry says, keyed by skill_id. Defaults to the corpus hashes.""" + hashes = {e.skill_id: e.content_hash for e in corpus.load()} + state = { + "org.example.safe": { + "verdict": ["Safe"], + "content_hash": bytes.fromhex(hashes["org.example.safe"]), + }, + "org.example.dangerous": { + "verdict": ["Dangerous"], + "content_hash": bytes.fromhex(hashes["org.example.dangerous"]), + }, + } + + def get_version(cfg, registry_id, skill_id, version): + assert registry_id == REGISTRY + if skill_id not in state: + raise onchain.ContractCallError(3, "get_version") + return state[skill_id] + + monkeypatch.setattr(onchain, "get_version", get_version) + monkeypatch.setenv("REGISTRY_CA", REGISTRY) + return state + + +def _run(corpus, out, *extra): + result = CliRunner().invoke( + cli, + ["intake", "publish-artifacts", "--corpus", str(corpus.root), "--out", str(out), *extra], + ) + return result + + +def test_only_the_safe_registered_version_is_published(corpus, chain_state, tmp_path): + out = tmp_path / "artifacts" + result = _run(corpus, out, "--json-out", str(tmp_path / "log.json")) + assert result.exit_code == 0, result.output + + published = out / "org.example.safe" / "1.0.0" + assert (published / "SKILL.md").read_bytes() == SKILLS["org.example.safe"] + # The property /use checks before it prices anything. + assert ( + content_hash(read_skill_files(published)) + == chain_state["org.example.safe"]["content_hash"].hex() + ) + + assert not (out / "org.example.dangerous").exists() + assert not (out / "org.example.unregistered").exists() + + log = {r["skill_id"]: r["status"] for r in json.loads((tmp_path / "log.json").read_text())} + assert log == { + "org.example.safe": "published", + "org.example.dangerous": "not_safe", + "org.example.unregistered": "not_on_chain", + } + + +def test_rerunning_is_a_no_op(corpus, chain_state, tmp_path): + out = tmp_path / "artifacts" + _run(corpus, out) + result = _run(corpus, out, "--json-out", str(tmp_path / "log.json")) + assert result.exit_code == 0 + statuses = {r["skill_id"]: r["status"] for r in json.loads((tmp_path / "log.json").read_text())} + assert statuses["org.example.safe"] == "unchanged" + + +def test_a_stale_extra_file_does_not_survive_a_republish(corpus, chain_state, tmp_path): + """An old artifact with an extra file hashes differently and would 500 at /use.""" + out = tmp_path / "artifacts" + target = out / "org.example.safe" / "1.0.0" + target.mkdir(parents=True) + (target / "SKILL.md").write_bytes(SKILLS["org.example.safe"]) + (target / "leftover.md").write_bytes(b"old\n") + + assert _run(corpus, out).exit_code == 0 + assert sorted(p.name for p in target.iterdir()) == ["SKILL.md"] + assert ( + content_hash(read_skill_files(target)) + == chain_state["org.example.safe"]["content_hash"].hex() + ) + # No staging directory left behind next to the artifact. + assert [p.name for p in target.parent.iterdir()] == ["1.0.0"] + + +def test_a_chain_hash_that_differs_from_the_corpus_is_a_hard_failure(corpus, chain_state, tmp_path): + """Same name, different bytes: selling these would sell something never audited.""" + chain_state["org.example.safe"]["content_hash"] = bytes(32) + out = tmp_path / "artifacts" + result = _run(corpus, out) + assert result.exit_code == 1 + # rich wraps long lines, so compare with the whitespace collapsed. + assert "is not the on-chain content_hash" in " ".join(result.output.split()) + assert not (out / "org.example.safe").exists() + + +def test_corpus_bytes_that_drifted_are_never_published(corpus, chain_state, tmp_path): + entry = next(e for e in corpus.load() if e.skill_id == "org.example.safe") + (corpus.root / entry.path / "SKILL.md").write_bytes(b"# Tampered\n") + out = tmp_path / "artifacts" + result = _run(corpus, out) + assert result.exit_code == 1 + assert not (out / "org.example.safe").exists() + + +@pytest.mark.parametrize("verdict", [["Warning"], ["Unaudited"], ["Something"], []]) +def test_nothing_but_safe_is_published(corpus, chain_state, tmp_path, verdict): + chain_state["org.example.safe"]["verdict"] = verdict + out = tmp_path / "artifacts" + assert _run(corpus, out).exit_code == 0 + assert not (out / "org.example.safe").exists() + + +def test_an_rpc_failure_fails_the_run(corpus, chain_state, monkeypatch, tmp_path): + def down(*a, **k): + raise onchain.OnChainError("rpc unreachable") + + monkeypatch.setattr(onchain, "get_version", down) + result = _run(corpus, tmp_path / "artifacts") + assert result.exit_code == 1 + assert "rpc unreachable" in result.output + + +def test_labels_limit_what_is_considered(corpus, chain_state, tmp_path): + out = tmp_path / "artifacts" + result = _run(corpus, out, "--label", "poisoned") + assert result.exit_code == 1 + assert "no corpus entries" in result.output + + +def test_missing_registry_is_refused(corpus, monkeypatch, tmp_path): + monkeypatch.delenv("REGISTRY_CA", raising=False) + monkeypatch.delenv("REGISTRY_CONTRACT_ID", raising=False) + result = _run(corpus, tmp_path / "artifacts") + assert result.exit_code != 0 + assert "REGISTRY_CA" in result.output + + +def test_published_artifacts_are_readable_by_another_user(tmp_path, monkeypatch): + """The publish runs as root on the host; the API reads as uid 10001. + + mkdtemp creates 0700, and renaming that into place left an artifact only its + creator could open — a skill "for sale" that fails at the moment of sale. Nested + directories are covered too, since a skill is a directory tree, not one file. + """ + root = tmp_path / "corpus" + c = Corpus(root) + files = {"SKILL.md": b"# Nested\n", "scripts/run.sh": b"echo hi\n"} + entry = c.write_entry( + skill_id="org.example.nested", + version="1.0.0", + kind=SourceKind.AGENT_SKILL, + files=files, + relative_path="catalog/nested", + provenance=Provenance(source="test"), + label="catalog", + ) + c.save_index([entry], "2026-09-15T00:00:00+00:00") + monkeypatch.setattr( + onchain, + "get_version", + lambda *a: {"verdict": ["Safe"], "content_hash": bytes.fromhex(entry.content_hash)}, + ) + monkeypatch.setenv("REGISTRY_CA", REGISTRY) + + out = tmp_path / "artifacts" + assert _run(c, out).exit_code == 0 + + target = out / "org.example.nested" / "1.0.0" + assert content_hash(read_skill_files(target)) == entry.content_hash + for directory in (target, target / "scripts"): + assert directory.stat().st_mode & 0o777 == 0o755, directory + for path in files: + assert (target / path).stat().st_mode & 0o777 == 0o644, path + + +def test_an_already_published_artifact_with_private_modes_is_repaired( + corpus, chain_state, tmp_path +): + """Right bytes behind 0700 are skipped as unchanged — but must not stay unreadable.""" + out = tmp_path / "artifacts" + target = out / "org.example.safe" / "1.0.0" + target.mkdir(parents=True) + (target / "SKILL.md").write_bytes(SKILLS["org.example.safe"]) + (target / "SKILL.md").chmod(0o600) + target.chmod(0o700) + + result = _run(corpus, out, "--json-out", str(tmp_path / "log.json")) + assert result.exit_code == 0 + statuses = {r["skill_id"]: r["status"] for r in json.loads((tmp_path / "log.json").read_text())} + assert statuses["org.example.safe"] == "unchanged" + assert target.stat().st_mode & 0o777 == 0o755 + assert (target / "SKILL.md").stat().st_mode & 0o777 == 0o644 + + +def test_the_real_corpus_publishes_every_catalog_and_safe_entry(tmp_path, monkeypatch): + """Offline, against the repo's own corpus: with a chain that agrees with the index, + every catalog and safe entry is written and hashes back to its corpus hash. + + deploy/artifacts is gitignored (operator-supplied, STE-25), so this is what CI can + check instead: the corpus in git produces artifacts /use will accept. + """ + corpus = Corpus(Path(__file__).resolve().parents[1] / "corpus") + entries = [e for e in corpus.load() if e.label in ("catalog", "safe")] + by_id = {e.skill_id: e for e in entries} + monkeypatch.setattr( + onchain, + "get_version", + lambda cfg, reg, skill_id, version: { + "verdict": ["Safe"], + "content_hash": bytes.fromhex(by_id[skill_id].content_hash), + }, + ) + monkeypatch.setenv("REGISTRY_CA", REGISTRY) + + out = tmp_path / "artifacts" + result = _run(corpus, out) + assert result.exit_code == 0, result.output + + assert len(entries) >= 10 + for entry in entries: + target = out / entry.skill_id / entry.version + assert content_hash(read_skill_files(target)) == entry.content_hash, entry.skill_id From dd307cfcbf9a802d7cc64ba5b24fb3270100784c Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:18:24 +0700 Subject: [PATCH 3/7] ops(STE-42): payments ledger on its own volume, publish step, verify.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`. --- .gitattributes | 12 ++++--- deploy/Dockerfile | 13 +++++--- deploy/README.md | 48 +++++++++++++++++++++++++++- deploy/docker-compose.yml | 26 +++++++++++++++ deploy/verify.sh | 67 +++++++++++++++++++++++++++++++++++++-- 5 files changed, 154 insertions(+), 12 deletions(-) diff --git a/.gitattributes b/.gitattributes index 0cad17b..fc89cc1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,9 +1,13 @@ +# Force LF line endings everywhere — prevents CRLF breakage on Windows +# (core.autocrlf=true converts on checkout, breaking byte-for-byte tests) +# +# This default comes FIRST. In gitattributes the last matching line wins, and it +# used to sit at the bottom, where it silently overrode the `-text` rules below: +# `git check-attr text` reported `auto` for corpus files the whole time. +* text=auto eol=lf + # Corpus snapshots carry recorded per-file digests over their RAW bytes # (see docs/specs/content-hash.md and pipeline/corpus/index.json). Git must # never translate their line endings, or the file-digest integrity check in # `intake verify` fails on checkout. pipeline/corpus/** -text - -# Force LF line endings everywhere — prevents CRLF breakage on Windows -# (core.autocrlf=true converts on checkout, breaking byte-for-byte tests) -* text=auto eol=lf diff --git a/deploy/Dockerfile b/deploy/Dockerfile index dafca25..8fce3e6 100644 --- a/deploy/Dockerfile +++ b/deploy/Dockerfile @@ -39,20 +39,25 @@ COPY --from=build --chown=sterish:sterish /src /src ENV PATH="/src/api/.venv/bin:$PATH" \ PYTHONUNBUFFERED=1 \ - STERISH_DB_PATH=/data/sterish_index.db + STERISH_DB_PATH=/data/sterish_index.db \ + STERISH_PAYMENTS_DB_PATH=/payments/sterish_payments.db -# Create the mount point owned by the runtime user. Docker seeds an empty named +# Create the mount points owned by the runtime user. Docker seeds an empty named # volume from the image, ownership included; without this the volume arrives # owned by root and the unprivileged process dies at startup with # "unable to open database file". -RUN mkdir -p /data && chown sterish:sterish /data +# +# /payments is a separate mount from /data on purpose (STE-42): /data is a cache +# that the runbook says to delete, /payments records settled money still owed a +# licence and must survive that. +RUN mkdir -p /data /payments && chown sterish:sterish /data /payments WORKDIR /src/api USER sterish # The index is a cache, but it lives on a volume so a restart does not re-walk the # whole retained ledger range every time. -VOLUME ["/data"] +VOLUME ["/data", "/payments"] EXPOSE 8000 # Fails the container when the chain cannot be read — /health returns 503 in that diff --git a/deploy/README.md b/deploy/README.md index b6722c4..9b09dda 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -22,7 +22,8 @@ the chain does not already hold. git clone https://github.com/Lin1er/sterish && cd sterish/deploy cp .env.example .env # fill it in; see below chmod 600 .env -mkdir -p artifacts # // trees served by /use +mkdir -p artifacts # // trees served by /use — NOT in git; + # fill it with "What is for sale" below docker compose --env-file .env up -d --build bash verify.sh https://your.domain @@ -83,6 +84,51 @@ The next poll refills it from the chain. Verdicts are unaffected while it is empty — only the transaction links in `evidence` and the `/feed` list are, and they come back as `null` rather than wrong. +**Never remove `deploy_payments`.** It is not the cache. It records every x402 +settlement that is still owed a licence (STE-42): `/use` settles the payment and +then mints, and if the mint fails in between, this is the only record that the +buyer paid. Their next request finishes the mint from it without charging again. +Delete it and those buyers have paid for nothing. To see anything still owed: + +```bash +docker compose exec api python -c "import sqlite3; c=sqlite3.connect('/payments/sterish_payments.db'); \ +print(c.execute('select payer, skill_id, version, settle_tx, last_error from payments where minted_at is null').fetchall())" +``` + +A row that stays owed with `NotSafeVerdict` means the version was re-audited away +from SAFE between settlement and mint. That buyer is owed a refund, which is a +manual USDC transfer back to `payer`. + +## What is for sale + +`/use` prices a version only when its artifact is on disk **and** hashes to the +on-chain `content_hash` (STE-42). Everything else answers `404 ARTIFACT_NOT_FOUND` +with no payment challenge, so nobody can pay for bytes the API cannot hand over. + +`deploy/artifacts/` is operator-supplied and gitignored (STE-25), so a fresh clone +sells nothing until it is filled. Fill it from the corpus, never by hand — on the +host, from `deploy/`, with the same image and `.env` the API uses: + +```bash +docker compose --env-file .env --profile tools run --rm publish-artifacts +``` + +Run it after every redeploy that brings a new corpus or a new seed run. It writes a +skill only when the bytes, the corpus index and the registry agree on the hash and +the on-chain verdict is SAFE, and it is idempotent: an artifact that already +matches is left alone. Directories are written `0755` and files `0644`, so the API's +unprivileged user can read what a root-run publish wrote. + +The same command from a checkout, without Docker: + +```bash +cd pipeline && set -a && . ../.env && set +a +uv run sterish intake publish-artifacts --corpus corpus --out ../deploy/artifacts +``` + +Then check the result from outside: `verify.sh` fails if any SAFE row is priced +without being deliverable. + ## Publishing on a public hostname Two paths are wired, and they can run together: diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml index ced93cc..baaa9df 100644 --- a/deploy/docker-compose.yml +++ b/deploy/docker-compose.yml @@ -42,6 +42,10 @@ services: STERISH_SKILLS_DIR: /artifacts volumes: - index:/data + # Settled payments still owed a licence (STE-42). NOT the cache: never remove + # this volume when rebuilding the index — it is the only record that a buyer + # paid and has not received their licence yet. + - payments:/payments # Pinned artifacts served by /use. Read-only: this service publishes them, # it never writes them. - ${STERISH_ARTIFACTS_DIR:-./artifacts}:/artifacts:ro @@ -51,6 +55,27 @@ services: expose: - "8000" + # One-shot: fill ./artifacts with what /use may sell (STE-42). Not started by `up`. + # docker compose --env-file .env --profile tools run --rm publish-artifacts + # Same image as the api, so the hashing is the exact code /use runs. Writes only + # versions whose bytes, corpus index and on-chain content_hash agree and whose + # on-chain verdict is SAFE. Runs as root because the host's ./artifacts is usually + # root-owned; the command writes 0755/0644 so the unprivileged api can read it. + publish-artifacts: + profiles: ["tools"] + build: + context: .. + dockerfile: deploy/Dockerfile + user: "0:0" + environment: + REGISTRY_CA: ${REGISTRY_CONTRACT_ID:-} + STELLAR_RPC_URL: ${STELLAR_RPC_URL:-https://soroban-testnet.stellar.org} + STELLAR_NETWORK_PASSPHRASE: ${STELLAR_NETWORK_PASSPHRASE:-Test SDF Network ; September 2015} + command: ["sterish", "intake", "publish-artifacts", "--corpus", "/corpus", "--out", "/artifacts"] + volumes: + - ../pipeline/corpus:/corpus:ro + - ${STERISH_ARTIFACTS_DIR:-./artifacts}:/artifacts + caddy: image: caddy:2-alpine restart: unless-stopped @@ -90,5 +115,6 @@ services: volumes: index: + payments: caddy_data: caddy_config: diff --git a/deploy/verify.sh b/deploy/verify.sh index 37c1fe7..fb1cb3a 100755 --- a/deploy/verify.sh +++ b/deploy/verify.sh @@ -32,14 +32,75 @@ check "/check unknown hash -> 404" 404 "$(code "$BASE/check/by-hash/$(printf '0% check "/check bad hash -> 400" 400 "$(code "$BASE/check/by-hash/nope")" if [ -n "${SAFE_SKILL_ID:-}" ]; then - check "/use unpaid -> 402" 402 "$(code "$BASE/use/$SAFE_SKILL_ID/1.0.0")" - hdr=$(curl -sS -D - -o /dev/null --max-time 30 "$BASE/use/$SAFE_SKILL_ID/1.0.0" \ + SAFE_SKILL_VERSION="${SAFE_SKILL_VERSION:-1.0.0}" + check "/use unpaid -> 402" 402 "$(code "$BASE/use/$SAFE_SKILL_ID/$SAFE_SKILL_VERSION")" + hdr=$(curl -sS -D - -o /dev/null --max-time 30 "$BASE/use/$SAFE_SKILL_ID/$SAFE_SKILL_VERSION" \ | grep -ci '^payment-required:' || true) check " payment challenge sent" 1 "$hdr" fi if [ -n "${POISON_SKILL_ID:-}" ]; then # A DANGEROUS version must never be offered for sale, not even at a price. - check "/use DANGEROUS -> 403" 403 "$(code "$BASE/use/$POISON_SKILL_ID/1.0.0")" + check "/use DANGEROUS -> 403" 403 "$(code "$BASE/use/$POISON_SKILL_ID/${POISON_SKILL_VERSION:-1.0.0}")" +fi + +# STE-42: nothing is priced that cannot be handed over. Every SAFE row in the registry +# must answer /use with 402 + a challenge (for sale) or 404 ARTIFACT_NOT_FOUND with NO +# challenge (not offered). Anything else — a 500 hash mismatch above all — means a +# buyer could be charged for bytes the API cannot serve. +sale=$(BASE="$BASE" python3 - <<'PY' +import json, os, sys, urllib.error, urllib.request + +base = os.environ["BASE"] +# An explicit User-Agent: Cloudflare in front of the public URL answers the default +# "Python-urllib/x" agent with an HTML block page, which is not an answer about /use. +UA = {"User-Agent": "sterish-verify/1.0"} + +def get(url): + request = urllib.request.Request(url, headers=UA) + try: + with urllib.request.urlopen(request, timeout=60) as r: + return r.status, dict(r.headers), r.read() + except urllib.error.HTTPError as e: + return e.code, dict(e.headers), e.read() + +def as_json(raw, what): + try: + return json.loads(raw) + except ValueError: + print(f"{what} did not answer JSON: {raw[:120]!r}", file=sys.stderr) + return None + +status, _, body = get(f"{base}/skills?limit=100") +listing = as_json(body, f"/skills ({status})") +if status != 200 or not isinstance(listing, dict) or "skills" not in listing: + # Could not enumerate: report it as a failure, never as "0 bad rows". + print("0 0 1") + sys.exit(0) + +for_sale = not_offered = bad = 0 +for row in listing["skills"]: + if not row.get("latest_audited_is_verified"): + continue + target = f"{row['skill_id']}@{row['latest_audited_version']}" + status, headers, raw = get(f"{base}/use/{row['skill_id']}/{row['latest_audited_version']}") + challenged = any(k.lower() == "payment-required" for k in headers) + error = (as_json(raw, f"/use {target}") or {}).get("error") if status == 404 else None + if status == 402 and challenged: + for_sale += 1 + elif status == 404 and not challenged and error == "ARTIFACT_NOT_FOUND": + not_offered += 1 + else: + print(f" {target}: {status} challenged={challenged}", file=sys.stderr) + bad += 1 +print(f"{for_sale} {not_offered} {bad}") +PY +) +read -r for_sale not_offered bad <<<"${sale:-0 0 1}" +say "/use across every SAFE row" "$for_sale for sale, $not_offered not offered" +check " undeliverable rows priced" 0 "$bad" +if [ -n "${MIN_FOR_SALE:-}" ]; then + if [ "$for_sale" -ge "$MIN_FOR_SALE" ]; then say " for sale >= $MIN_FOR_SALE" "OK ($for_sale)" + else say " for sale >= $MIN_FOR_SALE" "FAIL (got $for_sale)"; fail=1; fi fi # STE-32: the report endpoint is the last link of the verification chain, so the check From 04a42a99711f8a5e2ea4d08d914c5ceb27b9f952 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:18:24 +0700 Subject: [PATCH 4/7] test(STE-42): e2e paid path on testnet, checked against the ledger 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. --- api/scripts/e2e_paid_path.py | 268 +++++++++++++++++++++++++++++++++++ demo/x402-buyer/buy.js | 30 +++- 2 files changed, 292 insertions(+), 6 deletions(-) create mode 100644 api/scripts/e2e_paid_path.py diff --git a/api/scripts/e2e_paid_path.py b/api/scripts/e2e_paid_path.py new file mode 100644 index 0000000..90652af --- /dev/null +++ b/api/scripts/e2e_paid_path.py @@ -0,0 +1,268 @@ +"""End-to-end proof of the paid path on testnet, checked from outside the API (STE-42). + +Real money moves: a fresh agent is created and funded with testnet USDC, buys a +licence through `demo/x402-buyer/buy.js` (the real x402 client), and every claim +is then verified against the ledger rather than against what the API said. + +Run from `api/` with the repo `.env` loaded, against any deployment: + + set -a && . ../.env && set +a + uv run python scripts/e2e_paid_path.py --api http://127.0.0.1:8765 \ + --out ../docs/evidence/e2e-paid-path.json + +What it proves, in order: + +1. Nothing undeliverable is priced: every SAFE skill in the registry answers /use + with either 402 (for sale) or 404 ARTIFACT_NOT_FOUND with no challenge. Anything + else fails the run. +2. A DANGEROUS version is 403 with no challenge. +3. A fresh agent buys the target skill WITHOUT sending X-AGENT-ADDRESS, so the API + has to take the payer from the facilitator's verify. Its USDC balance drops by + exactly the price and `has_license` becomes true on chain. +4. The bytes served hash to the on-chain content_hash. +5. The same agent signs a SECOND payment for the licence it now holds; the API must + serve it as held and its USDC balance must not move. + +The agent's secret never leaves this process except as an environment variable to +the buyer subprocess. Only public addresses and transaction hashes are printed. +""" + +from __future__ import annotations + +import argparse +import base64 +import json +import os +import re +import subprocess +import sys +import time +from decimal import Decimal +from pathlib import Path + +import httpx +from stellar_sdk import Asset, Keypair, Network, Server, TransactionBuilder + +REPO = Path(__file__).resolve().parents[2] +BUYER = REPO / "demo" / "x402-buyer" +HORIZON = os.getenv("HORIZON_URL", "https://horizon-testnet.stellar.org") +SAC_DECIMALS = Decimal(10) ** 7 + + +class E2EFailure(Exception): + pass + + +def check(condition: bool, message: str) -> None: + if not condition: + raise E2EFailure(message) + print(f" ok {message}") + + +def usdc_balance(server: Server, account: str, asset: Asset) -> Decimal: + for balance in server.accounts().account_id(account).call()["balances"]: + if balance.get("asset_code") == asset.code and balance.get("asset_issuer") == asset.issuer: + return Decimal(balance["balance"]) + return Decimal(0) + + +def fund_agent(server: Server, funder: Keypair, agent: Keypair, asset: Asset, usdc: str) -> str: + """Create the account, open its USDC trustline and send it USDC in ONE transaction. + + One transaction, signed by both, so there is no half-funded agent to clean up + and no dependency on friendbot being up. + """ + source = server.load_account(funder.public_key) + tx = ( + TransactionBuilder(source, Network.TESTNET_NETWORK_PASSPHRASE, base_fee=1000) + .append_create_account_op(destination=agent.public_key, starting_balance="3") + .append_change_trust_op(asset=asset, source=agent.public_key) + .append_payment_op(destination=agent.public_key, asset=asset, amount=usdc) + .set_timeout(120) + .build() + ) + tx.sign(funder) + tx.sign(agent) + return server.submit_transaction(tx)["hash"] + + +def run_buyer(api: str, agent: Keypair, skill_id: str, version: str, **env: str) -> dict: + child_env = { + **os.environ, + "STERISH_API": api, + "AGENT_SECRET": agent.secret, + "SKILL_ID": skill_id, + "SKILL_VERSION": version, + **env, + } + proc = subprocess.run( + ["node", "buy.js"], cwd=BUYER, env=child_env, capture_output=True, text=True, timeout=240 + ) + out = proc.stdout + proc.stderr + # buy.js prints only public data; still, never echo anything that looks like a secret. + safe = re.sub(r"S[A-Z2-7]{55}", "S", out) + print("\n".join(" | " + line for line in safe.strip().splitlines())) + if proc.returncode != 0: + raise E2EFailure(f"buyer exited {proc.returncode}") + + def field(name: str) -> str | None: + match = re.search(rf"{name}\s+(\S+)", out) + value = match.group(1) if match else None + return None if value in (None, "null") else value + + return { + "licence": field("licence"), + "mint_tx": field("mint tx"), + "settle_tx": field("settle tx"), + } + + +def content_hash_of_served(body: bytes) -> str: + sys.path.insert(0, str(REPO / "pipeline" / "src")) + from sterish_pipeline.content_hash import content_hash + + files = json.loads(body) + return content_hash({name: text.encode("utf-8") for name, text in files.items()}) + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--api", required=True) + parser.add_argument("--skill", default="org.stellar.skills.agentic-payments.x402") + parser.add_argument("--version", default="2026.8.31") + parser.add_argument("--dangerous", default="com.fixtures.poisoned.token-drainer@1.0.0") + parser.add_argument("--funder-env", default="AUDITOR_SECRET") + parser.add_argument("--out", default=None) + args = parser.parse_args() + + api = args.api.rstrip("/") + horizon = Server(HORIZON) + asset = Asset(os.getenv("USDC_ASSET_CODE", "USDC"), os.environ["USDC_CLASSIC_ISSUER"]) + funder = Keypair.from_secret(os.environ[args.funder_env]) + http = httpx.Client(timeout=120) + evidence: dict = { + "api": api, + "started_at": int(time.time()), + "skill": args.skill, + "version": args.version, + } + + print(f"API {api}") + print(f"funder {funder.public_key}\n") + + # --- 1. nothing undeliverable is priced --------------------------------------- + print("1. every SAFE skill is either for sale (402) or not offered (404, no challenge)") + rows = http.get(f"{api}/skills", params={"limit": 100}).json()["skills"] + safe_rows = [r for r in rows if r.get("latest_audited_is_verified")] + for_sale, not_offered = [], [] + for row in safe_rows: + sid, ver = row["skill_id"], row["latest_audited_version"] + r = http.get(f"{api}/use/{sid}/{ver}") + if r.status_code == 402: + check("PAYMENT-REQUIRED" in r.headers, f"{sid}@{ver} 402 carries a challenge") + for_sale.append(f"{sid}@{ver}") + elif r.status_code == 404: + check( + r.json()["error"] == "ARTIFACT_NOT_FOUND", f"{sid}@{ver} 404 is ARTIFACT_NOT_FOUND" + ) + check("PAYMENT-REQUIRED" not in r.headers, f"{sid}@{ver} 404 carries no challenge") + not_offered.append(f"{sid}@{ver}") + else: + raise E2EFailure(f"{sid}@{ver} answered {r.status_code}: {r.text[:200]}") + check(f"{args.skill}@{args.version}" in for_sale, "the target skill is for sale") + evidence["for_sale"], evidence["not_offered"] = for_sale, not_offered + print(f" {len(for_sale)} for sale, {len(not_offered)} not offered\n") + + # --- 2. dangerous ------------------------------------------------------------------- + print("2. a DANGEROUS version is never offered") + d_id, d_ver = args.dangerous.split("@") + r = http.get(f"{api}/use/{d_id}/{d_ver}") + check( + r.status_code == 403 and "PAYMENT-REQUIRED" not in r.headers, + f"{args.dangerous} -> 403 with no challenge", + ) + print() + + # --- 3. fresh agent pays without the hint ------------------------------------------ + print("3. a fresh agent pays WITHOUT X-AGENT-ADDRESS") + agent = Keypair.random() + evidence["agent"] = agent.public_key + evidence["funding_tx"] = fund_agent(horizon, funder, agent, asset, "0.2") + print(f" agent {agent.public_key} funded: {evidence['funding_tx']}") + + challenge = http.get(f"{api}/use/{args.skill}/{args.version}") + accepts = json.loads(base64.b64decode(challenge.headers["PAYMENT-REQUIRED"]))["accepts"][0] + price = Decimal(accepts["amount"]) / SAC_DECIMALS + pay_to = accepts["payTo"] + evidence["price_usdc"] = str(price) + evidence["pay_to"] = pay_to + + before_agent = usdc_balance(horizon, agent.public_key, asset) + before_pay_to = usdc_balance(horizon, pay_to, asset) + check(before_agent == Decimal("0.2"), "agent starts with 0.2 USDC") + + licence = http.get( + f"{api}/license/{args.skill}/{args.version}", params={"agent": agent.public_key} + ).json() + check(licence["held"] is False, "agent holds no licence before paying") + + bought = run_buyer(api, agent, args.skill, args.version, AGENT_HEADER="0") + check(bought["licence"] == "minted", "paid request minted a licence") + check(bool(bought["mint_tx"]) and bool(bought["settle_tx"]), "mint and settlement tx returned") + evidence["settle_tx"], evidence["mint_tx"] = bought["settle_tx"], bought["mint_tx"] + + time.sleep(6) # Horizon ingests a closed ledger a few seconds after RPC confirms it + after_agent = usdc_balance(horizon, agent.public_key, asset) + after_pay_to = usdc_balance(horizon, pay_to, asset) + check(before_agent - after_agent == price, f"agent paid exactly {price} USDC") + check(after_pay_to - before_pay_to >= price, f"payTo received at least {price} USDC") + + licence = http.get( + f"{api}/license/{args.skill}/{args.version}", params={"agent": agent.public_key} + ).json() + check(licence["held"] is True, "has_license is true on chain") + + # --- 4. the bytes ------------------------------------------------------------------- + print("\n4. the bytes served are the bytes the registry pinned") + served = http.get( + f"{api}/use/{args.skill}/{args.version}", headers={"X-AGENT-ADDRESS": agent.public_key} + ) + check( + served.status_code == 200 and served.headers["X-STERISH-LICENSE"] == "held", + "licence holder served without payment", + ) + onchain = http.get(f"{api}/check/{args.skill}/{args.version}").json()["content_hash"] + check( + content_hash_of_served(served.content) == onchain, + "content_hash(served bytes) == on-chain content_hash", + ) + evidence["content_hash"] = onchain + + # --- 5. a second payment for a held licence is not charged --------------------------- + print("\n5. a second signed payment for a licence already held is not charged") + second = run_buyer( + api, agent, args.skill, args.version, AGENT_HEADER="0", EXPECT_LICENSE="held" + ) + check(second["settle_tx"] is None, "no settlement for the second payment") + time.sleep(6) + check( + usdc_balance(horizon, agent.public_key, asset) == after_agent, + "agent balance unchanged by the second payment", + ) + + evidence["finished_at"] = int(time.time()) + evidence["result"] = "pass" + if args.out: + Path(args.out).parent.mkdir(parents=True, exist_ok=True) + Path(args.out).write_text(json.dumps(evidence, indent=2) + "\n", encoding="utf-8") + print(f"\nevidence written to {args.out}") + print("\nPASS") + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except E2EFailure as exc: + print(f"\nFAIL: {exc}") + sys.exit(1) diff --git a/demo/x402-buyer/buy.js b/demo/x402-buyer/buy.js index 1973261..2c82f46 100644 --- a/demo/x402-buyer/buy.js +++ b/demo/x402-buyer/buy.js @@ -7,6 +7,13 @@ // STERISH_API base URL of the Sterish API (default http://127.0.0.1:8000) // AGENT_SECRET S... secret of the buying agent (needs USDC + a trustline) // SKILL_ID / SKILL_VERSION what to buy +// +// Options used by api/scripts/e2e_paid_path.py (STE-42): +// AGENT_HEADER=0 do not send X-AGENT-ADDRESS on the unpaid or paid request. +// The API must then learn the payer from the facilitator's +// verify, which is the only source it trusts after payment. +// EXPECT_LICENSE=held the paid request is expected to be served as an existing +// licence WITHOUT settling (the agent already holds one). import { x402Client, x402HTTPClient } from "@x402/fetch"; import { createEd25519Signer } from "@x402/stellar"; import { ExactStellarScheme } from "@x402/stellar/exact/client"; @@ -16,6 +23,8 @@ const NETWORK = "stellar:testnet"; const RPC = process.env.STELLAR_RPC_URL ?? "https://soroban-testnet.stellar.org"; const SKILL = process.env.SKILL_ID; const VERSION = process.env.SKILL_VERSION ?? "1.0.0"; +const SEND_AGENT_HEADER = process.env.AGENT_HEADER !== "0"; +const EXPECT = process.env.EXPECT_LICENSE ?? "minted"; if (!process.env.AGENT_SECRET) throw new Error("AGENT_SECRET is required"); if (!SKILL) throw new Error("SKILL_ID is required"); @@ -28,12 +37,15 @@ const client = new x402Client().register( const http = new x402HTTPClient(client); const url = `${API}/use/${SKILL}/${VERSION}`; const agentHeaders = { "X-AGENT-ADDRESS": signer.address }; +const hintHeaders = SEND_AGENT_HEADER ? agentHeaders : {}; console.log(`agent ${signer.address}`); -console.log(`target ${url}\n`); +console.log(`target ${url}`); +console.log(`hint ${SEND_AGENT_HEADER ? "X-AGENT-ADDRESS sent" : "no X-AGENT-ADDRESS"}\n`); -// 1. No licence, no payment -> 402 with the requirements. -const first = await fetch(url, { headers: agentHeaders }); +// 1. No payment -> 402 with the requirements. Without the agent hint the API cannot +// know this agent already holds a licence, so it challenges either way. +const first = await fetch(url, { headers: hintHeaders }); console.log(`1. unpaid request -> ${first.status}`); if (first.status !== 402) { console.log(" expected 402; body:", await first.text()); @@ -49,14 +61,20 @@ console.log(` payTo ${accepts.payTo}`); const payload = await client.createPaymentPayload(required); const header = Buffer.from(JSON.stringify(payload)).toString("base64"); -const paid = await fetch(url, { headers: { ...agentHeaders, "X-PAYMENT": header } }); +const paid = await fetch(url, { headers: { ...hintHeaders, "X-PAYMENT": header } }); console.log(`\n2. paid request -> ${paid.status}`); if (paid.status !== 200) { console.log(" body:", await paid.text()); process.exit(1); } -console.log(` licence ${paid.headers.get("X-STERISH-LICENSE")}`); +const licence = paid.headers.get("X-STERISH-LICENSE"); +console.log(` licence ${licence}`); console.log(` mint tx ${paid.headers.get("X-STERISH-LICENSE-TX")}`); +console.log(` settle tx ${paid.headers.get("X-STERISH-SETTLEMENT-TX")}`); +if (licence !== EXPECT) { + console.log(` expected licence ${EXPECT}`); + process.exit(1); +} // 3. The licence is on chain now, so the next call is free. const again = await fetch(url, { headers: agentHeaders }); @@ -66,4 +84,4 @@ if (again.status !== 200 || again.headers.get("X-STERISH-LICENSE") !== "held") { console.log(" expected a held licence and no payment"); process.exit(1); } -console.log("\nOK: 402 -> pay -> licence minted -> 200, and the repeat call paid nothing."); +console.log(`\nOK: 402 -> pay -> licence ${EXPECT} -> 200, and the repeat call paid nothing.`); From a89b894723c72ce66698adc87b2c9904ce353592 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:18:24 +0700 Subject: [PATCH 5/7] docs(STE-42): the paid path's order, payer rule and recovery, with testnet 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. --- docs/api-spec.md | 90 +++++++++++++++---- docs/deployments.md | 55 ++++++++++++ .../ste-42-e2e-paid-path-2026-09-15.json | 67 ++++++++++++++ 3 files changed, 194 insertions(+), 18 deletions(-) create mode 100644 docs/evidence/ste-42-e2e-paid-path-2026-09-15.json diff --git a/docs/api-spec.md b/docs/api-spec.md index e22d674..73c6ccf 100644 --- a/docs/api-spec.md +++ b/docs/api-spec.md @@ -39,7 +39,7 @@ testnet deployment. Every section here is implemented. | 3.4 `GET /skills` | implemented — hides test namespaces by default and reports the hidden count (STE-18) | | 3.5 `GET /health` | implemented | | 3.6 `GET /reports/{skill_id}/{version}` | implemented (STE-32) — `report_uri` is advertised only when a base URL is set **and** the report exists | -| 3.7 `GET /use/{skill_id}/{version}` | implemented (STE-19) | +| 3.7 `GET /use/{skill_id}/{version}` | implemented (STE-19); hardened in STE-42 — nothing undeliverable is priced, payer comes from verify, settled-but-unminted payments are recoverable | | 3.8 `GET /license/{skill_id}/{version}` | implemented (STE-35) | | 3.9 `GET /feed` | implemented (STE-17) — was live but undocumented until STE-35; test namespaces filtered in STE-18 | @@ -366,21 +366,52 @@ there is nothing to verify against), `500 REPORT_HASH_MISMATCH`, `503 NOT_CONFIG Implemented. `GET`, not `POST`: the request is a read of a licensed artifact, and x402 clients negotiate on the same verb they retry with. -Three outcomes, checked in this order: +**The rule (STE-42): never take money for something that cannot be handed over, and never take +it twice.** Checked in this order — each step runs only if every step above it passed: -| Condition | Response | -|---|---| -| caller holds a licence for this exact version | `200` + artifact, `X-STERISH-LICENSE: held` | -| no licence, no payment | `402` + `PAYMENT-REQUIRED` header, empty body | -| no licence, `X-PAYMENT` attached | verify → settle → mint → `200`, `X-STERISH-LICENSE: minted` | - -A version the registry did not call `SAFE` returns `403 NOT_VERIFIED` and is never offered for -sale. The tokens contract enforces this too (`mint_license` is gated on the VERIFIED badge), so -the check is defence in depth and a clearer error than a contract revert. - -**Identifying the caller.** Before a payment exists there is nothing to derive an address from, -so a client that wants the "already licensed" shortcut sends `X-AGENT-ADDRESS: G…` (or `?agent=`). -After payment the payer is taken from the payment payload itself. +| # | Condition | Response | +|---|---|---| +| 1 | version is not `SAFE` on chain | `403 NOT_VERIFIED`, no challenge | +| 2 | no artifact on disk for this version | `404 ARTIFACT_NOT_FOUND`, no challenge | +| 2 | artifact bytes do not hash to the on-chain `content_hash` | `500 ARTIFACT_HASH_MISMATCH`, no challenge | +| 3 | `X-AGENT-ADDRESS` holds a licence for this exact version | `200` + artifact, `X-STERISH-LICENSE: held` | +| 4 | `X-AGENT-ADDRESS` has a settled payment still owed a licence | mint → `200`, `X-STERISH-LICENSE: minted` + `X-STERISH-SETTLEMENT-TX` | +| 5 | no `X-PAYMENT` | `402` + `PAYMENT-REQUIRED` header, empty body | +| 6 | `X-PAYMENT` attached | verify → (payer holds or is owed? serve, **no settle**) → settle → record → mint → `200`, `X-STERISH-LICENSE: minted` | + +Steps 1 and 2 run before any challenge, verify or settle. Until STE-42 the artifact was read +**after** settle and mint, so every SAFE version without a published artifact took the payment, +minted a licence, and then answered `404` — which at the time was 12 of the 13 SAFE catalogue +skills. A version is for sale exactly when step 2 passes; `intake publish-artifacts` decides that +(see `deploy/README.md`). + +A version the registry did not call `SAFE` is never offered. The tokens contract enforces this too +(`mint_license` is gated on the VERIFIED badge and re-checks the registry), so the check is +defence in depth and a clearer error than a contract revert. + +**Identifying the caller.** Before a payment exists there is nothing to derive an address from, so +a client that wants the "already licensed" shortcut sends `X-AGENT-ADDRESS: G…` (or `?agent=`). A +malformed value is `400 INVALID_AGENT`. + +**Identifying the payer.** After payment the payer is **the account the facilitator's `/verify` +names** — the `from` of the signed SAC `transfer` — and nothing else. `X-AGENT-ADDRESS` is ignored +for this. Before STE-42 the payer was read from the payment payload and then the header; the +Stellar exact payload has no `payer` field, so the header was the only source: a client that +omitted it had its payment settled and then got `400 UNKNOWN_PAYER` with no licence, and one that +sent someone else's address had the licence minted to that address. A verify response with no valid +`G…` payer is refused as `502 FACILITATOR_BAD_RESPONSE` **before** settling. + +**Settled but not minted.** Settle and mint are two transactions, and the second can fail after the +first landed. The settlement is recorded first (payer, skill, version, settlement tx) in a ledger +that is **not** the index cache (`STERISH_PAYMENTS_DB_PATH`). A failed mint answers +`502 LICENSE_MINT_PENDING` carrying `settlement_tx` and `settlement_tx_url`. The payer's next +request — with `X-AGENT-ADDRESS`, or with a fresh payment — finishes the mint **without settling +again**. Before minting, the licence is read from chain: a mint whose confirmation timed out but +landed is closed out rather than minted twice (the contract would refuse it with `AlreadyMinted` +anyway, and that refusal is also treated as fulfilled). + +**Concurrency.** One purchase per `(payer, skill_id, version)` at a time, so two payments signed in +parallel settle once. The lock is in-process; the API runs as a single worker. **The 402 body.** Requirements travel in the `PAYMENT-REQUIRED` header as base64 JSON, with an empty body. This shape was captured from the reference `@x402/express` server against the same @@ -411,9 +442,18 @@ unaffected, and `/health` reports `facilitator_reachable` separately from `rpc_r Verify runs before settle deliberately: settling first would move money for a request that is about to be refused. -**Errors:** `403 NOT_VERIFIED`, `400 INVALID_PAYMENT`, `402 PAYMENT_REJECTED` (carries the -facilitator's own reason), `503 FACILITATOR_UNAVAILABLE`, `404 ARTIFACT_NOT_FOUND`, -`500 ARTIFACT_HASH_MISMATCH`. +**Response headers on a sale:** `X-STERISH-LICENSE` (`held` | `minted`), `X-STERISH-LICENSE-TX` +(mint), `X-STERISH-SETTLEMENT-TX` (settlement), `X-PAYMENT-RESPONSE` (facilitator receipt). All are +listed in CORS `expose_headers`, so a browser client can read them. + +**Errors:** `403 NOT_VERIFIED`, `404 ARTIFACT_NOT_FOUND`, `500 ARTIFACT_HASH_MISMATCH`, +`400 INVALID_AGENT`, `400 INVALID_PAYMENT`, `402 PAYMENT_REJECTED` (carries the facilitator's own +reason), `503 FACILITATOR_UNAVAILABLE`, `502 FACILITATOR_BAD_RESPONSE`, `502 LICENSE_READ_FAILED`, +`502 LICENSE_MINT_PENDING`. + +**Known limit.** If the version is re-audited away from `SAFE` between settlement and mint, the mint +is refused (`NotSafeVerdict`) and the version now answers `403`. The settlement stays recorded as +owed; that buyer is owed a refund, which is an operator action (`deploy/README.md`). ### 3.8 `GET /license/{skill_id}/{version}` — licence status without the artifact (STE-35) @@ -533,7 +573,17 @@ All error responses share one shape: | 404 | `NOT_FOUND` | `content_hash` not in the hash index | `lookup_by_hash` → `None` | | 404 | `SKILL_NOT_FOUND` | unknown `skill_id` | `SkillNotFound` (3) | | 404 | `VERSION_NOT_FOUND` | known skill, unknown version | `VersionNotFound` (4) | +| 400 | `INVALID_AGENT` | `X-AGENT-ADDRESS` / `?agent=` is not a `G…` account | — | +| 400 | `INVALID_PAYMENT` | `X-PAYMENT` is not base64 JSON | — | +| 402 | `PAYMENT_REJECTED` | the facilitator refused to verify or settle the payment | — | +| 403 | `NOT_VERIFIED` | `/use` on a version that is not `SAFE` | — | +| 404 | `ARTIFACT_NOT_FOUND` | `/use` on a version with no published artifact — not for sale | — | +| 500 | `ARTIFACT_HASH_MISMATCH` | artifact bytes do not hash to the on-chain `content_hash` | — | | 502 | `RPC_UNAVAILABLE` | Stellar RPC unreachable or returned an error | — | +| 502 | `FACILITATOR_BAD_RESPONSE` | verify named no valid payer, or settle succeeded without a tx | — | +| 502 | `LICENSE_READ_FAILED` | `has_license` returned a contract error | — | +| 502 | `LICENSE_MINT_PENDING` | paid and settled, mint failed; retry finishes it without charging | — | +| 503 | `FACILITATOR_UNAVAILABLE` | the x402 facilitator is unreachable | — | | 503 | `NOT_CONFIGURED` | `REGISTRY_CONTRACT_ID` unset | `NotInitialized` (1) | | 500 | `INTERNAL` | anything else | — | @@ -590,6 +640,10 @@ storage; only `evidence_hash` is on the ledger. `indexer.rebuild()`); the next poll refills from chain. Covered by `api/tests/test_cache_is_not_source_of_truth.py` and the live `test_rebuild_from_chain_is_consistent`. +- **The payments ledger is NOT a cache (STE-42).** `STERISH_PAYMENTS_DB_PATH` records x402 + settlements still owed a licence; it cannot be rebuilt from anything, because a settlement the + API never minted for leaves no licence on chain to find. It lives on its own volume + (`/payments`) and the index rebuild procedure above must never touch it. ## 7. Change process diff --git a/docs/deployments.md b/docs/deployments.md index e39571e..fd34ab5 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -348,6 +348,61 @@ gate. - **`/supported` reports `areFeesSponsored: true`**, which means the buying agent needs no XLM at all — it signs an auth entry and the facilitator assembles and pays for the transaction. +## On-chain evidence — nothing undeliverable is sold (STE-42) + +**The bug.** `/use` settled the USDC and minted the licence *before* it looked for the artifact. +Only `com.sterish.weather-lookup@1.0.0` had one, so every other SAFE version — including all +12 catalogue skills seeded in STE-18 — offered a 402, took 0.10 USDC, minted, and then answered +`404 ARTIFACT_NOT_FOUND`. The STE-19 proof passed only because it happened to buy that one skill. +A second hole in the same path: the payer was read from `X-AGENT-ADDRESS`, because the Stellar +exact payload carries no payer, so a client that omitted the header was settled and then told +`400 UNKNOWN_PAYER` with no licence. + +**Fixed and proven on testnet, 15 September 2026**, API running locally against the deployed +contracts and the live OZ Channels facilitator, driven by `api/scripts/e2e_paid_path.py` with the +real x402 client (`demo/x402-buyer/buy.js`). Every claim was checked against the ledger, not +against what the API answered. Full record: [`evidence/ste-42-e2e-paid-path-2026-09-15.json`](evidence/ste-42-e2e-paid-path-2026-09-15.json). + +| | | +|---|---| +| Artifacts published | 14 by `intake publish-artifacts` (12 catalogue + 2 safe fixtures), each written only after bytes, corpus index and on-chain `content_hash` agreed and the on-chain verdict was SAFE | +| Every SAFE row in the registry | **15 for sale (402), 33 not offered (404, no challenge), 0 anything else** | +| DANGEROUS `com.fixtures.poisoned.token-drainer@1.0.0` | 403, no challenge | +| Agent (fresh, no history) | `GAUJNTTBOZ4YONBUHLMKQOJGQNIHBN423ID26AKQ62BVK3HKKTJDMD4V` | +| Funding (create + trustline + 0.2 USDC, one tx) | [`18cf690533f75618…`](https://stellar.expert/explorer/testnet/tx/18cf690533f756183fe7fcfc8af9cec6a54734a8b23b154ffe936aca613d5777) | +| Bought `org.stellar.skills.agentic-payments.x402@2026.8.31` **with no `X-AGENT-ADDRESS`** | settlement [`73a5124de3b85434…`](https://stellar.expert/explorer/testnet/tx/73a5124de3b854341f3bbeacf45ff6304ee6b59fa8072d16c43c3a16d6320221) · mint [`858c136e206a3a03…`](https://stellar.expert/explorer/testnet/tx/858c136e206a3a037baa81dd68c54e3a6ab6b619adca392e0337f5ef6173fdb2) | + +Verified from outside the API: + +- the agent's USDC balance dropped by **exactly 0.1**, and `payTo` received at least 0.1 +- `has_license(agent, skill, version)` read **true** from the tokens contract +- `content_hash` of the served bytes = the on-chain `a1728e0400eb3bc9…` +- the same agent then **signed a second payment** for the licence it already held, again without + the header: served `held`, **no settlement**, balance unchanged + +The failure paths that cannot be forced on a live network — a mint that fails after settlement, a +mint whose confirmation times out but lands, concurrent payments from one payer, a facilitator +that verifies without naming a payer — are covered offline in `api/tests/test_use_x402.py`, each +asserting how many times settle ran. + +`deploy/artifacts/` is operator-supplied and gitignored (STE-25), so merging does not put these +14 artifacts on the server. **The redeploy for this ticket must run, on CT 204:** + +```bash +cd /opt/sterish/deploy +docker compose --env-file .env --profile tools run --rm publish-artifacts +``` + +**Production is still on the old code** until this merges and CT 204 is redeployed. `verify.sh` +now checks the property itself: every SAFE row must be 402-with-challenge or 404-without. Run +against `https://api-sterish.jameshub.fun` before the redeploy it reads **48 for sale, 0 not +offered** — the bug in one line, since only 15 of those 48 have bytes to hand over. After the +redeploy it must read 15 and 33. + +`verify.sh` sends its own User-Agent for that check. Cloudflare answers the default +`Python-urllib/3.x` agent with `403 error code: 1010`, an HTML page that is not an answer about +`/use` at all. + ## Backend deployment (STE-25) A Docker Compose stack in `deploy/`: the API (with the indexer running inside its process) plus diff --git a/docs/evidence/ste-42-e2e-paid-path-2026-09-15.json b/docs/evidence/ste-42-e2e-paid-path-2026-09-15.json new file mode 100644 index 0000000..c33ed09 --- /dev/null +++ b/docs/evidence/ste-42-e2e-paid-path-2026-09-15.json @@ -0,0 +1,67 @@ +{ + "api": "http://127.0.0.1:8765", + "started_at": 1789466771, + "skill": "org.stellar.skills.agentic-payments.x402", + "version": "2026.8.31", + "for_sale": [ + "com.sterish.weather-lookup@1.0.0", + "org.stellar.skills.agentic-payments.mpp@2026.8.31", + "org.stellar.skills.agentic-payments.x402@2026.8.31", + "org.stellar.skills.cross-chain.axelar@2026.8.31", + "org.stellar.skills.dapp.data-fetching@2026.8.31", + "org.stellar.skills.dapp.react@2026.8.31", + "org.stellar.skills.dapp.smart-accounts@2026.8.31", + "org.stellar.skills.data.horizon@2026.8.31", + "org.stellar.skills.smart-contracts.development@2026.8.31", + "org.stellar.skills.smart-contracts.security@2026.8.31", + "org.stellar.skills.smart-contracts.testing@2026.8.31", + "org.stellar.skills.standards.ecosystem@2026.8.31", + "org.stellar.skills.standards.resources@2026.8.31", + "com.fixtures.safe.premium-pdf-suite@3.1.0", + "com.fixtures.safe.weather-lookup@1.2.0" + ], + "not_offered": [ + "com.sterish.e2e-1788541421@1.0.0", + "com.sterish.e2e-1788541483@1.0.0", + "com.sterish.e2e-1788541618@1.0.0", + "com.sterish.it-safe-skill-1788541727@1.0.0", + "com.sterish.it-safe-skill-1788541759@1.0.0", + "com.sterish.it-safe-skill-1788541814@1.0.0", + "com.sterish.it-safe-skill-1788541857@1.0.0", + "com.sterish.it-safe-skill-1788541888@1.0.0", + "com.sterish.it-safe-skill-1788542003@1.0.0", + "com.sterish.it-safe-skill-1788542033@1.0.0", + "com.sterish.it-safe-skill-1788542088@1.0.0", + "com.sterish.it-safe-skill-1788542119@1.0.0", + "com.sterish.it-safe-skill-1788542150@1.0.0", + "com.sterish.it-safe-skill-1788542184@1.0.0", + "com.sterish.it-safe-skill-1788542239@1.0.0", + "com.sterish.it-safe-skill-1788542268@1.0.0", + "com.sterish.it-safe-skill-1788542297@1.0.0", + "com.sterish.it-safe-skill-1788685017@1.0.0", + "com.sterish.it-safe-skill-1788685048@1.0.0", + "com.sterish.it-safe-skill-1788685104@1.0.0", + "com.sterish.it-safe-skill-1788685139@1.0.0", + "com.sterish.it-safe-skill-1788685168@1.0.0", + "com.sterish.it-safe-skill-1788685359@1.0.0", + "com.sterish.it-safe-skill-1788685388@1.0.0", + "com.sterish.it-safe-skill-1788685444@1.0.0", + "com.sterish.it-safe-skill-1788685474@1.0.0", + "com.sterish.it-safe-skill-1788685488@1.0.0", + "com.sterish.it-safe-skill-1788685576@1.0.0", + "com.sterish.it-safe-skill-1788685608@1.0.0", + "com.sterish.it-safe-skill-1788685663@1.0.0", + "com.sterish.it-safe-skill-1788685693@1.0.0", + "com.sterish.it-safe-skill-1788685709@1.0.0", + "com.sterish.canon-safe-1788685783@1.0.0" + ], + "agent": "GAUJNTTBOZ4YONBUHLMKQOJGQNIHBN423ID26AKQ62BVK3HKKTJDMD4V", + "funding_tx": "18cf690533f756183fe7fcfc8af9cec6a54734a8b23b154ffe936aca613d5777", + "price_usdc": "0.1", + "pay_to": "GD73M4F7RN74KBLFGJP4WKBMCBJWBOA4SFNOP5HG4NBCDQUQCC2ARSZU", + "settle_tx": "73a5124de3b854341f3bbeacf45ff6304ee6b59fa8072d16c43c3a16d6320221", + "mint_tx": "858c136e206a3a037baa81dd68c54e3a6ab6b619adca392e0337f5ef6173fdb2", + "content_hash": "a1728e0400eb3bc979b66d8eef41d55c229662b5a74e25cecf8b9c7db1136e51", + "finished_at": 1789466856, + "result": "pass" +} From 169a60c127eadf5e94591066ffb6fec072be08f1 Mon Sep 17 00:00:00 2001 From: lin1er Date: Wed, 16 Sep 2026 15:43:47 +0700 Subject: [PATCH 6/7] fix(STE-42): publish-artifacts covers the demo set by default 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. --- pipeline/src/sterish_pipeline/intake/cli.py | 7 +++++-- pipeline/tests/test_publish_artifacts.py | 23 +++++++++++++++------ 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/pipeline/src/sterish_pipeline/intake/cli.py b/pipeline/src/sterish_pipeline/intake/cli.py index 6c75d93..af972f3 100644 --- a/pipeline/src/sterish_pipeline/intake/cli.py +++ b/pipeline/src/sterish_pipeline/intake/cli.py @@ -468,8 +468,11 @@ def seed( "--label", "labels", multiple=True, - default=("catalog", "safe"), - help="Corpus labels to consider. Repeatable. Default: catalog, safe.", + # `demo` since STE-18: the demo set includes SAFE versions that are for sale too. + # Anything not SAFE on chain is skipped whatever its label, so a wider default + # cannot put an unsold skill up for sale. + default=("catalog", "safe", "demo"), + help="Corpus labels to consider. Repeatable. Default: catalog, safe, demo.", ) @click.option("--json-out", type=click.Path(), default=None, help="Write the result as JSON") def publish_artifacts( diff --git a/pipeline/tests/test_publish_artifacts.py b/pipeline/tests/test_publish_artifacts.py index 80506d6..0f69988 100644 --- a/pipeline/tests/test_publish_artifacts.py +++ b/pipeline/tests/test_publish_artifacts.py @@ -239,22 +239,23 @@ def test_an_already_published_artifact_with_private_modes_is_repaired( assert (target / "SKILL.md").stat().st_mode & 0o777 == 0o644 -def test_the_real_corpus_publishes_every_catalog_and_safe_entry(tmp_path, monkeypatch): +def test_the_real_corpus_publishes_every_entry_the_default_labels_cover(tmp_path, monkeypatch): """Offline, against the repo's own corpus: with a chain that agrees with the index, - every catalog and safe entry is written and hashes back to its corpus hash. + every catalog, safe and demo entry is written and hashes back to its corpus hash. deploy/artifacts is gitignored (operator-supplied, STE-25), so this is what CI can - check instead: the corpus in git produces artifacts /use will accept. + check instead: the corpus in git produces artifacts /use will accept. Keyed on + (skill_id, version), since the demo set holds two versions of one skill. """ corpus = Corpus(Path(__file__).resolve().parents[1] / "corpus") - entries = [e for e in corpus.load() if e.label in ("catalog", "safe")] - by_id = {e.skill_id: e for e in entries} + entries = [e for e in corpus.load() if e.label in ("catalog", "safe", "demo")] + by_key = {(e.skill_id, e.version): e for e in entries} monkeypatch.setattr( onchain, "get_version", lambda cfg, reg, skill_id, version: { "verdict": ["Safe"], - "content_hash": bytes.fromhex(by_id[skill_id].content_hash), + "content_hash": bytes.fromhex(by_key[(skill_id, version)].content_hash), }, ) monkeypatch.setenv("REGISTRY_CA", REGISTRY) @@ -264,6 +265,16 @@ def test_the_real_corpus_publishes_every_catalog_and_safe_entry(tmp_path, monkey assert result.exit_code == 0, result.output assert len(entries) >= 10 + assert any(e.label == "demo" for e in entries) for entry in entries: target = out / entry.skill_id / entry.version assert content_hash(read_skill_files(target)) == entry.content_hash, entry.skill_id + + +def test_the_default_labels_include_the_demo_set(): + """STE-18 added SAFE demo versions (release-notes v1, changelog-writer v1). Left out of + the default, the compose publish step would skip them and /use would not sell them.""" + from sterish_pipeline.intake.cli import publish_artifacts + + labels = next(p for p in publish_artifacts.params if p.name == "labels") + assert set(labels.default) == {"catalog", "safe", "demo"} From 554d1e3c015c592b0746592d6300143ed3126107 Mon Sep 17 00:00:00 2001 From: lin1er Date: Wed, 16 Sep 2026 15:47:10 +0700 Subject: [PATCH 7/7] docs(STE-42): the paid-path e2e re-run against Registry v2 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). --- docs/deployments.md | 31 +++++++++++++---- .../ste-42-e2e-paid-path-v2-2026-09-16.json | 33 +++++++++++++++++++ 2 files changed, 57 insertions(+), 7 deletions(-) create mode 100644 docs/evidence/ste-42-e2e-paid-path-v2-2026-09-16.json diff --git a/docs/deployments.md b/docs/deployments.md index fd34ab5..1700391 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -385,19 +385,36 @@ mint whose confirmation times out but lands, concurrent payments from one payer, that verifies without naming a payer — are covered offline in `api/tests/test_use_x402.py`, each asserting how many times settle ran. -`deploy/artifacts/` is operator-supplied and gitignored (STE-25), so merging does not put these -14 artifacts on the server. **The redeploy for this ticket must run, on CT 204:** +### Re-verified against Registry v2 (16 September 2026) + +STE-44 moved the Registry and Tokens to new addresses, and STE-18 added demo skills. After rebasing +onto that `main`, the same e2e was run again with the API pointed at **Registry v2** +`CCZJN366…` and **Tokens v2** `CB6VK4EX…`. Record: +[`evidence/ste-42-e2e-paid-path-v2-2026-09-16.json`](evidence/ste-42-e2e-paid-path-v2-2026-09-16.json). + +| | | +|---|---| +| Artifacts published against v2 | 16 skill versions: 12 catalogue (`cctp` is DANGEROUS on chain), 2 safe fixtures, and the SAFE demo versions `release-notes` 1.0.0 and `changelog-writer` 1.0.0. 6 refused as not SAFE on chain | +| SAFE rows in `/skills` | **15 for sale, 0 not offered**, nothing else | +| Agent (no `X-AGENT-ADDRESS`) | `GCF76SG6QUBTJHK6AEFPS22TOB6JO5TKXXR5FW3QSDFOFLNXNLCJTXSC` | +| Settlement · mint | [`ea78a0348640629a…`](https://stellar.expert/explorer/testnet/tx/ea78a0348640629ae8e96a4de8afdf6fab57b8f4414e240064995ab07b43bea4) · [`f73dfdfc46b35d62…`](https://stellar.expert/explorer/testnet/tx/f73dfdfc46b35d6235294736b51004a946d740b2ead0b29d5a6fe244036bd126) | + +Same results as on v1: exactly 0.1 USDC paid, `has_license` true on Tokens v2, served bytes hash to +the on-chain `content_hash`, and a second signed payment for the held licence settles nothing. + +`publish-artifacts` now includes the `demo` label by default, because the demo set contains SAFE +versions that are for sale too. + +`deploy/artifacts/` is operator-supplied and gitignored (STE-25), so merging does not put artifacts +on the server. **The redeploy for this ticket must run, on CT 204:** ```bash cd /opt/sterish/deploy docker compose --env-file .env --profile tools run --rm publish-artifacts ``` -**Production is still on the old code** until this merges and CT 204 is redeployed. `verify.sh` -now checks the property itself: every SAFE row must be 402-with-challenge or 404-without. Run -against `https://api-sterish.jameshub.fun` before the redeploy it reads **48 for sale, 0 not -offered** — the bug in one line, since only 15 of those 48 have bytes to hand over. After the -redeploy it must read 15 and 33. +(On 16 September the v2-verified artifacts were already copied to CT 204 as a mitigation, STE-45; +the command above is idempotent and leaves matching artifacts untouched.) `verify.sh` sends its own User-Agent for that check. Cloudflare answers the default `Python-urllib/3.x` agent with `403 error code: 1010`, an HTML page that is not an answer about diff --git a/docs/evidence/ste-42-e2e-paid-path-v2-2026-09-16.json b/docs/evidence/ste-42-e2e-paid-path-v2-2026-09-16.json new file mode 100644 index 0000000..d71af01 --- /dev/null +++ b/docs/evidence/ste-42-e2e-paid-path-v2-2026-09-16.json @@ -0,0 +1,33 @@ +{ + "api": "http://127.0.0.1:8765", + "started_at": 1789548280, + "skill": "org.stellar.skills.agentic-payments.x402", + "version": "2026.8.31", + "for_sale": [ + "org.stellar.skills.agentic-payments.mpp@2026.8.31", + "org.stellar.skills.agentic-payments.x402@2026.8.31", + "org.stellar.skills.cross-chain.axelar@2026.8.31", + "org.stellar.skills.dapp.data-fetching@2026.8.31", + "org.stellar.skills.dapp.react@2026.8.31", + "org.stellar.skills.dapp.smart-accounts@2026.8.31", + "org.stellar.skills.data.horizon@2026.8.31", + "org.stellar.skills.smart-contracts.development@2026.8.31", + "org.stellar.skills.smart-contracts.security@2026.8.31", + "org.stellar.skills.smart-contracts.testing@2026.8.31", + "org.stellar.skills.standards.ecosystem@2026.8.31", + "org.stellar.skills.standards.resources@2026.8.31", + "com.fixtures.safe.premium-pdf-suite@3.1.0", + "com.fixtures.safe.weather-lookup@1.2.0", + "com.fixtures.demo.changelog-writer@1.0.0" + ], + "not_offered": [], + "agent": "GCF76SG6QUBTJHK6AEFPS22TOB6JO5TKXXR5FW3QSDFOFLNXNLCJTXSC", + "funding_tx": "f9f6c8f9f4ef79797e8f942523f6b42a68c91ff54388550bcbf7bae6fa7824c9", + "price_usdc": "0.1", + "pay_to": "GD73M4F7RN74KBLFGJP4WKBMCBJWBOA4SFNOP5HG4NBCDQUQCC2ARSZU", + "settle_tx": "ea78a0348640629ae8e96a4de8afdf6fab57b8f4414e240064995ab07b43bea4", + "mint_tx": "f73dfdfc46b35d6235294736b51004a946d740b2ead0b29d5a6fe244036bd126", + "content_hash": "a1728e0400eb3bc979b66d8eef41d55c229662b5a74e25cecf8b9c7db1136e51", + "finished_at": 1789548342, + "result": "pass" +}