Update docs to match the 0.2.0 daemon (admin-UI actions, runtime image, Zaprite, roles)
This commit is contained in:
Grant
+20
-37
@@ -56,44 +56,21 @@ See [`src/crypto/mod.rs`](src/crypto/mod.rs) for the exact byte layout.
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
licensing-service/
|
||||
├── Cargo.toml
|
||||
├── LICENSE # source-available; no redistribution
|
||||
├── README.md
|
||||
├── .env.example # required env vars
|
||||
├── migrations/
|
||||
│ └── 0001_initial.sql # SQLite schema
|
||||
├── src/
|
||||
│ ├── main.rs # entry point: wires everything
|
||||
│ ├── config.rs # env-driven config
|
||||
│ ├── 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
|
||||
```
|
||||
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):
|
||||
|
||||
- `main.rs`, `config.rs`, `error.rs`, `models.rs` — entry point, env-driven config, error → HTTP mapping, shared domain types.
|
||||
- `crypto/` — the LIC1 license-key byte layout and Ed25519 sign/verify (the contract the four SDKs implement).
|
||||
- `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).
|
||||
- `payment/` (`btcpay/`, `zaprite/`) + `merchant_profiles.rs` — the payment-provider abstraction and multi-profile routing.
|
||||
- `reconcile.rs`, `subscriptions.rs`, `upgrades.rs` — the background worker (invoice reconciliation, recurring renewals, tier upgrades).
|
||||
- `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`.
|
||||
- `web/index.html` — the embedded admin SPA.
|
||||
|
||||
Deeper docs: [`docs/API.md`](docs/API.md), [`docs/INTEGRATION.md`](docs/INTEGRATION.md), [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
|
||||
|
||||
## 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
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
---
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -63,7 +68,6 @@ Who might attack this?
|
||||
- **Key rotation.** A single static signing key is fine for first launch. 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`.
|
||||
|
||||
|
||||
@@ -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};
|
||||
|
||||
Reference in New Issue
Block a user