App licensing

licence lets you sell your app with signed licence files. The app checks them offline against a public key you pin, and licence.require("sso") switches a licensed feature on or off.

licence:
  driver: http
  product: acme-desktop
  roots: ["ed25519:CvBKNOIhJSGvXg9chN9qV8-z6byK3-is6-12mXaidWQ"]  # the well-known test root; pin your own in production
  file: ./main.licence
  features: [sso, audit-export]
  url: https://api.mainsdk.dev
  refresh: 6h
  trust: ./main.licence-trust          # CA certificates and revocation lists
  machine: os                          # os | env
  over: enforce                        # enforce | report
  skew: 5m                             # clock skew tolerated, 0 to 1h

import { licence } from "mainsdk";

// 403 unless the licence in scope includes sso and is valid or in grace
licence.require("sso");

// "valid", "grace", "expired", "revoked", "suspended", "tampered" or "missing"
const { status, graceEndsAt } = licence.state();

import { it } from "node:test";
import assert from "node:assert/strict";
import { createClock, createTestApp, createTestLicenceCA } from "@mainsdk/testing";

const yaml = `schema: 1
project: prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY
licence:
  product: acme-desktop
  roots: ["ed25519:CvBKNOIhJSGvXg9chN9qV8-z6byK3-is6-12mXaidWQ"]
  features: [sso, audit-export]
`;
const ca = await createTestLicenceCA({ product: "acme-desktop", project: "prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY" });

it("turns sso off when the licence has no sso", async () => {
  // test licences start on 2026-11-01, so set the clock after that
  const app = createTestApp({ yaml, clock: createClock(Date.UTC(2026, 10, 1, 12)) });
  await app.licence.install(await ca.issue({ features: ["audit-export"] }), { scope: "app" });
  assert.equal(app.licence.has("sso"), false);
  assert.equal(app.licence.has("audit-export"), true);
  assert.throws(() => app.licence.require("sso"), { code: "MAIN-LICENCE-0001" });
});

it("refuses a licence with one changed byte", async () => {
  const app = createTestApp({ yaml, clock: createClock(Date.UTC(2026, 10, 1, 12)) });
  const bad = ca.tamper(await ca.issue(), "payload");
  await assert.rejects(app.licence.install(bad, { scope: "app" }), { code: "MAIN-LICENCE-0004" });
});

licence:
  driver: offline

Quick start

licence:
  product: acme-desktop
  roots: ["ed25519:CvBKNOIhJSGvXg9chN9qV8-z6byK3-is6-12mXaidWQ"]   # the well-known test root; pin your own in production
  file: ./main.licence
  features: [sso, audit-export]

import { licence } from "mainsdk";

export async function GET() {
  licence.require("sso");   // throws MAIN-LICENCE-0001 (403) unless the licence is valid or in grace and lists sso
  return Response.json({ ok: true });
}

use mainsdk::prelude::*;
let app = App::test();
let state = app.licence().state().await?;
assert_eq!(state.status, "missing");

Configuration

licence:
  driver: http                    # offline (default) | http | local
  product: acme-desktop           # must equal the licence's product; a-z, 0-9 and -, 1 to 64 characters
  roots:                          # pinned root public keys, 1 to 4
    - ed25519:CvBKNOIhJSGvXg9chN9qV8-z6byK3-is6-12mXaidWQ
  file: ./main.licence            # read at start; or token, not both
  # token: secret:MAINSDK_LICENCE
  trust: ./main.licence-trust     # optional: CA certificates and revocation lists
  features: [sso, audit-export, offline-sync]
  url: https://api.mainsdk.dev    # http driver only
  refresh: 6h
  skew: 5m
  over: enforce
  machine: os

An invalid section stops the app with MAIN-LICENCE-0011; mainsdk check finds it first. The full key list is in the main.yaml reference.

What you get

A customer gets a signed licence file, the way desktop and self-hosted software is sold. The key you pin is in main.yaml. Nothing calls home while a request runs. When a licence expires, or you revoke it and the app hears about it, licensed features keep working through a grace period and then turn off. The rest of the app keeps serving. It runs in your app and is free. Licensing explains how app licences differ from TAPS licences, API keys and entitlements.

Examples

Gate a feature

has returns a boolean from memory. require throws. Both are true only while the licence in scope is valid or in grace and lists the feature.

import { licence } from "mainsdk";

const showAudit = licence.has("audit-export");   // false when expired, revoked, tampered or missing
licence.require("sso");                          // MAIN-LICENCE-0001 with { feature, status, reason }

Read the state and the limits

state() returns the status, the reason, the dates and whether revocation data is fresh. limit(name) returns the licence's number, seats for "seats", or null. get() returns the verified claims, or null when the licence is missing or tampered.

import { licence } from "mainsdk";

const { status, reason, expiresAt, graceEndsAt, revocation } = licence.state();
const seats = licence.limit("seats");   // number | null
const claims = licence.get();           // claims.features, claims.plan, claims.taps ... or null
if (status === "grace") console.warn(`licence ends ${graceEndsAt} (${reason})`);

Watch for changes

watch(scope, fn) calls fn once per status change for the app ("app") or one tenant id, and returns an unsubscribe.

import { licence } from "mainsdk";

declare function notifyOwner(status: string, reason?: string): void;

const stop = licence.watch("app", (s) => {
  if (s.status !== "valid") notifyOwner(s.status, s.reason);
});
// stop() to unsubscribe

Status changes are worked out when the licence is read or installed. There is no timer, so fn runs on the next read, install or refresh after a status changes, not at the instant of expiry.

Install a licence

update(token, { scope? }) verifies a compact token, then stores it. A token that doesn't verify throws MAIN-LICENCE-0004 (400) and changes nothing. The caller needs the licence.manage permission. An app licence is installed outside a tenant or inside tenant.system(); a tenant licence (scope: "tenant") must name the current tenant. Anything else is MAIN-LICENCE-0016.

import { licence, tenant } from "mainsdk";

export async function installTenantLicence(tenantId: string, token: string) {
  return tenant.run(tenantId, () => licence.update(token, { scope: "tenant" }));
}

export async function installAppLicence(token: string) {
  return tenant.system("install licence", () => licence.update(token, { scope: "app" }));
}

An installed licence takes precedence over licence.file and licence.token while its seq is the highest. Tenant licences load at start and refresh from the runtime store.

Refresh and machine id

refresh() fetches new licences and revocation lists now. On the http driver it posts to the refresh endpoint; on offline it re-reads the files. It never throws for a network fault. machine() returns this machine's id, m_ and 32 hex digits, which you give your vendor for a machine-bound licence.

import { licence } from "mainsdk";

const state = await licence.refresh();
const id = await licence.machine();   // MAIN-LICENCE-0015 when the OS id can't be read

How a licence is checked

A licence file holds your licence, signed by an issuing CA, and the CA's certificate, signed by a root. The app pins the root, so the chain verifies with no network. Ed25519 and canonical JSON make any changed byte fail. A licence is accepted only if every step passes, in order: format, chain, signature, CA scope, test root, subject, environment and machine binding, then no rollback. The first failure decides the reason.

revocation in the state is fresh (the newest list for the licence's CA is before its nextUpdate), stale (past it) or none (never seen). A suspension is lifted by a later list that leaves the entry out. A revoked entry stays.

With entitlements and limits

A feature under licence.features is in a tenant's plan only when the plan includes it and the licence does. entitlements.require for such a feature throws MAIN-LICENCE-0001, not MAIN-PLAN-0001. A licence limit, or seats, that has the name of a plan limit or of a limits.quotas or limits.concurrency entry lowers it. It never raises it. A tenant licence with a plan is a plan source in entitlements, after a manual plan and before pay.

over: report covers plan-limit checks and quotas. Concurrency has no report mode: a concurrency ceiling from a licence always enforces.

Errors and checks

See check codes and errors for all of them.

Swapping drivers

The http driver refreshes only after the server listens: first within 60 seconds, then every licence.refresh, with exponential backoff from 1 minute on failure and at least Retry-After after a 429. The wire contract is POST {licence.url}/v1/licences/refresh. The answer is untrusted: every licence, certificate and list in it is verified like a file, and what fails is dropped and logged.

Testing

createTestLicenceCA() from @mainsdk/testing makes a CA under the well-known test root. It issues licences, rotates, revokes, writes signed lists and tampers with tokens. app.licence.install(token, { scope, tenant }) installs one under createTestApp() as the system would. createRefreshServer() is a fake refresh endpoint for the http driver, and buildLicenceFixtures() rebuilds the golden files in packages/testing/fixtures/licence/ byte for byte.

import { it } from "node:test";
import assert from "node:assert/strict";
import { createClock, createTestApp, createTestLicenceCA } from "@mainsdk/testing";

const yaml = `schema: 1
project: prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY
licence:
  product: acme-desktop
  roots: ["ed25519:CvBKNOIhJSGvXg9chN9qV8-z6byK3-is6-12mXaidWQ"]
  features: [sso, audit-export]
`;
const ca = await createTestLicenceCA({ product: "acme-desktop", project: "prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY" });

it("turns sso off when the licence has no sso", async () => {
  // test licences start on 2026-11-01, so set the clock after that
  const app = createTestApp({ yaml, clock: createClock(Date.UTC(2026, 10, 1, 12)) });
  await app.licence.install(await ca.issue({ features: ["audit-export"] }), { scope: "app" });
  assert.equal(app.licence.has("sso"), false);
  assert.equal(app.licence.has("audit-export"), true);
  assert.throws(() => app.licence.require("sso"), { code: "MAIN-LICENCE-0001" });
});

it("refuses a licence with one changed byte", async () => {
  const app = createTestApp({ yaml, clock: createClock(Date.UTC(2026, 10, 1, 12)) });
  const bad = ca.tamper(await ca.issue(), "payload");
  await assert.rejects(app.licence.install(bad, { scope: "app" }), { code: "MAIN-LICENCE-0004" });
});

From the shell, mainsdk licence verify and mainsdk licence show check a file. See the CLI and the testing kit.

Security and privacy

• has, require, state, limit and get read memory only: no store, file or network call, so a check adds no request-path latency.
• Verification uses the platform's WebCrypto and makes no network call. A licence signed directly by a root is tampered. The test root is refused in production.
• The app remembers the highest licence seq, the highest list number and the latest time it has seen. An older licence, an older list or a clock set backwards is refused and raises a security event.
• Logs, channels, problems and audit records carry the licence id, key ids and machine id, never the token, a signature or the raw machine source.
• Channels: mainsdk:licence.verify, .state, .check, .refresh and .over. Audit records: licence.installed, licence.renewed, licence.state_changed.

What it promises, and what it doesn't

A licence can't be forged or edited without a CA's private key. A CA can't exist without a pinned root's private key. An app that has seen a newer licence, a newer list or a later time can't be rolled back through any input the SDK reads. A network or clock fault never stops the app.

It doesn't stop someone who controls the machine. MainSDK is open source and runs on the customer's machine, so that person can patch the SDK, replace the pinned root, wipe the runtime store to forget the rollback marks, or keep the machine offline so a revocation never arrives. The seal reports changed files, but can be rewritten too. Machine binding stops a casual copy between machines; with machine: env the id is set by whoever runs the app. Licensing keeps honest customers honest and makes your terms auditable. Serve features worth stealing from a server you run.

FAQ

Does a licence check make a network call? No. Verification is offline. Only the http driver talks to your refresh endpoint, in the background after the server listens, and a failure never blocks a valid licence.

What happens when the licence expires? The state moves to grace, then expired. Only features under licence.features and licence limits turn off. The app starts and serves either way.

Who issues licences? Today, your own CA, or the testing kit for development. Issuing from MainSDK Cloud is planned for 0.6 (spec licence-cloud).

Next

• Licensing: app licences compared with TAPS licences, API keys and entitlements
• License your app: the steps, start to finish
• Plans and entitlements
• Rate limits and quotas

Helpers for wiring and tests