bsmnt 0.5.0 → 0.6.1

package/src/modules/features/env/dotenvx/files/save-key.mjs

@@ -0,0 +1,129 @@
+// Save the private key to 1Password (Development vault) and point .env's op-ref
+// at it, so teammates restore with `bun run env:setup`.
+//
+//   bun run env:save
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+
+const VAULT = "Development";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+// Write the op-ref into .env (it's a plaintext line, never encrypted).
+function setOpRef(ref) {
+  let content = existsSync(".env") ? readFileSync(".env", "utf-8") : "";
+  if (/^DOTENV_PRIVATE_KEY_OP_REF=.*$/m.test(content)) {
+    content = content.replace(
+      /^DOTENV_PRIVATE_KEY_OP_REF=.*$/m,
+      `DOTENV_PRIVATE_KEY_OP_REF=${ref}`,
+    );
+  } else {
+    if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+    content += `DOTENV_PRIVATE_KEY_OP_REF=${ref}\n`;
+  }
+  writeFileSync(".env", content);
+}
+
+// 1. Read the base private key from .env.keys.
+if (!existsSync(".env.keys")) {
+  fail("No .env.keys found — set up dotenvx (or run `bun run env:setup`) first.");
+}
+const keyMatch = readFileSync(".env.keys", "utf-8").match(
+  /^\s*DOTENV_PRIVATE_KEY\s*=\s*(.+?)\s*$/m,
+);
+const privateKey = keyMatch?.[1]?.replace(/^["']|["']$/g, "");
+if (!privateKey) fail("No DOTENV_PRIVATE_KEY found in .env.keys.");
+
+// 2. Require the 1Password CLI; offer to sign in if the session is missing.
+const whoami = spawnSync("op", ["whoami"], { stdio: "ignore" });
+if (whoami.error?.code === "ENOENT") {
+  fail("1Password CLI not found — install `op` and run `op signin` first.");
+}
+if (whoami.status !== 0) {
+  // Sign-in is interactive, so it needs a TTY.
+  if (!process.stdin.isTTY) {
+    fail("Not signed in to 1Password — run `op signin` first.");
+  }
+  console.error("Not signed in to 1Password — launching `op signin`…");
+  spawnSync("op", ["signin"], { stdio: "inherit" });
+  // CLI-only sign-in doesn't persist the session, so confirm it took.
+  const recheck = spawnSync("op", ["whoami"], { stdio: "ignore" });
+  if (recheck.status !== 0) {
+    fail("Still not signed in to 1Password — run `op signin` and retry.");
+  }
+}
+
+// 3. Prompt for the item title (default: package.json name) and an optional tag.
+if (!process.stdin.isTTY) fail("env:save is interactive — run it in a terminal.");
+let defaultTitle = "";
+try {
+  defaultTitle = JSON.parse(readFileSync("package.json", "utf-8")).name ?? "";
+} catch {
+  // no package.json name — leave the title prompt empty
+}
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const title =
+  (
+    await rl.question(
+      `1Password item title${defaultTitle ? ` [${defaultTitle}]` : ""}: `,
+    )
+  ).trim() || defaultTitle;
+const tag = (await rl.question("Tag (optional): ")).trim();
+rl.close();
+if (!title) fail("A title is required.");
+
+// 4. Refuse if an item with that title already exists in the vault.
+const existing = spawnSync("op", ["item", "get", title, "--vault", VAULT], {
+  stdio: "ignore",
+});
+if (existing.status === 0) {
+  fail(
+    `An item "${title}" already exists in ${VAULT} — rename or remove it first.`,
+  );
+}
+
+// 5. Create the item. The key is piped via a JSON template (stdin) so it never
+// lands in argv; category/title/tags are flags. `-` must be the first arg.
+const args = [
+  "item",
+  "create",
+  "-",
+  "--category",
+  "Secure Note",
+  "--title",
+  title,
+  "--vault",
+  VAULT,
+  "--format",
+  "json",
+];
+if (tag) args.push("--tags", tag);
+const template = {
+  fields: [{ label: "private-key", type: "CONCEALED", value: privateKey }],
+};
+const created = spawnSync("op", args, {
+  input: JSON.stringify(template),
+  encoding: "utf-8",
+  stdio: ["pipe", "pipe", "inherit"],
+});
+if (created.status !== 0) fail("\nFailed to create the 1Password item.");
+
+// 6. Reference the item by id (stable; survives renames), falling back to title.
+let itemRef = title;
+try {
+  const id = JSON.parse(created.stdout)?.id;
+  if (id) itemRef = id;
+} catch {
+  // non-JSON output — keep the title-based ref
+}
+const ref = `op://${VAULT}/${itemRef}/private-key`;
+setOpRef(ref);
+
+console.log(`\n✓ Saved to 1Password (${VAULT} / "${title}").`);
+console.log(`  Set DOTENV_PRIVATE_KEY_OP_REF=${ref} in .env.`);
+console.log("  Teammates can now restore with `bun run env:setup`.");

package/src/modules/features/env/dotenvx/files/setup-env.mjs

@@ -0,0 +1,67 @@
+// Restore .env.keys (dotenvx private decryption keys) from 1Password via `op`.
+// Store either the full .env.keys contents (recommended — covers every
+// environment) or just the DOTENV_PRIVATE_KEY value in a 1Password item field;
+// the reference lives in the committed .env (DOTENV_PRIVATE_KEY_OP_REF):
+//
+//   DOTENV_PRIVATE_KEY_OP_REF="op://Development/<item>/<field>" bun run env:setup
+//
+// `--auto` (run from the preinstall hook) is for onboarding: it never fails
+// `bun install` — it skips when .env.keys already exists, in CI, or when the
+// reference / `op` CLI is missing.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+
+const AUTO = process.argv.includes("--auto");
+
+// In --auto mode any unmet precondition exits 0 so the install never breaks.
+const stop = (msg) => {
+  console.error(msg);
+  process.exit(AUTO ? 0 : 1);
+};
+
+// Onboarding skips: nothing to do, or the wrong place to do it.
+if (AUTO && existsSync(".env.keys")) process.exit(0);
+if (AUTO && (process.env.CI || process.env.VERCEL)) process.exit(0);
+
+const OP_REF = process.env.DOTENV_PRIVATE_KEY_OP_REF;
+if (!OP_REF) {
+  stop(
+    "✗ set DOTENV_PRIVATE_KEY_OP_REF to the 1Password reference for .env.keys\n" +
+      '  e.g. DOTENV_PRIVATE_KEY_OP_REF="op://Development/<item>/<field>" bun run env:setup',
+  );
+}
+
+const res = spawnSync("op", ["read", OP_REF], { encoding: "utf8" });
+
+if (res.error) {
+  const why =
+    res.error.code === "ENOENT"
+      ? "install the 1Password CLI (`op`) and sign in — https://developer.1password.com/docs/cli/get-started/"
+      : res.error.message;
+  stop(`✗ failed to run \`op\`: ${why}`);
+}
+
+if (res.status !== 0) {
+  stop(`✗ \`op read\` failed:\n${res.stderr.trim()}`);
+}
+
+const HEADER = `#/------------------!DOTENV_PRIVATE_KEYS!-------------------/
+#/ private decryption keys. DO NOT commit to source control /
+#/     [how it works](https://dotenvx.com/encryption)       /
+#/          ⛨ ARMORED KEYS: \`dotenvx armor up\`              /
+#/----------------------------------------------------------/
+
+# .env
+`;
+
+const value = res.stdout.trim();
+
+// op may hold the full .env.keys file or just the bare private key. Pass full
+// contents through; wrap a bare key in the standard .env.keys format.
+const contents = value.includes("DOTENV_PRIVATE_KEY")
+  ? `${value}\n`
+  : `${HEADER}DOTENV_PRIVATE_KEY=${value}\n`;
+
+writeFileSync(".env.keys", contents);
+console.info("✓ wrote .env.keys from 1Password");

package/src/modules/features/env/dotenvx/files/vercelignore

@@ -0,0 +1,4 @@
+# Never upload the private keys or local env files on `vercel deploy`.
+# (Encrypted .env / .env.production / .env.preview ARE uploaded — they're safe.)
+.env.keys
+.env*.local

package/src/modules/features/env/dotenvx/files/write-env.mjs

@@ -0,0 +1,47 @@
+// Add or (re)encrypt env values without remembering the dotenvx flags.
+//
+//   bun run env:set KEY value          # encrypt one value into .env
+//   bun run env:set KEY value --plain  # store it plaintext (e.g. NEXT_PUBLIC_*)
+//   bun run env:set KEY value --prod   # target .env.production (--preview too)
+//   bun run env:encrypt-all            # bulk-encrypt every plaintext value in .env
+//   bun run env:encrypt-all --prod     # bulk-encrypt .env.production
+
+import { spawnSync } from "node:child_process";
+
+const [mode, ...rest] = process.argv.slice(2);
+
+// --prod / --preview pick the per-environment file; default is the shared .env.
+const ENV_FLAGS = new Set(["--prod", "--production", "--preview"]);
+const file =
+  rest.includes("--prod") || rest.includes("--production")
+    ? ".env.production"
+    : rest.includes("--preview")
+      ? ".env.preview"
+      : ".env";
+
+// On bulk encrypt, keep browser-public NEXT_PUBLIC_* and the 1Password pointer
+// plaintext (same exclusions the scaffold uses).
+const EXCLUDE = ["--exclude-key", "DOTENV_PRIVATE_KEY_OP_REF", "NEXT_PUBLIC_*"];
+
+function run(args) {
+  // `dotenvx` resolves from node_modules/.bin when run via `bun run`.
+  const res = spawnSync("dotenvx", args, { stdio: "inherit" });
+  process.exit(res.status ?? 1);
+}
+
+if (mode === "encrypt") {
+  run(["encrypt", "-f", file, ...EXCLUDE]);
+} else if (mode === "set") {
+  // Forward KEY, value and any dotenvx flags (e.g. --plain) straight through.
+  const passthrough = rest.filter((arg) => !ENV_FLAGS.has(arg));
+  if (passthrough.filter((arg) => !arg.startsWith("-")).length < 2) {
+    console.error(
+      "Usage: bun run env:set KEY value [--plain] [--preview|--prod]",
+    );
+    process.exit(1);
+  }
+  run(["set", ...passthrough, "-f", file]);
+} else {
+  console.error(`Unknown env command: ${mode ?? "(none)"} (use set | encrypt)`);
+  process.exit(1);
+}

package/src/templates/next-default/.env.example

@@ -1,11 +1,19 @@
 # ============================================
 # Basement Next Starter - Environment Variables
 # ============================================
-# Copy this file to .env.local and fill in the values
-# Run: cp .env.example .env.local
+# This project uses dotenvx (https://dotenvx.com): the committed `.env` holds
+# shared values, with secrets encrypted there. The private keys live in
+# `.env.keys` (gitignored) — restore them with `bun run env:setup`.
 #
-# Only configure the integrations you need.
-# Remove unused sections to keep your env file clean.
+# Add or change a variable in `.env` (not .env.local):
+#   - Secret (API key, token, …):  bun run env:set KEY value   (--preview / --prod)
+#   - Trivial / NEXT_PUBLIC_*:      bun run env:set KEY value --plain
+#   - Bulk-encrypt a file edited by hand:  bun run env:encrypt-all  (--preview / --prod)
+#
+# Edge runtime (middleware, `runtime = "edge"`): dotenvx can't decrypt there.
+# Set any secret those read directly in Vercel's env vars, not here.
+#
+# This file just documents the available variables; real values live in `.env`.
 # ============================================
 
 
@@ -16,7 +24,7 @@
 # Base URL for your site (used for SEO, canonical URLs, etc.)
 # Development: http://localhost:3000
 # Production: https://your-domain.com
-NEXT_PUBLIC_BASE_URL="http://localhost:3000"
+NEXT_PUBLIC_BASE_URL=""
 
 # Draft mode secret for preview functionality
 # Generate a random string: openssl rand -base64 32
@@ -32,7 +40,7 @@ DRAFT_MODE_TOKEN=""
 
 # Required for Sanity
 NEXT_PUBLIC_SANITY_PROJECT_ID=""
-NEXT_PUBLIC_SANITY_DATASET="production"
+NEXT_PUBLIC_SANITY_DATASET=""
 NEXT_PUBLIC_SANITY_API_READ_TOKEN=""
 
 # Optional - for server-side mutations and visual editing

package/src/templates/next-default/.github/workflows/ci.yml

@@ -46,8 +46,29 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      # dotenvx needs the private key to decrypt secrets at build time. It's
+      # pulled from 1Password via an org-wide service-account token + the op-ref
+      # committed in .env. Optional: builds pass without it (only plaintext /
+      # NEXT_PUBLIC_* is read), and a per-repo DOTENV_PRIVATE_KEY secret still
+      # works as a fallback.
+      - name: Install 1Password CLI
+        if: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN != '' }}
+        uses: 1password/install-cli-action@v1
+
       - name: Build
-        run: bun run build
+        env:
+          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+          DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
+        run: |
+          if [ -n "$OP_SERVICE_ACCOUNT_TOKEN" ]; then
+            ref="$(grep -m1 '^DOTENV_PRIVATE_KEY_OP_REF=' .env | cut -d= -f2-)"
+            if [ -n "$ref" ]; then
+              DOTENV_PRIVATE_KEY="$(op read "$ref")"
+              echo "::add-mask::$DOTENV_PRIVATE_KEY"
+              export DOTENV_PRIVATE_KEY
+            fi
+          fi
+          bun run build
 
       # Runs your tests if any exist; a fresh project with none passes cleanly.
       - name: Test

package/src/templates/next-default/.vscode/extensions.json

@@ -10,6 +10,9 @@
     // Sanity CMS (GROQ syntax + validation)
     "sanity-io.vscode-sanity",
 
+    // Env (dotenvx — view decrypted .env values inline)
+    "dotenv.dotenvx-vscode",
+
     // DX Enhancements
     "yoavbls.pretty-ts-errors"
   ]

package/src/templates/next-default/README.md

@@ -22,6 +22,35 @@ bun dev
 | `bun format` | Format the codebase |
 | `bun typecheck` | Run TypeScript |
 | `bun analyze` | Analyze the Next.js bundle |
+| `bun env:set KEY value` | Encrypt one value into `.env` (`--plain`, `--preview`/`--prod`) |
+| `bun env:encrypt-all` | Bulk-encrypt every plaintext value in a file (`--preview`/`--prod`) |
+| `bun env:setup` | Restore `.env.keys` from 1Password |
+| `bun env:view` | Print the decrypted `.env` (`--preview` / `--prod`) |
+| `bun env:setup-remote` | Push private keys to GitHub / Vercel (`github`/`vercel`, or pick) |
+| `bun env:save` | Save the private key to 1Password (Development vault) |
+
+## Environment variables
+
+Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed `.env` holds encrypted values, the private keys live in `.env.keys` (gitignored), and dev/build run through `dotenvx run` so values decrypt automatically.
+
+**First run.** `bun install` restores `.env.keys` from 1Password (via `DOTENV_PRIVATE_KEY_OP_REF` in `.env`), or run `bun run env:setup`. Needs 1Password access + the `op` CLI:
+
+- macOS: `brew install --cask 1password-cli`
+- Windows: `winget install 1password-cli`
+- Linux / other: [1Password CLI docs](https://developer.1password.com/docs/cli/get-started/)
+
+**Add or change a variable** (in `.env`):
+
+- Secret: `bun run env:set KEY value` (`--preview`/`--prod` to target an environment)
+- Public / `NEXT_PUBLIC_*`: `bun run env:set KEY value --plain`
+- Bulk-encrypt a hand-edited file: `bun run env:encrypt-all`
+- Inspect: `bun run env:view` (`--preview`/`--prod`)
+
+**Per environment.** Scripts load `.env.$VERCEL_ENV` over `.env`. After adding a per-env file, push its key with `bun run env:setup-remote vercel` — `instrumentation.ts` uses it to decrypt at runtime.
+
+**Edge runtime.** dotenvx decrypts only in the Node runtime; secrets read in `middleware.ts` or a `runtime = "edge"` route must be set as plain Vercel env vars.
+
+A gitleaks pre-commit hook + CI scan block committed plaintext secrets (install: `brew install gitleaks`).
 
 ## Project Structure
 
@@ -60,6 +89,8 @@ The workflow takes its runtime versions from your manifests, so there's a single
 
 It also caches Bun's install cache between runs, and the test step is a no-op until you add real test files.
 
+The build decrypts the committed `.env` with the dotenvx private key, pulled from 1Password: set an **org-level** `OP_SERVICE_ACCOUNT_TOKEN` (a read-only [service account](https://developer.1password.com/docs/service-accounts/) scoped to the `Development` vault) — one secret for every repo — and CI reads the key via the op-ref committed in `.env`. A per-repo `DOTENV_PRIVATE_KEY` secret (`bun run env:setup-remote github`) works as a fallback; builds pass without either (only plaintext / `NEXT_PUBLIC_*` is read).
+
 ### Branch protection
 
 To block merges when CI fails, enable branch protection on `main`: