@capxul/sandbox 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -0,0 +1,48 @@
+# Capxul Sandbox (`@capxul/sandbox`)
+
+The published interactive CLI for two sandbox operator/developer tasks:
+
+- `key create` mints a test publishable key for a local origin and writes the
+  canonical Next.js environment names to `.env.local`.
+- `faucet send` mints test USDX on Base Sepolia to a Capxul email,
+  `@org-handle`, or an explicitly confirmed raw-address escape hatch.
+
+```bash
+npx @capxul/sandbox key create
+npx @capxul/sandbox faucet send
+
+# Repository development
+vp run --filter @capxul/sandbox dev -- --help
+```
+
+`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
+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
+
+```bash
+vp run --filter @capxul/sandbox check-types
+vp test run apps/sandbox
+vp run --filter @capxul/sandbox build
+```
+
+These checks prove parsing, environment-file rewriting, bounded amount
+conversion, Convex command construction, and packing. They do not prove a live
+key mint, faucet transaction, or installed CLI artifact.
+
+Repository Rule 4 names `vp run --filter @capxul/sandbox proofs:live` as the
+live-only ProofKit boundary, but that command does not exist yet. Keep live
+acceptance unproven until [#920](https://github.com/Xelmar-tech/infrastructure/issues/920)
+lands. [#922](https://github.com/Xelmar-tech/infrastructure/issues/922) tracks
+the separate packed-install/bin smoke gap.
+
+Read [CONTEXT.md](./CONTEXT.md) before changing command, secret, deployment, or
+proof behavior.

package/dist/main.mjs

@@ -1,315 +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 { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-//#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;
+import path, { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readFile, writeFile } from "node:fs/promises";
+//#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": "e0deb415da6714f8",
+				"openfortPublishableKey": "f8fed245b357f1c3",
+				"shieldPublishableKey": "d8eb8898a1ff1d9a"
+			},
+			"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"
 		}
-		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);
-		}
-		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;
-		}
-	}
-	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];
+			actualHost = new URL(raw).host;
+		} catch {
+			mismatches.push(`${optionalUrlName}: expected a URL for ${tier.name}, received an invalid URL`);
+			continue;
 		}
-		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;
-})))();
-const backendRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
-const repoRoot = resolve(backendRoot, "..", "..");
-const defaultOperatorSecretsPath = resolve(homedir(), ".config/capxul/secrets.env");
-const DEFAULT_APP_NAME = "Customer Next.js Quickstart";
-const DEFAULT_ALLOWED_ORIGIN = "http://localhost:3000";
-const DEFAULT_HANDOFF_PATH = resolve(homedir(), ".config/capxul/quickstart-handoffs/customer-nextjs-quickstart.md");
-const CANONICAL_QUICKSTART_DEPLOYMENT = {
-	deployment: "dev:glad-jaguar-154",
-	convexUrl: "https://glad-jaguar-154.convex.cloud",
-	convexSiteUrl: "https://glad-jaguar-154.convex.site"
-};
-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;
+		if (actualHost !== new URL(tier.convexSiteUrl).host) mismatches.push(`${optionalUrlName}: expected host '${new URL(tier.convexSiteUrl).host}', received '${actualHost}'`);
 	}
-	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;
+	if (mismatches.length > 0) throw new Error(`Deployment tuple mismatch: expected ${appEnv} '${tier.name}'. Refusing to continue.\n${mismatches.join("\n")}`);
+	return tier;
 }
-function requiredEnv(env, name) {
-	const value = env[name]?.trim();
-	if (value === void 0 || value.length === 0) throw new Error(`Missing required env: ${name}`);
-	return value;
+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 standingStaging = resolveDeploymentTier("staging");
+const CANONICAL_QUICKSTART_DEPLOYMENT = {
+	deployment: standingStaging.deployment,
+	convexUrl: standingStaging.convexUrl,
+	convexSiteUrl: standingStaging.convexSiteUrl
+};
 function normalizeHttpOrigin(raw) {
 	const value = raw.trim();
 	if (value.length === 0) throw new Error("Origin is required.");
@@ -324,42 +143,6 @@ function normalizeHttpOrigin(raw) {
 	if (url.pathname !== "/" || url.search || url.hash) throw new Error("Origin must not include a path, query, or hash.");
 	return `${url.protocol}//${url.host}`;
 }
-function writeConvexDeploymentEnvFile(deployment) {
-	const path = resolve(mkdtempSync(resolve(tmpdir(), "capxul-convex-")), "deployment.env");
-	writeFileSync(path, `CONVEX_DEPLOYMENT=${deployment}\n`, {
-		encoding: "utf8",
-		mode: 384
-	});
-	return path;
-}
-function minimalConvexEnv() {
-	return {
-		CI: "true",
-		HOME: homedir(),
-		PATH: process.env.PATH ?? "",
-		TMPDIR: process.env.TMPDIR ?? tmpdir()
-	};
-}
-function runConvex(deploymentEnvFile, args) {
-	const result = spawnSync(resolve(backendRoot, "node_modules/.bin/convex"), [
-		...args,
-		"--env-file",
-		deploymentEnvFile
-	], {
-		cwd: backendRoot,
-		env: minimalConvexEnv(),
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		]
-	});
-	return {
-		ok: result.status === 0,
-		output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
-	};
-}
 function extractField(output, field) {
 	const quoted = new RegExp(`"${field}"\\s*:\\s*"([^"]+)"`).exec(output);
 	if (quoted?.[1]) return quoted[1];
@@ -367,140 +150,6 @@ function extractField(output, field) {
 	if (jsLike?.[1]) return jsLike[1];
 	throw new Error(`Convex output did not include ${field}`);
 }
-function packageVersion(packageDir) {
-	const pkg = JSON.parse(readFileSync(resolve(repoRoot, "packages", packageDir, "package.json"), "utf8"));
-	if (!pkg.version) throw new Error(`Missing version in packages/${packageDir}/package.json`);
-	return pkg.version;
-}
-function redactPublishableKeys(output) {
-	return output.replace(/cap_pk_(test|live)_[0-9A-HJKMNP-TV-Z]+/g, "cap_pk_$1_REDACTED");
-}
-function writeSecureHandoff(path, values) {
-	const handoffDir = dirname(path);
-	const handoffDirAlreadyExisted = existsSync(handoffDir);
-	mkdirSync(handoffDir, {
-		recursive: true,
-		mode: 448
-	});
-	if (!handoffDirAlreadyExisted) chmodSync(handoffDir, 448);
-	const body = `# Capxul Next.js Quickstart Secure Handoff
-
-Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
-
-| Value | Customer value |
-| --- | --- |
-| Package versions | @capxul/sdk@${values.sdkVersion}, @capxul/sdk-react@${values.sdkReactVersion} |
-| npm dist tag | alpha |
-| Environment | ${values.environment} |
-| Developer application | ${values.appName} |
-| Application id | ${values.applicationId} |
-| Publishable key id | ${values.keyId} |
-| Publishable key | ${values.publishableKey} |
-| Capxul site URL | ${values.convexSiteUrl} |
-| Convex URL | ${values.convexUrl} |
-| Local allowed origin | ${values.allowedOrigin} |
-| Production allowed origin | <set after customer domain is known> |
-| Auth method | Email OTP |
-
-Put the publishable key in \`.env.local\` as
-\`NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY\`, and set server-side
-\`CAPXUL_SITE_URL=${values.convexSiteUrl}\` for the Next.js rewrites. Do not send
-backend secrets, private keys, Convex deploy keys, Resend keys, Openfort server
-keys, or operator credentials to the customer.
-`;
-	const tmpDir = mkdtempSync(join(handoffDir, ".handoff-"));
-	try {
-		const tmpPath = join(tmpDir, "quickstart.md");
-		writeFileSync(tmpPath, body, {
-			encoding: "utf8",
-			mode: 384
-		});
-		chmodSync(tmpPath, 384);
-		renameSync(tmpPath, path);
-		chmodSync(path, 384);
-	} finally {
-		rmSync(tmpDir, {
-			recursive: true,
-			force: true
-		});
-	}
-}
-async function mintNextjsQuickstartKey(input, deps = {}) {
-	const environment = input.environment ?? "test";
-	const pushBackend = input.pushBackend ?? true;
-	const openfortPublishableKey = requiredEnv(input.env, "OPENFORT_PUBLISHABLE_KEY");
-	const shieldPublishableKey = requiredEnv(input.env, "SHIELD_PUBLISHABLE_KEY");
-	const allowedOrigin = normalizeHttpOrigin(input.allowedOrigin);
-	const convexSiteUrl = input.convexSiteUrl.replace(/\/$/, "");
-	const convexUrl = input.convexUrl.replace(/\/$/, "");
-	const authBaseUrl = `${convexSiteUrl}/api/auth`;
-	const deploymentEnvFile = writeConvexDeploymentEnvFile(input.deployment);
-	const run = deps.runConvex ?? runConvex;
-	const resolvePackageVersion = deps.packageVersion ?? packageVersion;
-	if (pushBackend) {
-		const deploy = run(deploymentEnvFile, ["dev", "--once"]);
-		if (!deploy.ok) throw new Error(deploy.output || "Convex deploy failed.");
-	}
-	const publishableKeyConfig = {
-		allowedOrigins: [allowedOrigin],
-		authBaseUrl,
-		convexUrl,
-		siteBaseUrl: convexSiteUrl,
-		openfortPublishableKey,
-		shieldPublishableKey
-	};
-	const app = run(deploymentEnvFile, [
-		"run",
-		"credentials/mutations:createDeveloperApplication",
-		JSON.stringify({
-			name: input.appName,
-			...publishableKeyConfig
-		})
-	]);
-	if (!app.ok) throw new Error(app.output || "Developer application creation failed.");
-	const applicationId = extractField(app.output, "applicationId");
-	const key = run(deploymentEnvFile, [
-		"run",
-		"credentials/mutations:mintPublishableKey",
-		JSON.stringify({
-			applicationId,
-			environment,
-			...publishableKeyConfig
-		})
-	]);
-	if (!key.ok) throw new Error(redactPublishableKeys(key.output || "Publishable key mint failed."));
-	const keyId = extractField(key.output, "keyId");
-	const publishableKey = extractField(key.output, "publishableKey");
-	writeSecureHandoff(input.handoffPath, {
-		appName: input.appName,
-		applicationId,
-		keyId,
-		publishableKey,
-		allowedOrigin,
-		convexSiteUrl,
-		convexUrl,
-		sdkVersion: resolvePackageVersion("sdk"),
-		sdkReactVersion: resolvePackageVersion("sdk-react"),
-		environment
-	});
-	return {
-		appName: input.appName,
-		applicationId,
-		keyId,
-		publishableKey,
-		allowedOrigin,
-		convexSiteUrl,
-		convexUrl,
-		handoffPath: input.handoffPath,
-		environment
-	};
-}
-//#endregion
-//#region src/runtime.ts
-const bundledPackageVersions = {
-	sdk: "1.0.0-alpha.14",
-	"sdk-react": "1.0.0-alpha.14"
-};
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const FAUCET_DECIMALS = 6n;
 const FAUCET_DECIMAL_PLACES = Number(FAUCET_DECIMALS);
@@ -545,11 +194,6 @@ function convexChildEnv(deployment, sourceEnv) {
 	}
 	return env;
 }
-function bundledPackageVersion(packageDir) {
-	const version = bundledPackageVersions[packageDir];
-	if (version === void 0 || version.length === 0) throw new Error(`Missing bundled package version for ${packageDir}`);
-	return version;
-}
 function createConvexPathRunner({ deployment, env: sourceEnv = process.env, spawn = spawnSync }) {
 	return (_deploymentEnvFile, args) => {
 		const childEnv = convexChildEnv(deployment, sourceEnv);
@@ -696,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,
@@ -728,34 +372,127 @@ 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;
 	}
 }
+/** Default developer origin when the caller passes no origin. */
+const DEFAULT_ORIGIN = "http://localhost:3000";
+/**
+* Origins the shared sandbox deployment pre-trusts for email/OTP auth. Mirrors
+* `QUICKSTART_ORIGINS` in `scripts/sync-convex-env.sh` (which unions these into
+* the deployment's `CAPXUL_TRUSTED_ORIGINS`). A minted key scopes *bootstrap* to
+* whatever origin you pass, but the deployment-level trusted-origin gate
+* (`authFactory.buildTrustedOrigins`) rejects OTP/auth requests from origins
+* outside this set — and a self-serve `npx` caller cannot change that env var.
+* So an origin outside this set bootstraps but never completes sign-in. Keep in
+* sync with `sync-convex-env.sh`.
+*/
+const PRETRUSTED_QUICKSTART_ORIGINS = ["http://localhost:3000", "http://localhost:3100"];
+function isPretrustedQuickstartOrigin(origin) {
+	return PRETRUSTED_QUICKSTART_ORIGINS.includes(origin);
+}
+const ENV_FILE_NAME = ".env.local";
+const PUBLISHABLE_KEY_VAR = "NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY";
+const SITE_URL_VAR = "CAPXUL_SITE_URL";
+function resolveOrigin(options) {
+	return options.origin ?? "http://localhost:3000";
+}
+function isMintResponse(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.publishableKey === "string" && typeof candidate.convexSiteUrl === "string" && typeof candidate.authBaseUrl === "string" && Array.isArray(candidate.allowedOrigins) && candidate.allowedOrigins.every((origin) => typeof origin === "string");
+}
+/**
+* Upsert `key=value` into env-file text: replace the line if the key already
+* exists (preserving every other line), otherwise append. Keeps a developer's
+* existing `.env.local` intact rather than overwriting it.
+*/
+function upsertEnvVar(contents, key, value) {
+	const line = `${key}=${value}`;
+	const lines = contents.length === 0 ? [] : contents.split("\n");
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	const pattern = new RegExp(`^${key}=`);
+	let replaced = false;
+	const next = lines.map((existing) => {
+		if (pattern.test(existing)) {
+			replaced = true;
+			return line;
+		}
+		return existing;
+	});
+	if (!replaced) next.push(line);
+	return `${next.join("\n")}\n`;
+}
+function rewriteSnippet() {
+	return [
+		"Add these rewrites to next.config.ts so browser requests stay same-origin:",
+		"",
+		"  import type { NextConfig } from \"next\";",
+		"  import { loadEnvConfig } from \"@next/env\";",
+		"",
+		"  loadEnvConfig(process.cwd());",
+		"",
+		"  const capxulSiteUrl = process.env.CAPXUL_SITE_URL;",
+		"  if (!capxulSiteUrl) {",
+		"    throw new Error(\"CAPXUL_SITE_URL is required\");",
+		"  }",
+		"",
+		"  const nextConfig: NextConfig = {",
+		"    async rewrites() {",
+		"      return [",
+		"        {",
+		"          source: \"/v1/client/bootstrap\",",
+		"          destination: `${capxulSiteUrl}/v1/client/bootstrap`,",
+		"        },",
+		"        {",
+		"          source: \"/api/auth/:path*\",",
+		"          destination: `${capxulSiteUrl}/api/auth/:path*`,",
+		"        },",
+		"      ];",
+		"    },",
+		"  };",
+		"",
+		"  export default nextConfig;"
+	].join("\n");
+}
+async function runQuickstart(options, deps) {
+	const origin = resolveOrigin(options);
+	const endpoint = `${deps.baseUrl.replace(/\/$/, "")}/v1/client/mint-quickstart-key`;
+	deps.log(`Requesting a sandbox publishable key for ${origin} ...`);
+	const response = await deps.fetch(endpoint, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ origin })
+	});
+	if (!response.ok) {
+		const detail = await response.text().catch(() => "");
+		throw new Error(`Mint request failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}`);
+	}
+	const payload = await response.json();
+	if (!isMintResponse(payload)) throw new Error("Mint response did not match the expected shape.");
+	let updated = upsertEnvVar(await deps.readEnvFile() ?? "", PUBLISHABLE_KEY_VAR, payload.publishableKey);
+	updated = upsertEnvVar(updated, SITE_URL_VAR, payload.convexSiteUrl);
+	await deps.writeEnvFile(updated);
+	deps.log(`Wrote ${PUBLISHABLE_KEY_VAR} and ${SITE_URL_VAR} to ${ENV_FILE_NAME}.`);
+	deps.log(`Key is scoped to: ${payload.allowedOrigins.join(", ")}`);
+	deps.log("");
+	deps.log(rewriteSnippet());
+	return payload;
+}
 //#endregion
 //#region src/commands/key-create.ts
 async function runKeyCreate() {
 	intro("Capxul sandbox key create");
 	note([
-		`Deployment: ${CANONICAL_QUICKSTART_DEPLOYMENT.deployment}`,
-		`Site URL: ${CANONICAL_QUICKSTART_DEPLOYMENT.convexSiteUrl}`,
-		`Convex URL: ${CANONICAL_QUICKSTART_DEPLOYMENT.convexUrl}`,
-		"This npx CLI calls the already-deployed canonical backend; it does not push code."
-	].join("\n"), "Canonical deployment");
-	const appNamePrompt = await text({
-		message: "Developer application name",
-		initialValue: DEFAULT_APP_NAME,
-		validate(value) {
-			if ((value ?? "").trim().length === 0) return "Application name is required.";
-		}
-	});
-	if (isCancel(appNamePrompt)) {
-		cancel("No key created.");
-		return 0;
-	}
-	const allowedOriginPrompt = await text({
+		"Mints a sandbox test publishable key from the public Capxul backend.",
+		"No secrets, no login — nothing to configure. The key is written to",
+		".env.local in this directory (existing values are preserved)."
+	].join("\n"), "Quickstart");
+	const originPrompt = await text({
 		message: "Allowed local origin",
-		initialValue: DEFAULT_ALLOWED_ORIGIN,
+		initialValue: DEFAULT_ORIGIN,
 		validate(value) {
 			try {
 				normalizeHttpOrigin(value ?? "");
@@ -764,58 +501,44 @@ async function runKeyCreate() {
 			}
 		}
 	});
-	if (isCancel(allowedOriginPrompt)) {
-		cancel("No key created.");
-		return 0;
-	}
-	const handoffPathPrompt = await text({
-		message: "Secure handoff file",
-		initialValue: DEFAULT_HANDOFF_PATH,
-		validate(value) {
-			if ((value ?? "").trim().length === 0) return "Handoff path is required.";
-		}
-	});
-	if (isCancel(handoffPathPrompt)) {
-		cancel("No key created.");
-		return 0;
-	}
-	const appName = appNamePrompt.trim();
-	const allowedOrigin = normalizeHttpOrigin(allowedOriginPrompt);
-	const handoffPath = handoffPathPrompt.trim();
-	const shouldCreate = await confirm({
-		message: `Create a test publishable key for ${appName}?`,
-		initialValue: true
-	});
-	if (isCancel(shouldCreate) || shouldCreate === false) {
+	if (isCancel(originPrompt)) {
 		cancel("No key created.");
 		return 0;
 	}
+	const origin = normalizeHttpOrigin(originPrompt);
+	const baseUrl = process.env.CAPXUL_QUICKSTART_URL ?? "https://little-sandpiper-974.convex.site";
+	const envPath = resolve(process.cwd(), ".env.local");
 	const s = spinner();
-	s.start("Creating developer application and test publishable key");
+	s.start("Requesting a sandbox publishable key");
 	try {
-		const operatorEnv = loadOperatorEnv();
-		const result = await mintNextjsQuickstartKey({
-			env: operatorEnv,
-			...CANONICAL_QUICKSTART_DEPLOYMENT,
-			appName,
-			allowedOrigin,
-			handoffPath,
-			environment: "test",
-			pushBackend: false
-		}, {
-			packageVersion: bundledPackageVersion,
-			runConvex: canonicalConvexRunner(operatorEnv)
+		const result = await runQuickstart({ origin }, {
+			baseUrl,
+			fetch: globalThis.fetch,
+			readEnvFile: async () => {
+				try {
+					return await readFile(envPath, "utf8");
+				} catch {
+					return null;
+				}
+			},
+			writeEnvFile: (contents) => writeFile(envPath, contents, { mode: 384 }),
+			log: () => {}
 		});
-		s.stop("Publishable key captured in secure handoff");
+		s.stop("Publishable key written to .env.local");
 		note([
-			`Handoff: ${result.handoffPath}`,
-			`Application id: ${result.applicationId}`,
-			`Key id: ${result.keyId}`,
-			`Allowed origin: ${result.allowedOrigin}`,
-			`Capxul site URL: ${result.convexSiteUrl}`,
-			"Raw publishable key was not printed; copy it from the handoff file.",
-			"Before handoff, ensure CAPXUL_TRUSTED_ORIGINS and CORS_ALLOWED_ORIGINS include this origin."
-		].join("\n"), "Created");
+			"Wrote NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY and CAPXUL_SITE_URL to .env.local",
+			"(any other lines were preserved).",
+			`Key is scoped to: ${result.allowedOrigins.join(", ")}`
+		].join("\n"), "Written");
+		if (!isPretrustedQuickstartOrigin(origin)) note([
+			`The shared sandbox only completes email/OTP sign-in for its pre-trusted`,
+			`origins: ${PRETRUSTED_QUICKSTART_ORIGINS.join(", ")}.`,
+			``,
+			`${origin} will bootstrap, but sign-in requests are rejected until Capxul`,
+			`adds it. For the self-serve quickstart, run your app on a pre-trusted`,
+			`origin (for example http://localhost:3000).`
+		].join("\n"), "Origin not pre-trusted");
+		note(rewriteSnippet(), "Next steps");
 		outro("Done.");
 		return 0;
 	} catch (error) {

package/package.json

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