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
20 changes: 20 additions & 0 deletions deploy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,26 @@ uv run sterish intake publish-artifacts --corpus corpus --out ../deploy/artifact
Then check the result from outside: `verify.sh` fails if any SAFE row is priced
without being deliverable.

## Where production runs (STE-54)

Since 17 September 2026 production runs on a VPS (`187.53.142.100`, Ubuntu, 2 vCPU / 8 GB, IPv4 +
IPv6), not on the homelab LXC it started on (Proxmox pve02, CT 204). The homelab went down when
that node was rebuilt, depends on home power and internet, and had no IPv6 route, so RPC calls
retried from IPv6 to IPv4.

- Redeploy: `sterish-redeploy` on the VPS (`git reset --hard origin/main`, then
`docker compose --env-file .env --profile tunnel up -d --build`).
- Caddy listens on loopback only (`HTTP_PORT=127.0.0.1:8080`); every public request arrives through
the Cloudflare Tunnel, so the VPS exposes no HTTP port.
- Host-local and untracked (they survive the reset): `docker-compose.override.yml` and
`cloudflared-config.local.yml`, which carries the ingress until this repo's
`cloudflared-config.yml` is on `main`.
- **`deploy_payments` is the payments ledger, not a cache.** Moving hosts means stopping the API on
the old host first, copying the SQLite file, and checking the hash on both sides — two live copies
would both accept payments. `deploy_index` is a cache and is simply rebuilt.
- The old CT 204 stack is stopped and kept for rollback; its redeploy scripts are renamed
`*.DISABLED-moved-to-vps` so nobody brings a second connector up by accident.

## Publishing on a public hostname

Two paths are wired, and they can run together:
Expand Down
6 changes: 6 additions & 0 deletions deploy/cloudflared-config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ ingress:
# issues certificates for `jameshub.fun` and `*.jameshub.fun` only — a single
# level. A two-level name like `api.sterish.jameshub.fun` would need
# `*.sterish.jameshub.fun`, which Universal SSL does not cover.
# Canonical hostname since STE-54. Needs a proxied CNAME to
# 0cce8c0e-6239-4454-9ec6-a2a4515e4c9d.cfargotunnel.com in the sterish.xyz zone.
- hostname: api.sterish.xyz
service: http://caddy:80

# Original hostname, kept so nothing that already points at it breaks.
- hostname: api-sterish.jameshub.fun
# `caddy` is the compose service name, NOT localhost: cloudflared runs in its
# own container, so localhost there is itself.
Expand Down
40 changes: 40 additions & 0 deletions docs/deployments.md
Original file line number Diff line number Diff line change
Expand Up @@ -914,6 +914,46 @@ dropped and rebuilt (a cache; STE-46 backfills `mint_tx` from it), Caddy restart
**Expected side effect, announced on STE-48:** the dashboard's `200 held` path answers `401
OWNERSHIP_PROOF_REQUIRED` until its SEP-43 signing UI lands. New purchases are unaffected.

### Migration 2026-09-17 — production moves to a VPS, `api.sterish.xyz` (STE-54)

From the homelab LXC (Proxmox pve02, CT 204) to a VPS, `187.53.142.100` (Ubuntu 26.04, 2 vCPU / 8 GB /
96 GB, IPv4 + IPv6). Same Cloudflare Tunnel (`sterish-api`, `0cce8c0e…`), now with the VPS as its only
connector. Record: [`evidence/ste-54-vps-migration-2026-09-17.json`](evidence/ste-54-vps-migration-2026-09-17.json).

**Order, so there is never a moment with two ledgers taking payments:**

1. VPS prepared with the tunnel **off**: repo cloned, `.env` and the tunnel credentials copied
host-to-host (never printed), Caddy bound to loopback, stack built, `publish-artifacts`
(18 for sale, 4 not SAFE), health checked locally.
2. **13:49:02 UTC** — API stopped on CT 204, freezing the payments ledger.
3. Ledger copied: `sha256` `058a002e…` identical on the old host, in transit and on the VPS; 8 settlements,
0 owed a licence.
4. VPS API and its tunnel connector started; CT 204's Caddy and connector stopped. **13:49:16 UTC** —
`cloudflared tunnel info` lists one connector, origin `187.53.142.100`.
5. CT 204's redeploy scripts renamed `*.DISABLED-moved-to-vps`; its stack is kept for rollback.

**Verified through `https://api-sterish.jameshub.fun`, now served by the VPS:**

| | |
|---|---|
| `deploy/verify.sh` | all pass; 17 SAFE rows for sale, 0 undeliverable priced, `sha256(report) == evidence_hash` |
| real purchase, `e2e_paid_path.py` | fresh agent `GC6VEHOE…` bought `standards.ecosystem`: exactly 0.1 USDC (settle [`54d18460…`](https://stellar.expert/explorer/testnet/tx/54d18460153bc4bcc6c51229898c138a4591be9f5b8a681fbcde4346f8d4b170), mint [`2eb739ee…`](https://stellar.expert/explorer/testnet/tx/2eb739eeaeddbb7b344fd2bb539ff7681a069447f6318fe2f1641cdb961e047c)); holder served with a SEP-53 proof; address-only, forged, replayed, borrowed and wrong-version proofs all `401`; a second payment settled nothing |
| ledger continuity | 9 rows after the purchase: the 8 migrated plus the new one |
| API log | real visitor addresses, 0 5xx, **0 warnings** — the IPv6→IPv4 RPC retries seen on CT 204 are gone |

**`api.sterish.xyz` — live the same evening.** The Cloudflare origin certificate available (`cert.pem`)
turned out to be scoped to the `jameshub.fun` zone: `cloudflared tunnel route dns` with it created a
stray `api.sterish.xyz.jameshub.fun` record instead. That record was deleted in the dashboard, and a
proxied CNAME `api` → `0cce8c0e-6239-4454-9ec6-a2a4515e4c9d.cfargotunnel.com` was added in the
`sterish.xyz` zone (the stray name now returns NXDOMAIN). `REPORT_BASE_URL` then moved to
`https://api.sterish.xyz`; for a few minutes earlier it had been set there before the record existed
and was reverted, so `report_uri` briefly pointed at an unresolvable name.

Verified through `https://api.sterish.xyz`: `deploy/verify.sh` all pass; `report_uri`, the x402
`resource.url` and the STE-48 `challenge_url` all use `https://api.sterish.xyz`; the old hostname
still answers; and the D3 flow transcript was regenerated through the new hostname, **15/15**
([`evidence/d3-flow-transcript-2026-09-17.md`](evidence/d3-flow-transcript-2026-09-17.md)).

## Full-loop rehearsal against the v2 pair (STE-27, 2026-09-16)

The first run of the whole loop against Registry v2 + Tokens v2 + the unchanged Escrow — the
Expand Down
44 changes: 22 additions & 22 deletions docs/evidence/d3-flow-transcript-2026-09-17.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Sterish full flow, recorded from the live API

> Generated by `api/scripts/d3_flow_transcript.py` on **2026-09-17T12:10:00+00:00** against `https://api-sterish.jameshub.fun` (STE-52). Every request below was made for real; every ✅ is a check the script ran, and the script stops at the first ❌. Testnet only — links expire with the testnet reset on 16 December 2026.
> Generated by `api/scripts/d3_flow_transcript.py` on **2026-09-17T15:18:25+00:00** against `https://api.sterish.xyz` (STE-52). Every request below was made for real; every ✅ is a check the script ran, and the script stops at the first ❌. Testnet only — links expire with the testnet reset on 16 December 2026.

Skill followed: **`org.stellar.skills.cross-chain.cctp` 2026.8.31** · negative path: **`com.fixtures.poisoned.token-drainer@1.0.0`**

## 0. The deployment answers, and reads the registry it claims

```bash
curl -s 'https://api-sterish.jameshub.fun/health'
curl -s 'https://api.sterish.xyz/health'
```
```http
HTTP 200
Expand All @@ -30,7 +30,7 @@ HTTP 200
Registry: [`CCZJN366SV57JEBZVXGYY3ZBLJNFV4IR5ILCAI3EMX2WDNQPEPQ4BRL2`](https://stellar.expert/explorer/testnet/contract/CCZJN366SV57JEBZVXGYY3ZBLJNFV4IR5ILCAI3EMX2WDNQPEPQ4BRL2)

```bash
curl -s 'https://api-sterish.jameshub.fun/skills?limit=100'
curl -s 'https://api.sterish.xyz/skills?limit=100'
```
```http
HTTP 200
Expand All @@ -54,7 +54,7 @@ _Summarised from the 24 rows returned._
## 1. Register → audit: the verdict is on chain, and so is the hash of its report

```bash
curl -s 'https://api-sterish.jameshub.fun/check/org.stellar.skills.cross-chain.cctp/2026.8.31'
curl -s 'https://api.sterish.xyz/check/org.stellar.skills.cross-chain.cctp/2026.8.31'
```
```http
HTTP 200
Expand All @@ -80,7 +80,7 @@ HTTP 200
"audit_tx": "3490559a37fa8c2b54e5acbb48064a5172fce4a1e315f924fae0c1abf767df22",
"audit_tx_url": "https://stellar.expert/explorer/testnet/tx/3490559a37fa8c2b54e5acbb48064a5172fce4a1e315f924fae0c1abf767df22",
"evidence_hash": "6513a8c7d3b84b11b9530e73b5a3f5589d6b11cf01ce5348b8717301373379f7",
"report_uri": "https://api-sterish.jameshub.fun/reports/org.stellar.skills.cross-chain.cctp/2026.8.31"
"report_uri": "https://api.sterish.xyz/reports/org.stellar.skills.cross-chain.cctp/2026.8.31"
}
}
```
Expand All @@ -95,7 +95,7 @@ HTTP 200
| `mint_verified` (badge) | [`9ecc990a69df512c…`](https://stellar.expert/explorer/testnet/tx/9ecc990a69df512c272d0cd896952be2f2269416dd3dced2783666f019caec61) |

```bash
curl -s 'https://api-sterish.jameshub.fun/reports/org.stellar.skills.cross-chain.cctp/2026.8.31'
curl -s 'https://api.sterish.xyz/reports/org.stellar.skills.cross-chain.cctp/2026.8.31'
```
```http
HTTP 200
Expand Down Expand Up @@ -126,18 +126,18 @@ _Trimmed to the verdict fields; the hash below is over the full bytes._
## 2. License: 402 → pay USDC over x402 → licence minted

```bash
curl -s 'https://api-sterish.jameshub.fun/use/org.stellar.skills.cross-chain.cctp/2026.8.31'
curl -s 'https://api.sterish.xyz/use/org.stellar.skills.cross-chain.cctp/2026.8.31'
```
```http
HTTP 402
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9hcGktc3RlcmlzaC5qYW1lc2h1
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9hcGkuc3RlcmlzaC54eXovdXNl
```
```json
{
"x402Version": 2,
"error": "Payment required",
"resource": {
"url": "https://api-sterish.jameshub.fun/use/org.stellar.skills.cross-chain.cctp/2026.8.31",
"url": "https://api.sterish.xyz/use/org.stellar.skills.cross-chain.cctp/2026.8.31",
"description": "License for org.stellar.skills.cross-chain.cctp@2026.8.31",
"mimeType": "application/json"
},
Expand All @@ -161,27 +161,27 @@ _The `PAYMENT-REQUIRED` header, base64-decoded._
- ✅ 402 with an x402 `exact` challenge on `stellar:testnet`
- ✅ price **0.1 USDC** (SAC `CBIELTK6…`), paid to `GD73M4F7…`

A fresh agent `GAR4TZFASYN4PSFEL2UCE4LR7NIWEIF6FPWXQOP53GDFCPHUCFIBWOMJ` is created and funded with 0.5 USDC ([`85df8494999f5493…`](https://stellar.expert/explorer/testnet/tx/85df8494999f5493a0956817b1667682db158dcad193f388f70017fbf1d76499)). It holds no XLM beyond the account reserve: the facilitator sponsors fees.
A fresh agent `GAKHP5233JPQS5HHW6ODVLAWVOIEUWIJQX3XDACM2AWCNURAOUT5G4HM` is created and funded with 0.5 USDC ([`f7e5e92a6fd5ca0c…`](https://stellar.expert/explorer/testnet/tx/f7e5e92a6fd5ca0c0ef171b5a2bb67880e40fdccec5e92e6dbd29d499996c85b)). It holds no XLM beyond the account reserve: the facilitator sponsors fees.

The agent signs the payment with the reference x402 client (`@x402/fetch` + `@x402/stellar`, in `demo/x402-buyer/buy.js`) and retries **without naming itself**: the API takes the payer from the facilitator's verify.

```http
HTTP 200
X-STERISH-LICENSE: minted
X-STERISH-SETTLEMENT-TX: af081d9d80d0f5b552a778438c8734cec72dfd29dc78f37ed96536c954e8beba
X-STERISH-LICENSE-TX: f0f05066e1b13f00a7cda4f16eec22a74dd4b529cd27f14ac77b6bb591f51e0b
X-STERISH-SETTLEMENT-TX: 7cc53a35ddb943df9f99549b960aa62ea3e79d79f372266ad60c3fce2f685d40
X-STERISH-LICENSE-TX: 686deecc9d84bd6cd73fc38c817d9a5f2f656c861b62e46f449f3904ff941fbe
```

- ✅ paid request answered 200 with a minted licence
- ✅ agent USDC balance fell by exactly 0.1

| Step | Transaction |
|---|---|
| x402 settlement (USDC transfer) | [`af081d9d80d0f5b5…`](https://stellar.expert/explorer/testnet/tx/af081d9d80d0f5b552a778438c8734cec72dfd29dc78f37ed96536c954e8beba) |
| `mint_license` (soulbound) | [`f0f05066e1b13f00…`](https://stellar.expert/explorer/testnet/tx/f0f05066e1b13f00a7cda4f16eec22a74dd4b529cd27f14ac77b6bb591f51e0b) |
| x402 settlement (USDC transfer) | [`7cc53a35ddb943df…`](https://stellar.expert/explorer/testnet/tx/7cc53a35ddb943df9f99549b960aa62ea3e79d79f372266ad60c3fce2f685d40) |
| `mint_license` (soulbound) | [`686deecc9d84bd6c…`](https://stellar.expert/explorer/testnet/tx/686deecc9d84bd6cd73fc38c817d9a5f2f656c861b62e46f449f3904ff941fbe) |

```bash
curl -s 'https://api-sterish.jameshub.fun/license/org.stellar.skills.cross-chain.cctp/2026.8.31?agent=GAR4TZFASYN4PSFEL2UCE4LR7NIWEIF6FPWXQOP53GDFCPHUCFIBWOMJ'
curl -s 'https://api.sterish.xyz/license/org.stellar.skills.cross-chain.cctp/2026.8.31?agent=GAKHP5233JPQS5HHW6ODVLAWVOIEUWIJQX3XDACM2AWCNURAOUT5G4HM'
```
```http
HTTP 200
Expand All @@ -190,7 +190,7 @@ HTTP 200
{
"skill_id": "org.stellar.skills.cross-chain.cctp",
"version": "2026.8.31",
"agent": "GAR4TZFASYN4PSFEL2UCE4LR7NIWEIF6FPWXQOP53GDFCPHUCFIBWOMJ",
"agent": "GAKHP5233JPQS5HHW6ODVLAWVOIEUWIJQX3XDACM2AWCNURAOUT5G4HM",
"held": true,
"tokens_contract_id": "CB6VK4EXEN7V6MXLOFUI2ECMLSDUXAUV5EZICWBICKJDL3WPPU3CTP3T",
"contract_url": "https://stellar.expert/explorer/testnet/contract/CB6VK4EXEN7V6MXLOFUI2ECMLSDUXAUV5EZICWBICKJDL3WPPU3CTP3T"
Expand All @@ -202,9 +202,9 @@ HTTP 200
## 3. Use: the bytes served are the bytes that were audited, and the repeat is free

```bash
curl -s 'https://api-sterish.jameshub.fun/use/org.stellar.skills.cross-chain.cctp/2026.8.31' \
-H 'X-AGENT-ADDRESS: GAR4TZFASYN4PSFEL2UCE4LR7NIWEIF6FPWXQOP53GDFCPHUCFIBWOMJ' \
-H 'X-STERISH-PROOF-NONCE: 4f876bbd23e912bb1e21efaca44fb891' \
curl -s 'https://api.sterish.xyz/use/org.stellar.skills.cross-chain.cctp/2026.8.31' \
-H 'X-AGENT-ADDRESS: GAKHP5233JPQS5HHW6ODVLAWVOIEUWIJQX3XDACM2AWCNURAOUT5G4HM' \
-H 'X-STERISH-PROOF-NONCE: 8aabb0b326833b08c076b022c5d1d155' \
-H 'X-STERISH-PROOF-SIGNATURE: <SEP-53 signature, base64>'
```
```http
Expand All @@ -220,7 +220,7 @@ _Repeat request with a SEP-53 ownership proof (STE-48 is deployed). Body: the sk
## 4. The negative path: a poisoned skill is flagged and cannot be bought

```bash
curl -s 'https://api-sterish.jameshub.fun/check/com.fixtures.poisoned.token-drainer/1.0.0'
curl -s 'https://api.sterish.xyz/check/com.fixtures.poisoned.token-drainer/1.0.0'
```
```http
HTTP 200
Expand All @@ -238,7 +238,7 @@ HTTP 200
- ✅ `com.fixtures.poisoned.token-drainer` is **DANGEROUS** (10/100), not VERIFIED

```bash
curl -s 'https://api-sterish.jameshub.fun/use/com.fixtures.poisoned.token-drainer/1.0.0'
curl -s 'https://api.sterish.xyz/use/com.fixtures.poisoned.token-drainer/1.0.0'
```
```http
HTTP 403
Expand All @@ -254,4 +254,4 @@ HTTP 403

## Result

**PASS** — 15 checks, all against the live deployment and the ledger. Agent `GAR4TZFASYN4PSFEL2UCE4LR7NIWEIF6FPWXQOP53GDFCPHUCFIBWOMJ`.
**PASS** — 15 checks, all against the live deployment and the ledger. Agent `GAKHP5233JPQS5HHW6ODVLAWVOIEUWIJQX3XDACM2AWCNURAOUT5G4HM`.
51 changes: 51 additions & 0 deletions docs/evidence/ste-54-vps-migration-2026-09-17.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
{
"ticket": "STE-54",
"date": "2026-09-17",
"from": "Proxmox pve02 LXC CT 204 (homelab)",
"to": "VPS 187.53.142.100 (Ubuntu 26.04, 2 vCPU / 8 GB / 96 GB, IPv4+IPv6)",
"tunnel": "sterish-api 0cce8c0e-6239-4454-9ec6-a2a4515e4c9d (unchanged; the VPS is now its only connector, origin IP 187.53.142.100)",
"cutover_utc": {
"start": "13:49:02",
"end": "13:49:16"
},
"payments_ledger": {
"sha256_prefix_old_host": "058a002ed05e74d0",
"sha256_prefix_copied": "058a002ed05e74d0",
"sha256_prefix_on_vps": "058a002ed05e74d0",
"rows_at_cutover": 8,
"owed_at_cutover": 0,
"rows_after_e2e": 9
},
"index": "rebuilt from chain on the VPS (cache)",
"publish_artifacts": "18 for sale (18 newly published), 4 not SAFE, 0 failed",
"verify_sh": "all checks passed via https://api-sterish.jameshub.fun (17 SAFE rows for sale, 0 undeliverable priced)",
"e2e_paid_path": {
"api": "https://api-sterish.jameshub.fun",
"skill": "org.stellar.skills.standards.ecosystem",
"agent": "GC6VEHOETZU4G6SUVT2JCLQHRUZSN57R6JM65VXHEQ6EIWLEAWL7PV2O",
"funding_tx": "04ce8d6c45bdea7c2a9695166ab3e16bb433065fc614189e404a00ef48080833",
"settle_tx": "54d18460153bc4bcc6c51229898c138a4591be9f5b8a681fbcde4346f8d4b170",
"mint_tx": "2eb739eeaeddbb7b344fd2bb539ff7681a069447f6318fe2f1641cdb961e047c",
"ownership_proof": "held with proof 200; address-only, forged, replayed, borrowed, wrong-version all 401",
"result": "pass"
},
"api_log_after_cutover": {
"real visitor addresses logged": true,
"5xx": 0,
"warnings": 0,
"note": "the IPv6 RPC retry warnings seen on CT 204 (no IPv6 route) are gone: the VPS has a working IPv6 route"
},
"old_host": "stack stopped, not deleted; ctredeploy scripts renamed *.DISABLED-moved-to-vps; /opt/sterish/MOVED-TO-VPS.txt",
"api.sterish.xyz": {
"dns": "proxied CNAME api -> 0cce8c0e-6239-4454-9ec6-a2a4515e4c9d.cfargotunnel.com in the sterish.xyz zone (added in the dashboard); stray api.sterish.xyz.jameshub.fun deleted (NXDOMAIN)",
"report_base_url": "https://api.sterish.xyz",
"verify_sh": "all checks passed via https://api.sterish.xyz",
"urls_built_by_api": {
"report_uri": "https://api.sterish.xyz/reports/...",
"x402_resource_url": "https://api.sterish.xyz/use/...",
"ownership_challenge_url": "https://api.sterish.xyz/use/.../challenge?agent=..."
},
"old_hostname": "api-sterish.jameshub.fun still 200",
"d3_transcript": "regenerated through api.sterish.xyz, 15/15"
}
}
Loading