superlean-codex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperleanAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# Superlean Codex
+
+Run Codex through SuperleanAI while keeping your existing ChatGPT login.
+
+## Install
+
+Install the launcher globally, then run it from any project:
+
+```sh
+npm install -g superlean-codex
+superlean-codex
+```
+
+Or install and launch it in one command:
+
+```sh
+npx --yes superlean-codex@latest
+```
+
+Requires Node.js 22+ with npm on macOS, Linux, or WSL.
+
+## First run
+
+The launcher:
+
+1. Checks that Codex is already signed in with ChatGPT.
+2. Opens the Superlean dashboard in your browser.
+3. Asks you to approve **Connect Codex** using the code shown in the terminal.
+4. Saves your Superlean identity key and starts Codex in the current project.
+
+If the first check fails, run `codex login` directly and choose **Sign in with
+ChatGPT**, then run `superlean-codex` again. Superlean does not read, copy, or
+store the ChatGPT tokens in Codex's credential store.
+
+After setup, use the launcher just like Codex:
+
+```sh
+superlean-codex
+superlean-codex --resume
+superlean-codex exec "Explain this repository"
+```
+
+Reconnect to Superlean after a key expires or is revoked:
+
+```sh
+superlean-codex login
+```
+
+Reconnects reuse the existing usable Codex key entry. A new entry is created
+only when none can be reused.
+
+## What it installs
+
+The first run writes the shell launcher to `~/.superlean/bin`, adds that
+directory to Bash or Zsh startup files, and stores the Superlean identity key
+in `~/.superlean/codex.env.sh` with owner-only permissions. Personal overrides
+in `~/.superlean/codex-user.env.sh` are preserved across reinstalls.
+
+An existing Codex installation is used when available. Otherwise, npm runs the
+official `@openai/codex` package from its cache. The launcher preserves your
+current directory and forwards all Codex arguments.
+
+The launcher applies these settings only to the Codex process it starts; it
+does not rewrite your normal Codex configuration:
+
+```toml
+model_provider = "superlean"
+
+[model_providers.superlean]
+name = "SuperleanAI"
+base_url = "https://api.superleanai.com/codex/v1"
+wire_api = "responses"
+requires_openai_auth = true
+env_http_headers = { "X-SuperleanAI-Key" = "SUPERLEANAI_CODEX_KEY" }
+```
+
+`requires_openai_auth` keeps your ChatGPT authentication in the Authorization
+header. The separate `X-SuperleanAI-Key` header identifies your Superlean
+account and is removed by the gateway before the request is forwarded.
+
+## Other install options
+
+Set up the launcher without starting Codex:
+
+```sh
+npx --yes superlean-codex@latest install
+```
+
+Use `--no-profile` to leave shell startup files unchanged. If the installer
+does not edit a profile, it prints the PATH command to add manually.
+
+Pass Codex arguments through the npm entry point after `--`:
+
+```sh
+npx --yes superlean-codex@latest -- --help
+```
+
+## Development
+
+```sh
+npm test
+npm run check
+npm pack --dry-run
+node bin/superlean.js --help
+```
+
+The browser login protocol is documented in
+[docs/service-login.md](docs/service-login.md).
+
+## Releasing
+
+CI (`.github/workflows/ci.yml`) runs tests and static checks on Node 22 and 24
+for every push to `main` and every pull request. CD
+(`.github/workflows/publish.yml`) publishes to npm when a GitHub Release is
+published, using [npm trusted publishing](https://docs.npmjs.com/trusted-publishers)
+(OIDC) with provenance. No npm token is stored in GitHub.
+
+One-time setup:
+
+1. If the package does not exist on npm yet, publish the first version manually
+   by running `npm publish` from a local checkout.
+2. On npmjs.com, open the package page → **Settings** → **Trusted Publisher**
+   and add a GitHub Actions publisher with organization `superleanai`,
+   repository `superlean-codex`, and workflow filename `publish.yml`.
+
+To cut a release:
+
+```sh
+npm version patch   # or minor / major
+git push --follow-tags
+gh release create v0.1.1 --generate-notes
+```
+
+The release tag must match the version in `package.json`, and `prepublishOnly`
+runs the test suite and static checks before the package is uploaded.
+
+## License
+
+MIT © SuperleanAI. See [LICENSE](LICENSE).

package/bin/superlean.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { install, shellQuote } from '../lib/install.js';
+
+const help = `Usage:
+  npx superlean-codex@latest                  Set up and launch Codex
+  npx superlean-codex@latest install          Set up without launching
+  npx superlean-codex@latest login            Sign in to Superlean again
+  npx superlean-codex@latest --no-profile     Leave shell profiles unchanged
+  npx superlean-codex@latest -- [args]        Pass arguments to Codex
+
+After setup, use superlean-codex in a new terminal.
+Requires macOS, Linux, or WSL and Node.js 22+ with npm.`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  let launch = true;
+  let profile = true;
+  while (args.length) {
+    const arg = args[0];
+    if (arg === '--') { args.shift(); break; }
+    if (arg === '--help' || arg === '-h') { console.log(help); return; }
+    if (arg === '--no-profile') { profile = false; args.shift(); continue; }
+    if (arg === 'install') { launch = false; args.shift(); continue; }
+    break;
+  }
+  if (process.platform === 'win32') throw new Error('Use WSL for the Superlean shell launcher.');
+  const result = await install({ home: homedir(), shell: process.env.SHELL, profile });
+  console.log(`Superlean installed. Environment: ${result.envPath}`);
+  if (result.profiles.length) console.log('Next time, open a new terminal and run superlean-codex.');
+  else console.log(`Add the launcher to this shell: export PATH=${shellQuote(result.binDir)}:"$PATH"`);
+  if (!launch) return;
+  console.log('Checking your Codex login before applying Superlean settings.');
+  const child = spawn(result.launcherPath, args, { stdio: 'inherit' });
+  const onInterrupt = () => {};
+  const onTerminate = () => child.kill('SIGTERM');
+  process.on('SIGINT', onInterrupt);
+  process.on('SIGTERM', onTerminate);
+  const { code, signal } = await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+  process.removeListener('SIGINT', onInterrupt);
+  process.removeListener('SIGTERM', onTerminate);
+  process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 143);
+}
+main().catch((error) => { console.error(`Superlean: ${error.message}`); process.exitCode = 1; });

package/docs/service-login.md

@@ -0,0 +1,21 @@
+# Browser-approved CLI login
+
+The launcher creates a random verifier and sends its SHA-256 challenge to
+`POST /api/cli/login` with `provider: "codex"`. The dashboard returns a
+short-lived flow ID and browser approval URL. After the signed-in user approves
+the matching code, only the terminal holding the verifier can redeem the flow.
+
+The redemption response contains a Codex-scoped Superlean JWT. The launcher
+writes it to `~/.superlean/codex.env.sh` and exposes it to Codex as
+`SUPERLEANAI_CODEX_KEY`. Codex reads that value through `env_http_headers` and
+sends it as `X-SuperleanAI-Key`; its own ChatGPT bearer token remains in the
+Authorization header.
+
+The gateway accepts this combination only on the `/codex` profile, verifies
+that the Superlean key has a live `proxy:codex` database row, strips the
+identity header, and forwards the user's ChatGPT credential. Reconnecting
+reuses the most recent usable Codex key entry.
+
+The flow stores neither the verifier nor either bearer credential. Flow IDs
+are hashed in the database, approvals expire after ten minutes, and successful
+redemption deletes the flow.

package/lib/check-codex-auth.js

@@ -0,0 +1,9 @@
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+  if (input.length > 64 * 1024) process.exit(1);
+});
+process.stdin.on('end', () => {
+  process.exit(/^Logged in using ChatGPT\s*$/m.test(input) ? 0 : 1);
+});

package/lib/configure-codex.js

@@ -0,0 +1,25 @@
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { shellQuote } from './shell-quote.js';
+
+function safe(value, name, { nonempty = true } = {}) {
+  if (typeof value !== 'string' || (nonempty && !value) || /[\r\n\0]/.test(value)) {
+    throw new Error(`${name} must be ${nonempty ? 'a nonempty string' : 'a string'} without newlines.`);
+  }
+  return value;
+}
+
+export async function configureCodex({ directory, baseUrl = 'https://api.superleanai.com/codex/v1', userKey }) {
+  safe(directory, 'directory');
+  safe(userKey, 'user key');
+  const parsed = new URL(safe(baseUrl, 'base URL'));
+  if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+    throw new Error('base URL must be an HTTP(S) URL without embedded credentials.');
+  }
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, 'codex.env.sh');
+  const contents = `# Generated by Superlean. Reconnect with: superlean-codex login\nunset OPENAI_API_KEY\nexport SUPERLEANAI_CODEX_KEY=${shellQuote(userKey)}\n`;
+  await writeFile(path, contents, { mode: 0o600 });
+  await chmod(path, 0o600);
+  return path;
+}

package/lib/install.js

@@ -0,0 +1,68 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { shellQuote } from './shell-quote.js';
+export { shellQuote } from './shell-quote.js';
+
+const marker = '# >>> Superlean >>>';
+const endMarker = '# <<< Superlean <<<';
+
+async function readOptional(path) {
+  try { return await readFile(path, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function updateProfile(path, binDir) {
+  const current = (await readOptional(path)) ?? '';
+  const block = `${marker}\ncase ":$PATH:" in\n  *:${shellQuote(binDir)}:*) ;;\n  *) export PATH=${shellQuote(binDir)}:"$PATH" ;;\nesac\n${endMarker}`;
+  const start = current.indexOf(marker);
+  let updated;
+  if (start === -1) updated = `${current}${current.endsWith('\n') || !current ? '' : '\n'}\n${block}\n`;
+  else {
+    const end = current.indexOf(endMarker, start);
+    if (end === -1) throw new Error(`Incomplete Superlean block in ${path}; repair it and retry.`);
+    updated = current.slice(0, start) + block + current.slice(end + endMarker.length);
+  }
+  if (updated !== current) await writeFile(path, updated, { mode: 0o600 });
+}
+
+export async function install({ home, shell = '', profile = true }) {
+  if (!home || /[\r\n]/.test(home)) throw new Error('A home directory without newlines is required.');
+  const directory = join(home, '.superlean');
+  const binDir = join(directory, 'bin');
+  const libDir = join(directory, 'lib-codex');
+  await mkdir(binDir, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  await mkdir(libDir, { recursive: true, mode: 0o700 });
+  await writeFile(join(libDir, 'package.json'), '{"type":"module"}\n', { mode: 0o600 });
+  for (const name of ['service-login.js', 'configure-codex.js', 'shell-quote.js', 'check-codex-auth.js']) {
+    await writeFile(join(libDir, name), await readFile(new URL(name, import.meta.url), 'utf8'), { mode: 0o600 });
+  }
+  await writeFile(join(directory, 'codex-defaults.sh'), await readFile(new URL('../shell/env.sh', import.meta.url), 'utf8'), { mode: 0o600 });
+  const envPath = join(directory, 'codex-user.env.sh');
+  try { await writeFile(envPath, '# Personal Codex overrides. Preserved when Superlean is reinstalled.\n', { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const launcherPath = join(binDir, 'superlean-codex');
+  const script = (await readFile(new URL('../shell/launcher.sh', import.meta.url), 'utf8'))
+    .replaceAll('__SUPERLEAN_DIR__', shellQuote(directory))
+    .replaceAll('__SUPERLEAN_LIB_DIR__', shellQuote(libDir));
+  await writeFile(launcherPath, script, { mode: 0o700 });
+  await chmod(launcherPath, 0o700);
+  const profiles = [];
+  if (profile) {
+    switch (basename(shell)) {
+      case 'zsh': profiles.push(join(home, '.zshrc')); break;
+      case 'bash': {
+        profiles.push(join(home, '.bashrc'));
+        const loginFiles = ['.bash_profile', '.bash_login', '.profile'];
+        let loginFile = '.profile';
+        for (const file of loginFiles) if (await readOptional(join(home, file)) !== null) { loginFile = file; break; }
+        profiles.push(join(home, loginFile));
+        break;
+      }
+      case 'sh': case 'dash': case '': profiles.push(join(home, '.profile')); break;
+      default: break;
+    }
+    for (const path of profiles) await updateProfile(path, binDir);
+  }
+  return { directory, binDir, envPath, launcherPath, profiles };
+}

package/lib/service-login.js

@@ -0,0 +1,85 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { pathToFileURL } from 'node:url';
+import { configureCodex } from './configure-codex.js';
+
+export async function openBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : 'xdg-open';
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, [url], { stdio: 'ignore', detached: true });
+    child.unref();
+    child.once('error', reject);
+    child.once('exit', (code) => code === 0 ? resolve() : reject(new Error('Browser could not open.')));
+  });
+}
+
+export async function serviceLogin({
+  dashboard = 'https://dashboard.superleanai.com', fetchFn = fetch,
+  openUrl = openBrowser, wait = delay, output = console.log, signal,
+} = {}) {
+  const origin = new URL(dashboard);
+  if (origin.protocol !== 'https:' && !(origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname))) {
+    throw new Error('Superlean sign-in requires HTTPS, except on localhost.');
+  }
+  async function post(path, body) {
+    const response = await fetchFn(new URL(path, origin), {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body), redirect: 'error',
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15000)]) : AbortSignal.timeout(15000),
+    });
+    let data;
+    try { data = await response.json(); } catch {
+      throw new Error('Superlean CLI sign-in is unavailable. The dashboard must include the CLI login endpoints.');
+    }
+    return { response, data };
+  }
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const { response: started, data: flow } = await post('/api/cli/login', { code_challenge: challenge, provider: 'codex' });
+  if (started.status !== 201 || !/^[A-Za-z0-9_-]{43}$/.test(flow.flow_id ?? '')
+      || typeof flow.verification_uri !== 'string' || !Number.isFinite(flow.expires_in)
+      || flow.expires_in <= 0 || flow.expires_in > 600 || !Number.isFinite(flow.interval)
+      || flow.interval < 1 || flow.interval > 30) {
+    throw new Error('Superlean could not start CLI sign-in. Check that the updated dashboard is deployed.');
+  }
+  const verificationUrl = new URL(flow.verification_uri, origin);
+  if (verificationUrl.origin !== origin.origin || verificationUrl.pathname !== '/cli/authorize'
+      || verificationUrl.searchParams.get('flow') !== flow.flow_id) {
+    throw new Error('The dashboard returned an invalid sign-in URL.');
+  }
+  const userCode = `${flow.flow_id.slice(0, 4)}-${flow.flow_id.slice(4, 8)}`;
+  const displayCode = process.stdout.isTTY ? `\u001b[1m${userCode}\u001b[22m` : userCode;
+  output(`\n\nSign in to Superlean and approve code ${displayCode}:\n\n`);
+  output(verificationUrl.href);
+  const deadline = Date.now() + flow.expires_in * 1000;
+  // A missing browser (for example over SSH) leaves the printed URL usable.
+  Promise.resolve().then(() => openUrl(verificationUrl.href)).catch(() => {});
+  while (Date.now() < deadline) {
+    await wait(Math.min(flow.interval * 1000, Math.max(0, deadline - Date.now())), undefined, { signal });
+    if (Date.now() >= deadline) break;
+    const { response, data } = await post('/api/cli/login/token', { flow_id: flow.flow_id, code_verifier: verifier });
+    if (response.status === 202 && data.error === 'authorization_pending') continue;
+    if (response.status === 200 && typeof data.user_key === 'string' && data.user_key.trim()) {
+      return data.user_key;
+    }
+    if (response.status === 402) throw new Error('An active Superlean subscription is required. Visit https://dashboard.superleanai.com/subscription, then retry.');
+    if (response.status === 410) throw new Error('Superlean sign-in expired or was already used. Run the launcher again.');
+    throw new Error('Superlean could not complete sign-in. Run the launcher again.');
+  }
+  throw new Error('Superlean sign-in expired. Run the launcher again.');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const controller = new AbortController();
+  process.once('SIGINT', () => controller.abort());
+  process.once('SIGTERM', () => controller.abort());
+  try {
+    const userKey = await serviceLogin({ signal: controller.signal });
+    await configureCodex({ directory: process.argv[2], userKey });
+    console.log('Superlean connected. Starting Codex.');
+  } catch (error) {
+    console.error(controller.signal.aborted ? 'Superlean sign-in cancelled.' : `Superlean: ${error.message}`);
+    process.exitCode = controller.signal.aborted ? 130 : 1;
+  }
+}

package/lib/shell-quote.js

@@ -0,0 +1,3 @@
+export function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "superlean-codex",
+  "version": "0.1.0",
+  "description": "One-command setup and shell launcher for Codex through SuperleanAI.",
+  "license": "MIT",
+  "author": "SuperleanAI",
+  "homepage": "https://github.com/superleanai/superlean-codex#readme",
+  "bugs": {
+    "url": "https://github.com/superleanai/superlean-codex/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superleanai/superlean-codex.git"
+  },
+  "keywords": [
+    "codex",
+    "openai",
+    "superleanai",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "superlean-codex": "bin/superlean.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "shell/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/superlean.js && node --check lib/install.js && node --check lib/configure-codex.js && node --check lib/service-login.js && node --check lib/check-codex-auth.js && sh -n shell/launcher.sh && sh -n shell/env.sh",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/shell/env.sh

@@ -0,0 +1,3 @@
+# Superlean defaults. Add environment variables shipped to all users here.
+# This file is sourced only by the Superlean Codex launcher.
+# Keep user credentials out of this package.

package/shell/launcher.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+set -eu
+
+superlean_dir=__SUPERLEAN_DIR__
+superlean_lib_dir=__SUPERLEAN_LIB_DIR__
+
+if ! command -v node >/dev/null 2>&1; then
+  echo 'Superlean: install Node.js 22+ (with npm) and try again.' >&2
+  exit 127
+fi
+if (
+  unset OPENAI_API_KEY SUPERLEANAI_CODEX_KEY
+  if command -v codex >/dev/null 2>&1; then
+    superlean_auth=$(codex login status 2>&1) || exit "$?"
+  elif command -v npx >/dev/null 2>&1; then
+    superlean_auth=$(npx --yes --package=@openai/codex@latest -- codex login status 2>&1) || exit "$?"
+  else
+    echo 'Superlean: install Node.js 22+ (with npm), or install Codex and try again.' >&2
+    exit 127
+  fi
+  printf '%s' "$superlean_auth" | node "$superlean_lib_dir/check-codex-auth.js"
+); then
+  :
+else
+  superlean_status=$?
+  echo 'Superlean: could not confirm your ChatGPT login. Run codex login without Superlean settings, then retry.' >&2
+  exit "$superlean_status"
+fi
+
+. "$superlean_dir/codex-defaults.sh"
+. "$superlean_dir/codex-user.env.sh"
+
+superlean_login=false
+if [ "${1-}" = login ]; then superlean_login=true; shift; fi
+if [ "$superlean_login" = true ] || [ ! -f "$superlean_dir/codex.env.sh" ]; then
+  node "$superlean_lib_dir/service-login.js" "$superlean_dir"
+fi
+. "$superlean_dir/codex.env.sh"
+
+set -- \
+  -c 'model_provider="superlean"' \
+  -c 'model_providers.superlean.name="SuperleanAI"' \
+  -c 'model_providers.superlean.base_url="https://api.superleanai.com/codex/v1"' \
+  -c 'model_providers.superlean.wire_api="responses"' \
+  -c 'model_providers.superlean.requires_openai_auth=true' \
+  -c 'model_providers.superlean.env_http_headers={"X-SuperleanAI-Key"="SUPERLEANAI_CODEX_KEY"}' \
+  "$@"
+
+if command -v codex >/dev/null 2>&1; then exec codex "$@"; fi
+if ! command -v npx >/dev/null 2>&1; then
+  echo 'Superlean: install Node.js 22+ (with npm), or install Codex and try again.' >&2
+  exit 127
+fi
+exec npx --yes --package=@openai/codex@latest -- codex "$@"