@suluk/platform 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "The platform generator (C051): write one `definePlatform` manifest → it plans the shadcn-registry adds, generates the wired Hono entry, and merges each module's provision fragment into a single provision.config. The manifest compiles to a shadcn-add list + a C047 provision.config; the generator runs the adds + `@suluk/provision`. Turns the Suluk backend registry into a one-command platform. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"

package/src/catalog.ts

@@ -29,7 +29,7 @@ export const CATALOG: Record<string, CatalogEntry> = Object.fromEntries(Object.e
 export const BASE_DEPS = ["@suluk/platform", "@suluk/provision", "@suluk/core", "@suluk/env", "effect", "hono", "drizzle-orm"];
 
 /** Pinned ranges for the NON-@suluk ecosystem deps — the single place they're kept current for every generated app.
- *  @suluk/* are NOT here: they resolve to "latest" so a package fix flows to the app via `bun update` (the C052 payoff). */
+ *  `@suluk/*` are NOT here: they resolve to "latest" so a package fix flows to the app via `bun update` (the C052 payoff). */
 export const ECOSYSTEM_VERSIONS: Record<string, string> = {
   "better-auth": "^1.0.0",
   "@better-auth/api-key": "^1.0.0",

package/src/generate.ts

@@ -59,6 +59,9 @@ export async function generatePlatform(input: PlatformManifest | Platform, opts:
     ["src/env.ts", plan.envTs, true], // the @suluk/env declare-once (derived from the manifest's secrets)
     ["scripts/sync-secrets.ts", plan.syncSecrets, true], // the deploy-time secret push (derived)
     ["scripts/link-key.ts", plan.linkKey, true], // register the private key into ~/.suluk/settings.json (the central store)
+    ["scripts/provision.ts", plan.provisionScript, true], // the credential lifecycle (source .env.temp/.env → provision → seal)
+    ["scripts/mint-tokens.ts", plan.mintTokens, true], // mint scoped least-privilege CF tokens from the master
+    [".env.temp", plan.envTemp, false], // the PLAINTEXT provisioning bootstrap — SCAFFOLD IF ABSENT (gitignored; consumed by provision)
     [".env", plan.envScaffold, false], // the COMMITTED encrypted-secrets file — SCAFFOLD IF ABSENT (never clobber secrets)
   ] as const) {
     if (always || (await read(file)) == null) {

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @suluk/platform — the platform generator (C051). Write one `definePlatform` manifest; the generator plans the
+ * `@suluk/platform` — the platform generator (C051). Write one `definePlatform` manifest; the generator plans the
  * shadcn-registry adds, generates the wired Hono entry, and merges each module's provision fragment into a single
  * provision.config. The higher-level surface over C047's provision.config + the C050 registry: `services: ["auth",
  * "credits", "billing"]` → a whole backend. The generated `provision.config.ts` imports `mergeProvision` from here.

package/src/plan.ts

@@ -39,6 +39,13 @@ export interface PlatformPlan {
   /** the generated `scripts/link-key.ts` — register the private key into the centralized `~/.suluk/settings.json` (the store
    *  `@suluk/env` reads by default for local dev/deploy/CI), the toolfactory model. */
   linkKey: string;
+  /** the generated `.env.temp` SCAFFOLD — the PLAINTEXT bootstrap for `bun run provision` (gitignored; consumed + deleted). */
+  envTemp: string;
+  /** the generated `scripts/provision.ts` — the credential lifecycle: source `.env.temp`/`.env` → provision → mint scoped
+   *  tokens → encrypt keepers → DELETE the ephemeral master token → stage the encrypted `.env`. */
+  provisionScript: string;
+  /** the generated `scripts/mint-tokens.ts` — mint scoped least-privilege CF tokens from the master, encrypted into `.env`. */
+  mintTokens: string;
   /** the generated `.env` SCAFFOLD (committed) — a header + the setup steps, NO values. `generate` writes it only if absent
    *  (never clobbering the operator's encrypted secrets). Secret VALUES are added encrypted via `suluk-env set`. */
   envScaffold: string;
@@ -75,6 +82,9 @@ export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
     envTs: buildEnvTs(env),
     syncSecrets: buildSyncSecrets(),
     linkKey: buildLinkKey(),
+    envTemp: buildEnvTemp(env),
+    provisionScript: buildProvisionScript(env),
+    mintTokens: buildMintTokens(env),
     envScaffold: buildEnvScaffold(env),
   };
 }
@@ -85,22 +95,23 @@ const secretsOf = (env: EnvVar[]): EnvVar[] => env.filter((e) => e.secret);
 /** The SECRET env keys → `.env.example` (required uncommented `KEY=`, optional commented `# KEY=`), each with its hint.
  *  Non-secret config is NOT here — it's in the manifest `vars` → wrangler `[vars]`. Safe to commit (no values). */
 function buildEnvExample(env: EnvVar[]): string {
-  const secrets = env.filter((e) => e.secret);
-  const line = (e: EnvVar, commented: boolean) => `${commented ? "# " : ""}${e.name}=${e.hint ? `        # ${e.hint}` : ""}`;
-  const required = secrets.filter((e) => e.required);
-  const optional = secrets.filter((e) => !e.required);
+  const line = (e: EnvVar) => `${e.name}=${e.hint ? `        # ${e.hint}` : ""}`;
+  const provisioning = provisioningOf(env).filter((e) => !e.minted); // the master + account id (the raw inputs)
+  const minted = env.filter((e) => e.minted); // the scoped tokens the mint step creates
+  const runtime = runtimeSecretsOf(env);
   return [
-    "# .env keys checklist (generated). The `.env` is COMMITTED with these values ENCRYPTED (@suluk/env, ML-KEM-768):",
-    "#   bunx suluk-env keygen                 # once — keypair (SULUK_PUBLIC_KEY → .env; private → .env.keys)",
-    "#   bun run link-key                      # register the private key in ~/.suluk/settings.json (@suluk/env reads it by default)",
-    "#   bunx suluk-env set KEY=value          # per secret — encrypts it into .env",
-    "# Non-secret config lives in platform.config.ts `vars` (→ wrangler.toml [vars]), NOT here.",
+    "# Secret keys checklist (generated). SETUP: fill `.env.temp` (plaintext) → `bun run provision`. It creates the keypair,",
+    "# provisions infra, mints the scoped tokens, ENCRYPTS the keepers into the COMMITTED `.env` (@suluk/env ML-KEM-768), and",
+    "# DELETES the ephemeral CF master token. Non-secret config lives in platform.config.ts `vars` (→ wrangler.toml [vars]).",
     "",
-    "# Required — the app won't start without these:",
-    ...required.map((e) => line(e, false)),
+    "# PROVISIONING creds — supply in .env.temp (plaintext). The master is EPHEMERAL (deleted after minting; never committed):",
+    ...provisioning.map(line),
     "",
-    "# Optional:",
-    ...optional.map((e) => line(e, true)),
+    "# Scoped least-privilege tokens — MINTED by `bun run provision`/`mint-tokens` (you don't supply these); kept encrypted:",
+    ...minted.map((e) => `# ${line(e)}`),
+    "",
+    "# RUNTIME secrets — supply in .env.temp; encrypted into .env + shipped to the Worker:",
+    ...runtime.map((e) => (e.required ? line(e) : `# ${line(e)}`)),
     "",
   ].join("\n");
 }
@@ -112,8 +123,9 @@ function buildEnvExample(env: EnvVar[]): string {
  */
 function buildEnvTs(env: EnvVar[]): string {
   const secrets = secretsOf(env);
+  const surface = (e: EnvVar): string => (e.provisioning || e.minted || e.surface === "local" ? '["local"]' : '["cloudflare"]');
   const spec = secrets
-    .map((e) => `  ${e.name}: { secret: true, ${e.required ? "required: true, " : ""}surfaces: ["cloudflare"]${e.hint ? `, description: ${JSON.stringify(e.hint)}` : ""} },`)
+    .map((e) => `  ${e.name}: { secret: true, ${e.required ? "required: true, " : ""}surfaces: ${surface(e)}${e.hint ? `, description: ${JSON.stringify(e.hint)}` : ""} },`)
     .join("\n");
   return [
     "// AUTO-GENERATED by @suluk/platform — the @suluk/env declare-once for this app's SECRETS. Values live ENCRYPTED in the",
@@ -134,15 +146,29 @@ function buildEnvTs(env: EnvVar[]): string {
  */
 function buildSyncSecrets(): string {
   return `#!/usr/bin/env bun
-// AUTO-GENERATED by @suluk/platform. Push the committed, @suluk/env-encrypted secrets to the Worker as \`wrangler secret\`s.
-// Run at deploy: \`bun run sync-secrets\`. Needs the private key (.env.keys / ~/.suluk / SULUK_PRIVATE_KEY) + a CF-authed wrangler.
-import { loadEnvFile } from "@suluk/env/node";
+// AUTO-GENERATED by @suluk/platform. Push the DECRYPTION key to the Worker (so src/index.ts's loadEnv decrypts the committed
+// .env at runtime), and optionally each runtime secret directly. Run at deploy: \`bun run sync-secrets\` (needs a deployed
+// Worker + a CF-authed wrangler; the private key comes from ~/.suluk/settings.json).
+import { loadEnvFile, readPrivateKey } from "@suluk/env/node";
 import { env } from "../src/env";
 
+const put = async (name: string, value: string) => {
+  const p = Bun.spawn(["bunx", "wrangler", "secret", "put", name], { stdin: "pipe", stdout: "inherit", stderr: "inherit" });
+  p.stdin.write(value); await p.stdin.end();
+  if ((await p.exited) !== 0) { console.error(\`✗ failed to put \${name}\`); process.exit(1); }
+  console.log(\`✓ \${name}\`);
+};
+
+// 1. the DECRYPTION key — the Worker's loadEnv decrypts the committed .env with it (the primary runtime path).
+const priv = readPrivateKey();
+if (!priv) { console.error("✗ no private key (~/.suluk/settings.json / SULUK_PRIVATE_KEY) — run \`bun run link-key\`"); process.exit(1); }
+await put("SULUK_PRIVATE_KEY", priv);
+
+// 2. (optional, belt-and-suspenders) push each cloudflare-surfaced runtime secret directly too.
 const values = await loadEnvFile(); // decrypt every value in .env into a { KEY: value } record
 const names = env.forSurface("cloudflare").filter((k) => values[k] !== undefined && values[k] !== "");
 if (!names.length) {
-  console.log("no cloudflare-surfaced secrets are set in .env yet — run \`bunx suluk-env set KEY=value\` first.");
+  console.log("✓ synced SULUK_PRIVATE_KEY (no cloudflare-surfaced runtime secrets set yet).");
   process.exit(0);
 }
 for (const name of names) {
@@ -193,6 +219,139 @@ console.log(\`✓ linked \${name} → \${settingsPath}. You can now \\\`rm .env.
 `;
 }
 
+/** the app's PROVISIONING creds (surface "local" — used to stand up + deploy, never shipped to the Worker). */
+const provisioningOf = (env: EnvVar[]): EnvVar[] => env.filter((e) => e.provisioning || e.minted || e.surface === "local");
+/** the ephemeral provisioning creds (the CF master token) — DELETED after provisioning, never committed. */
+const ephemeralOf = (env: EnvVar[]): EnvVar[] => env.filter((e) => e.provisioning);
+/** the RUNTIME secrets (surface "cloudflare") — encrypted in the committed .env + reach the Worker. */
+const runtimeSecretsOf = (env: EnvVar[]): EnvVar[] => secretsOf(env).filter((e) => !e.provisioning && !e.minted && e.surface !== "local");
+
+/**
+ * `.env.temp` — the PLAINTEXT bootstrap (gitignored). The operator drops the raw provisioning creds (+ the runtime secrets)
+ * here; `bun run provision` CONSUMES it (stages the values into `.env`, encrypts the keepers, DELETES the ephemeral master
+ * token, then deletes `.env.temp`). `generate` writes this scaffold only if absent. NEVER committed.
+ */
+function buildEnvTemp(env: EnvVar[]): string {
+  const line = (e: EnvVar) => `${e.name}=        # ${e.hint ?? ""}`;
+  return [
+    "# .env.temp — PLAINTEXT bootstrap for `bun run provision`. Gitignored; consumed + DELETED after provisioning.",
+    "# Fill in the raw values, then run `bun run provision` (it encrypts the keepers into .env + deletes this file + the",
+    "# ephemeral CF master token). The DECRYPTION key is generated for you (→ ~/.suluk/settings.json + the Worker).",
+    "",
+    "# Provisioning creds (used to create infra + mint scoped tokens; the master is DELETED, never committed):",
+    ...provisioningOf(env).filter((e) => !e.minted).map(line),
+    "",
+    "# Runtime secrets (encrypted into .env + committed; shipped to the Worker):",
+    ...runtimeSecretsOf(env).map(line),
+    "",
+  ].join("\n");
+}
+
+/**
+ * `scripts/mint-tokens.ts` — mint the scoped least-privilege CF tokens from the master (toolfactory's model), each encrypted
+ * straight into `.env` via `suluk-env set`. Idempotent (skips a token already set). The value is never printed.
+ */
+function buildMintTokens(env: EnvVar[]): string {
+  const minted = env.filter((e) => e.minted);
+  // map each minted token → the CF permission-group name(s) its hint implies (the operator can refine in the CF dashboard).
+  const groups: Record<string, string[]> = {
+    CLOUDFLARE_D1_TOKEN: ["D1 Write"],
+    CLOUDFLARE_WORKERS_TOKEN: ["Workers Scripts Write"],
+    CLOUDFLARE_KV_TOKEN: ["Workers KV Storage Write"],
+  };
+  const specs = minted.map((e) => `  { name: ${JSON.stringify(e.name)}, groups: ${JSON.stringify(groups[e.name] ?? ["Workers Scripts Write"])} },`).join("\n");
+  return `#!/usr/bin/env bun
+// AUTO-GENERATED by @suluk/platform. Mint scoped least-privilege CF tokens FROM the master (CLOUDFLARE_API_TOKEN), each
+// stored ENCRYPTED in .env via \`suluk-env set\`. Routine deploy/migrate then use these, not the master. Idempotent.
+import { setVar, loadEnvFile, rawEnvRecord } from "@suluk/env/node";
+
+await loadEnvFile({ override: true });
+const token = process.env.CLOUDFLARE_API_TOKEN, acct = process.env.CLOUDFLARE_ACCOUNT_ID;
+if (!token || !acct) { console.error("✗ CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID required (put them in .env.temp, run \`bun run provision\`)"); process.exit(1); }
+
+const SCOPED = [
+${specs}
+];
+// resolve the CF permission-group ids once (POST /accounts/{id}/tokens needs ids, not names).
+const pgRes = await fetch("https://api.cloudflare.com/client/v4/user/tokens/permission_groups", { headers: { Authorization: \`Bearer \${token}\` } });
+const pg = (await pgRes.json()) as { result?: Array<{ id: string; name: string }> };
+const idOf = (name: string) => pg.result?.find((g) => g.name === name)?.id;
+
+const have = rawEnvRecord();
+for (const s of SCOPED) {
+  if (have[s.name]) { console.log(\`– skip \${s.name} (already set)\`); continue; }
+  const permission_groups = s.groups.map((n) => ({ id: idOf(n) })).filter((g) => g.id);
+  const res = await fetch(\`https://api.cloudflare.com/client/v4/accounts/\${acct}/tokens\`, {
+    method: "POST",
+    headers: { Authorization: \`Bearer \${token}\`, "Content-Type": "application/json" },
+    body: JSON.stringify({ name: \`\${s.name.toLowerCase()}\`, policies: [{ effect: "allow", resources: { [\`com.cloudflare.api.account.\${acct}\`]: "*" }, permission_groups }] }),
+  });
+  const out = (await res.json()) as { success?: boolean; result?: { value?: string }; errors?: unknown };
+  if (!out.success || !out.result?.value) { console.error(\`✗ mint \${s.name}: \${JSON.stringify(out.errors)}\`); process.exit(1); }
+  await setVar(s.name, out.result.value); // encrypted into .env; never printed
+  console.log(\`✓ minted \${s.name}\`);
+}
+console.log("✓ scoped tokens ready (encrypted in .env).");
+`;
+}
+
+/**
+ * `scripts/provision.ts` — the credential lifecycle (the encrypted-commit model): source the raw creds from `.env.temp`
+ * (plaintext, first run — CONSUMED + deleted) OR the already-encrypted `.env`; ensure a keypair centralized in
+ * `~/.suluk/settings.json`; stand up the infra; mint scoped tokens; ENCRYPT the keepers into `.env`; DELETE the ephemeral
+ * master token (never committed); stage the encrypted `.env`. `bun run deploy` then ships the Worker + the decryption key.
+ */
+function buildProvisionScript(env: EnvVar[]): string {
+  const ephemeral = ephemeralOf(env).map((e) => e.name);
+  return `#!/usr/bin/env bun
+// AUTO-GENERATED by @suluk/platform — stand up the infra + SEAL the secrets (@suluk/env encrypted-commit model). Run once
+// after filling .env.temp (or with an existing encrypted .env). Idempotent.
+import { existsSync, rmSync, readFileSync, writeFileSync } from "node:fs";
+import { loadEnvFile, setVar } from "@suluk/env/node";
+
+const EPHEMERAL = ${JSON.stringify(ephemeral)}; // the CF master token(s): used to provision + mint, then DELETED (never committed)
+const sh = async (cmd: string, args: string[]) => { const p = Bun.spawn([cmd, ...args], { stdout: "inherit", stderr: "inherit" }); if ((await p.exited) !== 0) { console.error(\`✗ \${cmd} \${args.join(" ")}\`); process.exit(1); } };
+
+// 1. keypair → the central ~/.suluk/settings.json (the private key never stays in the repo).
+await Bun.spawn(["bunx", "suluk-env", "keygen"]).exited; // idempotent (nonzero if a key already exists)
+await sh("bun", ["run", "scripts/link-key.ts"]);
+rmSync(".env.keys", { force: true });
+
+// 2. source the raw creds: .env.temp (plaintext, first run) → stage into .env, then it's consumed; else the encrypted .env.
+if (existsSync(".env.temp")) {
+  for (const l of readFileSync(".env.temp", "utf8").split("\\n")) {
+    const m = l.match(/^\\s*([A-Z0-9_]+)\\s*=\\s*(.+)$/);
+    if (m && m[2].trim()) await setVar(m[1], m[2].trim().replace(/^["']|["']$/g, ""), { plain: true }); // stage plaintext (encrypted at step 5)
+  }
+}
+await loadEnvFile({ override: true }); // decrypt everything into process.env
+if (!process.env.CLOUDFLARE_API_TOKEN || !process.env.CLOUDFLARE_ACCOUNT_ID) { console.error("✗ CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID missing — put them in .env.temp"); process.exit(1); }
+
+// 3. provision the infra (D1/KV — the C047 provision.config), 4. mint the scoped least-privilege tokens from the master.
+await sh("bunx", ["suluk-provision", "apply"]);
+await sh("bun", ["run", "scripts/mint-tokens.ts"]);
+
+// 5. ENCRYPT every keeper value in .env in place (runtime secrets + account id + minted tokens).
+await sh("bunx", ["suluk-env", "encrypt"]);
+
+// 6. DELETE the ephemeral master token from .env (never committed) — routine ops use the minted scoped tokens.
+if (EPHEMERAL.length) {
+  const kept = readFileSync(".env", "utf8").split("\\n").filter((l) => { const m = l.match(/^\\s*([A-Z0-9_]+)\\s*=/); return !(m && EPHEMERAL.includes(m[1])); });
+  writeFileSync(".env", kept.join("\\n"));
+}
+// 7. consume the plaintext bootstrap + stage the encrypted .env.
+rmSync(".env.temp", { force: true });
+await sh("git", ["add", "-f", ".env"]);
+console.log("✓ provisioned + sealed: infra up, secrets encrypted in .env; the CF master token was removed from .env.");
+console.log("");
+console.log("⚠ REVOKE the master CF token in the dashboard now (https://dash.cloudflare.com/profile/api-tokens) — it minted the");
+console.log("  scoped least-privilege tokens and is no longer needed. Routine deploy/migrate use the minted tokens. To create new");
+console.log("  services / mint new tokens / teardown later, generate a FRESH master token, put it in .env.temp, re-run \`bun run provision\`.");
+console.log("");
+console.log("Next: \`bun run deploy\` (ships the Worker + pushes SULUK_PRIVATE_KEY so it decrypts the committed .env at runtime).");
+`;
+}
+
 /**
  * The `.env` SCAFFOLD — a header + setup steps, NO values (safe to commit). `generate` writes it ONLY IF ABSENT so it never
  * clobbers the operator's encrypted secrets. Its presence also lets `src/index.ts`'s `import "../.env"` resolve on a fresh app.
@@ -302,17 +461,18 @@ export function mergeGitignore(generated: string, existing: string | null): stri
 /** The encrypted-env preflight (run via `predev` / `bun run check`): is there a keypair, and is every REQUIRED secret set
  *  (encrypted) in the committed `.env`? A plaintext secret sitting in `.env` is flagged (encrypt it before you commit). */
 function buildEnvCheckScript(env: EnvVar[]): string {
-  const required = env.filter((e) => e.secret && e.required).map((e) => e.name);
+  // the required secrets that should be SET + ENCRYPTED in the committed .env after provisioning — the ephemeral master is
+  // EXCLUDED (it's deleted after provisioning, so its absence is correct).
+  const required = env.filter((e) => e.secret && e.required && !e.provisioning).map((e) => e.name);
   return `#!/usr/bin/env bun
 /**
- * AUTO-GENERATED by @suluk/platform — the ENCRYPTED-env preflight (wired as \`predev\` + \`bun run check\`). Secrets live in the
- * committed .env, ENCRYPTED with @suluk/env. This checks: a keypair exists, the REQUIRED secrets are set, and none is sitting
- * in plaintext (which must never be committed). Non-secret config is in platform.config.ts \`vars\` → wrangler.toml [vars].
+ * AUTO-GENERATED by @suluk/platform — the env preflight (wired as \`predev\` + \`bun run check\`). SETUP: fill \`.env.temp\`
+ * (plaintext) then \`bun run provision\`. This verifies the END STATE: a keypair exists, the required secrets are set +
+ * ENCRYPTED in the committed .env, and none is sitting in plaintext. Non-secret config is in platform.config.ts \`vars\`.
  */
 import { existsSync, readFileSync } from "node:fs";
 
 const REQUIRED = ${JSON.stringify(required)};
-const ENV = ".env";
 
 const parse = (p: string): Record<string, string> => {
   const out: Record<string, string> = {};
@@ -322,15 +482,17 @@ const parse = (p: string): Record<string, string> => {
   }
   return out;
 };
-
-const have = existsSync(ENV) ? parse(ENV) : {};
-const isEncrypted = (v: string) => v.startsWith("encrypted:");
 const fail = (msg: string) => { console.error("✗ " + msg); process.exit(1); };
 
-if (!have.SULUK_PUBLIC_KEY) fail("no @suluk/env keypair — run \`bunx suluk-env keygen\` (creates SULUK_PUBLIC_KEY in .env + .env.keys).");
+// a plaintext bootstrap is waiting to be consumed → provision it (encrypts the keepers, deletes the master).
+if (existsSync(".env.temp")) fail(".env.temp is present (plaintext) — run \`bun run provision\` to consume it (seals secrets into .env, deletes the master token).");
+
+const have = existsSync(".env") ? parse(".env") : {};
+const isEncrypted = (v: string) => v.startsWith("encrypted:");
+if (!have.SULUK_PUBLIC_KEY) fail("no keypair yet — fill .env.temp with your creds/secrets and run \`bun run provision\` (creates the keypair, provisions, seals secrets).");
 
 const missing = REQUIRED.filter((k) => !have[k] && !process.env[k]);
-if (missing.length) fail("missing required secret(s): " + missing.join(", ") + "\\n  → set each: bunx suluk-env set KEY=value");
+if (missing.length) fail("missing required secret(s) in .env: " + missing.join(", ") + "\\n  → add them to .env.temp + \`bun run provision\`, or \`bunx suluk-env set KEY=value\`");
 
 const plaintext = Object.keys(have).filter((k) => k !== "SULUK_PUBLIC_KEY" && have[k] && !isEncrypted(have[k]));
 if (plaintext.length) fail("PLAINTEXT secret(s) in .env (never commit these): " + plaintext.join(", ") + "\\n  → encrypt: bunx suluk-env encrypt");
@@ -360,7 +522,9 @@ export function buildPackageJson(name: string, services: string[], catalog: Reco
       "env:keygen": "suluk-env keygen", // create the @suluk/env keypair (SULUK_PUBLIC_KEY → .env; private → .env.keys)
       "link-key": "bun run scripts/link-key.ts", // register the private key in ~/.suluk/settings.json (the central store)
       "env:set": "suluk-env set", // encrypt + add a secret: `bun run env:set BETTER_AUTH_SECRET=...`
-      "sync-secrets": "bun run scripts/sync-secrets.ts", // decrypt cloudflare-surfaced secrets → `wrangler secret put` each
+      provision: "bun run scripts/provision.ts", // stand up infra + mint scoped tokens + seal secrets (consumes .env.temp)
+      "mint-tokens": "bun run scripts/mint-tokens.ts", // (re)mint the scoped least-privilege CF tokens from the master
+      "sync-secrets": "bun run scripts/sync-secrets.ts", // push SULUK_PRIVATE_KEY + runtime secrets to the Worker
       typecheck: "tsc --noEmit -p .",
       test: "bun test",
     },

package/src/service.ts

@@ -16,15 +16,30 @@ export type Mount =
   | { kind: "route"; path: string; symbol: string; from: string } // e.g. `app.route("/api/credits", creditsRoutes())`
   | { kind: "dev" }; // dev/CI tooling (journeys, audit) — files only, no runtime mount, no provision fragment
 
-/** An env var a module needs at runtime — drives the generated `.env.example` + the env-check preflight. (Unchanged.) */
+/** An env var a module (or the app's provisioning) needs — drives the generated `env.ts`, `.env.example`, `.env.temp`, the
+ *  env-check preflight, and the provision/sync-secrets scripts. */
 export interface EnvVar {
   name: string;
   /** the app WON'T work without it (the "minimum keys") — the env-check requires a non-empty value before it's happy. */
   required?: boolean;
-  /** a credential (never commit) — shown commented in `.env.example` + flagged in the temp file. */
+  /** a credential (encrypted at rest in the committed `.env`, or — if `provisioning` — staged plaintext in `.env.temp`). */
   secret?: boolean;
-  /** a one-line hint shown as a comment in `.env.example`. */
+  /** a one-line hint shown as a comment. */
   hint?: string;
+  /**
+   * Where the value is USED. `"cloudflare"` = a Worker RUNTIME secret (pushed by `sync-secrets` / decrypted by `loadEnv`);
+   * `"local"` = used only by provisioning/deploy on this machine, NEVER shipped to the Worker. Defaults: a `secret` → the
+   * Worker runtime (`"cloudflare"`); a `provisioning`/`minted` cred → `"local"`.
+   */
+  surface?: "local" | "cloudflare";
+  /**
+   * An EPHEMERAL provisioning credential (e.g. the Cloudflare API master token): supplied PLAINTEXT in `.env.temp`, used to
+   * provision infra + mint scoped tokens, then DELETED after provisioning — never committed (not even encrypted). Implies
+   * `surface: "local"`.
+   */
+  provisioning?: boolean;
+  /** a scoped least-privilege token MINTED during provisioning (from the master), then kept ENCRYPTED in `.env`. `surface: "local"`. */
+  minted?: boolean;
 }
 
 /** The old catalog record — now a DERIVED VIEW of a {@link Service} (see {@link toCatalogEntry}); kept so `planPlatform`
@@ -153,7 +168,22 @@ export function toCatalogEntry(s: Service): CatalogEntry {
 // Each core service is exported as a NAMED, precisely-typed const so a `defineSystem` author can import it and get typed
 // serviceOpts keyed by id. Ported field-for-field from the C051 CATALOG (byte-identity via the Phase-0 golden lock).
 
-export const appService = defineService({ id: "app", mount: { kind: "base" }, env: [{ name: "TRUSTED_ORIGINS", hint: "comma-separated browser origins allowed on /api/* (CORS)" }] });
+export const appService = defineService({
+  id: "app",
+  mount: { kind: "base" },
+  env: [
+    { name: "TRUSTED_ORIGINS", hint: "comma-separated browser origins allowed on /api/* (CORS)" },
+    // ── Cloudflare provisioning creds (surface "local" — used to stand up + deploy the infra, NEVER shipped to the Worker) ──
+    // The MASTER token is EPHEMERAL: supply it plaintext in .env.temp, it mints the scoped tokens below + provisions, then
+    // it's DELETED (never committed). Routine deploy/migrate then use the minted least-privilege tokens.
+    { name: "CLOUDFLARE_API_TOKEN", required: true, secret: true, provisioning: true, hint: "CF account-scoped master token (Workers Scripts + D1 + KV Edit) — mints the scoped tokens + provisions, then DELETED (never in git)" },
+    { name: "CLOUDFLARE_ACCOUNT_ID", required: true, secret: true, surface: "local", hint: "CF account id — a KEEPER (routine scoped-token ops need it), kept encrypted in .env" },
+    // Scoped least-privilege tokens minted from the master during provisioning; kept ENCRYPTED in .env for routine ops.
+    { name: "CLOUDFLARE_D1_TOKEN", secret: true, minted: true, hint: "scoped: D1 Write (migrations)" },
+    { name: "CLOUDFLARE_WORKERS_TOKEN", secret: true, minted: true, hint: "scoped: Workers Scripts Write (deploy + secret put)" },
+    { name: "CLOUDFLARE_KV_TOKEN", secret: true, minted: true, hint: "scoped: KV Write (rate-limit / rate-credit namespaces)" },
+  ],
+});
 
 export const authService = defineService({
   id: "auth",
@@ -250,7 +280,7 @@ export const rateLimitService = defineService({ id: "rate-limit", mount: { kind:
 export const rateCreditService = defineService({ id: "rate-credit", mount: { kind: "middleware", symbol: "mountRateCredit", from: "./services/rate-credit" } }); // credit-backed free-tier bucket (KV binding)
 export const i18nService = defineService({ id: "i18n", mount: { kind: "middleware", symbol: "mountI18n", from: "./services/i18n" }, deps: ["@suluk/i18n"] });
 export const referenceService = defineService({ id: "reference", mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" }, deps: ["@suluk/reference"] }); // derived — no provision
-export const adminService = defineService({ id: "admin", mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" }, deps: ["@suluk/credits"] }); // reads existing tables — no provision
+export const adminService = defineService({ id: "admin", mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" }, deps: ["@suluk/credits"], env: [{ name: "SUPERADMIN_EMAILS", secret: true, hint: "comma/space-separated admin emails → the admin scope (secret-surfaced so they stay out of git plaintext)" }] }); // reads existing tables — no provision
 export const logsService = defineService({ id: "logs", mount: { kind: "route", path: "/api/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } });
 export const journeysService = defineService({ id: "journeys", mount: { kind: "dev" }, deps: ["@suluk/journeys"] });
 export const auditService = defineService({ id: "audit", mount: { kind: "dev" }, deps: ["@suluk/cockpit", "@suluk/harden"] });