breakaway 2.0.0-main.57 → 2.0.0-main.59

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.57",
+  "version": "2.0.0-main.59",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "breakaway",
-      "version": "2.0.0-main.57",
+      "version": "2.0.0-main.59",
       "license": "FSL-1.1-Apache-2.0",
       "bin": {
         "breakaway": "scripts/tasks.mjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "2.0.0-main.57",
+  "version": "2.0.0-main.59",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/scripts/tasks/infra.js

@@ -164,7 +164,7 @@ function init(opts, { cwd, log, error, version = VERSION }) {
   }
   log(`${opts['dry-run'] ? 'Would write' : 'Wrote'} ${file.path}, for ${environments.join(', ')}, from ${branch}.`);
   log(
-    `Before the board can apply a plan, the owner makes, for each environment, a GitHub environment of the same name that only ${branch} may use, with that environment's write token as the secret CLOUDFLARE_API_TOKEN; sets the repository variable BREAKAWAY_URL to the board's address; and gives the board's GitHub App Actions: read and write here. Agents never do these, and never run the workflow.`,
+    `Before the board can apply a plan, the owner makes, for each environment, a GitHub environment of the same name that only ${branch} may use, with that environment's write token as the secret CLOUDFLARE_API_TOKEN (the board's read permissions, plus Cloudflare's Workers Editor on that environment's Workers, or the legacy Workers Scripts Write, and only the Write permissions its file needs); sets the repository variable BREAKAWAY_URL to the board's address; and gives the board's GitHub App Actions: read and write here. Agents never do these, and never run the workflow.`,
   );
   return 0;
 }

package/src/infra-cloudflare-plan.js

@@ -9,7 +9,8 @@
  * a discovered resource the desired state doesn't list is deleted. Deleting a Worker, D1 database, KV namespace, R2
  * bucket, queue, or container application is marked irreversible, with why.
  *
- * Tokens can't be scoped to one Worker, so the provider keeps every change inside the environment's scope itself: it
+ * Only Workers can be scoped one by one (Workers Editor, BRK-243); a database, namespace, bucket, or queue permission
+ * reaches every one on the account. So the provider keeps every change inside the environment's scope itself: it
  * refuses to make a resource that already exists on the account outside the scope, a database, namespace, bucket, or
  * queue no Worker in the desired state binds, and a delete of something a remaining Worker still binds.
  *
@@ -53,9 +54,27 @@ export { MANAGED };
 /** Kinds Cloudflare names by their name, so a rename is a change of its own (KV's title, a route's pattern). */
 const RENAMES = new Set(['kv', 'route']);
 
+/**
+ * What the write token needs to change a Worker (BRK-243): Cloudflare's Workers Editor role, scoped to the
+ * environment's Workers. It replaces the legacy Workers Scripts Write (Editor at the Workers product scope), and a
+ * token made with that still works. Editor can't make or delete a Worker: that's Admin at the Workers product scope,
+ * which the owner gives the write token by hand for the one apply that needs it. Custom domains have no per-Worker
+ * role yet, so an environment that declares them scopes Editor to the Workers product.
+ */
+export const WORKERS_WRITE = {
+  edit: 'Workers Editor on this Worker (or the legacy Workers Scripts Write)',
+  create:
+    'Workers Admin at the Workers product scope, because Workers Editor can’t make a Worker: give the write token Admin for this apply, then take it away',
+  delete:
+    'Workers Admin, because Workers Editor can’t delete a Worker: give the write token Admin for this apply, then take it away',
+  domain:
+    'Workers Editor at the Workers product scope (custom domains have no per-Worker role yet; or the legacy Workers Scripts Write) and Workers Routes Write on its zone',
+};
+
 /** Why deleting each kind can't be undone. Routes and custom domains hold nothing, so they can be made again. */
 const LOST = {
-  worker: 'deleting a Worker deletes every version of it, so it can’t be rolled back',
+  worker:
+    'deleting a Worker deletes every version of it, so it can’t be rolled back; it needs Workers Admin on the write token, which Workers Editor doesn’t have, so give it for this apply and take it away after',
   d1: 'deleting a D1 database deletes its data; Time Travel can’t restore a deleted database',
   kv: 'deleting a KV namespace deletes every key in it',
   r2: 'deleting an R2 bucket deletes it for good (Cloudflare refuses unless it’s empty)',
@@ -620,11 +639,11 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
   switch (c.kind) {
     case 'worker': {
       const p = `${a}/workers/scripts/${encodeURIComponent(c.name)}`;
-      const perm = { permission: 'Workers Scripts Write' };
-      if (c.op === 'delete') return call('DELETE', p, perm);
+      const perm = { permission: WORKERS_WRITE.edit };
+      if (c.op === 'delete') return call('DELETE', p, { permission: WORKERS_WRITE.delete });
       if (c.op === 'create') {
         // The Worker alone: its first version, with its code, comes from its deploy.
-        await call('POST', `${a}/workers/workers`, { ...perm, json: { name: c.name } });
+        await call('POST', `${a}/workers/workers`, { permission: WORKERS_WRITE.create, json: { name: c.name } });
         if (Array.isArray(after.crons) && after.crons.length)
           await call('PUT', `${p}/schedules`, { ...perm, json: after.crons.map((cron) => ({ cron })) });
         return;
@@ -731,7 +750,7 @@ async function applyChange(c, { call, a, live, have, made, resolve }) {
     }
     case 'custom-domain': {
       // Attaching makes a DNS record and a certificate, so it needs Workers Routes Write on the zone too.
-      const perm = { permission: 'Workers Scripts Write and Workers Routes Write on its zone' };
+      const perm = { permission: WORKERS_WRITE.domain };
       if (c.op === 'delete') return call('DELETE', `${a}/workers/domains/${id}`, perm);
       const zone = after.zone ?? before.zone;
       return call('PUT', `${a}/workers/domains`, {
@@ -824,7 +843,7 @@ export async function rollbackWorker(ctx, { worker, versions, force = false }) {
   const account = await accountOf(reader(ctx), ctx);
   const p = `/accounts/${encodeURIComponent(account)}/workers/scripts/${encodeURIComponent(worker)}/deployments${force ? '?force=true' : ''}`;
   return writer(ctx)('POST', p, {
-    permission: 'Workers Scripts Write',
+    permission: WORKERS_WRITE.edit,
     json: {
       strategy: 'percentage',
       versions: versions.map((v) => ({ version_id: v.id, percentage: v.percentage })),

package/src/infra-cloudflare.js

@@ -93,12 +93,23 @@ export function refuses(r, op) {
   return null;
 }
 
+/**
+ * Cloudflare's Workers role the board reads Workers with (BRK-243): Metadata Read-Only at the Workers product scope,
+ * which reads settings and never a Worker's code. It replaces the legacy Workers Scripts Read, which Cloudflare maps to
+ * Content Read-Only (code included); a token made with that still works.
+ */
+export const WORKERS_READ = 'Workers Metadata Read-Only';
+
 /**
  * The board's read-only token (BRK-188, "Tokens"; BRK-194 keeps it). Read only: no permission ends in Edit or Write.
  * @type {import('./infra-provider.js').ReadToken['permissions']}
  */
 export const READ_PERMISSIONS = [
-  { name: 'Workers Scripts Read', for: 'Workers, their settings, deployments, secret names, and cron triggers' },
+  {
+    name: WORKERS_READ,
+    legacy: ['Workers Scripts Read'],
+    for: 'Workers, their settings, deployments, secret names, cron triggers, Durable Object namespaces, and custom domains, never their code',
+  },
   { name: 'Workers KV Storage Read', for: 'KV namespaces, never their values' },
   { name: 'Workers R2 Storage Read', for: 'R2 buckets and their settings, never their objects' },
   { name: 'D1 Read', for: 'D1 databases' },
@@ -131,6 +142,12 @@ export const NEVER_CALLED = [
   /\/secrets\/[^/]+$/u,
 ];
 
+/** A permission as a 403 names it: with its legacy names in parentheses, for a token made before Cloudflare renamed it. */
+export function named(permission) {
+  const legacy = READ_PERMISSIONS.find((p) => p.name === permission)?.legacy;
+  return legacy?.length ? `${permission} (or the legacy ${legacy.join(' or ')})` : permission;
+}
+
 /** An answer Cloudflare refused, with what the token was missing when it was a 403. */
 export class CloudflareError extends Error {
   /** @param {string} message @param {number} status */
@@ -181,7 +198,7 @@ export function reader(ctx) {
     if (res.status === 404 && missingOk) return null;
     if (res.status === 403)
       throw Object.assign(
-        new CloudflareError(`Cloudflare refused GET ${path.split('?')[0]}: the token needs ${permission}`, 403),
+        new CloudflareError(`Cloudflare refused GET ${path.split('?')[0]}: the token needs ${named(permission)}`, 403),
         { permission },
       );
     if (!res.ok || json?.success === false)
@@ -322,9 +339,9 @@ export async function discover(ctx, { live = false } = {}) {
   seen.account = await accountOf(cf, ctx);
   const a = enc(seen.account);
   const scripts = new Map(
-    (
-      await cf.get(`/accounts/${a}/workers/scripts`, { permission: 'Workers Scripts Read' }).then((j) => j.result ?? [])
-    ).map((s) => [String(s.id), s]),
+    (await cf.get(`/accounts/${a}/workers/scripts`, { permission: WORKERS_READ }).then((j) => j.result ?? [])).map(
+      (s) => [String(s.id), s],
+    ),
   );
   seen.scripts = [...scripts.keys()];
   if (!scripts.has(target)) return done();
@@ -337,7 +354,7 @@ export async function discover(ctx, { live = false } = {}) {
     const name = /** @type {string} */ (queue.shift());
     if (bindingsOf.has(name) || !scripts.has(name)) continue;
     const p = `/accounts/${a}/workers/scripts/${enc(name)}`;
-    const opts = { permission: 'Workers Scripts Read' };
+    const opts = { permission: WORKERS_READ };
     const settings = (await cf.get(`${p}/settings`, opts)).result ?? {};
     const deployments = (await cf.get(`${p}/deployments`, opts)).result ?? {};
     const secrets = (await cf.get(`${p}/secrets`, opts)).result ?? [];
@@ -501,7 +518,7 @@ export async function discover(ctx, { live = false } = {}) {
   // Durable Object namespaces: those a Worker in scope binds or defines, and the Worker whose class runs them.
   const doBound = scoped('durable_object_namespace');
   const namespaces = await cf.all(`/accounts/${a}/workers/durable_objects/namespaces`, {
-    permission: 'Workers Scripts Read',
+    permission: WORKERS_READ,
   });
   for (const ns of namespaces) {
     const id = rid('durable-object', ns.id);
@@ -578,7 +595,7 @@ export async function discover(ctx, { live = false } = {}) {
   }
 
   // Custom domains attached to a Worker in scope.
-  const domains = (await cf.get(`/accounts/${a}/workers/domains`, { permission: 'Workers Scripts Read' })).result ?? [];
+  const domains = (await cf.get(`/accounts/${a}/workers/domains`, { permission: WORKERS_READ })).result ?? [];
   for (const d of domains) {
     if (!workers.has(String(d.service))) continue;
     add({

package/src/infra-provider.js

@@ -158,8 +158,10 @@ export const COST_NOTE_MAX = 500;
  * One permission a read-only token needs, by the name the platform's token page gives it, and what the board reads
  * with it. Never a token's value.
  * @typedef {object} TokenPermission
- * @property {string} name like `Workers Scripts Read`
+ * @property {string} name like `Workers Metadata Read-Only`
  * @property {string} for what the board reads with it, in a few words
+ * @property {string[]} [legacy] older names for the same access (like `Workers Scripts Read`): a token made with one of
+ *   them still counts as having it, and the board names them in parentheses
  */
 
 /**
@@ -263,8 +265,11 @@ export function checkProvider(provider) {
 function checkReadToken(what, token) {
   if (!isObject(token)) fail(what, 'readToken is not an object');
   if (!Array.isArray(token.permissions) || token.permissions.length === 0) fail(what, 'readToken names no permissions');
-  for (const p of token.permissions)
+  for (const p of token.permissions) {
     if (!isObject(p) || !text(p.name) || !text(p.for)) fail(what, 'a readToken permission has no name or no for');
+    if (p.legacy !== undefined && (!Array.isArray(p.legacy) || !p.legacy.every(text)))
+      fail(what, 'a readToken permission’s legacy is not a list of names');
+  }
   if (typeof token.url !== 'string' || !token.url.startsWith('https://')) fail(what, 'readToken has no https url');
   if (token.check !== undefined && typeof token.check !== 'function') fail(what, 'readToken check is not a function');
 }