Initial backup of root workspace files

Glue files not covered by subproject repos: top-level docs, logo,
keysat-design-system, and crosscheck tests. Subproject folders are
gitignored (each has its own Gitea remote).

BUILDING.md

@@ -0,0 +1,99 @@
+# Building and sideloading Keysat
+
+This repo ships three components that you'll bundle into a single installable `.s9pk`:
+
+- `licensing-service/` — the Rust daemon (`keysat` binary).
+- `licensing-service-startos/` — the StartOS 0.4.0.x wrapper (TypeScript manifest + actions + Dockerfile).
+- `licensing-client-rust/` and `licensing-client-ts/` — SDKs for downstream software. Not bundled into the `.s9pk`; published separately when you cut a release.
+
+The Rust service's on-disk folder name is still `licensing-service/` for continuity, but the crate, binary, and operator-visible branding are all **Keysat** now.
+
+## Prerequisites
+
+1. A working **StartOS 0.4.0.x development environment** on a Linux or macOS workstation. Follow [docs.start9.com](https://docs.start9.com) if you haven't set this up yet.
+2. `start-cli` installed on your PATH, with `~/.startos/developer.key.pem` initialised (`start-cli init`).
+3. **Node 20+** (for the StartOS SDK, TypeScript).
+4. **Docker + buildx** (for multi-arch image builds).
+5. Network reachability from your workstation to your Start9 server (LAN or Tor — whatever you usually use to `start-cli install`).
+6. A running **BTCPay Server** on the same Start9 server (Keysat depends on it).
+
+You do **not** need Rust locally — the Dockerfile pulls a pinned `rust:1.75-slim-bookworm` image.
+
+## One-time setup
+
+### 1. Fetch the shared build logic
+
+Every 0.4.0.x wrapper includes `s9pk.mk`, which is maintained by the Start9 team. Fetch the current copy once:
+
+```bash
+cd licensing-service-startos
+curl -o s9pk.mk https://raw.githubusercontent.com/Start9Labs/hello-world-startos/master/s9pk.mk
+```
+
+The `Makefile` `include s9pk.mk` line will error out until that file is in place.
+
+### 2. Install TypeScript deps
+
+```bash
+cd licensing-service-startos
+npm install
+```
+
+## Building
+
+From `licensing-service-startos/`:
+
+```bash
+# Build for all supported architectures (x86_64 + aarch64)
+make
+
+# Or just the architecture your Start9 box runs
+make arm        # Raspberry Pi / Apple Silicon
+make x86        # x86_64 StartOS server
+```
+
+The resulting artifact lands in `licensing-service-startos/*.s9pk` — a single file you can sideload.
+
+## Sideloading
+
+```bash
+cd licensing-service-startos
+make install
+```
+
+This uses your `~/.startos/developer.key.pem` to push the package to the Start9 server it's registered against. First-run prompts for the Start9 dashboard password; subsequent installs reuse the cached session.
+
+If you prefer to upload the `.s9pk` through the StartOS dashboard UI, copy the file off your workstation and drag it into **Sideload package** from the dashboard.
+
+## First-boot checklist
+
+Once installed, open **Keysat** in your StartOS dashboard and run these actions in order:
+
+1. **Set operator name** — your display name, shown on the public homepage.
+2. **Connect BTCPay** — opens a BTCPay consent page in your browser. Click Authorize; Keysat auto-detects your store and registers its inbound webhook.
+3. **Check BTCPay connection** — confirms the authorize completed and the webhook is live.
+4. **Create product** — one per thing you plan to sell.
+5. **Create policy** — at least one per product, slugged `default`. Sets the shape of keys issued through the public purchase flow.
+
+At this point your buyers can `POST /v1/purchase` against your Keysat URL, pay via BTCPay, and poll back for their license key.
+
+## Testing it end-to-end
+
+Keysat ships with a cross-check test suite that independently signs license keys with a Python reference implementation and replays them through the Rust and TypeScript SDK parsers. See `tests/crosscheck/README.md`.
+
+The simplest smoke test against a live install:
+
+```bash
+# On your workstation, once the service is running on StartOS:
+curl https://<your-keysat-url>/v1/pubkey
+curl https://<your-keysat-url>/healthz
+```
+
+The first returns the Ed25519 public key you'll bake into downstream software. The second should just return `{"ok":true}`.
+
+## Troubleshooting
+
+- **"KEYSAT_ADMIN_API_KEY must be at least 32 characters"** — shouldn't happen from StartOS (the wrapper generates the key), but if you're running locally, `openssl rand -hex 32` gives a valid value.
+- **"BTCPay not yet configured — purchases will return 503"** — run **Connect BTCPay** from the StartOS dashboard.
+- **Rebuilds don't reflect Rust source changes** — Docker layer caching is aggressive; `make clean` before `make` to force a full rebuild.
+- **Existing installs using `LICENSING_*` env vars** — the daemon still reads those as a fallback for one release cycle. New installs set `KEYSAT_*` directly.