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

package/README.md

@@ -0,0 +1,42 @@
+# 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 public quickstart endpoint and needs no operator secret.
+`faucet send` invokes the canonical Convex deployment and requires operator
+configuration from `~/.config/capxul/secrets.env`; 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

@@ -2,10 +2,11 @@
 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 { existsSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } 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);
@@ -278,16 +279,12 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports.populate = DotenvModule.populate;
 	module.exports = DotenvModule;
 })))();
-const backendRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
-const repoRoot = resolve(backendRoot, "..", "..");
+resolve(resolve(fileURLToPath(new URL("..", import.meta.url))), "..", "..");
 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"
+	deployment: "prod:little-sandpiper-974",
+	convexUrl: "https://little-sandpiper-974.convex.cloud",
+	convexSiteUrl: "https://little-sandpiper-974.convex.site"
 };
 function loadOperatorEnv(sourceEnv = process.env) {
 	const env = { ...sourceEnv };
@@ -305,11 +302,6 @@ function loadOperatorEnv(sourceEnv = process.env) {
 	env.CAPXUL_E2E_ORIGIN ||= env.CAPXUL_E2E_BOOTSTRAP_URL || env.SITE_URL;
 	return env;
 }
-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 normalizeHttpOrigin(raw) {
 	const value = raw.trim();
 	if (value.length === 0) throw new Error("Origin is required.");
@@ -324,42 +316,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 +323,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 +367,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);
@@ -732,30 +549,122 @@ async function runFaucetSend() {
 		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 +673,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.3",
   "private": false,
   "description": "Capxul sandbox CLI for canonical quickstart keys and testnet faucet funds.",
   "keywords": [