@qerexa/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qerexa Inc.
+
+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

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# Qerexa CLI (preview)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Put a Qerexa check in front of your CI jobs, and manage short-lived secrets
+from the terminal.
+
+`qerexa-cli gate` exits 0 only when Qerexa gives a clear, current yes: an
+`allowed` decision with its own ID and an expiry still in the future. Every
+other outcome exits non-zero, so the pipeline step that depends on it simply
+doesn't run. When a human review is needed, `--no-wait` exits with code 2 right
+away instead of polling.
+
+An approved review still exits non-zero. Approving a review isn't permission
+to deploy or move money, so feed that decision into your own action-bound
+execution step rather than treating it as a green light.
+
+This is a preview, not a certified execution control. Redirects are never
+followed, so your API key stays with the API host you configure.
+
+## Install
+
+```bash
+npm install -g @qerexa/cli      # or: npx @qerexa/cli help
+qerexa-cli help
+```
+
+From this repository:
+
+```bash
+node packages/cli/index.mjs help
+```
+
+## Config
+
+The CLI reads `~/.qerexarc` (or legacy `~/.trustrc`) JSON:
+
+```json
+{ "apiKey": "qrx_api_...", "baseUrl": "https://api.qerexa.com" }
+```
+
+The base URL defaults to `https://api.qerexa.com`. For local development pass
+`--base-url http://localhost:3000` or set `QEREXA_BASE_URL`.
+
+Environment overrides:
+
+- `QEREXA_API_KEY`
+- `QEREXA_BASE_URL`
+- Legacy: `TRUST_API_KEY`, `TRUST_BASE_URL`
+
+## Commands
+
+- `qerexa-cli create [--ttl <seconds>] [--stdin|--text <value>]`
+- `qerexa-cli read <id>`
+- `qerexa-cli burn <id>`
+- `qerexa-cli gate --action deploy.production --file .github/workflows/deploy.yml --source cicd --provider github`
+
+The `gate` command submits the supplied file as intent. Inspect it for embedded
+secrets before use. It polls a durable review flow, but even an approved flow
+does not yield a successful gate result.
+
+Each `gate` call sends an `Idempotency-Key`. In GitHub Actions or GitLab CI the
+key is derived from the run ID, the run attempt (or job ID), and a hash of the
+request, so retries of the same gate deduplicate while other gates in the run,
+and re-run attempts, are evaluated afresh. Outside CI a random key is used. Set
+`QEREXA_REQUEST_ID` to override it; use a value unique to each gate request.
+
+Output is JSON.

package/index.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+
+const HELP = `qerexa-cli <command>
+
+Commands:
+  create [--ttl <seconds>] [--stdin]        Create a secret (reads plaintext from --stdin or --text)
+  read <id>                                  Read a secret by id
+  burn <id>                                  Burn a secret by id
+  gate --action <action> [--file <yaml>]     Evaluate; review approval requires separate execution authorization
+
+Options:
+  --base-url <url>   Override API base URL (default https://api.qerexa.com or config)
+  --text <value>     Plaintext for create when --stdin is not used
+  --source <type>    canonical, kubernetes, cicd, or llm_tool_call
+  --provider <name>  CI provider hint (github, gitlab, jenkins, generic)
+  --actor <name>     Machine actor identity (default ci-runner)
+  --reason <text>    Human-readable reason for the action
+  --no-wait          Return immediately when human approval is required
+  --approval-timeout <seconds>  Overall wait limit (default 1800)
+
+Config:
+  Reads ~/.qerexarc (or legacy ~/.trustrc) JSON { "apiKey": "qrx_api_...", "baseUrl": "https://api.qerexa.com" }
+  Env overrides: QEREXA_API_KEY, QEREXA_BASE_URL (legacy: TRUST_API_KEY, TRUST_BASE_URL)
+`;
+
+function loadConfig() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const primaryPath = path.join(home, ".qerexarc");
+  const legacyPath = path.join(home, ".trustrc");
+  for (const configPath of [primaryPath, legacyPath]) {
+    if (fs.existsSync(configPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(configPath, "utf8"));
+      } catch {
+        // fall through
+      }
+    }
+  }
+  return {};
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const args = { command, positional: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (token === "--ttl") {
+      args.ttl = Number(rest[++i]);
+    } else if (token === "--stdin") {
+      args.stdin = true;
+    } else if (token === "--base-url") {
+      args.baseUrl = rest[++i];
+    } else if (token === "--text") {
+      args.text = rest[++i];
+    } else if (token === "--action") {
+      args.action = rest[++i];
+    } else if (token === "--file") {
+      args.file = rest[++i];
+    } else if (token === "--source") {
+      args.source = rest[++i];
+    } else if (token === "--provider") {
+      args.provider = rest[++i];
+    } else if (token === "--actor") {
+      args.actor = rest[++i];
+    } else if (token === "--reason") {
+      args.reason = rest[++i];
+    } else if (token === "--approval-timeout") {
+      args.approvalTimeout = Number(rest[++i]);
+    } else if (token === "--no-wait") {
+      args.noWait = true;
+    } else if (!token.startsWith("--")) {
+      args.positional.push(token);
+    }
+  }
+  return args;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function resilientFetch(url, init, attempts = 3) {
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      // The API never redirects. Following one would send X-API-Key to another
+      // host (fetch drops only Authorization), and a 3xx is never an allow.
+      const response = await fetch(url, {
+        ...init,
+        redirect: "manual",
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (response.status !== 429 && response.status < 500) return response;
+      if (attempt === attempts - 1) return response;
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts - 1) throw error;
+    }
+    await delay(Math.min(1000, 200 * 2 ** attempt));
+  }
+  throw lastError ?? new Error("Qerexa request failed");
+}
+
+// One key per distinct request: retries of the same gate dedupe, while other
+// gates in the same CI run (and re-run attempts) are evaluated afresh.
+function gateIdempotencyKey(payload) {
+  if (process.env.QEREXA_REQUEST_ID) return process.env.QEREXA_REQUEST_ID;
+  const runId = process.env.GITHUB_RUN_ID || process.env.CI_PIPELINE_ID;
+  if (!runId) return randomUUID();
+  const attempt = process.env.GITHUB_RUN_ATTEMPT || process.env.CI_JOB_ID || "1";
+  const digest = createHash("sha256").update(JSON.stringify(payload)).digest("hex").slice(0, 32);
+  return `ci-${runId}-${attempt}-${digest}`;
+}
+
+async function gateAction(args, apiKey, baseUrl) {
+  if (!args.action) throw new Error("gate requires --action <action>");
+  const payload = {
+    action: args.action,
+    actor: args.actor || process.env.CI_JOB_NAME || process.env.GITHUB_JOB || "ci-runner",
+    reasoning: args.reason || `CI gate for ${args.action}`,
+    metadata: {
+      run_id:
+        process.env.GITHUB_RUN_ID || process.env.CI_PIPELINE_ID || process.env.BUILD_NUMBER || null,
+      repository: process.env.GITHUB_REPOSITORY || process.env.CI_PROJECT_PATH || null,
+      ref: process.env.GITHUB_REF || process.env.CI_COMMIT_REF_NAME || null,
+    },
+  };
+  if (args.file) {
+    payload.intent = {
+      source: args.source || "cicd",
+      provider: args.provider || "generic",
+      payload: fs.readFileSync(args.file, "utf8"),
+    };
+  }
+
+  const response = await resilientFetch(`${baseUrl}/api/v1/gates/evaluate`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "X-API-Key": apiKey,
+      "Content-Type": "application/json",
+      "Idempotency-Key": gateIdempotencyKey(payload),
+    },
+    body: JSON.stringify(payload),
+  });
+  const result = await response.json().catch(() => ({}));
+  const expiresAt = Date.parse(result.expires_at || "");
+  if (response.status === 200 && result.decision === "allowed" && result.allowed === true
+      && typeof result.decision_id === "string" && result.decision_id
+      && Number.isFinite(expiresAt) && expiresAt > Date.now()) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (response.status !== 202 || result.decision !== "approval_required"
+      || result.allowed !== false || typeof result.flow_id !== "string" || !result.flow_id) {
+    throw new Error(
+      `Qerexa blocked ${args.action}: ${result.reason || result.error || response.status}`
+    );
+  }
+  console.error(`Qerexa approval required. Flow: ${result.flow_id}`);
+  if (args.noWait) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exitCode = 2;
+    return;
+  }
+
+  const configuredTimeout = Number.isFinite(args.approvalTimeout)
+    ? args.approvalTimeout * 1000
+    : 1_800_000;
+  const serverDeadline = Date.parse(result.review_deadline || "");
+  const deadline = Number.isFinite(serverDeadline)
+    ? Math.min(Date.now() + configuredTimeout, serverDeadline)
+    : Date.now() + configuredTimeout;
+  while (Date.now() < deadline) {
+    const statusResponse = await resilientFetch(
+      `${baseUrl}/api/v1/trust-flows/${encodeURIComponent(result.flow_id)}`,
+      { headers: { Authorization: `Bearer ${apiKey}`, "X-API-Key": apiKey } }
+    );
+    if (!statusResponse.ok) throw new Error(`Qerexa flow status failed: ${statusResponse.status}`);
+    const flow = await statusResponse.json().catch(() => ({}));
+    for (const field of ["expires_at", "time_window_end"]) {
+      if (flow[field] !== undefined) {
+        const expiry = Date.parse(flow[field]);
+        if (!Number.isFinite(expiry) || expiry <= Date.now()) {
+          throw new Error(`Qerexa flow ${result.flow_id} has invalid or expired ${field}`);
+        }
+      }
+    }
+    if (flow.time_window_start !== undefined) {
+      const start = Date.parse(flow.time_window_start);
+      if (!Number.isFinite(start) || start > Date.now()) {
+        throw new Error(`Qerexa flow ${result.flow_id} execution window is not open`);
+      }
+    }
+    const status = String(flow.status || "").toLowerCase();
+    if (status === "approved") {
+      throw new Error(`Qerexa review flow ${result.flow_id} was approved, but separate action-bound execution authorization is required`);
+    }
+    if (status === "completed") {
+      throw new Error(`Qerexa flow ${result.flow_id} is already completed; do not execute again`);
+    }
+    if (["rejected", "denied", "blocked", "expired", "revoked"].includes(status)) {
+      throw new Error(`Qerexa flow ${result.flow_id} ended with status ${status}`);
+    }
+    await delay(Math.min(2000, Math.max(0, deadline - Date.now())));
+  }
+  throw new Error(`Qerexa approval timed out for flow ${result.flow_id}`);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function trFetch(pathname, method, apiKey, body, baseUrl) {
+  const res = await fetch(`${baseUrl}${pathname}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${method} ${pathname} failed ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+async function main() {
+  const cfg = loadConfig();
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.command || args.command === "help" || args.command === "--help") {
+    console.log(HELP);
+    return;
+  }
+
+  const apiKey = process.env.QEREXA_API_KEY || process.env.TRUST_API_KEY || cfg.apiKey;
+  const baseUrl =
+    args.baseUrl ||
+    process.env.QEREXA_BASE_URL ||
+    process.env.TRUST_BASE_URL ||
+    cfg.baseUrl ||
+    "https://api.qerexa.com";
+  if (!apiKey) {
+    console.error('API key missing. Set QEREXA_API_KEY or ~/.qerexarc { "apiKey": "..." }');
+    process.exit(1);
+  }
+
+  if (args.command === "gate") {
+    await gateAction(args, apiKey, baseUrl.replace(/\/$/, ""));
+    return;
+  }
+
+  if (args.command === "create") {
+    const ttl = Number.isFinite(args.ttl) ? args.ttl : undefined;
+    let plaintext = args.text;
+    if (args.stdin) {
+      plaintext = await readStdin();
+    }
+    if (!plaintext) {
+      console.error("Provide plaintext via --text or --stdin");
+      process.exit(1);
+    }
+    const body = { plaintext, one_time: false };
+    if (ttl) body.ttl_seconds = ttl;
+    const res = await trFetch("/api/v1/secrets", "POST", apiKey, body, baseUrl);
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+
+  if (args.command === "read") {
+    const id = args.positional[0];
+    if (!id) {
+      console.error("Usage: qerexa-cli read <id>");
+      process.exit(1);
+    }
+    const res = await trFetch(`/api/v1/secret/${id}`, "GET", apiKey, undefined, baseUrl);
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+
+  if (args.command === "burn") {
+    const id = args.positional[0];
+    if (!id) {
+      console.error("Usage: qerexa-cli burn <id>");
+      process.exit(1);
+    }
+    const res = await trFetch(`/api/v1/secret/${id}/burn`, "POST", apiKey, undefined, baseUrl);
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+
+  console.error("Unknown command\n");
+  console.log(HELP);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@qerexa/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Preview CLI for Qerexa execution gates and secret workflows.",
+  "type": "module",
+  "bin": {
+    "qerexa-cli": "index.mjs",
+    "trust-cli": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test index.test.mjs"
+  },
+  "keywords": [
+    "qerexa",
+    "trust-rails",
+    "secrets",
+    "cli"
+  ],
+  "author": "Qerexa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rodriguew/Trust-Rails.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://qerexa.com",
+  "bugs": {
+    "url": "https://github.com/rodriguew/Trust-Rails/issues"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}