@bhooai/nexus-crypto 2.0.15 → 2.0.16

package/package.json

@@ -1,17 +1,30 @@
 {
     "name": "@bhooai/nexus-crypto",
-    "version": "2.0.15",
+    "version": "2.0.16",
     "publishConfig": {
         "access": "public"
     },
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.ts",
+            "default": "./src/index.ts"
+        },
+        "./browser": {
+            "types": "./src/license-browser.ts",
+            "default": "./src/license-browser.ts"
+        },
+        "./package.json": "./package.json"
+    },
     "scripts": {
         "build": "tsc -p tsconfig.json",
         "test": "vitest run"
     },
-    "dependencies": {},
+    "dependencies": {
+        "jose": "^5.9.6"
+    },
     "devDependencies": {
         "@types/node": "^22.5.0",
         "typescript": "^5.6.2",

package/src/license-browser.ts

@@ -0,0 +1,59 @@
+/**
+ * Browser-safe license gate.
+ *
+ * The real key derivation in `./license.ts` needs Node's `crypto`/`fs`/`os`,
+ * so client bundles (the admin SPA, safe-goto) can't import it. This variant
+ * only asserts that a master key has been injected into the client by the
+ * host application — via `import.meta.env.VITE_NEXUS_LICENSE_KEY`,
+ * `globalThis.NEXUS_LICENSE_KEY`, `globalThis.__NEXUS_LICENSE_KEY__`, or
+ * `process.env.NEXUS_LICENSE_KEY` (bundler-injected).
+ *
+ * Keys are minted/verified by the authority at nexus-bhooai-com
+ * (`POST /api/license-verify`); the browser only consumes the key.
+ */
+
+export const LICENSE_ENV_VAR = 'NEXUS_LICENSE_KEY';
+
+/** Machine-readable license failure. Mirrors the Node `LicenseError`. */
+export class LicenseError extends Error {
+  readonly code = 'LICENSE_REQUIRED';
+  constructor(
+    packageName: string,
+    readonly hint = 'No license found — get a key at https://nexus.bhooai.com/account, then expose it to the app as VITE_NEXUS_LICENSE_KEY (or globalThis.NEXUS_LICENSE_KEY).',
+  ) {
+    super(`[${packageName}] ${hint}`);
+    this.name = 'LicenseError';
+  }
+}
+
+function readBrowserKey(): string | null {
+  const g = globalThis as unknown as Record<string, unknown>;
+  const env = (import.meta as unknown as { env?: Record<string, unknown> } | undefined)?.env;
+  const processEnv = (g.process as { env?: Record<string, unknown> } | undefined)?.env;
+  const candidates = [
+    env?.VITE_NEXUS_LICENSE_KEY,
+    env?.NEXUS_LICENSE_KEY,
+    g.NEXUS_LICENSE_KEY,
+    g.__NEXUS_LICENSE_KEY__,
+    processEnv?.NEXUS_LICENSE_KEY,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.trim()) return c.trim();
+  }
+  return null;
+}
+
+/** True when a master key is available to the client. */
+export function hasLicense(): boolean {
+  return readBrowserKey() !== null;
+}
+
+/**
+ * Gate for licensed client features. Returns the injected key, or throws a
+ * "add license first" LicenseError when none is exposed to the client.
+ */
+export function requireLicense(packageName: string): string {
+  const key = readBrowserKey();
+  if (!key) throw new LicenseError(packageName);
+  return key;
+}

package/src/license.ts

@@ -1,141 +1,297 @@
 /**
- * License core — one master key, per-package derived keys.
+ * License core — authority-signed tokens, verified online each run.
  *
- * Flow: the user pastes a master key (`nxl_…`, issued by nexus.bhooai.com)
- * once via `nexus license add`. Every package derives its own key from that
- * single master secret with HKDF-SHA256 (salt `bhooai-nexus/v1`, info =
- * package name), and gated features call `requireLicense()` which throws a
- * "add license first" error when no master key is present.
+ * The authority (nexus-bhooai-com) signs a compact JWS license token with a
+ * private key that never leaves the authority. This package only holds the
+ * *verification* side: it fetches the authority's public keys (JWKS), verifies
+ * the token signature offline, then confirms current validity with the
+ * authority online. A user cannot forge a valid token from this code — they
+ * would need the authority's private key.
  *
- * Master key lookup order: `NEXUS_LICENSE_KEY` env → `~/.nexus/license.json`
- * → `./.nexus-license.json` (project-local).
+ * Flow:
+ *   - `nexus license add` (browser) stores the token at
+ *     `<projectRoot>/license/license.jwt`.
+ *   - Each run calls `ensureLicense()`, which verifies the token (signature via
+ *     fetched JWKS + online status) and caches the result in memory for the run.
+ *   - Gated features call `requireLicense()` (sync, reads the in-memory result).
+ *
+ * Lookup order: `NEXUS_LICENSE_KEY` env (CI/containers) →
+ * `<projectRoot>/license/license.jwt`. The token is a bearer credential, so the
+ * `license/` folder should be gitignored.
  */
-import { hkdfSync, timingSafeEqual } from 'node:crypto';
-import { homedir } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from 'node:fs';
+import { createLocalJWKSet, jwtVerify, type JSONWebKeySet } from 'jose';
 
 export const LICENSE_ENV_VAR = 'NEXUS_LICENSE_KEY';
-export const LICENSE_FILE_NAME = 'license.json';
-export const LICENSE_DIR_NAME = '.nexus';
-export const PROJECT_LICENSE_FILE = '.nexus-license.json';
-export const HKDF_SALT = 'bhooai-nexus/v1';
-export const HKDF_LENGTH = 32;
+export const LICENSE_SERVER_ENV_VAR = 'NEXUS_LICENSE_SERVER';
+export const LICENSE_FILE_NAME = 'license.jwt';
+export const LICENSE_DIR_NAME = 'license';
+export const LICENSE_ISSUER = 'nexus-bhooai-com';
+
+/** Default authority. Override per-project/CI via `NEXUS_LICENSE_SERVER`. */
+export const DEFAULT_LICENSE_SERVER = 'https://nexus.bhooai.com';
+
+/** How long a fetched JWKS is cached in memory before re-fetching. */
+export const JWKS_TTL_MS = 60 * 60 * 1000;
+
+/** License token claims (subset we rely on). */
+export interface LicenseClaims {
+  iss?: string;
+  sub?: string;
+  kid?: string;
+  plan?: string;
+  seats?: number;
+  keyHash?: string;
+  iat?: number;
+  exp?: number;
+  jti?: string;
+  [k: string]: unknown;
+}
 
 /** Machine-readable license failure. Packages surface this at gated entry points. */
 export class LicenseError extends Error {
   readonly code = 'LICENSE_REQUIRED';
   constructor(
     packageName: string,
-    readonly hint = `No license found — run \`nexus license add <key>\` (get one at https://nexus.bhooai.com/account) and retry.`,
+    readonly hint = 'No valid license — run `nexus license add` (or set NEXUS_LICENSE_KEY to a signed license token) and retry.',
   ) {
     super(`[${packageName}] ${hint}`);
     this.name = 'LicenseError';
   }
 }
 
-export interface StoredLicense {
-  key: string;
-  addedAt: string;
-  server?: string;
+export type LicenseSource = 'env' | 'file';
+
+export interface ResolvedLicense {
+  token: string;
+  source: LicenseSource;
+  file?: string;
 }
 
-function licenseFileCandidates(projectDir?: string): string[] {
-  const files: string[] = [];
-  if (projectDir) files.push(join(projectDir, PROJECT_LICENSE_FILE));
-  try {
-    files.push(join(homedir(), LICENSE_DIR_NAME, LICENSE_FILE_NAME));
-  } catch {
-    // homedir() can throw in restricted environments — env + project file still work
-  }
-  return files;
+interface ResolveOptions {
+  projectDir?: string;
+  env?: NodeJS.ProcessEnv;
 }
 
-/** Read the stored master key file, or null when missing/unparseable. */
-export function readLicenseFile(path: string): StoredLicense | null {
-  try {
-    if (!existsSync(path)) return null;
-    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<StoredLicense>;
-    if (typeof raw.key !== 'string' || !raw.key) return null;
-    return { key: raw.key, addedAt: typeof raw.addedAt === 'string' ? raw.addedAt : '', server: raw.server };
-  } catch {
-    return null;
-  }
+/** Path to a project's license token file. */
+export function licenseFilePath(projectDir: string): string {
+  return join(projectDir, LICENSE_DIR_NAME, LICENSE_FILE_NAME);
 }
 
-/**
- * Resolve the master license key without touching the network.
- * Returns null when no key is configured anywhere.
- */
-export function loadMasterKey(opts: { projectDir?: string; env?: NodeJS.ProcessEnv } = {}): string | null {
+/** Resolve the license token and where it came from, without touching the network. */
+export function resolveLicenseToken(opts: ResolveOptions = {}): ResolvedLicense | null {
   const env = opts.env ?? process.env;
   const fromEnv = (env[LICENSE_ENV_VAR] ?? '').trim();
-  if (fromEnv) return fromEnv;
-  for (const file of licenseFileCandidates(opts.projectDir)) {
-    const stored = readLicenseFile(file);
-    if (stored) return stored.key;
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+
+  if (opts.projectDir) {
+    const file = licenseFilePath(opts.projectDir);
+    if (existsSync(file)) {
+      try {
+        const token = readFileSync(file, 'utf8').trim();
+        if (token) return { token, source: 'file', file };
+      } catch {
+        // unreadable → treated as no license
+      }
+    }
   }
   return null;
 }
 
-/** Persist a master key to `~/.nexus/license.json` (mode 0600). */
-export function saveMasterKey(key: string, opts: { server?: string } = {}): string {
-  const dir = join(homedir(), LICENSE_DIR_NAME);
+/** Store a signed token into the project's `license/` folder. */
+export function storeLicenseToken(projectDir: string, token: string): string {
+  const dir = join(projectDir, LICENSE_DIR_NAME);
   mkdirSync(dir, { recursive: true });
-  const path = join(dir, LICENSE_FILE_NAME);
-  writeFileSync(
-    path,
-    JSON.stringify({ key, addedAt: new Date().toISOString(), ...(opts.server ? { server: opts.server } : {}) }, null, 2),
-    'utf8',
-  );
+  const file = join(dir, LICENSE_FILE_NAME);
+  writeFileSync(file, token.trim() + '\n', 'utf8');
+  return file;
+}
+
+/** Remove a project's stored license token (and any legacy files). */
+export function removeLicense(projectDir: string): boolean {
+  const dir = join(projectDir, LICENSE_DIR_NAME);
+  let removed = false;
+  for (const name of [LICENSE_FILE_NAME, 'license.json', 'license.lic']) {
+    const p = join(dir, name);
+    if (existsSync(p)) {
+      rmSync(p);
+      removed = true;
+    }
+  }
+  const legacy = join(projectDir, '.nexus-license.json');
+  if (existsSync(legacy)) {
+    rmSync(legacy);
+    removed = true;
+  }
+  return removed;
+}
+
+/** Resolve the authority base URL (env override → default). */
+export function getLicenseServer(env: NodeJS.ProcessEnv = process.env): string {
+  return (env[LICENSE_SERVER_ENV_VAR] ?? '').trim().replace(/\/+$/, '') || DEFAULT_LICENSE_SERVER;
+}
+
+type LocalJwks = ReturnType<typeof createLocalJWKSet>;
+
+let jwksCache: { server: string; jwks: LocalJwks; fetchedAt: number } | null = null;
+
+/** Fetch (and memory-cache) the authority's public keys as a verifier. */
+export async function fetchLicenseJwks(
+  server: string,
+  fetchImpl: typeof fetch = fetch,
+  force = false,
+): Promise<LocalJwks> {
+  const base = server.replace(/\/+$/, '');
+  if (!force && jwksCache && jwksCache.server === base && Date.now() - jwksCache.fetchedAt < JWKS_TTL_MS) {
+    return jwksCache.jwks;
+  }
+  const url = `${base}/.well-known/nexus-license-jwks.json`;
+  let res: Response;
   try {
-    chmodSync(path, 0o600);
+    res = await fetchImpl(url, { headers: { accept: 'application/json' } });
   } catch {
-    // Windows ACLs — best effort
+    throw new Error(`Cannot reach the license authority at ${base} — check your connection.`);
   }
-  return path;
+  if (!res.ok) throw new Error(`License JWKS request failed (HTTP ${res.status}) from ${url}.`);
+  const body = (await res.json().catch(() => ({}))) as JSONWebKeySet;
+  const jwks = createLocalJWKSet(body);
+  jwksCache = { server: base, jwks, fetchedAt: Date.now() };
+  return jwks;
+}
+
+/** Verify a signed token's signature + issuer + expiry. Throws on failure. */
+export async function verifyLicenseToken(token: string, jwks: LocalJwks): Promise<LicenseClaims> {
+  const { payload } = await jwtVerify(token, jwks, { issuer: LICENSE_ISSUER });
+  return payload as LicenseClaims;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  plan?: string;
+  expiresAt?: string | null;
+  message?: string;
 }
 
-/** Remove the user-wide license file. Returns true when a file was removed. */
-export function removeMasterKey(): boolean {
+/** Confirm current validity with the authority (revocation, expiry, seats). */
+export async function verifyLicenseOnline(
+  server: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<VerifyResult> {
+  const url = `${server.replace(/\/+$/, '')}/api/license-verify`;
+  let res: Response;
   try {
-    const path = join(homedir(), LICENSE_DIR_NAME, LICENSE_FILE_NAME);
-    if (!existsSync(path)) return false;
-    rmSync(path);
-    return true;
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token }),
+    });
   } catch {
-    return false;
+    throw new Error(`Cannot reach the license server at ${server} — check your connection.`);
   }
+  const data = (await res.json().catch(() => ({}))) as Partial<VerifyResult> & { error?: { message?: string } };
+  if (!res.ok) throw new Error(data.error?.message ?? `License server responded with HTTP ${res.status}.`);
+  return { valid: !!data.valid, plan: data.plan, expiresAt: data.expiresAt ?? null, message: data.message };
+}
+
+/** Per-process license state, set by `ensureLicense()` at boot. */
+interface RunLicenseState {
+  status: 'valid' | 'invalid';
+  claims?: LicenseClaims;
+  message?: string;
+  checkedAt: number;
+}
+
+let runState: RunLicenseState | null = null;
+
+/** The verified claims for this run, or null when unlicensed/invalid. */
+export function getLicenseClaims(): LicenseClaims | null {
+  return runState?.status === 'valid' ? runState.claims ?? null : null;
+}
+
+/** The current license error message for this run, if any. */
+export function getLicenseError(): string | null {
+  return runState?.status === 'invalid' ? runState.message ?? 'Invalid license.' : null;
+}
+
+export interface EnsureLicenseOptions {
+  projectDir?: string;
+  server?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+  /** Force a JWKS re-fetch (ignore the memory cache). */
+  force?: boolean;
 }
 
 /**
- * Derive a package-specific key from the master secret (HKDF-SHA256).
- * Deterministic and one-way: packages never see each other's keys or the master.
+ * Operator escape hatch for the license authority itself. The authority issues
+ * licenses and cannot verify a token against itself at boot (its HTTP server is
+ * not listening yet), so it runs with `NEXUS_LICENSE_ISSUER=1`. This is a
+ * deployment flag — end-user projects should NOT set it.
  */
-export function derivePackageKey(masterKey: string, packageName: string): string {
-  if (!masterKey) throw new LicenseError(packageName);
-  return Buffer.from(hkdfSync('sha256', masterKey, HKDF_SALT, packageName, HKDF_LENGTH)).toString('hex');
+export function isLicenseIssuer(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.NEXUS_LICENSE_ISSUER ?? '').trim() === '1';
 }
 
-/** Fingerprint for display (first 12 chars) — safe to log, never the key. */
-export function keyFingerprint(key: string): string {
-  return key.slice(0, 12);
-}
+/**
+ * Verify the license once for this run: signature (via fetched JWKS) + online
+ * status with the authority. Caches the result in memory. Throws LicenseError
+ * when missing/invalid/revoked/unreachable (fail-closed).
+ */
+export async function ensureLicense(opts: EnsureLicenseOptions = {}): Promise<LicenseClaims> {
+  const env = opts.env ?? process.env;
+  if (isLicenseIssuer(env)) {
+    const claims: LicenseClaims = { iss: LICENSE_ISSUER, plan: 'issuer' };
+    runState = { status: 'valid', claims, checkedAt: Date.now() };
+    return claims;
+  }
+  const resolved = resolveLicenseToken({ projectDir: opts.projectDir, env });
+  if (!resolved) throw new LicenseError('nexus');
+
+  const server = (opts.server ?? getLicenseServer(env)).replace(/\/+$/, '');
+
+  let claims: LicenseClaims;
+  try {
+    const jwks = await fetchLicenseJwks(server, opts.fetchImpl, opts.force);
+    claims = await verifyLicenseToken(resolved.token, jwks);
+  } catch (err) {
+    const message = `Invalid license token: ${(err as Error).message}`;
+    runState = { status: 'invalid', message, checkedAt: Date.now() };
+    throw new LicenseError('nexus', `${message} Run \`nexus license add\` to get a valid one.`);
+  }
 
-/** Constant-time master-key comparison (for tests/tools, not for secret storage). */
-export function keysEqual(a: string, b: string): boolean {
-  const ab = Buffer.from(a);
-  const bb = Buffer.from(b);
-  if (ab.length !== bb.length) return false;
-  return timingSafeEqual(ab, bb);
+  let online: VerifyResult;
+  try {
+    online = await verifyLicenseOnline(server, resolved.token, opts.fetchImpl);
+  } catch (err) {
+    const message = `Could not verify license with ${server}: ${(err as Error).message}`;
+    runState = { status: 'invalid', message, checkedAt: Date.now() };
+    throw new LicenseError('nexus', message);
+  }
+  if (!online.valid) {
+    const reason = (online.message ?? 'invalid key').replace(/\.\s*$/, '');
+    const message = `License rejected by ${server}: ${reason}.`;
+    runState = { status: 'invalid', message, checkedAt: Date.now() };
+    throw new LicenseError('nexus', `${message} Run \`nexus license add\` with a valid license.`);
+  }
+
+  runState = { status: 'valid', claims, checkedAt: Date.now() };
+  return claims;
 }
 
 /**
- * Gate for licensed features. Returns the derived package key, or throws a
- * "add license first" LicenseError when no master key is configured.
+ * Gate for licensed features. Sync — reads the in-memory result set by
+ * `ensureLicense()` at boot. Throws LicenseError when not licensed.
  */
-export function requireLicense(packageName: string, opts: { projectDir?: string } = {}): string {
-  const master = loadMasterKey({ projectDir: opts.projectDir });
-  if (!master) throw new LicenseError(packageName);
-  return derivePackageKey(master, packageName);
+export function requireLicense(packageName: string): void {
+  if (isLicenseIssuer()) return;
+  if (runState?.status === 'valid') return;
+  throw new LicenseError(packageName, runState?.message ? `${runState.message} Run \`nexus license add\`.` : undefined);
+}
+
+/** Test/tooling helper — clear the in-memory run state. */
+export function resetLicenseState(): void {
+  runState = null;
+  jwksCache = null;
 }

package/tests/license.test.ts

@@ -1,97 +1,185 @@
-import { describe, it, expect } from 'vitest';
-import { hkdfSync } from 'node:crypto';
+import { describe, it, expect, beforeAll } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { generateKeyPair, exportJWK, SignJWT, type KeyLike } from 'jose';
 import {
-  derivePackageKey,
+  ensureLicense,
   requireLicense,
-  loadMasterKey,
-  keyFingerprint,
-  keysEqual,
+  resolveLicenseToken,
+  storeLicenseToken,
+  removeLicense,
+  verifyLicenseToken,
+  fetchLicenseJwks,
+  resetLicenseState,
+  licenseFilePath,
+  getLicenseServer,
   LicenseError,
   LICENSE_ENV_VAR,
+  LICENSE_SERVER_ENV_VAR,
+  LICENSE_ISSUER,
 } from '../src/license.js';
 
-describe('hkdf primitive (RFC 5869 test case 1, SHA-256)', () => {
-  it('matches the RFC vector', () => {
-    const ikm = Buffer.alloc(22, 0x0b);
-    const salt = Buffer.from('000102030405060708090a0b0c', 'hex');
-    const info = Buffer.from('f0f1f2f3f4f5f6f7f8f9', 'hex');
-    const okm = Buffer.from(hkdfSync('sha256', ikm, salt, info, 42)).toString('hex');
-    expect(okm).toBe(
-      '3cb25f25faacd57a90434f64d0362f2a' + '2d2d0a90cf1a5a4c5db02d56ecc4c5bf' + '34007208d5b887185865',
-    );
-  });
-});
+const SERVER = 'http://auth.test';
+const NO_HOME = '/nonexistent-home-xyz';
+
+let privateKey: KeyLike;
+let publicJwk: Record<string, unknown>;
+
+async function signToken(opts: { key?: KeyLike; kid?: string; expires?: string } = {}): Promise<string> {
+  const key = opts.key ?? privateKey;
+  return new SignJWT({ plan: 'pro', seats: 1 })
+    .setProtectedHeader({ alg: 'EdDSA', kid: opts.kid ?? 'k1' })
+    .setIssuer(LICENSE_ISSUER)
+    .setIssuedAt()
+    .setExpirationTime(opts.expires ?? '1h')
+    .sign(key);
+}
+
+/** Stub fetch: JWKS endpoint + online verify (overridable). */
+function stubFetch(opts: { online?: unknown } = {}): typeof fetch {
+  return (async (url: string) => {
+    if (url.includes('/.well-known/nexus-license-jwks.json')) {
+      return { ok: true, status: 200, json: async () => ({ keys: [publicJwk] }) } as unknown as Response;
+    }
+    if (url.includes('/api/license-verify')) {
+      return { ok: true, status: 200, json: async () => opts.online ?? { valid: true, plan: 'pro' } } as unknown as Response;
+    }
+    return { ok: false, status: 404, json: async () => ({}) } as unknown as Response;
+  }) as unknown as typeof fetch;
+}
 
-describe('derivePackageKey', () => {
-  const master = 'nxl_test_master_key_001';
+function withTokenFile(token: string): string {
+  const dir = mkdtempSync(join(tmpdir(), 'nexus-lic-'));
+  storeLicenseToken(dir, token);
+  return dir;
+}
 
-  it('is deterministic', () => {
-    expect(derivePackageKey(master, 'nexus-payments')).toBe(derivePackageKey(master, 'nexus-payments'));
+beforeAll(async () => {
+  const pair = await generateKeyPair('EdDSA', { crv: 'Ed25519', extractable: true });
+  privateKey = pair.privateKey;
+  publicJwk = { ...(await exportJWK(pair.publicKey)), kid: 'k1', alg: 'EdDSA', use: 'sig' };
+});
+
+describe('resolveLicenseToken / storage', () => {
+  it('prefers the env token', () => {
+    expect(resolveLicenseToken({ env: { [LICENSE_ENV_VAR]: 'env-token' } as NodeJS.ProcessEnv })?.source).toBe('env');
   });
 
-  it('isolates packages (32-byte hex each)', () => {
-    const a = derivePackageKey(master, 'nexus-payments');
-    const b = derivePackageKey(master, 'nexus-ai-client');
-    expect(a).toHaveLength(64);
-    expect(b).toHaveLength(64);
-    expect(a).not.toBe(b);
+  it('reads the project license file', () => {
+    const dir = withTokenFile('file-token');
+    try {
+      const r = resolveLicenseToken({ projectDir: dir, env: {} as NodeJS.ProcessEnv });
+      expect(r?.token).toBe('file-token');
+      expect(r?.source).toBe('file');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
   });
 
-  it('throws LicenseError on empty master', () => {
-    expect(() => derivePackageKey('', 'nexus-payments')).toThrowError(LicenseError);
+  it('stores and removes the project license', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'nexus-lic-'));
     try {
-      derivePackageKey('', 'nexus-payments');
-    } catch (e) {
-      expect((e as Error).message).toContain('nexus license add');
+      storeLicenseToken(dir, 'tok');
+      expect(existsSync(licenseFilePath(dir))).toBe(true);
+      expect(readFileSync(licenseFilePath(dir), 'utf8').trim()).toBe('tok');
+      expect(removeLicense(dir)).toBe(true);
+      expect(existsSync(licenseFilePath(dir))).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
     }
   });
 });
 
-describe('loadMasterKey / requireLicense', () => {
-  it('prefers the env var', () => {
-    expect(loadMasterKey({ env: { [LICENSE_ENV_VAR]: 'nxl_from_env' } as NodeJS.ProcessEnv })).toBe('nxl_from_env');
+describe('ensureLicense (signed token + online)', () => {
+  it('accepts a valid token and marks the run licensed', async () => {
+    resetLicenseState();
+    const dir = withTokenFile(await signToken());
+    try {
+      const claims = await ensureLicense({ projectDir: dir, server: SERVER, fetchImpl: stubFetch(), force: true });
+      expect(claims.plan).toBe('pro');
+      expect(() => requireLicense('nexus-ai-client')).not.toThrow();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+      resetLicenseState();
+    }
+  });
+
+  it('rejects a forged token (wrong signing key)', async () => {
+    resetLicenseState();
+    const other = await generateKeyPair('EdDSA', { crv: 'Ed25519', extractable: true });
+    const dir = withTokenFile(await signToken({ key: other.privateKey }));
+    try {
+      await expect(ensureLicense({ projectDir: dir, server: SERVER, fetchImpl: stubFetch(), force: true })).rejects.toThrowError(LicenseError);
+      expect(() => requireLicense('nexus-ai-client')).toThrowError(/Invalid license/i);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+      resetLicenseState();
+    }
+  });
+
+  it('rejects an expired token', async () => {
+    resetLicenseState();
+    const dir = withTokenFile(await signToken({ expires: '-1h' }));
+    try {
+      await expect(ensureLicense({ projectDir: dir, server: SERVER, fetchImpl: stubFetch(), force: true })).rejects.toThrowError(LicenseError);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+      resetLicenseState();
+    }
   });
 
-  it('returns null when nothing is configured', () => {
-    expect(
-      loadMasterKey({ env: {} as NodeJS.ProcessEnv, projectDir: '/nonexistent-dir-xyz' }),
-    ).toBeNull();
+  it('rejects a raw (non-JWS) env value', async () => {
+    resetLicenseState();
+    await expect(
+      ensureLicense({ server: SERVER, env: { [LICENSE_ENV_VAR]: 'K8NK-M4SA-ECU4-400K' } as NodeJS.ProcessEnv, fetchImpl: stubFetch(), force: true }),
+    ).rejects.toThrowError(LicenseError);
   });
 
-  it('requireLicense throws the add-first error without a key', () => {
-    const prev = process.env[LICENSE_ENV_VAR];
-    delete process.env[LICENSE_ENV_VAR];
+  it('rejects when the authority says invalid (revoked)', async () => {
+    resetLicenseState();
+    const dir = withTokenFile(await signToken());
     try {
-      expect(() => requireLicense('nexus-payments', { projectDir: '/nonexistent-dir-xyz' })).toThrowError(
-        /nexus license add/,
-      );
+      await expect(
+        ensureLicense({ projectDir: dir, server: SERVER, fetchImpl: stubFetch({ online: { valid: false, message: 'License has been revoked.' } }), force: true }),
+      ).rejects.toThrowError(/rejected/i);
     } finally {
-      if (prev !== undefined) process.env[LICENSE_ENV_VAR] = prev;
+      rmSync(dir, { recursive: true, force: true });
+      resetLicenseState();
     }
   });
 
-  it('requireLicense derives from the env key', () => {
-    const prev = process.env[LICENSE_ENV_VAR];
-    process.env[LICENSE_ENV_VAR] = 'nxl_env_master';
+  it('fails closed when the authority is unreachable', async () => {
+    resetLicenseState();
+    const dir = withTokenFile(await signToken());
+    const downFetch = (async (url: string) => {
+      if (url.includes('jwks')) return { ok: true, status: 200, json: async () => ({ keys: [publicJwk] }) } as unknown as Response;
+      throw new Error('network down');
+    }) as unknown as typeof fetch;
     try {
-      expect(requireLicense('nexus-payments')).toBe(derivePackageKey('nxl_env_master', 'nexus-payments'));
+      await expect(ensureLicense({ projectDir: dir, server: SERVER, fetchImpl: downFetch, force: true })).rejects.toThrowError(/Could not verify/i);
     } finally {
-      if (prev !== undefined) process.env[LICENSE_ENV_VAR] = prev;
-      else delete process.env[LICENSE_ENV_VAR];
+      rmSync(dir, { recursive: true, force: true });
+      resetLicenseState();
     }
   });
+
+  it('throws when no license is configured', async () => {
+    resetLicenseState();
+    await expect(ensureLicense({ projectDir: NO_HOME, env: {} as NodeJS.ProcessEnv, fetchImpl: stubFetch() })).rejects.toThrowError(LicenseError);
+  });
 });
 
-describe('helpers', () => {
-  it('fingerprints without leaking the key', () => {
-    const fp = keyFingerprint('nxl_abcdefghijklmnop');
-    expect(fp).toHaveLength(12);
-    expect('nxl_abcdefghijklmnop').toContain(fp);
+describe('token primitives', () => {
+  it('verifies a token signature against the JWKS', async () => {
+    const jwks = await fetchLicenseJwks(SERVER, stubFetch(), true);
+    const claims = await verifyLicenseToken(await signToken(), jwks);
+    expect(claims.iss).toBe(LICENSE_ISSUER);
+    expect(claims.plan).toBe('pro');
   });
 
-  it('compares in constant time', () => {
-    expect(keysEqual('abc', 'abc')).toBe(true);
-    expect(keysEqual('abc', 'abd')).toBe(false);
-    expect(keysEqual('abc', 'abcd')).toBe(false);
+  it('honours the NEXUS_LICENSE_SERVER env override', () => {
+    expect(getLicenseServer({ [LICENSE_SERVER_ENV_VAR]: 'http://custom:9/' } as NodeJS.ProcessEnv)).toBe('http://custom:9');
+    expect(getLicenseServer({} as NodeJS.ProcessEnv)).toContain('nexus.bhooai.com');
   });
 });