@capxul/sandbox 1.0.0-alpha.3 → 1.1.0

package/README.md

@@ -15,10 +15,16 @@ npx @capxul/sandbox faucet send
 vp run --filter @capxul/sandbox dev -- --help
 ```
 
-`key create` uses the public quickstart endpoint and needs no operator secret.
+`key create` uses the Little Sandpiper public staging quickstart endpoint and
+needs no operator secret. `APP_ENV` does not retarget this public command; use
+the returned key only with the staging tuple.
 `faucet send` invokes the canonical Convex deployment and requires operator
-configuration from `~/.config/capxul/secrets.env`; never print or commit those
-values.
+access in the process environment: inside the infrastructure repository, run
+it through the one env entry point
+(`vp exec bash scripts/capxul-env.sh npx @capxul/sandbox faucet send`); outside
+it, supply the deploy key directly
+(`CONVEX_DEPLOY_KEY=… npx @capxul/sandbox faucet send`). Never print or commit
+those values.
 
 ## Verify in the repository
 

package/dist/main.mjs

@@ -1,307 +1,134 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
 import { cancel, confirm, intro, isCancel, note, outro, select, spinner, text } from "@clack/prompts";
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import path, { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { readFile, writeFile } from "node:fs/promises";
-//#region \0rolldown/runtime.js
-var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-//#endregion
-//#region ../../packages/backend/scripts/publishable-key-minting.ts
-var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
-	const fs = __require("fs");
-	const path = __require("path");
-	const os = __require("os");
-	const crypto = __require("crypto");
-	const TIPS = [
-		"◈ encrypted .env [www.dotenvx.com]",
-		"◈ secrets for agents [www.dotenvx.com]",
-		"⌁ auth for agents [www.vestauth.com]",
-		"⌘ custom filepath { path: '/custom/path/.env' }",
-		"⌘ enable debugging { debug: true }",
-		"⌘ override existing { override: true }",
-		"⌘ suppress logs { quiet: true }",
-		"⌘ multiple files { path: ['.env.local', '.env'] }"
-	];
-	function _getRandomTip() {
-		return TIPS[Math.floor(Math.random() * TIPS.length)];
-	}
-	function parseBoolean(value) {
-		if (typeof value === "string") return ![
-			"false",
-			"0",
-			"no",
-			"off",
-			""
-		].includes(value.toLowerCase());
-		return Boolean(value);
-	}
-	function supportsAnsi() {
-		return process.stdout.isTTY;
-	}
-	function dim(text) {
-		return supportsAnsi() ? `\x1b[2m${text}\x1b[0m` : text;
-	}
-	const LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
-	function parse(src) {
-		const obj = {};
-		let lines = src.toString();
-		lines = lines.replace(/\r\n?/gm, "\n");
-		let match;
-		while ((match = LINE.exec(lines)) != null) {
-			const key = match[1];
-			let value = match[2] || "";
-			value = value.trim();
-			const maybeQuote = value[0];
-			value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
-			if (maybeQuote === "\"") {
-				value = value.replace(/\\n/g, "\n");
-				value = value.replace(/\\r/g, "\r");
-			}
-			obj[key] = value;
-		}
-		return obj;
-	}
-	function _parseVault(options) {
-		options = options || {};
-		const vaultPath = _vaultPath(options);
-		options.path = vaultPath;
-		const result = DotenvModule.configDotenv(options);
-		if (!result.parsed) {
-			const err = /* @__PURE__ */ new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
-			err.code = "MISSING_DATA";
-			throw err;
-		}
-		const keys = _dotenvKey(options).split(",");
-		const length = keys.length;
-		let decrypted;
-		for (let i = 0; i < length; i++) try {
-			const attrs = _instructions(result, keys[i].trim());
-			decrypted = DotenvModule.decrypt(attrs.ciphertext, attrs.key);
-			break;
-		} catch (error) {
-			if (i + 1 >= length) throw error;
-		}
-		return DotenvModule.parse(decrypted);
-	}
-	function _warn(message) {
-		console.error(`⚠ ${message}`);
-	}
-	function _debug(message) {
-		console.log(`┆ ${message}`);
-	}
-	function _log(message) {
-		console.log(`◇ ${message}`);
-	}
-	function _dotenvKey(options) {
-		if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) return options.DOTENV_KEY;
-		if (process.env.DOTENV_KEY && process.env.DOTENV_KEY.length > 0) return process.env.DOTENV_KEY;
-		return "";
-	}
-	function _instructions(result, dotenvKey) {
-		let uri;
-		try {
-			uri = new URL(dotenvKey);
-		} catch (error) {
-			if (error.code === "ERR_INVALID_URL") {
-				const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
-				err.code = "INVALID_DOTENV_KEY";
-				throw err;
-			}
-			throw error;
-		}
-		const key = uri.password;
-		if (!key) {
-			const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: Missing key part");
-			err.code = "INVALID_DOTENV_KEY";
-			throw err;
-		}
-		const environment = uri.searchParams.get("environment");
-		if (!environment) {
-			const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: Missing environment part");
-			err.code = "INVALID_DOTENV_KEY";
-			throw err;
-		}
-		const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`;
-		const ciphertext = result.parsed[environmentKey];
-		if (!ciphertext) {
-			const err = /* @__PURE__ */ new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
-			err.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
-			throw err;
-		}
-		return {
-			ciphertext,
-			key
-		};
-	}
-	function _vaultPath(options) {
-		let possibleVaultPath = null;
-		if (options && options.path && options.path.length > 0) if (Array.isArray(options.path)) {
-			for (const filepath of options.path) if (fs.existsSync(filepath)) possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
-		} else possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
-		else possibleVaultPath = path.resolve(process.cwd(), ".env.vault");
-		if (fs.existsSync(possibleVaultPath)) return possibleVaultPath;
-		return null;
-	}
-	function _resolveHome(envPath) {
-		return envPath[0] === "~" ? path.join(os.homedir(), envPath.slice(1)) : envPath;
-	}
-	function _configVault(options) {
-		const debug = parseBoolean(process.env.DOTENV_CONFIG_DEBUG || options && options.debug);
-		const quiet = parseBoolean(process.env.DOTENV_CONFIG_QUIET || options && options.quiet);
-		if (debug || !quiet) _log("loading env from encrypted .env.vault");
-		const parsed = DotenvModule._parseVault(options);
-		let processEnv = process.env;
-		if (options && options.processEnv != null) processEnv = options.processEnv;
-		DotenvModule.populate(processEnv, parsed, options);
-		return { parsed };
-	}
-	function configDotenv(options) {
-		const dotenvPath = path.resolve(process.cwd(), ".env");
-		let encoding = "utf8";
-		let processEnv = process.env;
-		if (options && options.processEnv != null) processEnv = options.processEnv;
-		let debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || options && options.debug);
-		let quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || options && options.quiet);
-		if (options && options.encoding) encoding = options.encoding;
-		else if (debug) _debug("no encoding is specified (UTF-8 is used by default)");
-		let optionPaths = [dotenvPath];
-		if (options && options.path) if (!Array.isArray(options.path)) optionPaths = [_resolveHome(options.path)];
-		else {
-			optionPaths = [];
-			for (const filepath of options.path) optionPaths.push(_resolveHome(filepath));
-		}
-		let lastError;
-		const parsedAll = {};
-		for (const path of optionPaths) try {
-			const parsed = DotenvModule.parse(fs.readFileSync(path, { encoding }));
-			DotenvModule.populate(parsedAll, parsed, options);
-		} catch (e) {
-			if (debug) _debug(`failed to load ${path} ${e.message}`);
-			lastError = e;
-		}
-		const populated = DotenvModule.populate(processEnv, parsedAll, options);
-		debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || debug);
-		quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || quiet);
-		if (debug || !quiet) {
-			const keysCount = Object.keys(populated).length;
-			const shortPaths = [];
-			for (const filePath of optionPaths) try {
-				const relative = path.relative(process.cwd(), filePath);
-				shortPaths.push(relative);
-			} catch (e) {
-				if (debug) _debug(`failed to load ${filePath} ${e.message}`);
-				lastError = e;
-			}
-			_log(`injected env (${keysCount}) from ${shortPaths.join(",")} ${dim(`// tip: ${_getRandomTip()}`)}`);
-		}
-		if (lastError) return {
-			parsed: parsedAll,
-			error: lastError
-		};
-		else return { parsed: parsedAll };
-	}
-	function config(options) {
-		if (_dotenvKey(options).length === 0) return DotenvModule.configDotenv(options);
-		const vaultPath = _vaultPath(options);
-		if (!vaultPath) {
-			_warn(`you set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}`);
-			return DotenvModule.configDotenv(options);
+//#region ../../config/deployment-topology.json
+var deployment_topology_default = {
+	schemaVersion: 1,
+	product: "capxul-platform",
+	environments: {
+		"development": {
+			"appEnv": "development",
+			"productRole": "development",
+			"convexProject": "capxul-platform-dev",
+			"deployment": "dev:incredible-possum-990",
+			"deploymentReference": "dev/aaron-griffith",
+			"name": "incredible-possum-990",
+			"convexType": "dev",
+			"convexUrl": "https://incredible-possum-990.convex.cloud",
+			"convexSiteUrl": "https://incredible-possum-990.convex.site",
+			"chainId": 84532,
+			"expectedFingerprints": {
+				"applicationId": "a4b0c7e61ec45aec",
+				"openfortPublishableKey": "aab42edbcdc683e7",
+				"shieldPublishableKey": "a323489c9a8d8da2"
+			},
+			"proofCommand": "APP_ENV=development vp exec bash scripts/capxul-env.sh vp exec node scripts/prove-deployment-bootstrap.mjs"
+		},
+		"staging": {
+			"appEnv": "staging",
+			"productRole": "staging",
+			"convexProject": "capxul-platform-effect",
+			"deployment": "prod:little-sandpiper-974",
+			"deploymentReference": "production",
+			"name": "little-sandpiper-974",
+			"convexType": "prod",
+			"convexUrl": "https://little-sandpiper-974.convex.cloud",
+			"convexSiteUrl": "https://little-sandpiper-974.convex.site",
+			"chainId": 84532,
+			"expectedFingerprints": {
+				"applicationId": "4e2989ea295fc269",
+				"openfortPublishableKey": "aab42edbcdc683e7",
+				"shieldPublishableKey": "a323489c9a8d8da2"
+			},
+			"proofCommand": "APP_ENV=staging vp exec bash scripts/capxul-env.sh vp exec node scripts/prove-deployment-bootstrap.mjs"
 		}
-		return DotenvModule._configVault(options);
-	}
-	function decrypt(encrypted, keyStr) {
-		const key = Buffer.from(keyStr.slice(-64), "hex");
-		let ciphertext = Buffer.from(encrypted, "base64");
-		const nonce = ciphertext.subarray(0, 12);
-		const authTag = ciphertext.subarray(-16);
-		ciphertext = ciphertext.subarray(12, -16);
+	},
+	production: null
+};
+//#endregion
+//#region ../../scripts/deployment-topology.mjs
+const SUPPORTED_APP_ENVS = ["development", "staging"];
+function loadDeploymentTopology() {
+	const topology = structuredClone(deployment_topology_default);
+	const environmentNames = Object.keys(topology.environments ?? {}).sort();
+	if (topology.schemaVersion !== 1 || topology.product !== "capxul-platform" || topology.production !== null || JSON.stringify(environmentNames) !== JSON.stringify(SUPPORTED_APP_ENVS)) throw new Error("Invalid Capxul deployment topology: expected development + staging and no production tier");
+	return topology;
+}
+function resolveDeploymentTier(appEnv) {
+	const tier = loadDeploymentTopology().environments[appEnv];
+	if (tier === void 0) throw new Error(`Unsupported APP_ENV '${String(appEnv)}'; expected development or staging (production is not provisioned)`);
+	return tier;
+}
+function assertDeploymentTuple(appEnv, values) {
+	const tier = resolveDeploymentTier(appEnv);
+	const expected = {
+		CONVEX_DEPLOYMENT: tier.deployment,
+		CONVEX_URL: tier.convexUrl,
+		CONVEX_SITE_URL: tier.convexSiteUrl
+	};
+	const mismatches = Object.entries(expected).flatMap(([name, expectedValue]) => {
+		const actual = values[name]?.trim();
+		return actual === expectedValue ? [] : [`${name}: expected '${expectedValue}', received '${actual ?? "<missing>"}'`];
+	});
+	const deployKey = values.CONVEX_DEPLOY_KEY?.trim();
+	if (deployKey !== void 0 && deployKey.length > 0) {
+		const separatorIndex = deployKey.indexOf("|");
+		const candidateDeployment = separatorIndex > 0 && deployKey.slice(separatorIndex + 1).trim().length > 0 ? deployKey.slice(0, separatorIndex) : "";
+		const keyDeployment = /^(?:dev|prod):[a-z0-9-]+$/u.test(candidateDeployment) ? candidateDeployment : void 0;
+		if (keyDeployment !== tier.deployment) mismatches.push(`CONVEX_DEPLOY_KEY: expected a key bound to '${tier.deployment}', received a key for '${keyDeployment ?? "<invalid>"}'`);
+	}
+	for (const optionalUrlName of ["CAPXUL_E2E_BOOTSTRAP_URL", "CAPXUL_E2E_BOOTSTRAP_BASE_URL"]) {
+		const raw = values[optionalUrlName]?.trim();
+		if (raw === void 0 || raw.length === 0) continue;
+		let actualHost;
 		try {
-			const aesgcm = crypto.createDecipheriv("aes-256-gcm", key, nonce);
-			aesgcm.setAuthTag(authTag);
-			return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
-		} catch (error) {
-			const isRange = error instanceof RangeError;
-			const invalidKeyLength = error.message === "Invalid key length";
-			const decryptionFailed = error.message === "Unsupported state or unable to authenticate data";
-			if (isRange || invalidKeyLength) {
-				const err = /* @__PURE__ */ new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
-				err.code = "INVALID_DOTENV_KEY";
-				throw err;
-			} else if (decryptionFailed) {
-				const err = /* @__PURE__ */ new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
-				err.code = "DECRYPTION_FAILED";
-				throw err;
-			} else throw error;
+			actualHost = new URL(raw).host;
+		} catch {
+			mismatches.push(`${optionalUrlName}: expected a URL for ${tier.name}, received an invalid URL`);
+			continue;
 		}
+		if (actualHost !== new URL(tier.convexSiteUrl).host) mismatches.push(`${optionalUrlName}: expected host '${new URL(tier.convexSiteUrl).host}', received '${actualHost}'`);
 	}
-	function populate(processEnv, parsed, options = {}) {
-		const debug = Boolean(options && options.debug);
-		const override = Boolean(options && options.override);
-		const populated = {};
-		if (typeof parsed !== "object") {
-			const err = /* @__PURE__ */ new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
-			err.code = "OBJECT_REQUIRED";
-			throw err;
-		}
-		for (const key of Object.keys(parsed)) if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
-			if (override === true) {
-				processEnv[key] = parsed[key];
-				populated[key] = parsed[key];
-			}
-			if (debug) if (override === true) _debug(`"${key}" is already defined and WAS overwritten`);
-			else _debug(`"${key}" is already defined and was NOT overwritten`);
-		} else {
-			processEnv[key] = parsed[key];
-			populated[key] = parsed[key];
-		}
-		return populated;
-	}
-	const DotenvModule = {
-		configDotenv,
-		_configVault,
-		_parseVault,
-		config,
-		decrypt,
-		parse,
-		populate
-	};
-	module.exports.configDotenv = DotenvModule.configDotenv;
-	module.exports._configVault = DotenvModule._configVault;
-	module.exports._parseVault = DotenvModule._parseVault;
-	module.exports.config = DotenvModule.config;
-	module.exports.decrypt = DotenvModule.decrypt;
-	module.exports.parse = DotenvModule.parse;
-	module.exports.populate = DotenvModule.populate;
-	module.exports = DotenvModule;
-})))();
+	if (mismatches.length > 0) throw new Error(`Deployment tuple mismatch: expected ${appEnv} '${tier.name}'. Refusing to continue.\n${mismatches.join("\n")}`);
+	return tier;
+}
+function runCli() {
+	const command = process.argv[2] ?? "check";
+	const appEnvIndex = process.argv.indexOf("--app-env");
+	const appEnv = appEnvIndex === -1 ? process.env.APP_ENV ?? "development" : process.argv[appEnvIndex + 1];
+	if (command === "print") {
+		process.stdout.write(`${JSON.stringify(resolveDeploymentTier(appEnv), null, 2)}\n`);
+		return;
+	}
+	if (command === "field") {
+		const fieldIndex = process.argv.indexOf("--field");
+		const field = fieldIndex === -1 ? void 0 : process.argv[fieldIndex + 1];
+		const tier = resolveDeploymentTier(appEnv);
+		if (field === void 0 || !Object.hasOwn(tier, field)) throw new Error(`Unknown deployment topology field '${String(field)}'`);
+		process.stdout.write(`${String(tier[field])}\n`);
+		return;
+	}
+	if (command !== "check") throw new Error(`Unknown deployment-topology command '${command}'; expected check, print, or field`);
+	const tier = assertDeploymentTuple(appEnv, process.env);
+	process.stdout.write(`Capxul ${tier.productRole} tuple verified: ${tier.deployment} (${tier.convexProject})\n`);
+}
+if (process.argv[1] !== void 0 && path.basename(process.argv[1]) === "deployment-topology.mjs" && import.meta.url === pathToFileURL(process.argv[1]).href) try {
+	runCli();
+} catch (error) {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
 resolve(resolve(fileURLToPath(new URL("..", import.meta.url))), "..", "..");
-const defaultOperatorSecretsPath = resolve(homedir(), ".config/capxul/secrets.env");
+const standingStaging = resolveDeploymentTier("staging");
 const CANONICAL_QUICKSTART_DEPLOYMENT = {
-	deployment: "prod:little-sandpiper-974",
-	convexUrl: "https://little-sandpiper-974.convex.cloud",
-	convexSiteUrl: "https://little-sandpiper-974.convex.site"
+	deployment: standingStaging.deployment,
+	convexUrl: standingStaging.convexUrl,
+	convexSiteUrl: standingStaging.convexSiteUrl
 };
-function loadOperatorEnv(sourceEnv = process.env) {
-	const env = { ...sourceEnv };
-	const envFiles = [defaultOperatorSecretsPath, env.CAPXUL_SECRETS_FILE ? resolve(env.CAPXUL_SECRETS_FILE) : void 0].filter((path) => path !== void 0);
-	for (const path of envFiles) if (existsSync(path)) {
-		const parsed = (0, import_main.config)({
-			path,
-			processEnv: env,
-			override: true
-		});
-		if (parsed.error !== void 0) throw parsed.error;
-	}
-	env.CONVEX_URL ||= env.CAPXUL_E2E_CONVEX_URL;
-	env.CONVEX_SITE_URL ||= env.CAPXUL_E2E_CONVEX_SITE_URL;
-	env.CAPXUL_E2E_ORIGIN ||= env.CAPXUL_E2E_BOOTSTRAP_URL || env.SITE_URL;
-	return env;
-}
 function normalizeHttpOrigin(raw) {
 	const value = raw.trim();
 	if (value.length === 0) throw new Error("Origin is required.");
@@ -513,7 +340,7 @@ async function runFaucetSend() {
 	const s = spinner();
 	s.start("Minting testnet funds");
 	try {
-		const runConvex = canonicalConvexRunner(loadOperatorEnv());
+		const runConvex = canonicalConvexRunner();
 		const result = recipient.kind === "address" ? runConvex("", [
 			"run",
 			FAUCET_ADDRESS_FUNCTION,
@@ -545,7 +372,8 @@ async function runFaucetSend() {
 		return 0;
 	} catch (error) {
 		s.stop("Faucet send failed");
-		cancel(errorMessage(error));
+		const hint = process.env.CONVEX_DEPLOY_KEY === void 0 ? "\nHint: CONVEX_DEPLOY_KEY is not set — the faucet needs operator access to the canonical deployment. Supply it (CONVEX_DEPLOY_KEY=… npx @capxul/sandbox faucet send) or, inside the infrastructure repo, run through scripts/capxul-env.sh." : "";
+		cancel(errorMessage(error) + hint);
 		return 1;
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sandbox",
-  "version": "1.0.0-alpha.3",
+  "version": "1.1.0",
   "private": false,
   "description": "Capxul sandbox CLI for canonical quickstart keys and testnet faucet funds.",
   "keywords": [