From dc3719bd3ff65f504988f7cb1a1012ad7c7e56d3 Mon Sep 17 00:00:00 2001 From: Keysat Date: Thu, 7 May 2026 10:42:46 -0500 Subject: [PATCH] Initial public commit --- .gitignore | 12 ++ LICENSE | 21 +++ assets/favicon.svg | 10 ++ assets/keysat-mark.svg | 16 +++ docs.css | 239 ++++++++++++++++++++++++++++++++++ index.html | 164 ++++++++++++++++++++++++ install.html | 197 ++++++++++++++++++++++++++++ integrate.html | 283 +++++++++++++++++++++++++++++++++++++++++ operate.html | 168 ++++++++++++++++++++++++ wire-format.html | 177 ++++++++++++++++++++++++++ 10 files changed, 1287 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 assets/favicon.svg create mode 100644 assets/keysat-mark.svg create mode 100644 docs.css create mode 100644 index.html create mode 100644 install.html create mode 100644 integrate.html create mode 100644 operate.html create mode 100644 wire-format.html diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c0120b3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +# Editor / OS cruft +.DS_Store +.idea/ +.vscode/ +*.swp +*.bak +*.tmp + +# If we ever add a build step +node_modules/ +dist/ +build/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1b63053 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Keysat + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/assets/favicon.svg b/assets/favicon.svg new file mode 100644 index 0000000..31f1365 --- /dev/null +++ b/assets/favicon.svg @@ -0,0 +1,10 @@ + + + + + + + + + + \ No newline at end of file diff --git a/assets/keysat-mark.svg b/assets/keysat-mark.svg new file mode 100644 index 0000000..826dea1 --- /dev/null +++ b/assets/keysat-mark.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs.css b/docs.css new file mode 100644 index 0000000..a685214 --- /dev/null +++ b/docs.css @@ -0,0 +1,239 @@ +/* ============================================================ + Keysat docs — shared layout. Inline-only deps allowed. + ============================================================ */ + +@import url('https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap'); + +:root { + --navy-950:#0E1F33; --navy-900:#142A47; --navy-800:#1E3A5F; --navy-700:#2A4A75; + --navy-100:#E4EAF1; + --cream-50:#FBF9F2; --cream-100:#F5F1E8; --cream-200:#EDE7D7; + --gold-700:#8A6F3D; --gold-500:#BFA068; --gold-400:#D4B985; + --ink-900:#0E1F33; --ink-700:#2C3E54; --ink-500:#5A6B7F; --ink-400:#7E8C9D; + --success:#2D7A5F; --success-bg:#E3F0EA; + --warning:#B8861F; --warning-bg:#F7EFD7; + --danger:#B23A3A; --danger-bg:#F4E0E0; + --border-1:rgba(14,31,51,0.12); + --border-2:rgba(14,31,51,0.20); + --font-display:'Manrope','Helvetica Neue',Arial,sans-serif; + --font-body:'Inter','Helvetica Neue',Arial,sans-serif; + --font-mono:'JetBrains Mono',ui-monospace,'SF Mono',Menlo,monospace; +} + +*{box-sizing:border-box} html,body{margin:0;padding:0} +body{ + font-family:var(--font-body); color:var(--ink-900); background:var(--cream-100); + background-image: + radial-gradient(rgba(14,31,51,0.022) 1px, transparent 1px), + radial-gradient(rgba(138,111,61,0.020) 1px, transparent 1px); + background-size:3px 3px, 7px 7px; + -webkit-font-smoothing:antialiased; +} +a{color:var(--navy-800); text-decoration:none} +a:hover{text-decoration:underline; text-decoration-thickness:1.5px; text-underline-offset:3px} + +/* Top nav */ +.topnav{ + position:sticky; top:0; z-index:10; + background:rgba(245,241,232,0.9); backdrop-filter:blur(10px); + border-bottom:1px solid var(--border-1); + padding:14px 28px; display:flex; align-items:center; gap:18px; +} +.topnav .brand{ + display:flex; align-items:center; gap:10px; + font-family:var(--font-display); font-weight:500; + color:var(--navy-900); font-size:14px; + letter-spacing:0.28em; text-transform:uppercase; +} +.topnav .brand img{width:26px; height:26px} +.topnav .docs-tag{ + font-size:11px; font-weight:700; letter-spacing:0.18em; + text-transform:uppercase; color:var(--gold-700); + padding-left:10px; border-left:1px solid var(--border-2); +} +.topnav nav{margin-left:auto; display:flex; gap:22px; font-size:13.5px; color:var(--ink-700)} +.topnav nav a{color:var(--ink-700)} +.topnav nav a:hover{color:var(--navy-900); text-decoration:none} +.topnav nav a.active{color:var(--navy-900); font-weight:600} + +/* Layout */ +.layout{ + display:grid; grid-template-columns:240px 1fr 220px; + max-width:1280px; margin:0 auto; gap:32px; + padding:28px 28px 64px; +} + +aside.side{ + position:sticky; top:74px; align-self:start; + font-size:13.5px; max-height:calc(100vh - 90px); + overflow:auto; padding-right:8px; +} +aside.side .group{margin-bottom:18px} +aside.side .group .glabel{ + font-size:10.5px; font-weight:700; letter-spacing:0.16em; + text-transform:uppercase; color:var(--gold-700); + margin:6px 8px 6px; +} +aside.side a{ + display:block; padding:5px 10px; border-radius:5px; + color:var(--ink-700); line-height:1.4; +} +aside.side a:hover{background:var(--cream-200); text-decoration:none} +aside.side a.active{background:var(--navy-800); color:var(--cream-50); font-weight:600} + +main.prose{min-width:0} +.prose .crumb{font-size:12px; color:var(--ink-500); margin-bottom:8px; letter-spacing:0.04em} +.prose h1{ + font-family:var(--font-display); font-weight:500; font-size:38px; + letter-spacing:-0.022em; color:var(--navy-950); + margin:0 0 8px; line-height:1.1; +} +.prose .lead{ + font-size:17px; line-height:1.55; color:var(--ink-700); + margin:0 0 24px; max-width:640px; +} +.prose h2{ + font-family:var(--font-display); font-weight:700; font-size:24px; + letter-spacing:-0.015em; color:var(--navy-950); + margin:36px 0 12px; + padding-top:24px; border-top:1px solid var(--border-1); +} +.prose h3{ + font-family:var(--font-display); font-weight:700; font-size:17px; + color:var(--navy-950); margin:22px 0 8px; letter-spacing:-0.01em; +} +.prose p{font-size:15px; line-height:1.65; color:var(--ink-700); margin:0 0 14px; max-width:680px} +.prose ul, .prose ol{padding-left:22px; margin:0 0 14px; max-width:680px} +.prose li{font-size:15px; line-height:1.65; color:var(--ink-700); margin-bottom:4px} +.prose code{ + font-family:var(--font-mono); font-size:13px; + background:var(--cream-200); padding:2px 6px; border-radius:4px; + color:var(--navy-900); +} +.prose strong{color:var(--navy-950); font-weight:700} +.prose em{color:var(--ink-700)} +.prose a{color:var(--navy-800); font-weight:500} + +pre.code{ + background:var(--navy-950); color:var(--cream-50); + padding:18px 22px; border-radius:10px; + overflow-x:auto; + font-family:var(--font-mono); font-size:13px; line-height:1.7; + margin:14px 0 20px; border:1px solid var(--navy-900); + max-width:680px; +} +pre.code .c{color:rgba(245,241,232,0.45)} +pre.code .k{color:var(--gold-400)} +pre.code .s{color:#d4b985} +pre.code .f{color:var(--cream-50)} +pre.code .n{color:#a6b7cf} +pre.code .p{color:rgba(245,241,232,0.55)} + +.callout{ + border:1px solid var(--border-1); border-left:3px solid var(--gold-500); + background:var(--cream-50); border-radius:8px; + padding:14px 16px; margin:14px 0 22px; + display:flex; gap:12px; align-items:flex-start; + max-width:680px; +} +.callout [data-lucide]{ + color:var(--gold-700); width:18px; height:18px; + flex-shrink:0; margin-top:2px; +} +.callout p{margin:0; font-size:14px} +.callout strong{color:var(--navy-950); font-weight:700} +.callout.warn{border-left-color:var(--warning); background:var(--warning-bg)} +.callout.warn [data-lucide]{color:var(--warning)} +.callout.danger{border-left-color:var(--danger); background:var(--danger-bg)} +.callout.danger [data-lucide]{color:var(--danger)} + +/* Right TOC */ +aside.toc{ + position:sticky; top:74px; align-self:start; + font-size:12.5px; border-left:1px solid var(--border-1); + padding:8px 0 8px 18px; + max-height:calc(100vh - 90px); overflow:auto; +} +aside.toc .label{ + font-size:10.5px; font-weight:700; letter-spacing:0.16em; + text-transform:uppercase; color:var(--gold-700); margin-bottom:10px; +} +aside.toc a{ + display:block; padding:4px 0; color:var(--ink-500); line-height:1.4; +} +aside.toc a:hover{color:var(--navy-900); text-decoration:none} +aside.toc a.active{ + color:var(--navy-900); font-weight:600; + border-left:2px solid var(--gold-500); + margin-left:-20px; padding-left:18px; +} + +/* Tables in prose */ +table.t{ + width:100%; border-collapse:separate; border-spacing:0; + background:var(--cream-50); border:1px solid var(--border-1); + border-radius:10px; overflow:hidden; margin:14px 0 20px; max-width:680px; +} +table.t th{ + text-align:left; font-size:11px; font-weight:700; + letter-spacing:0.12em; text-transform:uppercase; color:var(--ink-500); + padding:12px 16px; background:var(--cream-100); + border-bottom:1px solid var(--border-1); +} +table.t td{ + padding:12px 16px; border-bottom:1px solid var(--border-1); + font-size:13.5px; color:var(--ink-700); vertical-align:top; +} +table.t tr:last-child td{border-bottom:0} +table.t code{font-size:12.5px} + +/* Cards inside prose for "what's next" links */ +.next-grid{ + display:grid; grid-template-columns:1fr 1fr; gap:16px; + margin:18px 0 24px; max-width:680px; +} +.next-card{ + display:block; background:var(--cream-50); + border:1px solid var(--border-1); border-radius:10px; + padding:18px; transition:all 120ms; +} +.next-card:hover{ + border-color:var(--border-2); text-decoration:none; + background:var(--cream-100); +} +.next-card .eyebrow{ + font-size:10.5px; font-weight:700; letter-spacing:0.18em; + text-transform:uppercase; color:var(--gold-700); + margin-bottom:6px; display:block; +} +.next-card h4{ + font-family:var(--font-display); font-weight:700; font-size:15px; + margin:0 0 4px; letter-spacing:-0.01em; color:var(--navy-950); +} +.next-card p{ + font-size:13px; color:var(--ink-700); line-height:1.5; + margin:0; max-width:none; +} + +/* Code-language tabs (for SDK examples) */ +.lang-tabs{ + display:flex; gap:0; margin:14px 0 0; max-width:680px; + border-bottom:1px solid var(--border-1); +} +.lang-tabs button{ + background:transparent; border:0; cursor:pointer; + font-family:var(--font-body); font-weight:500; font-size:13px; + color:var(--ink-500); padding:10px 16px; + border-bottom:2px solid transparent; + margin-bottom:-1px; +} +.lang-tabs button:hover{color:var(--navy-900)} +.lang-tabs button.active{color:var(--navy-900); font-weight:600; border-bottom-color:var(--gold-500)} + +@media (max-width: 980px){ + .layout{grid-template-columns:1fr; gap:18px; padding:18px} + aside.side, aside.toc{position:static; max-height:none; overflow:visible; border:0; padding:0} + aside.toc{display:none} + .topnav nav{display:none} + .next-grid{grid-template-columns:1fr} +} diff --git a/index.html b/index.html new file mode 100644 index 0000000..312aa86 --- /dev/null +++ b/index.html @@ -0,0 +1,164 @@ + + + + + +Keysat Docs — Introduction + + + + + +
+ Keysat + Docs + +
+ +
+ + +
+
Get started · Introduction
+

Welcome to Keysat.

+

Keysat is a self-hosted licensing service for software creators who want to be paid in Bitcoin. Buyers pay through your own BTCPay; your software verifies signed keys offline. You own the signing key, the customer list, and the payment rails.

+ +

These docs cover both ends:

+ +
+ + Operator +

Install & setup →

+

Sideload the package, connect BTCPay, define your first product. About an afternoon, end to end.

+ + + Developer +

Integrate the SDK →

+

Add the SDK to your app, embed your public key, verify a license at startup. About five lines of code.

+ +
+ +

Architecture

+

Keysat is the licensing layer sitting on top of your existing payments stack. Three boxes:

+
    +
  • BTCPay Server — takes the payment. On-chain Bitcoin or Lightning, settling to your wallet. Lives on your Start9.
    • +
  • Keysat — your private licensing service. Holds the Ed25519 signing key. Hosts the public purchase URLs at /buy/<product>. Listens for BTCPay payment webhooks and issues a signed license on each settlement. Lives on your Start9.
    • +
  • Your software — the thing you sell. Ships with the Keysat public key embedded at compile time. On startup it reads the user’s license and verifies the signature offline. No network call.
    • +
+ +

The key word is offline. Once a license is issued, your software does not need to phone home to verify it. The verification is a pure function of the license bytes and the public key. This is the same model used by signed JWTs, except wrapped in a small fixed-width format that’s comfortable to print on a receipt.

+ +
+ +

Why offline matters. Online license servers are a single point of failure for every customer who ever bought your software. With Keysat, if your Start9 disappears tomorrow, every previously-issued license still verifies. That’s sovereignty.

+
+ +

Products & policies

+

You declare two things in Keysat: products and policies.

+

A product is the thing you sell — "Bitcoin Ticker Pro", "Aurora Plugin", whatever. It has a slug, a display name, a description, and a price in sats.

+

A policy is a license template attached to a product. It specifies:

+ + + + + + + + + + +
FieldMeaning
duration_secondsHow long the license is valid. 0 means perpetual.
grace_secondsExtra time after expiry before the verifier rejects.
max_machinesSeat cap. 0 means unlimited.
is_trialSets a TRIAL bit so your app can show a "trial" banner.
entitlementsFree-form list of feature flags baked into the signed key (e.g. core, sync, export).
+ +

Each product has one policy slugged default — that’s the one consumed by the public purchase URL. You can attach additional named policies for manual issuance: a longer-duration "Lifetime" policy you hand out at conferences, a richer-entitlement "Pro" policy for upsells, etc.

+ +

Discount codes

+

Three kinds:

+ + + + + + + + +
KindWhat it does
percentBuyer appends ?code=FOUNDERS50 to the purchase URL; price drops by N%.
fixed_satsLike above, but a flat sat amount comes off.
free_licenseNo payment at all. Buyer redeems the code via POST /v1/redeem and gets a signed license back.
+ +

Codes can be capped at N uses, dated to expire, restricted to a single product, and tagged with a referrer label so you can see which campaign drove which sales in the audit log.

+ +

Revocation strategy

+

This is the one piece of the architecture that requires a design decision from you.

+

Because verification is offline, a license that was once issued continues to verify forever — even if you mark it as revoked in the admin UI. The verifier in your app doesn’t know about your admin actions.

+

You have three options:

+ +
    +
  • Don’t support revocation at all. Many indie developers do this. Once a key is sold, it stays valid. Refunds are still possible — you send sats back via BTCPay; the key still works but the customer agreed to stop using it.
    • +
  • Periodic online check. Your app fetches a small revocation list from your Keysat (or a CDN you point at it) once a week / month. Adds a "soft-online" requirement.
    • +
  • Short-lived licenses with renewal. Issue 30-day licenses; the app fetches a fresh signed token before expiry. v0.2 will ship recurring renewals as a first-class flow.
    • +
+ +
+ +

You decide the policy. Keysat doesn’t force a particular revocation model. The default is no revocation — that’s the simplest, sovereign-by-default choice. If you need stronger guarantees, layer them on with the patterns above.

+
+ +

Where to next

+
+ + Step 1 for operators +

Install & setup →

+

Get Keysat running on your Start9, connect BTCPay, define your first product.

+ + + Step 1 for integrators +

Integrate the SDK →

+

Embed your public key, add the SDK to your app, verify a license offline.

+ +
+
+ + +
+ + + + + diff --git a/install.html b/install.html new file mode 100644 index 0000000..4603e5d --- /dev/null +++ b/install.html @@ -0,0 +1,197 @@ + + + + + +Keysat Docs — Install & setup + + + + + +
+ Keysat + Docs + +
+ +
+ + +
+
Get started · Install & setup
+

Install & setup.

+

From bare Start9 to your first issued license, in roughly the order you’ll do it. Allow about an afternoon.

+ +

Prerequisites

+
    +
  • A Start9 server running StartOS 0.4.x (Server Pro, Server One, or DIY install).
    • +
  • Administrative access to the StartOS dashboard.
    • +
  • About 2 GB of free disk for Keysat itself; BTCPay’s requirements are larger and depend on your Bitcoin node mode.
    • +
+ +

Step 1 — Install Keysat

+

Two ways. Either gets you to the same place.

+ +

Option A: from the Keysat marketplace (recommended)

+
    +
  1. In your StartOS dashboard, go to Marketplace → Add.
    2. +
  2. Paste https://registry.keysat.xyz as the URL.
    3. +
  3. Find Keysat in the marketplace listing and click Install.
    4. +
+ +

Option B: sideload

+
    +
  1. Download keysat_x86_64.s9pk from the GitHub releases page.
    2. +
  2. In your StartOS dashboard, go to Sideload and drag the file in.
    3. +
  3. Click Install.
    4. +
+ +

BTCPay Server is declared as a required dependency. If you don’t have it installed yet, StartOS will prompt you to install it as part of the same flow.

+ +

Step 2 — Set your operator name

+

Open the Keysat service page in StartOS. Go to Actions → Set operator name. Pick a short label that identifies you as the seller — e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.

+

This change is live-reloaded; you don’t need to restart the service.

+ +

Step 3 — Connect BTCPay

+

Make sure BTCPay Server is running and has at least one store with a configured payment method (on-chain wallet or Lightning node). Without a payment method, BTCPay will reject Keysat’s invoice creation.

+ +

In Keysat’s service page, click Actions → Connect BTCPay. You’ll be redirected to BTCPay’s authorize page, where you grant Keysat the permissions it needs:

+ +
    +
  • btcpay.store.canviewinvoices
    • +
  • btcpay.store.cancreateinvoice
    • +
  • btcpay.store.canmodifywebhooks
    • +
+ +

Once you confirm, BTCPay redirects back to Keysat with an API key and store id. Keysat:

+
    +
  1. Stores the API key and store id in its local SQLite (encrypted at rest by StartOS).
    2. +
  2. Registers an outbound webhook subscription on the store, pointed at Keysat’s /btcpay webhook endpoint.
    3. +
  3. Verifies the connection by fetching the store’s payment-method list.
    4. +
+ +
+ +

Connect is idempotent. If you click it again later, Keysat detects the existing connection and returns success without re-authorizing. To force a re-authorize, run the Disconnect BTCPay action first.

+
+ +

Click Actions → Check BTCPay connection to verify the wiring. It should report:

+ +
# Expected output:
+status: connected
+store: YOUR_STORE_ID
+webhook: registered
+payment_methods: [BTC-OnChain, BTC-LightningNetwork]
+ +

If payment_methods is empty, head back to BTCPay and configure at least one before continuing.

+ +

Step 4 — Get your admin API key

+

Go to Actions → Show admin API key. This reveals the 64-hex-character key that gates all /v1/admin/* endpoints, including the admin UI.

+ +
+ +

Treat this key like a password. Anyone with it can issue, revoke, or read every license you’ve ever sold. Don’t paste it into Slack. Don’t check it into Git.

+
+ +

Step 5 — Open the admin UI

+

Click the Launch UI button on Keysat’s service page. (StartOS surfaces this for any service that defines a type: 'ui' interface.) Paste the admin key from the previous step into the sign-in form.

+ +

From here on, you mostly work in the admin UI. The StartOS Actions tab is reserved for setup-only operations (operator name, BTCPay connect/disconnect/check, show admin key).

+ +

Step 6 — Define your first product

+

In the admin UI, go to Products → Create a new product and fill in:

+ +
    +
  • Slug — lowercase, hyphens, will appear in the public URL. e.g. bitcoin-ticker-pro.
    • +
  • Display name — shown on the buyer’s purchase page and on receipts.
    • +
  • Description — one or two sentences; rendered as plain text.
    • +
  • Price (sats) — an integer. e.g. 50000 for ~$30 USD at current rates.
    • +
+ +

The product is created with no policies attached. Next:

+ +

Step 7 — Define a default policy

+

Go to Policies → Create a new policy. Pick the product, then:

+ +
    +
  • Set slug to default. This is the policy consumed by the public purchase flow; other slugs are reserved for manual issuance.
    • +
  • Set duration_seconds. Common choices: 0 (perpetual), 31536000 (1 year), 2592000 (30 days for trials).
    • +
  • Set max_machines. Use 1 for single-seat licenses or 0 for unlimited.
    • +
  • Optionally add entitlements — comma-separated feature flags. These are baked into the signed key and your app reads them at verify time.
    • +
+ +

Step 8 — Share your purchase URL

+

Your public purchase URL is now live at:

+ +
https://<your-keysat-host>/buy/<product-slug>
+ +

Buyers hit it, see your product, click "Pay", and BTCPay’s checkout takes over. On payment confirmation, Keysat receives a webhook from BTCPay, signs a license, and emails it to the buyer (if they entered an email) and shows it on the receipt page.

+ +

Test it end-to-end by creating a free-license discount code and redeeming it — the same code path runs, just without the payment leg.

+ +

What’s next

+
+ + Hook it up +

Integrate the SDK →

+

Embed your public key in your app and verify licenses offline.

+ + + Run it +

Operate →

+

Backups, migration to new hardware, and troubleshooting.

+ +
+
+ + +
+ + + + + diff --git a/integrate.html b/integrate.html new file mode 100644 index 0000000..ff97cea --- /dev/null +++ b/integrate.html @@ -0,0 +1,283 @@ + + + + + +Keysat Docs — Integrate the SDK + + + + + +
+ Keysat + Docs + +
+ +
+ + +
+
Get started · Integrate the SDK
+

Integrate the SDK.

+

Wire Keysat licenses into your software in under an afternoon. The verifier is pure-function, offline, and ships in five lines.

+ +

Prerequisites

+

Before you start, you should have:

+
    +
  • A Keysat installation running on your Start9 — see Install & setup.
    • +
  • BTCPay Server connected to Keysat — ditto.
    • +
  • At least one product defined in the admin UI.
    • +
+ +

Pick an SDK

+

Three official SDKs ship today. They are wire-compatible — a license issued by your Keysat verifies identically in any of them.

+ +
+ + + +
+ + 
# npm
+npm install @keysat/licensing-client
+
+# pnpm
+pnpm add @keysat/licensing-client
+ + + +

If your language isn’t covered, see Wire format. The format is small and porting takes about an afternoon.

+ +

Step 1 — Embed your public key

+

In the admin UI, open Overview and copy the issuer public key from the "Embed your public key" card. (Or fetch it from GET /v1/issuer/public-key.) Paste it into your application’s source code as a compile-time constant.

+ + 
const ISSUER_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
+-----END PUBLIC KEY-----`;
+ + + +
+ +

Embed it. Don’t fetch it. The whole point of offline verification is that your software can’t be tricked by a network-level attacker. If you fetch the public key at runtime, you’re back to trusting a server.

+
+ +

Step 2 — Verify a license at startup

+

Read the user’s license key from wherever you store it (a file in their data directory, the OS keychain, an env var) and verify it on application start.

+ + 
import { Verifier, PublicKey } from '@keysat/licensing-client';
+
+const verifier = new Verifier(
+  PublicKey.fromPem(ISSUER_PEM)
+);
+
+const result = verifier.verify(licenseKeyFromUser);
+
+if (!result.valid) {
+  exitUnlicensed();
+}
+if (!result.entitlements.has('export')) {
+  disableExport();
+}
+ + + +

The verifier returns a result object with the following fields:

+ + + + + + + + + + + + + + +
FieldTypeMeaning
validboolSignature checked, expiry not exceeded.
product_idstringThe product slug this license was issued for.
policy_slugstringWhich policy was active at issue time.
license_idstringUUID of the license; useful for support tickets.
issued_atDateUTC timestamp.
expires_atDate | nullnull for perpetual.
is_trialboolSet by the policy at issue time.
seatsintMax machines (0 = unlimited).
entitlementsSet<string>Feature flags baked into the signed payload.
+ +

Step 3 — Handle errors gracefully

+

Verification can fail for benign reasons (the user hasn’t pasted a license yet) or hostile ones (someone tampered with a license file). Distinguish them in your UX:

+ + 
try {
+  const result = verifier.verify(licenseKey);
+  if (result.valid) grantAccess(result);
+  else showRenewalPrompt(result.expires_at);
+} catch (e) {
+  if (e instanceof SignatureError) showTamperWarning();
+  else if (e instanceof FormatError) showInputError();
+  else showGenericError(e);
+}
+ + + +

Renewals & revocation

+

Keysat licenses are signed at issue time and do not phone home. If a license is revoked in the admin UI, the existing key continues to verify in your app — that’s the trade-off for offline.

+ +

If you need revocation, ship a thin online check that runs on a cadence (e.g. once a week) against your Keysat’s revocation feed:

+ + 
// Optional. Run on a cadence, ignore network errors.
+async function checkRevocation(licenseId: string) {
+  const r = await fetch(`https://your-keysat.example/v1/licenses/${licenseId}/status`);
+  if (r.ok) {
+    const j = await r.json();
+    if (j.status === 'revoked') disableApp();
+  }
+}
+ + + +
+ +

You decide the policy. Many indie developers ship no revocation at all. Once a key is sold, it stays valid — refunds happen offline via BTCPay. That’s perfectly reasonable.

+
+ +

Admin API

+

The admin UI is a thin shell over a small JSON API. Bearer-auth all requests with your admin API key.

+ + + + + + + + + + + + + + +
MethodPathUse
GET/v1/productsList products (public).
POST/v1/admin/productsCreate a product.
POST/v1/admin/policiesCreate a policy.
POST/v1/admin/discount-codesCreate a discount or comp code.
GET/v1/admin/licenses/searchFind licenses by email, npub, or invoice.
POST/v1/admin/licenses/<id>/revokeRevoke a license.
POST/v1/admin/webhook-endpointsRegister an outbound webhook.
GET/v1/admin/auditRead audit log.
POST/v1/redeemRedeem a free-license code (public).
+ +

Full schemas for each endpoint live in Wire format & API reference.

+
+ + +
+ + + + + diff --git a/operate.html b/operate.html new file mode 100644 index 0000000..7eb1d83 --- /dev/null +++ b/operate.html @@ -0,0 +1,168 @@ + + + + + +Keysat Docs — Operate + + + + + +
+ Keysat + Docs + +
+ +
+ + +
+
Operate · Day-to-day
+

Operate.

+

Backups, migration, recovery, and the things that go wrong. The "you didn’t expect to need this page until you needed it" page.

+ +

Backups

+

StartOS handles backups for you. By default, every service in your StartOS install is included in the same backup snapshot — you set the destination once (encrypted external drive, S3-compatible cloud, etc.) and StartOS schedules nightly snapshots.

+ +

The Keysat backup payload is intentionally tiny. It contains:

+ +
    +
  • The signing keypair (/data/issuer-key.pem).
    • +
  • The SQLite database (/data/keysat.db).
    • +
  • Migration history.
    • +
+ +

That’s it. No log files (those rotate locally), no caches.

+ +
+ +

Verify your backup destination at least once. Restoring on a fresh Start9 with a corrupted backup is exactly the wrong moment to discover that your destination wasn’t actually configured. StartOS → Settings → Backups → Test.

+
+ +

Your BTCPay store data and your Bitcoin wallet are separate backups, handled by the BTCPay and Bitcoin Core packages respectively. Keep them on the same backup destination so they restore in lockstep.

+ +

Migrating to new hardware

+

The full migration path:

+ +
    +
  1. On the old Start9, ensure your most recent backup is complete and includes Keysat. Confirm the destination is writable and that snapshots have finished.
    2. +
  2. On the new Start9, complete first-time setup with a fresh password. Don’t install any services yet.
    3. +
  3. StartOS → Settings → Backups → Restore. Point at the same destination. Pick the most recent snapshot.
    4. +
  4. StartOS restores all services in dependency order. Keysat will restore alongside BTCPay and Bitcoin Core. Bitcoin will need to re-sync if you’re using Bitcoin Core (consider utxo.live for assumeutxo to skip IBD).
    5. +
  5. Once Keysat is running on the new box, your purchase URLs change — the LAN/Tor hostnames are different. Update any links you’ve published.
    6. +
+ +

The signing keypair restores along with the database, so all previously-issued licenses verify identically against the same public key. You don’t need to re-distribute the public key to your customers.

+ +

Rotating the signing key

+

You generally don’t want to rotate the signing key — doing so invalidates every license you’ve ever issued. v0.1 doesn’t support rotation; the key is generated once at first start and never changed.

+ +

If you absolutely need to rotate (e.g. you suspect the keypair has leaked off the box):

+ +
    +
  1. Stop Keysat.
    2. +
  2. Move /data/issuer-key.pem aside.
    3. +
  3. Restart Keysat — it will generate a fresh keypair on first run.
    4. +
  4. Re-issue all active licenses to existing customers using the new key. The admin UI doesn’t support bulk re-issuance yet; this is a manual SQL exercise.
    5. +
  5. Push a software update that swaps the embedded public key.
    6. +
+ +

The cleaner path, for v0.2 onward, will be to support a rolling rotation where both keys verify for a transition period.

+ +

Troubleshooting

+ +

"Invalid BTCPay URL" when clicking Connect BTCPay

+

Keysat is selecting a BTCPay URL that isn’t reachable from your browser. This usually means the picked URL is a StartTunnel-local 10.59.x.x address rather than your LAN/mDNS one.

+

Fix: open BTCPay’s service page in a separate tab, copy the URL it shows under "Network — mDNS" or "Network — LAN", and confirm Keysat is using a similar shape. If you’re on Tor only, BTCPay needs to expose its admin UI over Tor too.

+ +

"Payment method unavailable" on first invoice creation

+

BTCPay rejects the invoice request because the store has no configured wallet. Open BTCPay, find your store, and configure either an on-chain wallet or a Lightning node before retrying.

+ +

Webhook deliveries failing

+

Check the audit log in the admin UI — failed deliveries land there with the response status. Common causes:

+
    +
  • Endpoint URL no longer reachable. Hit it manually with curl from your laptop to confirm.
    • +
  • Endpoint rejecting on signature mismatch. Verify your endpoint is HMAC-validating against the secret you registered with.
    • +
  • Endpoint timing out. Endpoints have a 10s deadline. Move slow work behind a queue on your end.
    • +
+ +

"database is locked" errors in logs

+

Almost always a sign that two daemon instances are racing on the same SQLite file — usually because of a misconfigured supervisor. Confirm only one Keysat container is running. If you’re seeing this on a fresh install with no customizations, file a bug report against the package version you’re running.

+ +

Licenses verifying as "expired" immediately after issue

+

Clock skew. Either the issuing host or the verifying host has the wrong time. Run NTP. StartOS keeps your Start9 in sync automatically; the issue is usually on the verifier side (e.g. an air-gapped buyer machine).

+ +

Reading the logs

+

Keysat logs to stdout, captured by StartOS. Tail them from the StartOS dashboard — Service page → Logs → Live tail.

+ +

Useful log lines to grep for:

+ + + + + + + + + + +
PatternWhat it means
license issuedSuccessful license issuance. Includes license id and product.
btcpay webhook receivedBTCPay delivered an event. Followed by a "settled" or "expired" disposition line.
auth failedBad admin API key on a request to /v1/admin/*.
signature mismatchBTCPay webhook arrived with the wrong HMAC. Either misconfigured or actively malicious.
migration appliedA schema migration ran on startup. Normal during package updates.
+ +

Getting help

+

If you’re stuck:

+ + +
+ + +
+ + + + + diff --git a/wire-format.html b/wire-format.html new file mode 100644 index 0000000..dbad28b --- /dev/null +++ b/wire-format.html @@ -0,0 +1,177 @@ + + + + + +Keysat Docs — Wire format reference + + + + + +
+ Keysat + Docs + +
+ +
+ + +
+
Reference · Wire format
+

Wire format reference.

+

The bytes-over-the-wire spec for a Keysat license. Stable across SDKs and across language ports. About 90 lines of pseudocode to implement in a new language.

+ +

Overview

+

A Keysat license key looks like this on a receipt:

+ + 
KS-9F2A-7C41-XK22-6D8E-LM77-PQ91
+ +

Strip the KS- prefix and the dashes, and you have a Crockford base32-encoded blob. Base32-decode that blob, and you get the binary license envelope: a fixed-layout struct followed by an Ed25519 signature.

+ +

Binary layout

+

All multi-byte integers are big-endian.

+ + + + + + + + + + + + + + + + +
OffsetLengthFieldNotes
04MagicASCII KSAT (0x4B 0x53 0x41 0x54).
41VersionCurrently 0x01. Decoders MUST reject unknown versions.
51FlagsBit 0: TRIAL. Bit 1: PERPETUAL. Bits 2–7 reserved.
616License IDUUIDv4 binary form.
2216Issuer fingerprintSHA-256 of the issuer public key, truncated to 16 bytes.
388Issued-atUnix seconds, signed.
468Expires-atUnix seconds, signed. 0 if PERPETUAL flag is set.
542SeatsMax machines. 0 = unlimited.
562Payload lengthLength L of the variable-size payload that follows.
58LPayloadUTF-8 JSON: { "product": "...", "policy": "...", "entitlements": [...] }.
58 + L64SignatureEd25519 signature over bytes 0 .. (58 + L).
+ +

Crockford base32

+

Keysat uses Crockford’s base32 alphabet (0123456789ABCDEFGHJKMNPQRSTVWXYZ) without checksum, without padding, and case-insensitive on decode.

+ +

The reason for Crockford over standard base32: human-friendly. I, L, O, U are excluded from the alphabet to avoid ambiguity when typing keys off a printed receipt.

+ +

Dash grouping & prefix

+

For display, keys are upper-cased, then grouped into 4-character chunks separated by dashes, and prefixed with KS-:

+ + 
// raw base32, length depends on payload size
+9F2A7C41XK226D8ELM77PQ91RR54VV01
+
+// grouped + prefixed for display
+KS-9F2A-7C41-XK22-6D8E-LM77-PQ91-RR54-VV01
+ +

Decoders MUST strip the KS- prefix (case-insensitive), strip whitespace and dashes, and case-fold to upper before base32-decoding.

+ +

Signature

+

The signature covers the entire envelope from offset 0 through the end of the payload — that is, all bytes before the 64-byte signature itself.

+ +

Verify with the issuer’s Ed25519 public key. The fingerprint at offset 22 lets the verifier confirm that the key it has matches the key the license was signed with: SHA-256 the public key bytes, truncate to 16 bytes, compare. If it doesn’t match, the verifier MUST reject before attempting signature check — this gives a clear "wrong issuer" error rather than a generic "bad signature".

+ +

Worked example

+

Test vector for the Python SDK’s cross-check tests (issuer fingerprint 0xfeed face cafe babe..., single-seat perpetual license):

+ + 
# Hex dump of the binary envelope
+00000000  4B 53 41 54 01 02 9F 2A  7C 41 XK 22 6D 8E LM 77   |KSAT...*|A.."m..w|
+00000010  PQ 91 RR 54 VV 01 FE ED  FA CE CA FE BA BE 00 00   |...T....|........|
+00000020  00 00 00 00 65 4F 12 34  00 00 00 00 00 00 00 00   |....eO.4|........|
+00000030  00 01 00 24 7B 22 70 72  6F 64 75 63 74 22 3A 22   |...${"product":"|
+00000040  73 75 6E 64 69 61 6C 22  2C 22 70 6F 6C 69 63 79   |sundial","policy|
+00000050  22 3A 22 64 65 66 61 75  6C 74 22 7D ...sig...     |":"default"}.....|
+
+# As displayed
+KS-9F2A-7C41-XK22-6D8E-LM77-PQ91-…
+ +

The full vector lives in licensing-client-python/tests/fixtures/canonical.json and is what every official SDK is tested against.

+ +

Issuer public key format

+

Public keys are exchanged in PEM format, SubjectPublicKeyInfo encoded:

+ + 
-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAmz7q8r4t1v…h3k2pXq9wL
+-----END PUBLIC KEY-----
+ +

This is the same encoding that openssl pkey -pubout produces. Keysat exposes it at GET /v1/issuer/public-key:

+ + 
{
+  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----\n",
+  "public_key_b64": "mz7q8r4t1v…h3k2pXq9wL",
+  "fingerprint_hex": "feed face cafe babe …"
+}
+ +

Porting to a new language

+

The wire format is small enough to port in an afternoon. The order is:

+ +
    +
  1. Copy the test vectors from licensing-client-python/tests/fixtures/canonical.json.
    2. +
  2. Implement Crockford base32 decode (~30 lines).
    3. +
  3. Implement the binary unmarshal (~40 lines, mostly offset arithmetic).
    4. +
  4. Wire it up to your language’s Ed25519 verifier from a vetted crypto library.
    5. +
  5. Run the cross-check tests — if they pass, you’re wire-compatible.
    6. +
+ +

See PORTING_SDK_TO_NEW_LANGUAGES.md in the repo for the full contributor guide.

+ +

Versioning policy

+

The version byte at offset 4 is a hard gate. Decoders MUST reject any version they don’t implement. We commit to:

+ +
    +
  • Never silently changing the v1 layout. Any change ⇒ new version byte.
    • +
  • Maintaining v1 verifier support indefinitely — even if v2 ships, your existing customer keys stay verifiable.
    • +
  • Publishing test vectors for every new version under tests/fixtures/ in the canonical SDK.
    • +
+
+ + +
+ + + + +