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
94 changes: 90 additions & 4 deletions api/scripts/e2e_paid_path.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@
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.
4b. STE-48: the holder's address alone, a proof signed by another key, a replayed proof,
a stranger's proof presented for the holder, and a proof for another version are all
401 with no artifact and no payment challenge (and, with --expiry-wait, an expired one).
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.

Expand Down Expand Up @@ -117,6 +120,30 @@ def field(name: str) -> str | None:
}


def sep53_sign(keypair: Keypair, message: str) -> str:
"""SEP-53, as a wallet's signMessage and `stellar message sign` produce it."""
import base64
import hashlib

digest = hashlib.sha256(b"Stellar Signed Message:\n" + message.encode("utf-8")).digest()
return base64.b64encode(keypair.sign(digest)).decode()


def proof_headers(
http: httpx.Client, api: str, skill: str, version: str, agent: str, signer: Keypair
) -> tuple[dict, dict]:
challenge = http.get(f"{api}/use/{skill}/{version}/challenge", params={"agent": agent})
if challenge.status_code != 200:
raise E2EFailure(f"challenge endpoint answered {challenge.status_code}: {challenge.text}")
body = challenge.json()
headers = {
"X-AGENT-ADDRESS": agent,
"X-STERISH-PROOF-NONCE": body["nonce"],
"X-STERISH-PROOF-SIGNATURE": sep53_sign(signer, body["message"]),
}
return headers, body


def content_hash_of_served(body: bytes) -> str:
sys.path.insert(0, str(REPO / "pipeline" / "src"))
from sterish_pipeline.content_hash import content_hash
Expand All @@ -133,6 +160,11 @@ def main() -> int:
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)
parser.add_argument(
"--expiry-wait", action="store_true",
help="also wait out one challenge and prove an expired proof is refused "
"(takes STERISH_PROOF_TTL_SECONDS of the target API)",
)
args = parser.parse_args()

api = args.api.rstrip("/")
Expand Down Expand Up @@ -224,12 +256,12 @@ def main() -> int:

# --- 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}
)
use_url = f"{api}/use/{args.skill}/{args.version}"
proven, _ = proof_headers(http, api, args.skill, args.version, agent.public_key, agent)
served = http.get(use_url, headers=proven)
check(
served.status_code == 200 and served.headers["X-STERISH-LICENSE"] == "held",
"licence holder served without payment",
"licence holder served without payment, with a SEP-53 ownership proof",
)
onchain = http.get(f"{api}/check/{args.skill}/{args.version}").json()["content_hash"]
check(
Expand All @@ -238,6 +270,60 @@ def main() -> int:
)
evidence["content_hash"] = onchain

# --- 4b. the licence cannot be borrowed (STE-48) ------------------------------------
print("\n4b. naming the holder is not enough: every forged or reused proof is refused")
stranger = Keypair.random()
evidence["stranger"] = stranger.public_key

def refused(response: httpx.Response, code: str, what: str) -> None:
body = response.json() if response.headers.get("content-type", "").startswith(
"application/json"
) else {}
check(
response.status_code == 401
and body.get("error") == code
and "PAYMENT-REQUIRED" not in response.headers
and "X-STERISH-LICENSE" not in response.headers,
f"{what} -> 401 {code}, no artifact, no payment challenge",
)

refused(
http.get(use_url, headers={"X-AGENT-ADDRESS": agent.public_key}),
"OWNERSHIP_PROOF_REQUIRED", "holder's address only",
)
refused(
http.get(use_url, params={"agent": agent.public_key}),
"OWNERSHIP_PROOF_REQUIRED", "holder's address as ?agent=",
)
forged, _ = proof_headers(http, api, args.skill, args.version, agent.public_key, stranger)
refused(http.get(use_url, headers=forged), "INVALID_OWNERSHIP_PROOF",
"holder's challenge signed by another key")
refused(http.get(use_url, headers=proven), "INVALID_OWNERSHIP_PROOF",
"the proof that was already used, replayed")
own, _ = proof_headers(http, api, args.skill, args.version, stranger.public_key, stranger)
refused(http.get(use_url, headers=dict(own, **{"X-AGENT-ADDRESS": agent.public_key})),
"INVALID_OWNERSHIP_PROOF", "a stranger's valid proof presented for the holder")
other_version, _ = proof_headers(
http, api, args.skill, args.version + ".other", agent.public_key, agent
)
refused(http.get(use_url, headers=other_version), "INVALID_OWNERSHIP_PROOF",
"a proof for another version")
stranger_paying = http.get(use_url, headers=own)
check(stranger_paying.status_code == 402 and "PAYMENT-REQUIRED" in stranger_paying.headers,
"a stranger proving its OWN address, with no licence, is asked to pay (402)")

if args.expiry_wait:
pending, challenge = proof_headers(
http, api, args.skill, args.version, agent.public_key, agent
)
wait = max(0, challenge["expires_at"] - int(time.time())) + 3
print(f" waiting {wait}s for the challenge to expire")
time.sleep(wait)
refused(http.get(use_url, headers=pending), "INVALID_OWNERSHIP_PROOF",
"a correctly signed proof after its challenge expired")
evidence["ownership_proof"] = "held with proof 200; address-only, forged, replayed, " \
"borrowed, wrong-version" + (", expired" if args.expiry_wait else "") + " all 401"

# --- 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(
Expand Down
5 changes: 5 additions & 0 deletions api/src/sterish_api/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,10 @@ class Settings:
# (STE-33). Not a thread pool size for the app — FastAPI already has one; this
# bounds the fan-out *inside* one handler. See fanout.py.
chain_concurrency: int
# Lifetime of a licence ownership challenge (STE-48), seconds. Long enough for a
# human to approve a wallet prompt, short enough that a captured signature is
# worthless soon after. Clamped to [30, 900].
proof_ttl_seconds: int

@property
def network(self) -> str:
Expand Down Expand Up @@ -127,6 +131,7 @@ def load_settings() -> Settings:
indexer_poll_seconds=_env_int("INDEXER_POLL_SECONDS", 8),
indexer_chunk_ledgers=_env_int("INDEXER_CHUNK_LEDGERS", 4000),
report_base_url=os.getenv("REPORT_BASE_URL", "").rstrip("/"),
proof_ttl_seconds=min(900, max(30, _env_int("STERISH_PROOF_TTL_SECONDS", 300))),
)


Expand Down
3 changes: 2 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, payments, x402
from . import chain, indexer, payments, proofs, x402
from .chain import ChainError, ContractError, NotConfiguredError
from .config import settings
from .errors import (
Expand Down Expand Up @@ -55,6 +55,7 @@ async def lifespan(app: FastAPI):
indexer.init_db()
# The payments ledger is not a cache (STE-42): created here, never rebuilt.
payments.init_db()
proofs.init_db()

task = None
if settings.indexer_enabled:
Expand Down
218 changes: 218 additions & 0 deletions api/src/sterish_api/proofs.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
"""Proof that the caller controls the address it claims (STE-48).

`GET /use` serves an already-licensed artifact for free. Before STE-48 "already
licensed" was decided by `X-AGENT-ADDRESS` alone, and licence holders are public on
chain, so anyone could name a holder's address and receive what that holder paid
for. A soulbound licence that anyone can borrow is not soulbound.

The free path now needs a signature from the address's own key over a short-lived,
single-use challenge the API issued:

1. `GET /use/{skill_id}/{version}/challenge?agent=G...` issues a nonce and returns the
exact message to sign.
2. The caller signs it with **SEP-53** — ed25519 over
`SHA-256("Stellar Signed Message:\\n" + message)` — which is what a wallet's SEP-43
`signMessage` produces and what `stellar message sign` produces.
3. The caller repeats `GET /use/...` with `X-AGENT-ADDRESS`, `X-STERISH-PROOF-NONCE` and
`X-STERISH-PROOF-SIGNATURE` (base64).

The message is rebuilt here from the stored row, never taken from the request, so a
client cannot get a different text accepted. A nonce is bound to one agent, one skill
and one version, expires, and is consumed by the first request that proves with it.
A failed signature does not consume it: otherwise anyone who guessed a nonce could
burn another caller's challenge, and a nonce is 128 random bits, so guessing is not a
path to anything else.

Stored in the payments database file (its own table): the rows must survive a
restart, or a nonce used just before one could be replayed just after.
"""

from __future__ import annotations

import base64
import binascii
import hashlib
import secrets
import sqlite3
import threading
import time
from dataclasses import dataclass
from typing import Any

from stellar_sdk import Keypair
from stellar_sdk.exceptions import BadSignatureError

from .config import settings

SEP53_PREFIX = b"Stellar Signed Message:\n"
MESSAGE_TITLE = "Sterish licence ownership proof"

NONCE_HEADER = "X-STERISH-PROOF-NONCE"
SIGNATURE_HEADER = "X-STERISH-PROOF-SIGNATURE"

_SCHEMA = """
CREATE TABLE IF NOT EXISTS proof_challenges (
nonce TEXT PRIMARY KEY,
agent TEXT NOT NULL,
skill_id TEXT NOT NULL,
version TEXT NOT NULL,
issued_at INTEGER NOT NULL,
expires_at INTEGER NOT NULL,
used_at INTEGER
);
CREATE INDEX IF NOT EXISTS idx_proof_expiry ON proof_challenges (expires_at);
"""

# Rows past expiry are kept this long before being purged, so a replay of a recently
# used nonce is still reported as "already used" rather than "unknown".
_PURGE_GRACE_SECONDS = 3600

_lock = threading.Lock()


class ProofInvalid(Exception):
"""The proof was supplied and is wrong. `reason` is safe to return to the caller."""

def __init__(self, reason: str):
super().__init__(reason)
self.reason = reason


@dataclass(frozen=True)
class Challenge:
agent: str
skill_id: str
version: str
nonce: str
issued_at: int
expires_at: int

@property
def message(self) -> str:
return build_message(
self.agent, self.skill_id, self.version, self.nonce, self.expires_at
)


def build_message(agent: str, skill_id: str, version: str, nonce: str, expires_at: int) -> str:
"""The exact text a caller signs. Frozen: changing it invalidates every client.

The network passphrase is in the text so a proof made for testnet can never be
mistaken for one made against a mainnet deployment of the same API.
"""
return "\n".join(
[
MESSAGE_TITLE,
f"agent: {agent}",
f"skill: {skill_id}",
f"version: {version}",
f"nonce: {nonce}",
f"expires: {expires_at}",
f"network: {settings.network_passphrase}",
]
)


def sep53_digest(message: str) -> bytes:
return hashlib.sha256(SEP53_PREFIX + message.encode("utf-8")).digest()


def _connect() -> sqlite3.Connection:
conn = sqlite3.connect(settings.payments_db_path, check_same_thread=False)
conn.row_factory = sqlite3.Row
conn.executescript(_SCHEMA)
return conn


def init_db() -> None:
with _lock, _connect():
pass


def issue(agent: str, skill_id: str, version: str, *, now: int | None = None) -> Challenge:
now = int(time.time()) if now is None else now
challenge = Challenge(
agent=agent,
skill_id=skill_id,
version=version,
nonce=secrets.token_hex(16),
issued_at=now,
expires_at=now + settings.proof_ttl_seconds,
)
with _lock, _connect() as conn:
conn.execute(
"DELETE FROM proof_challenges WHERE expires_at < ?", (now - _PURGE_GRACE_SECONDS,)
)
conn.execute(
"INSERT INTO proof_challenges "
"(nonce, agent, skill_id, version, issued_at, expires_at) VALUES (?, ?, ?, ?, ?, ?)",
(
challenge.nonce, agent, skill_id, version,
challenge.issued_at, challenge.expires_at,
),
)
return challenge


def _get(nonce: str) -> dict[str, Any] | None:
with _lock, _connect() as conn:
row = conn.execute("SELECT * FROM proof_challenges WHERE nonce = ?", (nonce,)).fetchone()
return dict(row) if row else None


def _decode_signature(raw: str) -> bytes:
value = raw.strip()
try:
# Accept both base64 alphabets; wallets differ. Padding is restored first.
padded = value + "=" * (-len(value) % 4)
decoded = base64.b64decode(padded.replace("-", "+").replace("_", "/"), validate=True)
except (binascii.Error, ValueError) as exc:
raise ProofInvalid("signature is not base64") from exc
if len(decoded) != 64:
raise ProofInvalid(f"signature must be 64 bytes (ed25519), got {len(decoded)}")
return decoded


def verify_and_consume(
agent: str,
skill_id: str,
version: str,
nonce: str,
signature: str,
*,
now: int | None = None,
) -> None:
"""Accept the proof exactly once, or raise ProofInvalid naming why."""
now = int(time.time()) if now is None else now
nonce = nonce.strip()
row = _get(nonce)
if row is None:
raise ProofInvalid("unknown nonce; request a new challenge")
if row["agent"] != agent:
raise ProofInvalid("this challenge was issued for a different agent")
if row["skill_id"] != skill_id or row["version"] != version:
raise ProofInvalid("this challenge was issued for a different skill or version")
if row["used_at"] is not None:
raise ProofInvalid("this challenge has already been used; request a new one")
if now > row["expires_at"]:
raise ProofInvalid("this challenge has expired; request a new one")

sig = _decode_signature(signature)
message = build_message(agent, skill_id, version, nonce, row["expires_at"])
try:
Keypair.from_public_key(agent).verify(sep53_digest(message), sig)
except BadSignatureError as exc:
raise ProofInvalid(
"signature does not verify against the agent's key "
"(expected SEP-53 over the challenge message)"
) from exc

# Conditional update: of two requests racing with the same valid proof, one wins.
with _lock, _connect() as conn:
consumed = conn.execute(
"UPDATE proof_challenges SET used_at = ? "
"WHERE nonce = ? AND used_at IS NULL AND expires_at >= ?",
(now, nonce, now),
).rowcount
if consumed != 1:
raise ProofInvalid("this challenge has already been used; request a new one")
Loading
Loading