@bhooai/nexus-crypto 2.0.13 → 2.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-crypto",
-    "version": "2.0.13",
+    "version": "2.0.15",
     "publishConfig": {
         "access": "public"
     },

package/src/index.ts

@@ -2,4 +2,5 @@ export * from './der.js';
 export * from './keypair.js';
 export * from './x509.js';
 export * from './csr.js';
-export * from './https.js';
+export * from './https.js';
+export * from './license.js';

package/src/license.ts

@@ -0,0 +1,141 @@
+/**
+ * License core — one master key, per-package derived keys.
+ *
+ * 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.
+ *
+ * Master key lookup order: `NEXUS_LICENSE_KEY` env → `~/.nexus/license.json`
+ * → `./.nexus-license.json` (project-local).
+ */
+import { hkdfSync, timingSafeEqual } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from 'node:fs';
+
+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;
+
+/** 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.`,
+  ) {
+    super(`[${packageName}] ${hint}`);
+    this.name = 'LicenseError';
+  }
+}
+
+export interface StoredLicense {
+  key: string;
+  addedAt: string;
+  server?: 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;
+}
+
+/** 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;
+  }
+}
+
+/**
+ * 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 {
+  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;
+  }
+  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);
+  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',
+  );
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Windows ACLs — best effort
+  }
+  return path;
+}
+
+/** Remove the user-wide license file. Returns true when a file was removed. */
+export function removeMasterKey(): boolean {
+  try {
+    const path = join(homedir(), LICENSE_DIR_NAME, LICENSE_FILE_NAME);
+    if (!existsSync(path)) return false;
+    rmSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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.
+ */
+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');
+}
+
+/** Fingerprint for display (first 12 chars) — safe to log, never the key. */
+export function keyFingerprint(key: string): string {
+  return key.slice(0, 12);
+}
+
+/** 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);
+}
+
+/**
+ * Gate for licensed features. Returns the derived package key, or throws a
+ * "add license first" LicenseError when no master key is configured.
+ */
+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);
+}

package/tests/license.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { hkdfSync } from 'node:crypto';
+import {
+  derivePackageKey,
+  requireLicense,
+  loadMasterKey,
+  keyFingerprint,
+  keysEqual,
+  LicenseError,
+  LICENSE_ENV_VAR,
+} 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',
+    );
+  });
+});
+
+describe('derivePackageKey', () => {
+  const master = 'nxl_test_master_key_001';
+
+  it('is deterministic', () => {
+    expect(derivePackageKey(master, 'nexus-payments')).toBe(derivePackageKey(master, 'nexus-payments'));
+  });
+
+  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('throws LicenseError on empty master', () => {
+    expect(() => derivePackageKey('', 'nexus-payments')).toThrowError(LicenseError);
+    try {
+      derivePackageKey('', 'nexus-payments');
+    } catch (e) {
+      expect((e as Error).message).toContain('nexus license add');
+    }
+  });
+});
+
+describe('loadMasterKey / requireLicense', () => {
+  it('prefers the env var', () => {
+    expect(loadMasterKey({ env: { [LICENSE_ENV_VAR]: 'nxl_from_env' } as NodeJS.ProcessEnv })).toBe('nxl_from_env');
+  });
+
+  it('returns null when nothing is configured', () => {
+    expect(
+      loadMasterKey({ env: {} as NodeJS.ProcessEnv, projectDir: '/nonexistent-dir-xyz' }),
+    ).toBeNull();
+  });
+
+  it('requireLicense throws the add-first error without a key', () => {
+    const prev = process.env[LICENSE_ENV_VAR];
+    delete process.env[LICENSE_ENV_VAR];
+    try {
+      expect(() => requireLicense('nexus-payments', { projectDir: '/nonexistent-dir-xyz' })).toThrowError(
+        /nexus license add/,
+      );
+    } finally {
+      if (prev !== undefined) process.env[LICENSE_ENV_VAR] = prev;
+    }
+  });
+
+  it('requireLicense derives from the env key', () => {
+    const prev = process.env[LICENSE_ENV_VAR];
+    process.env[LICENSE_ENV_VAR] = 'nxl_env_master';
+    try {
+      expect(requireLicense('nexus-payments')).toBe(derivePackageKey('nxl_env_master', 'nexus-payments'));
+    } finally {
+      if (prev !== undefined) process.env[LICENSE_ENV_VAR] = prev;
+      else delete process.env[LICENSE_ENV_VAR];
+    }
+  });
+});
+
+describe('helpers', () => {
+  it('fingerprints without leaking the key', () => {
+    const fp = keyFingerprint('nxl_abcdefghijklmnop');
+    expect(fp).toHaveLength(12);
+    expect('nxl_abcdefghijklmnop').toContain(fp);
+  });
+
+  it('compares in constant time', () => {
+    expect(keysEqual('abc', 'abc')).toBe(true);
+    expect(keysEqual('abc', 'abd')).toBe(false);
+    expect(keysEqual('abc', 'abcd')).toBe(false);
+  });
+});