@eventra_dev/eventra-cli 1.0.2 → 1.0.4

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm version" src="https://img.shields.io/npm/v/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://github.com/and-1991/eventra-cli/actions/workflows/test.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/and-1991/eventra-cli/test.yml?branch=main&label=tests&style=flat-square&logo=vitest&logoColor=white"></a>
-  <img alt="unit tests" src="https://img.shields.io/badge/unit-59%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
+  <img alt="unit tests" src="https://img.shields.io/badge/unit-74%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
   <img alt="e2e fixtures" src="https://img.shields.io/badge/e2e-12%20fixtures-brightgreen?style=flat-square">
   <img alt="node" src="https://img.shields.io/node/v/@eventra_dev/eventra-cli?style=flat-square&color=darkgreen&logo=node.js&logoColor=white">
   <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-blue?style=flat-square&logo=typescript&logoColor=white"></a>
@@ -155,7 +155,23 @@ Incremental scan with the same rules as `sync`.
 
 ### `eventra send`
 
-Uploads `events` from config to the Eventra API. Requires `apiKey` (and optionally `endpoint`) in `eventra.json`. Events are POSTed to `POST /api/v1/cli/events` and marked as non-billable on the backend.
+Uploads `events` from config to the Eventra API. Requires an API key and (optionally) an `endpoint`. Events are POSTed to `POST /api/v1/cli/events` and marked as non-billable on the backend.
+
+**API key resolution** (checked in this order, never written to `eventra.json`):
+
+1. `EVENTRA_API_KEY` environment variable — recommended for CI
+2. `eventra.local.json` (created by `eventra init`/`eventra send`, automatically gitignored)
+3. legacy inline `apiKey` in `eventra.json` (deprecated — avoid committing real keys here)
+
+`eventra.json` is meant to be committed so CI can diff it via `eventra check`; keeping the key out of it avoids leaking it into source control. In a non-interactive shell (no TTY), `send` fails fast with a message pointing at `EVENTRA_API_KEY` instead of hanging on a prompt.
+
+**Endpoint trust.** The default production endpoint is always used with no extra step. A *custom* `endpoint` is only trusted without approval when it comes from the `EVENTRA_ENDPOINT` environment variable (setting an env var is already a local/CI action). A custom `endpoint` committed inline in `eventra.json` is trust-on-first-use: `send` refuses to run until it's approved once with:
+
+```bash
+eventra send --trust-endpoint
+```
+
+This records the endpoint in `eventra.local.json` (gitignored). If `eventra.json`'s `endpoint` later changes to a different value — e.g. a PR silently pointing it at another host — `send` blocks again until re-approved, so a committed config change alone can't redirect where your API key and events get sent.
 
 Network resilience:
 
@@ -224,6 +240,8 @@ External plugins export an object (or factory) with:
 
 No dependency on `@eventra_dev/eventra-cli` is required. See [`ARCHITECTURE.md`](./ARCHITECTURE.md#plugin-kernel-phase-15--foundation-shipped) for details.
 
+**Only official `@eventra_dev/cli-plugin-*` packages can be loaded.** `eventra.json` is meant to be committed to git, so its `plugins` array is effectively PR-editable; since the CLI `import()`s whatever is listed there, an arbitrary specifier would be arbitrary code execution on every machine that runs `sync`/`check`/`watch`. Because `@eventra_dev` is an npm scope only the Eventra maintainers can publish to, restricting to `@eventra_dev/cli-plugin-*` means nothing outside that scope can ever be loaded this way. Any other entry in `plugins` is skipped with a console warning instead of being imported — third-party/community plugins aren't supported today.
+
 ---
 
 ## Configuration
@@ -244,10 +262,14 @@ No dependency on `@eventra_dev/eventra-cli` is required. See [`ARCHITECTURE.md`]
 
 | Field | Description |
 |-------|-------------|
-| `plugins` | Module specifiers to `import()` at startup (e.g. `@eventra_dev/cli-plugin-vue`) |
+| `apiKey` | Legacy inline API key — leave empty. Use `EVENTRA_API_KEY` or `eventra.local.json` instead (see [`eventra send`](#eventra-send)) so a real key never ends up in this committed file |
+| `endpoint` | Custom `eventra send` target (e.g. self-hosted). Non-default values from this file need one-time local approval — see [`eventra send`](#eventra-send) |
+| `plugins` | `@eventra_dev/cli-plugin-*` specifiers to `import()` at startup. Anything outside that scope is skipped (see [Plugin contract](#plugin-contract-for-authors)) |
 | `sync.include` | Base glob patterns; plugin `includeGlobs` are merged automatically |
 | `sync.exclude` | Paths skipped during scan |
 
+`eventra init`/`eventra send` never write a real key into this file — they write to `eventra.local.json` instead, which is automatically added to `.gitignore`.
+
 ---
 
 ## How it works
@@ -275,7 +297,7 @@ No runtime execution. No monkey-patching.
 
 ## Test Coverage
 
-Two test layers, **59 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios**.
+Two test layers, **74 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios**.
 
 **Unit tests (vitest)** — 13 suites covering core modules:
 
@@ -322,6 +344,8 @@ pnpm --filter @eventra_dev/eventra-cli test:unit  # vitest only
 pnpm --filter @eventra_dev/eventra-cli test:e2e   # fixtures + check exit codes
 ```
 
+> **Node version note:** the CLI itself supports Node 18+ (see `engines`), but `vitest@4` depends on `node:util`'s `styleText`, which requires Node **≥ 20.12** — running the test suite on an older Node 20.x patch (or Node 18) fails to start. CI runs the matrix on Node 20 and 22; locally, use the version pinned in the repo's `.nvmrc`.
+
 ---
 
 ## License

package/dist/cli/init.js

@@ -29,7 +29,7 @@ async function init() {
     console.log(chalk_1.default.gray("• cross-file propagation chains"));
     console.log("");
     const config = {
-        apiKey,
+        apiKey: "",
         endpoint,
         events: [],
         functionWrappers: [],
@@ -47,6 +47,12 @@ async function init() {
     };
     await (0, config_1.saveConfig)(config);
     console.log(chalk_1.default.green("eventra.json created"));
+    // Never write the key into eventra.json — that file is meant to be
+    // committed (CI diffs it via `eventra check`). Keep secrets out of git.
+    if (apiKey) {
+        await (0, config_1.saveLocalApiKey)(apiKey);
+        console.log(chalk_1.default.green("API key saved to eventra.local.json (added to .gitignore)"));
+    }
     console.log("");
     console.log(chalk_1.default.gray("Run `eventra sync`"));
 }

package/dist/cli/send.js

@@ -9,6 +9,8 @@ const inquirer_1 = __importDefault(require("inquirer"));
 const config_1 = require("../config/config");
 const package_json_1 = __importDefault(require("../../package.json"));
 const CLI_VERSION = package_json_1.default.version;
+// Always trusted, no local approval needed — matches `eventra init`'s prompt default.
+const DEFAULT_SEND_ENDPOINT = "https://api.eventra.dev/api/v1/cli/events";
 // retry/backoff tuning (mirrors SDK defaults)
 const MAX_ATTEMPTS = 4;
 const BASE_DELAY_MS = 500;
@@ -56,16 +58,40 @@ async function attemptDelivery(endpoint, apiKey, payload) {
         clearTimeout(timeout);
     }
 }
-async function send() {
+async function send(opts = {}) {
     const config = await (0, config_1.loadConfig)();
-    const endpoint = config?.endpoint || process.env.EVENTRA_ENDPOINT;
     if (!config) {
         console.log(chalk_1.default.red("eventra.json not found. Run 'eventra init'"));
         return;
     }
-    let apiKey = config.apiKey;
-    // ask api key
+    const endpoint = config.endpoint || process.env.EVENTRA_ENDPOINT || undefined;
+    // A non-default endpoint sourced from the committed eventra.json (not from
+    // EVENTRA_ENDPOINT, which already requires a local/CI env-var change) needs
+    // one-time local approval — otherwise a PR silently editing `endpoint` could
+    // redirect send (and the API key) to an attacker's server.
+    if (endpoint &&
+        endpoint !== DEFAULT_SEND_ENDPOINT &&
+        endpoint === config.endpoint &&
+        !process.env.EVENTRA_ENDPOINT) {
+        const trusted = await (0, config_1.getTrustedEndpoint)();
+        if (endpoint !== trusted) {
+            if (!opts.trustEndpoint) {
+                console.log(chalk_1.default.red(`Endpoint "${endpoint}" from eventra.json is not locally approved.`));
+                console.log(chalk_1.default.gray("If this is expected (e.g. a self-hosted ingest URL), approve it once with:"));
+                console.log(chalk_1.default.gray("  eventra send --trust-endpoint"));
+                return;
+            }
+            await (0, config_1.trustEndpoint)(endpoint);
+            console.log(chalk_1.default.green(`Endpoint "${endpoint}" approved and saved to eventra.local.json`));
+        }
+    }
+    let apiKey = await (0, config_1.resolveApiKey)(config);
+    // ask for the key only when interactive — never hang a CI/non-TTY run on a prompt
     if (!apiKey) {
+        if (!process.stdin.isTTY) {
+            console.log(chalk_1.default.red("API key required. Set the EVENTRA_API_KEY environment variable (recommended for CI) or run 'eventra init'."));
+            return;
+        }
         const answers = await inquirer_1.default.prompt([
             {
                 type: "input",
@@ -74,11 +100,12 @@ async function send() {
             }
         ]);
         apiKey = answers.apiKey;
-        await (0, config_1.saveConfig)({
-            ...config,
-            apiKey,
-        });
-        console.log(chalk_1.default.green("API key saved"));
+        if (apiKey) {
+            // Saved to the gitignored local secrets file, never to eventra.json —
+            // that file is meant to be committed for `eventra check` drift detection.
+            await (0, config_1.saveLocalApiKey)(apiKey);
+            console.log(chalk_1.default.green("API key saved to eventra.local.json (added to .gitignore)"));
+        }
     }
     // no events
     if (!config.events?.length) {

package/dist/config/config.js

@@ -3,13 +3,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONFIG_NAME = void 0;
+exports.LOCAL_CONFIG_NAME = exports.CONFIG_NAME = void 0;
 exports.normalizeConfig = normalizeConfig;
 exports.loadConfig = loadConfig;
 exports.saveConfig = saveConfig;
+exports.resolveApiKey = resolveApiKey;
+exports.saveLocalApiKey = saveLocalApiKey;
+exports.getTrustedEndpoint = getTrustedEndpoint;
+exports.trustEndpoint = trustEndpoint;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 exports.CONFIG_NAME = "eventra.json";
+/**
+ * Secrets live here instead of `eventra.json`, since the latter is meant to be
+ * committed (CI diffs `events`/`functionWrappers` against it via `eventra check`).
+ */
+exports.LOCAL_CONFIG_NAME = "eventra.local.json";
 const DEFAULT_INCLUDE = ["**/*.{ts,tsx,js,jsx}"];
 const DEFAULT_EXCLUDE = ["node_modules", "dist", ".next", ".git"];
 function normalizeConfig(config) {
@@ -52,3 +61,74 @@ async function saveConfig(config) {
     const configPath = path_1.default.join(process.cwd(), exports.CONFIG_NAME);
     await fs_extra_1.default.writeJSON(configPath, normalizeConfig(config), { spaces: 2 });
 }
+async function readLocalSecrets() {
+    const localPath = path_1.default.join(process.cwd(), exports.LOCAL_CONFIG_NAME);
+    if (!(await fs_extra_1.default.pathExists(localPath)))
+        return {};
+    try {
+        const parsed = await fs_extra_1.default.readJSON(localPath);
+        return {
+            apiKey: typeof parsed?.apiKey === "string" && parsed.apiKey ? parsed.apiKey : undefined,
+            trustedEndpoint: typeof parsed?.trustedEndpoint === "string" && parsed.trustedEndpoint
+                ? parsed.trustedEndpoint
+                : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function writeLocalSecrets(patch) {
+    const localPath = path_1.default.join(process.cwd(), exports.LOCAL_CONFIG_NAME);
+    const next = { ...(await readLocalSecrets()), ...patch };
+    const out = {};
+    if (next.apiKey)
+        out.apiKey = next.apiKey;
+    if (next.trustedEndpoint)
+        out.trustedEndpoint = next.trustedEndpoint;
+    await fs_extra_1.default.writeJSON(localPath, out, { spaces: 2 });
+    await ensureGitignored(exports.LOCAL_CONFIG_NAME);
+}
+async function ensureGitignored(entry) {
+    const gitignorePath = path_1.default.join(process.cwd(), ".gitignore");
+    let content = "";
+    if (await fs_extra_1.default.pathExists(gitignorePath)) {
+        content = await fs_extra_1.default.readFile(gitignorePath, "utf8");
+        if (content.split(/\r?\n/).some((line) => line.trim() === entry))
+            return;
+    }
+    const needsLeadingNewline = content.length > 0 && !content.endsWith("\n");
+    await fs_extra_1.default.appendFile(gitignorePath, `${needsLeadingNewline ? "\n" : ""}${entry}\n`);
+}
+/**
+ * Resolves the API key for outbound requests only — never persisted back onto
+ * the `EventraConfig` object, so it can't leak into `eventra.json` via `saveConfig`.
+ * Priority: `EVENTRA_API_KEY` env var > `eventra.local.json` (gitignored) >
+ * legacy inline `apiKey` in `eventra.json` (kept for backward compatibility only).
+ */
+async function resolveApiKey(config) {
+    if (process.env.EVENTRA_API_KEY)
+        return process.env.EVENTRA_API_KEY;
+    const { apiKey } = await readLocalSecrets();
+    if (apiKey)
+        return apiKey;
+    return config.apiKey || undefined;
+}
+/** Persists an API key to the gitignored local secrets file, never to `eventra.json`. */
+async function saveLocalApiKey(apiKey) {
+    await writeLocalSecrets({ apiKey });
+}
+/**
+ * The `endpoint` a locally-run `eventra send` last approved, trust-on-first-use
+ * style — a non-default `endpoint` sourced from the *committed* `eventra.json`
+ * must match this before it's used, so a PR silently changing it can't redirect
+ * `send` (and the API key with it) without a human approving it locally once.
+ */
+async function getTrustedEndpoint() {
+    const { trustedEndpoint } = await readLocalSecrets();
+    return trustedEndpoint;
+}
+/** Records `endpoint` as locally approved (see `getTrustedEndpoint`). */
+async function trustEndpoint(endpoint) {
+    await writeLocalSecrets({ trustedEndpoint: endpoint });
+}

package/dist/index.js

@@ -72,8 +72,9 @@ program
 });
 program
     .command("send")
-    .action(async () => {
+    .option("--trust-endpoint", "approve the current eventra.json endpoint for local use")
+    .action(async (opts) => {
     const { send } = await Promise.resolve().then(() => __importStar(require("./cli/send")));
-    await send();
+    await send({ trustEndpoint: opts.trustEndpoint });
 });
 program.parse();

package/dist/plugin/loadPlugins.js

@@ -33,11 +33,24 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTrustedPluginSpecifier = isTrustedPluginSpecifier;
 exports.createBuiltinPluginRegistry = createBuiltinPluginRegistry;
 exports.createPluginRegistry = createPluginRegistry;
 const external_1 = require("./adapters/external");
 const eventra_sdk_1 = require("./builtins/eventra-sdk");
 const registry_1 = require("./registry");
+/**
+ * Only packages published under the `@eventra_dev` npm scope can ever be
+ * `import()`-ed as a plugin. `eventra.json` (and its `plugins` array) is meant
+ * to be committed to git, so anything else listed there is attacker-editable
+ * via a plain PR — restricting to a scope only the maintainers can publish to
+ * turns "arbitrary code execution via a one-line JSON edit" into "not possible
+ * without also compromising the @eventra_dev npm account."
+ */
+const TRUSTED_PLUGIN_RE = /^@eventra_dev\/cli-plugin-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isTrustedPluginSpecifier(spec) {
+    return TRUSTED_PLUGIN_RE.test(spec);
+}
 async function resolvePluginExport(mod) {
     let candidate = mod.default ?? mod;
     if (typeof candidate === "function") {
@@ -82,7 +95,14 @@ function createBuiltinPluginRegistry() {
 async function createPluginRegistry(config) {
     const registry = createBuiltinPluginRegistry();
     for (const spec of config.plugins ?? []) {
-        await loadExternalPlugin(registry, spec);
+        const trimmed = spec.trim();
+        if (!trimmed)
+            continue;
+        if (!isTrustedPluginSpecifier(trimmed)) {
+            console.warn(`Eventra: skipping plugin "${trimmed}" — only official @eventra_dev/cli-plugin-* packages can be loaded.${pluginLoadHint(trimmed)}`);
+            continue;
+        }
+        await loadExternalPlugin(registry, trimmed);
     }
     return registry;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventra_dev/eventra-cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Static analytics event extraction CLI powered by the TypeScript compiler API",
   "license": "MIT",
   "type": "commonjs",