clilinkapi 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# CliLinkAPI
+
+Native Node.js/strict TypeScript gateway for a **ChatGPT-authenticated Codex** runtime. The clilinkapi key protects this HTTP service; it is not an OpenAI API key. No containers, VMs, direct OpenAI API client, browser-cookie extraction, or unofficial ChatGPT endpoints are used.
+
+**Current delivery status:** HTTP routing, Codex app-server adapter, discovery, permissions profiles, setup, cancellation, and tests are implemented. By default, native Windows agent execution is attempted without isolation qualification probes; setting `provider.allowUnqualifiedWindowsExecution=false` restores the platform block. The available Windows host failed sandbox initialization. Linux/macOS execution requires the real native isolation probes to pass on that host; those platforms have not been executed during this build. A successful live Codex completion is still unverified because runtime ChatGPT login and private configuration were unavailable. See [verification](docs/verification.md) and [security](docs/security.md). This is not a claim of a production-qualified cross-platform release.
+
+## Install natively
+
+Install the published CLI with Node.js 22 or newer:
+
+```sh
+npm install -g clilinkapi
+clilinkapi
+```
+
+Use `clilinkapi serve` to start with the default configuration, or `clilinkapi serve "/absolute/path/to/clilinkapi.json"` to select a configuration file. Run `clilinkapi` without arguments for the available setup and login commands.
+
+To build from source:
+
+Install Node.js 22 or 24 LTS and use a native shell:
+
+```sh
+npm ci
+npm run check
+npm test
+npm run build
+```
+
+- **Windows:** PowerShell on native Windows x64/arm64. Setup, ACLs, login, model discovery and HTTP functions run natively; unqualified coding-agent execution is enabled by default (see below). WSL, containers and VMs are not workarounds used by this project.
+- **Linux:** native x64/arm64; install distribution `bubblewrap` (`sudo apt install bubblewrap` on Debian/Ubuntu, `sudo dnf install bubblewrap` on Fedora). User namespaces and the applicable AppArmor policy must permit its execution. Do not disable security protections merely to make the test pass.
+- **macOS:** native x64/arm64; Codex uses Seatbelt. The OS must permit the native sandbox. Run the integration tests on the intended runtime account.
+
+The runtime is pinned to Codex CLI/SDK **0.155.0**. Package installation includes the official platform binary. No global `codex` command is needed. Changes to the pinned version require requalification of protocol, permission profiles and sandbox tests.
+
+## Configure and sign in
+
+For a standalone command, run `npm link` once after building. Then use `clilinkapi serve`, `clilinkapi doctor`, or `clilinkapi serve "C:/path/to/clilinkapi.json"` from any directory. Running `clilinkapi` alone shows help. This links the command to this checkout and still requires Node.js; rebuild after source changes. On Windows, use `clilinkapi.cmd` if PowerShell blocks the generated script. See the [configuration guide](docs/configuration.md#1-install-dependencies) for setup details.
+
+See the [complete configuration guide](docs/configuration.md) for a full JSON template, every field and default, Windows execution settings, LAN access, n8n setup, verification commands, and troubleshooting.
+
+Copy `clilinkapi.example.json` to a temporary template and edit its absolute paths. Only placeholders belong in version control. Use `/home/your-user/.clilinkapi/codex` on Linux or `/Users/your-user/.clilinkapi/codex` on macOS for `provider.codexHome`; the example uses Windows paths. Both workspace directories must already exist. Remove unused workspace entries.
+
+Keep private configuration and Codex home outside **every** workspace, preferably in a dedicated service account's private directory. Workspaces cannot overlap or be filesystem roots. The service rejects custom Codex configuration, hooks, plugins, rules and skills in its dedicated Codex home. Project `.codex`/`.agents` folders may remain in place: the runtime treats the workspace as untrusted and skips project configuration; project skills in `.agents/skills` are allowed by default. Set `provider.allowProjectSkills` to `false` and restart the server to disable workspace skills. Bundled runtime skills remain disabled. Symbolic links and Windows junctions are allowed by default when their resolved targets stay inside the same workspace. Set `provider.allowSymbolicLinks` to `false` and restart to reject all symbolic links and junctions. Broken links, directory cycles, links outside the workspace, and hard-linked files remain blocked. Parent directories may contain Codex configuration or instructions; their presence does not block workspace validation. Use trusted projects and a dedicated runtime account. Do not put credentials in project files.
+
+The CLI expands `~`, literal `$HOME`, `${HOME}`, `%USERPROFILE%`, and `$env:USERPROFILE` at the start of its configuration filename. This also works when your shell does not expand them. For example, Command Prompt users can use `npm run clilinkapi -- setup "~/.clilinkapi/clilinkapi.json" ./clilinkapi.example.json`. Paths inside the JSON template still need actual absolute paths; replace `YOUR_USER` and the example workspace paths before setup.
+
+PowerShell:
+
+```powershell
+npm run clilinkapi -- setup "$HOME/.clilinkapi/clilinkapi.json" ./clilinkapi.example.json
+npm run clilinkapi -- login "$HOME/.clilinkapi/clilinkapi.json"
+npm run clilinkapi -- doctor "$HOME/.clilinkapi/clilinkapi.json"
+npm run clilinkapi -- serve "$HOME/.clilinkapi/clilinkapi.json"
+```
+
+Linux/macOS:
+
+```sh
+npm run clilinkapi -- setup "$HOME/.clilinkapi/clilinkapi.json" ./clilinkapi.example.json
+npm run clilinkapi -- login "$HOME/.clilinkapi/clilinkapi.json"
+npm run clilinkapi -- doctor "$HOME/.clilinkapi/clilinkapi.json"
+npm run clilinkapi -- serve "$HOME/.clilinkapi/clilinkapi.json"
+```
+
+`setup` uses 32 cryptographically random bytes, stores the generated key without printing it, and refuses to overwrite an existing configuration. On Unix it requires private directory/file modes (`0700`/`0600`); on Windows it applies an ACL for the runtime user and SYSTEM. Run under the same account that will run the server. Administrators remain trusted. A private parent directory is required even for key rotation.
+
+If an existing configuration fails the ACL check, run `npm run clilinkapi -- secure-config "~/.clilinkapi/clilinkapi.json"` as the runtime user. This secures the dedicated directory, configuration file and configured `codex` child folder without changing file contents or rotating the key. It creates that Codex folder if missing. It requires current-user ownership and refuses unrelated entries, links, your home directory and filesystem roots. A Codex home outside that dedicated child location must be secured separately. On Windows, startup permits read/traverse-only access to the configuration's parent folder, but rejects other users' modification rights; the configuration file and Codex storage still require private ACLs. Setup also secures an existing empty directory automatically. If a configuration already exists, continue with `login` or `doctor` instead of rerunning setup.
+
+`login` invokes the official Codex login process with ChatGPT authentication forced. The official process may print a login URL or device code for the human sign-in flow; the clilinkapi never prints stored credentials. If browser login is unavailable, use `login CONFIG --device-auth` where supported by your workspace. Supported Codex credential storage remains in `provider.codexHome` or its supported OS credential store. No credential file is parsed or copied by the clilinkapi. A compatible existing **dedicated** Codex home may be configured; a browser or desktop login is not assumed to be shared.
+
+If login fails, check your ChatGPT subscription, workspace Codex permissions, SSO/device-code policy, system clock, and outbound access. Re-run official login as the runtime user for expired sessions. An API-key-authenticated account is rejected. Usage limits are returned as upstream errors, never bypassed. CliLinkAPI startup does not require upstream availability; protected `/v1/models` reports login problems without attempting generation.
+
+Update configuration while stopped, preserve private permissions, and restart; there is no hot reload. Rotation:
+
+```sh
+npm run clilinkapi -- rotate-key /absolute/private/clilinkapi.json
+```
+
+Restart and update clients through your own secure secret-distribution method. Running processes retain the previous key until restarted. Do not print the key into a terminal or commit it. Never run multiple clilinkapi instances against overlapping project trees; see the concurrency limitation in the security document.
+
+## API
+
+All endpoints require `Authorization: Bearer <clilinkapi-key>`. One shared key gives its holder access to **all** configured workspaces. There is no per-workspace identity or privilege separation between key holders.
+
+`GET /v1/models` queries the logged-in runtime's `model/list`; it returns visible models, optionally intersected with `provider.allowedModels`. An empty allowlist means all discovered visible models. `reasoning_efforts` is a clilinkapi extension. No static/fabricated model catalog is shipped. A runtime catalog is not a guarantee of remaining quota or a successful future request.
+
+`POST /v1/chat/completions` supports only:
+
+| Field | Behavior |
+| --- | --- |
+| `messages` | Required text-only system, developer, user, assistant messages; at least one user message |
+| `model` | Optional discovered model; otherwise configured default, catalog default, or first discovered model |
+| `reasoning_effort` | Separate native setting validated against that model's discovered efforts |
+| `stream` | Boolean, default false |
+
+`X-Workspace-ID` selects a configured workspace. Clients such as n8n may omit it when `compatibility.defaultWorkspace` is configured. Arbitrary directories and session IDs are rejected. New conversations start ephemeral Codex threads; matching external tool results resume the waiting turn using a bounded, one-use continuation. Send conversation history each time. System/developer messages become Codex developer instructions with role labels; Codex's own instructions remain in force. See [n8n setup and limitations](docs/n8n.md).
+
+Friendly effort labels `Light`, `Medium`, `Strong` map to `low`, `medium`, `high` only if supported. Other values must appear in discovery. Defaults can be set as `provider.defaultModel` and `provider.defaultReasoning`. Invalid defaults or overrides are rejected, never downgraded. Effort is never added to prompt text and is unrelated to verbosity or output limits.
+
+Text messages, function tools and results, `tool_choice: auto/none`, `n: 1`, text response format, and streaming usage requests are supported. Sampling controls, token limits, image inputs, structured output and forced tool choices return 400. Use clients with automatic retries disabled: a failed/timed-out call may already have edited files or invoked an external tool.
+
+## Requests without exposing the key
+
+The following Node example loads the private config locally. Run it as the client identity authorized to read that config; distribute only the clilinkapi key to other clients using your secure method. Set `CLILINKAPI_CONFIG` to its absolute path.
+
+```js
+import { readFile } from 'node:fs/promises';
+const config = JSON.parse(await readFile(process.env.CLILINKAPI_CONFIG, 'utf8'));
+const headers = {
+  Authorization: `Bearer ${config.auth.apiKey}`,
+  'Content-Type': 'application/json',
+  'X-Workspace-ID': 'project-a'
+};
+const catalog = await fetch('http://127.0.0.1:3000/v1/models', { headers }).then(r => r.json());
+const model = catalog.data[0].id;
+const request = { model, reasoning_effort: 'Light', messages: [
+  { role: 'user', content: 'Describe this project without modifying it.' }
+] };
+const response = await fetch('http://127.0.0.1:3000/v1/chat/completions', {
+  method: 'POST', headers, body: JSON.stringify(request)
+});
+console.log(await response.json());
+
+// Real SSE. Incremental final-answer deltas only, with bounded redaction buffering.
+const streaming = await fetch('http://127.0.0.1:3000/v1/chat/completions', {
+  method: 'POST', headers, body: JSON.stringify({ ...request, stream: true })
+});
+for await (const chunk of streaming.body) process.stdout.write(chunk);
+```
+
+Use a reasoning effort listed for the selected model if `low` is unavailable. [OpenAI SDK client example](examples/client.mjs) uses `baseURL`, the locally generated clilinkapi key, workspace selection and `maxRetries: 0`.
+
+Non-streaming responses contain the actual labelled Codex final answer, with host-path/known-secret redaction, at `choices[0].message.content`. Usage is included only when reported by Codex. Tool activity and commentary are excluded. SSE emits final-answer deltas, then a stop chunk and `[DONE]`; errors after headers are SSE error objects followed by connection close, without a successful terminator. If Codex provides only a buffered answer, streaming returns `stream_unavailable`; it is not turned into fake tokens. Redaction holds a small suffix and unfinished word, so very short responses may appear together. Ordinary chat completions generally do not run commands; **these requests can modify files and execute commands** within their configured permissions.
+
+## Deployment and verification
+
+CliLinkAPI requires a dedicated Codex home without custom configuration, hooks, plugins, rules, or skills. Codex can create `skills/.system` during normal startup; CliLinkAPI permits the pinned runtime's bundled skill directories and explicitly disables those skills. Other skill directories remain rejected. A startup rejection identifies the blocked entry so it can be relocated without deleting credentials.
+
+Bind to localhost by default. For network deployment terminate HTTPS at a maintained reverse proxy, disable response buffering for SSE, set upstream timeouts above the clilinkapi timeout, apply request-size/rate limits, and firewall direct access to the clilinkapi port. Direct TLS is not implemented. Do not transmit bearer keys over public plaintext HTTP. No permissive CORS policy is installed.
+
+```sh
+npm run check
+npm test
+npm run build
+npm run test:isolation
+# Set CLILINKAPI_CONFIG to an actual private configuration after ChatGPT login:
+npm run test:live
+```
+
+`test:live` starts a local clilinkapi and requests a real response through HTTP, then checks a temporary permitted file and denied external sentinel reads/writes through further HTTP requests. It cleans up only those uniquely named test files. On Linux/macOS, each eligible generation first probes real sandbox reads, writes, link escapes and subprocess inheritance. Windows generation skips these probes by default; native sandbox initialization may still fail. CI configures Node 22/24 on Windows/Linux/macOS; it does not store ChatGPT credentials or claim to run authenticated live tests.
+
+See [architecture and adapter guide](docs/architecture.md), [security boundaries](docs/security.md), and [checks executed](docs/verification.md).
+
+## Configure unqualified Windows execution
+
+`provider.allowUnqualifiedWindowsExecution` defaults to `true` when omitted. Set it to `false` in your private configuration to block Windows execution, then restart the server. Existing explicit `false` values remain respected.
+
+This setting bypasses the Windows platform gate and skips the per-generation isolation probes on Windows only. It does not certify read, ACL, descendant-process, or network isolation. Native permission profiles are still requested; Codex may still reject a turn or command if the Windows sandbox cannot initialize. There is no automatic unrestricted fallback. Linux/macOS continue to require their probes regardless of this setting.
+
+The startup banner and `doctor` report unqualified execution explicitly. Authentication, configuration ACL checks, workspace validation, and dedicated Codex home checks remain enabled. Use a dedicated runtime account and trusted clients; workspace confinement is not verified in this mode.
+

package/clilinkapi.example.json

@@ -0,0 +1,12 @@
+{
+  "server": { "host": "127.0.0.1", "port": 3000, "timeoutMs": 180000, "maxConcurrency": 2, "maxBodyBytes": 262144 },
+  "auth": { "apiKey": "REPLACE_WITH_A_SECURE_RANDOM_KEY" },
+  "compatibility": { "defaultWorkspace": "project-a", "toolTimeoutMs": 300000, "maxPendingTools": 8 },
+  "provider": { "type": "codex", "authentication": "chatgpt", "codexHome": "C:/Users/YOUR_USER/.clilinkapi/codex", "allowedModels": [], "allowUnqualifiedWindowsExecution": true, "allowProjectSkills": true, "allowSymbolicLinks": true },
+  "workspaces": {
+    "project-a": { "path": "C:/Projects/project-a", "access": "read-write" },
+    "reference-docs": { "path": "C:/Documents/reference", "access": "read-only" }
+  }
+}
+
+

package/dist/src/auth.js

@@ -0,0 +1,9 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { CliLinkAPIError } from './errors.js';
+export function authenticate(header, key) {
+    const supplied = header?.match(/^Bearer ([^\s]+)$/)?.[1] ?? '';
+    const digest = (s) => createHash('sha256').update(s).digest();
+    if (!timingSafeEqual(digest(supplied), digest(key)) || !supplied)
+        throw new CliLinkAPIError(401, 'invalid_api_key', 'Missing or invalid clilinkapi API key.');
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { mkdir, writeFile, rename, unlink, realpath, readdir, lstat } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { loadConfig, parseConfig, validatePaths, readJson } from './config.js';
+import { protect, verifyPrivate, verifyOwner, verifyConfigDirectory } from './permissions.js';
+import { createServer } from './server.js';
+import { createProvider } from './providers/registry.js';
+import { codexBinary, runtimeEnv, verifyRuntime } from './providers/runtime.js';
+import { requireNativePlatform } from './sandbox.js';
+import { normalizeError } from './errors.js';
+import { startupMessage } from './startup.js';
+export const defaultConfig = () => path.join(os.homedir(), '.clilinkapi', 'clilinkapi.json');
+export function resolveConfigFilename(filename) {
+    // cmd.exe leaves $HOME literal; quoted tilde paths also need application expansion.
+    const homePrefix = /^(?:~|\$HOME|\$\{HOME\}|%USERPROFILE%|\$env:USERPROFILE)(?=[\\/]|$)/i;
+    const expanded = filename.replace(homePrefix, () => os.homedir());
+    if (!path.isAbsolute(expanded))
+        throw new Error('Configuration filename must be absolute. Use "~/.clilinkapi/clilinkapi.json" or a full path such as "C:/Users/your-user/.clilinkapi/clilinkapi.json".');
+    return path.normalize(expanded);
+}
+async function privateDirectory(directory) {
+    const created = await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (created)
+        await protect(directory, true);
+    else {
+        // Setup can safely secure an existing empty directory, but must not change
+        // permissions on a shared/nonempty parent as an implicit side effect.
+        await verifyOwner(directory);
+        if ((await readdir(directory)).length === 0)
+            await protect(directory, true);
+    }
+    await verifyPrivate(directory);
+}
+export async function secureConfig(filename) {
+    filename = resolveConfigFilename(filename);
+    const directory = path.dirname(filename);
+    await verifyOwner(directory);
+    const homeDirectory = await realpath(os.homedir()).catch(() => path.resolve(os.homedir()));
+    if (path.parse(directory).root === directory || path.relative(homeDirectory, await realpath(directory)) === '')
+        throw new Error('Use a dedicated configuration directory; refusing to change home or filesystem-root permissions.');
+    const entries = await readdir(directory);
+    const exists = entries.includes(path.basename(filename));
+    let codexHome;
+    if (exists) {
+        await verifyOwner(filename);
+        if (!(await lstat(filename)).isFile())
+            throw new Error('Configuration must be a regular file.');
+        const input = await readJson(filename);
+        if (input && typeof input === 'object' && 'provider' in input && input.provider && typeof input.provider === 'object' && 'codexHome' in input.provider) {
+            const configured = input.provider.codexHome;
+            if (typeof configured !== 'string' || !path.isAbsolute(configured) || path.relative(directory, path.normalize(configured)) !== 'codex')
+                throw new Error('secure-config prepares Codex storage only at the dedicated configuration directory/codex path. Configure that location or secure a different Codex home separately.');
+            codexHome = path.join(directory, 'codex');
+        }
+    }
+    if (entries.some(entry => entry !== path.basename(filename) && !(codexHome && entry === 'codex')))
+        throw new Error('Configuration directory contains other entries. Use a dedicated directory containing only the configuration file and configured codex folder before repairing permissions.');
+    const runtimePaths = [];
+    if (codexHome && entries.includes('codex')) {
+        const collect = async (target) => {
+            await verifyOwner(target);
+            const info = await lstat(target);
+            runtimePaths.push({ path: target, directory: info.isDirectory() });
+            if (info.isDirectory())
+                for (const name of await readdir(target))
+                    await collect(path.join(target, name));
+        };
+        await collect(codexHome);
+        if (!runtimePaths[0]?.directory)
+            throw new Error('Codex home must be a directory.');
+    }
+    await protect(directory, true);
+    if (exists) {
+        await protect(filename);
+        await verifyPrivate(filename);
+    }
+    if (codexHome) {
+        if (!entries.includes('codex')) {
+            await mkdir(codexHome, { mode: 0o700 });
+            runtimePaths.push({ path: codexHome, directory: true });
+        }
+        for (const entry of runtimePaths) {
+            await protect(entry.path, entry.directory);
+            await verifyPrivate(entry.path);
+        }
+    }
+    await verifyPrivate(directory);
+}
+export async function setup(filename, template) {
+    filename = resolveConfigFilename(filename);
+    const input = await readJson(template);
+    if (!input || typeof input !== 'object')
+        throw new Error('Invalid template.');
+    const candidate = input;
+    candidate.auth = { apiKey: randomBytes(32).toString('base64url') };
+    const config = parseConfig(candidate);
+    await privateDirectory(path.dirname(filename));
+    await privateDirectory(config.provider.codexHome);
+    // Exclusive creation: setup never overwrites an existing key.
+    const pending = filename + '.' + randomUUID() + '.tmp';
+    try {
+        // Reserve destination before writing secrets, then verify workspace boundaries.
+        await writeFile(filename, '', { flag: 'wx', mode: 0o600 });
+    }
+    catch {
+        throw new Error('Configuration already exists or cannot be created. Use rotate-key explicitly to rotate a key.');
+    }
+    try {
+        await protect(filename);
+        await validatePaths(config, filename);
+        await writeFile(pending, JSON.stringify(config, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        await protect(pending);
+        await rename(pending, filename);
+    }
+    catch (error) {
+        await unlink(pending).catch(() => undefined);
+        await unlink(filename).catch(() => undefined);
+        throw error;
+    }
+}
+export async function rotate(filename) {
+    filename = resolveConfigFilename(filename);
+    await verifyConfigDirectory(path.dirname(filename));
+    await verifyPrivate(filename);
+    const input = await readJson(filename);
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('Invalid configuration.');
+    // Explicit rotation must also recover from a placeholder/invalid old key.
+    // Validate every other setting before atomically replacing the file.
+    const config = parseConfig({ ...input, auth: { apiKey: randomBytes(32).toString('base64url') } });
+    await validatePaths(config, filename);
+    const temp = filename + '.' + randomUUID() + '.tmp';
+    try {
+        await writeFile(temp, JSON.stringify(config, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        await protect(temp);
+        await rename(temp, filename);
+    }
+    finally {
+        await unlink(temp).catch(() => undefined);
+    }
+}
+async function main() {
+    const [command = 'help', configArgument = defaultConfig(), template] = process.argv.slice(2);
+    const filename = resolveConfigFilename(configArgument);
+    if (command === 'secure-config') {
+        await secureConfig(filename);
+        console.log('Configuration permissions repaired. File contents and API key were not changed.');
+        return;
+    }
+    if (command === 'setup') {
+        if (!template)
+            throw new Error('Usage: clilinkapi setup ABSOLUTE_CONFIG_PATH TEMPLATE_JSON_PATH');
+        await setup(filename, template);
+        console.log('Configuration created privately. Key was not printed.');
+        return;
+    }
+    if (command === 'rotate-key') {
+        await rotate(filename);
+        console.log('CliLinkAPI key rotated. Restart the clilinkapi and update clients. Key was not printed.');
+        return;
+    }
+    if (!['serve', 'login', 'doctor'].includes(command)) {
+        console.log('Commands: setup CONFIG TEMPLATE | secure-config CONFIG | rotate-key CONFIG | login CONFIG [--device-auth] | doctor CONFIG | serve CONFIG\nDefault CONFIG: user home/.clilinkapi/clilinkapi.json');
+        return;
+    }
+    await verifyConfigDirectory(path.dirname(filename));
+    await verifyPrivate(filename);
+    const config = await loadConfig(filename);
+    await verifyPrivate(config.provider.codexHome);
+    await verifyRuntime(config.provider.codexHome);
+    if (command === 'login') {
+        if (template && template !== '--device-auth')
+            throw new Error('Only --device-auth is accepted after the config path.');
+        const child = spawn(codexBinary(), ['-c', 'forced_login_method="chatgpt"', 'login', ...(template ? [template] : [])], { env: runtimeEnv(config.provider.codexHome), cwd: config.provider.codexHome, stdio: 'inherit', windowsHide: true });
+        await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', code => code === 0 ? resolve() : reject(new Error('Official Codex login did not complete.'))); });
+        return;
+    }
+    const provider = createProvider(config, await realpath(filename));
+    if (command === 'doctor') {
+        let failed = false;
+        try {
+            requireNativePlatform(config.provider.allowUnqualifiedWindowsExecution);
+            console.log(process.platform === 'win32' && config.provider.allowUnqualifiedWindowsExecution
+                ? 'WARNING: Unqualified Windows execution enabled. Isolation probes are skipped; read/ACL/descendant isolation is not verified. Native permission profiles remain requested and may still fail.'
+                : 'Native platform is eligible; each generation still requires isolation probes.');
+        }
+        catch (error) {
+            console.log(normalizeError(error).message);
+            failed = true;
+        }
+        try {
+            const models = await provider.models(AbortSignal.timeout(30000));
+            console.log(JSON.stringify({ chatgpt_login: true, models: models.map(m => ({ id: m.id, reasoning_efforts: m.efforts })) }));
+        }
+        catch (error) {
+            console.log(normalizeError(error).message);
+            failed = true;
+        }
+        finally {
+            await provider.close();
+        }
+        if (failed)
+            process.exitCode = 1;
+        return;
+    }
+    const app = createServer(config, provider);
+    await new Promise((resolve, reject) => { app.server.once('error', reject); app.server.listen(config.server.port, config.server.host, resolve); });
+    const address = app.server.address();
+    if (address && typeof address !== 'string')
+        console.log(startupMessage(config, address));
+    let closing = false;
+    const close = () => { if (!closing) {
+        closing = true;
+        void app.close();
+    } };
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(await realpath(process.argv[1])).href)
+    main().catch(error => {
+        // Only configuration errors are displayed locally. Never stringify runtime objects.
+        console.error(error instanceof Error ? error.message : 'CliLinkAPI startup failed.');
+        process.exitCode = 1;
+    });
+//# sourceMappingURL=cli.js.map

package/dist/src/config.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import path from 'node:path';
+import { lstat, realpath, readFile, stat, readdir } from 'node:fs/promises';
+import { CliLinkAPIError } from './errors.js';
+export const configSchema = z.strictObject({
+    server: z.strictObject({ host: z.string().min(1).default('127.0.0.1'), port: z.number().int().min(1).max(65535).default(3000), timeoutMs: z.number().int().min(1000).max(3600000).default(180000), maxConcurrency: z.number().int().min(1).max(16).default(2), maxBodyBytes: z.number().int().min(1024).max(1048576).default(262144) }).default({ host: '127.0.0.1', port: 3000, timeoutMs: 180000, maxConcurrency: 2, maxBodyBytes: 262144 }),
+    auth: z.strictObject({ apiKey: z.string().min(43).max(256).refine(v => !/replace|placeholder|changeme|example|your[_-]?key/i.test(v) && new Set(v).size >= 16, 'Generate a clilinkapi key with setup or rotate-key') }),
+    compatibility: z.strictObject({ defaultWorkspace: z.string().optional(), toolTimeoutMs: z.number().int().min(1000).max(1800000).default(300000), maxPendingTools: z.number().int().min(1).max(64).default(8) }).default({ toolTimeoutMs: 300000, maxPendingTools: 8 }),
+    provider: z.strictObject({ type: z.literal('codex'), authentication: z.literal('chatgpt'), allowUnqualifiedWindowsExecution: z.boolean().default(true), allowProjectSkills: z.boolean().default(true), allowSymbolicLinks: z.boolean().default(true), codexHome: z.string().min(1), allowedModels: z.array(z.string().regex(/^[a-zA-Z0-9._-]+$/)).default([]), defaultModel: z.string().optional(), defaultReasoning: z.string().optional() }),
+    workspaces: z.record(z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/), z.strictObject({ path: z.string(), access: z.enum(['read-only', 'read-write']) })).refine(v => Object.keys(v).length > 0, 'Configure at least one workspace')
+});
+export const inside = (root, target) => { const r = path.relative(root, target); return r === '' || (!r.startsWith('..' + path.sep) && r !== '..' && !path.isAbsolute(r)); };
+export function parseConfig(value) {
+    const result = configSchema.safeParse(value);
+    if (!result.success)
+        throw new Error('Invalid configuration: ' + result.error.issues.map(i => i.path.join('.') + ': ' + i.message).join('; '));
+    if (result.data.compatibility.defaultWorkspace && !Object.hasOwn(result.data.workspaces, result.data.compatibility.defaultWorkspace))
+        throw new Error('compatibility.defaultWorkspace must name a configured workspace.');
+    return result.data;
+}
+export async function canonicalDirectory(directory) {
+    if (!path.isAbsolute(directory))
+        throw new Error('Workspace and Codex home paths must be absolute native paths.');
+    const resolved = await realpath(directory);
+    if (!(await stat(resolved)).isDirectory() || path.parse(resolved).root === resolved)
+        throw new Error('Directories must exist and must not be filesystem roots.');
+    return resolved;
+}
+export async function validatePaths(config, filename) {
+    const configPath = await realpath(filename);
+    config.provider.codexHome = await canonicalDirectory(config.provider.codexHome);
+    const roots = [];
+    for (const workspace of Object.values(config.workspaces)) {
+        workspace.path = await canonicalDirectory(workspace.path);
+        if (inside(workspace.path, configPath) || inside(workspace.path, config.provider.codexHome) || inside(config.provider.codexHome, workspace.path))
+            throw new Error('Keep clilinkapi configuration and Codex credential storage outside every workspace.');
+        if (roots.some(root => inside(root, workspace.path) || inside(workspace.path, root)))
+            throw new Error('Workspace directories must not overlap or alias one another.');
+        roots.push(workspace.path);
+    }
+}
+export async function loadConfig(filename) {
+    if ((await lstat(filename)).isSymbolicLink())
+        throw new Error('Configuration must not be a symlink.');
+    const config = parseConfig(await readJson(filename));
+    await validatePaths(config, filename);
+    return config;
+}
+export async function readJson(filename) {
+    const text = await readFile(filename, 'utf8');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('Configuration is not valid JSON. Check syntax locally; file contents are intentionally omitted.');
+    }
+}
+// Defense in depth only: native enforcement is still mandatory for races and links
+// created by an executing agent. Hard-linked files are rejected; project configuration
+// is ignored by the runtime's untrusted-project policy.
+export async function inspectWorkspace(workspace, allowSymbolicLinks = true) {
+    const projectSkills = [];
+    if (await realpath(workspace.path) !== workspace.path)
+        throw new CliLinkAPIError(403, 'workspace_changed', 'Workspace identity changed. Restart after reviewing configuration.');
+    const walk = async (directory, ancestors) => {
+        const resolved = await realpath(directory);
+        if (!inside(workspace.path, resolved) || ancestors.has(resolved))
+            throw new CliLinkAPIError(403, 'workspace_link', 'Workspace links must stay inside the workspace and must not form directory cycles.');
+        const nextAncestors = new Set(ancestors).add(resolved);
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const filename = path.join(directory, entry.name);
+            let info = await lstat(filename);
+            if (info.isSymbolicLink()) {
+                if (!allowSymbolicLinks)
+                    throw new CliLinkAPIError(403, 'workspace_link', 'Symbolic links and junctions are disabled by provider.allowSymbolicLinks.');
+                let target;
+                try {
+                    target = await realpath(filename);
+                }
+                catch {
+                    throw new CliLinkAPIError(403, 'workspace_link', 'Workspace symbolic links must resolve to an existing target without link loops.');
+                }
+                if (!inside(workspace.path, target))
+                    throw new CliLinkAPIError(403, 'workspace_link', 'Symbolic links and junctions must point inside the same workspace.');
+                info = await stat(filename);
+            }
+            if (!info.isDirectory() && info.nlink > 1)
+                throw new CliLinkAPIError(403, 'workspace_link', 'Hard-linked files are not supported in workspaces.');
+            if (!info.isDirectory() && entry.name.toLowerCase() === 'skill.md')
+                projectSkills.push(filename);
+            if (info.isDirectory())
+                await walk(filename, nextAncestors);
+        }
+    };
+    await walk(workspace.path, new Set());
+    return projectSkills;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/errors.js

@@ -0,0 +1,24 @@
+export class CliLinkAPIError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function normalizeError(error) {
+    if (error instanceof CliLinkAPIError)
+        return error;
+    // Never pass raw upstream errors (which can contain paths, prompts, or credentials).
+    const text = error instanceof Error ? error.message : '';
+    if (/rate.?limit|quota|usage limit/i.test(text))
+        return new CliLinkAPIError(429, 'upstream_rate_limit', 'Codex usage limit reached. Check your ChatGPT workspace subscription.');
+    if (/auth|unauthorized|login|token expired|401/i.test(text))
+        return new CliLinkAPIError(503, 'upstream_authentication', 'Codex ChatGPT login is missing or expired. Run clilinkapi login as the runtime user.');
+    if (/approval|permission|sandbox/i.test(text))
+        return new CliLinkAPIError(403, 'execution_denied', 'Codex denied execution under the configured permissions. No escalation was approved.');
+    return new CliLinkAPIError(502, 'upstream_error', 'Codex execution failed. Check runtime access and retry deliberately; changes may already have occurred.');
+}
+export const errorBody = (error) => ({ error: { message: error.message, type: error.status === 401 ? 'authentication_error' : error.status < 500 ? 'invalid_request_error' : 'server_error', param: null, code: error.code } });
+//# sourceMappingURL=errors.js.map

package/dist/src/permissions.js

@@ -0,0 +1,64 @@
+import { chmod, lstat } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+// Static PowerShell program; the filename is passed through an environment variable,
+// never interpolated into executable code. Restrict to current identity and SYSTEM.
+const readAcl = `$ErrorActionPreference='Stop'; $p=$env:CLILINKAPI_ACL_PATH; $dir=[System.IO.Directory]::Exists($p); $a=if($dir){[System.IO.Directory]::GetAccessControl($p)}else{[System.IO.File]::GetAccessControl($p)};`;
+const aclScript = readAcl + `$s=[System.Security.Principal.WindowsIdentity]::GetCurrent().User; if($a.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $s.Value){$a.SetOwner($s)}; $a.SetAccessRuleProtection($true,$false); foreach($r in @($a.Access)){[void]$a.RemoveAccessRuleSpecific($r)}; $inherit=if($dir){'ContainerInherit,ObjectInherit'}else{'None'}; foreach($id in @($s.Value,'S-1-5-18')) { $sid=[System.Security.Principal.SecurityIdentifier]::new($id); $r=[System.Security.AccessControl.FileSystemAccessRule]::new($sid,'FullControl',$inherit,'None','Allow'); $a.AddAccessRule($r) }; if($dir){[System.IO.Directory]::SetAccessControl($p,$a)}else{[System.IO.File]::SetAccessControl($p,$a)}`;
+const verifyScript = readAcl + `$s=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; if($a.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $s){exit 2}; foreach($r in $a.Access){$id=$r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value; if($r.AccessControlType -eq 'Allow' -and $id -ne $s -and $id -ne 'S-1-5-18'){exit 3}}`;
+async function windows(script, filename) { await exec('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], { env: { ...process.env, CLILINKAPI_ACL_PATH: filename }, windowsHide: true, timeout: 10000 }); }
+export async function protect(filename, directory = false) { if (process.platform === 'win32')
+    await windows(aclScript, filename);
+else
+    await chmod(filename, directory ? 0o700 : 0o600); }
+export async function verifyOwner(filename) {
+    const info = await lstat(filename);
+    if (info.isSymbolicLink() || (!info.isDirectory() && info.nlink > 1))
+        throw new Error('Secret storage must not be a symbolic or hard link.');
+    if (process.platform === 'win32') {
+        try {
+            await windows(readAcl + `$s=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; if($a.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $s){exit 2}`, filename);
+        }
+        catch {
+            throw new Error('Secret storage must be owned by the current runtime user before permissions can be repaired.');
+        }
+    }
+    else if (process.getuid && info.uid !== process.getuid())
+        throw new Error('Secret storage must be owned by the current runtime user before permissions can be repaired.');
+}
+export async function verifyPrivate(filename) {
+    const info = await lstat(filename);
+    if (info.isSymbolicLink() || (!info.isDirectory() && info.nlink > 1))
+        throw new Error('Secret storage must not be a symbolic or hard link.');
+    if (process.platform === 'win32') {
+        try {
+            await windows(verifyScript, filename);
+        }
+        catch {
+            throw new Error(`Private storage check failed for "${filename}": ACL must grant access only to the runtime user and SYSTEM. Run: npm run clilinkapi -- secure-config CONFIG_PATH`);
+        }
+    }
+    else if ((info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+        throw new Error('Secret storage must be owned by the runtime user, with mode 0600 (file) or 0700 (directory).');
+}
+// A parent may be traversable/readable without making a protected secret file
+// readable. Reject other identities' directory mutation rights, which could
+// permit replacing that file. The file itself must still pass verifyPrivate.
+export async function verifyConfigDirectory(directory) {
+    await verifyOwner(directory);
+    if (!(await lstat(directory)).isDirectory())
+        throw new Error('Configuration parent must be a directory.');
+    if (process.platform !== 'win32') {
+        await verifyPrivate(directory);
+        return;
+    }
+    const script = readAcl + `$s=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; $unsafe=[System.Security.AccessControl.FileSystemRights]::Write -bor [System.Security.AccessControl.FileSystemRights]::Delete -bor [System.Security.AccessControl.FileSystemRights]::DeleteSubdirectoriesAndFiles -bor [System.Security.AccessControl.FileSystemRights]::ChangePermissions -bor [System.Security.AccessControl.FileSystemRights]::TakeOwnership; foreach($r in $a.Access){$id=$r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value; if($r.AccessControlType -eq 'Allow' -and $id -ne $s -and $id -ne 'S-1-5-18' -and ($r.FileSystemRights -band $unsafe) -ne 0){exit 3}}`;
+    try {
+        await windows(script, directory);
+    }
+    catch {
+        throw new Error(`Configuration directory "${directory}" permits modification by another account. Run: npm run clilinkapi -- secure-config CONFIG_PATH`);
+    }
+}
+//# sourceMappingURL=permissions.js.map