@seekrit/cli 0.30.0 → 0.31.0

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { z } from "zod";
 import { Command } from "commander";
 import { homedir, hostname, tmpdir, userInfo } from "node:os";
 import { dirname, join, parse } from "node:path";
 import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
+import { createHash } from "node:crypto";
 /** All catalog keys as a runtime array (for iteration / zod enums). */
 const ENTITLEMENT_KEYS = Object.keys({
 	"feature.kms": {
@@ -2719,7 +2720,7 @@ function isCliSessionToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.30.0";
+var version = "0.31.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -3406,7 +3407,8 @@ function tryBuildContext(dotenvVars = {}) {
 			auth,
 			client: CLI_CLIENT
 		}),
-		auth
+		auth,
+		apiUrl
 	};
 }
 function buildContext() {
@@ -4812,6 +4814,163 @@ function registerBranchCommands(program) {
 		console.error(`deleted branch ${app.slug}#${target.slug}`);
 	});
 }
+/** Domain separators — must match `crates/seekrit-cache`. */
+const KEY_DOMAIN = "seekrit-lkg-cache-v1";
+const TOKEN_DOMAIN = "seekrit-token-fp-v1";
+/** 24h: long enough to ride out an outage, short enough to bound the tail. */
+const DEFAULT_MAX_AGE_MS = 1440 * 60 * 1e3;
+/**
+* Derive the key for one resolve request. Overrides are sorted, so flag order
+* never splits the cache. Byte-for-byte identical to `CacheKey::new` in
+* `crates/seekrit-cache`.
+*/
+function cacheKey(apiUrl, token, branch, overrides = {}) {
+	const pairs = Object.entries(overrides).map(([group, env]) => `${group}:${env}`).sort();
+	return {
+		key: createHash("sha256").update([
+			KEY_DOMAIN,
+			apiUrl.replace(/\/+$/, ""),
+			token,
+			branch ?? "",
+			pairs.join(",")
+		].join("\n")).digest("hex"),
+		tokenFingerprint: tokenFingerprint(token)
+	};
+}
+/** The hex SHA-256 identifying a token without storing it. */
+function tokenFingerprint(token) {
+	return createHash("sha256").update(`${TOKEN_DOMAIN}\n${token}`).digest("hex");
+}
+/**
+* `$XDG_CACHE_HOME/seekrit`, else `~/.cache/seekrit` — beside the config
+* directory holding the credential, never a shared temp directory.
+*/
+function defaultCacheDir() {
+	return join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "seekrit");
+}
+/** Render an age for a log line, rounded to its largest whole unit. */
+function humanize(ms) {
+	const secs = Math.floor(ms / 1e3);
+	if (secs < 60) return `${secs}s`;
+	if (secs < 3600) return `${Math.floor(secs / 60)}m`;
+	if (secs < 86400) return `${Math.floor(secs / 3600)}h`;
+	return `${Math.floor(secs / 86400)}d`;
+}
+/**
+* Whether a failed resolve means the API was *unreachable* (the cache may stand
+* in) rather than *refusing us* (it must not). A refusal is an answer, and
+* revocation is supposed to take effect the moment it arrives.
+*/
+function mayFallBack(err) {
+	if (err instanceof SeekritApiError) return err.status >= 500 || err.status === 429;
+	return true;
+}
+/** An opened cache, bound to one resolve request. */
+var LkgCache = class {
+	dir;
+	maxAgeMs;
+	id;
+	constructor(id, options = {}) {
+		this.id = id;
+		this.dir = options.dir ?? defaultCacheDir();
+		this.maxAgeMs = options.maxAgeMs ?? 864e5;
+	}
+	path() {
+		return join(this.dir, `${this.id.key}.json`);
+	}
+	read() {
+		const path = this.path();
+		if (!existsSync(path)) return { kind: "missing" };
+		let envelope;
+		try {
+			envelope = JSON.parse(readFileSync(path, "utf8"));
+		} catch (err) {
+			return {
+				kind: "unusable",
+				reason: `corrupt cache entry: ${message(err)}`
+			};
+		}
+		if (envelope.version !== 1) return {
+			kind: "unusable",
+			reason: `cache entry is format v${envelope.version}, this build reads v1`
+		};
+		if (envelope.tokenFingerprint !== this.id.tokenFingerprint) return {
+			kind: "unusable",
+			reason: "cache entry belongs to a different token"
+		};
+		if (typeof envelope.body !== "string") return {
+			kind: "unusable",
+			reason: "cache entry has no body"
+		};
+		const ageMs = Math.max(0, Date.now() - envelope.fetchedAt * 1e3);
+		if (ageMs >= this.maxAgeMs) return {
+			kind: "expired",
+			ageMs
+		};
+		return {
+			kind: "hit",
+			body: envelope.body,
+			ageMs
+		};
+	}
+	/**
+	* Record a freshly-fetched response. Written to a temporary file and renamed,
+	* so a concurrent reader sees either the old entry or the new one — never a
+	* half-written file. Throws only on genuinely unexpected I/O; callers treat a
+	* failed write as a warning, never as a failed resolve.
+	*/
+	write(body) {
+		mkdirSync(this.dir, {
+			recursive: true,
+			mode: 448
+		});
+		const envelope = {
+			version: 1,
+			fetchedAt: Math.floor(Date.now() / 1e3),
+			tokenFingerprint: this.id.tokenFingerprint,
+			body
+		};
+		const tmp = join(this.dir, `${this.id.key}.${process.pid}.tmp`);
+		try {
+			writeFileSync(tmp, JSON.stringify(envelope), { mode: 384 });
+			renameSync(tmp, this.path());
+		} catch (err) {
+			rmSync(tmp, { force: true });
+			throw err;
+		}
+		this.pruneExpired();
+	}
+	/** Drop this entry — used when the API refuses the token. */
+	invalidate() {
+		rmSync(this.path(), { force: true });
+	}
+	/**
+	* Delete entries past their usefulness (a rotated token or a changed
+	* `--with` leaves one nothing will read again). Best-effort and silent, and
+	* it only ever touches files this cache named: `<64 hex>.json`.
+	*/
+	pruneExpired() {
+		let names;
+		try {
+			names = readdirSync(this.dir);
+		} catch {
+			return;
+		}
+		for (const name of names) {
+			if (!/^[0-9a-f]{64}\.json$/.test(name)) continue;
+			const path = join(this.dir, name);
+			let expired = true;
+			try {
+				const envelope = JSON.parse(readFileSync(path, "utf8"));
+				expired = Math.max(0, Date.now() - envelope.fetchedAt * 1e3) >= this.maxAgeMs;
+			} catch {}
+			if (expired) rmSync(path, { force: true });
+		}
+	}
+};
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
 //#endregion
 //#region src/format.ts
 function shellQuote(value) {
@@ -6070,7 +6229,7 @@ async function materializeEnv(ctx, opts) {
 		if (!opts.envId) fail("specify --app and --env, or authenticate with a service token (SEEKRIT_TOKEN)");
 		query.env = opts.envId;
 	}
-	const { scope, layers } = await ctx.client.resolve(query);
+	const { scope, layers } = await resolveWithCache(ctx, query, opts.cache);
 	const privateKey = await getPrivateKey(ctx);
 	const values = {};
 	const provenance = {};
@@ -6094,6 +6253,46 @@ async function materializeEnv(ctx, opts) {
 	};
 }
 /**
+* Resolve, going through the last-known-good cache when one is configured.
+*
+* Always live first: the cache exists for when the call cannot land, not to
+* save a round trip, so a recovered network is picked up on the very next
+* invocation. A *refused* resolve (401/403/…) drops the entry rather than
+* falling back to it — otherwise revoking a token would keep working offline
+* until the entry aged out.
+*/
+async function resolveWithCache(ctx, query, cache) {
+	if (!cache) return ctx.client.resolve(query);
+	try {
+		const response = await ctx.client.resolve(query);
+		try {
+			cache.write(JSON.stringify(response));
+		} catch (err) {
+			warn(`could not update the cache: ${errorMessage(err)}`);
+		}
+		return response;
+	} catch (err) {
+		if (!mayFallBack(err)) {
+			cache.invalidate();
+			throw err;
+		}
+		const found = cache.read();
+		if (found.kind === "hit") {
+			warn(`${errorMessage(err)} — using cached secrets fetched ${humanize(found.ageMs)} ago`);
+			return JSON.parse(found.body);
+		}
+		if (found.kind === "expired") warn(`cached secrets are ${humanize(found.ageMs)} old, past --cache-max-age`);
+		else if (found.kind === "unusable") warn(`ignoring the cached secrets: ${found.reason}`);
+		throw err;
+	}
+}
+function warn(text) {
+	process.stderr.write(`seekrit: ${text}\n`);
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
 * Overlay `.env` files onto an existing value/provenance set (later files win).
 * Missing files are skipped. Returns the files that were actually loaded. Used
 * both by {@link materializeEnv} and by `seekrit run`'s degraded path, where
@@ -6840,8 +7039,55 @@ withTarget(secrets.command("rm <name>").description("delete a secret")).action(a
 	await ctx.client.deleteSecret(orgId, envId, name);
 	console.error(`${name} deleted`);
 });
+/**
+* Open the last-known-good cache for this request, or `undefined` when it is
+* off. `dotenvVars` carries `SEEKRIT_*` values read from a `.env` file, so the
+* flags follow the same `flag > env > .env` precedence as the credentials.
+*
+* **Service tokens only.** A user session's private key is fetched from the API
+* and unlocked with a passphrase, so caching the resolve response alone would
+* not make an offline run work — and the token is what the cache key is built
+* from. `--cache` under user auth is a no-op we say out loud rather than a
+* silent one.
+*/
+function openCache(ctx, options, dotenvVars = {}) {
+	const lookup = (key) => process.env[key] ?? dotenvVars[key];
+	const truthy = (value) => [
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes((value ?? "").trim().toLowerCase());
+	if (!(options.cache ?? truthy(lookup("SEEKRIT_CACHE")))) return void 0;
+	if (!isTokenAuth(ctx)) {
+		process.stderr.write("seekrit: --cache needs a service token (SEEKRIT_TOKEN); continuing without it\n");
+		return;
+	}
+	const token = ctx.auth.type === "bearer" ? ctx.auth.token : "";
+	const maxAgeRaw = options.cacheMaxAge ?? lookup("SEEKRIT_CACHE_MAX_AGE");
+	const maxAgeMs = maxAgeRaw ? parseDurationMs(maxAgeRaw) : DEFAULT_MAX_AGE_MS;
+	const branch = options.branch ?? process.env.SEEKRIT_BRANCH ?? dotenvVars.SEEKRIT_BRANCH;
+	return new LkgCache(cacheKey(ctx.apiUrl, token, branch, options.with), {
+		dir: options.cacheDir ?? lookup("SEEKRIT_CACHE_DIR"),
+		maxAgeMs
+	});
+}
+/** `30s` / `15m` / `24h` / `7d` / bare seconds → ms. Matches the Rust parser. */
+function parseDurationMs(raw) {
+	const match = /^(\d+)\s*([smhd]?)$/.exec(raw.trim());
+	if (!match) fail(`--cache-max-age: not a duration: "${raw}" (try 15m, 24h, 7d)`);
+	const value = Number(match[1]);
+	if (value === 0) fail("--cache-max-age: must be greater than zero");
+	return value * ({
+		"": 1,
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400
+	}[match[2] ?? ""] ?? 1) * 1e3;
+}
 /** Resolve the layered environment for the current principal. */
-async function materialize(ctx, options) {
+async function materialize(ctx, options, dotenvVars = {}) {
 	let envId;
 	if (!isTokenAuth(ctx)) envId = (await resolveAppEnv(ctx, options)).envId;
 	return materializeEnv(ctx, {
@@ -6849,7 +7095,8 @@ async function materialize(ctx, options) {
 		branch: options.branch ?? process.env.SEEKRIT_BRANCH,
 		with: options.with,
 		envFiles: options.envFile ?? [".env"],
-		interpolate: options.interpolate
+		interpolate: options.interpolate,
+		cache: openCache(ctx, options, dotenvVars)
 	});
 }
 /**
@@ -6871,7 +7118,7 @@ async function materializeForRun(options) {
 		return await materialize(ctx, {
 			...options,
 			branch
-		});
+		}, dotenvVars);
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		console.error(`seekrit: continuing without seekrit-managed secrets: ${message}`);
@@ -6994,7 +7241,7 @@ async function reapStragglers(pids, signal) {
 		process.kill(pid, "SIGKILL");
 	} catch {}
 }
-program.command("run").description("run a command with decrypted secrets injected (process env > .env > app > group)").passThroughOptions().option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
+program.command("run").description("run a command with decrypted secrets injected (process env > .env > app > group)").passThroughOptions().option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--cache", "keep a last-known-good copy of the encrypted response and fall back to it when the API is unreachable (off by default; SEEKRIT_CACHE=1)").option("--cache-dir <path>", "where to keep it (default: $XDG_CACHE_HOME/seekrit)").option("--cache-max-age <duration>", "how stale a cached copy may be and still be used, e.g. 15m, 24h, 7d (default: 24h)").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
 	const [cmd, ...args] = commandParts;
 	if (!cmd) fail("no command given");
 	const { values, provenance, interpolated, unresolvedRefs } = await materializeForRun(options);
@@ -7046,7 +7293,7 @@ program.command("run").description("run a command with decrypted secrets injecte
 	});
 	child.on("error", (err) => fail(`failed to start ${cmd}: ${err.message}`));
 });
-program.command("export").description("print decrypted secrets (dotenv, json, or shell)").option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
+program.command("export").description("print decrypted secrets (dotenv, json, or shell)").option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--cache", "keep a last-known-good copy of the encrypted response and fall back to it when the API is unreachable (off by default; SEEKRIT_CACHE=1)").option("--cache-dir <path>", "where to keep it (default: $XDG_CACHE_HOME/seekrit)").option("--cache-max-age <duration>", "how stale a cached copy may be and still be used, e.g. 15m, 24h, 7d (default: 24h)").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
 	if (![
 		"dotenv",
 		"json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {
@@ -26,13 +26,15 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
-    "@seekrit/api-client": "0.0.1",
+    "vitest": "^4.1.9",
     "@seekrit/core": "0.0.1",
+    "@seekrit/api-client": "0.0.1",
     "@seekrit/crypto": "0.0.1"
   },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }