Electron / TypeScript

The reference for @keygrant/electron 0.9.0, the KeyGrant SDK for Electron and Node: every option, call and status. The rules every SDK shares are in How every SDK behaves.

• Node.js 20 or later.
• Runs in Electron's main process or any Node process, not in a renderer: it uses Node's file system, child processes and WebCrypto.
• Depends on zod only. Nothing in it is specific to Electron.

Release notes

Add it

@keygrant/electron is on npm.

npm install @keygrant/electron

Use it

The quick start, after Add it: embed your product's public key, activate a key, and check the license on every launch. You need a product with a license model and a key to try (see Getting started).

1. Get the public key

The SDK verifies each lease offline with your product's public keys. Fetch them once and ship them with your app. The request needs no API key:

curl https://api.keygrant.dev/v1/products/my-product/pubkey

{  "publicJwk": {    "kty": "OKP",    "key_ops": ["verify"],    "alg": "EdDSA",    "ext": true,    "crv": "Ed25519",    "x": "…"  },  "keys": [    { "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "…" }  ]}

• my-product is your product's API ID, the last part of the product page's URL in the dashboard (/app/products/my-product).
• Pass the keys array to the SDK's publicJwks option unchanged: it is every key a build of your app should carry, each with its id (kid).
• Copy key set, on the product's Signing key tab, copies the same set as {"keys": [...]}.
• The SPKI and .pem forms, and when the keys change, are in Get your product's public key.

2. Activate a key

Create one License for the process, and activate the key your customer enters:

import { License } from "@keygrant/electron";
const license = new License({  product: "my-product",  apiBaseUrl: "https://api.keygrant.dev",  publicJwks: PUBLIC_KEYS, // the keys from step 1  major: 1, // this build's major version});
const result = await license.activate(userEnteredKey);if (!result.ok) showActivationError(result.error);

• activate sends the key to KeyGrant to be checked, takes one of the key's device seats for this machine, and stores the signed lease KeyGrant returns, a JWT that your app verifies offline.
• When it fails, result.error says why, such as invalid-key or limit. Every value is in Activating.

3. Check the license on launch

// Run on every launch.async function checkLicense() {  const status = await license.status();  if (status.state === "licensed" || status.state === "trial") return; // run  if (status.state === "unknown") {    // The license file could not be read: keep running and check again shortly.    setTimeout(checkLicense, 5_000);    return;  }  // "expired" or "invalid": status.reason says why. "unlicensed": no key is stored yet.  showActivationWindow(status);}
checkLicense();

status() verifies the stored lease on the device, and usually needs no network.

• A lease lasts the key's Offline days, and never runs past the key's expiry plus its grace period: see How long a lease lasts.
• A device trial started with startTrial() gets one lease that runs to the trial's end.
• When the lease nears its end, status() renews it first, waiting at most 5 seconds for KeyGrant: see When the SDK goes online.
• When KeyGrant cannot be reached, your app keeps working until the lease runs out. See Offline validation & grace.

The rest of this page is every option, call and status.

new License(options)

The constructor checks the public keys and revokedLicenseFiles, and no other option, and does no I/O. It throws when:

• neither publicJwks nor publicJwk is given, or both are;
• publicJwks is empty;
• a key is not an Ed25519 public JWK: its kty is not OKP, its crv not Ed25519, it holds the private d, its use is not sig, its key_ops do not include verify, its alg is not EdDSA or Ed25519, or its x is not 32 bytes of base64url;
• revokedLicenseFiles is given and is not a list of texts.

An x pasted with its padding is read as the same key.

Methods

Calls on one License run one at a time, except has, require, upgradeUrl and the two pickUp calls, which only read and run beside any call. Create one License per process.

Activating

• Activating the same key again on the same device keeps its seat.
• Activating a different key replaces the stored license without releasing the old key's seat: call deactivate() first to free it.
• activate() rejects when the license file cannot be read or the activation cannot be saved.

activate() answers one of:

Keys only their buyer can activate

When a key is locked to its buyer (Who can activate), pass what the customer typed as activate(key, { email, code }), asking for each only when an error names it. The steps and rules are in How every SDK behaves. Since 0.7.0.

let result = await license.activate(key)if (!result.ok && result.error === 'user-email-required') {  // Ask for the email the key was sold to.  result = await license.activate(key, { email })}if (!result.ok && result.error === 'user-code-required') {  // A code was just emailed to that address: ask for it.  result = await license.activate(key, { email, code })}if (!result.ok && result.error === 'try-again') {  // The code could not be emailed. Nothing was activated; offer to try again.}

• The options argument comes in 0.7.0: in 0.6.0 and earlier, activate(key) takes none, and answers a locked key network.
• importLicenseFile(content, { email, code }) passes them on to a key file's key.

The errors it answers:

Restoring a license without the key

For an App Store build, which may not take a typed key: pickUp(email) emails the customer a six-digit code, and restoreByEmail(email, code) activates the key that fits this build. How a pickup works is in How every SDK behaves. Since 0.9.0.

// An App Store build: no key field. Ask for the email the customer bought with.await license.pickUp(email)// They type the code from the email:const result = await license.restoreByEmail(email, code)if (!result.ok && result.error === 'wrong-code') {  // Ask for the code again.} else if (!result.ok && result.error === 'code-expired') {  // Offer to send a new code: license.pickUp(email).} else if (!result.ok && result.error === 'no-key') {  // No purchase on that email.}

• To let the customer choose, call pickUp(email, code), show each key by its modelName, and activate the one chosen with activate(picked.key, { email, code: picked.activationCode }).
• restoreByEmail with the same email and code after pickUp(email, code), or again after an activation that got no answer, needs no new code (What is kept).
• The requests are on the endpoints page.

The errors a pickup answers:

Deactivation

deactivate() resolves { released }:

• A copied license that is not held to a machine ID is released like any other.
• In every case the key, the activation and the lease are removed from this device. The record of any device trial is kept, and so is a stored offline license file (removeLicenseFile() drops that).
• deactivate() rejects when an earlier call is stuck. It also rejects when the license file cannot be read or saved, and the key then stays on the device.

The status

status(), refresh() and startTrial() resolve the same status object. It does not include the license's expiry date or grace period. A trial status includes the trial's end.

States and reasons

status() never rejects because of a storage error: an unreadable file gives unknown, and if a save fails, the status still reflects KeyGrant's response. What to tell the customer for each reason is in Offline validation & grace.

License files

A customer can be sent a .kglicense file: a key file, which activates its key, or an offline license file, which licenses the app with no network. How each behaves is in How every SDK behaves, and what each costs under Delivered as in License models. Since 0.6.0.

• LICENSE_FILE_EXTENSION is .kglicense, for an open dialog's filter or a drop handler's test.
• importLicenseFile takes the file's content, never its path, so your app reads the file and hands over its bytes.
• List the ids of leaked files in revokedLicenseFiles (Blocking a leaked file).
• These are not the file the SDK stores its own state in (below).

// main processimport { app, dialog, ipcMain } from 'electron'import { readFile } from 'node:fs/promises'import { License, LICENSE_FILE_EXTENSION } from '@keygrant/electron'
const license = new License({  product: 'sluice',  apiBaseUrl: 'https://api.keygrant.dev',  publicJwks: KEYS.keys,  major: 3,  revokedLicenseFiles: [], // ids of files that leaked: an update adds them here})
// The renderer hands over a dropped file's bytes.ipcMain.handle('license:import', (_event, bytes: Uint8Array) => license.importLicenseFile(bytes))
// "Open license file..." in a menu.async function openLicenseFile() {  const { filePaths } = await dialog.showOpenDialog({    filters: [{ name: 'License file', extensions: [LICENSE_FILE_EXTENSION.slice(1)] }],  })  if (filePaths[0]) return license.importLicenseFile(await readFile(filePaths[0]))}
// macOS: a .kglicense the app is registered for, double-clicked in Finder.app.on('open-file', async (event, path) => {  event.preventDefault()  try {    const result = await license.importLicenseFile(await readFile(path))    if (!result.ok) showError(result.error)  } catch (error) {    showError(error) // unreadable, not saved, or a license call still running: try again  }})

A dropped file reaches the main process from the renderer through the preload script:

// preloadimport { contextBridge, ipcRenderer } from 'electron'contextBridge.exposeInMainWorld('licensing', {  importFile: (bytes: Uint8Array) => ipcRenderer.invoke('license:import', bytes),})
// rendererwindow.addEventListener('dragover', (event) => event.preventDefault())window.addEventListener('drop', async (event) => {  event.preventDefault()  const file = event.dataTransfer?.files[0]  if (!file) return  const result = await window.licensing.importFile(new Uint8Array(await file.arrayBuffer()))  if (result.ok) showThanks(result.licensedTo.name ?? result.licensedTo.email)  else showError(result.error)})

What importLicenseFile answers

It verifies the file offline (Importing a file) and resolves { ok: true, kind: 'key' | 'offline', licensedTo }, or { ok: false, error } with nothing stored. error is one of these, or, for a key file whose key did not activate, whatever activate() answers (above).

• It rejects when an earlier call on the License has not finished, when an offline file cannot be saved, and, for a key file, wherever activate() rejects.
• A key file of a locked key takes the same { email, code } as activate() (above), and an offline file ignores it.

The status of a stored file

A stored offline file is checked again on every status(), which then resolves { state: 'licensed', source: 'file', key, licensedTo, ... } with the file's entitlements, and never asks KeyGrant, refresh() included.

• Show "Licensed to Ada Lovelace" from licensedTo.
• A status with source: 'file' has no seat to deactivate: offer removeLicenseFile() instead. deactivate() leaves the file alone.
• Which wins when the device also holds a key, and the reasons a file's status can be invalid, are in The status of a stored file.

Metered uses

A license model can count uses of what it sells (see Metered uses). The app spends them with use(meter, n), before the work they count, and does the work only when the spend is ok. Since 0.8.0.

const spent = await license.use('exports') // use('exports', 40) spends forty at once, whole or noneif (spent.ok) {  runExport() // spent.left: what is left now, net of this device's unsynced spends} else if (spent.error === 'used-up') {  offerMoreExports(spent.left) // KeyGrant's word: fewer left than asked (0 when none)} else if (spent.error === 'offline-limit') {  askToConnect() // KeyGrant could not be reached, and this is past what this device may spend without it} else {  showMeterProblem(spent.error) // 'no-meter', 'not-licensed', 'revoked', 'device', 'upgrade', 'outdated', 'storage', 'invalid-amount'}
const { meters } = await license.status() // offline, from the leasemeters?.exports // { left: 950, total: 1000, offline: 100, unsynced: 0, resets: false }

• use() resolves { ok: true, left }, with offline: true when the device spent from its offline allowance, or { ok: false, error }. It never rejects.
• A request waits at most 5 seconds for KeyGrant, less when httpTimeoutMs is shorter.
• deactivate() sends the unsynced spends with the release.
• How a spend works online and offline, and why a meter never takes the license away, is in How every SDK behaves.

When use() does not spend

status().meters

By meter code, on a licensed status from a key's lease that names meters. It is a plain object: to test a code that is also an Object.prototype member, use Object.hasOwn(status.meters ?? {}, code).

Adapters

Pass any of them in adapters; the SDK uses the default for each one you leave out. The default fingerprinter has 2 seconds to read the machine ID during a status check, and 10 seconds during an activation or a trial.

interface StorageAdapter {  // readOnly: write nothing, not even a repair.  read(opts?: { readOnly?: boolean }): Promise<StoredState | null>;  write(state: StoredState): Promise<void>;  // Optional. When present, every save goes through it.  update?(merge: (latest: StoredState) => StoredState): Promise<void>;}
interface RegistryStash {  readTrialStart(): Promise<number | null>;  writeTrialStart(ms: number): Promise<void>;}
interface Clock {  now(): number; // Unix milliseconds}
interface Fingerprinter {  get(): Promise<string>;  // Used when present. Only kind "machine" holds a license to its device.  identify?(opts: { timeoutMs: number }): Promise<DeviceIdentity>;}
interface DeviceIdentity {  fingerprint: string | null;  kind?: "machine" | "hostname";  alternates: string[];}
interface HttpAdapter {  // Must resolve, not throw, on a 4xx.  post(    url: string,    body: unknown,    opts?: { timeoutMs?: number },  ): Promise<{ status: number; json: unknown }>;}

• fingerprint: a custom fingerprinter holds a license to its machine only if it implements identify and reports kind: "machine". If it implements only get(), licenses are never held to the device.
• registry: the default stores nothing. A registry stash you supply is read when a trial starts, and the earliest start date it holds is sent with the request. The start date KeyGrant returns is then written back to it.
• http: if your adapter throws, the SDK treats it as no response.

Where the license is stored

The default storage is one JSON file, <product>.json, in the per-user folder every SDK shares. The folders, and how a save works, are in Where the license is stored. defaultStoragePath(product) gives its path, and createFileStorage(path) keeps it somewhere else (below).

Other exports

The package also exports these types:

• LicenseConfig, LicenseStatus, LicenseState, LicenseReason, LicenseError, ActivateResult, DeactivateResult, Adapters, StorageAdapter, StoredState, RegistryStash, Clock, Fingerprinter, DeviceIdentity, HttpAdapter, Entitlement and Entitlements.
• In 0.6.0: ImportLicenseFileResult, LicenseFileError, LicenseFileKind and LicensedTo.
• In 0.7.0: ActivateOptions.
• In 0.8.0: MeterStatus, UseResult, UseError, MeterFigure and SpendEntry.
• In 0.9.0: PickedKey, PickupError, PickUpSentResult, PickUpKeysResult and RestoreResult.