keysat/KEYSAT_INTEGRATION.md

Integrating Keysat licensing into your software

This document is the complete instruction set for adding Keysat-based licensing to any application. It covers Node/TypeScript, Python, and Rust. Hand it to an LLM (or a developer) along with your codebase and ask them to wire it up — they should have everything they need.

How to use this document

Drop KEYSAT_INTEGRATION.md into a fresh session against the target codebase, then prompt:

Read this KEYSAT_INTEGRATION.md. Then add Keysat licensing to this codebase. Ask the software creator how they would like to license, monetize and/or gate their software, including how unlicensed software should operate. Use the creator's Keysat public key which can be found in the Keysat admin UI. After wiring, summarize what you changed.

Reading this as an LLM? Your job is to add license-key reading, signature verification, and entitlement-based feature gating to the target application. Before you write any code, ask the software creator the questions in section 0. Then read sections 1–6, then jump to the language section (7a/7b/7c) that matches your target codebase. The "Worked example" in section 14 is the canonical pattern to mimic.

---

0. Questions to ask the software creator before writing code

Don't write any code until you have answers. The whole licensing model hangs on these:

1. What's the operator's Keysat instance URL? (e.g. https://licensing.example.com. Used for online validation and the in-app purchase flow.)

2. What's the operator's product slug? (Short string the operator chose when creating the product in their Keysat admin. License keys are scoped to this slug.)

3. What's the operator's signing public key? (PEM-formatted Ed25519 public key. Get it from the Keysat admin Overview tab → "Embed your public key" → Copy. The operator pastes it; you embed it.)

4. How should unlicensed users experience the app? Three legitimate patterns; pick whichever fits the operator's business model. None is "wrong."

   • Hard gate — the app downloads freely from the Start9 registry, but won't function without a paid license. The binary is essentially a locked installer until the buyer activates. Common for closed-source paid apps and for open-source apps that the operator chooses to monetize through the registry distribution. See section 8 for the two flavors of hard gating (refuse-to-start vs. activate-screen-only).
   • Soft gate — the app runs and provides basic functionality unlicensed; specific paid features return 402 with an "Upgrade to unlock" message. Recommended for free → paid migrations and for freemium products.
   • Nag mode — no enforcement; just a "support development" banner when unlicensed. Pure honor system. Useful when the app is fundamentally free-to-use but the operator wants a tip-jar.

   Nudge the operator if their answer doesn't match their business reality. Closed-source-paid + nag-mode is incoherent; freemium + hard-gate alienates the existing user base.

5. What are the entitlement strings, and what does each unlock? The operator decides; ask them. Common patterns:

   • ["self_host"] for a free tier — "you can run the app, no premium features"
   • ["self_host", "export", "ai_features", "team_seats"] for a paid tier
   • ["patron"] extra for a vanity supporter tier Document the mapping (entitlement string → feature unlocked) in your integration so the operator can ship the right policies.

6. Where should the license key live on disk at runtime? Default: /data/license.txt for server / containerized apps, or ~/.config/<your-app>/license.key for desktop apps. Operator may override.

7. Which pricing tiers exist and roughly what they cost? (Optional for the integration itself, but useful for shaping the "Upgrade" message that shows when an unlicensed user hits a paid feature.)

If the creator doesn't know yet, propose sensible defaults from the ranges above and confirm before coding.

8. Compile a config card before writing code. After answering 1–7, produce a short summary the operator can paste into the Keysat admin without re-deriving anything. This is the single highest-leverage step for avoiding "wait, what entitlements did we agree on?" churn later. The card has three parts:

   • Product: the slug from question 2.
   • Policies: each policy's name and the entitlement set it issues. Treat this as the operator's pricing menu — one policy per tier.
   • Behavior matrix: caller state → what happens. Lets the operator sanity-check the gating model (question 4) against the policy set.

   Show the card to the operator, get explicit confirmation, then write code. Example for a two-tier hard-gate-flavor-2 freemium app:

   Product slug: youtube-summarizer
   
   Policies to create in Keysat admin:
     • Core   → entitlements: ["core"]
     • Pro    → entitlements: ["core", "subscriptions", "history", "library"]
   
   Entitlement → unlocks:
     core           — past the activation screen; basic summarize
     subscriptions  — channel subscriptions, auto-queue
     history        — saved summary library
     library        — bulk import/export
   
   Behavior matrix:
     no license     → 402 license_required everywhere
     Core license   → summarize works; subs/history/library = 402 feature_not_in_tier
     Pro license    → all features available
   

   Without this card, mid-implementation drift is near-certain — the LLM gates on library_io, the operator creates a policy with library, and the buyer sees a "feature not in tier" error on a feature they thought they paid for.

---

1. What Keysat does, in one paragraph

Keysat lets independent software creators sell their work on their own terms. The operator (the creator) runs a Keysat instance — typically on a Start9 box — and Keysat handles the buy page, the Bitcoin payment via BTCPay, and issuing each buyer a signed license key in LIC1-…-… form. Your software's job is to read that key from somewhere on disk (a file, an env var, a config setting) and verify its signature against the operator's public key. What happens after verification is up to the creator: maybe the app refuses to function without a license (one-time purchase model), maybe specific features unlock (free + paid tiers), maybe nothing changes and the verified license is just used to show a "thanks for supporting development" badge. You never talk to a Keysat server at runtime unless you want to — verification is offline, fast (~1ms), and doesn't depend on the network.

---

2. The whole integration in 30 seconds

1. Install the Keysat SDK in your language.
2. Embed the operator's PUBLIC key into your app at build time.
3. On startup, read the license key from disk; verify it; populate an
   `entitlements` set.
4. Throughout your code, gate paid features with `if entitlements.has("X")`.
5. (Optional) On a timer, also call /v1/validate to catch revocations.

Everything else is polish.

---

3. Prerequisites — three things you need from the operator

1. A Keysat instance reachable on the public internet. Typically something like https://licensing.example.com. The operator already has this; you don't need to install one.

2. A product slug the operator created in their Keysat. This is a short string (acme-paint-pro, myapp, etc.). Licenses issued for one slug won't validate against another — this is intentional and stops a customer from buying a cheap product and using its key to unlock an expensive one.

3. The operator's signing public key in PEM form. This is what you embed in source. Get it from:

   • The admin Overview tab → "Embed your public key" tip card → Copy
   • Or curl https://licensing.example.com/v1/issuer/public-key | jq -r .public_key_pem

   The PEM is non-secret — anyone with the public key can verify licenses but not mint them. It's safe to commit to source control and ship in your binary.

4. The public buy URL for your product. Each product on a Keysat instance has a buyer-facing page at <keysat-base-url>/buy/<product-slug>. Use this for "Buy a key" / "Upgrade to Pro" links in your app's activation screen, settings, and per-feature upsell tiles. Compute it from the same constants you've already embedded — don't hard-code a separate URL that can drift:

   const buyUrl = `${KEYSAT_BASE_URL.replace(/\/$/, "")}/buy/${PRODUCT_SLUG}`
   

   The simpler "link to a buy page" path (this URL) is fine for most apps. If you want a more integrated checkout, see section 11 for client.startPurchase().

---

4. The wire format you'll be reading

License keys look like:

LIC1-AIAMCWOS5JVHSQE2UMP6PNKXODHSIPHM5O3XQQ2J6CE4XV6WVNMA3BIAAAAA…

A LIC1- prefix, then two base32 segments separated by -. The first segment is a binary payload; the second is an Ed25519 signature over the payload. The SDK parses and verifies in one call. You should never need to handle the encoding manually.

The signed payload contains:

• product_id (UUID) — for matching against your product slug
• license_id (UUID) — useful for logging
• issued_at (Unix seconds)
• expires_at (Unix seconds; 0 means perpetual)
• flags (bitfield; FLAG_TRIAL=1)
• entitlements: string[] — this is the array you gate features on
• fingerprint_hash (32 bytes; for online machine-binding)

Your software reads entitlements and decides what to unlock.

---

5. Where to read the license from

There's no one-size-fits-all answer; pick one based on how your users interact with your app. Recommended order:

1. A file in the user's data directory. On Linux this is typically ~/.config/<your-app>/license.key, or /data/license.txt for server software running in a container. The file contains exactly one line: the raw LIC1-… string. This is the most common pattern.

2. An environment variable like MYAPP_LICENSE_KEY. Useful for server-side software, CLIs, Docker Compose, and systemd. Easy to set, but users forget they set it and lose track.

3. A "paste your license key" UI in your app's settings, with the value persisted to localStorage / OS keychain / your own config. Most familiar to users coming from commercial software.

4. Multiple of the above. A common pattern is: "env var first, then file, then UI prompt." All three give you a license string either way; the SDK doesn't care where it came from.

For Start9 packages: there's a activate-license-template that wires this up for you using StartOS Actions and the package store. Copy that template, replace the slug, and you've got Pattern 1 + a StartOS Actions UI for buyers to paste keys into.

---

6. The canonical integration pattern

Every integration follows the same shape regardless of language and regardless of which enforcement model from question 4 the operator picked. The verify-once-at-startup primitive is the same; what you do with the result is what changes.

on startup:
    raw_key = read_license_string()             # file, env, or UI value
    license_state = {state: 'unlicensed', entitlements: []}
    if raw_key is not None:
        result = verify(raw_key, ISSUER_PEM)     # SDK call
        if result.is_valid:
            license_state = {
                state: 'licensed',
                entitlements: result.entitlements,
                license_id: result.license_id,
                expires_at: result.expires_at,
            }
        else:
            log("license rejected: " + result.reason)

    # Then — depending on the operator's chosen model:
    #
    #   HARD GATE  : if not licensed, exit (Flavor 1) or block all
    #                business endpoints (Flavor 2). See section 7d.
    #
    #   SOFT GATE  : run normally; specific feature handlers consult
    #                license_state.entitlements before unlocking.
    #                See section 7a/7b/7c.
    #
    #   NAG MODE   : run normally; show a "support development" banner
    #                in the UI when license_state.state != 'licensed'.

The verify-and-populate-state step is identical for all three models. The doc is structured the same way: section 7 covers the verify primitive in each language; section 7d covers the hard-gate enforcement flavors; the worked examples in section 14 show soft-gate; the patterns are mix-and-match.

One universal rule across all three models: never hard-fail on network errors during the optional online validate() call (section 9). That's separate from refusing to start when no license is present — which is fine for hard-gate Flavor 1. The thing to avoid is making your app's uptime depend on the operator's licensing server being reachable.

Don't forget background workers. HTTP middleware gates only catch incoming requests. If you have in-process timers, schedulers, queue consumers, or other background jobs that exercise gated features, add an explicit early-return at the top of each one:

async function checkSubscriptionsBackground() {
  if (!LIC.entitlements.has("subscriptions")) return  // skip silently
  // … existing work
}

Otherwise an unlicensed (or insufficient-tier) instance will keep doing work the buyer didn't pay for — wasting bandwidth, API quota, and server CPU, and producing stale state in the UI when entitlements are later restored. This bites people because the server returns 402 to direct callers but the timer keeps humming along.

---

7. Language-specific implementations

7a. TypeScript / Node

Install (preferred, once published):

npm install @keysat/licensing-client

GitHub fallback (if the npm package isn't published yet). Several prerequisites must be met for this path to work end-to-end:

1. The keysat-xyz/keysat-client-ts repo must be public on GitHub. Private repos require credentials, which fails inside hermetic build environments (Docker, CI, fresh dev machines without an SSH key). If the repo flips public temporarily for one build, every future build re-hits this wall — prefer publishing to npm if at all possible.

2. The repo must include a prepare script in package.json that builds dist/ on git-install. This is fixed as of this doc; if you see Cannot find module '...dist/index.cjs' after install, the SDK you're pulling pre-dates the fix and you need a newer commit.

3. Use the explicit git+https:// URL form, not the github: shorthand:

   // package.json
   "@keysat/licensing-client": "git+https://github.com/keysat-xyz/keysat-client-ts.git"
   

   The github:user/repo shorthand often resolves to git+ssh://... on machines with an existing GitHub SSH key, which then breaks for any subsequent integrator without a key (CI, Docker, a fresh laptop).

4. If you switched from github: to git+https://, also delete the stale lock-file entry. npm install will keep the previous resolved: "git+ssh://..." line in package-lock.json even after you change the spec in package.json. The fastest fix is:

   rm package-lock.json node_modules
   npm cache clean --force
   npm install
   

   Or hand-edit the resolved: field of the offending entry to swap git+ssh:// → git+https://, leaving the commit hash unchanged.

When all four are satisfied:

npm install github:keysat-xyz/keysat-client-ts

Embed the public key. The simplest way is to commit the PEM file to your repo at assets/issuer.pub and import it as a raw string:

// in your bundler config (Vite shown)
import issuerPem from './assets/issuer.pub?raw'

Or in plain Node:

import { readFileSync } from 'node:fs'
import * as path from 'node:path'
const issuerPem = readFileSync(path.join(__dirname, 'assets/issuer.pub'), 'utf8')

Verify on startup:

import { Verifier, PublicKey } from '@keysat/licensing-client'
import { readFileSync } from 'node:fs'

const PRODUCT_SLUG = '<your-product-slug>'
const LICENSE_PATH = process.env.MYAPP_LICENSE_KEY_PATH || '/data/license.txt'

function readLicenseKey(): string | null {
  if (process.env.MYAPP_LICENSE_KEY) return process.env.MYAPP_LICENSE_KEY.trim()
  try { return readFileSync(LICENSE_PATH, 'utf8').trim() }
  catch { return null }
}

const verifier = new Verifier(PublicKey.fromPem(issuerPem))

export interface LicenseState {
  state: 'licensed' | 'unlicensed' | 'invalid'
  reason?: string
  licenseId?: string
  entitlements: Set<string>
  expiresAt?: Date
  isTrial?: boolean
}

export function checkLicense(): LicenseState {
  const raw = readLicenseKey()
  if (!raw) return { state: 'unlicensed', entitlements: new Set() }
  try {
    const ok = verifier.verify(raw)
    // (optional) reject keys for the wrong product slug
    if (ok.payload.productSlug && ok.payload.productSlug !== PRODUCT_SLUG) {
      return { state: 'invalid', reason: 'product_mismatch', entitlements: new Set() }
    }
    return {
      state: 'licensed',
      licenseId: ok.payload.licenseId,
      entitlements: new Set(ok.payload.entitlements || []),
      expiresAt: ok.payload.expiresAt
        ? new Date(ok.payload.expiresAt * 1000)
        : undefined,
      isTrial: !!(ok.payload.flags & 1),
    }
  } catch (e: any) {
    return { state: 'invalid', reason: e.message, entitlements: new Set() }
  }
}

Use the state object wherever a feature is gated:

const lic = checkLicense()
console.log(`[license] state=${lic.state} entitlements=[${[...lic.entitlements].join(',')}]`)

// In an Express route:
app.post('/api/export', (req, res) => {
  if (!lic.entitlements.has('export')) {
    return res.status(402).json({
      error: 'feature_not_in_tier',
      message: 'Export requires a paid license. See <upgrade_url>.',
    })
  }
  // ... existing export logic
})

7b. Python

Install (preferred, once published):

pip install keysat-licensing-client

GitHub fallback (if the PyPI package isn't published yet). The keysat-xyz/keysat-client-python repo must be public on GitHub for this to work in clean environments:

pip install git+https://github.com/keysat-xyz/keysat-client-python.git

(Python's pip-from-git path is simpler than npm's — no separate build step is required since pure-Python packages are installable from source.)

Embed the public key at a path your code can read:

# myapp/license.py
from pathlib import Path
ISSUER_PEM = (Path(__file__).parent / 'assets' / 'issuer.pub').read_text()

Verify on startup:

# myapp/license.py
import os
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Optional

from keysat_licensing_client import Verifier

PRODUCT_SLUG = '<your-product-slug>'
LICENSE_PATH = os.environ.get('MYAPP_LICENSE_KEY_PATH', '/data/license.txt')

ISSUER_PEM = (Path(__file__).parent / 'assets' / 'issuer.pub').read_text()
_verifier = Verifier.from_pem(ISSUER_PEM)


@dataclass
class LicenseState:
    state: str  # 'licensed' | 'unlicensed' | 'invalid'
    reason: Optional[str] = None
    license_id: Optional[str] = None
    entitlements: set = field(default_factory=set)
    expires_at: Optional[datetime] = None
    is_trial: bool = False


def _read_license_key() -> Optional[str]:
    if env := os.environ.get('MYAPP_LICENSE_KEY'):
        return env.strip()
    try:
        return Path(LICENSE_PATH).read_text().strip()
    except (FileNotFoundError, PermissionError):
        return None


def check_license() -> LicenseState:
    raw = _read_license_key()
    if not raw:
        return LicenseState(state='unlicensed')
    try:
        ok = _verifier.verify(raw)
        return LicenseState(
            state='licensed',
            license_id=str(ok.payload.license_id),
            entitlements=set(ok.payload.entitlements or []),
            expires_at=datetime.fromtimestamp(ok.payload.expires_at)
                if ok.payload.expires_at else None,
            is_trial=bool(ok.payload.flags & 1),
        )
    except Exception as e:
        return LicenseState(state='invalid', reason=str(e))

Use it:

# myapp/server.py
from .license import check_license

LIC = check_license()
print(f'[license] state={LIC.state} entitlements={LIC.entitlements}')

@app.post('/api/export')
def export_endpoint():
    if 'export' not in LIC.entitlements:
        abort(402, description={
            'error': 'feature_not_in_tier',
            'message': 'Export requires a paid license.',
        })
    # ... do the thing

7c. Rust

Install (preferred, once published):

# Cargo.toml
[dependencies]
keysat-licensing-client = "0.1"

Git fallback (if not on crates.io yet). The keysat-xyz/keysat-client-rust repo must be public on GitHub:

keysat-licensing-client = { git = "https://github.com/keysat-xyz/keysat-client-rust.git" }

Cargo builds from source, so no separate build step is required.

Embed the public key:

const ISSUER_PEM: &str = include_str!("../assets/issuer.pub");

Verify on startup:

// src/license.rs
use keysat_licensing_client::{Verifier, PublicKeyPem};
use std::collections::HashSet;
use std::path::PathBuf;

pub const PRODUCT_SLUG: &str = "<your-product-slug>";
pub const ISSUER_PEM: &str = include_str!("../assets/issuer.pub");

#[derive(Debug, Clone)]
pub struct LicenseState {
    pub state: &'static str, // "licensed" | "unlicensed" | "invalid"
    pub reason: Option<String>,
    pub license_id: Option<String>,
    pub entitlements: HashSet<String>,
    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
    pub is_trial: bool,
}

impl Default for LicenseState {
    fn default() -> Self {
        Self {
            state: "unlicensed",
            reason: None,
            license_id: None,
            entitlements: HashSet::new(),
            expires_at: None,
            is_trial: false,
        }
    }
}

fn read_license_key() -> Option<String> {
    if let Ok(s) = std::env::var("MYAPP_LICENSE_KEY") {
        let s = s.trim().to_string();
        if !s.is_empty() { return Some(s) }
    }
    let path = std::env::var("MYAPP_LICENSE_KEY_PATH")
        .unwrap_or_else(|_| "/data/license.txt".to_string());
    std::fs::read_to_string(PathBuf::from(path))
        .ok()
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty())
}

pub fn check_license() -> LicenseState {
    let raw = match read_license_key() {
        Some(s) => s,
        None => return LicenseState::default(),
    };
    let pubkey = match PublicKeyPem::from_str(ISSUER_PEM) {
        Ok(k) => k,
        Err(e) => return LicenseState {
            state: "invalid", reason: Some(format!("bad pubkey embedded: {e}")),
            ..Default::default()
        },
    };
    let verifier = Verifier::new(pubkey);
    match verifier.verify(&raw) {
        Ok(ok) => LicenseState {
            state: "licensed",
            license_id: Some(ok.payload.license_id.to_string()),
            entitlements: ok.payload.entitlements.into_iter().collect(),
            expires_at: if ok.payload.expires_at == 0 {
                None
            } else {
                chrono::DateTime::from_timestamp(ok.payload.expires_at, 0)
            },
            is_trial: (ok.payload.flags & 1) != 0,
            ..Default::default()
        },
        Err(e) => LicenseState {
            state: "invalid", reason: Some(e.to_string()),
            ..Default::default()
        },
    }
}

Use it:

let lic = license::check_license();
tracing::info!(state = lic.state, entitlements = ?lic.entitlements, "license loaded");

// At a feature gate:
if !lic.entitlements.contains("export") {
    return Err(MyError::PaymentRequired(
        "Export requires a paid license.".into()
    ));
}

7d. Hard-gate patterns — "the app doesn't function without a license"

If the operator chose hard gate in the section-0 questions (binary freely downloadable, but locked until activated), use one of these two flavors instead of the entitlements-as-feature-flags pattern above. The verifier helpers from 7a / 7b / 7c are still the right primitive — the difference is what you do with the result.

Flavor 1: Refuse to start. The daemon exits at boot with a clear log line if there's no valid license. StartOS will show the service as crashing — the operator's README needs to tell buyers "install the license first via Actions → Set license, then start the service."

// TypeScript / Node
const lic = checkLicense()
if (lic.state !== 'licensed') {
  console.error(`[license] not licensed (${lic.state}): ${lic.reason || ''}`)
  console.error(`[license] paste a license key into ${LICENSE_PATH} via the StartOS "Set license" action, then restart.`)
  process.exit(1)
}

# Python
lic = check_license()
if lic.state != 'licensed':
    log.error(f'[license] not licensed ({lic.state}): {lic.reason or ""}')
    log.error(f'[license] paste a license key, then restart.')
    raise SystemExit(1)

// Rust
let lic = license::check_license();
if lic.state != "licensed" {
    eprintln!("[license] not licensed ({}): {}", lic.state, lic.reason.unwrap_or_default());
    eprintln!("[license] paste a license key, then restart.");
    std::process::exit(1);
}

This is the most aggressive option. Use when (a) the app is closed-source and there's no "free version" of the binary anyone could compile, and (b) the operator is OK with StartOS surfacing the service as unhealthy until activated.

Flavor 2: Run, but block all real work behind an "Activate" screen. The daemon starts normally, but every business endpoint returns 402 until a license is activated. Only the activation endpoint(s) and a status endpoint are open. Buyers see a clean "paste your license to get started" UI on first run; StartOS shows the service as healthy. Generally a better buyer experience than Flavor 1.

// TypeScript / Express — middleware that gates everything except
// the activation paths.
const ACTIVATION_PATHS = new Set([
  '/api/license-status',  // for the frontend to render activation UI
  '/api/activate',         // accepts a pasted license key, writes to file, refreshes state
  '/healthz',              // for StartOS / orchestration
])

let LIC = checkLicense()  // mutable; refresh after activation

app.use((req, res, next) => {
  if (ACTIVATION_PATHS.has(req.path)) return next()
  if (LIC.state !== 'licensed') {
    return res.status(402).json({
      error: 'license_required',
      message: 'This service requires a Keysat license to function.',
      activate_url: '/activate',  // your frontend's activation page
      state: LIC.state,
      reason: LIC.reason,
    })
  }
  next()
})

// Activation endpoint — accepts a pasted key, writes it, re-checks.
app.post('/api/activate', express.json(), (req, res) => {
  const key = (req.body.license_key || '').trim()
  if (!key.startsWith('LIC1-')) {
    return res.status(400).json({ error: 'bad_format', message: 'Expected a LIC1-… key.' })
  }
  fs.writeFileSync(LICENSE_PATH, key + '\n')
  LIC = checkLicense()
  if (LIC.state === 'licensed') {
    return res.json({ ok: true, state: 'licensed', entitlements: [...LIC.entitlements] })
  }
  return res.status(400).json({ error: 'invalid', state: LIC.state, reason: LIC.reason })
})

# Python / Flask — same idea
ACTIVATION_PATHS = {'/api/license-status', '/api/activate', '/healthz'}
LIC = check_license()  # module-level; reload after activation

@app.before_request
def license_gate():
    if request.path in ACTIVATION_PATHS:
        return None
    if LIC.state != 'licensed':
        return jsonify({
            'error': 'license_required',
            'message': 'This service requires a Keysat license to function.',
            'state': LIC.state,
            'reason': LIC.reason,
        }), 402

@app.post('/api/activate')
def activate():
    global LIC
    key = (request.json or {}).get('license_key', '').strip()
    if not key.startswith('LIC1-'):
        return {'error': 'bad_format'}, 400
    Path(LICENSE_PATH).write_text(key + '\n')
    LIC = check_license()
    if LIC.state == 'licensed':
        return {'ok': True, 'entitlements': sorted(LIC.entitlements)}
    return {'error': 'invalid', 'state': LIC.state, 'reason': LIC.reason}, 400

// Rust / axum — same idea: a middleware layer that guards all admin
// routes, plus an /api/activate endpoint that accepts a key and updates
// the in-memory state.
//
// Sketch (full impl follows the existing axum middleware pattern):
//   Router::new()
//     .route("/api/license-status", get(license_status))
//     .route("/api/activate", post(activate))
//     .route("/healthz", get(healthz))
//     .nest("/api", api_routes())
//     .layer(axum::middleware::from_fn_with_state(state.clone(), license_gate))
//
// Inside `license_gate`, return 402 unless the request path is in
// ACTIVATION_PATHS or `state.license.read().await.state == "licensed"`.

How would Keysat itself do this? Keysat already has the Mode::Enforce build-time flag in license_self.rs: when built with KEYSAT_LICENSE_ENFORCE=1, missing or invalid licenses cause the daemon to refuse to start (Flavor 1). Default Permissive builds run unlicensed at Creator-tier caps. To switch Keysat to Flavor 2 ("run but block until activated") would mean: keep the existing boot-time license check non-fatal, expose /admin/login-style activation endpoints under a hardcoded allowlist, and have an axum middleware return 402 on every other admin/business endpoint until state.self_tier flips from Unlicensed to Licensed. The pieces are all there — it's a few hundred lines of axum middleware + an SPA "Activate" splash screen.

7e. Packaging gotchas — Docker, s9pk, hermetic builds

Most non-trivial integrations end up packaged in Docker (Start9 s9pk, generic container deploys, CI-built images). The following gotchas together account for ~80% of the "it works locally but the build fails" failure mode:

1. Slim base images don't ship git, ssh, or ca-certificates. node:20-slim, python:3.11-slim, etc. are intentionally minimal. If you have a git-URL dependency (e.g. the GitHub fallback above), you'll need at least these in the builder stage:

RUN apt-get update && apt-get install -y --no-install-recommends \
      git ca-certificates \
  && rm -rf /var/lib/apt/lists/*

Without git: npm errors with spawn git ENOENT when resolving the dependency. Without ca-certificates: HTTPS clones fail with SSL certificate problem: unable to get local issuer certificate.

2. npm's git resolver tries ssh:// for github.com URLs first. Even if your package.json spec and package-lock.json resolved both say git+https://, npm internally tries SSH first when the host is github.com. In a container with no SSH client or key, this fails. Force git to silently rewrite SSH URLs to HTTPS:

RUN git config --global --add url."https://github.com/".insteadOf "ssh://git@github.com/" \
 && git config --global --add url."https://github.com/".insteadOf "git@github.com:" \
 && git config --global --add url."https://github.com/".insteadOf "git://github.com/"

The --add flag matters — without it, each subsequent invocation overwrites the previous one (they share a key) and only the last rewrite is active.

3. Don't forget to COPY your new license module. If your Dockerfile lists individual server files explicitly:

COPY server/package.json ./server/
COPY server/index.js ./server/
COPY public/ ./public/
COPY assets/ ./assets/

…the build will succeed, the image will start, and then crash at runtime with Cannot find module './license.js'. Add a line for the license module:

COPY server/license.js ./server/   # ← easy to miss

This is the single most common "package builds, container won't boot" failure when retro-fitting licensing into an existing app.

4. Make's incremental rebuild can mask uncommitted changes. s9pk build chains often look like make x86 → start-cli s9pk pack → docker build. Make may decide nothing's newer than the existing .s9pk because its dependencies typically include .git/index (which only updates on git add). Symptom: you change a source file, rebuild, get an instant "✅ Build Complete!" with the same package as before.

Either stage your changes (git add -A) so .git/index updates, or delete the existing .s9pk to force a rebuild:

rm myapp_x86_64.s9pk && make x86

5. The --ignore-scripts flag will skip the SDK's prepare build. If your Dockerfile uses npm ci --ignore-scripts (a common security hardening), the SDK won't build its dist/ and you'll hit the "Cannot find module" runtime error from §7a. Either drop --ignore-scripts for the builder stage, or pre-build the SDK elsewhere and vendor dist/ in.

7f. Frontend integration for hard-gate Flavor 2

If you picked hard-gate Flavor 2 (server starts, business endpoints return 402 until activated), the frontend is half the work — otherwise unlicensed users see a sea of fetch errors instead of a clean activation screen. The pattern below is framework-agnostic and works in vanilla JS, React, Vue, etc.

Step 1: Fetch license-status before any other API call. It's the prerequisite for deciding what to render.

async function loadLicenseStatus() {
  const r = await fetch("/api/license-status")
  return r.json()  // { state, entitlements, productSlug, keysatBaseUrl, … }
}

Step 2: Render the activation screen as a top-level guard. If state !== "licensed" (or the core entitlement is missing), replace the entire app body with the activation card. Don't render the normal UI underneath — every API call would 402 anyway, producing visible broken state.

if (lic.state !== "licensed" || !lic.entitlements.includes("core")) {
  return <ActivationScreen lic={lic} onActivate={key => activate(key)} />
}
return <App />

Step 3: The activation card needs four things:

• A <textarea> for pasting the LIC1-... key (use a textarea, not an input — keys are 100+ chars and users will copy-paste with whitespace)
• An "Activate" button that POSTs to /api/license/activate with {license_key: <pasted>} and refreshes state on success
• Distinct error messages for each reason code (see §12), not a generic "activation failed"
• A "Buy a key" link to ${keysatBaseUrl}/buy/${productSlug} (see §3)

Step 4: Gate Pro features in the UI, not just the server. The server returns 402 for missing entitlements, but unless the frontend also checks, users see ghost UI for features they can't use:

{lic.entitlements.includes("subscriptions")
  ? <SubscriptionsPanel />
  : <ProUpsell feature="subscriptions" buyUrl={buyUrl} />}

Each ProUpsell should explain what they'd unlock, not just "Pro feature." The server's 402 response includes a message field with a sentence-long description — surface it.

Step 5: Add a license block to settings. Buyers want to see what tier they're on, when it expires, and have a way to remove the key. Hit /api/license-status for state, render a colored badge per tier, and expose a "Deactivate" button that POSTs to /api/license/deactivate.

Step 6: Respond to entitlement changes without a reload. After activation, re-fetch any data your app skipped at boot (history, subscriptions, etc.) — the user just unlocked them. After deactivation, clear it from in-memory state so the previous tier's data doesn't leak through the activation screen.

Reference shape your /api/license-status should return so the frontend has everything it needs without extra round-trips:

{
  "state": "licensed",
  "reason": null,
  "licenseId": "abc123…",
  "entitlements": ["core", "subscriptions", "history", "library"],
  "expiresAt": "2027-05-01T00:00:00Z",
  "isTrial": false,
  "productSlug": "youtube-summarizer",
  "keysatBaseUrl": "https://licensing.example.com"
}

productSlug and keysatBaseUrl aren't strictly part of license state — they're there so the frontend can construct the /buy/<slug> URL without hard-coding it. Ship them in the response.

---

8. Picking entitlement names

Entitlement strings are arbitrary; they're whatever the operator put on the policy when issuing the license. Common conventions:

• Feature flags: export, ai_summaries, team_seats, recurring_billing, card_payments
• Capability tiers: unlimited_products, unlimited_seats, priority_support
• Branded markers: patron (no real feature, just a badge)

Pick names that are stable, lowercase, snake-case, descriptive. Document your chosen entitlement names in your README so operators / customers know what they're buying. Treat them like API contract — once you ship a feature gated on "export", you can't rename to "file_export" without breaking existing licenses.

The operator can use whatever set they want when creating policies; your app only needs to know the names of features it gates on. Operators selling tiered plans typically have:

• A free / Creator tier with one entitlement (self_host or similar)
• A pro / paid tier with several (unlimited_*, premium features)
• Optional Patron / supporter tier with all of Pro plus a patron badge

---

9. Online validation (optional, recommended)

Offline verify proves the key was signed by the right operator. Online validation also catches revocations (operator disabled a key) and enforces fingerprint binding (one license = one machine). Use both: offline at boot, online on a timer.

// TypeScript
import { Client } from '@keysat/licensing-client'
const client = new Client('https://licensing.example.com')

async function onlineCheck(licenseKey: string, machineFingerprint: string) {
  try {
    const r = await client.validate(licenseKey, PRODUCT_SLUG, machineFingerprint)
    if (!r.ok) {
      // r.reason is one of: 'revoked' | 'fingerprint_mismatch' |
      //                     'not_found' | 'bad_signature' | 'product_mismatch'
      console.warn('license rejected:', r.reason)
      // → React in your UI; don't hard-crash on this.
    }
  } catch {
    // Network errors → "status unknown". Don't block the user.
  }
}

# Python
from keysat_licensing_client import Client
client = Client('https://licensing.example.com')
try:
    r = client.validate(license_key, PRODUCT_SLUG, machine_fingerprint)
    if not r.ok:
        log.warning(f'license rejected: {r.reason}')
except Exception:
    pass  # network error → status unknown

// Rust (with `online` feature)
let client = keysat_licensing_client::online::Client::new("https://licensing.example.com")?;
match client.validate(&key, Some(PRODUCT_SLUG), Some(&fp)).await {
    Ok(r) if r.ok => { /* fine */ }
    Ok(r) => log::warn!("rejected: {:?}", r.reason),
    Err(_) => { /* network error, don't punish */ }
}

Cadence: once at startup after the offline check succeeds, then on a timer (hourly is plenty). Once-per-feature-call is too aggressive and beats up the operator's server.

Critical: never refuse to start if validate() throws. Network errors must degrade to "I can't tell, assume the user is fine" — not "app refuses to launch." Otherwise your app's uptime depends on the operator's licensing server being up.

---

10. Fingerprint binding (for validate())

When you call client.validate(...), the third argument is a machine fingerprint. The operator's Keysat binds the first fingerprint it sees to the license; subsequent calls with a different fingerprint return reason: 'fingerprint_mismatch'. This is the anti-piracy mechanism.

Compute the fingerprint from something stable across reboots but unique per machine:

Platform	Source
Linux	/etc/machine-id
macOS	ioreg -d2 -c IOPlatformExpertDevice → IOPlatformUUID
Windows	Registry: HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid
Fallback	A UUID written into your app's config dir on first launch

Mix in a per-product salt so fingerprints collected by your app can't be reused against a different operator's licensing service:

const fingerprint = `${PRODUCT_SLUG}|${machineId}`

The SDK hashes this before sending, so the operator's Keysat never sees the raw input.

If a customer legitimately moves devices and hits fingerprint_mismatch, they should contact the operator. The operator can reset the binding from their admin dashboard. Don't try to help users bypass this in your app — it's the protection working as intended.

---

11. Driving the purchase flow from inside your app (optional)

If your app can open URLs (desktop GUI, CLI that can xdg-open), you can drive the entire purchase flow from inside without forcing the user into a separate browser tab.

import { Client } from '@keysat/licensing-client'
import open from 'open'

const client = new Client('https://licensing.example.com')

async function buyLicense(buyerEmail?: string): Promise<string> {
  const session = await client.startPurchase(PRODUCT_SLUG, { buyerEmail })
  await open(session.checkoutUrl) // BTCPay invoice page
  const key = await client.waitForLicense(session.invoiceId, { timeoutMs: 30 * 60_000 })
  return key
}

waitForLicense polls /v1/purchase/<id> until the BTCPay invoice settles and the license is signed. Save the returned key to disk (/data/license.txt or wherever your app reads from), then re-run checkLicense().

The simpler alternative: just link to the operator's buy page and let them complete the purchase on the web, then paste the resulting key into your app's settings. Less integrated, less friction to implement.

---

12. UX patterns for revocation & errors

When validate() returns ok: false, the reason field tells you why:

reason	What to show the user
revoked	"This license has been revoked by the seller. Contact support."
fingerprint_mismatch	"This license is already active on another computer."
not_found	"License key not recognized. Did you copy it correctly?"
bad_signature	"This license appears tampered. Contact support."
product_mismatch	"This license is for a different product."
expired	"Your license expired on . Renew at ."

Customize the copy for your tone, but show distinct messages — they mean very different things to the user.

---

13. Migrating from a non-Bitcoin licensing scheme (Gumroad, Stripe, etc.)

If you already sell licenses through a non-Bitcoin system, you don't have to do a flag-day migration. Two-phase plan:

Phase 1: dual-stack. Your app accepts BOTH old-format keys and LIC1-… keys. They look different, so detection is trivial:

const isKeysat = raw.startsWith('LIC1-')

Honor old keys via your old verification path, new keys via the Keysat SDK. Both unlock the same features. Existing customers see no change.

Phase 2: cutover. When you're ready to retire the old system, issue fresh LIC1- keys for existing customers via the operator's admin "Issue license manually" action and email them with a one-line "here's your new key" note. Mark the old format deprecated; don't break it for some grace period.

For free → paid migrations, use free-license discount codes: the operator creates a code with kind: free_license, max_uses: <your existing user count>, you put a "Redeem your existing-user code" button in your app's first-launch screen, and existing users redeem once and never see the prompt again.

---

14. Worked example: minimal Express server

A complete pattern for an Express + JS app. Copy-paste, replace MYAPP, the slug, and the issuer PEM, and you have a working integration.

// server/license.js
const fs = require('node:fs')
const path = require('node:path')
const { Verifier, PublicKey } = require('@keysat/licensing-client')

const PRODUCT_SLUG = 'myapp'
const LICENSE_PATH = process.env.MYAPP_LICENSE_KEY_PATH || '/data/license.txt'
const ISSUER_PEM = fs.readFileSync(
  path.join(__dirname, '..', 'assets', 'issuer.pub'),
  'utf8'
)
const verifier = new Verifier(PublicKey.fromPem(ISSUER_PEM))

function readKey() {
  if (process.env.MYAPP_LICENSE_KEY) return process.env.MYAPP_LICENSE_KEY.trim()
  try { return fs.readFileSync(LICENSE_PATH, 'utf8').trim() } catch { return null }
}

function checkLicense() {
  const raw = readKey()
  if (!raw) return { state: 'unlicensed', entitlements: new Set() }
  try {
    const ok = verifier.verify(raw)
    return {
      state: 'licensed',
      licenseId: ok.payload.licenseId,
      entitlements: new Set(ok.payload.entitlements || []),
      expiresAt: ok.payload.expiresAt
        ? new Date(ok.payload.expiresAt * 1000)
        : null,
      isTrial: !!(ok.payload.flags & 1),
    }
  } catch (e) {
    return { state: 'invalid', reason: e.message, entitlements: new Set() }
  }
}

module.exports = { checkLicense, LICENSE_PATH }

// server/index.js
const express = require('express')
const { checkLicense, LICENSE_PATH } = require('./license')

const app = express()
const LIC = checkLicense()
console.log(`[license] state=${LIC.state} entitlements=[${[...LIC.entitlements].join(',')}]`)

if (LIC.state === 'invalid') {
  console.warn(`[license] invalid: ${LIC.reason} — running unlicensed`)
}

// Free for everyone
app.get('/api/healthz', (_, res) => res.json({ ok: true }))

// Free tier: limited basic feature
app.post('/api/basic', (req, res) => {
  res.json({ ok: true, result: 'basic feature' })
})

// Paid feature — gated on the `export` entitlement
app.post('/api/export', (req, res) => {
  if (!LIC.entitlements.has('export')) {
    return res.status(402).json({
      error: 'feature_not_in_tier',
      message: 'Export requires a paid license. See <upgrade_url>.',
      license_path: LICENSE_PATH,
    })
  }
  res.json({ ok: true, result: 'paid export' })
})

// Buyer-facing license status (so the frontend can show "licensed" badge
// and construct the buy URL without hard-coding it).
const KEYSAT_BASE_URL = 'https://licensing.example.com'  // operator's instance

app.get('/api/license-status', (_, res) => {
  res.json({
    state: LIC.state,
    reason: LIC.reason || null,
    licenseId: LIC.licenseId || null,
    entitlements: [...LIC.entitlements],
    expiresAt: LIC.expiresAt || null,
    isTrial: !!LIC.isTrial,
    productSlug: PRODUCT_SLUG,
    keysatBaseUrl: KEYSAT_BASE_URL,
  })
})

app.listen(process.env.PORT || 8080)

That's a complete integration. ~75 lines. Replace the slug, the PEM file, and the entitlement names with what your operator chose, and ship it.

---

15. Common mistakes

• Embedding the wrong key. The PEM you embed is the public key (from GET /v1/issuer/public-key). The private key never leaves the operator's Keysat. If you accidentally ship a private key, every attacker can mint licenses.
• Hard-failing on validate() errors. If your app refuses to boot when validation throws, you've gated on the operator's server uptime. Always treat network errors as "status unknown" and fall back to the offline check.
• Calling validate() in a hot loop. Once at startup + once per hour is plenty.
• Slug mismatch. A license issued for slug foo won't validate against slug bar. Typos in the slug constant cause "license valid but my code rejects it" head-scratchers. Read the slug from a single constant.
• Logging the full license key. It's a bearer credential — log the license_id instead.
• Refusing to start without a license. Boot in unlicensed mode and let the user keep using whatever's free-tier. Much better UX than exit-on-startup.
• Forgetting to COPY the new license module into the container. If your Dockerfile lists individual server files explicitly, adding server/license.js requires its own COPY line. Build succeeds, container starts, then crashes at startup with Cannot find module './license.js'. See §7e for the full Docker checklist.
• Letting the SDK ship without a built dist/. Git installs of the Keysat client only work if the package has a prepare script that builds on install (or commits its dist/ directory). Without that, the install succeeds but the package is empty. If you publish to npm, this isn't a problem — prepublishOnly builds dist/ for you. If you only host on GitHub, ensure prepare is wired.
• Using github:user/repo shorthand instead of git+https://.... The shorthand often resolves to SSH on machines with a GitHub key, which then breaks every hermetic build downstream. Always use the explicit git+https://github.com/... form, and double-check the resolved: field in your package-lock.json after switching — npm caches the previous resolution and may keep an SSH URL in the lock even after you change the spec.
• Skipping the frontend half of hard-gate Flavor 2. A server-only integration boots happily but every request 402s, which the unlicensed user experiences as a broken app rather than a clear "activate to continue" screen. See §7f for the framework-agnostic pattern.

---

16. Testing the integration

1. Get a real license to test against. Easiest: ask the operator to issue you one manually from their admin UI's "Manually issue a license" form (Licenses tab). Or, if they've created a free_license discount code, redeem it: curl -X POST https://licensing.example.com/v1/redeem -H 'content-type: application/json' -d '{"product":"<slug>","code":"<code>"}' — the response includes a license_key.
2. Save the key to /data/license.txt (or wherever you read from).
3. Restart your app.
4. Look for a startup log line: [license] state=licensed entitlements=[…].
5. Hit a paid endpoint — should succeed.
6. Hit a paid endpoint after deleting the license file — should return 402.
7. Tamper with one character of the key — should log state=invalid.
8. (Online) Have the operator revoke the license; on next online check, reason should be revoked.

---

17. Reference: Keysat dogfoods this same pattern

The Keysat daemon itself uses this exact integration to license itself. license_self.rs in the Keysat repo:

• Embeds the master public key as TRUST_ROOT_PUBKEY_PEM.
• Reads the license from /data/keysat-license.txt at boot.
• Verifies via the same parse_key + verify_payload machinery the SDK uses.
• Exposes state.self_tier.entitlements to the rest of the daemon.
• Other handlers gate features on entitlements (e.g., unlimited_products, recurring_billing) — see tier.rs for the canonical gate-helper pattern.

If you want a working precedent to copy, that's the cleanest one in the codebase. The pattern is identical to what your app should do.