Keysat
b5a066750a
Two related changes that ship together because the second was uncovered
while testing the first.
1. Live config reload (the ostensible feature):
The "Set Gemini API Key" StartOS action writes to /data/config/
startos-config.json. The server used to read that file once at
startup (and via a separate Python read in docker_entrypoint.sh
before that), which meant a key change required a service restart
to take effect. Now the server polls the file every 3 s
(RECAP_CONFIG_POLL_MS, env-overridable) and updates serverApiKey
in place. fs.watch was tried first and dropped — it's flaky on
macOS (FSEvents single-file quirks) and behaves inconsistently with
atomic-rename writes the SDK file model uses. Polling is dead
simple and a stat call every 3 s is free.
Also dropped the Python config read from docker_entrypoint.sh; the
server now handles it natively. Entrypoint still loads /data/.env
for arbitrary env vars (RECAP_*, etc.).
2. Vendor module resolution (the silently-broken thing):
The earlier vendor change (move @keysat/licensing-client from a
git+https dep to a file: dep at vendor/) created a symlink in
server/node_modules. That symlink to the vendor dir was getting
resolved by Node, so the keysat client tried to import @noble/
ed25519 from /app/vendor/keysat-licensing-client/dist/, walked up
to /app/vendor/, then /app/, neither of which had node_modules.
Result: v0.2.0 and v0.2.1 would crash at startup with
ERR_MODULE_NOT_FOUND on @noble/ed25519. The Docker BUILD succeeded
because npm install with file: deps doesn't pull transitive deps
into the parent node_modules — but the runtime would have failed
the moment server/license.js ran.
Fix:
• Dockerfile builder now `npm install`s inside vendor/keysat-
licensing-client/ so @noble/* lands in its own node_modules,
where Node's resolver finds it.
• Dockerfile runner now COPYs vendor/ to the runner image
(previously not copied — the symlink in server/node_modules
would have pointed at nothing).
• vendor/keysat-licensing-client/package-lock.json is committed
so the in-Docker install is reproducible.
@keysat/licensing-client
TypeScript / JavaScript client for Keysat — a self-hosted Bitcoin-paid software licensing server that runs on Start9.
Works in modern browsers and Node 18+. No native dependencies; signature verification is done in pure JS via @noble/ed25519.
What you get
- Offline verification: check a license key with just the issuing server's public key. No network.
- Online validation: live revocation check and fingerprint binding via the service's
/v1/validateendpoint. - Purchase flow: kick off a BTCPay checkout and poll for the issued key.
Install
npm install @keysat/licensing-client
5-line offline check
import { Verifier, PublicKey } from '@keysat/licensing-client'
const verifier = new Verifier(PublicKey.fromPem(ISSUER_PUBKEY_PEM))
const ok = verifier.verify(keyFromUser)
console.log('licensed for product', ok.productId)
That's the whole integration. Embed your public key as a string at build time (e.g. Vite's ?raw import, webpack raw-loader, or just a const). If the verifier returns without throwing, the key is real and was issued by you.
10-line online check (with revocation + fingerprint)
import { Client } from '@keysat/licensing-client'
const client = new Client('https://license.example.com')
const result = await client.validate(keyFromUser, 'my-product', machineFingerprint)
if (!result.ok) {
console.error('rejected:', result.reason)
process.exit(1)
}
The server enforces revocation live and does trust-on-first-use fingerprint binding, so the same key used from a second machine gets rejected.
Purchase flow
const session = await client.startPurchase('my-product')
console.log('pay at:', session.checkoutUrl)
const key = await client.waitForLicense(session.invoiceId)
console.log('got license:', key)
waitForLicense polls until the BTCPay invoice settles and the service issues a key. It throws if the invoice expires or becomes invalid.
Browser usage
Everything here works in the browser too. Drop the library into your React/Svelte/Vue app and run offline verification client-side — no server call needed for the common case.
// Vite: import the PEM as a raw string at build time
import issuerPem from './issuer.pub?raw'
import { Verifier, PublicKey } from '@keysat/licensing-client'
const verifier = new Verifier(PublicKey.fromPem(issuerPem))
License
MIT.