@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/runtime-archives.d.ts

@@ -0,0 +1,5 @@
+import type { RuntimeArtifact } from './runtime-catalog.js';
+export declare function fileSha256(path: string): Promise<string>;
+export declare function archiveName(name: string): string;
+export declare function extractArchive(file: string, destination: string, format: 'tgz' | 'zip'): Promise<void>;
+export declare function cacheArtifact(artifact: RuntimeArtifact, cache: string, fetcher: typeof fetch, signal: AbortSignal, offline?: boolean): Promise<string>;

package/dist/src/runtime-archives.js

@@ -0,0 +1,127 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join, posix } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import * as tar from 'tar';
+import * as zip from 'yauzl';
+import { fail } from './model.js';
+export async function fileSha256(path) { const hash = createHash('sha256'); for await (const chunk of createReadStream(path))
+    hash.update(chunk); return hash.digest('hex'); }
+export function archiveName(name) {
+    if (!name || name.includes('\\') || name.includes('\0') || name.startsWith('/') || /^[a-zA-Z]:/.test(name) || name.split('/').includes('..'))
+        fail('invalid', 'Runtime archive contains an unsafe path.');
+    return name.replace(/^(\.\/)+/, '');
+}
+export async function extractArchive(file, destination, format) {
+    await mkdir(destination, { recursive: true, mode: 0o700 });
+    let count = 0, bytes = 0;
+    const bound = (name, size) => { archiveName(name); if (++count > 100000 || !Number.isSafeInteger(size) || size < 0 || (bytes += size) > 8 * 1024 ** 3)
+        fail('limit', 'Runtime archive exceeds extraction bounds.'); };
+    if (format === 'tgz') {
+        let unsafe;
+        await tar.t({ file, strict: true, filter: (path, entry) => {
+                try {
+                    if (!('type' in entry))
+                        fail('invalid', 'Unsupported runtime archive metadata.');
+                    bound(path, entry.size);
+                    if (!['File', 'Directory', 'SymbolicLink', 'Link', 'OldFile', 'ContiguousFile'].includes(entry.type))
+                        fail('invalid', 'Unsupported runtime archive entry.');
+                    if (entry.type === 'SymbolicLink' || entry.type === 'Link') {
+                        const target = entry.linkpath;
+                        if (typeof target !== 'string')
+                            fail('invalid', 'Runtime archive link omitted its target.');
+                        if (target.startsWith('/') || target.includes('\\') || /^[a-zA-Z]:/.test(target))
+                            fail('invalid', 'Runtime archive link escapes extraction storage.');
+                        const joined = posix.normalize(entry.type === 'Link' ? target : posix.join(posix.dirname(path), target));
+                        archiveName(joined);
+                    }
+                    return true;
+                }
+                catch (error) {
+                    unsafe ??= error;
+                    return false;
+                }
+            } });
+        if (unsafe)
+            throw unsafe;
+        await tar.x({ file, cwd: destination, strict: true, preserveOwner: false, noChmod: false });
+        return;
+    }
+    const archive = await new Promise((ok, bad) => zip.open(file, { lazyEntries: true, strictFileNames: true }, (e, z) => e ? bad(e) : ok(z)));
+    await new Promise((ok, bad) => {
+        const failed = (e) => { archive.close(); bad(e); };
+        archive.on('error', failed);
+        archive.on('end', ok);
+        archive.on('entry', (entry) => {
+            void (async () => {
+                bound(entry.fileName, entry.uncompressedSize);
+                const mode = entry.externalFileAttributes >>> 16, type = mode & 0o170000;
+                if (type && type !== 0o100000 && type !== 0o040000)
+                    fail('invalid', 'Runtime zip may contain only files and directories.');
+                const path = join(destination, entry.fileName);
+                if (entry.fileName.endsWith('/'))
+                    await mkdir(path, { recursive: true, mode: 0o700 });
+                else {
+                    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+                    const stream = await new Promise((ok, bad) => archive.openReadStream(entry, (e, s) => e ? bad(e) : ok(s)));
+                    await pipeline(stream, createWriteStream(path, { flags: 'wx', mode: mode & 0o111 ? 0o755 : 0o644 }));
+                }
+                archive.readEntry();
+            })().catch(failed);
+        });
+        archive.readEntry();
+    });
+}
+export async function cacheArtifact(artifact, cache, fetcher, signal, offline = false) {
+    await mkdir(cache, { recursive: true, mode: 0o700 });
+    const path = join(cache, artifact.sha256 + '.' + artifact.format);
+    try {
+        if ((await stat(path)).isFile() && await fileSha256(path) === artifact.sha256)
+            return path;
+        fail('binding', 'Cached runtime archive failed its SHA256 check; remove the corrupt cache entry before retrying.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (offline)
+        fail('configuration', 'Required runtime archive is not cached; run ghidra download before using --offline.', { artifact: artifact.name, sha256: artifact.sha256 });
+    const temporary = path + '.partial-' + randomUUID();
+    try {
+        let headers = {};
+        if (artifact.url.startsWith('https://ghcr.io/v2/homebrew/core/ghidra/')) {
+            const response = await fetcher('https://ghcr.io/token?service=ghcr.io&scope=repository:homebrew/core/ghidra:pull', { signal, redirect: 'error' });
+            if (!response.ok)
+                fail('download', 'Anonymous runtime registry authorization failed.');
+            const value = await response.json();
+            if (!value.token || value.token.length > 8192)
+                fail('download', 'Invalid anonymous runtime registry token.');
+            headers = { Authorization: 'Bearer ' + value.token };
+        }
+        const response = await fetcher(artifact.url, { signal, headers });
+        if (!response.ok || !response.body)
+            fail('download', 'Pinned runtime download failed.', { artifact: artifact.name, status: response.status });
+        let size = 0;
+        const hash = createHash('sha256'), handle = await open(temporary, 'wx', 0o600);
+        try {
+            for await (const chunk of response.body) {
+                if ((size += chunk.byteLength) > 2 * 1024 ** 3)
+                    fail('limit', 'Runtime download exceeds two GiB.');
+                hash.update(chunk);
+                await handle.writeFile(chunk);
+            }
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (hash.digest('hex') !== artifact.sha256)
+            fail('binding', 'Downloaded runtime archive failed its pinned SHA256 check.');
+        await rename(temporary, path);
+        return path;
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/src/runtime-catalog.d.ts

@@ -0,0 +1,18 @@
+export interface RuntimeArtifact {
+    name: string;
+    url: string;
+    sha256: string;
+    format: 'zip' | 'tgz';
+    root: string;
+    license: string;
+}
+export declare const ghidraArchive: RuntimeArtifact;
+export declare function runtimeCatalog(platform?: string, arch?: string, kernel?: string): {
+    schema: number;
+    ghidraVersion: string;
+    javaVersion: string;
+    platform: string;
+    architecture: string;
+    ghidra: RuntimeArtifact;
+    java: RuntimeArtifact;
+};

package/dist/src/runtime-catalog.js

@@ -0,0 +1,27 @@
+import { release } from 'node:os';
+import { fail } from './model.js';
+const github = 'https://github.com/';
+export const ghidraArchive = { name: 'ghidra-12.1.2', url: github + 'NationalSecurityAgency/ghidra/releases/download/Ghidra_12.1.2_build/ghidra_12.1.2_PUBLIC_20260605.zip', sha256: 'b62e81a0390618466c019c60d8c2f796ced2509c4c1aea4a37644a77272cf99d', format: 'zip', root: 'ghidra_12.1.2_PUBLIC', license: 'Apache-2.0 and included third-party licenses' };
+const bottles = { arm64_sonoma: '40f68357d6b62a08429c36228907c995e3449283b6d2e08ba5a4e30b53a09725', arm64_sequoia: '90aa942184fca2337ad0a123f818f37372ea642e8e69e969d45cc144a6f26fdf', arm64_tahoe: '079007d8a3a477c8d5901e6596947612d86c8641956424a2bcb71ecd798bedcc', sonoma: 'e30f8c84b64331f87f6ef1890cbdded6672bb7fcc8b674794ac93e4b3e62ad2b' };
+const jdks = {
+    'darwin-arm64': ['aarch64_mac', '6ebcf221c9b41507b14c098e93c6ead6440b8d9bd154f8ec666c4c73abbdb201'],
+    'darwin-x64': ['x64_mac', '34180eb03e6d207c388cce3da668f6cc7cd7508c185c24782fadac2c9c0e66f9'],
+    'linux-x64': ['x64_linux', '4b2220e232a97997b436ca6ab15cbf70171ecff52958a46159dfa5a8c44ca4de'],
+    'win32-x64': ['x64_windows', 'd3625e7cadf23787ea540229544b6e2ab494b3b54da1801879e583e1dfee0a64'],
+};
+export function runtimeCatalog(platform = process.platform, arch = process.arch, kernel = release()) {
+    const jdk = jdks[platform + '-' + arch];
+    if (!jdk)
+        fail('configuration', 'No verified managed runtime for this OS/architecture; use an external compatible Ghidra installation.');
+    const windows = platform === 'win32', format = windows ? 'zip' : 'tgz', extension = windows ? 'zip' : 'tar.gz';
+    const java = { name: 'temurin-21.0.11+10-' + platform + '-' + arch, url: github + 'adoptium/temurin21-binaries/releases/download/jdk-21.0.11%2B10/OpenJDK21U-jdk_' + jdk[0] + '_hotspot_21.0.11_10.' + extension, sha256: jdk[1], format, root: 'jdk-21.0.11+10' + (platform === 'darwin' ? '.jdk/Contents/Home' : ''), license: 'GPL-2.0 WITH Classpath-exception-2.0; included legal notices' };
+    let ghidra = ghidraArchive;
+    if (platform === 'darwin') {
+        const major = Number(kernel.split('.')[0]);
+        if (major < 23)
+            fail('configuration', 'Managed macOS runtimes require macOS 14 or newer.');
+        const tag = arch === 'x64' ? 'sonoma' : major >= 25 ? 'arm64_tahoe' : major >= 24 ? 'arm64_sequoia' : 'arm64_sonoma', hash = bottles[tag];
+        ghidra = { name: 'ghidra-12.1.2-' + tag, url: 'https://ghcr.io/v2/homebrew/core/ghidra/blobs/sha256:' + hash, sha256: hash, format: 'tgz', root: 'ghidra/12.1.2/libexec', license: ghidraArchive.license };
+    }
+    return { schema: 1, ghidraVersion: '12.1.2', javaVersion: '21.0.11+10', platform, architecture: arch, ghidra, java };
+}

package/dist/src/runtime-manager.d.ts

@@ -0,0 +1,101 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+export declare function runtimeWrite(path: string, value: unknown): Promise<void>;
+/** Passive, conservative inventory: a reused PID blocks deletion; it never grants kill authority. */
+export declare function runtimeProcesses(directory: string): Promise<Record<string, unknown>[]>;
+export declare function externalGhidra(path: string): Promise<string>;
+export declare class RuntimeManager {
+    private readonly c;
+    readonly directory: string;
+    readonly root: string;
+    constructor(c: CommandContext);
+    status(): Promise<{
+        missing: string[];
+        capabilities: {
+            headless: boolean;
+            decompiler: boolean;
+            gui: boolean;
+            debugger: {
+                backend: string;
+                requires: string;
+                checkedBy: string;
+            } | {
+                backend: string;
+                checkedBy: string;
+                requires?: undefined;
+            };
+        };
+        server: {
+            pid?: unknown;
+            mode: string;
+            state: string;
+        };
+        processes: Record<string, unknown>[];
+        installations: {
+            id: string;
+            selected: boolean;
+            ghidraVersion: unknown;
+            verifiedAt: unknown;
+        }[];
+        retainedStages: string[];
+        lastCheck: any;
+        storage: {
+            runtime: string;
+            research: string;
+            materials: string;
+        };
+        installation?: string | undefined;
+        fingerprint?: string | undefined;
+        state: string;
+        mode: string;
+        recommended: string;
+        ghidraVersion: string | undefined;
+        java: string | undefined;
+        ghidraHome: string | undefined;
+    }>;
+    download(offline?: boolean): Promise<{
+        state: string;
+        ghidraVersion: string;
+        javaVersion: string;
+        items: {
+            name: string;
+            path: string;
+            sha256: string;
+            license: string;
+        }[];
+    }>;
+    private archive;
+    private cleanupProbes;
+    install(o: Record<string, unknown>): Promise<{
+        checks: string[];
+        schema: 1;
+        mode: "managed" | "external";
+        id?: string;
+        ghidraHome: string;
+        java: string;
+        fingerprint: string;
+        selectedAt: string;
+        uninstalledAt?: string;
+        state: string;
+    }>;
+    uninstall(purgeCache?: boolean): Promise<{
+        state: string;
+        mode: "external" | "managed";
+        externalInstallationPreserved: boolean;
+        researchPreserved: boolean;
+        materialsPreserved: boolean;
+        cachePreserved: boolean;
+    }>;
+    private probe;
+    doctor(): Promise<{
+        state: string;
+        fingerprint: string;
+        ghidraVersion: string;
+        checkedAt: string;
+        headless: unknown;
+        decompiler: unknown;
+        server: boolean;
+        debugger: Record<string, unknown>;
+        diagnostics: string;
+    }>;
+}
+export declare function runtimeCommands(exclusive: <T>(c: CommandContext, action: () => Promise<T>, quiescent?: boolean) => Promise<T>): CommandDefinition[];