@ivora/cli 0.0.0-stage → 0.1.0

package/dist/lib/secrets.js

@@ -0,0 +1,151 @@
+/**
+ * Secret handling: redaction of keys, webhook secrets and credentials in anything the CLI
+ * prints, and the secret-store interface. Keys are stored in the OS keychain only (macOS Keychain
+ * or the freedesktop Secret Service). There is no plain-text file fallback: where no keychain
+ * is available, `ivora login` refuses and `IVORA_API_KEY` is the way to supply a key.
+ */
+import { execFile } from 'node:child_process';
+import { CliError, ExitCode } from './output.js';
+const API_KEY = /\biv_(test|live)_[A-Za-z0-9_-]+/g;
+const WEBHOOK_SECRET = /\bwhsec_[A-Za-z0-9+/=_-]+/g;
+const AUTH_SCHEME = /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi;
+export const REDACTED = '[redacted]';
+/** Redacts API keys, webhook secrets and Bearer/Basic credentials in free text. */
+export function redact(text) {
+    return text
+        .replace(API_KEY, (_m, env) => `iv_${env}_${REDACTED}`)
+        .replace(WEBHOOK_SECRET, `whsec_${REDACTED}`)
+        .replace(AUTH_SCHEME, (_m, scheme) => `${scheme} ${REDACTED}`);
+}
+const SECRET_HEADERS = new Set([
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'ivora-signature',
+]);
+/** Returns a copy of the headers with credential headers replaced, for --debug output. */
+export function redactHeaders(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        out[name] = SECRET_HEADERS.has(name.toLowerCase()) ? REDACTED : redact(value);
+    }
+    return out;
+}
+const SECRET_FIELD = /password|secret|api_?key|authorization/i;
+/** Returns a deep copy of a JSON body with password, secret and key fields replaced. */
+export function redactBody(value) {
+    if (Array.isArray(value))
+        return value.map(redactBody);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            out[key] = SECRET_FIELD.test(key) ? REDACTED : redactBody(inner);
+        }
+        return out;
+    }
+    return typeof value === 'string' ? redact(value) : value;
+}
+/** A short, non-secret label for a key, e.g. `iv_test_ab12...`. */
+export function displayPrefix(apiKey) {
+    const match = /^(iv_(?:test|live)_)(.{0,4})/.exec(apiKey);
+    return match ? `${match[1]}${match[2]}...` : '(unrecognised key)';
+}
+/** In-memory store, used by tests and by `IVORA_API_KEY` sessions that persist nothing. */
+export class MemorySecretStore {
+    values = new Map();
+    async get(ref) {
+        return this.values.get(ref);
+    }
+    async set(ref, secret) {
+        this.values.set(ref, secret);
+    }
+    async delete(ref) {
+        return this.values.delete(ref);
+    }
+}
+const SERVICE = 'ivora-cli';
+const REF = /^[A-Za-z0-9:_-]{1,80}$/;
+const KEYCHAIN_SECRET = /^[A-Za-z0-9_-]{8,200}$/;
+export const defaultExec = (cmd, args, input) => new Promise((resolve) => {
+    const child = execFile(cmd, args, { encoding: 'utf8', timeout: 15_000 }, (err, stdout) => {
+        if (!err)
+            return resolve({ code: 0, stdout });
+        const e = err;
+        resolve({
+            code: typeof e.code === 'number' ? e.code : 1,
+            stdout: '',
+            missing: e.code === 'ENOENT',
+        });
+    });
+    child.stdin?.on('error', () => undefined);
+    child.stdin?.end(input ?? '');
+});
+/**
+ * OS keychain through its command-line tool. The secret travels on stdin only, so it does not
+ * show up in the process list. `get` returns undefined for a missing entry.
+ */
+export class KeychainSecretStore {
+    platform;
+    exec;
+    constructor(platform, exec = defaultExec) {
+        this.platform = platform;
+        this.exec = exec;
+    }
+    check(ref) {
+        if (!REF.test(ref))
+            throw new CliError('Invalid secret reference.', ExitCode.Usage);
+    }
+    async get(ref) {
+        this.check(ref);
+        const r = this.platform === 'darwin'
+            ? await this.exec('security', ['find-generic-password', '-s', SERVICE, '-a', ref, '-w'])
+            : await this.exec('secret-tool', ['lookup', 'service', SERVICE, 'account', ref]);
+        const value = r.stdout.replace(/\r?\n$/, '');
+        return r.code === 0 && value !== '' ? value : undefined;
+    }
+    async set(ref, secret) {
+        this.check(ref);
+        // Stricter than any real key, so the value is safe in the `security -i` command line.
+        if (!KEYCHAIN_SECRET.test(secret)) {
+            throw new CliError('The key has an unexpected format.', ExitCode.Usage);
+        }
+        const r = this.platform === 'darwin'
+            ? await this.exec('security', ['-i'], `add-generic-password -U -s ${SERVICE} -a ${ref} -w ${secret}\n`)
+            : await this.exec('secret-tool', ['store', '--label=Ivora CLI API key', 'service', SERVICE, 'account', ref], secret);
+        if (r.code !== 0) {
+            throw new CliError('Could not save the key in the OS keychain. Use the IVORA_API_KEY environment variable instead.', ExitCode.ApiError);
+        }
+    }
+    async delete(ref) {
+        this.check(ref);
+        const r = this.platform === 'darwin'
+            ? await this.exec('security', ['delete-generic-password', '-s', SERVICE, '-a', ref])
+            : await this.exec('secret-tool', ['clear', 'service', SERVICE, 'account', ref]);
+        return r.code === 0;
+    }
+}
+/** Used where no keychain exists: reads find nothing and writes explain the alternative. */
+export class UnavailableSecretStore {
+    async get() {
+        return undefined;
+    }
+    async set() {
+        throw new CliError('No OS keychain is available on this system, and the CLI never writes keys to disk in ' +
+            'plain text. Set the IVORA_API_KEY environment variable instead.', ExitCode.Usage);
+    }
+    async delete() {
+        return false;
+    }
+}
+/** The keychain store for this platform, or one that refuses writes. */
+export async function openSecretStore(platform = process.platform, exec = defaultExec) {
+    if (platform === 'darwin')
+        return new KeychainSecretStore('darwin', exec);
+    if (platform === 'linux') {
+        const probe = await exec('secret-tool', ['--version']);
+        if (!probe.missing)
+            return new KeychainSecretStore('linux', exec);
+    }
+    return new UnavailableSecretStore();
+}

package/dist/lib/session.js

@@ -0,0 +1,58 @@
+import { ApiClient } from './http.js';
+import { CliError, ExitCode, Output } from './output.js';
+import { assertKeyMatchesProfile, environmentForKey, loadConfig, resolveBaseUrl, selectProfileName, } from './profiles.js';
+/**
+ * Resolves the profile, key and API client for a command. The key comes from `IVORA_API_KEY`
+ * or the secret store. Live is an opt-in: a live profile or live key is used only with
+ * `--live` or `--profile <live profile>`.
+ */
+export async function openSession(ctx) {
+    const g = ctx.globals();
+    const config = await loadConfig(ctx.env);
+    const name = selectProfileName(g, config);
+    const stored = config.profiles[name];
+    const envKey = ctx.env.IVORA_API_KEY || undefined;
+    let profile;
+    let apiKey;
+    if (envKey !== undefined) {
+        const environment = environmentForKey(envKey);
+        if (environment === undefined) {
+            throw new CliError('IVORA_API_KEY does not look like an Ivora API key.', ExitCode.Usage);
+        }
+        // Naming a profile opts in to live only when that profile is stored as live. With no
+        // stored profile, a live key from the environment always needs --live.
+        if (!stored && environment === 'live' && !g.live) {
+            throw new CliError('IVORA_API_KEY holds a live key: pass --live to use it.', ExitCode.Usage);
+        }
+        profile = stored ?? { name, environment };
+        apiKey = envKey;
+    }
+    else {
+        if (!stored) {
+            throw new CliError(`No profile "${name}". Run \`ivora login${name === 'live' ? ' --live' : ''}\` first.`, ExitCode.Auth);
+        }
+        profile = stored;
+        const key = stored.keyRef ? await (await ctx.secrets()).get(stored.keyRef) : undefined;
+        if (key === undefined) {
+            throw new CliError(`No stored key for profile "${name}". Run \`ivora login\` again, or set IVORA_API_KEY.`, ExitCode.Auth);
+        }
+        apiKey = key;
+    }
+    assertKeyMatchesProfile(apiKey, profile);
+    if (g.live && profile.environment !== 'live') {
+        throw new CliError(`--live was given but profile "${profile.name}" is a test profile.`, ExitCode.Usage);
+    }
+    if (profile.environment === 'live' && !g.live && g.profile !== profile.name) {
+        throw new CliError('Live access is opt-in: pass --live (or --profile <name> for a live profile).', ExitCode.Usage);
+    }
+    const baseUrl = resolveBaseUrl(profile, ctx.env, (text) => ctx.out().info(`note: ${text}`));
+    const debug = g.debug ? (line) => ctx.out().info(line) : undefined;
+    const client = new ApiClient({
+        baseUrl,
+        apiKey,
+        apiVersion: g.apiVersion,
+        ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+        ...(debug ? { debug } : {}),
+    });
+    return { profile, apiKey, baseUrl, client };
+}

package/dist/version.js

@@ -0,0 +1,9 @@
+/** Version of this CLI. A test keeps it equal to package.json. */
+export const CLI_VERSION = '0.1.0';
+/** The dated /v1 API version this release pins, sent as `Ivora-Version`. */
+export const DEFAULT_API_VERSION = '2026-10-15';
+/** Dated /v1 API versions this release supports, oldest first (`--api-version`). */
+export const SUPPORTED_API_VERSIONS = [DEFAULT_API_VERSION];
+export function isSupportedApiVersion(value) {
+    return SUPPORTED_API_VERSIONS.includes(value);
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@ivora/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Command-line client for the public Ivora /v1 API",
+  "license": "Apache-2.0",
+  "author": "Ivora",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "ivora": "dist/bin/ivora.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ivora-Charge/ivora-cli.git"
+  },
+  "homepage": "https://github.com/Ivora-Charge/ivora-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Ivora-Charge/ivora-cli/issues"
+  },
+  "keywords": [
+    "ivora",
+    "ocpp",
+    "ev-charging",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node scripts/clean.mjs .test-build && tsc -p tsconfig.test.json && node --test --test-reporter=spec \".test-build/test/**/*.test.js\"",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "check:package": "node scripts/check-package.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/guard-publish.mjs"
+  },
+  "dependencies": {
+    "commander": "15.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.20.5",
+    "eslint": "10.12.0",
+    "globals": "17.13.0",
+    "prettier": "3.9.10",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.1"
+  }
+}