create-safest-tools 0.2.0 → 0.2.1

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:

package/package.json

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

package/src/cli.mjs

@@ -7,6 +7,23 @@ import { scaffoldProject, validateGeneratedConfiguration } from "./scaffold.mjs"
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 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 +49,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 +107,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;
 }
@@ -106,7 +128,7 @@ export async function runCli(argv, dependencies = {}) {
   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,7 +9,7 @@ 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.
 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.

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 = "";
@@ -113,7 +117,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 };