Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -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
268 changes: 268 additions & 0 deletions api/scripts/e2e_paid_path.py
Original file line number Diff line number Diff line change
@@ -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<redacted>", 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)
5 changes: 5 additions & 0 deletions api/src/sterish_api/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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),
Expand Down
5 changes: 4 additions & 1 deletion api/src/sterish_api/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand Down
Loading
Loading