@casomoltd/tooling 0.35.0 → 0.36.0

package/bin/buttondown.mjs

@@ -12,19 +12,25 @@
  *   buttondown emit <dir>          write each long field out as rendered
  *   buttondown draft <file.md>     create or replace a draft
  *   buttondown upload <image>      upload an image, print its URL
- *   buttondown api <METHOD> <path> [json]
- *                                  any call, for setting up a manual test
+ *   buttondown api <METHOD> <path> [json] [--send]
+ *                                  any call, for setting up a manual test;
+ *                                  one that sends or schedules an email
+ *                                  is refused without --send
  *
  * `diff`, `apply` and `check` exit 1 on drift, a refusal or a problem, so a
  * script can gate on them.
  */
 import {
-  apply, assertApiPath, client, draft, drift, emit, loadSettings, readKey,
-  runCheck, upload, writeTokens,
+  apply, assertApiPath, assertNotSending, client, draft, drift, emit,
+  loadSettings, readKey, runCheck, upload, writeTokens,
 } from "../buttondown/engine.mjs";
 
+/** The one flag: without it, `api` refuses any call that could send an
+ *  email, and no other command takes it. */
+const SEND_FLAG = "--send";
+
 const USAGE = "usage: buttondown [diff|apply|check|tokens|emit <dir>|"
-  + "draft <file.md>|upload <image>|api <METHOD> <path> [json]]";
+  + `draft <file.md>|upload <image>|api <METHOD> <path> [json] [${SEND_FLAG}]]`;
 
 /** Each command with the fewest and most arguments it takes. */
 const ARGS = {
@@ -32,9 +38,13 @@ const ARGS = {
   emit: [1, 1], draft: [1, 1], upload: [1, 1], api: [2, 3],
 };
 
-const [command = "diff", ...args] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+const send = argv.includes(SEND_FLAG);
+const [command = "diff", ...args] = argv.filter((a) => a !== SEND_FLAG);
 const [fewest, most] = ARGS[command] ?? [];
-if (fewest === undefined || args.length < fewest || args.length > most) {
+const badUsage = fewest === undefined || args.length < fewest
+  || args.length > most || (send && command !== "api");
+if (badUsage) {
   console.error(USAGE);
   process.exit(2);
 }
@@ -85,9 +95,16 @@ switch (command) {
   case "api": {
     const [method, url, body] = args;
     assertApiPath(settings, method, url);
-    const res = await (await api()).call(
-      method.toUpperCase(), url, body && JSON.parse(body),
-    );
+    const payload = body && JSON.parse(body);
+    if (!send) {
+      try {
+        assertNotSending(method, url, payload);
+      } catch (e) {
+        console.error(`buttondown: ${e.message}; add ${SEND_FLAG} to send it`);
+        process.exit(1);
+      }
+    }
+    const res = await (await api()).call(method.toUpperCase(), url, payload);
     console.log(res.status, res.data ? JSON.stringify(res.data, null, 2) : "");
     process.exit(res.ok ? 0 : 1);
   }

package/buttondown/engine.mjs

@@ -87,6 +87,19 @@ const API_PATH = new URL(API).pathname;
 /** The status of an email not yet sent. */
 const DRAFT = "draft";
 
+/**
+ * The api routes that can mail someone, judged on a `requestPath`. A write
+ * to the emails collection or to one email may carry a status that sends
+ * it, so it passes only as a draft; any action on an email (publish,
+ * send-draft and whatever Buttondown adds) or on a subscriber (a reminder,
+ * an email to one reader) is refused outright, so a new route fails closed.
+ * Creating an unactivated subscriber also mails a confirmation, and stays
+ * allowed: it is how a manual test stands in for a reader signing up, to an
+ * address the tester owns.
+ */
+const EMAIL_WRITE = new RegExp(`^${API_PATH}/emails(/[^/]+)?/?$`);
+const SENDING_ACTION = new RegExp(`^${API_PATH}/(emails|subscribers)/[^/]+/.`);
+
 const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n/;
 
 /** The Buttondown fields holding the two skins. */
@@ -387,7 +400,7 @@ export async function readKey(env = process.env) {
 export function client(settings, key) {
   const {newsletter} = settings;
   async function call(method, url, body, {form} = {}) {
-    const res = await fetch(new URL(API + url), {
+    const res = await fetch(requestUrl(url), {
       method,
       headers: {
         Authorization: `Token ${key}`,
@@ -445,25 +458,37 @@ export function client(settings, key) {
 
 /**
  * Refuses an `api` call that writes newsletter settings anywhere but this
- * newsletter. Judged on the path the server routes: percent-decoded, then
- * normalised, so `/%6eewsletters/<other>`, `/./newsletters/<other>` and
- * `<own>/../<other>` are seen for what they are. A path still encoded after
- * one decoding is refused outright rather than guessed at.
+ * newsletter, judged on the path the server routes (`requestPath`).
  */
 export function assertApiPath(settings, method, url) {
   if (method.toUpperCase() === "GET") return;
-  const decoded = decodeURIComponent(new URL(API + url).pathname);
-  if (decoded.includes("%")) {
-    throw new Error(`api refuses an encoded path: ${url}`);
-  }
-  const {pathname} = new URL(decoded, API);
-  const own = API_PATH + newsletterPath(settings.newsletter);
+  const pathname = requestPath(url);
+  const own = (API_PATH + newsletterPath(settings.newsletter)).toLowerCase();
   if (pathname.startsWith(`${API_PATH}/newsletters`)
     && pathname !== own && !pathname.startsWith(`${own}/`)) {
     throw new Error(`api writes under /newsletters only to ${own}`);
   }
 }
 
+/**
+ * Throws if an api call could send or schedule an email (`EMAIL_WRITE`,
+ * `SENDING_ACTION`). Sending reaches real inboxes and cannot be recalled, so
+ * the caller lets a call through only on a person's explicit say-so.
+ */
+export function assertNotSending(method, url, body) {
+  const cannotSend = ["GET", "DELETE"].includes(method.toUpperCase());
+  if (cannotSend) return;
+  const pathname = requestPath(url);
+  const status = body && typeof body === "object" ? body.status : undefined;
+  const creates = pathname.replace(/\/$/, "") === `${API_PATH}/emails`;
+  const draftOnly = status === DRAFT || (status === undefined && !creates);
+  if (SENDING_ACTION.test(pathname)
+    || (EMAIL_WRITE.test(pathname) && !draftOnly)) {
+    throw new Error(`api refuses a call that could send an email: `
+      + `${method.toUpperCase()} ${url}`);
+  }
+}
+
 /** Whether a live value already says what the repo wants. */
 export function same(field, got, want) {
   if (IMAGE_FIELDS.has(field)) {
@@ -693,6 +718,26 @@ export function stripComments(text) {
   }
 }
 
+/** The URL `call` fetches for an api path, and the one the guards judge. */
+function requestUrl(url) {
+  return new URL(API + url);
+}
+
+/**
+ * The path the server routes for an `api` url, from `requestUrl`,
+ * then percent-decoded, slash-collapsed and normalised, so
+ * `/%6eewsletters/<other>`, `//emails/<id>/publish`, `/./newsletters/<other>`
+ * and `<own>/../<other>` are seen for what they are. A path still encoded
+ * after one decoding is refused outright rather than guessed at.
+ */
+function requestPath(url) {
+  const decoded = decodeURIComponent(requestUrl(url).pathname);
+  if (decoded.includes("%")) {
+    throw new Error(`api refuses an encoded path: ${url}`);
+  }
+  return new URL(decoded.replace(/\/{2,}/g, "/"), API).pathname.toLowerCase();
+}
+
 /** Throws unless an image field holds an absolute URL, since Buttondown
  *  stores a relative one as given and the image then never loads. */
 function assertAbsoluteUrl(field, value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
   "license": "MIT",
   "repository": {