keysat-root/ROADMAP.md

# ROADMAP — Keysat

Longer-term backlog. Near-term state lives in `AGENTS.md` → Current state.

## Payments & subscriptions

- Rail-preference editing UI — only matters when two providers on one profile both serve the same rail; settable today via `PUT /v1/admin/merchant-profiles/:id/rail-preferences/:rail`.
- **Auto-charge silently lapses a subscription on a 200-with-failure response (money-path bug; elevated above the other parked payments items).** `try_auto_charge_zaprite` returns `Ok(true)` on *any* HTTP 2xx (`subscriptions.rs:1403-1410`), reading the order `status` only for a log line. If Zaprite returns 200 carrying a `FAILED`/`DECLINED`/`EXPIRED` order status, the daemon fires `auto_charge_initiated` and then waits for an `order.paid` webhook that never arrives — the subscription silently lapses, no error surfaced, the customer churns. Safe fix (no production data needed): treat any non-`PAID` terminal order status as not-success and fall through to the manual-pay path — a conservative fail-safe, ~10 lines + a mock-provider test. (Found during the 2026-06-17 adjudication; it replaces the old "harden Zaprite failure-body shapes" item, which was already satisfied for non-2xx responses — those route correctly to WARN + `auto_charge_failed` audit + webhook + manual-pay fallback.)
## Agent compatibility & scoped API keys

- **Agent-delegable payment-provider connect** (approved, not urgent — see
  `plans/agent-payment-connect-scope.md`). Add an à-la-carte `payment_providers:write` scope
  (never bundled into `merchant-onboard`), gated by a daemon-level **sandbox-mode flag** as the
  outer gate (production daemons reject scoped connect entirely) with a **network gate** inner
  defense (regtest/testnet/signet only, fail-closed to mainnet). BTCPay network is derived from
  an on-chain address prefix (no `server/info` field exists).
- **Onboarding doc-harness — Stage 2 (Path 2, regtest buyer-pays).** Gated on slices 3–5 above.
  Stage 1 (Path 1, no payments) shipped `completed-clean` this session — harness at
  `licensing-service-startos/onboarding-harness/`, record in its `STAGE1-RESULT.md`. Stage 2
  reuses the harness but boots the fixture with `KEYSAT_SANDBOX_MODE` on, stands up a Dockerized
  BTCPay regtest stack (bitcoind regtest + NBXplorer + Postgres + BTCPay) as additional
  disposable infra, and grants the agent `merchant-onboard` + `payment_providers:write`. Goal:
  the agent connects BTCPay (regtest) over the API and drives a test buyer payment that activates
  a license, with zero master-key steps. The walkthrough must be explicitly labeled
  regtest/test-network and must state that connecting a real mainnet wallet is the one
  operator-reserved step **by design** (a key that can redirect funds stays with the human) — a
  security feature, not a gap.

## Packaging & distribution

- **Start9 Community Registry submission** — **operator-owned** (Grant handles the Start9 communication
  directly; not an agent task; kept here as reference only). Mechanism (researched 2026-06-18): **email-based,
  not a PR or form.** Mail `submissions@start9labs.com` (the 0.3.5.x docs say `submissions@start9.com` — addresses are
  inconsistent) a link to the public wrapper repo (+ detailed README); both wrapper and upstream source must
  be public. Start9 snapshots the repo, **builds from source on a clean Debian box** (`prepare.sh` + `make`; a
  failed first build bounces the submission), installs + tests on real hardware (metadata, install/uninstall,
  interfaces, health, backup/restore, low-resource device), lands it in Community **Beta**, and promotes to
  production when you reply asking. Updates follow the same loop. `start-cli s9pk publish` is **self-hosted-registry
  only** — unrelated to community intake. `prepare.sh` shipped this session (`licensing-service-startos/prepare.sh`).
  **Clear with Start9 before submitting:** (1) is the custom source-available `LicenseRef-Keysat-1.0` acceptable
  (docs conflict: "source available" vs "Open Source License") — highest-leverage; a hard No blocks regardless of
  build-readiness; (2) does the 0.4.x build flow still invoke `prepare.sh` (a 0.3.5.x concept, absent from 0.4.x
  docs). Then the on-box manual verification. Functional criteria otherwise pass (2026-06-17 spec check).
- **Registry version retention** — does the self-hosted registry need to keep every prior version of the keysat
  s9pk as we upgrade, or can superseded versions be pruned? Research-agent to investigate StartOS registry
  version-retention semantics + storage implications. (Captured 2026-06-16.)

## Operability & alerts

- **Surface internal failure conditions to the operator via StartOS-native notifications / health checks** —
  NOT a bespoke email/SMTP subsystem. The need is real and not covered by the webhook-delegation model: when
  the failure IS the webhook path (a dead-lettered endpoint, or the operator's receiver being down), a webhook
  can't report it, and the operator's own email pipeline is downstream of the same webhooks. So Keysat must own
  an out-of-band operator-visible channel — and on StartOS that channel is the OS notification/health surface,
  not a mailer Keysat ships itself. Conditions worth alerting on (the surviving kernel of the dropped email plan):
  payment-provider auth dead (repeated 401s ⇒ key revoked/rotated), a webhook endpoint hitting dead-letter,
  master self-license expiring-soon / expired, and (optional) renewals failing across the pool. The health-check
  path is already wired; verify the `start-sdk` 1.3.2 notification API before committing to a delivery mechanism.
  Background + the original alert catalog (Tier 1/2/3, throttling) live in the superseded
  `plans/keysat-smtp-emails.md`. **Buyer-facing email and the per-profile SMTP send path are dropped** (decided
  2026-06-18): operators selling via Keysat already own their buyer relationship and email pipeline through their
  own app + the existing webhooks, so Keysat emailing buyers is redundant and a branding/double-send liability.
  The dormant `merchant_profiles.smtp_*` columns (migration 0020) are now dead weight — left in place (a removal
  migration isn't worth it) and flagged in `src/merchant_profiles.rs`.

## Security & hardening (2026-06-18 full-eval P2s; EVALUATION.md has full detail but is overwritten each run, so the durable list lives here)

- **X-Forwarded-For rate-limit bypass.** Login/recover/validate buckets key off the raw first XFF value
  (`api/auth.rs:137`, `api/recover.rs:65`, `api/admin.rs:63`, `api/validate.rs:95`); rotating XFF defeats the
  throttle. First confirm whether the StartOS front proxy overwrites XFF (decides real-world reachability), then
  derive client IP from the trusted-proxy connection with a peer-socket fallback.
- **Dependency advisories** (mechanical, low-risk): bump `sqlx 0.7.4` → ≥0.8.1 (RUSTSEC-2024-0363),
  `rustls-webpki 0.101.7` → ≥0.103.13 (RUSTSEC-2026-0098/0099/0104), update start-sdk for the wrapper's
  `fast-xml-parser` (GHSA-5wm8-gmm8-39j9); re-run `cargo audit` / `npm audit`.
- **Admin UI co-located with the public API** on the single `:8080` interface (`startos/interfaces.ts`) — operator
  can't network-isolate admin. Split the admin SPA + `/v1/admin/*` onto their own port/interface.
- **Webhook-endpoint registration accepts `file://` / loopback URLs** (`webhooks.rs:106`, admin-gated) — add a
  scheme + host allowlist (reject non-http(s), loopback, link-local).
- **Runtime-prepared SQL** in `db/repo.rs` + `subscriptions.rs` (no compile-time column check; this class already
  500'd every paid purchase once on `:52`) — migrate the money-path queries to compile-checked `sqlx::query!`.
- **`rate_buckets` grows unbounded** (`rate_limit.rs:63`, one row per client IP on a public endpoint, no reaper) —
  add a reaper mirroring the session/redemption reapers in `main.rs`.
- **No CI.** Stand up one job (`cargo test && cargo clippy && tsc --noEmit`, ideally `cargo fmt --check`); the suite
  is good but unenforced, so green depends on the operator remembering to run it before `publish.sh`.
- Doc-drift P3 cluster (each one-liners, see EVALUATION.md): BUILDING.md Node 20→22 / Rust 1.75→1.88, broken docs
  `/changelog` footer link, README "Show credentials" → "Show admin API key", PORTING_SDK stale (Python/Go shipped;
  crate renamed), testing.md stale test counts, and the `unlimited_merchant_profiles` guide/code-comment ("still
  needs adding") vs AGENTS ("confirmed live") contradiction — resolve with a live `GET /v1/products/keysat/policies`.

## Licensing model

- Evaluate Elastic License v2 vs the current custom `LicenseRef-Keysat-1.0` (parked decision).

## Validation

- Re-test `KEYSAT_INTEGRATION.md` against a fresh downstream app to confirm a clean one-shot SDK integration.
- **Add an automated regression test for multi-profile webhook routing** (adjudicated 2026-06-17 → DO, low blast radius — replaces the parked "manual Zaprite sandbox pass"). The routing is a deterministic provider-id→profile primary-key lookup with an anti-forgery re-fetch backstop, so the manual sandbox ceremony isn't worth it — but the path-keyed route (`/v1/{provider}/webhook/:provider_id` → `handle_for_provider`) currently has zero automated coverage on the money path. Plan: in `tests/api.rs`, reuse the two-provider fixture (~:3958), POST a Settled webhook to `/v1/zaprite/webhook/{provider-A-id}`, assert only profile A settles (B untouched; an unknown path-id 404s). Existing mock seam, no external account, runs in `cargo test`. Effort S.

## Design (contract conformance)

- **Design-contract cleanup from the 2026-06-16 design-checker audit** (re-run design-checker after to confirm).
  Detail also in `design/DESIGN.md`.
  - **3 blockers** — code violates the contract's named "never" rules on live CTAs: (a) gold-as-fill on admin
    `.featured-pill-toggle.on` (`licensing-service-startos/licensing-service/web/index.html:418`) → navy fill or
    gold border+text; (b) gold-as-fill on admin `#tier-banner-cta` upgrade button (`web/index.html:537-542`) →
    navy primary; (c) primary buy CTA pill radius `999px` (`keysat-xyz-landing/index.html:384-385`) → `r-md` 8px.
  - **Structural** — consolidate the 4 surfaces' inlined CSS-variable copies onto canonical
    `design/brand/palette.css` (import it, drop the private copies).
  - **Token gaps** (tokenize-vs-snap) — 14px landing card radius; wordmark letter-spacing 0.30 vs 0.28em (add a
    `letterSpacing.wordmark` token); semantic badge text one-offs (`#205c47`/`#7a5814`/`#8a2828`); hardcoded
    syntax-highlight hex → `var()`; admin `#f6f1e7` off-token.

## Admin UI

- **Reorder the entitlements catalog** from the edit-products view (admin SPA). (Captured 2026-06-18.)

## Code health / refactoring (from the 2026-06-19 refactor-scout test drive)

- **Delete 3 confirmed-dead functions** (clippy + grep confirm zero callers): deprecated payment shims
  `read_/write_active_provider_preference` (`src/payment/mod.rs:59-102`), unwired `_audit_payload`
  (`src/upgrades.rs:607`), unused `BtcpayClient::store_id` (`src/btcpay/client.rs:172`).
- **`db/repo.rs` column consts** — extract `PRODUCT_COLS` (lines 17-46, repeated 4×) and `INVOICE_COLS`
  (516-518, 2×) named consts to match the `*_COLS` convention every other entity already uses; test-covered by
  `tests/api.rs` so low risk.
- **Large-function splits — DEFER, each gated on writing characterization tests FIRST:** `buy_page::render()`
  (~1070 lines, `src/api/buy_page.rs:35`), `subscriptions::renew_one()` (~370 lines, money-critical worker),
  and the `db/repo.rs` god module (~3422 lines, split along its existing section-comment headers).