Keysat
255d669cf0
Refresh AGENTS Current state for the full-eval session; document the email-based community-registry submission flow and the start-cli installer in the packaging guide; add a ROADMAP Security & hardening section so the eval P2s survive EVALUATION.md overwrites.
131 lines
8.6 KiB
Markdown
131 lines
8.6 KiB
Markdown
# 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, the scoped-connect gate, or migrations 0020–0022 + 0024–0025, 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 building or changing any user-facing UI (landing, docs, admin SPA), read `design/DESIGN.md` and `design/tokens.tokens.json` and conform to them** — the brand contract; pull colors/type/space/radii/shadows from the tokens, never hardcode off-scale values.
|
||
- 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
|
||
onboarding-harness/ docs-onboarding test rig → onboarding-harness/README.md
|
||
Dockerfile Makefile s9pk.mk build pipeline
|
||
keysat-xyz-landing/ keysat-docs/ public sites → guides/website-copy.md
|
||
licensing-client-{rust,ts,python,go}/ the four SDK source repos
|
||
activate-license-template/ StartOS license-activation wrapper template (drop-in actions)
|
||
design/ design contract (DESIGN.md + tokens.tokens.json) + brand/ assets; original Claude Design system archived in design/_imports/
|
||
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-keysat/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
|
||
|
||
- `riscv` build target is unverified and not declared in the manifest; the wrapper `Makefile`
|
||
now pins `ARCHES` to `x86 arm` so no target (even a bare `make`) attempts it. Revisit only if
|
||
a riscv StartOS target appears.
|
||
- StartOS Community Registry submission — `prepare.sh` shipped (2026-06-18). Submission is
|
||
**email-based** (no PR, no form): mail `submissions@start9labs.com` a link to the public wrapper
|
||
repo; Start9 builds-from-source on a clean box → Community Beta → production-on-reply. Resolve two
|
||
unknowns with Start9 *before* submitting: (1) source-available `LicenseRef-Keysat-1.0` acceptability,
|
||
(2) whether the 0.4.x build still invokes `prepare.sh`. On-box manual verification still pending. Detail in ROADMAP.
|
||
- 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.
|
||
|
||
## Current state (2026-06-18)
|
||
|
||
- **Live / canonical: `0.2.0:60`** — universal s9pk at `files.keysat.xyz/keysat.s9pk` (byte-verified) + GitHub
|
||
release `v0.2.0-60` + registry-registered; installed on the live box `immense-voyage.local` and serving
|
||
(master `licensing.keysat.xyz` returns 200 post-restart). Migrations through 0025; four SDKs published; two
|
||
public sites (keysat.xyz, docs.keysat.xyz) live. All repos synced to **both** GitHub + gitea.
|
||
`keysat-registry-landing` remotes deleted by the operator.
|
||
|
||
- **This session — full eval + three P1 fixes (all committed & pushed).** Ran the five-agent `/full-eval`
|
||
(evaluator, security-auditor, exerciser, doc-auditor, start9-spec-checker); report in `EVALUATION.md`
|
||
(no P0s; strong crypto/auth/webhook posture). Fixed all three P1s: (1) crosscheck harness `run_ts.mjs`
|
||
hardcoded `/sessions/...` path → resolves relative to repo (keysat-root); (2) Rust SDK + `keysat-docs`
|
||
imported `licensing_client` not `keysat_licensing_client` — fixed, plus two latent bugs it masked (example's
|
||
undeclared `anyhow` → stdlib; doctest `include_str!` of a missing file → inline PEM); (3) added
|
||
`licensing-service-startos/prepare.sh` clean-Debian build bootstrap. Reviewer-approved; verified green.
|
||
- **Registry submission mechanism researched.** Email-based (no PR/form) — see Open TODOs + ROADMAP. Two
|
||
blocking unknowns to clear with Start9 first: license acceptability + whether 0.4.x still uses `prepare.sh`.
|
||
- **Prior context still current:** `:60` Zaprite silent-lapse fix shipped; Keysat sends no buyer email
|
||
(SMTP path dormant); docs reconciled; `unlimited_merchant_profiles` live on Pro+Patron (not Creator).
|
||
- **Next (priority):** 1) email Start9 re: license + 0.4.x build flow (gates the whole submission). 2) eval
|
||
P2 hardening — XFF rate-limit bypass, dep-advisory bumps, admin/public port split (ROADMAP "Security &
|
||
hardening"). 3) automated multi-profile webhook routing test (Effort S). 4) split `audit:read` scope.
|
||
- **Tests/build:** daemon `cargo test` ~117–131 green across 8 suites; wrapper `tsc` clean; Rust SDK
|
||
`cargo build --examples` + doctest now green; crosscheck harness passes end-to-end. No CI enforces any of it.
|