create-safest-tools 0.2.0 → 0.2.2

package/README.md

@@ -21,6 +21,10 @@ npx create-safest-tools safest-resolve \
 
 The `--email-from` address must belong to a domain onboarded under Cloudflare Email Service → Email Sending. Domain onboarding permits delivery to arbitrary invited users; invitations, email verification, and forgot-password delivery use this address.
 
+### Where to find the Cloudflare Access AUD
+
+In the Cloudflare dashboard, go to **Zero Trust → Access controls → Applications** and create a **Self-hosted and private** application named **Safest Resolve infrastructure**. Add the reports hostname with **Path** `v1/infrastructure/*` only; do not protect the entire hostname. Add or create a policy named **Safest infrastructure owners** with **Action: Allow** and an **Include → Emails** rule containing only the infrastructure-owner email supplied to `--admin-email`. Do not use **Everyone**. Create the application, select **Configure → Additional settings**, and copy the 64-character **Application Audience (AUD) Tag** into `--access-aud`. The tag stays the same unless the Access application is deleted or recreated. See Cloudflare's [application-path](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/app-paths/) and [Get your AUD tag](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#get-your-aud-tag) instructions.
+
 The command creates a local project and prints a read-only infrastructure plan. It does not change Cloudflare unless `--deploy` is supplied or the generated project’s `npm run setup` command is run and explicitly confirmed.
 
 The generated installation owns:
@@ -46,7 +50,7 @@ npm run setup:plan
 npm run setup
 ```
 
-`setup:plan` lists exact resource names and exits without modifying Cloudflare. `setup` opens Wrangler's Cloudflare login when needed, lets you choose the owning account, and fails closed unless it can verify an active Workers Paid subscription. It then guides Google, GitHub, and Cloudflare OAuth configuration with exact callback URLs and masked secret input. Nothing is provisioned until the exact `DEPLOY <installation-id>` confirmation.
+`setup:plan` lists exact resource names and exits without modifying Cloudflare. `setup` opens Wrangler's Cloudflare login when needed, lets you choose the owning account, and verifies Workers Paid from the account's Workers usage model. Standard accounts need no separate billing token; only legacy or ambiguous account models use the temporary Billing Read fallback. It then guides Google, GitHub, and Cloudflare OAuth configuration with exact callback URLs and masked secret input. Nothing is provisioned until the exact `DEPLOY <installation-id>` confirmation.
 
 Create a Cloudflare Access self-hosted application for `<reports-host>/v1/infrastructure/*` first and copy its 64-character audience into `reports.config.json`. The allowlisted infrastructure engineer uses it to bootstrap the Safest owner account. The owner then invites administrators, and administrators invite analysts. Those invited users sign in with Safest accounts and do not need Cloudflare accounts.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-safest-tools",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Create customer-owned abuse-reporting infrastructure on Cloudflare",
   "type": "module",
   "license": "Apache-2.0",

package/src/cli.mjs

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
@@ -6,7 +7,25 @@ import { buildConfiguration } from "./config.mjs";
 import { scaffoldProject, validateGeneratedConfiguration } from "./scaffold.mjs";
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const packageVersion = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")).version;
 const defaultTemplateDirectory = resolve(packageRoot, "template");
+const accessAudienceDocumentation = "https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#get-your-aud-tag";
+
+export function accessAudienceGuidance(publicBaseUrl = "", adminEmails = []) {
+  let reportsHost = "<reports-host>";
+  try { reportsHost = new URL(publicBaseUrl).host || reportsHost; } catch {}
+  const ownerEmail = adminEmails[0] || "<infrastructure-owner-email>";
+  return `Before entering the Cloudflare Access application AUD:
+  1. In Cloudflare, go to Zero Trust > Access controls > Applications.
+  2. Create a Self-hosted and private application named Safest Resolve infrastructure.
+  3. Add public hostname ${reportsHost} with Path v1/infrastructure/* only.
+  4. Add a policy named Safest infrastructure owners: Action Allow; Include Emails; Value ${ownerEmail}.
+     Do not select Everyone and do not protect the entire reporting hostname.
+  5. Create the application, then select Configure > Additional settings.
+  6. Copy the 64-character Application Audience (AUD) Tag.
+The tag stays the same unless you delete or recreate the Access application.
+Cloudflare guide: ${accessAudienceDocumentation}`;
+}
 
 function usage() {
   return `Create customer-owned abuse-reporting infrastructure on Cloudflare
@@ -32,6 +51,8 @@ Options:
   --help                 Show this help
   --version              Show the package version
 
+${accessAudienceGuidance()}
+
 This product does not proxy or inspect application requests. Applications submit
 reports explicitly through the widget, public form, or server API.
 `;
@@ -88,12 +109,15 @@ async function ask(input, prompt, fallback = "") {
   return answer || fallback;
 }
 
-async function completeInteractive(options, input) {
+async function completeInteractive(options, input, output) {
   options.installationName ||= await ask(input, "Installation name", "safest-resolve");
   options.publicBaseUrl ||= await ask(input, "Public reports origin", "https://reports.example.com");
   if (!options.allowedOrigins.length) options.allowedOrigins.push(await ask(input, "Application origin allowed to embed the report form", "https://app.example.com"));
   if (!options.adminEmails.length) options.adminEmails.push(await ask(input, "Infrastructure owner email"));
-  options.accessAudience ||= await ask(input, "Cloudflare Access application AUD (leave placeholder if it is not created yet)", "replace-with-the-cloudflare-access-application-aud");
+  if (!options.accessAudience) {
+    output.log(`\n${accessAudienceGuidance(options.publicBaseUrl, options.adminEmails)}\n`);
+    options.accessAudience = await ask(input, "Cloudflare Access application AUD (press Enter to use a deployment-blocking placeholder)", "replace-with-the-cloudflare-access-application-aud");
+  }
   options.emailFromAddress ||= await ask(input, "Sender address on a Cloudflare Email Sending domain");
   return options;
 }
@@ -102,11 +126,11 @@ export async function runCli(argv, dependencies = {}) {
   const output = dependencies.output ?? console;
   const options = parseArguments(argv);
   if (options.help) { output.log(usage()); return { status: "help" }; }
-  if (options.version) { output.log("0.2.0"); return { status: "version" }; }
+  if (options.version) { output.log(packageVersion); return { status: "version" }; }
   const interactive = dependencies.interactive ?? (process.stdin.isTTY && !options.yes);
   if (interactive) {
     const input = createInterface({ input: process.stdin, output: process.stdout });
-    try { await completeInteractive(options, input); } finally { input.close(); }
+    try { await completeInteractive(options, input, output); } finally { input.close(); }
   }
   const configuration = buildConfiguration(options);
   const templateDirectory = dependencies.templateDirectory ?? defaultTemplateDirectory;

package/template/README.md

@@ -9,9 +9,9 @@ This project deploys one Worker, one D1 database, four private R2 buckets, a Dyn
 Before deployment:
 
 1. Review `reports.config.json` and `npm run setup:plan`.
-2. Create a Cloudflare Access self-hosted application for `<reports-host>/v1/infrastructure/*`; put its 64-character AUD in `access.audience` and keep `access.ownerEmails` restricted to infrastructure owners.
+2. In Cloudflare, go to **Zero Trust → Access controls → Applications** and create a **Self-hosted and private** application named **Safest Resolve infrastructure**. Add the reports hostname with **Path** `v1/infrastructure/*` only; do not protect the entire hostname. Add a reusable policy named **Safest infrastructure owners** with **Action: Allow** and an **Include → Emails** rule containing only the email addresses in `access.ownerEmails`; do not use **Everyone**. Create the application, select **Configure → Additional settings**, and copy the 64-character **Application Audience (AUD) Tag** into `access.audience`. The tag stays stable unless the Access application is deleted or recreated. See Cloudflare's [application-path](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/app-paths/), [policy](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/policy-management/), and [Get your AUD tag](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#get-your-aud-tag) instructions.
 3. Under Cloudflare Email Service → Email Sending, onboard the configured sender domain. Password verification, invitations, and password recovery to arbitrary recipients depend on domain onboarding.
-4. Run `npm run setup`. The guided setup signs in through Wrangler, verifies Workers Paid before provisioning, creates owner-only local secrets, and walks through optional Google, GitHub, and Cloudflare OAuth credentials with exact callback URLs.
+4. Run `npm run setup`. The guided setup signs in through Wrangler and verifies Workers Paid from the account's Workers usage model before provisioning. Standard accounts need no separate billing token; only legacy or ambiguous models use the temporary Billing Read fallback. Setup then creates owner-only local secrets and walks through optional Google, GitHub, and Cloudflare OAuth credentials with exact callback URLs.
 5. Bootstrap the infrastructure owner, then invite administrators and analysts from People. Invited users do not need Cloudflare accounts and can upload a JPEG, PNG, or WebP profile picture up to 2 MB. Names and workspace roles are always displayed separately.
 6. Type the exact installation confirmation when setup requests it.
 

package/template/package.json

@@ -1,7 +1,7 @@
 {
   "name": "safest-resolve-installation",
-  "version": "0.2.0",
-  "safestToolsVersion": "0.2.0-resolve",
+  "version": "0.2.2",
+  "safestToolsVersion": "0.2.2-resolve",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/scripts/reports-cloudflare-preflight.mjs

@@ -3,11 +3,15 @@ import { spawn } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
-function runProcess(program, args, { cwd, inherit = false } = {}) {
+export function wranglerEnvironment(logLevel = "none", env = process.env) {
+  return { ...env, WRANGLER_LOG: logLevel, WRANGLER_WRITE_LOGS: "false" };
+}
+
+function runProcess(program, args, { cwd, inherit = false, wranglerLog = "none" } = {}) {
   return new Promise((resolvePromise, reject) => {
     const child = spawn(program, args, {
       cwd,
-      env: { ...process.env, WRANGLER_LOG: "none" },
+      env: wranglerEnvironment(wranglerLog),
       stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"],
     });
     let stdout = "";
@@ -51,10 +55,33 @@ async function fetchSubscriptions(accountId, token, fetchImpl) {
   return { ok: true, subscriptions: body.result };
 }
 
-async function billingTokenFromUser(account, ui) {
+async function fetchWorkersAccountSettings(accountId, token, fetchImpl) {
+  const response = await fetchImpl(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/workers/account-settings`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success !== true || !body.result || typeof body.result !== "object") {
+    return { ok: false, status: response.status, body };
+  }
+  return { ok: true, settings: body.result };
+}
+
+export function isWorkersPaidUsageModel(value) {
+  return String(value ?? "").trim().toLowerCase() === "standard";
+}
+
+function accountSettingsFailureDetail(verification) {
+  if (!verification.ok) return `the Workers account-settings request returned Cloudflare API ${verification.status}`;
+  const usageModel = String(verification.settings.default_usage_model ?? "").trim();
+  return usageModel
+    ? `Cloudflare reported the legacy or ambiguous usage model “${usageModel}”`
+    : "Cloudflare did not report a Workers usage model";
+}
+
+async function billingTokenFromUser(account, detail, ui) {
   ui.note(
-    `Wrangler is authenticated, but its OAuth grant cannot read billing subscriptions.\n\n` +
-      `Create a temporary read-only token for account “${account.name}”:\n` +
+    `Wrangler is authenticated, but ${detail}.\n\n` +
+      `Standard Workers Paid accounts need no additional token. For this legacy or ambiguous account, create a temporary read-only token for “${account.name}”:\n` +
       `1. Open https://dash.cloudflare.com/profile/api-tokens\n` +
       `2. Create a custom token.\n` +
       `3. Add Account → Billing → Read.\n` +
@@ -77,16 +104,23 @@ async function billingTokenFromUser(account, ui) {
   return clack.isCancel(token) ? null : token.trim();
 }
 
-export async function verifyWorkersPaid({ account, wranglerToken, interactive, fetchImpl = fetch, ui = clack }) {
-  let verification = await fetchSubscriptions(account.id, process.env.CLOUDFLARE_BILLING_API_TOKEN || wranglerToken, fetchImpl);
-  if (!verification.ok && (verification.status === 401 || verification.status === 403) && !process.env.CLOUDFLARE_BILLING_API_TOKEN) {
+export async function verifyWorkersPaid({ account, wranglerToken, interactive, fetchImpl = fetch, ui = clack, env = process.env }) {
+  const accountSettings = await fetchWorkersAccountSettings(account.id, wranglerToken, fetchImpl);
+  if (accountSettings.ok && isWorkersPaidUsageModel(accountSettings.settings.default_usage_model)) {
+    return { source: "workers-account-settings", label: "Workers Standard", usageModel: "standard" };
+  }
+
+  const detail = accountSettingsFailureDetail(accountSettings);
+  let billingToken = env.CLOUDFLARE_BILLING_API_TOKEN;
+  if (!billingToken) {
     if (!interactive) {
-      throw new Error("Workers Paid could not be verified. Set CLOUDFLARE_BILLING_API_TOKEN to a temporary Account Billing Read token and run setup again.");
+      throw new Error(`Workers Paid could not be verified because ${detail}. Set CLOUDFLARE_BILLING_API_TOKEN to a temporary Account Billing Read token and run setup again.`);
     }
-    const billingToken = await billingTokenFromUser(account, ui);
+    billingToken = await billingTokenFromUser(account, detail, ui);
     if (!billingToken) throw new Error("Setup cancelled before provisioning: Workers Paid was not verified.");
-    verification = await fetchSubscriptions(account.id, billingToken, fetchImpl);
   }
+
+  const verification = await fetchSubscriptions(account.id, billingToken, fetchImpl);
   if (!verification.ok) {
     throw new Error(`Workers Paid could not be verified for “${account.name}” (Cloudflare API ${verification.status}). No resources were provisioned.`);
   }
@@ -94,7 +128,11 @@ export async function verifyWorkersPaid({ account, wranglerToken, interactive, f
   if (!subscription) {
     throw new Error(`“${account.name}” does not have an active Workers Paid subscription. Upgrade it in Cloudflare, then run setup again. No resources were provisioned.`);
   }
-  return subscription;
+  return {
+    source: "billing-subscription",
+    label: subscription.rate_plan?.public_name ?? "active Workers subscription",
+    subscription,
+  };
 }
 
 export async function ensureWranglerAuthentication({ wrangler, projectRoot, interactive, ui = clack, runner = runProcess }) {
@@ -113,7 +151,10 @@ export async function ensureWranglerAuthentication({ wrangler, projectRoot, inte
   if (identity.loggedIn !== true || !Array.isArray(identity.accounts) || !identity.accounts.length) {
     throw new Error("Wrangler is authenticated but no accessible Cloudflare account was found.");
   }
-  const tokenResult = await runner(process.execPath, [wrangler, "auth", "token", "--json"], { cwd: projectRoot });
+  // Wrangler emits this JSON through its logger. `WRANGLER_LOG=none` suppresses
+  // the response in Wrangler 4.127+, so allow log output only for this captured
+  // command. Disable Wrangler's disk logs so the OAuth token stays in memory.
+  const tokenResult = await runner(process.execPath, [wrangler, "auth", "token", "--json"], { cwd: projectRoot, wranglerLog: "log" });
   const token = jsonOutput(tokenResult, "Wrangler token lookup");
   if (typeof token.token !== "string" || !token.token) throw new Error("Wrangler did not provide an API token for preflight checks.");
   return { identity, token: token.token };

package/template/scripts/reports-deploy.mjs

@@ -110,13 +110,13 @@ export async function deployReports(argv = process.argv.slice(2)) {
     wranglerConfigPath: resolve(projectRoot, "wrangler.jsonc"),
     interactive,
   });
-  const subscription = await verifyWorkersPaid({
+  const workersPlan = await verifyWorkersPaid({
     account: accountSelection.account,
     wranglerToken: authentication.token,
     interactive,
   });
   await saveCloudflareAccountSelection(accountSelection);
-  console.log(`\nWorkers Paid verified for ${accountSelection.account.name} (${subscription.rate_plan?.public_name ?? "active Workers subscription"}).`);
+  console.log(`\nWorkers Paid verified for ${accountSelection.account.name} (${workersPlan.label}).`);
   const secretsPath = resolve(projectRoot, options.secrets);
   try {
     await readFile(secretsPath, "utf8");