Skip to content

STE-55: prove a licence with the wallet, and list licences from the API - #62

Merged
AncungAulia merged 1 commit into
mainfrom
feat/ste-55-ownership-proof-and-licenses
Sep 24, 2026
Merged

AncungAulia merged 1 commit into
mainfrom
feat/ste-55-ownership-proof-and-licenses

Conversation

@AncungAulia

Copy link
Copy Markdown
Collaborator

Closes STE-55. Follows STE-48 (#50) and STE-46 (#55) on the API side.

Why

STE-48 has been live since 17 September: GET /use no longer serves a licence to whoever names its holder, since holders are public on chain. The dashboard never signed anything, so "Get the skill" and "Request again" have been failing in production. Confirmed against api.sterish.xyz with a wallet that does hold a licence:

401 {"error":"OWNERSHIP_PROOF_REQUIRED", "challenge_url": "https://api.sterish.xyz/use/.../challenge?agent=G…"}

What is in here

The proof, as api-spec §3.7 locks it. lib/ownership.ts: fetch the exact challenge_url the 401 carried, have the wallet sign the message verbatim (SEP-43 signMessage, which is SEP-53), repeat the request with X-STERISH-PROOF-NONCE and X-STERISH-PROOF-SIGNATURE. requestSkillProving wraps all three, so a 401 is part of the flow rather than something to show, and the version card and the licences page both go through it.

The signature step is named, and called what it is. "Sign the message in your wallet to prove this licence is yours", with "a signature, not a payment: nothing is charged and no transaction is sent", and a Cancel. New wording for OWNERSHIP_PROOF_REQUIRED, INVALID_OWNERSHIP_PROOF (a challenge is single use, so it says to sign a fresh one), LICENSE_READ_FAILED and FACILITATOR_BAD_RESPONSE.

The licences page reads GET /licenses. STE-47 walked the tokens contract id by id because no list endpoint existed. The API now builds the list from the contract's own enumeration, so a licence older than the RPC event window is still listed, and mint_tx may be null without the row disappearing (the page says so). lib/tokens.ts is deleted; isAccountAddress moves to utils/stellar.ts.

The mock keeps up: it issues challenges, consumes a nonce, and refuses a replay, another agent's nonce or an unknown one, so the whole client dance runs offline.

Default API URL is now https://api.sterish.xyz (STE-54). The old hostname still works as an alias; the Vercel env should move too.

Decisions worth flagging

Nothing changes about paying. Spec §3.7 is explicit that a signed x402 payment needs no separate proof, so the 402 path is untouched: a wallet holding nothing is still quoted a price rather than asked to prove anything. There is a Playwright step for exactly that.

The client never builds the challenge URL. It uses the one the API sent, so the host and shape stay the API's business. Verified live that Access-Control-Allow-Origin: * is present on both the challenge and the 401, so the browser can read them cross-origin.

A challenge is fetched immediately before the request it is for, never cached: a nonce is single use and lives about five minutes.

Verification

  • 165 unit tests, including: the challenge fetched from the URL the 401 gave, proof headers sent, a challenge for another address or another scheme refused, a 402 passed through untouched, a non-proof error not retried, and the mock's nonce rules (replay, another agent's nonce, still quoting a non-holder).
  • 11 Playwright steps on a production build over the mock: the list from the API, the proof step named and cancellable, the failure explained, the version card on the same path, and a non-holder still quoted.
  • Four runs against the live API with a real key standing in for the wallet: a held skill fetched by proving ownership, an impostor signature refused with INVALID_OWNERSHIP_PROOF, a bare request answered 401 with a challenge_url, and GET /licenses listing this wallet's axelar licence. That script is not committed: it needs a key and the network, so it would fail CI.

Found while testing

A declined signature rendered "[object Object]" on the licences page: the wallet kit rejects with a plain object, not an Error. Wallet errors now go through walletErrorMessage, as the payment path already did, with a test for it.

🤖 Generated with Claude Code

… the API

STE-48 went live on 17 September: the free paths of GET /use answer 401 with
a challenge_url instead of serving a licence to anyone who names its holder.
The dashboard did not sign anything, so "Get the skill" and "Request again"
had been failing in production.

- lib/ownership.ts does the three steps of api-spec 3.7: fetch the exact
  challenge_url the 401 carried, have the wallet sign the message verbatim
  (SEP-43 signMessage, which is SEP-53), repeat the request with the nonce and
  signature. requestSkillProving wraps it, so a 401 is part of the flow rather
  than an error, and both the version card and the licences page use it.
- The signature step is named on screen and called what it is: a signature, not
  a payment, with nothing charged and no transaction sent. It can be cancelled.
- New wording for OWNERSHIP_PROOF_REQUIRED, INVALID_OWNERSHIP_PROOF (says to
  sign a fresh challenge), LICENSE_READ_FAILED and FACILITATOR_BAD_RESPONSE.
- The licences page reads GET /licenses (STE-46) instead of walking the tokens
  contract id by id, and links the mint transaction the API supplies, saying so
  when it is older than the indexer's window. lib/tokens.ts is deleted;
  isAccountAddress moves to utils/stellar.ts.
- The mock serves the challenge, consumes a nonce, and refuses a replay or
  another agent's nonce, so the whole client dance is exercised offline.
- Default and example API URL move to https://api.sterish.xyz (STE-54).

Found while testing: a declined signature rendered "[object Object]" on the
licences page, because the kit rejects with a plain object rather than an
Error. Wallet errors go through walletErrorMessage now, as the payment path
already did.

Verified: 165 unit tests; 11 Playwright steps on a mock build (list from the
API, the challenge fetched from the URL the 401 gave, the proof step named and
cancellable, a non-holder still quoted rather than asked to prove); and four
runs against the live API with a real key, standing in for the wallet: a held
skill fetched by proving, an impostor signature refused with
INVALID_OWNERSHIP_PROOF, a bare request answered 401 with a challenge_url, and
GET /licenses listing this wallet's axelar licence.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@vercel

vercel Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
sterish Ready Ready Preview Sep 24, 2026 11:38am UTC

@AncungAulia
AncungAulia merged commit 65c5cb8 into main Sep 24, 2026
3 checks passed

This branch was successfully deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant