@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/sdk.d.ts

@@ -0,0 +1,4 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Research } from './research.js';
+export declare function sdkInputs(operation: string, p: Record<string, unknown>): void;
+export declare function sdkCommands(research: (c: CommandContext) => Research): CommandDefinition[];

package/dist/src/sdk.js

@@ -0,0 +1,125 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { sdkOperations } from './sdk-contracts.js';
+import { option, key, parsed, selectedOptions } from './arguments.js';
+import { scope, address, number } from './research.js';
+import { id, fail, object, text } from './model.js';
+import { verifyMutation } from './mutation-effects.js';
+import { resolve } from 'node:path';
+export function sdkInputs(operation, p) {
+    if (['type-structure', 'type-layout', 'type-settings'].includes(operation) && !/^\/(?:[^/\0]+\/)*[^/\0]+$/.test(String(p.path)))
+        fail('invalid', 'Types require an absolute native type path.');
+    for (const name of ['packing', 'alignment'])
+        if (p[name] !== undefined) {
+            const n = number(Number(p[name]) + 1, 65) - 1;
+            if (n > 0 && (n & (n - 1)) !== 0)
+                fail('invalid', 'Packing/alignment must be -1, zero or a power of two through 64.');
+        }
+    if (p.types !== undefined && (!Array.isArray(p.types) || !p.types.length || p.types.length > 256 || p.types.some(v => typeof v !== 'string' || !v.startsWith('/'))))
+        fail('invalid', 'Select 1–256 explicit type paths.');
+    if (operation === 'type-structure' && (!Array.isArray(p.fields) || !p.fields.length || p.fields.length > 256))
+        fail('invalid', 'A structure needs 1–256 field objects.');
+    if (operation === 'type-structure') {
+        const names = new Set();
+        for (const item of p.fields) {
+            const field = object(item), name = text(field.name, 512);
+            text(field.type, 512);
+            if (names.has(name) || Object.keys(field).some(key => !['name', 'type', 'comment', 'offset', 'bit_size', 'bit_offset', 'byte_width'].includes(key)))
+                fail('invalid', 'Fields require unique names and known layout properties.');
+            names.add(name);
+            if (field.comment !== undefined && (typeof field.comment !== 'string' || field.comment.length > 4096 || field.comment.includes('\0')))
+                fail('invalid', 'Field comment exceeds its text bound.');
+            for (const [key, max, min] of [['offset', 1048576, 0], ['bit_size', 512, 1], ['bit_offset', 511, 0], ['byte_width', 64, 1]])
+                if (field[key] !== undefined) {
+                    if (typeof field[key] !== 'number')
+                        fail('invalid', 'Field numeric values must be exact JSON integers.');
+                    number(field[key], max, min);
+                }
+            if (field.offset !== undefined && Number(p.packing ?? 0) >= 0)
+                fail('invalid', 'Explicit field offsets require disabled packing (-1).');
+            if ((field.bit_offset !== undefined || field.byte_width !== undefined) && (field.bit_size === undefined || field.offset === undefined))
+                fail('invalid', 'Explicit bit placement requires a bitfield and byte offset.');
+        }
+    }
+    if (operation === 'type-settings')
+        for (const value of Object.values(object(p.settings))) {
+            if (value !== null && (!['string', 'number', 'boolean'].includes(typeof value) || typeof value === 'number' && !Number.isSafeInteger(value) || typeof value === 'string' && (value.length > 4096 || value.includes('\0'))))
+                fail('invalid', 'Type settings require bounded primitive values or null.');
+        }
+    if (operation === 'decompiler-ir')
+        for (const [key, value] of Object.entries(object(p.options ?? {})))
+            if (!['eliminate_unreachable', 'respect_read_only', 'infer_constant_pointers', 'split_structures', 'split_arrays'].includes(key) || typeof value !== 'boolean')
+                fail('invalid', 'Decompiler options require known Boolean properties.');
+    if (operation === 'changes') {
+        const categories = p.categories;
+        if (!Array.isArray(categories) || !categories.length || categories.length > 8 || new Set(categories).size !== categories.length || categories.some(value => !['bytes', 'code_units', 'comments', 'symbols', 'functions', 'references', 'context', 'properties'].includes(String(value))))
+            fail('invalid', 'Select 1–8 distinct supported diff categories.');
+    }
+    for (const name of ['expect_hex', 'bytes_hex'])
+        if (p[name] !== undefined &&
+            (typeof p[name] !== 'string' || !/^(?:[a-fA-F0-9]{2}){1,4096}$/.test(p[name])))
+            fail('invalid', name + ' needs 1–4096 complete hex bytes.');
+    if (operation === 'patch-bytes' && String(p.expect_hex).length !== String(p.bytes_hex).length)
+        fail('invalid', 'Expected and replacement lengths must match.');
+    for (const name of ['expect_sha256', 'second_sha256'])
+        if (p[name] !== undefined && !/^[a-f0-9]{64}$/.test(String(p[name])))
+            fail('invalid', 'Memory preconditions require SHA256.');
+    for (const name of ['expect_size', 'second_size'])
+        if (p[name] !== undefined)
+            p[name] = number(p[name], 16777216, 1);
+    for (const [name, max] of [['max_ranges', 1000], ['max_ops', 10000], ['timeout_seconds', 120]])
+        if (p[name] !== undefined)
+            p[name] = number(p[name], max, 1);
+    if (p.instructions !== undefined && (!Array.isArray(p.instructions) || !p.instructions.length || p.instructions.length > 64 || p.instructions.some(v => typeof v !== 'string' || v.length > 512 || /[\r\n\0]/.test(v))))
+        fail('invalid', 'Assembly requires 1–64 bounded instruction strings.');
+    if (operation === 'library-update' && p.new_name === undefined && p.path === undefined)
+        fail('invalid', 'Supply a library name or path update.');
+    if (operation.startsWith('context-') && p.end_address !== undefined) {
+        const start = address(p.address), end = address(p.end_address), parts = (v) => v.split(':');
+        const a = parts(start), b = parts(end);
+        if (a.length !== b.length || a.length === 2 && a[0] !== b[0])
+            fail('invalid', 'Processor context needs one address space.');
+        const length = BigInt('0x' + b.at(-1)) - BigInt('0x' + a.at(-1)) + 1n;
+        if (length < 1n || length > 65536n)
+            fail('invalid', 'Processor context range is 1–65536 bytes.');
+    }
+    if (operation === 'context-set' && !/^(?:0x)?[a-f0-9]{1,128}$/i.test(String(p.value)))
+        fail('invalid', 'Context value must be an unsigned hex integer.');
+    if (operation === 'context-set')
+        p.value = String(p.value).toLowerCase();
+}
+export function sdkCommands(research) {
+    const groups = new Map();
+    for (const entry of sdkOperations) {
+        const children = groups.get(entry.group) ?? [];
+        groups.set(entry.group, children);
+        children.push(command(entry.name, entry.description, async ({ options: o }, c) => {
+            const selected = scope(o), p = {};
+            for (const parameter of entry.params) {
+                const value = o[key(parameter.name)];
+                if (value !== undefined)
+                    p[parameter.name] = parsed(parameter, value);
+                else if (parameter.required)
+                    fail('invalid', 'Missing ' + parameter.name);
+            }
+            sdkInputs(entry.operation, p);
+            const api = research(c), operation = '/sdk/' + entry.operation;
+            if (entry.operation === 'type-archive-import') {
+                const archive = await api.workspace.artifacts.capture(resolve(c.cwd, String(p.input)), 'input');
+                if (archive.size > 67108864)
+                    fail('limit', 'Type archive exceeds 64 MiB.');
+                delete p.input;
+                p.archive = archive;
+            }
+            if (entry.write)
+                return api.mutate(selected, operation, p, async () => ({}), o.requestId === undefined ? undefined : id(o.requestId), (backend, snapshot, response) => verifyMutation(backend, snapshot, operation, p, response));
+            const other = entry.pair ? { session: o.otherSession === undefined ? selected.session : id(o.otherSession), target: id(o.otherTarget) } : undefined;
+            const value = object(other ? await api.crossRead(selected, other, operation, p) : await api.read(selected, operation, p));
+            if (Buffer.byteLength(JSON.stringify(value)) > 1048576)
+                fail('limit', 'SDK result exceeds 1 MiB; narrow the operation.');
+            return { ...selected, ...(other ? { other } : {}), value };
+        }, { permission: entry.write ? 'Destructive' : Permission.ReadOnly, options: [...selectedOptions, ...entry.params.map(option),
+                ...(entry.pair ? [{ flags: '--other-target <id>', description: 'Second immutable target', required: true }, { flags: '--other-session <id>', description: 'Second session (default selected session)' }] : []),
+                ...(entry.write ? [{ flags: '--request-id <id>', description: 'Retrieve this changing intent without repeating it' }] : [])] }));
+    }
+    return [...groups].map(([name, children]) => command(name, name + ' native SDK workflows', children));
+}

package/dist/src/server.d.ts

@@ -0,0 +1,46 @@
+import type { CommandContext } from '@eyeauras/cli-factory';
+import { type ChildProcess } from 'node:child_process';
+import { type NativeInputs } from './native-inputs.js';
+export interface ServerBinding {
+    mode: 'local' | 'external';
+    origin: string;
+    repository: string;
+    readerUser: string;
+    publisherUser: string;
+    readerSecret: string;
+    publisherSecret: string;
+}
+/** Own local startup; external profiles connect without taking ownership of their server. */
+export declare class GhidraServer {
+    readonly directory: string;
+    private readonly inputs;
+    private readonly c;
+    private readonly state;
+    constructor(directory: string, inputs: NativeInputs, c: CommandContext, state?: {
+        initializing?: Promise<ServerBinding>;
+        child?: ChildProcess;
+    });
+    fork(c: CommandContext): GhidraServer;
+    private root;
+    private run;
+    credentials(binding: ServerBinding, role: 'reader' | 'publisher'): Promise<Record<string, string>>;
+    fields(snapshot: string, selectors: string): Promise<Record<string, unknown>>;
+    inspect(snapshot: string, request: string): Promise<Record<string, unknown>>;
+    sdkFile(operation: string, p: Record<string, unknown>): Promise<Record<string, unknown>>;
+    traceInspect(snapshot: string): Promise<Record<string, unknown>>;
+    project(operation: string, parameters: Record<string, unknown>): Promise<Record<string, unknown>>;
+    projectOutcome(requestId: string, expected: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+    administration(operation: string, parameters: Record<string, unknown>): Promise<Record<string, unknown>>;
+    programStatus(binding: ServerBinding, path: string): Promise<Record<string, unknown>>;
+    initialImport(root: string): Promise<Record<string, unknown>>;
+    initialPublication(binding: ServerBinding, root: string, operation?: 'stage' | 'verify-stage' | 'promote' | 'verify'): Promise<Record<string, unknown>>;
+    publish(binding: ServerBinding, path: string, snapshot: string, expected: number, request: string, journal: string, sourceSha: string): Promise<Record<string, unknown>>;
+    recoverPublication(binding: ServerBinding, path: string, snapshot: string, expected: number, request: string, journal: string, sourceSha: string): Promise<Record<string, unknown>>;
+    private authority;
+    ensure(): Promise<ServerBinding>;
+    private initialize;
+    private identity;
+    stop(): Promise<void>;
+}
+/** Stop only the authenticated owned server recorded below this workspace/probe root. */
+export declare function stopLocalServer(directory: string, c: CommandContext): Promise<void>;

package/dist/src/server.js

@@ -0,0 +1,460 @@
+import { randomUUID, randomBytes, createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { readFile, mkdir, open, rename, readdir, stat, chmod, realpath } from 'node:fs/promises';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { createServer } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fail, object, stable, text, digest } from './model.js';
+import { nativeHelpers, nativeJvmDirectories, nativeExtensionArguments } from './native-inputs.js';
+import { parseDomainJson } from './json.js';
+const live = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        throw error;
+    }
+};
+async function durable(path, value) {
+    const temporary = path + '.new-' + randomUUID(), handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(stable(value));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(temporary, path);
+    if (process.platform !== 'win32') {
+        const directory = await open(dirname(path), 'r');
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+}
+async function ports(count) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const base = 20000 + Math.floor(Math.random() * 30000), held = [];
+        try {
+            for (let index = 0; index < count; index++) {
+                const listener = createServer();
+                held.push(listener);
+                await new Promise((resolve, reject) => { listener.once('error', reject); listener.listen(base + index, '127.0.0.1', resolve); });
+            }
+            return base;
+        }
+        catch { /* Collision is retried before any resource or process is published. */ }
+        finally {
+            await Promise.all(held.filter(listener => listener.listening).map(listener => new Promise(resolve => listener.close(() => resolve()))));
+        }
+    }
+    fail('launch', 'Could not reserve loopback ports for the owned server.');
+}
+/** Own local startup; external profiles connect without taking ownership of their server. */
+export class GhidraServer {
+    directory;
+    inputs;
+    c;
+    state;
+    constructor(directory, inputs, c, state = {}) {
+        this.directory = directory;
+        this.inputs = inputs;
+        this.c = c;
+        this.state = state;
+    }
+    fork(c) { return new GhidraServer(this.directory, this.inputs, c, this.state); }
+    root() { return join(this.directory, 'server'); }
+    async run(label, main, args, environment = {}, input, acceptedCodes = [0], timeoutMilliseconds = 120000) {
+        const root = join(this.root(), 'calls', label + '-' + randomUUID());
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const classes = await nativeHelpers(this.directory, this.inputs);
+        const log = await open(join(root, 'diagnostic.log'), 'a', 0o600);
+        const child = spawn(this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
+            ...nativeJvmDirectories(root), ...nativeExtensionArguments(this.inputs), '-cp', classes + delimiter + this.inputs.classpath, main, ...args], { cwd: root, windowsHide: true, env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, ...environment }, stdio: ['pipe', 'pipe', log.fd] });
+        const exited = new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
+        exited.catch(() => { });
+        await log.close();
+        let output = '', overflow = false;
+        child.stdout.on('data', chunk => { if (!overflow)
+            output += chunk.toString(); if (Buffer.byteLength(output) > 1024 * 1024) {
+            overflow = true;
+            child.kill('SIGTERM');
+        } });
+        const abort = () => child.kill('SIGTERM');
+        this.c.signal.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(abort, timeoutMilliseconds);
+        const force = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+            child.kill('SIGKILL'); }, timeoutMilliseconds + 5000);
+        try {
+            child.stdin.on('error', () => { });
+            child.stdin.end(input);
+            if (this.c.signal.aborted)
+                abort();
+            const code = await exited;
+            if (code === null || !acceptedCodes.includes(code) || overflow)
+                fail('authorization', 'Native server operation could not be verified; its owned diagnostic stage is retained.');
+            let result;
+            try {
+                result = object(parseDomainJson(output));
+            }
+            catch {
+                fail('malformed', 'Native server operation returned malformed content.');
+            }
+            if (result.error || result.state === 'failed')
+                fail('authorization', 'Native server operation did not establish its outcome.');
+            return result;
+        }
+        finally {
+            clearTimeout(timer);
+            clearTimeout(force);
+            this.c.signal.removeEventListener('abort', abort);
+        }
+    }
+    async credentials(binding, role) {
+        const url = new URL(binding.origin);
+        return { GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100',
+            GHIDRA_SERVER_USER: role === 'reader' ? binding.readerUser : binding.publisherUser,
+            GHIDRA_SERVER_PASSWORD: await this.c.secrets.require(role === 'reader' ? binding.readerSecret : binding.publisherSecret) };
+    }
+    async fields(snapshot, selectors) {
+        return this.run('snapshot-fields', 'InsightSnapshotFields', [snapshot, selectors]);
+    }
+    async inspect(snapshot, request) { return this.run('snapshot-inspect', 'InsightSnapshotInspect', [snapshot, request]); }
+    async sdkFile(operation, p) {
+        const root = join(this.root(), 'sdk-files', randomUUID());
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const tracking = operation.startsWith('vt.');
+        const request = join(root, 'request.json');
+        await durable(request, { ...p, operation: tracking ? operation.slice(3) : operation });
+        const main = tracking ? 'InsightVersionTracking' : /^(fid|bsim)-(build|query)$/.test(operation) ? 'InsightFunctionDatabases' : 'InsightSdkFiles';
+        const result = await this.run('sdk-file', main, [request]);
+        return object(result.value);
+    }
+    async traceInspect(snapshot) { return this.run('trace-inspect', 'InsightTraceInspect', [snapshot]); }
+    async project(operation, parameters) {
+        const requestId = text(parameters.request_id, 128);
+        if (!/^(?:a|read)_[a-zA-Z0-9-]+$/.test(requestId))
+            fail('binding', 'Invalid internal project request identity.');
+        const parent = join(this.directory, 'project-calls');
+        await mkdir(parent, { recursive: true, mode: 0o700 });
+        if (await realpath(parent) !== resolve(parent))
+            fail('binding', 'Project call container moved outside owned storage.');
+        const root = join(parent, requestId);
+        await mkdir(root, { mode: 0o700 });
+        const request = join(root, 'request.json');
+        await durable(request, { ...parameters, operation });
+        return this.run('project-files', 'InsightProjectFiles', [request]);
+    }
+    async projectOutcome(requestId, expected) {
+        if (!/^a_[a-zA-Z0-9-]+$/.test(requestId))
+            fail('binding', 'Invalid retained project request identity.');
+        const root = join(this.directory, 'project-calls', requestId);
+        try {
+            if (await realpath(root) !== resolve(root))
+                fail('binding', 'Retained project call moved outside owned storage.');
+            const raw = await readFile(join(root, 'request.json'), 'utf8'), request = object(parseDomainJson(raw)), journal = object(parseDomainJson(await readFile(join(root, 'result.json'), 'utf8')));
+            if (journal.schema !== 1 || journal.request !== requestId || journal.hash !== createHash('sha256').update(raw).digest('hex') ||
+                Object.entries(expected).some(([key, value]) => stable(request[key]) !== stable(value)))
+                fail('binding', 'Project completion journal differs from the retained request.');
+            return object(journal.result);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    async administration(operation, parameters) {
+        const connection = join(this.root(), 'connection.json');
+        if (operation === 'status') {
+            try {
+                if (object(JSON.parse(await readFile(connection, 'utf8'))).enabled === false)
+                    return { connected: false, mode: this.c.profile.values.server ? 'external' : 'local', state: 'disconnected' };
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (operation === 'connect') {
+            await mkdir(this.root(), { recursive: true, mode: 0o700 });
+            await durable(connection, { enabled: true });
+        }
+        if (operation === 'stop') {
+            await this.stop();
+            return { connected: false, mode: this.c.profile.values.server ? 'external' : 'local', state: 'stopped' };
+        }
+        if (operation === 'disconnect') {
+            await this.stop();
+            await mkdir(this.root(), { recursive: true, mode: 0o700 });
+            await durable(connection, { enabled: false });
+            return { connected: false, mode: this.c.profile.values.server ? 'external' : 'local' };
+        }
+        if (operation === 'status' && !this.c.profile.values.server) {
+            let local;
+            try {
+                local = JSON.parse(await readFile(join(this.root(), 'local.json'), 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return { connected: false, mode: 'local', state: 'not_started' };
+                throw error;
+            }
+            if (!local.pid || !live(local.pid))
+                return { connected: false, mode: 'local', repository: local.repository };
+            await this.identity(local);
+            await this.authority(local);
+            return { connected: true, mode: 'local', repository: local.repository };
+        }
+        const binding = await this.ensure();
+        if (operation === 'connect' || operation === 'status')
+            return { connected: true, mode: binding.mode, repository: binding.repository };
+        if (operation === 'set_permissions' && parameters.repository === binding.repository &&
+            (parameters.user === binding.readerUser && parameters.access !== 0 || parameters.user === binding.publisherUser && ![1, 2].includes(Number(parameters.access))))
+            fail('authorization', 'Canonical reader/publisher authority cannot be changed by repository administration.');
+        const root = join(this.root(), 'administration', randomUUID());
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const request = join(root, 'request.json');
+        await durable(request, { operation, ...parameters, protected_repository: binding.repository });
+        return this.run('administration', 'InsightServerAdministration', [request], await this.credentials(binding, 'publisher'));
+    }
+    async programStatus(binding, path) {
+        return this.run('program-status', 'InsightRepositoryProbe', [binding.repository, path, 'reader'], await this.credentials(binding, 'reader'));
+    }
+    async initialImport(root) { return this.run('initial-import', 'InsightInitialImport', [root], {}, undefined, [0], 600000); }
+    async initialPublication(binding, root, operation = 'stage') {
+        return this.run('initial-publication', 'db.InsightInitialPublication', [root, operation], await this.credentials(binding, operation.startsWith('verify') ? 'reader' : 'publisher'));
+    }
+    async publish(binding, path, snapshot, expected, request, journal, sourceSha) {
+        return this.run('publish', 'db.InsightSnapshotPublisher', [binding.repository, path, snapshot, String(expected), 'insight merge ' + request, journal, sourceSha], await this.credentials(binding, 'publisher'), undefined, [0, 2]);
+    }
+    async recoverPublication(binding, path, snapshot, expected, request, journal, sourceSha) {
+        return this.run('recover-publication', 'db.InsightPublicationRecovery', [binding.repository, path, snapshot, String(expected), 'insight merge ' + request, journal, sourceSha], { ...await this.credentials(binding, 'reader'), INSIGHT_PUBLISHER_USER: binding.publisherUser,
+            INSIGHT_PUBLISHER_PASSWORD: await this.c.secrets.require(binding.publisherSecret) });
+    }
+    async authority(binding) {
+        for (const role of ['reader', 'publisher']) {
+            const result = await this.run('verify-' + role, 'InsightServerProbe', [binding.repository, role], await this.credentials(binding, role));
+            if (result.repository !== binding.repository || result.role !== role || (role === 'reader' ? result.permission !== 0 : ![1, 2].includes(Number(result.permission))))
+                fail('authorization', 'Actual repository permissions do not match the selected server profile.');
+        }
+    }
+    async ensure() {
+        try {
+            if (object(JSON.parse(await readFile(join(this.root(), 'connection.json'), 'utf8'))).enabled === false)
+                fail('blocked', 'Configured server is disconnected; use ghidra server connect before shared operations.');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (!this.state.initializing)
+            this.state.initializing = this.initialize().catch(error => { this.state.initializing = undefined; throw error; });
+        const binding = await this.state.initializing;
+        if (binding.mode === 'local') {
+            const local = binding;
+            if (local.pid && !live(local.pid)) {
+                this.state.initializing = undefined;
+                return this.ensure();
+            }
+            await this.identity(local);
+        }
+        return binding;
+    }
+    async initialize() {
+        const root = this.root();
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const values = this.c.profile.values;
+        const mode = values.server ? 'external' : 'local';
+        const effective = mode === 'external' ? { mode, origin: text(values.server), repository: text(values.repository),
+            readerUser: text(values.readerUser), publisherUser: text(values.publisherUser) } : { mode };
+        if (mode === 'external' && (!/^ghidra:\/\/[^/?#@]+$/.test(text(values.server)) || /[\\/]/.test(text(values.repository)) ||
+            text(values.repository).startsWith('.') || values.readerUser === values.publisherUser))
+            fail('configuration', 'External server requires an origin, repository and distinct reader/publisher accounts.');
+        const configuration = digest(effective), configured = join(root, 'configuration.json');
+        try {
+            if (object(JSON.parse(await readFile(configured, 'utf8'))).hash !== configuration)
+                fail('binding', 'Server profile changed while its durable workspace remains; restore the original binding.');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            await durable(configured, { hash: configuration });
+        }
+        if (mode === 'external') {
+            const origin = text(values.server), repository = text(values.repository), readerUser = text(values.readerUser), publisherUser = text(values.publisherUser);
+            if (!/^ghidra:\/\/[^/?#@]+$/.test(origin) || new URL(origin).protocol !== 'ghidra:' || /[\\/]/.test(repository) || repository.startsWith('.') || readerUser === publisherUser)
+                fail('configuration', 'External server requires an origin, repository and distinct reader/publisher accounts.');
+            const binding = { mode, origin, repository, readerUser, publisherUser, readerSecret: 'readerPassword', publisherSecret: 'publisherPassword' };
+            await this.authority(binding);
+            return binding;
+        }
+        const saved = join(root, 'local.json'), data = join(root, 'data');
+        let local;
+        try {
+            local = JSON.parse(await readFile(saved, 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            await mkdir(data, { recursive: true, mode: 0o700 });
+            if ((await readdir(data)).length)
+                fail('binding', 'Unidentified server storage exists; it cannot be adopted.');
+            const instance = 'server_' + randomUUID(), base = await ports(4);
+            local = { mode: 'local', instance, port: base, identityPort: base + 3, origin: `ghidra://127.0.0.1:${base}`,
+                repository: 'insight_' + randomUUID().replaceAll('-', ''), readerUser: 'reader', publisherUser: 'publisher',
+                readerSecret: instance + '-readerPassword', publisherSecret: instance + '-publisherPassword',
+                keySecret: instance + '-keystorePassword', tokenSecret: instance + '-identityToken', phase: 'seeded' };
+            await durable(saved, local);
+        }
+        if (local.mode !== 'local' || !/^server_[a-f0-9-]{36}$/.test(local.instance) || local.origin !== `ghidra://127.0.0.1:${local.port}` ||
+            local.identityPort !== local.port + 3 || !local.repository.startsWith('insight_') || local.readerUser !== 'reader' || local.publisherUser !== 'publisher')
+            fail('binding', 'Owned local server receipt is inconsistent.');
+        for (const key of [local.readerSecret, local.publisherSecret, local.keySecret, local.tokenSecret]) {
+            if (!key.startsWith(local.instance + '-'))
+                fail('binding', 'Owned local server secret reference is inconsistent.');
+            if (!await this.c.secrets.get(key)) {
+                if (local.phase !== 'seeded')
+                    fail('credentials', 'Owned local server credentials are missing; retain its storage and restore its credential store.');
+                await this.c.secrets.set(key, randomBytes(32).toString('hex'));
+            }
+        }
+        if (local.pid && live(local.pid)) {
+            await this.identity(local);
+            await this.authority(local);
+            return local;
+        }
+        // A prior owner may have died after spawn and before recording its PID.
+        if (!local.pid && await this.identity(local).then(() => true, () => false)) {
+            const identity = await this.identity(local);
+            local.pid = Number(identity.pid);
+            local.phase = 'running';
+            await durable(saved, local);
+            await this.authority(local);
+            return local;
+        }
+        const initialized = await this.run('initialize', 'ghidra.server.InsightServerInit', [data, local.repository, local.publisherUser, local.readerUser], {
+            INSIGHT_PUBLISHER_PASSWORD: await this.c.secrets.require(local.publisherSecret), INSIGHT_READER_PASSWORD: await this.c.secrets.require(local.readerSecret)
+        });
+        if (initialized.state !== 'ready' || initialized.repository !== local.repository || initialized.readerReadOnly !== true || initialized.publisherAdmin !== true)
+            fail('authorization', 'Owned local server initialization did not establish its permission boundary.');
+        local.phase = 'initialized';
+        delete local.pid;
+        await durable(saved, local);
+        const keystore = join(root, 'owned-cert.p12');
+        try {
+            await stat(keystore);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            // keytool gets the random password through its documented environment input, never argv.
+            await this.run('certificate', 'InsightKeytool', [keystore], { INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret) });
+            await chmod(keystore, 0o600);
+        }
+        const classes = await nativeHelpers(this.directory, this.inputs);
+        const processRoot = join(root, 'processes', randomUUID());
+        await mkdir(processRoot, { recursive: true, mode: 0o700 });
+        const log = await open(join(processRoot, 'runtime.log'), 'a', 0o600);
+        const child = spawn(this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
+            ...nativeJvmDirectories(processRoot), '-cp', classes + delimiter + (this.inputs.serverClasspath ?? this.inputs.classpath),
+            'InsightServerMain', data, String(local.port), String(local.identityPort), local.instance, keystore], { cwd: processRoot, detached: true, windowsHide: true, env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: processRoot, TMPDIR: processRoot,
+                INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret), INSIGHT_SERVER_TOKEN: await this.c.secrets.require(local.tokenSecret) }, stdio: ['ignore', log.fd, log.fd] });
+        child.on('error', () => { });
+        child.unref();
+        await log.close();
+        if (!child.pid)
+            fail('launch', 'Owned local Ghidra server could not be started.');
+        this.state.child = child;
+        local.pid = child.pid;
+        local.phase = 'running';
+        await durable(saved, local);
+        try {
+            const deadline = Date.now() + 60000;
+            while (Date.now() < deadline && child.exitCode === null && child.signalCode === null && !this.c.signal.aborted) {
+                try {
+                    await this.identity(local);
+                    await this.authority(local);
+                    return local;
+                }
+                catch {
+                    await delay(100);
+                }
+            }
+            fail('launch', 'Owned local Ghidra server did not become ready; its storage and diagnostic stage are retained.');
+        }
+        catch (error) {
+            // Only this newly-created child handle can be cleaned without a ready identity probe.
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGTERM');
+            for (let i = 0; i < 100 && child.exitCode === null && child.signalCode === null; i++)
+                await delay(50);
+            throw error;
+        }
+    }
+    identity(local) { return serverIdentity(local, this.c); }
+    async stop() { await stopLocalServer(this.directory, this.c); this.state.child = undefined; this.state.initializing = undefined; }
+}
+async function serverIdentity(local, c) {
+    const token = await c.secrets.require(local.tokenSecret);
+    const response = await c.fetch(`http://127.0.0.1:${local.identityPort}/identity`, { redirect: 'error',
+        signal: AbortSignal.timeout(1000), headers: { Authorization: 'Bearer ' + token } });
+    if (!response.ok || Number(response.headers.get('content-length')) > 4096)
+        fail('binding', 'Owned server identity was not verified.');
+    const reader = response.body?.getReader();
+    if (!reader)
+        fail('binding', 'Owned server identity has no body.');
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > 4096)
+                fail('binding', 'Owned server identity exceeded its bound.');
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const value = Buffer.concat(chunks).toString('utf8');
+    const result = object(JSON.parse(value));
+    if (result.instance !== local.instance || result.port !== local.port || !Number.isSafeInteger(result.pid) || Number(result.pid) < 1 ||
+        local.pid !== undefined && result.pid !== local.pid)
+        fail('binding', 'Server endpoint no longer belongs to the recorded owned process.');
+    return result;
+}
+/** Stop only the authenticated owned server recorded below this workspace/probe root. */
+export async function stopLocalServer(directory, c) {
+    let local;
+    try {
+        local = JSON.parse(await readFile(join(directory, 'server', 'local.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!local.pid)
+        return;
+    if (live(local.pid)) {
+        await serverIdentity(local, c);
+        process.kill(local.pid, 'SIGTERM');
+        for (let i = 0; i < 100 && live(local.pid); i++)
+            await delay(50);
+        if (live(local.pid))
+            fail('busy', 'Owned server did not stop; its receipt is retained.');
+    }
+    local.phase = 'stopped';
+    delete local.pid;
+    await durable(join(directory, 'server', 'local.json'), local);
+}