Add prepare.sh build bootstrap for clean Debian box

Start9's build-from-source flow needs every host prerequisite installed before
'make' runs. Add a bootstrap mirroring the official 0.4.0.x environment-setup
page: apt prereqs, Node 22, Docker (+binfmt for cross-arch), and start-cli via
the official installer. Rust stays inside the package Dockerfile, not the host.

KEYSAT_AGENT_GUIDE.md

@@ -57,6 +57,7 @@ API keys. Each carries a role that bounds what it can do. Format: `ks_<43 chars>
 | `read-only` | List / get every resource. Mutate nothing. |
 | `license-issuer` | All `read-only` scopes + issue / revoke / suspend / change-tier on licenses. Cannot touch products, policies, or codes. |
 | `support` | All `license-issuer` scopes + cancel subscriptions + force-deactivate machines. |
+| `merchant-onboard` | All `read-only` scopes + `products:write` + `policies:write` + `licenses:write` — the least-privilege credential for standing up a fresh catalog (create products, define policies/tiers, issue licenses against them) via the API. Deliberately excludes the support writes (subscriptions / machines) and every master-only gate. Tier caps still bound it. |
 | `full-admin` | Every scope. Equivalent to the master key for most endpoints. |
 
 Endpoints that touch settings (operator name, payment provider connections,
@@ -138,7 +139,7 @@ upgrade CTA without parsing message strings.
 | `expired` | Past `expires_at` |
 | `fingerprint_mismatch` | Different machine than the one bound on first activate |
 | `product_mismatch` | License is for a different product than the caller asserted |
-| `machine_cap_exceeded` | Activating this fingerprint would exceed `max_machines` |
+| `too_many_machines` | Activating this fingerprint would exceed `max_machines` |
 
 ---
 
@@ -173,7 +174,9 @@ curl -X POST $KS/v1/admin/licenses/$LICENSE_ID/revoke \
   -d '{"reason":"customer request"}'
 ```
 
-Idempotent. The next online validate from the buyer's app returns `reason: revoked`.
+The next online validate from the buyer's app returns `reason: revoked`. Not
+idempotent — a second revoke of the same license returns `404 not_found` (treat
+as success-equivalent on retry; see Idempotency below).
 
 Scope required: `licenses:write`.
 
@@ -277,10 +280,16 @@ A few patterns that work well in practice.
 
 ### Idempotency
 
-The daemon's mutation endpoints are idempotent where they can be. Revoke,
+The daemon's mutation endpoints are idempotent where they can be. Suspend,
-suspend, unsuspend, archive, unarchive, subscription cancel — all return
+unsuspend, archive, unarchive, subscription cancel — all return success on the
-success on the second call without changing state. Your agent can safely
+second call without changing state. Your agent can safely retry on network
-retry on network errors.
+errors.
+
+One exception: **revoke is not idempotent** — revoking an already-revoked
+license returns `404 not_found` (the row no longer matches the
+`status != 'revoked'` update guard). When retrying a revoke after an ambiguous
+network failure, treat a `404` as success-equivalent: the license is already
+revoked.
 
 ### Pagination
 
@@ -349,15 +358,26 @@ Some operations are deliberately operator-only and not accessible to any
 scoped key, including `full-admin`:
 
 - Generating / revoking scoped API keys (`/v1/admin/api-keys`)
-- Connecting / disconnecting payment providers
+- Disconnecting a payment provider, and connecting *any* provider on a
+  production daemon
 - Setting the operator name
 - Activating the self-license (`/v1/admin/self-license`)
 - Resetting the analytics install_uuid
 - Changing the web UI password (StartOS Action only)
 
 These all require the master `KEYSAT_ADMIN_API_KEY`. The reasoning: an agent
-that can rotate its own credentials, connect arbitrary payment processors, or
+that can rotate its own credentials, redirect settled payments, or change the
-change the operator identity is no longer bounded by the role it was given.
+operator identity is no longer bounded by the role it was given.
+
+**One narrow exception — agent-delegated payment connect.** A key granted the
+à-la-carte `payment_providers:write` scope (never granted by any role —
+operators add it explicitly per key) CAN initiate a BTCPay connect, but only
+fail-closed under two gates: the daemon must be in **sandbox mode** (an outer
+gate — scoped connect is refused outright on a production daemon, even for
+regtest), and the target store must be **non-mainnet** (an inner gate enforced
+after the OAuth round-trip). Disconnecting a provider, and any connect on a
+production / mainnet daemon, remain master-only. This lets an integrating agent
+wire up a throwaway sandbox without ever touching a live store's settlement.
 
 ---
 

Makefile

@@ -15,4 +15,9 @@
 #
 # Chain targets when needed: `make clean arm install`.
 
+# Only x86_64 and aarch64 are supported and declared in the manifest. The shared
+# s9pk.mk defaults ARCHES to include riscv; override it here so a bare `make`
+# (which builds every arch in ARCHES) does not attempt an unverified riscv build.
+ARCHES := x86 arm
+
 include s9pk.mk

README.md

@@ -80,10 +80,10 @@ comp keys, beta access, or "first N users free" launch promos.
 Built from the local `Dockerfile` via `images.main.source.dockerBuild`,
 with build context set to the parent directory so the Dockerfile can
 `COPY` from the sibling `licensing-service/` source tree. The Rust binary
-is statically linked against musl (target
+is statically compiled against musl (target `*-unknown-linux-musl`), and the
-`*-unknown-linux-musl`) so the runtime image is a `scratch`-based final
+runtime stage is `debian:bookworm-slim` with `ca-certificates`, `tini` (init /
-stage with no shared-library dependencies. Architectures: `x86_64` and
+signal handling), and `sqlite3` (an SQL shell for occasional admin tasks)
-`aarch64`.
+installed. Architectures: `x86_64` and `aarch64`.
 
 `start-cli s9pk pack` ingests the resulting OCI image, converts it to a
 squashfs filesystem image, and embeds that in the `.s9pk`. At runtime
@@ -105,25 +105,24 @@ mandatory.
 ## Installation and First-Run Flow
 
 1. Install Keysat via the marketplace (or sideload the `.s9pk`).
-2. Resolve the auto-created **critical task** "Connect BTCPay" by
+2. Resolve the auto-created **important task** "Connect BTCPay" — open
-   running the **Connect BTCPay** action. This opens a one-click
+   the embedded admin web UI (**Settings → Payment providers**) and
-   authorize page on your local BTCPay; after approval, Keysat
+   click **Connect BTCPay**. This opens a one-click authorize page on
-   auto-detects your store and registers an inbound webhook. No API
+   your local BTCPay; after approval, Keysat auto-detects your store and
-   keys to copy.
+   registers an inbound webhook. No API keys to copy. The install task
-3. Run **Check BTCPay connection** to confirm — the install task clears
+   clears automatically once BTCPay reports connected.
-   automatically.
+3. Set your **operator name** (shown on the public homepage and in
-4. Set your **operator name** (shown on the public homepage and in
    buyer-facing receipts).
-5. Create one or more **products** — each represents something you sell.
+4. Create one or more **products** — each represents something you sell.
-6. Create at least one **policy** per product. Multi-tier ladders
+5. Create at least one **policy** per product. Multi-tier ladders
    (Basic / Pro / Max) are first-class: when a product has two or more
    public policies, the buy page renders a tier picker and the buyer
    chooses before paying. Policies define duration, grace period, seat
    cap, entitlements, recurring cadence, trial flag, price overrides,
    marketing bullets, and per-entitlement hide-on-buy-page toggles.
-7. Optionally create **discount / referral / free-license codes** (see
+6. Optionally create **discount / referral / free-license codes** in the
-   `Create discount code` action).
+   admin web UI.
-8. Share the public service URL with buyers.
+7. Share the public service URL with buyers.
 
 ## Configuration Management
 
@@ -145,7 +144,7 @@ interfaces for clarity:
 | Interface | Type | Path prefix | Purpose                                                                      |
 |-----------|------|-------------|------------------------------------------------------------------------------|
 | `api`     | api  | `/`         | Public REST API for buyers (purchase, redeem) and licensed apps (validate, machine activation). Bake the URL into your software builds as the licensing endpoint. |
-| `webhook` | api  | `/btcpay`   | BTCPay webhook landing endpoint. Registered automatically during Connect BTCPay; not for human use. |
+| `webhook` | api  | `/btcpay`   | BTCPay webhook landing endpoint. Registered automatically when you connect BTCPay in the admin web UI; not for human use. |
 
 StartOS terminates TLS at the platform edge. Inside the container every
 request arrives as plain HTTP. For browser-facing URLs (e.g., the public
@@ -153,44 +152,23 @@ purchase page) hardcode `https://`.
 
 ## Actions (StartOS UI)
 
-Grouped as displayed in the dashboard.
+The StartOS Actions tab is intentionally minimal — only the four operations
+that must happen outside the embedded admin web UI are registered as actions:
 
-**General**
+- *Set web UI password* — set / recover the admin SPA login password (you
-- *Set operator name* — your public-facing brand.
+  can't reset it from inside the UI if you're locked out).
+- *Show credentials* — reveal the admin API key on first install, before
+  you've logged into the admin UI.
+- *Activate Keysat license* — first-install bootstrap for paid self-hosting
+  tiers, and recovery if `/data/keysat-license.txt` is lost.
+- *Show license status* — sanity-check the self-license state without
+  logging into the admin UI.
 
-**BTCPay**
+Everything else — connecting BTCPay (and Zaprite), operator name, products,
-- *Connect BTCPay* — one-click authorize against your BTCPay; auto-detects store and registers webhook.
+policies, discount / referral / free-license codes, licenses, machines,
-- *Check BTCPay connection* — confirm BTCPay state; clears the install task on success.
+outbound webhooks, scoped API keys, and the audit log — lives in the embedded
-
+**admin web UI** (Settings tab + the workspace sidebar), not as StartOS
-**Credentials**
+actions.
-- *Show admin credentials* — admin API key for direct `/v1/admin/*` access.
-
-**Products + Policies**
-- *Create product* — declare something to sell.
-- *Create policy* — license template for a product (duration, grace, seat cap, entitlements, trial flag, price override).
-
-**Discount codes**
-- *Create discount code* — percent-off / fixed-sats-off / free-license.
-- *List discount codes* — usage stats.
-- *Disable / enable discount code*.
-
-**Licenses**
-- *Issue license manually* — comp / press / grandfathered keys.
-- *Search licenses* — by email or BTCPay invoice id.
-- *Suspend license* — reversible lockout.
-- *Unsuspend license*.
-- *Revoke license* — terminal kill.
-
-**Machines**
-- *List machines* — installs bound to a license.
-- *Deactivate machine* — free a seat.
-
-**Webhooks (outbound)**
-- *Register webhook endpoint* — POST signed events to your URL.
-- *List webhook endpoints*.
-
-**Diagnostics**
-- *View audit log* — admin mutation history, filterable.
 
 ## Backups and Restore
 
@@ -228,7 +206,7 @@ Known current limitations:
 - **No bulk / volume licensing UI.** "Buy 10 keys at once with discount" is not built into the buy page. Operators can issue N comp licenses via the admin API in a loop.
 - **Webhook delivery retries are bounded.** A subscriber down past the 10-attempt retry window lands in the dead-letter queue (visible in admin UI → Webhooks → Failed). BTCPay invoice reconciliation runs as a background poll so dropped *payment* webhooks are recovered.
 - **Hardware fingerprinting is client-supplied.** Keysat does not derive fingerprints itself; the buyer-side SDK passes whatever the integrator chose. The fingerprint is bound on first activate and enforced thereafter.
-- **Card payments not shipped.** The Zaprite payment provider is in design for v0.3 — operators on Pro / Patron will get a card-payment option alongside BTCPay. Until then, payments are BTC / Lightning only.
+- **Card payments via Zaprite are gated.** Zaprite ships as an optional second payment provider (card / fiat alongside BTCPay) but is gated by the `zaprite_payments` entitlement — operators on the tiers that grant it can connect Zaprite in the admin web UI. BTCPay remains the required provider; without the entitlement, payments are BTC / Lightning only.
 
 ## What Is Unchanged from Upstream
 
@@ -257,7 +235,7 @@ service:
   marketingUrl: https://keysat.xyz
 image:
   source: dockerBuild
-  baseImage: scratch (musl-static Rust binary)
+  baseImage: debian:bookworm-slim (musl-compiled Rust binary; bundles ca-certificates, tini, sqlite3)
   arches: [x86_64, aarch64]
 volumes:
   - id: main
@@ -292,10 +270,10 @@ backups:
 firstRun:
   tasks:
     - id: btcpay-initial-setup
-      severity: critical
+      severity: important
       runs: configureBtcpay
 features:
-  paymentRail: btcpay-server   # zaprite planned for v0.3 (card payments)
+  paymentProviders: [btcpay-server, zaprite]   # btcpay required; zaprite optional, gated by the zaprite_payments entitlement
   signing: ed25519
   offlineVerification: true
   multiSeat: true
@@ -315,7 +293,7 @@ features:
   outboundWebhooks: true
   webhookDlq: true   # failed deliveries retryable from admin UI
   auditLog: true
-  scopedApiKeys: [read-only, license-issuer, support, full-admin]
+  scopedApiKeys: [read-only, license-issuer, support, merchant-onboard, full-admin]
   openapiSpec: /v1/openapi.json
   selfLicensingTier: [Creator, Pro, Patron]
 sdks:

licensing-service/README.md

@@ -56,44 +56,21 @@ See [`src/crypto/mod.rs`](src/crypto/mod.rs) for the exact byte layout.
 
 ## Project layout
 
-```
+The daemon source lives under `src/`, organized by subsystem (browse it for the current layout — the tree below has grown well past the v0.1 snapshot):
-licensing-service/
+
-├── Cargo.toml
+- `main.rs`, `config.rs`, `error.rs`, `models.rs` — entry point, env-driven config, error → HTTP mapping, shared domain types.
-├── LICENSE                        # source-available; no redistribution
+- `crypto/` — the LIC1 license-key byte layout and Ed25519 sign/verify (the contract the four SDKs implement).
-├── README.md
+- `db/` — SQLite pool, migrations, and `repo.rs` (all SQL). `migrations/` holds the numbered, additive schema (0001 through the latest; the schema has grown substantially since 0001).
-├── .env.example                   # required env vars
+- `payment/` (`btcpay/`, `zaprite/`) + `merchant_profiles.rs` — the payment-provider abstraction and multi-profile routing.
-├── migrations/
+- `reconcile.rs`, `subscriptions.rs`, `upgrades.rs` — the background worker (invoice reconciliation, recurring renewals, tier upgrades).
-│   └── 0001_initial.sql           # SQLite schema
+- `api/` — the ~30 route modules: public (`products`, `purchase`, `validate`, `redeem`) and admin (`admin*`, scoped API keys, webhooks, etc.), plus the router and `AppState` in `api/mod.rs`.
-├── src/
+- `web/index.html` — the embedded admin SPA.
-│   ├── main.rs                    # entry point: wires everything
+
-│   ├── config.rs                  # env-driven config
+Deeper docs: [`docs/API.md`](docs/API.md), [`docs/INTEGRATION.md`](docs/INTEGRATION.md), [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
-│   ├── error.rs                   # unified error → HTTP mapping
-│   ├── models.rs                  # shared domain types
-│   ├── crypto/
-│   │   ├── mod.rs                 # license key format + sign/verify
-│   │   └── keys.rs                # server keypair lifecycle
-│   ├── db/
-│   │   ├── mod.rs                 # pool + migrations
-│   │   └── repo.rs                # all SQL queries
-│   ├── btcpay/
-│   │   ├── client.rs              # Greenfield API client
-│   │   └── webhook.rs             # HMAC verification + event parsing
-│   └── api/
-│       ├── mod.rs                 # router + AppState
-│       ├── products.rs            # public product endpoints
-│       ├── purchase.rs            # buy + poll
-│       ├── validate.rs            # the hot path for downstream software
-│       ├── webhook.rs             # BTCPay landing
-│       └── admin.rs               # operator-only actions
-└── docs/
-    ├── API.md                     # full endpoint reference
-    ├── INTEGRATION.md             # for developers embedding a client
-    └── ARCHITECTURE.md            # deeper design notes
-```
 
 ## Running locally
 
-Prerequisites: Rust 1.75+, a BTCPay Server instance you can point at (local or hosted).
+Prerequisites: Rust 1.88+ (the build toolchain; the crate's Cargo.toml still declares MSRV 1.75, but the dependency tree now requires a newer compiler), a BTCPay Server instance you can point at (local or hosted).
 
 ```bash
 cp .env.example .env
@@ -109,7 +86,7 @@ On first boot the server generates a fresh Ed25519 keypair and stores it in the
 
 ```bash
 curl -X POST http://localhost:8080/v1/admin/products \
-  -H "Authorization: Bearer $LICENSING_ADMIN_API_KEY" \
+  -H "Authorization: Bearer $KEYSAT_ADMIN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "slug": "my-app",
@@ -143,7 +120,7 @@ curl -X POST http://localhost:8080/v1/validate \
 
 ## Deploying on Start9
 
-This repository ships the service only. To package as an `.s9pk` for the 0.4.0.x platform you'll need a separate wrapper repository following [docs.start9.com/packaging/0.4.0.x](https://docs.start9.com/packaging/0.4.0.x/). The service is designed to slot in cleanly:
+The StartOS wrapper lives in **this same repository** under `../startos/` (this `licensing-service/` directory is the daemon source it bundles). Build the `.s9pk` for the 0.4.0.x platform from the parent directory — see the build/release guide and `../Makefile`. The service is designed to slot in cleanly:
 
 - **Declares a dependency** on BTCPay Server in the manifest. StartOS will make BTCPay reachable at a `.startos` hostname and supply the env vars from the wrapper's action handlers.
 - **Persists to `/data`**, so everything (SQLite DB including the signing key) is covered by one-click encrypted backups.
@@ -170,4 +147,10 @@ Commercial redistribution / resale rights: contact licensing@keysat.xyz.
 
 ## Status
 
-v0.1 — minimal working implementation. Feature direction after this is expected to cover: SDK crates for Rust and TypeScript, s9pk wrapper repository, richer admin UI, invoice reconciliation job for dropped webhooks, per-product webhook endpoints for the operator.
+0.2.0 — shipped and in production. The current feature set:
+
+- **Four published SDKs** — TypeScript (npm), Rust (crates.io), Python (PyPI), and Go — all wire-compatible against the cross-check fixtures in `tests/crosscheck/`.
+- **StartOS wrapper included in this repo** under `../startos/`; build the `.s9pk` from the parent directory (no separate wrapper repository).
+- **Embedded admin SPA** (`web/index.html`) for all day-to-day operations.
+- **Subscriptions** (recurring auto-renew with trials + grace), **policies / tiers** with per-policy entitlements, **discount / referral / free-license codes**, **outbound webhooks** with a dead-letter queue, and a background **invoice reconciliation** job that recovers dropped payment webhooks.
+- **Payment providers**: BTCPay Server is required; Zaprite (card / fiat) is optional and gated by the `zaprite_payments` entitlement.

licensing-service/docs/API.md

@@ -6,7 +6,7 @@ All endpoints are JSON in / JSON out. Errors return a body of the form:
 { "ok": false, "error": "not_found", "message": "product 'xyz'" }
 ```
 
-Admin endpoints require `Authorization: Bearer $LICENSING_ADMIN_API_KEY`.
+Admin endpoints require `Authorization: Bearer $KEYSAT_ADMIN_API_KEY`.
 
 ---
 
@@ -19,7 +19,7 @@ Service metadata including the Ed25519 public key. Useful for SDKs to fetch the
 ```json
 {
   "service": "keysat",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "operator": "Acme Software",
   "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCow...\n-----END PUBLIC KEY-----\n",
   "key_algorithm": "ed25519",
@@ -128,7 +128,7 @@ On failure:
 { "ok": false, "reason": "revoked" }
 ```
 
-Possible `reason` values: `bad_format`, `bad_signature`, `not_found`, `revoked`, `product_mismatch`, `fingerprint_mismatch`.
+Possible `reason` values: `bad_format`, `bad_signature`, `not_found`, `revoked`, `suspended`, `expired`, `product_mismatch`, `fingerprint_mismatch`, `too_many_machines` (multi-seat cap reached).
 
 ### `POST /v1/btcpay/webhook`
 
@@ -138,7 +138,7 @@ Landing point for BTCPay Server webhook events. Only BTCPay should call this. We
 
 ## Admin endpoints
 
-All of these require `Authorization: Bearer $LICENSING_ADMIN_API_KEY`.
+All of these require `Authorization: Bearer $KEYSAT_ADMIN_API_KEY`.
 
 ### `POST /v1/admin/products`
 

licensing-service/docs/ARCHITECTURE.md

@@ -12,13 +12,18 @@
 
 ## Data model
 
-See [`migrations/0001_initial.sql`](../migrations/0001_initial.sql). Five tables:
+The schema lives in [`migrations/`](../migrations/) as numbered, additive
+migrations (0001 through the latest — it has grown substantially past the
+original five-table v0.1 schema, adding discount codes, tiered pricing,
+multi-currency, subscriptions, tier upgrades, per-product entitlement catalogs,
+scoped API keys, merchant profiles, and more). The core tables established in
+[`0001_initial.sql`](../migrations/0001_initial.sql):
 
 - `products` — what's for sale. Independent pricing per product.
 - `invoices` — one per purchase attempt, keyed by BTCPay's invoice id.
-- `licenses` — one per successful payment (or manual issuance). Has optional `fingerprint` (machine bind) and `bound_identity` (user bind) columns.
+- `licenses` — one per successful payment (or manual issuance). Has optional `fingerprint` (machine bind) and `bound_identity` (user bind) columns. Later migrations add `expires_at`, entitlements, trial flag, and tier columns.
 - `validation_log` — append-only audit log of every validate call. Useful for detecting abuse (same key, many fingerprints) and for rate-limiting layers above us.
-- `server_keys` — singleton table holding the server's Ed25519 keypair. Generated on first boot, never rotated in v0.1 (rotation is a planned feature).
+- `server_keys` — singleton table holding the server's Ed25519 keypair. Generated on first boot.
 
 ## License key format
 
@@ -28,7 +33,7 @@ LIC1 - <base32(74-byte payload)> - <base32(64-byte signature)>
 
 The payload is a fixed binary layout, not JSON, to keep keys short. Details in [`src/crypto/mod.rs`](../src/crypto/mod.rs).
 
-Why base32 Crockford-style (no padding)?
+Why base32 (RFC 4648, no padding)?
 
 - Uppercase only, unambiguous chars, easy to read aloud or type from a screen.
 - Slightly longer than base64 but less error-prone for humans copying keys.
@@ -58,14 +63,12 @@ Who might attack this?
 
 5. **Chargeback / dispute** (applicable to non-Bitcoin rails, but worth noting). Bitcoin payments are irreversible, so the normal fraud model that motivates software DRM mostly doesn't apply here. Most revocations will be: key leaked publicly, legitimate business decision, mistaken issuance.
 
-## What's deliberately NOT in v0.1
+## Deliberately out of scope
 
-- **Key rotation.** A single static signing key is fine for first launch. Rotation requires SDK multi-key support and a migration strategy; deferred.
+- **Key rotation.** A single static signing key is fine for now. Rotation requires SDK multi-key support and a migration strategy; deferred.
-- **Trial periods / demos.** This is a pure paid-license server. Trials are the developer's responsibility in-app.
-- **Payment currencies other than BTC.** BTCPay supports Lightning, altcoins, and fiat; we only send BTC-denominated invoices. Adding Lightning is straightforward (BTCPay handles it transparently if the store has LN configured).
-- **Subscription / time-limited licenses.** The payload has an `issued_at` field but no `expires_at`. Adding expiry is a later schema + payload change.
 - **Multi-tenant / SaaS mode.** This is a *single-operator* server by design. Running multiple logical operators on one instance is a different product.
-- **Admin UI.** Everything is API-driven. Wrap it in whatever UI you like — or just use `curl`.
+
+(Trial/time-limited policies, multi-currency pricing, the optional Zaprite card rail, and the embedded admin UI all shipped after v0.1 and are no longer on this list.)
 
 ## Notes on Start9 dependencies
 

licensing-service/docs/INTEGRATION.md

@@ -25,9 +25,18 @@ curl -s https://license.example.com/v1/pubkey | jq -r .public_key_pem
 
 Commit the resulting PEM into your client source tree. **Do not fetch it dynamically at runtime** — that would let an attacker who compromises your licensing server swap the key and re-sign forged licenses retroactively. A pinned public key is the whole point.
 
+> **Official SDKs exist — use them first.** Four wire-compatible client SDKs
+> are published: TypeScript (`@keysat/licensing-client` on npm), Rust
+> (`keysat-licensing-client` on crates.io), Python (`keysat-licensing-client`
+> on PyPI), and Go (`github.com/keysat-xyz/keysat-client-go`). Install commands
+> are in the main README. The by-hand reference implementations below are a
+> fallback for languages without an SDK, or for understanding exactly what the
+> SDKs do under the hood.
+
 ## Reference integration in Rust
 
-This is what a Start9 package written in Rust might look like. No SDK crate yet — that's planned; here's what you'd write by hand:
+This is what a Start9 package written in Rust might look like if you verify by
+hand instead of using the Rust SDK:
 
 ```rust
 use anyhow::{Context, Result};

licensing-service/src/merchant_profiles.rs

@@ -27,10 +27,14 @@ use uuid::Uuid;
 
 /// A merchant profile row. Mirrors the `merchant_profiles` table.
 ///
-/// SMTP fields are flattened onto the same struct for simplicity; they
+/// NOTE: the `smtp_*` fields are DORMANT and not consumed by anything.
-/// land in the same table on the same row. NULL on all six means
+/// They were laid down in migration 0020 ahead of the keysat-smtp-emails
-/// "inherit StartOS-level SMTP config." See the keysat-smtp-emails
+/// plan, which was SUPERSEDED 2026-06-18: Keysat will never send buyer
-/// plan for how they're consumed.
+/// email itself (operators own that via their own app + the existing
+/// webhooks). The columns are left in place because a removal migration
+/// isn't worth it — do not build a send path against them. See
+/// `plans/keysat-smtp-emails.md` (superseded banner) and the
+/// "Operability & alerts" ROADMAP item.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MerchantProfile {
     pub id: String,
@@ -42,7 +46,8 @@ pub struct MerchantProfile {
     pub post_purchase_redirect_url: Option<String>,
     pub is_default: bool,
 
-    // SMTP override (all-or-nothing for now; the SMTP plan refines this).
+    // Dormant SMTP-override columns (see struct doc) — stored/returned
+    // but never read to send mail; no send path exists or is planned.
     pub smtp_host: Option<String>,
     pub smtp_port: Option<i64>,
     pub smtp_username: Option<String>,

licensing-service/src/subscriptions.rs

@@ -67,7 +67,7 @@ use crate::payment::CreateInvoiceParams;
 use anyhow::{anyhow, Context, Result};
 use chrono::{Duration as ChronoDuration, Utc};
 use serde::{Deserialize, Serialize};
-use serde_json::json;
+use serde_json::{json, Value};
 use sqlx::{Row, SqlitePool};
 use std::time::Duration as StdDuration;
 use uuid::Uuid;
@@ -1349,13 +1349,18 @@ pub async fn capture_zaprite_payment_profile(
 /// worker *after* it has created the order; this turns the order
 /// from "buyer must pay" into "auto-charged, will settle via the
 /// usual webhook." Returns:
-///   - `Ok(true)`  — the charge call succeeded; the buyer is not
+///   - `Ok(true)`  — the charge settled (order status PAID/COMPLETE/
-///                   expected to pay manually. The settle webhook
+///                   OVERPAID); the buyer is not expected to pay
-///                   will fire on its own and flip the sub to
+///                   manually. The settle webhook will fire on its
-///                   `active` via `on_invoice_settled`.
+///                   own and flip the sub to `active` via
-///   - `Ok(false)` — sub has no saved profile, or active provider
+///                   `on_invoice_settled`.
-///                   isn't Zaprite. Caller proceeds with manual-pay
+///   - `Ok(false)` — sub has no saved profile, active provider isn't
-///                   fallback (`subscription.renewal_pending`).
+///                   Zaprite, OR Zaprite accepted the request (HTTP
+///                   2xx) but the order did NOT reach a settled status
+///                   (declined/expired/in-flight/unknown). In every
+///                   `Ok(false)` case the caller proceeds with the
+///                   manual-pay fallback (`subscription.renewal_pending`)
+///                   so the buyer keeps a path to recover the cycle.
 ///   - `Err(_)`    — Zaprite returned an error (declined card,
 ///                   expired profile, network blip). Caller treats
 ///                   this as a soft failure: log, audit, and ALSO
@@ -1400,12 +1405,86 @@ async fn try_auto_charge_zaprite(
         .await
         .context("Zaprite charge_order_with_profile")?;
 
+    // A 2xx from `/v1/orders/charge` only means Zaprite ACCEPTED the
+    // request — the order's `status` says whether the money actually
+    // moved. A charge that came back declined/expired/in-flight (or any
+    // status we don't positively recognize as settled) leaves no settle
+    // webhook to wait for, so returning Ok(true) here would silently
+    // lapse the sub: we'd suppress the manual-pay notification and wait
+    // forever for an `order.paid` that never arrives. Fail safe — only
+    // suppress manual-pay when the order is in a recognized settled
+    // state; otherwise fall through (Ok(false)) so the buyer still gets
+    // a pay link and can recover the cycle.
+    let order_status = resp.get("status").and_then(|v| v.as_str()).unwrap_or("?");
+    if !zaprite_charge_settled(&resp) {
+        tracing::warn!(
+            sub_id = %sub.id,
+            order_id = %provider_invoice_id,
+            profile_id = %profile_id,
+            order_status,
+            "Zaprite auto-charge accepted (HTTP 2xx) but order is not settled; \
+             falling back to manual-pay renewal"
+        );
+        return Ok(false);
+    }
+
     tracing::info!(
         sub_id = %sub.id,
         order_id = %provider_invoice_id,
         profile_id = %profile_id,
-        order_status = resp.get("status").and_then(|v| v.as_str()).unwrap_or("?"),
+        order_status,
-        "Zaprite auto-charge succeeded; awaiting settle webhook"
+        "Zaprite auto-charge settled; awaiting settle webhook"
     );
     Ok(true)
 }
+
+/// Does a Zaprite `/v1/orders/charge` response (HTTP 2xx already
+/// confirmed by the client) indicate the charge actually settled?
+///
+/// Mirrors the PAID/COMPLETE/OVERPAID → `Settled` mapping in
+/// `ZapriteProvider::get_invoice_status`. Deliberately an **allowlist**,
+/// not a failure blocklist: Zaprite's confirmed order-status enum is
+/// PENDING|PROCESSING|PAID|COMPLETE|OVERPAID|UNDERPAID with no documented
+/// terminal-failure string, so any unrecognized or missing status must be
+/// treated as "not settled" and routed to manual-pay rather than
+/// optimistically assumed paid.
+fn zaprite_charge_settled(resp: &Value) -> bool {
+    matches!(
+        resp.get("status").and_then(|v| v.as_str()),
+        Some("PAID") | Some("COMPLETE") | Some("OVERPAID")
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::zaprite_charge_settled;
+    use serde_json::json;
+
+    #[test]
+    fn charge_settled_only_for_recognized_paid_statuses() {
+        // Settled states → suppress manual-pay (Ok(true) upstream).
+        for s in ["PAID", "COMPLETE", "OVERPAID"] {
+            assert!(
+                zaprite_charge_settled(&json!({ "status": s })),
+                "{s} should count as settled"
+            );
+        }
+        // The silent-lapse guard: a 2xx carrying any non-settled status
+        // must NOT be treated as success. In-flight, underpaid,
+        // terminal-failure, and unknown statuses all fall through to the
+        // manual-pay path.
+        for s in [
+            "PENDING", "PROCESSING", "UNDERPAID", "FAILED", "DECLINED", "EXPIRED",
+            "CANCELED", "REFUNDED", "",
+        ] {
+            assert!(
+                !zaprite_charge_settled(&json!({ "status": s })),
+                "{s} must NOT count as settled"
+            );
+        }
+        // Malformed / absent / non-string status fields fall through too.
+        assert!(!zaprite_charge_settled(&json!({})));
+        assert!(!zaprite_charge_settled(&json!({ "status": null })));
+        assert!(!zaprite_charge_settled(&json!({ "status": 200 })));
+    }
+}

licensing-service/web/index.html

@@ -415,16 +415,16 @@ hr.div { border:none; border-top:1px solid var(--border-1); margin:18px 0; }
   border:1px solid var(--border-1);
 }
 .featured-pill-toggle.on {
-  background:var(--gold-500); color:var(--navy-950);
+  background:var(--navy-800); color:var(--cream-50);
-  border-color:var(--gold-500);
+  border-color:var(--navy-800);
-  box-shadow:0 2px 6px rgba(191,160,104,0.25);
+  box-shadow:0 2px 6px rgba(14,31,51,0.18);
 }
 .featured-pill-toggle.on .state {
-  background:var(--navy-950); color:var(--gold-500);
+  background:var(--cream-50); color:var(--navy-900);
-  border-color:var(--navy-950);
+  border-color:var(--cream-50);
 }
 .featured-pill-toggle.on:hover {
-  background:var(--gold-400);
+  background:var(--navy-900);
 }
 
 /* Tier-card drag affordance — cursor signals draggability on hover,
@@ -534,12 +534,12 @@ hr.div { border:none; border-top:1px solid var(--border-1); margin:18px 0; }
         <div id="tier-banner-msg" style="margin-bottom:8px;"></div>
         <a id="tier-banner-cta" target="_blank" rel="noopener" style="
           display:inline-block; padding:5px 10px;
-          background:var(--gold-500); color:var(--navy-950);
+          background:var(--cream-50); color:var(--navy-900);
           font-weight:700; font-size:11px;
-          border-radius:5px; text-decoration:none;
+          border-radius:8px; text-decoration:none;
           transition:background 120ms;
-        " onmouseover="this.style.background='var(--gold-400)'"
+        " onmouseover="this.style.background='var(--cream-200)'"
-           onmouseout="this.style.background='var(--gold-500)'"></a>
+           onmouseout="this.style.background='var(--cream-50)'"></a>
       </div>
       <div class="footer" id="sidebar-footer">
         <span class="dot warn"></span>
@@ -5763,7 +5763,7 @@ hr.div { border:none; border-top:1px solid var(--border-1); margin:18px 0; }
   // -------- Merchant profiles (multi-provider model, :52+) --------
   // Each profile represents one "business" the operator is running on
   // this Keysat instance. Owns business identity (brand, support contact,
-  // post-purchase redirect, optional SMTP override) and a set of payment
+  // post-purchase redirect; SMTP-override cols are dormant/unused) and a set of payment
   // providers (BTCPay / Zaprite) that legally settle to that business.
   // Products attach to a profile. Tier-gated: Creator gets 1, Pro/Patron
   // get unlimited.

onboarding-harness/README.md

@@ -53,15 +53,26 @@ that boundary is a feature, not a gap.
 
 ```sh
 (cd stage2/btcpay-regtest && docker compose -p keysat-btcpay up -d)   # one-time
+./stage2/btcpay-regtest/probe.sh  # mints the BTCPay store token into .live-env (one-time)
 ./stage2/run-stage2.sh            # boots sandbox daemon + regtest wiring + scoped key
 # feed runs/<id>/AGENT_BRIEF.md to the onboarding-tester agent
+./stage2/teardown-stage2.sh       # WHEN DONE: stop daemon(s) + docs + sandbox dev server + BTCPay stack
 ```
 
 - `stage2/btcpay-regtest/` — the BTCPay regtest compose + de-risk probe (`FINDINGS.md`).
 - `stage2/validate-gate.sh` — end-to-end gate check (deny mainnet/undetermined, allow regtest).
 - `stage2/buyer-pay.sh` — the test buyer's wallet (pay invoice on regtest + mine).
+- `stage2/teardown-stage2.sh` — full cleanup: tears down every Stage 2 run, kills any orphaned
+  sandbox dev server (`:4311`), and stops the BTCPay docker stack + volumes (`--keep-btcpay`
+  to leave it up between runs). **Always run this when finished** — the agent can leave a
+  daemon, a docs server, or an `npm run dev` behind.
 - `stage2/STAGE2-RESULT.md` — convergence + the publishable walkthrough.
 
+**Harvesting on a clean run:** do NOT reflexively bolt a new success story onto the public
+HTML. First check whether `keysat-docs/agent.html` (the connect workflow + worked example)
+and the docs already cover the buyer-pays + SDK-gating case well enough; only propose
+additions for a genuine gap, with operator approval.
+
 ## Requirements
 
 `cargo`, `node`/`npm`, `python3`, `curl`, `jq`, `openssl`. (Docker is only

onboarding-harness/stage2/btcpay-regtest/probe.sh

@@ -1,25 +1,55 @@
 #!/usr/bin/env bash
-# De-risk probe for agent-payment-connect network detection (spec §6.1).
+# De-risk probe + .live-env minter for the Stage 2 / combined onboarding harness.
-# Stands up a store + on-chain regtest wallet on the local BTCPay regtest stack,
+# Run once after `docker compose -p keysat-btcpay up -d`.
-# then dumps the exact Greenfield responses the slice-3 gate would consult:
+#
-#   - GET /api/v1/stores/{id}/payment-methods         (paymentMethodId form? derivationScheme exposed?)
+# Two jobs:
-#   - GET /api/v1/stores/{id}/payment-methods/{pmid}/wallet/address   (bcrt1… prefix?)
+#   A. Mint .live-env — create the two stores the harness needs (one with an
+#      on-chain regtest wallet, one without) plus store-scoped BTCPay API tokens
+#      carrying the five permissions the Connect-BTCPay flow documents
+#      (install.html#connect-btcpay), and write them to .live-env for
+#      run-stage2.sh / validate-gate.sh to source.
+#   B. De-risk (spec §6.1) — dump the exact Greenfield responses the slice-3
+#      network gate consults (payment-methods, wallet/address) into probe-out/
+#      and classify the receive-address HRP.
+#
+# Idempotency: assumes a FRESH instance (compose `up -d` after `down -v`).
+# Re-running against a live instance creates duplicate stores — tear down first.
 # Read-only against Keysat; only mutates the throwaway BTCPay instance.
 set -uo pipefail
 
 BASE="${BTCPAY_BASE:-http://127.0.0.1:49392}"
 ADMIN_EMAIL="admin@keysat.local"
 ADMIN_PW="keysatregtest1!"
-OUT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/probe-out"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT_DIR="$HERE/probe-out"
+LIVE_ENV="$HERE/.live-env"
 mkdir -p "$OUT_DIR"
 
+# Permissions the documented Connect-BTCPay flow grants (install.html#connect-btcpay).
+STORE_PERMS='canviewstoresettings canmodifystoresettings canviewinvoices cancreateinvoice canmodifyinvoices'
+BTND=keysat-btcpay-bitcoind-1
+
 hr(){ printf '\n\033[1;36m=== %s ===\033[0m\n' "$*"; }
 jqp(){ jq . 2>/dev/null || cat; }
+AUTH=(-u "$ADMIN_EMAIL:$ADMIN_PW")
+cli(){ docker exec "$BTND" bitcoin-cli -regtest -rpcuser=keysat -rpcpassword=keysat -rpcport=43782 "$@"; }
+
+create_store(){ # NAME -> store id
+  curl -sS "${AUTH[@]}" -X POST "$BASE/api/v1/stores" \
+    -H 'Content-Type: application/json' -d "{\"name\":\"$1\"}" | jq -r '.id'
+}
+store_token(){ # STORE_ID -> store-scoped API key with the 5 documented perms
+  local sid="$1" perms="" p
+  for p in $STORE_PERMS; do perms="$perms\"btcpay.store.$p:$sid\","; done
+  curl -sS "${AUTH[@]}" -X POST "$BASE/api/v1/api-keys" \
+    -H 'Content-Type: application/json' \
+    -d "{\"label\":\"keysat-$sid\",\"permissions\":[${perms%,}]}" | jq -r '.apiKey'
+}
 
 # --- 0. wait for BTCPay --------------------------------------------------------
 hr "0. waiting for BTCPay health at $BASE"
 for i in $(seq 1 120); do
-  if curl -fsS "$BASE/api/v1/health" >/dev/null 2>&1; then break; fi
+  curl -fsS "$BASE/api/v1/health" >/dev/null 2>&1 && break
   sleep 2
   [[ $i == 120 ]] && { echo "BTCPay never became healthy"; exit 1; }
 done
@@ -31,52 +61,64 @@ curl -sS -X POST "$BASE/api/v1/users" \
   -H 'Content-Type: application/json' \
   -d "{\"email\":\"$ADMIN_EMAIL\",\"password\":\"$ADMIN_PW\",\"isAdministrator\":true}" | jqp
 
-# Basic-auth header for subsequent Greenfield calls.
+# --- 2. admin user API key (KEYSAT_LIVE_BTCPAY_KEY; broad, for ad-hoc admin use) -
-AUTH=(-u "$ADMIN_EMAIL:$ADMIN_PW")
+hr "2. mint admin user API key"
+ADMIN_KEY="$(curl -sS "${AUTH[@]}" -X POST "$BASE/api/v1/api-keys" \
+  -H 'Content-Type: application/json' \
+  -d '{"label":"keysat-admin","permissions":["btcpay.server.canmodifyserversettings","btcpay.store.canmodifystoresettings","btcpay.store.canmodifyinvoices"]}' \
+  | jq -r '.apiKey')"
+echo "ADMIN_KEY=${ADMIN_KEY:0:8}…"
 
-# --- 2. create a store ---------------------------------------------------------
+# --- 3. regtest store WITH an on-chain wallet ----------------------------------
-hr "2. create store"
+hr "3. create regtest store (with on-chain wallet)"
-STORE_JSON="$(curl -sS "${AUTH[@]}" -X POST "$BASE/api/v1/stores" \
+STORE_REGTEST="$(create_store 'Keysat Regtest Co')"
-  -H 'Content-Type: application/json' -d '{"name":"Keysat Regtest Co"}')"
+echo "STORE_REGTEST=$STORE_REGTEST"
-echo "$STORE_JSON" | jqp
+[[ -z "$STORE_REGTEST" || "$STORE_REGTEST" == null ]] && { echo "no regtest store id"; exit 1; }
-STORE_ID="$(echo "$STORE_JSON" | jq -r '.id')"
-echo "STORE_ID=$STORE_ID"
-[[ -z "$STORE_ID" || "$STORE_ID" == null ]] && { echo "no store id"; exit 1; }
 
-# --- 3. generate an on-chain wallet; try BTC-CHAIN then BTC --------------------
 gen_body='{"savePrivateKeys":false,"importKeysToRPC":false,"wordList":"English","wordCount":12,"scriptPubKeyType":"Segwit"}'
 PMID=""
 for cand in BTC-CHAIN BTC; do
-  hr "3. generate wallet on pmid=$cand"
+  hr "3b. generate wallet on pmid=$cand"
   code="$(curl -sS -o "$OUT_DIR/gen-$cand.json" -w '%{http_code}' "${AUTH[@]}" \
-    -X POST "$BASE/api/v1/stores/$STORE_ID/payment-methods/$cand/wallet/generate" \
+    -X POST "$BASE/api/v1/stores/$STORE_REGTEST/payment-methods/$cand/wallet/generate" \
     -H 'Content-Type: application/json' -d "$gen_body")"
   echo "HTTP $code"; cat "$OUT_DIR/gen-$cand.json" | jqp
-  if [[ "$code" == 2* ]]; then PMID="$cand"; break; fi
+  [[ "$code" == 2* ]] && { PMID="$cand"; break; }
 done
-[[ -z "$PMID" ]] && echo "!! wallet generate failed for both pmid forms (see above)"
+[[ -z "$PMID" ]] && { echo "!! wallet generate failed for both pmid forms"; exit 1; }
 
-# --- 4. mine some regtest blocks so the wallet has a usable address ------------
+# --- 4. mine regtest blocks so the wallet has a usable address -----------------
 hr "4. mine regtest blocks"
-ADDR_FOR_MINE="$(docker exec keysat-btcpay-bitcoind-1 bitcoin-cli -regtest -rpcuser=keysat -rpcpassword=keysat -rpcport=43782 getnewaddress 2>/dev/null || true)"
+ADDR_FOR_MINE="$(cli getnewaddress 2>/dev/null || true)"
 echo "miner address: ${ADDR_FOR_MINE:-<none>}"
-if [[ -n "$ADDR_FOR_MINE" ]]; then
+[[ -n "$ADDR_FOR_MINE" ]] && { cli generatetoaddress 101 "$ADDR_FOR_MINE" >/dev/null 2>&1 \
-  docker exec keysat-btcpay-bitcoind-1 bitcoin-cli -regtest -rpcuser=keysat -rpcpassword=keysat -rpcport=43782 generatetoaddress 101 "$ADDR_FOR_MINE" >/dev/null 2>&1 \
+  && echo "mined 101 blocks" || echo "mine failed (non-fatal for detection probe)"; }
-    && echo "mined 101 blocks" || echo "mine failed (non-fatal for detection probe)"
-fi
 
-# --- 5. THE PAYLOADS the slice-3 gate consults --------------------------------
+# --- 5. no-wallet store (fail-closed arm of the gate) --------------------------
-hr "5a. GET payment-methods  (does it expose derivationScheme? what pmid?)"
+hr "5. create no-wallet store"
-curl -sS "${AUTH[@]}" "$BASE/api/v1/stores/$STORE_ID/payment-methods?includeConfig=true" \
+STORE_NOWALLET="$(create_store 'Keysat NoWallet Co')"
+echo "STORE_NOWALLET=$STORE_NOWALLET"
+[[ -z "$STORE_NOWALLET" || "$STORE_NOWALLET" == null ]] && { echo "no nowallet store id"; exit 1; }
+
+# --- 6. store-scoped tokens (what the agent/harness hand Keysat at connect) -----
+hr "6. mint store-scoped tokens"
+GATE_TOK_REGTEST="$(store_token "$STORE_REGTEST")"
+GATE_TOK_NOWALLET="$(store_token "$STORE_NOWALLET")"
+echo "GATE_TOK_REGTEST=${GATE_TOK_REGTEST:0:8}…  GATE_TOK_NOWALLET=${GATE_TOK_NOWALLET:0:8}…"
+[[ "$GATE_TOK_REGTEST" == null || -z "$GATE_TOK_REGTEST" ]] && { echo "regtest token mint failed"; exit 1; }
+
+# --- 7. THE PAYLOADS the slice-3 gate consults --------------------------------
+hr "7a. GET payment-methods  (does it expose derivationScheme? what pmid?)"
+curl -sS "${AUTH[@]}" "$BASE/api/v1/stores/$STORE_REGTEST/payment-methods?includeConfig=true" \
   | tee "$OUT_DIR/payment-methods.json" | jqp
 
-hr "5b. GET wallet/address  (THE network artifact — expect bcrt1…)"
+hr "7b. GET wallet/address  (THE network artifact — expect bcrt1…)"
-ADDR_JSON="$(curl -sS "${AUTH[@]}" "$BASE/api/v1/stores/$STORE_ID/payment-methods/${PMID:-BTC-CHAIN}/wallet/address")"
+ADDR_JSON="$(curl -sS "${AUTH[@]}" "$BASE/api/v1/stores/$STORE_REGTEST/payment-methods/${PMID:-BTC-CHAIN}/wallet/address")"
 echo "$ADDR_JSON" | tee "$OUT_DIR/wallet-address.json" | jqp
 ADDR="$(echo "$ADDR_JSON" | jq -r '.address // empty')"
 
-# --- 6. classify --------------------------------------------------------------
+# --- 8. classify --------------------------------------------------------------
-hr "6. network classification"
+hr "8. network classification"
 echo "pmid used      : ${PMID:-BTC-CHAIN}"
 echo "receive address: ${ADDR:-<none>}"
 case "$ADDR" in
@@ -89,4 +131,16 @@ case "$ADDR" in
   *)      echo "=> UNRECOGNIZED prefix => FAIL-CLOSED → mainnet → master-only";;
 esac
 
-hr "done — raw payloads under $OUT_DIR/"
+# --- 9. write .live-env -------------------------------------------------------
+hr "9. write .live-env"
+cat > "$LIVE_ENV" <<EOF
+export KEYSAT_LIVE_BTCPAY_URL=$BASE
+export KEYSAT_LIVE_BTCPAY_KEY=$ADMIN_KEY
+export KEYSAT_LIVE_BTCPAY_STORE_REGTEST=$STORE_REGTEST
+export KEYSAT_LIVE_BTCPAY_STORE_NOWALLET=$STORE_NOWALLET
+export GATE_TOK_REGTEST=$GATE_TOK_REGTEST
+export GATE_TOK_NOWALLET=$GATE_TOK_NOWALLET
+EOF
+echo "wrote $LIVE_ENV"
+
+hr "done — raw payloads under $OUT_DIR/, credentials in $LIVE_ENV"

onboarding-harness/stage2/run-stage2.sh

@@ -2,7 +2,10 @@
 # Stage 2 setup: a sandbox Keysat daemon wired to the regtest BTCPay stack, a
 # scoped key that can BOTH onboard a catalog AND connect a payment provider
 # (merchant-onboard + payment_providers:write), the docs corpus, and a sandbox
-# app — then the agent brief for the buyer-pays journey.
+# app — then the agent brief for the COMBINED journey: gate a paid product
+# (define product + paid tier, integrate the SDK, prove the export is BLOCKED),
+# then prove it end to end (connect BTCPay regtest, a buyer pays, and the
+# PURCHASED license UNLOCKS the gated export).
 #
 # Networking: the daemon binds 0.0.0.0 and registers its BTCPay webhook via
 # host.docker.internal so the BTCPay *container* can reach it on settle; the
@@ -67,32 +70,58 @@ DOCS_URL="$(state_get "$STATE" DOCS_URL)"; SANDBOX="$(state_get "$STATE" SANDBOX
 source "$STAGE2_DIR/btcpay-regtest/.live-env"
 
 cat > "$RUN_DIR/AGENT_BRIEF.md" <<EOF
-# Onboarding-tester brief — Keysat Stage 2 (agent connects BTCPay regtest + buyer pays)
+# Onboarding-tester brief — Keysat combined journey (gate a paid product, then prove it with a real buyer payment)
 
 You are a **fresh adopter**, following \`~/Projects/standards/guides/onboarding-tester.md\`.
-Reach the goal using **only the docs corpus**. Never read Keysat source to unblock
+Reach the goal using **only the docs corpus**. Never read Keysat's server or SDK source to
-yourself — a gap in the docs is a finding.
+unblock yourself — if the docs don't get you there, that is a finding.
 
 ## Goal (checkable end-state)
-Acting for a merchant on a **sandbox** Keysat instance, using a **scoped, non-master**
+You are an operator selling a Next.js/TypeScript app. Do the **whole flow in the order an
-API key (it carries \`payment_providers:write\`), and the published docs only:
+operator actually works** — gate the paid feature first, then prove it end to end with a
+real buyer payment. Use a **scoped, non-master** API key (it carries
+\`payment_providers:write\`), a **sandbox** Keysat instance, and the published docs only:
 
-1. **Connect a BTCPay payment provider** (this box's regtest BTCPay) to Keysat over the
+1. **Define the product + a paid tier that grants an entitlement.** Register the product in
-   API — no master key, no human clicking in a browser. (You hold a BTCPay credential for
+   Keysat's catalog and add a **paid** policy/tier whose purchase grants a named
-   the regtest server, the way an operator delegating setup would hand one to you.)
+   **entitlement** (the thing your gate will check for). Note the entitlement key.
-2. Create a product with a **paid** policy/tier.
+2. **Integrate the SDK and gate the Pro export — verify the BLOCKED path FIRST.** Wire
-3. Produce a **buyer checkout** for that product (a purchase invoice).
+   \`@keysat/licensing-client\` into your app so \`GET /api/export\` returns the CSV **only**
-4. Confirm that paying the invoice issues a license (the harness will pay it on regtest if
+   when the caller holds a valid license carrying that entitlement. Then prove it is shut:
-   you cannot from the docs alone — note where the docs leave that to plumbing).
+   with **no** license and with a **tampered/invalid** license, \`/api/export\` returns a
+   **4xx, not the CSV**. (At this point no real license exists yet — that's expected.)
+3. **Connect BTCPay (regtest) and drive a real buyer payment → license issued.** Connect
+   the regtest BTCPay to Keysat over the API (no master key, no browser — you hold a BTCPay
+   credential the way an operator delegating setup would hand you one). Produce a **buyer
+   checkout** for the paid product, then have the buyer pay it. The settled payment must
+   issue a **real, signed license** carrying the entitlement from step 1. (The harness will
+   pay the regtest invoice for you if the docs leave that last on-chain step to plumbing —
+   note where, but the *checkout* itself must come from the docs.)
+4. **Paste the PURCHASED license into the app → verify the UNLOCKED path.** Feed that
+   purchased license to your app and confirm \`GET /api/export\` now returns the **CSV**.
+   This is the step that ties the two halves together: the license a *buyer's payment*
+   produced unlocks the feature your *gate* protects.
 
-Success = a paid product whose purchase, once settled, yields a valid license — reached
+Success = the same gate that was demonstrably shut in step 2 is opened in step 4 by a
-from the docs alone, under a scoped key, with BTCPay connected by you.
+license that a real (regtest) buyer payment produced in step 3 — reached from the docs
+alone, under a scoped key, with BTCPay connected by you.
 
-## Docs corpus (the ONLY how-to sources)
+## Docs corpus (the ONLY how-to sources you may consult)
-- Keysat docs site: **$DOCS_URL** (start at \`/agent.html\`, \`/integrate.html\`).
+- Keysat docs site: **$DOCS_URL** — start at \`/integrate.html\` (SDK + gating) and
-- Daemon OpenAPI: **$BASE_URL/v1/openapi.json**.
+  \`/agent.html\` (scoped-key + connect-BTCPay workflow); the whole site is in-corpus.
+- Daemon OpenAPI: **$BASE_URL/v1/openapi.json** (unauthenticated; the docs point here).
+- The npm package README for \`@keysat/licensing-client\` is in-corpus (\`npm view\` / the
+  package page).
 
-## Credentials you were handed
+## Your sandbox app (mutate ONLY this)
+\`$SANDBOX\` — a pristine copy of the "Acme Reports" app whose **Pro export**
+(\`GET /api/export\`) is currently ungated. Read its own \`README.md\` freely (it's your
+app; it tells you nothing about Keysat). Deps are installed. Run it with \`npm run dev\`
+(serves on http://localhost:4311). How the app learns the license key (env var, file,
+header) is your call — pick what the docs suggest and note it. Put scratch under
+\`/tmp/onboarding-tester/\`.
+
+## Credentials you were handed (an operator delegating setup would hand you these)
 - Keysat server: **$BASE_URL**
 - Scoped API key (merchant-onboard + payment_providers:write): **$SK**
 - Regtest BTCPay server: **${KEYSAT_LIVE_BTCPAY_URL:-$BTCPAY_URL}**, store
@@ -102,7 +131,9 @@ from the docs alone, under a scoped key, with BTCPay connected by you.
   either an intended operator-only boundary (note it) or a doc gap (log it).
 
 ## Out of corpus (do not open)
-Anything under the Keysat source tree, migrations, tests, or this harness.
+Anything under the Keysat source tree (\`$WORKSPACE/licensing-service-startos\`,
+\`$WORKSPACE/licensing-client-*\`), migrations, tests, or this harness. Reading any of it
+invalidates the run — say so if you do.
 
 ## Output
 Write your friction report to \`$RUN_DIR/reports/friction.md\` AND return it as your final

onboarding-harness/stage2/teardown-stage2.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Full Stage 2 teardown — run when the onboarding test is done so nothing keeps
+# running. Stops, for each Stage 2 run: the ephemeral daemon + docs server +
+# sandbox copy (via the shared teardown.sh); then kills any sandbox dev server
+# the onboarding-tester left behind; then stops the shared regtest BTCPay docker
+# stack (containers + volumes).
+#
+# Usage:
+#   ./teardown-stage2.sh                 # tear down ALL Stage 2 runs + dev servers + BTCPay stack
+#   ./teardown-stage2.sh --keep-btcpay   # same, but leave the BTCPay stack up (iterating)
+#   ./teardown-stage2.sh runs/<id>       # one specific run dir (path relative to onboarding-harness/)
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../lib.sh"
+
+KEEP_BTCPAY=0; ONE_RUN=""
+for a in "$@"; do
+  case "$a" in
+    --keep-btcpay) KEEP_BTCPAY=1 ;;
+    *) ONE_RUN="$a" ;;
+  esac
+done
+
+# 1. Per-run teardown (daemon + docs server + sandbox copy + freed ports).
+if [[ -n "$ONE_RUN" ]]; then
+  "$HARNESS_DIR/teardown.sh" "$ONE_RUN" || true
+else
+  shopt -s nullglob
+  any=0
+  for d in "$RUNS_DIR"/*stage2*/; do
+    [[ -f "${d}state.env" ]] || continue
+    "$HARNESS_DIR/teardown.sh" "${d%/}" || true
+    any=1
+  done
+  [[ "$any" == 0 ]] && warn "no Stage 2 run dirs found under $RUNS_DIR"
+fi
+
+# 2. Kill any sandbox dev server the agent left running. The proof-of-work app
+#    serves on :4311 (npm run dev); the onboarding-tester may start it and not
+#    stop it.
+for pid in $(lsof -ti tcp:4311 -sTCP:LISTEN 2>/dev/null || true); do
+  kill "$pid" 2>/dev/null && log "stopped orphaned sandbox dev server (pid $pid on :4311)" || true
+done
+
+# 3. Stop the shared regtest BTCPay stack (containers + volumes) unless told to keep it.
+if [[ "$KEEP_BTCPAY" == 1 ]]; then
+  ok "left BTCPay regtest stack running (--keep-btcpay)"
+elif docker ps -a --filter "name=keysat-btcpay" --format '{{.Names}}' 2>/dev/null | grep -q .; then
+  ( cd "$HERE/btcpay-regtest" && docker compose -p keysat-btcpay down -v ) >/dev/null 2>&1 \
+    && ok "stopped BTCPay regtest stack (containers + volumes removed)" \
+    || warn "could not fully stop BTCPay — check: docker ps -a --filter name=keysat-btcpay"
+else
+  ok "BTCPay regtest stack already stopped"
+fi
+
+ok "Stage 2 teardown complete"

prepare.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# prepare.sh — bootstrap a clean Debian/Ubuntu box to build the Keysat s9pk.
+#
+# Start9's build-from-source flow clones this repo onto a fresh box, then runs a
+# bootstrap script followed by `make`. This installs every HOST prerequisite that
+# `make` needs (npm → wrapper bundle; start-cli s9pk pack → Docker image build).
+# It mirrors the official StartOS 0.4.0.x environment-setup page:
+#   https://docs.start9.com/packaging/0.4.0.x/environment-setup.html
+#
+# Note: `prepare.sh` is a 0.3.5.x community-submission convention; the 0.4.x docs
+# don't mention it, so the 0.4.x submission flow may not invoke it. This file is
+# still the runnable, single-source record of what a clean build box needs.
+#
+# The Rust daemon is NOT built on the host — it compiles inside this package's
+# Dockerfile (FROM rust:1.88-slim-bookworm), so no rustup/cargo is installed here.
+#
+# Idempotent: re-running skips tools already present. Targets apt-based distros.
+
+set -euo pipefail
+
+# Use sudo only when not already root (Start9's build box may run either way).
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then
+  SUDO="sudo"
+fi
+
+NODE_MAJOR=22
+
+log() { printf '\n\033[1;36m==> %s\033[0m\n' "$*"; }
+
+# --- apt prerequisites -------------------------------------------------------
+# build-essential → make/gcc; squashfs-tools(-ng) → start-cli s9pk packing;
+# jq → used by s9pk.mk's build summary; git → the s9pk embeds the commit hash.
+log "Installing apt prerequisites (make, jq, git, squashfs, curl)"
+$SUDO apt-get update
+$SUDO apt-get install -y --no-install-recommends \
+  build-essential \
+  ca-certificates \
+  curl \
+  git \
+  jq \
+  squashfs-tools \
+  squashfs-tools-ng
+
+# --- Node.js 22 --------------------------------------------------------------
+# The wrapper (@start9labs/start-sdk + @vercel/ncc bundle) needs Node 22. We
+# install it system-wide via NodeSource so it's on PATH for the non-interactive
+# `make` that follows (the docs' nvm method would need a shell rc sourced first).
+if command -v node >/dev/null 2>&1 && node -v | grep -q "^v${NODE_MAJOR}\."; then
+  log "Node.js $(node -v) already present — skipping"
+else
+  log "Installing Node.js ${NODE_MAJOR} (NodeSource)"
+  curl -fsSL "https://deb.nodesource.com/setup_${NODE_MAJOR}.x" | $SUDO -E bash -
+  $SUDO apt-get install -y nodejs
+fi
+
+# --- Docker (+ buildx) -------------------------------------------------------
+# start-cli s9pk pack builds the daemon image from the Dockerfile via Docker
+# buildx. get.docker.com is Docker's official installer and bundles the buildx
+# plugin.
+if command -v docker >/dev/null 2>&1; then
+  log "Docker $(docker --version | awk '{print $3}' | tr -d ,) already present — skipping"
+else
+  log "Installing Docker (official get.docker.com installer)"
+  curl -fsSL https://get.docker.com | $SUDO sh
+fi
+
+# Cross-architecture builds (`make universal` / `make arm` on an x86 host) need
+# QEMU binfmt handlers registered. Best-effort: requires the Docker daemon to be
+# running. Harmless to skip if you only build the host's native arch (`make x86`).
+if $SUDO docker info >/dev/null 2>&1; then
+  log "Registering QEMU binfmt handlers for cross-arch builds (best-effort)"
+  $SUDO docker run --privileged --rm tonistiigi/binfmt --install all ||
+    echo "  (binfmt registration skipped — only native-arch builds will work)"
+else
+  echo "  (Docker daemon not reachable yet — skipping binfmt setup; start Docker"
+  echo "   and re-run this script if you need cross-arch/universal builds.)"
+fi
+
+# --- start-cli (StartOS 0.4.x SDK) -------------------------------------------
+# Official installer: fetches the latest prebuilt binary into ~/.local/bin.
+# For a reproducible build, pin a release instead, e.g.:
+#   curl -fsSLo ~/.local/bin/start-cli \
+#     https://github.com/Start9Labs/start-os/releases/download/<tag>/start-cli_x86_64-linux
+#   chmod +x ~/.local/bin/start-cli
+if command -v start-cli >/dev/null 2>&1; then
+  log "start-cli $(start-cli --version 2>/dev/null | awk '{print $2}') already present — skipping"
+else
+  log "Installing start-cli (StartOS 0.4.x SDK)"
+  curl -fsSL https://start9.com/start-cli/install.sh | sh
+fi
+
+# The installer drops start-cli in ~/.local/bin and appends it to your shell rc.
+# Persist it to .profile for future shells (only if not already recorded, so
+# re-runs don't pile up duplicates), and export it for the rest of THIS session.
+if ! grep -qsF '.local/bin' "${HOME}/.profile"; then
+  echo 'export PATH="$HOME/.local/bin:$PATH"' >>"${HOME}/.profile"
+fi
+export PATH="${HOME}/.local/bin:${PATH}"
+
+log "Done. Initialise your signing key with 'start-cli init', then run 'make' (or 'make x86')."

startos/versions/v0.2.0.ts

@@ -39,7 +39,13 @@ const RELEASE_NOTES = [
 // in RELEASE_NOTES above (the milestone). Subsequent revisions
 // append here.
 const ROUTINE_NOTES = [
-  '0.2.0:57 — **New `merchant-onboard` scoped-API-key role for least-privilege self-serve onboarding.** A fifth scoped-key role sits between `license-issuer` and `full-admin`, granting read access plus `products:write` + `policies:write` + `licenses:write` — the minimum a merchant (or an integrating agent) needs to stand up a catalog end-to-end over the API: create a product, define its policies/tiers, and issue licenses against them, all without holding the master key. The catalog write *scopes* already existed and were enforced on the endpoints since :55; only a role that expands to them was missing, so this is a `Role`-variant addition, not a scope-model change. `Role::grants` matches the write scopes explicitly (never by `:write` suffix), so the role can never widen into settings / payment-provider / merchant-profile / webhook writes, and every master-only operation (signing-key rotation, payment connect, web-admin password, API-key management, server settings, per-license tier change, DB introspection) stays behind `require_admin` and is structurally unreachable from any scoped key. Existing Creator-tier caps still bound it (5 products / 5 policies per product / 10 active codes). **Caveat:** the role covers catalog setup + manual license issuance fully, but connecting a BTCPay/Zaprite payment provider stays master-only by design, so the buyer-paid purchase flow still needs a one-time operator step. Migration 0023 rebuilds `scoped_api_keys` to widen the role CHECK constraint (SQLite can\'t alter a CHECK in place; the table has no foreign keys, so it\'s a plain copy/drop/rename) — additive, a straight drop-in over :56. Daemon api test suite is at 57, up from 56. No SDK change.',
+  '0.2.0:60 — **Fix a Zaprite auto-charge silent-lapse on the recurring-renewal money path.** `charge_order_with_profile` already errors on a non-2xx response (those route correctly to WARN + `auto_charge_failed` audit + manual-pay fallback), but on a 2xx `try_auto_charge_zaprite` returned `Ok(true)` regardless of the order\'s actual status — it read `status` only for a log line. So a 200 carrying a non-settled status (a declined or expired charge, or an in-flight PENDING/PROCESSING) suppressed the manual-pay renewal notification and left the worker waiting for an `order.paid` webhook that never arrives: the subscription silently lapsed, the buyer got no pay link, and the operator saw no error. Fixed by classifying the charge response — the auto-charge is treated as successful (and manual-pay suppressed) only when the order is in a recognized settled state (`PAID`/`COMPLETE`/`OVERPAID`, mirroring `get_invoice_status`\'s `Settled` mapping); any other or unrecognized status logs a WARN and falls through to the existing manual-pay `subscription.renewal_pending` path so the buyer can always recover the cycle. Allowlist by design — Zaprite has no documented terminal-failure status string, so an unknown or missing status is treated as not-settled rather than optimistically assumed paid. Adds a unit test on the new `zaprite_charge_settled` helper covering settled / in-flight / failed / unknown statuses. BTCPay subscriptions and any sub without a saved Zaprite profile are unaffected. Also docs-only: flagged the dormant `merchant_profiles.smtp_*` columns (the buyer-email / SMTP plan was dropped — Keysat does not send email). No schema change, no SDK change — straight drop-in over :59.',
+  '',
+  '0.2.0:59 — **Admin UI: drop the gold button-fill design-contract violations.** Two admin-SPA controls filled with gold, which the brand contract (`design/DESIGN.md`) and the admin-UI pill convention forbid (gold is a marketing accent, never a button fill): the "Featured" tier toggle\'s on-state and the sidebar tier-upgrade CTA. Both now follow the convention — the Featured toggle is navy-filled with a cream pip when on; the upgrade CTA is cream-filled with navy text (the on-brand high-contrast treatment for a primary action on the navy sidebar), and its corner radius is aligned to the 8px button spec. CSS / inline-style only in the embedded `web/index.html` — no schema, no SDK, no behavior change. Straight drop-in over :58. (The matching public-landing fix — the Buy button\'s pill radius set to 8px — ships in the keysat-xyz-landing repo, deployed separately.)',
+  '',
+  '0.2.0:58 — **Agent-delegable BTCPay connect, gated to sandbox + non-mainnet.** Makes Keysat fully agent-operable for *dev/test setup*: an operator can hand an agent a scoped key that connects a BTCPay payment provider over the API — no master key, no browser click — but only on a sandbox daemon and only for a non-mainnet (regtest/testnet/signet) store. On a production daemon, or for a mainnet store, connecting a provider stays master-only, and disconnect is always master-only. The reasoning: a credential that can repoint where settlement lands is a fund-redirection key, so the capability is deliberately narrow and fails closed. **Gated in three layers:** (1) a daemon-level `KEYSAT_SANDBOX_MODE` flag, read at boot and never settable via any API, is the outer gate — scoped connect is disabled entirely on a production box; (2) `payment_providers:write` is an à-la-carte per-key scope that belongs to no role (not even full-admin), granted explicitly when an operator mints a key; (3) at OAuth-callback time the daemon resolves the target store\'s Bitcoin network from its on-chain receive address and refuses anything not provably non-mainnet, failing closed to mainnet on any ambiguity (no on-chain wallet, unreachable BTCPay, unrecognized address) — it denies rather than guesses. Migrations 0024 (`scoped_api_keys.extra_scopes`) and 0025 (`btcpay_authorize_state.scoped_initiator` + actor hash, to carry the initiator across the browser round-trip) are additive — straight drop-in over :57. The served OpenAPI spec now documents the BTCPay connect/callback/status/disconnect paths and the key-creation `scopes` field, and `/v1/admin/tier` surfaces a read-only `sandbox` flag. Also hardened: the GET authorize-callback now returns the real HTTP status on a denied connect (was a misleading 200 with an error page). Validated end-to-end against a live regtest BTCPay; the docs-onboarding harness (a fresh agent integrating from the published docs alone) converged completed-clean on the full buyer-pays journey. Daemon api test suite is at 65, up from 57. Zaprite connect stays master-only. No SDK change.',
+  '',
+  '0.2.0:57 —**New `merchant-onboard` scoped-API-key role for least-privilege self-serve onboarding.** A fifth scoped-key role sits between `license-issuer` and `full-admin`, granting read access plus `products:write` + `policies:write` + `licenses:write` — the minimum a merchant (or an integrating agent) needs to stand up a catalog end-to-end over the API: create a product, define its policies/tiers, and issue licenses against them, all without holding the master key. The catalog write *scopes* already existed and were enforced on the endpoints since :55; only a role that expands to them was missing, so this is a `Role`-variant addition, not a scope-model change. `Role::grants` matches the write scopes explicitly (never by `:write` suffix), so the role can never widen into settings / payment-provider / merchant-profile / webhook writes, and every master-only operation (signing-key rotation, payment connect, web-admin password, API-key management, server settings, per-license tier change, DB introspection) stays behind `require_admin` and is structurally unreachable from any scoped key. Existing Creator-tier caps still bound it (5 products / 5 policies per product / 10 active codes). **Caveat:** the role covers catalog setup + manual license issuance fully, but connecting a BTCPay/Zaprite payment provider stays master-only by design, so the buyer-paid purchase flow still needs a one-time operator step. Migration 0023 rebuilds `scoped_api_keys` to widen the role CHECK constraint (SQLite can\'t alter a CHECK in place; the table has no foreign keys, so it\'s a plain copy/drop/rename) — additive, a straight drop-in over :56. Daemon api test suite is at 57, up from 56. No SDK change.',
   '',
   '0.2.0:56 — **Product→merchant-profile write path — multi-profile is now functional end-to-end.** The multi-profile *resolver* has been complete since :52, but products had no way to be *assigned* to a profile, so every product stuck to the auto-created default profile. This cut wires the missing write half. `Product.merchant_profile_id` now threads through all four product SELECTs + `row_to_product`; a new `repo::set_product_merchant_profile` validates the target profile exists first (returns a clean 404 rather than a raw FK 500); it is threaded through `CreateProductReq` (applied as a post-write step) and `UpdateProductReq` (double-`Option` semantics, where `Some(None)` clears a product back to the default profile). The admin SPA shows a merchant-profile `<select>` on the product form only when more than one profile exists, so single-profile operators see no change. No schema migration (highest is still 0022) — straight drop-in over :55. No SDK change.',
   '',
@@ -530,7 +536,7 @@ const ROUTINE_NOTES = [
 ].join('\n\n')
 
 export const v0_2_0 = VersionInfo.of({
-  version: '0.2.0:57',
+  version: '0.2.0:60',
   releaseNotes: { en_US: ROUTINE_NOTES },
   // No on-disk transformation needed — v0.2.0:0 is a label change.
   // SQLite-level migrations live separately under