@ornexus/neocortex 4.0.1

package/packages/client/dist/license/license-client.js

@@ -0,0 +1,257 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - License Client
+ *
+ * Manages license activation, JWT token caching, and proactive refresh.
+ * Integrates with the IP Protection Server's license endpoints and
+ * uses EncryptedCache for persistent token storage.
+ *
+ * Story 31.01: REFRESH_THRESHOLD_S fixed from 3600 to 300 (5 min)
+ * Story 31.02: Refresh token support (store, use, rotate)
+ * Story 31.03: Refresh token persistence in EncryptedCache
+ *
+ * NEVER throws exceptions - returns null on failure (graceful degradation).
+ */
+import { decodeJwt } from 'jose';
+import { NoOpCache } from '../types/index.js';
+import { getMachineFingerprint } from '../machine/fingerprint.js';
+// ── Constants ────────────────────────────────────────────────────────────
+const CACHE_KEY = 'neocortex:jwt:token';
+const REFRESH_CACHE_KEY = 'neocortex:jwt:refresh_token';
+const REFRESH_THRESHOLD_S = 300; // 5 minutes before expiry
+const REFRESH_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days (matches server REFRESH_TOKEN_TTL_DAYS)
+const DEFAULT_CLIENT_VERSION = '0.1.0';
+// ── LicenseClient ────────────────────────────────────────────────────────
+export class LicenseClient {
+    serverUrl;
+    licenseKey;
+    cache;
+    clientVersion;
+    machineId;
+    token = null;
+    refreshToken = null;
+    constructor(options) {
+        this.serverUrl = options.serverUrl.replace(/\/+$/, '');
+        this.licenseKey = options.licenseKey;
+        this.cache = options.cacheProvider ?? new NoOpCache();
+        this.clientVersion = options.clientVersion ?? DEFAULT_CLIENT_VERSION;
+        this.machineId = getMachineFingerprint();
+    }
+    /**
+     * Get a valid JWT token. Checks memory, cache, refresh token, then activation.
+     * NEVER throws - returns null on failure.
+     *
+     * Flow:
+     * 1. in-memory JWT valid? -> return
+     * 2. in-memory JWT needs-refresh? -> refresh(refresh_token) -> return
+     * 3. cached JWT valid? -> return
+     * 4. cached JWT needs-refresh? -> refresh(refresh_token) -> return
+     * 5. cached refresh_token exists? -> refresh(refresh_token) -> return  (Story 31.02)
+     * 6. activate() -> return
+     */
+    async getToken() {
+        try {
+            // 1. Check in-memory token
+            if (this.token) {
+                const validity = this.checkTokenValidity(this.token);
+                if (validity === 'valid')
+                    return this.token;
+                if (validity === 'needs-refresh') {
+                    const refreshed = await this.refresh();
+                    return refreshed?.token ?? this.token; // fallback to current if refresh fails
+                }
+                // expired or invalid - clear memory
+                this.token = null;
+            }
+            // 2. Check JWT cache
+            const cached = await this.loadFromCache();
+            if (cached) {
+                this.token = cached;
+                const validity = this.checkTokenValidity(cached);
+                if (validity === 'valid')
+                    return cached;
+                if (validity === 'needs-refresh') {
+                    const refreshed = await this.refresh();
+                    return refreshed?.token ?? cached; // fallback to current if refresh fails
+                }
+                // expired - clear
+                this.token = null;
+            }
+            // 3. Try refresh with cached refresh_token (Story 31.02/31.03)
+            // Lazy load refresh_token from cache if not in memory
+            if (!this.refreshToken) {
+                this.refreshToken = await this.loadRefreshTokenFromCache();
+            }
+            if (this.refreshToken) {
+                const refreshed = await this.refresh();
+                if (refreshed?.token)
+                    return refreshed.token;
+            }
+            // 4. Activate (last resort)
+            const result = await this.activate();
+            return result?.token ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Activate the license by calling POST /api/v1/license/activate.
+     * Stores token and refresh_token in memory and cache on success.
+     * NEVER throws - returns null on failure.
+     */
+    async activate() {
+        try {
+            const response = await fetch(`${this.serverUrl}/api/v1/license/activate`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    license_key: this.licenseKey,
+                    machine_id: this.machineId,
+                    client_version: this.clientVersion,
+                }),
+            });
+            if (!response.ok)
+                return null;
+            const data = (await response.json());
+            this.token = data.token;
+            this.refreshToken = data.refresh_token ?? null;
+            // Persist JWT to cache (fire-and-forget)
+            this.cache.set(CACHE_KEY, data.token, data.expires_in * 1000).catch(() => { });
+            // Persist refresh token with 7-day TTL (fire-and-forget)
+            if (data.refresh_token) {
+                this.cache.set(REFRESH_CACHE_KEY, data.refresh_token, REFRESH_TOKEN_TTL_MS).catch(() => { });
+            }
+            return {
+                token: data.token,
+                expiresIn: data.expires_in,
+                refreshToken: data.refresh_token,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Refresh using refresh_token by calling POST /api/v1/license/refresh.
+     * Sends refresh_token in body (no Authorization header needed).
+     * Handles token rotation: stores the new refresh_token from response.
+     * NEVER throws - returns null on failure.
+     *
+     * Story 31.02: Signature changed from refresh(currentToken) to refresh().
+     * The refresh_token in the body is the credential, not the JWT.
+     *
+     * @param _currentToken - Deprecated. Kept for backward compat but ignored.
+     */
+    async refresh(_currentToken) {
+        try {
+            // Load refresh_token: in-memory first, then cache
+            const rt = this.refreshToken ?? await this.loadRefreshTokenFromCache();
+            if (!rt) {
+                // No refresh token available -- cannot use new flow
+                return null;
+            }
+            const response = await fetch(`${this.serverUrl}/api/v1/license/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refresh_token: rt }),
+            });
+            if (!response.ok) {
+                // Refresh token invalid/expired -- clear it
+                this.refreshToken = null;
+                this.cache.set(REFRESH_CACHE_KEY, '', 1).catch(() => { }); // expire immediately
+                return null;
+            }
+            const data = (await response.json());
+            this.token = data.token;
+            // Token rotation: server issues new refresh token
+            this.refreshToken = data.refresh_token ?? null;
+            // Persist JWT to cache (fire-and-forget)
+            this.cache.set(CACHE_KEY, data.token, data.expires_in * 1000).catch(() => { });
+            // Persist rotated refresh token (fire-and-forget)
+            if (data.refresh_token) {
+                this.cache.set(REFRESH_CACHE_KEY, data.refresh_token, REFRESH_TOKEN_TTL_MS).catch(() => { });
+            }
+            return {
+                token: data.token,
+                expiresIn: data.expires_in,
+                refreshToken: data.refresh_token,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Force-refresh the token.
+     * Used when tier_changed is detected or a 401 response indicates the token is expired.
+     * Falls back to re-activation if refresh fails.
+     * NEVER throws - returns new token or null on failure.
+     *
+     * Story 18.8: Updated to prefer refresh over re-activate (preserves updated tier).
+     * Story 31.02: Uses refresh_token flow instead of JWT-based refresh.
+     */
+    async forceRefresh() {
+        try {
+            // 1. Try refresh with refresh_token first
+            const refreshResult = await this.refresh();
+            if (refreshResult?.token)
+                return refreshResult.token;
+            // 2. Refresh failed -- clear everything and re-activate
+            this.token = null;
+            this.refreshToken = null;
+            await this.cache.clear().catch(() => { });
+            const result = await this.activate();
+            return result?.token ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Private Methods ─────────────────────────────────────────────────
+    checkTokenValidity(token) {
+        try {
+            const payload = decodeJwt(token);
+            if (!payload.exp)
+                return 'expired';
+            const now = Math.floor(Date.now() / 1000);
+            if (payload.exp <= now)
+                return 'expired';
+            if (payload.exp - now <= REFRESH_THRESHOLD_S)
+                return 'needs-refresh';
+            return 'valid';
+        }
+        catch {
+            return 'expired';
+        }
+    }
+    async loadFromCache() {
+        try {
+            return await this.cache.get(CACHE_KEY);
+        }
+        catch {
+            return null;
+        }
+    }
+    async loadRefreshTokenFromCache() {
+        try {
+            const rt = await this.cache.get(REFRESH_CACHE_KEY);
+            // Guard against empty/expired entries
+            return rt && rt.length > 0 ? rt : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/packages/client/dist/machine/fingerprint.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * Generate a hardware-based fingerprint (not persisted).
+ * This is the original computation used as fallback and for seeding.
+ *
+ * @returns 64-character hex string (SHA-256 digest)
+ */
+export declare function computeHardwareFingerprint(): string;
+/**
+ * Generate a stable machine fingerprint as a SHA-256 hex digest.
+ *
+ * Story P26.01: On first call, generates from hardware and persists to
+ * ~/.neocortex/.machine-id. On subsequent calls, reads from disk.
+ * This ensures the fingerprint remains stable even if hardware attributes
+ * change (e.g., USB NIC added/removed, hostname change).
+ *
+ * Backward compat: if config.json has machineId, uses that to seed .machine-id.
+ *
+ * Fail-open: if disk operations fail, falls back to hardware-generated fingerprint.
+ *
+ * @returns 64-character hex string (SHA-256 digest)
+ */
+export declare function getMachineFingerprint(): string;

package/packages/client/dist/machine/fingerprint.js

@@ -0,0 +1,160 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Machine Fingerprint
+ *
+ * Generates a stable, deterministic machine identifier from hardware/OS
+ * attributes using SHA-256. Used for license activation machine tracking.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { arch, cpus, homedir, hostname, networkInterfaces, platform } from 'node:os';
+const ALL_ZEROS_MAC = '00:00:00:00:00:00';
+/** Path to the persisted machine-id file */
+const NEOCORTEX_DIR = join(homedir(), '.neocortex');
+const MACHINE_ID_FILE = join(NEOCORTEX_DIR, '.machine-id');
+/**
+ * Collect sorted, non-internal MAC addresses from network interfaces.
+ * Filters out internal/loopback interfaces and all-zeros MACs.
+ */
+function collectMacAddresses() {
+    const interfaces = networkInterfaces();
+    const macs = [];
+    for (const entries of Object.values(interfaces)) {
+        if (!entries)
+            continue;
+        for (const entry of entries) {
+            if (!entry.internal && entry.mac !== ALL_ZEROS_MAC) {
+                macs.push(entry.mac);
+            }
+        }
+    }
+    // Sort for determinism regardless of NIC enumeration order
+    return [...new Set(macs)].sort();
+}
+/**
+ * Generate a hardware-based fingerprint (not persisted).
+ * This is the original computation used as fallback and for seeding.
+ *
+ * @returns 64-character hex string (SHA-256 digest)
+ */
+export function computeHardwareFingerprint() {
+    const host = hostname();
+    const plat = platform();
+    const architecture = arch();
+    const cpuList = cpus();
+    const cpuModel = cpuList.length > 0 ? cpuList[0].model : '';
+    const macs = collectMacAddresses();
+    const input = `${host}|${plat}|${architecture}|${cpuModel}|${macs.join(',')}`;
+    return createHash('sha256').update(input).digest('hex');
+}
+/**
+ * Set restrictive file permissions (chmod 600) on a file.
+ * Fail-open: never throws.
+ */
+function setFilePermissions600(filePath) {
+    try {
+        if (process.platform !== 'win32') {
+            chmodSync(filePath, 0o600);
+        }
+        // Windows ACL handled by secure-config.ts setSecureFilePermissions() if needed
+    }
+    catch {
+        // Fail-open
+    }
+}
+/**
+ * Read persisted machine ID from disk.
+ * Returns null if file doesn't exist or can't be read.
+ */
+function readPersistedMachineId() {
+    try {
+        if (!existsSync(MACHINE_ID_FILE))
+            return null;
+        const raw = readFileSync(MACHINE_ID_FILE, 'utf-8').trim();
+        // Validate: must be a 64-char hex string
+        if (/^[a-f0-9]{64}$/.test(raw))
+            return raw;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist machine ID to disk.
+ * Creates ~/.neocortex/ if needed. Sets chmod 600 on the file.
+ * Fail-open: never throws.
+ */
+function persistMachineId(machineId) {
+    try {
+        mkdirSync(NEOCORTEX_DIR, { recursive: true });
+        writeFileSync(MACHINE_ID_FILE, machineId + '\n', 'utf-8');
+        setFilePermissions600(MACHINE_ID_FILE);
+    }
+    catch {
+        // Fail-open: if disk fails, fingerprint still works from hardware
+    }
+}
+/**
+ * Check if config.json has a machineId field that can seed .machine-id.
+ * This provides backward compatibility for existing installations.
+ */
+function readMachineIdFromConfig() {
+    try {
+        const configPath = join(NEOCORTEX_DIR, 'config.json');
+        if (!existsSync(configPath))
+            return null;
+        const raw = readFileSync(configPath, 'utf-8');
+        const config = JSON.parse(raw.replace(/^\uFEFF/, ''));
+        const machineId = config.machineId;
+        if (typeof machineId === 'string' && /^[a-f0-9]{64}$/.test(machineId)) {
+            return machineId;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generate a stable machine fingerprint as a SHA-256 hex digest.
+ *
+ * Story P26.01: On first call, generates from hardware and persists to
+ * ~/.neocortex/.machine-id. On subsequent calls, reads from disk.
+ * This ensures the fingerprint remains stable even if hardware attributes
+ * change (e.g., USB NIC added/removed, hostname change).
+ *
+ * Backward compat: if config.json has machineId, uses that to seed .machine-id.
+ *
+ * Fail-open: if disk operations fail, falls back to hardware-generated fingerprint.
+ *
+ * @returns 64-character hex string (SHA-256 digest)
+ */
+export function getMachineFingerprint() {
+    // 1. Try reading persisted machine ID from disk
+    const persisted = readPersistedMachineId();
+    if (persisted)
+        return persisted;
+    // 2. Check config.json for backward-compatible machineId
+    const fromConfig = readMachineIdFromConfig();
+    if (fromConfig) {
+        persistMachineId(fromConfig);
+        return fromConfig;
+    }
+    // 3. Generate from hardware and persist
+    const fingerprint = computeHardwareFingerprint();
+    persistMachineId(fingerprint);
+    return fingerprint;
+}

package/packages/client/dist/machine/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { getMachineFingerprint } from './fingerprint.js';

package/packages/client/dist/machine/index.js

@@ -0,0 +1,5 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { getMachineFingerprint } from './fingerprint.js';

package/packages/client/dist/resilience/circuit-breaker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitBreakerConfig {
+    /** Number of failures within window to trip circuit. Default: 3 */
+    failureThreshold: number;
+    /** Window in ms for counting failures. Default: 60_000 (60s) */
+    failureWindowMs: number;
+    /** Time in ms before OPEN transitions to HALF_OPEN. Default: 60_000 (60s) */
+    halfOpenAfterMs: number;
+    /** Path to persist circuit state. Default: ~/.neocortex/.circuit-state */
+    stateFilePath: string;
+}
+export interface FailureRecord {
+    timestamp: number;
+}
+export interface CircuitBreakerState {
+    state: CircuitState;
+    failures: FailureRecord[];
+    openedAt: number | null;
+    lastProbeAt: number | null;
+}
+export declare class ClientCircuitBreaker {
+    private readonly config;
+    private internalState;
+    constructor(config?: Partial<CircuitBreakerConfig>, initialState?: CircuitBreakerState);
+    /**
+     * Check if a request can be made to the server.
+     * Returns false if circuit is OPEN (fail-fast to cache).
+     */
+    canCall(): boolean;
+    /**
+     * Record a successful server response. Closes the circuit.
+     */
+    recordSuccess(): Promise<void>;
+    /**
+     * Record a failed server response. Opens circuit after threshold failures in window.
+     */
+    recordFailure(): Promise<void>;
+    /**
+     * Get current circuit breaker state (copy).
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Reset circuit breaker to initial CLOSED state.
+     */
+    reset(): Promise<void>;
+    /**
+     * Load circuit breaker state from disk.
+     */
+    static loadFromDisk(path?: string): Promise<ClientCircuitBreaker>;
+    /**
+     * Remove failures outside the counting window.
+     */
+    private pruneExpiredFailures;
+    /**
+     * Persist state to disk with atomic write.
+     */
+    private saveToDisk;
+}