@carchalabs/licensekit-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bugra Omer Aydemir
+
+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.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @carchalabs/licensekit-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The lease format used by [LicenseKit](https://licensekit.carchalabs.com). A lease is a compact JSON Web Signature (RFC 7515) signed with Ed25519 (RFC 9864), with the header `typ: licensekit-lease+jwt` and a `kid` that is the RFC 7638 thumbprint of the signing key.
+
+Apps normally use [`@carchalabs/licensekit-electron`](https://www.npmjs.com/package/@carchalabs/licensekit-electron), which uses this package. Use it directly to sign leases on a server or to verify them in another runtime.
+
+```js
+const { generateSigningKeys, signLease, verifyLease, keySet } = require('@carchalabs/licensekit-core');
+
+const { privateKeyPem, publicKeyPem } = generateSigningKeys();
+const token = signLease(claims, privateKeyPem);
+const result = verifyLease(token, { keys: keySet([publicKeyPem]), product: 'my-app', fingerprintHash, now: Math.floor(Date.now() / 1000) });
+if (!result.ok) console.log(result.reason);
+```
+
+`verifyLease` accepts only Ed25519, selects the key by `kid`, and checks issuer, product, device, `nbf`, `exp` and the check-in deadline. Failure reasons are listed in the [documentation](https://licensekit.carchalabs.com/docs/#lease).
+
+Other exports: `keyId`, `publicJwk`, `publicKeyFromPrivate`, `decodeLease`, `hashFingerprint`, `generateLicenseKey`, `normalizeLicenseKey`, `hashLicenseKey`.
+
+Requires Node 22.13 or later. MIT License.

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { KeyObject } from 'node:crypto';
+export declare const LEASE_ALGORITHM = "Ed25519";
+export declare const LEASE_TYPE = "licensekit-lease+jwt";
+export declare const LEASE_ISSUER = "licensekit";
+export declare const DEFAULT_LEEWAY_SECONDS = 300;
+export interface LeaseHeader {
+    alg: string;
+    typ: string;
+    kid: string;
+}
+export interface LeaseClaims {
+    iss: string;
+    sub: string;
+    aud: string;
+    jti: string;
+    iat: number;
+    nbf: number;
+    exp?: number;
+    rev: number;
+    fp: string;
+    feat: string[];
+    cus?: string;
+    grc?: number;
+    mnt?: number;
+}
+export interface PublicJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+    kid: string;
+    alg: typeof LEASE_ALGORITHM;
+    use: 'sig';
+}
+export type LeaseFailure = 'malformed' | 'unsupported_algorithm' | 'wrong_type' | 'unknown_key' | 'bad_signature' | 'wrong_issuer' | 'wrong_product' | 'wrong_device' | 'not_yet_valid' | 'expired' | 'revalidation_required';
+export type LeaseVerifyResult = {
+    ok: true;
+    header: LeaseHeader;
+    claims: LeaseClaims;
+} | {
+    ok: false;
+    reason: LeaseFailure;
+    claims?: LeaseClaims;
+};
+export type KeyInput = string | KeyObject;
+export interface LeaseVerifyOptions {
+    keys: KeyInput[] | Map<string, KeyObject>;
+    product: string;
+    fingerprintHash: string;
+    issuer?: string;
+    now?: number;
+    graceSeconds?: number;
+    leewaySeconds?: number;
+}
+export declare function generateSigningKeys(): {
+    privateKeyPem: string;
+    publicKeyPem: string;
+};
+export declare function publicKeyFromPrivate(privateKeyPem: string): string;
+export declare function keyId(key: KeyInput): string;
+export declare function publicJwk(key: KeyInput): PublicJwk;
+export declare function keySet(keys: KeyInput[]): Map<string, KeyObject>;
+export declare function signLease(claims: LeaseClaims, privateKey: KeyInput): string;
+export declare function decodeLease(token: string): {
+    header: LeaseHeader;
+    claims: LeaseClaims;
+} | null;
+export declare function verifyLease(token: string, options: LeaseVerifyOptions): LeaseVerifyResult;
+export declare function hashFingerprint(rawFingerprint: string, product: string): string;
+export declare function generateLicenseKey(): string;
+export declare function normalizeLicenseKey(input: string): string;
+export declare function hashLicenseKey(input: string): string;
+export declare function legacyLicenseKeyHash(input: string): string;

package/dist/index.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LEEWAY_SECONDS = exports.LEASE_ISSUER = exports.LEASE_TYPE = exports.LEASE_ALGORITHM = void 0;
+exports.generateSigningKeys = generateSigningKeys;
+exports.publicKeyFromPrivate = publicKeyFromPrivate;
+exports.keyId = keyId;
+exports.publicJwk = publicJwk;
+exports.keySet = keySet;
+exports.signLease = signLease;
+exports.decodeLease = decodeLease;
+exports.verifyLease = verifyLease;
+exports.hashFingerprint = hashFingerprint;
+exports.generateLicenseKey = generateLicenseKey;
+exports.normalizeLicenseKey = normalizeLicenseKey;
+exports.hashLicenseKey = hashLicenseKey;
+exports.legacyLicenseKeyHash = legacyLicenseKeyHash;
+const node_crypto_1 = require("node:crypto");
+exports.LEASE_ALGORITHM = 'Ed25519';
+exports.LEASE_TYPE = 'licensekit-lease+jwt';
+exports.LEASE_ISSUER = 'licensekit';
+exports.DEFAULT_LEEWAY_SECONDS = 300;
+const toBase64Url = (buf) => buf.toString('base64url');
+const fromBase64Url = (text) => Buffer.from(text, 'base64url');
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+function asPrivateKey(key) {
+    return typeof key === 'string' ? (0, node_crypto_1.createPrivateKey)(key) : key;
+}
+function asPublicKey(key) {
+    if (typeof key === 'string')
+        return (0, node_crypto_1.createPublicKey)(key);
+    return key.type === 'private' ? (0, node_crypto_1.createPublicKey)(key) : key;
+}
+function generateSigningKeys() {
+    const { privateKey, publicKey } = (0, node_crypto_1.generateKeyPairSync)('ed25519');
+    return {
+        privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+        publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    };
+}
+function publicKeyFromPrivate(privateKeyPem) {
+    return (0, node_crypto_1.createPublicKey)((0, node_crypto_1.createPrivateKey)(privateKeyPem)).export({ type: 'spki', format: 'pem' }).toString();
+}
+function ed25519PublicX(key) {
+    const jwk = asPublicKey(key).export({ format: 'jwk' });
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') {
+        throw new Error('Only Ed25519 keys are supported');
+    }
+    return jwk.x;
+}
+function keyId(key) {
+    const canonical = JSON.stringify({ crv: 'Ed25519', kty: 'OKP', x: ed25519PublicX(key) });
+    return toBase64Url((0, node_crypto_1.createHash)('sha256').update(canonical, 'utf8').digest());
+}
+function publicJwk(key) {
+    return { kty: 'OKP', crv: 'Ed25519', x: ed25519PublicX(key), kid: keyId(key), alg: exports.LEASE_ALGORITHM, use: 'sig' };
+}
+function keySet(keys) {
+    const set = new Map();
+    for (const key of keys) {
+        const publicKey = asPublicKey(key);
+        set.set(keyId(publicKey), publicKey);
+    }
+    return set;
+}
+function signLease(claims, privateKey) {
+    const key = asPrivateKey(privateKey);
+    const header = { alg: exports.LEASE_ALGORITHM, typ: exports.LEASE_TYPE, kid: keyId(key) };
+    const signingInput = `${toBase64Url(Buffer.from(JSON.stringify(header), 'utf8'))}.${toBase64Url(Buffer.from(JSON.stringify(claims), 'utf8'))}`;
+    const signature = (0, node_crypto_1.sign)(null, Buffer.from(signingInput, 'ascii'), key);
+    return `${signingInput}.${toBase64Url(signature)}`;
+}
+function parseSegment(segment) {
+    if (!BASE64URL.test(segment))
+        return null;
+    try {
+        return JSON.parse(fromBase64Url(segment).toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isLeaseClaims(value) {
+    if (!isObject(value))
+        return false;
+    const strings = ['iss', 'sub', 'aud', 'jti', 'fp'].every((name) => typeof value[name] === 'string');
+    const numbers = ['iat', 'nbf', 'rev'].every((name) => Number.isFinite(value[name]));
+    const expiry = value.exp === undefined || Number.isFinite(value.exp);
+    const features = Array.isArray(value.feat) && value.feat.every((feature) => typeof feature === 'string');
+    const customer = value.cus === undefined || typeof value.cus === 'string';
+    const optionalTimes = ['grc', 'mnt'].every((name) => value[name] === undefined || (Number.isFinite(value[name]) && value[name] >= 0));
+    return strings && numbers && expiry && features && customer && optionalTimes;
+}
+function decodeLease(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    const header = parseSegment(parts[0]);
+    const claims = parseSegment(parts[1]);
+    if (!isObject(header) || !isLeaseClaims(claims))
+        return null;
+    return { header: header, claims };
+}
+function verifyLease(token, options) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts.some((part) => part.length === 0))
+        return { ok: false, reason: 'malformed' };
+    const [encodedHeader, encodedClaims, encodedSignature] = parts;
+    const header = parseSegment(encodedHeader);
+    if (!isObject(header))
+        return { ok: false, reason: 'malformed' };
+    if (header.alg !== exports.LEASE_ALGORITHM)
+        return { ok: false, reason: 'unsupported_algorithm' };
+    if (header.typ !== exports.LEASE_TYPE)
+        return { ok: false, reason: 'wrong_type' };
+    const keys = options.keys instanceof Map ? options.keys : keySet(options.keys);
+    const key = typeof header.kid === 'string' ? keys.get(header.kid) : undefined;
+    if (!key)
+        return { ok: false, reason: 'unknown_key' };
+    if (!BASE64URL.test(encodedSignature))
+        return { ok: false, reason: 'malformed' };
+    let signatureValid = false;
+    try {
+        signatureValid = (0, node_crypto_1.verify)(null, Buffer.from(`${encodedHeader}.${encodedClaims}`, 'ascii'), key, fromBase64Url(encodedSignature));
+    }
+    catch {
+        signatureValid = false;
+    }
+    if (!signatureValid)
+        return { ok: false, reason: 'bad_signature' };
+    const claims = parseSegment(encodedClaims);
+    if (!isLeaseClaims(claims))
+        return { ok: false, reason: 'malformed' };
+    if (claims.iss !== (options.issuer ?? exports.LEASE_ISSUER))
+        return { ok: false, reason: 'wrong_issuer', claims };
+    if (claims.aud !== options.product)
+        return { ok: false, reason: 'wrong_product', claims };
+    if (claims.fp !== options.fingerprintHash)
+        return { ok: false, reason: 'wrong_device', claims };
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    if (now + (options.leewaySeconds ?? exports.DEFAULT_LEEWAY_SECONDS) < claims.nbf)
+        return { ok: false, reason: 'not_yet_valid', claims };
+    if (claims.exp !== undefined && now >= claims.exp)
+        return { ok: false, reason: 'expired', claims };
+    if (now >= claims.rev + (options.graceSeconds ?? 0))
+        return { ok: false, reason: 'revalidation_required', claims };
+    return { ok: true, header: header, claims };
+}
+function hashFingerprint(rawFingerprint, product) {
+    return (0, node_crypto_1.createHash)('sha256').update(`licensekit:${product}:${rawFingerprint}`).digest('hex');
+}
+const CROCKFORD_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const LICENSE_KEY_PREFIX = 'LK';
+function generateLicenseKey() {
+    const bytes = (0, node_crypto_1.randomBytes)(16);
+    const body = Array.from(bytes, (byte) => CROCKFORD_ALPHABET[byte & 31]).join('');
+    return `${LICENSE_KEY_PREFIX}-${body.match(/.{4}/g).join('-')}`;
+}
+function normalizeLicenseKey(input) {
+    let body = input.toUpperCase().replace(/[\s-]/g, '');
+    if (body.startsWith(LICENSE_KEY_PREFIX))
+        body = body.slice(LICENSE_KEY_PREFIX.length);
+    body = body.replace(/[IL]/g, '1').replace(/O/g, '0');
+    const groups = body.match(/.{1,4}/g) ?? [];
+    return [LICENSE_KEY_PREFIX, ...groups].join('-');
+}
+function hashLicenseKey(input) {
+    return (0, node_crypto_1.createHash)('sha256').update(normalizeLicenseKey(input)).digest('hex');
+}
+function legacyLicenseKeyHash(input) {
+    return (0, node_crypto_1.createHash)('sha256').update(input.trim().toUpperCase()).digest('hex');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@carchalabs/licensekit-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "LicenseKit lease format: Ed25519-signed compact JWS, key sets and license keys",
+  "homepage": "https://licensekit.carchalabs.com/docs/",
+  "repository": { "type": "git", "url": "git+https://github.com/carcha-labs/licensekit-sdk.git", "directory": "packages/core" },
+  "bugs": { "url": "https://github.com/carcha-labs/licensekit-sdk/issues" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src", "!dist/**/*.test.*", "!src/**/*.test.ts"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "node --test dist/*.test.js"
+  },
+  "engines": { "node": ">=22.13" },
+  "publishConfig": { "access": "public" },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,234 @@
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign,
+  verify,
+  KeyObject,
+} from 'node:crypto';
+
+export const LEASE_ALGORITHM = 'Ed25519';
+export const LEASE_TYPE = 'licensekit-lease+jwt';
+export const LEASE_ISSUER = 'licensekit';
+export const DEFAULT_LEEWAY_SECONDS = 300;
+
+export interface LeaseHeader {
+  alg: string;
+  typ: string;
+  kid: string;
+}
+
+export interface LeaseClaims {
+  iss: string;
+  sub: string;
+  aud: string;
+  jti: string;
+  iat: number;
+  nbf: number;
+  exp?: number;
+  rev: number;
+  fp: string;
+  feat: string[];
+  cus?: string;
+  grc?: number;
+  mnt?: number;
+}
+
+export interface PublicJwk {
+  kty: 'OKP';
+  crv: 'Ed25519';
+  x: string;
+  kid: string;
+  alg: typeof LEASE_ALGORITHM;
+  use: 'sig';
+}
+
+export type LeaseFailure =
+  | 'malformed'
+  | 'unsupported_algorithm'
+  | 'wrong_type'
+  | 'unknown_key'
+  | 'bad_signature'
+  | 'wrong_issuer'
+  | 'wrong_product'
+  | 'wrong_device'
+  | 'not_yet_valid'
+  | 'expired'
+  | 'revalidation_required';
+
+export type LeaseVerifyResult =
+  | { ok: true; header: LeaseHeader; claims: LeaseClaims }
+  | { ok: false; reason: LeaseFailure; claims?: LeaseClaims };
+
+export type KeyInput = string | KeyObject;
+
+export interface LeaseVerifyOptions {
+  keys: KeyInput[] | Map<string, KeyObject>;
+  product: string;
+  fingerprintHash: string;
+  issuer?: string;
+  now?: number;
+  graceSeconds?: number;
+  leewaySeconds?: number;
+}
+
+const toBase64Url = (buf: Buffer) => buf.toString('base64url');
+const fromBase64Url = (text: string) => Buffer.from(text, 'base64url');
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+
+function asPrivateKey(key: KeyInput): KeyObject {
+  return typeof key === 'string' ? createPrivateKey(key) : key;
+}
+
+function asPublicKey(key: KeyInput): KeyObject {
+  if (typeof key === 'string') return createPublicKey(key);
+  return key.type === 'private' ? createPublicKey(key) : key;
+}
+
+export function generateSigningKeys(): { privateKeyPem: string; publicKeyPem: string } {
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+  return {
+    privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+    publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+  };
+}
+
+export function publicKeyFromPrivate(privateKeyPem: string): string {
+  return createPublicKey(createPrivateKey(privateKeyPem)).export({ type: 'spki', format: 'pem' }).toString();
+}
+
+function ed25519PublicX(key: KeyInput): string {
+  const jwk = asPublicKey(key).export({ format: 'jwk' });
+  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') {
+    throw new Error('Only Ed25519 keys are supported');
+  }
+  return jwk.x;
+}
+
+export function keyId(key: KeyInput): string {
+  const canonical = JSON.stringify({ crv: 'Ed25519', kty: 'OKP', x: ed25519PublicX(key) });
+  return toBase64Url(createHash('sha256').update(canonical, 'utf8').digest());
+}
+
+export function publicJwk(key: KeyInput): PublicJwk {
+  return { kty: 'OKP', crv: 'Ed25519', x: ed25519PublicX(key), kid: keyId(key), alg: LEASE_ALGORITHM, use: 'sig' };
+}
+
+export function keySet(keys: KeyInput[]): Map<string, KeyObject> {
+  const set = new Map<string, KeyObject>();
+  for (const key of keys) {
+    const publicKey = asPublicKey(key);
+    set.set(keyId(publicKey), publicKey);
+  }
+  return set;
+}
+
+export function signLease(claims: LeaseClaims, privateKey: KeyInput): string {
+  const key = asPrivateKey(privateKey);
+  const header: LeaseHeader = { alg: LEASE_ALGORITHM, typ: LEASE_TYPE, kid: keyId(key) };
+  const signingInput = `${toBase64Url(Buffer.from(JSON.stringify(header), 'utf8'))}.${toBase64Url(Buffer.from(JSON.stringify(claims), 'utf8'))}`;
+  const signature = sign(null, Buffer.from(signingInput, 'ascii'), key);
+  return `${signingInput}.${toBase64Url(signature)}`;
+}
+
+function parseSegment(segment: string): unknown {
+  if (!BASE64URL.test(segment)) return null;
+  try {
+    return JSON.parse(fromBase64Url(segment).toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isLeaseClaims(value: unknown): value is LeaseClaims {
+  if (!isObject(value)) return false;
+  const strings = ['iss', 'sub', 'aud', 'jti', 'fp'].every((name) => typeof value[name] === 'string');
+  const numbers = ['iat', 'nbf', 'rev'].every((name) => Number.isFinite(value[name]));
+  const expiry = value.exp === undefined || Number.isFinite(value.exp);
+  const features = Array.isArray(value.feat) && value.feat.every((feature) => typeof feature === 'string');
+  const customer = value.cus === undefined || typeof value.cus === 'string';
+  const optionalTimes = ['grc', 'mnt'].every((name) => value[name] === undefined || (Number.isFinite(value[name]) && (value[name] as number) >= 0));
+  return strings && numbers && expiry && features && customer && optionalTimes;
+}
+
+export function decodeLease(token: string): { header: LeaseHeader; claims: LeaseClaims } | null {
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  const header = parseSegment(parts[0]);
+  const claims = parseSegment(parts[1]);
+  if (!isObject(header) || !isLeaseClaims(claims)) return null;
+  return { header: header as unknown as LeaseHeader, claims };
+}
+
+export function verifyLease(token: string, options: LeaseVerifyOptions): LeaseVerifyResult {
+  const parts = token.split('.');
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) return { ok: false, reason: 'malformed' };
+  const [encodedHeader, encodedClaims, encodedSignature] = parts;
+
+  const header = parseSegment(encodedHeader);
+  if (!isObject(header)) return { ok: false, reason: 'malformed' };
+  if (header.alg !== LEASE_ALGORITHM) return { ok: false, reason: 'unsupported_algorithm' };
+  if (header.typ !== LEASE_TYPE) return { ok: false, reason: 'wrong_type' };
+
+  const keys = options.keys instanceof Map ? options.keys : keySet(options.keys);
+  const key = typeof header.kid === 'string' ? keys.get(header.kid) : undefined;
+  if (!key) return { ok: false, reason: 'unknown_key' };
+
+  if (!BASE64URL.test(encodedSignature)) return { ok: false, reason: 'malformed' };
+  let signatureValid = false;
+  try {
+    signatureValid = verify(null, Buffer.from(`${encodedHeader}.${encodedClaims}`, 'ascii'), key, fromBase64Url(encodedSignature));
+  } catch {
+    signatureValid = false;
+  }
+  if (!signatureValid) return { ok: false, reason: 'bad_signature' };
+
+  const claims = parseSegment(encodedClaims);
+  if (!isLeaseClaims(claims)) return { ok: false, reason: 'malformed' };
+
+  if (claims.iss !== (options.issuer ?? LEASE_ISSUER)) return { ok: false, reason: 'wrong_issuer', claims };
+  if (claims.aud !== options.product) return { ok: false, reason: 'wrong_product', claims };
+  if (claims.fp !== options.fingerprintHash) return { ok: false, reason: 'wrong_device', claims };
+
+  const now = options.now ?? Math.floor(Date.now() / 1000);
+  if (now + (options.leewaySeconds ?? DEFAULT_LEEWAY_SECONDS) < claims.nbf) return { ok: false, reason: 'not_yet_valid', claims };
+  if (claims.exp !== undefined && now >= claims.exp) return { ok: false, reason: 'expired', claims };
+  if (now >= claims.rev + (options.graceSeconds ?? 0)) return { ok: false, reason: 'revalidation_required', claims };
+
+  return { ok: true, header: header as unknown as LeaseHeader, claims };
+}
+
+export function hashFingerprint(rawFingerprint: string, product: string): string {
+  return createHash('sha256').update(`licensekit:${product}:${rawFingerprint}`).digest('hex');
+}
+
+const CROCKFORD_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const LICENSE_KEY_PREFIX = 'LK';
+
+export function generateLicenseKey(): string {
+  const bytes = randomBytes(16);
+  const body = Array.from(bytes, (byte) => CROCKFORD_ALPHABET[byte & 31]).join('');
+  return `${LICENSE_KEY_PREFIX}-${body.match(/.{4}/g)!.join('-')}`;
+}
+
+export function normalizeLicenseKey(input: string): string {
+  let body = input.toUpperCase().replace(/[\s-]/g, '');
+  if (body.startsWith(LICENSE_KEY_PREFIX)) body = body.slice(LICENSE_KEY_PREFIX.length);
+  body = body.replace(/[IL]/g, '1').replace(/O/g, '0');
+  const groups = body.match(/.{1,4}/g) ?? [];
+  return [LICENSE_KEY_PREFIX, ...groups].join('-');
+}
+
+export function hashLicenseKey(input: string): string {
+  return createHash('sha256').update(normalizeLicenseKey(input)).digest('hex');
+}
+
+export function legacyLicenseKeyHash(input: string): string {
+  return createHash('sha256').update(input.trim().toUpperCase()).digest('hex');
+}