keysat-root/AGENTS.md

AGENTS.md — Keysat workspace

Self-hosted, Bitcoin-native software licensing service running as a StartOS 0.4.x package, with four wire-compatible SDKs and a public landing/docs site.

This file holds whole-repo, every-session facts. Subsystem detail lives in scoped guides under docs/guides/ (symlinked to .claude/rules/ so Claude Code auto-loads each when you edit matching files). Before editing a subsystem, read its guide — see the index below.

Stack

• Daemon: Rust 1.88, axum, sqlx + SQLite, Ed25519 signing.
• Wrapper: TypeScript, @start9labs/start-sdk ^1.3.2, @vercel/ncc bundle, Node 22.
• SDKs: TS (npm), Rust (crates.io), Python (PyPI), Go (proxy.golang.org).
• Platform: StartOS 0.4.0.x (LXC under the hood — commands/paths reflect that, not Docker).
• Payment providers: BTCPay Server (required dep); Zaprite (optional, gated by zaprite_payments).

Subsystem guides (read before editing the area)

• Before editing the daemon source, read docs/guides/daemon-architecture.md.
• Before editing payment / provider / merchant-profile code or migrations 0020–0022, read docs/guides/payments.md.
• Before touching self-license or tier-gating code, read docs/guides/licensing-tiers.md.
• Before changing the LIC1 wire format, crypto, or crosscheck fixtures, read docs/guides/crypto-wire-format.md.
• Before building, bumping the version, or editing the StartOS wrapper, read docs/guides/startos-packaging.md.
• Before editing the admin SPA (web/index.html), read docs/guides/admin-ui.md.
• Before editing public site/docs copy, read docs/guides/website-copy.md.
• Before adding/altering tests or relying on lint/CI, read docs/guides/testing.md.

Build / test / run (quick ref)

From licensing-service-startos/: make x86 | make arm | make universal | make install | make clean | npm run check. From licensing-service-startos/licensing-service/: cargo check | cargo build --release | cargo test | cargo test --test <suite> | cargo test <name>. Details, the version-bump-before-build rule, and release scripts: docs/guides/startos-packaging.md. Test suites, the no-CI / formatting-not-enforced status, and known-failing tests: docs/guides/testing.md.

Directory layout

licensing-service-startos/        daemon + StartOS wrapper (s9pk package source)
  licensing-service/src/          Rust daemon            → guides/daemon-architecture.md
  licensing-service/migrations/   SQLite migrations (numbered, additive)
  licensing-service/web/index.html  embedded admin SPA   → guides/admin-ui.md
  licensing-service/tests/        integration suites     → guides/testing.md
  startos/                        wrapper TS             → guides/startos-packaging.md
  Dockerfile  Makefile  s9pk.mk   build pipeline
keysat-xyz-landing/ keysat-docs/ keysat-registry-landing/   public sites → guides/website-copy.md
licensing-client-{rust,ts,python,go}/  the four SDK source repos
activate-license-template/        Tauri desktop template for license activation
keysat-design-system/             design tokens / brand assets
plans/                            design specs (multi-provider-payment-model.md, keysat-smtp-emails.md)
tests/crosscheck/                 cross-language LIC1 verifier → guides/crypto-wire-format.md

Note: the daemon (licensing-service-startos, repo keysat), each SDK, and plans/ are separate git repos — commit code/plan changes in their own repo. The root Licensing repo (keysat-root) tracks only AGENTS.md + docs/guides/

• .claude/rules/ + EVALUATION.md (the latest full-eval report; overwritten each run, history in git log). Remotes differ per repo: the daemon's main tracks GitHub (origin, the public upstream) with a gitea backup — plain git push goes to GitHub, so also git push gitea main; root + plans are Gitea-only. Run git remote -v (full) and check what the branch tracks before pushing.

Conventions (whole-repo)

• Daemon licensed LicenseRef-Keysat-1.0 (custom, source-available); SDKs MIT.
• Commits in imperative mood, body only when the "why" isn't obvious. Sign as Keysat (Grant), not Claude — git user is Keysat.
• Direct push to main + run ~/.keysat/publish.sh is the authorized release flow until launch.
• Never rewrite user-facing copy outside the explicit scope of a request.

Never

• No AI co-authorship on commits or PRs (no "Co-Authored-By", no "Generated with…").
• Don't push --no-verify or bypass hooks unless explicitly authorized.
• Don't commit built artifacts (*.s9pk, keysat-*.s9pk, javascript/) or secrets — reference env-var names; real values live in ~/.keysat/filebrowser.env and /data/keysat-license.txt outside the repo.

Memory references

Operator-specific memories at ~/.claude/projects/-Users-macpro-Projects-licensing-Licensing/memory/ (scan before a major change): keysat_release_workflow.md, no_unauthorized_copy_changes.md, keysat_admin_ui_pill_convention.md, startos_lxc.md, startos_registry_icon_unrenderable.md, keysat_open_threads.md.

Open TODOs

• Verify the universal multi-arch publish end-to-end: publish.sh now runs make universal (one keysat.s9pk, both arches) instead of x86-only; the first real publish must confirm the registry index lists both arches. riscv target unverified (not in the manifest, so make universal excludes it).
• StartOS Community Registry submission criteria — Start9 hasn't published the checklist; reach out directly when ready.
• Registry icon doesn't render in the StartOS marketplace (see guides/startos-packaging.md).
• Split audit:read out of the blanket :read scope into its own tier so a Read-only scoped key can read dashboards/licenses but NOT the full audit log (api/api_keys.rs::Role::grants). Deferred from the scoped-keys session.
• Build the admin SPA "API keys" management panel (create w/ role picker, list, revoke) — backend is wired; UI deferred to a design-focused session.

Current state (2026-06-13)

• Live: server immense-voyage.local runs daemon 0.2.0:54 (migrations 0020–0022). Registry registry.keysat.xyz publishes :54; four SDKs published; keysat.xyz + docs.keysat.xyz deployed. Prod is still :54 — the prior session's two P1 fixes are committed to source but NOT yet built/installed/ published. Next release builds :55.

• This session (UNCOMMITTED across 4 repos; docs + StartOS packaging, no daemon logic changed) — doc-auditor + start9-spec-checker + 2 reviewer passes, all approved/no blockers; tsc + bash -n clean. By repo:

  • root (Gitea): testing.md api 47→54; payments.md FK confirmed (db/mod.rs:29); startos-packaging.md + this block updated for universal publish; licensing-tiers.md gained the "no enforce mode / Creator caps" note.
  • keysat-docs (Gitea): integrate.html phantom GET /v1/licenses/{id}/status → real POST /v1/validate w/ key. Needs deploy-sites.sh docs to go live.
  • keysat daemon (GitHub+gitea): new instructions.md (Start9-required); manifest packageRepo + docsUrls[1] dead-link fixes; v0.2.0.ts stale-header removed; activateLicense.ts/showCredentials.ts enforce-mode drift cleaned (enforce retired — self_license.rs:15).
  • go SDK (Gitea): README v0.1→v0.2.
  • operator-local ~/.keysat/publish.sh (gitignored, NOT committed): x86-only → make universal (one keysat.s9pk, both arches). Pending a verification build. All 4 StartOS submission blockers now addressed. Left for operator decision: integrate.html BTCPay-only prereq/refund copy (no Zaprite mention). Commit = 4 per-repo commits (root, keysat-docs, go SDK are Gitea-only; daemon is GitHub+gitea — also git push gitea main).

• :52/:53 = multi-provider/merchant-profile model: data model + backend resolution shipped and audited sound; resolution/CRUD query surface has tests. Both :54 P0s (provider-injection test seam; Zaprite webhook-forgery re-confirm) remain fixed; live purchase + settle paths sound.

• Unshipped source work (awaiting :55) — two P1s from the prior session:

  1. Settle-amount tripwire. get_invoice_status now returns ProviderInvoiceSnapshot { status, amount }; audit_settle_amount (shared by webhook + reconcile issue paths) WARNs + writes an invoice.amount_mismatch audit row on drift, then issues anyway (advisory, not a gate — a hard gate would fight BTCPay payment tolerance). SAT-only: skips non-SAT (fiat sub renewals) and None. Reviewed (caught + fixed a fiat-renewal false-positive). See docs/guides/payments.md.
  2. Scoped API keys wired. 58 admin endpoints migrated require_admin→ require_scope; 12 sensitive ones stay master-only (issuer key, provider connect/disconnect, set-password, api-key CRUD, db-info, operator-name, per-license tier change). require_scope re-exported from api::admin. Role boundary tests added. Boundary documented in api/api_keys.rs module doc.

• GAP — multi-profile still non-functional end-to-end: nothing writes products.merchant_profile_id (INSERT in create_product_with_currency omits it; update_product_with_currency has no field; Product in models.rs lacks it). Resolver fully supports it; only the product→profile write path is missing. Gating piece for multi-profile.

• Work queue (next, in order):

  1. product→merchant-profile picker (the GAP — add merchant_profile_id to Product + repo.rs SELECT; set_product_merchant_profile writer mirroring set_product_entitlements_catalog; field on CreateProductReq/ UpdateProductReq applied post-write; profile <select> from GET /v1/admin/merchant-profiles, shown only when >1 profile; no migration).
  2. 3 other deferred UIs (rail picker, per-profile SMTP, rail-pref editor); unlimited_merchant_profiles on master Pro/Patron policies.
  3. Deferred this session (now in Open TODOs): split audit:read out of the blanket :read scope; build the admin "API keys" management SPA panel.

• Known debt (P2 — schedule, not urgent): no rate-limit on /v1/purchase + /v1/redeem; rate-limit bucket keys on spoofable X-Forwarded-For (bypass conditional on whether the StartOS proxy rewrites XFF — unverified); 422/415 errors return plain-text not JSON (breaks SDK JSON.parse); product slug has no validation (empty/300-char/meta chars stored); GET /v1/admin/products returns 405 though OpenAPI documents it; dep advisories (sqlx→≥0.8.1 RUSTSEC-2024-0363, rustls-webpki→≥0.103.12); 4 StartOS submission blockers (spec-checker-verified) all addressed and staged, pre-build — manifest packageRepo (…/keysat-startos→…/keysat) and docsUrls[1] (docs/INTEGRATION.md→KEYSAT_INTEGRATION.md, the real repo-root file) fixed; instructions.md written (reviewer + doc-auditor signed off); aarch64 now shipped via publish.sh make universal (one s9pk, both arches — pending a verification build); no CI + fmt/clippy/prettier unenforced.

• Deferred (P3+ — bulk or later decision): /v1/purchase 400 vs /v1/btcpay/webhook 503 for the same no-provider cause; undocumented required kind on discount-codes; field-naming drift (license_id/id, machines key vs license_key, redeem/purchase product vs validate product_slug); migration self-heal _sqlx_migrations allowlist foot-gun; 2 KB unauth Zaprite payload WARN-log; outbound-webhook SSRF (operator-only); re-register the master Zaprite webhook at the path-keyed URL; registry icon non-render (known platform limit); optional fmt/prettier standalone commit.

• Tests/build: cargo check clean (1 intentional deprecation warning); full suite green — api 54 (incl. new settle-tripwire + scoped-key role-boundary tests), subscriptions 7, upgrades 9, worker 3, crosscheck 4, migrations 9. No new clippy warnings. FK enforcement confirmed — sqlx pool sets foreign_keys(true) per connection (db/mod.rs). CI/fmt status is in Known debt.