@runeditrun/rer 0.2.2 → 0.2.4

package/modules/demo-host/plan.mjs

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import { assert, resourceName } from '../deploy-kit/validation.mjs';
+import { ownerWorkerName } from '../deploy-kit/owner.mjs';
+import { siteDeclaration } from '../deploy-kit/site.mjs';
+
+/* A seed's hosted demo at demo.<domain>: the Worker `rer deploy --demo` builds
+ * from deploy-demo.json, as `rer deploy --site` builds the run site from
+ * deploy-site.json. It is this folder's front Worker plus a Container class
+ * running the seed's own image (`rer build --platform container`, workerd
+ * engine), deployed by `wrangler deploy` with the image beside it. */
+
+export const DEMO_FILES = ['worker.mjs', 'container.mjs', 'capacity.mjs', 'claim.mjs', 'pages.mjs'];
+const FRONT_SET = /^(?:RER_.*|SESSION_SECRET|SETUP_TOKEN|OWNER_EMAIL)$/;
+const SECRET = /SECRET|TOKEN|PASSWORD|_KEY$/;
+
+/**
+ * deploy-demo.json: `{ "version": 1, "domain": "run-lamp.com", "name": "Lamp" }`, plus optionally
+ * `maxInstances` (concurrent demos, default 10) and `settings`, the seed's plain demo settings
+ * (such as MAIL_PROVIDER: "development"). Settings never carry secrets or what the front sets.
+ */
+export function demoDeclaration(value, originVar) {
+  assert(value && typeof value === 'object' && !Array.isArray(value) && value.version === 1 && Object.keys(value).every(key => ['version', 'domain', 'name', 'maxInstances', 'settings'].includes(key)), 'invalid-demo-declaration');
+  siteDeclaration({ version: 1, domain: value.domain });
+  assert(typeof value.name === 'string' && value.name.trim() === value.name && value.name.length > 0 && value.name.length <= 60 && !/[\p{Cc}\p{Cf}]/u.test(value.name), 'invalid-demo-name');
+  const maxInstances = value.maxInstances ?? 10;
+  assert(Number.isSafeInteger(maxInstances) && maxInstances >= 1 && maxInstances <= 100, 'invalid-demo-max-instances');
+  const settings = value.settings ?? {};
+  assert(settings && typeof settings === 'object' && !Array.isArray(settings) && Object.entries(settings).every(([name, setting]) =>
+    /^[A-Z][A-Z0-9_]{0,63}$/.test(name) && !FRONT_SET.test(name) && !SECRET.test(name) && name !== originVar && typeof setting === 'string' && setting.length <= 1024), 'invalid-demo-settings');
+  return { domain: value.domain, name: value.name, maxInstances, settings };
+}
+
+/** The demo Worker's name and its Wrangler configuration; no provider request. */
+export function demoPlan({ project, environment, compatibilityDate, originVar, declaration, turnstileSiteKey }) {
+  assert(/^\d{4}-\d{2}-\d{2}$/.test(compatibilityDate ?? '') && /^[A-Z][A-Z0-9_]{0,63}$/.test(originVar ?? ''), 'invalid-plan');
+  const { domain, name, maxInstances, settings } = demoDeclaration(declaration, originVar);
+  const worker = `${ownerWorkerName(project, environment)}--demo`, hostname = `demo.${domain}`;
+  assert(resourceName(worker), 'owner-name-too-long');
+  // Rate limit namespaces are account-wide integers: one per demo Worker.
+  const namespace = String(1000 + parseInt(createHash('sha256').update(worker).digest('hex').slice(0, 8), 16) % 1_000_000_000);
+  const wrangler = {
+    name: worker, main: 'worker.mjs', compatibility_date: compatibilityDate, workers_dev: false, preview_urls: false,
+    routes: [{ pattern: hostname, custom_domain: true }],
+    vars: { DEMO_ORIGIN: `https://${hostname}`, DEMO_SITE: `https://${domain}`, DEMO_NAME: name, DEMO_ORIGIN_VAR: originVar, DEMO_MAX_INSTANCES: String(maxInstances), DEMO_SETTINGS: JSON.stringify(settings),
+      ...(turnstileSiteKey ? { TURNSTILE_SITE_KEY: turnstileSiteKey } : {}) },
+    durable_objects: { bindings: [{ name: 'DEMO', class_name: 'DemoContainer' }, { name: 'CAPACITY', class_name: 'DemoCapacity' }] },
+    migrations: [{ tag: 'v1', new_sqlite_classes: ['DemoContainer', 'DemoCapacity'] }],
+    containers: [{ class_name: 'DemoContainer', image: './image/Dockerfile', max_instances: maxInstances, instance_type: 'basic' }],
+    ratelimits: [{ name: 'STARTS', namespace_id: namespace, simple: { limit: 3, period: 60 } }],
+  };
+  return { worker, hostname, origin: `https://${hostname}`, maxInstances, settings: Object.keys(settings), wrangler };
+}

package/modules/demo-host/worker.mjs

@@ -0,0 +1,72 @@
+// A seed's hosted demo at demo.<domain>, generated by `rer deploy --demo`.
+// GET / shows the start page (a Turnstile managed widget that submits itself).
+// POST /__demo/start checks the visitor's IP rate limit, Turnstile and capacity,
+// then starts a container of their own, signs its owner in and sets the
+// rer_demo cookie. Every request with that cookie goes to the visitor's
+// container; nothing else on this host is reachable.
+import { startPage, demoCookie } from './pages.mjs';
+
+export { DemoContainer } from './container.mjs';
+export { DemoCapacity } from './capacity.mjs';
+
+const HOUR = 60 * 60_000;
+const home = () => new Response(null, { status: 303, headers: { location: '/' } });
+
+/** The visitor's demo from its cookie; ids are checked by idFromString, so a forged one is no demo. */
+function demoId(request, env) {
+  const value = (request.headers.get('cookie') ?? '').split(';').map(part => part.trim()).find(part => part.startsWith('rer_demo='))?.slice(9);
+  if (!value) return null;
+  try { return env.DEMO.idFromString(value); } catch { return null; }
+}
+
+// The demo's end in the visitor's time zone, as the Demo bar shows it (HH:MM).
+function localTime(time, timeZone = 'UTC') {
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', { timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', second: '2-digit', timeZoneName: 'longOffset' }).formatToParts(time).map(part => [part.type, part.value]));
+  return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}${parts.timeZoneName === 'GMT' ? '+00:00' : parts.timeZoneName.slice(3)}`;
+}
+
+async function human(env, token, ip) {
+  if (typeof token !== 'string' || !token || token.length > 2048) return false;
+  const body = new URLSearchParams({ secret: env.TURNSTILE_SECRET_KEY, response: token });
+  if (ip) body.set('remoteip', ip);
+  const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', { method: 'POST', body });
+  const result = response.ok ? await response.json() : {};
+  if (result.success !== true) console.error('Turnstile refused a start:', response.status, JSON.stringify(result['error-codes'] ?? []));
+  return result.success === true;
+}
+
+async function start(request, env) {
+  if (request.headers.get('origin') !== env.DEMO_ORIGIN) return startPage(env, { status: 403, notice: 'Start the demo from this page.' });
+  const ip = request.headers.get('cf-connecting-ip') ?? '';
+  if (!(await env.STARTS.limit({ key: ip })).success) return startPage(env, { status: 429, notice: 'Too many demos started from your network. Try again in a minute.' });
+  const form = await request.formData();
+  if (!await human(env, form.get('cf-turnstile-response'), ip)) return startPage(env, { status: 403, notice: 'The check did not pass. Try again.' });
+  const id = env.DEMO.newUniqueId(), ends = Date.now() + HOUR;
+  if (!await env.CAPACITY.get(env.CAPACITY.idFromName('capacity')).acquire(id.toString(), ends, Number(env.DEMO_MAX_INSTANCES))) {
+    return startPage(env, { status: 503, notice: 'Every demo is in use right now. Try again in a few minutes.' });
+  }
+  const demo = env.DEMO.get(id);
+  try {
+    const signedIn = await demo.start({ origin: env.DEMO_ORIGIN, originVar: env.DEMO_ORIGIN_VAR, ends, endsLocal: localTime(ends, request.cf?.timezone), settings: JSON.parse(env.DEMO_SETTINGS) });
+    const headers = new Headers({ location: signedIn.location, 'cache-control': 'no-store' });
+    for (const cookie of [...signedIn.cookies, demoCookie(env, id.toString())]) headers.append('set-cookie', cookie);
+    return new Response(null, { status: 303, headers });
+  } catch (error) {
+    console.error('Demo start failed:', error.message);
+    await demo.end();
+    return startPage(env, { status: 502, notice: 'The demo did not start. Try again.' });
+  }
+}
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (url.pathname === '/__demo/start') return request.method === 'POST' ? start(request, env) : home();
+    const id = demoId(request, env);
+    if (id) return env.DEMO.get(id).fetch(request);
+    if (!['GET', 'HEAD'].includes(request.method)) return new Response('Start a demo first.', { status: 403 });
+    if (url.pathname !== '/') return home();
+    return startPage(env);
+  },
+};

package/modules/deploy-kit/README.md

@@ -193,6 +193,17 @@ No Single Redirect (dynamic redirect ruleset) permission is needed. Base's refer
 
 SQL files have ordered unique names and SHA-256 identities. `d1_migrations` holds controller history with ordered IDs, names, timestamps, SHA-256 hashes and states. Native archives already exclude this installation table. Standard Wrangler name-only inserts remain possible, but their missing hashes/states block subsequent Base deployment pending reviewed adoption. Applied entries must be an unchanged prefix of the desired set. A new migration gets an `applying` claim before its SQL and completion marker are submitted together through the [Cloudflare D1 SQL import API](https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/import/), using the same whole-file protocol as Wrangler to preserve compound trigger bodies and atomic SQL/completion. Uploads use bounded HTTPS R2 destinations, without account credentials; polling is bounded and signed URLs and import response text are never diagnostic output. Any interrupted, failed or uncertain outcome remains blocked and must be inspected explicitly; the kit never automatically retries, rolls back user data, or marks an unknown outcome successful. Readback checks every final identity.
 
+A seed that had to rewrite a migration it already released declares the rewrite
+in `migrations/rewrites.json`: `{ "version": 1, "rewrites": [{ "migration":
+"0019_import_custody.sql", "from": "<released SHA-256>", "to": "<current SHA-256>",
+"reason": "...", "reviewed": true }] }`. An applied row holding `from` then counts
+as that migration, so an upgrade past it proceeds; the ledger keeps the released
+digest it applied. A later migration must converge databases that applied the
+released bytes. The record is refused unless `reviewed` is `true`, it names a
+migration in the set, and `to` is that migration's current bytes; every other
+change to applied history is still refused. Keep the record for as long as any
+installation may hold the released digest.
+
 Completion preserves the original SQL bytes and always starts on a new line.
 Comment-only migrations are rejected before any provider request or ledger claim.
 The controller adds a separator only when the final non-comment token is not a
@@ -290,6 +301,22 @@ sleep}` selects a smaller bound and deterministic time; `healthOptions.now` and
 replaces the mode-0600 receipt and refuses any change to its identity; the default
 CLI and owner-account state do this. A no-op repeat never rewrites the original receipt.
 
+Owner-account secret changes use the same bounded `waitHealth` after their new
+Worker version has settled and been recorded. This includes explicit
+`--set-secret`/`--unset-secret` commands, a fresh owner setup token, and the
+post-claim retirement performed by standard deploys and custom deploy hooks.
+Readiness checks the receipt source SHA, fingerprint and actual new version;
+it needs neither build output nor clean source for a secret-only command.
+Workers without a public route retain provider-only verification.
+
+A failed readiness check leaves the applied secret change, owner claim and token
+retirement recorded. The public command fails with the last HTTP status and the
+first bounded, redacted response line. Correct the seed/app configuration and
+redeploy; an app that requires an already spent setup token must remove that
+runtime requirement, rather than restoring the token or undoing ownership.
+The ownership receipt records readiness success/failure for the new version;
+untrusted response prefixes are never written into that record.
+
 ## Read-only teardown verification
 
 The kit does not perform deletes. After a seed has validated its receipt and

package/modules/deploy-kit/env-file.mjs

@@ -21,6 +21,7 @@ export async function readDeployEnvFile(root, envFile, localOnlyKeys = []) {
     if (Object.hasOwn(settings, match[1])) throw new Error('Repeated deploy env key');
     settings[match[1]] = match[2].replace(/^"(.*)"$/, '$1');
   }
-  if ([...LOCAL_ONLY_KEYS, ...localOnlyKeys].some(key => Object.hasOwn(settings, key))) throw new Error('Local-only keys are refused for deploy');
+  const local = [...LOCAL_ONLY_KEYS, ...localOnlyKeys].find(key => Object.hasOwn(settings, key));
+  if (local) throw new Error(`Local-only key ${local} is refused for deploy; remove it from the file`);
   return settings;
 }

package/modules/deploy-kit/health-request.mjs

@@ -1,5 +1,10 @@
+import { StringDecoder } from 'node:string_decoder';
 import { assert } from './validation.mjs';
 
+// Do not flush an incomplete final character: a replacement would corrupt a
+// truncated credential prefix before the caller can redact it.
+const decodePrefix = bytes => new StringDecoder('utf8').write(bytes.subarray(0,256));
+
 async function bodyPrefix(response) {
   if (!response.body) return '';
   const reader = response.body.getReader(); let bytes = Buffer.alloc(0);
@@ -11,7 +16,7 @@ async function bodyPrefix(response) {
     }
   } catch { /* HTTP status remains authoritative if its diagnostic body breaks. */ }
   finally { await reader.cancel().catch(() => {}); }
-  return bytes.toString('utf8');
+  return decodePrefix(bytes);
 }
 
 /** One credential-free, bounded request. Retain only bounded response evidence. */
@@ -41,7 +46,7 @@ export async function healthRequest({origin, receipt, versionId, request, timeou
         const {done,value} = await reader.read();
         if (done) break;
         bytes = Buffer.concat([bytes, value]);
-        attempt.body = bytes.subarray(0,256).toString('utf8');
+        attempt.body = decodePrefix(bytes);
         assert(bytes.length <= 65536,'response-too-large');
       }
     } finally { await reader.cancel().catch(() => {}); }

package/modules/deploy-kit/migration-ledger.mjs

@@ -4,7 +4,44 @@ export const ledger = 'd1_migrations';
 const legacy = '_rer_deploy_migrations';
 export const literal = value => `'${value.replaceAll("'","''")}'`;
 export const createLedger = `CREATE TABLE ${ledger} (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE, applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, sha256 TEXT, state TEXT CHECK(state IN ('applying','applied')))`;
-const validPrefix = (rows, migrations) => rows.every((row, index) => row.name === migrations[index]?.name && row.sha256 === migrations[index]?.sha256 && row.state === 'applied');
+
+// Every ledger shape a deployment can hold: Wrangler's d1_migrations; that
+// table after the kit adopted it (sha256 and state added); the kit's own
+// d1_migrations, which rer 0.2.2 and later create; and the kit's
+// _rer_deploy_migrations from rer 0.2.1 and earlier, which stays authoritative
+// until the next deploy moves it into d1_migrations. Seed recovery code that
+// checks the ledger before reading or restoring it accepts all four with
+// migrationLedgerShape.
+const shapeColumns = table => `SELECT '${table}' AS ledger,cid,name,upper(type) AS type,"notnull",dflt_value,pk,hidden FROM pragma_table_xinfo('${table}')`;
+export const ledgerShapeQuery = `${shapeColumns(legacy)} UNION ALL ${shapeColumns(ledger)} ORDER BY ledger,cid`;
+const column = (name, type, notnull = 0, dflt_value = null, pk = 0) => ({ name, type, notnull, dflt_value, pk, hidden: 0 });
+const wrangler = [column('id','INTEGER',0,null,1), column('name','TEXT'), column('applied_at','TIMESTAMP',1,'CURRENT_TIMESTAMP')];
+const tracked = [column('sha256','TEXT'), column('state','TEXT')];
+const shapes = {
+  [ledger]: {
+    wrangler,
+    adopted: [...wrangler, ...tracked],
+    kit: [column('id','INTEGER',0,null,1), column('name','TEXT',1), column('applied_at','TEXT',1,'CURRENT_TIMESTAMP'), ...tracked],
+  },
+  [legacy]: { legacy: [column('name','TEXT',0,null,1), column('sha256','TEXT',1), column('state','TEXT',1)] },
+};
+/** The ledger's shape from its ledgerShapeQuery rows (node:sqlite or D1):
+ * { name, columns, shape } where shape is 'wrangler', 'adopted', 'kit' or
+ * 'legacy'. When both tables exist, _rer_deploy_migrations is the history, as
+ * restores read it. Any other shape throws invalid-migration-ledger. */
+export function migrationLedgerShape(rows) {
+  // Rows without a ledger column come from the d1_migrations-only query of rer 0.2.3.
+  const tables = Map.groupBy(rows ?? [], row => row.ledger ?? ledger);
+  const name = tables.has(legacy) ? legacy : ledger;
+  const read = (tables.get(name) ?? []).map(row => ({ name: row.name, type: String(row.type).toUpperCase(), notnull: Number(row.notnull), dflt_value: row.dflt_value ?? null, pk: Number(row.pk), hidden: Number(row.hidden) }));
+  const shape = Object.keys(shapes[name]).find(key => JSON.stringify(read) === JSON.stringify(shapes[name][key]));
+  assert(shape, 'invalid-migration-ledger');
+  return { name, columns: read.map(row => row.name), shape };
+}
+/** An applied row records this migration: its current bytes, or bytes a seed's
+ * reviewed rewrite record says this migration replaced. */
+export const recorded = (row, migration) => row.name === migration?.name && (row.sha256 === migration.sha256 || (migration.rewrites ?? []).some(rewrite => rewrite.from === row.sha256));
+const validPrefix = (rows, migrations) => rows.every((row, index) => recorded(row, migrations[index]) && row.state === 'applied');
 const same = (a, b) => a.length === b.length && a.every((row, index) => row.name === b[index].name && row.sha256 === b[index].sha256 && row.state === b[index].state);
 
 export async function readLedger(api, id, migrations, query) {

package/modules/deploy-kit/migrations.mjs

@@ -1,7 +1,9 @@
+import { join } from 'node:path';
 import { assert, hash } from './validation.mjs';
+import { regularBytes } from './artifact.mjs';
 import { assertMigrationSqlSafe } from './sql-safety.mjs';
 import { sqlTokens } from './sql-tokens.mjs';
-import { ledger, literal, createLedger, readLedger } from './migration-ledger.mjs';
+import { ledger, literal, createLedger, readLedger, recorded } from './migration-ledger.mjs';
 export function validateMigrations(migrations) {
   let previous = '';
   for (const migration of migrations) {
@@ -9,8 +11,42 @@ export function validateMigrations(migrations) {
     assert(typeof migration.sql === 'string' && migration.sql.trim() && hash(migration.sql) === migration.sha256 && migration.sql.length <= 512000, 'invalid-migration-bytes');
     assertMigrationSqlSafe(migration.sql);
     assert(sqlTokens(migration.sql).length > 0, 'invalid-migration-bytes');
+    assert(migration.rewrites === undefined || Array.isArray(migration.rewrites) && migration.rewrites.every(rewrite => /^[a-f0-9]{64}$/.test(rewrite?.from ?? '') && rewrite.from !== migration.sha256 && typeof rewrite.reason === 'string' && rewrite.reason.trim()), 'invalid-migration-rewrite');
   }
 }
+const rewriteKeys = ['migration','from','to','reason','reviewed'];
+/** A seed's reviewed rewrites of already released migrations, from
+ * migrations/rewrites.json: { version: 1, rewrites: [{ migration, from, to,
+ * reason, reviewed: true }] }. `from` is the released bytes' SHA-256, `to` the
+ * current bytes'. Each named migration then also accepts an applied row holding
+ * `from`; the ledger keeps that row as applied. Any other change stays refused. */
+export async function readMigrationRewrites(product) {
+  const text = await regularBytes(join(product,'migrations/rewrites.json'),1024*1024).then(String,error => { if (error.code === 'ENOENT') return undefined; throw error; });
+  if (text === undefined) return [];
+  let declaration; try { declaration = JSON.parse(text); } catch { throw new Error('invalid-migration-rewrites'); }
+  assert(declaration?.version === 1 && Object.keys(declaration).every(key => ['version','rewrites'].includes(key)) && Array.isArray(declaration.rewrites) && declaration.rewrites.length <= 1000, 'invalid-migration-rewrites');
+  for (const item of declaration.rewrites) {
+    assert(item && Object.keys(item).every(key => rewriteKeys.includes(key)) && /^[0-9]+_[a-zA-Z0-9_-]+\.sql$/.test(item.migration ?? '') && /^[a-f0-9]{64}$/.test(item.from ?? '') && /^[a-f0-9]{64}$/.test(item.to ?? '') && item.from !== item.to
+      && typeof item.reason === 'string' && item.reason.trim() && item.reason.length <= 1000, 'invalid-migration-rewrites');
+    assert(item.reviewed === true, 'unreviewed-migration-rewrite');
+  }
+  assert(new Set(declaration.rewrites.map(item => `${item.migration} ${item.from}`)).size === declaration.rewrites.length, 'invalid-migration-rewrites');
+  return declaration.rewrites;
+}
+/** Attach declared rewrites to the migrations they name. A record must name a
+ * migration in the list (unless `partial`, for a list that is one of several)
+ * and its `to` must be that migration's current bytes. */
+export function withRewrites(migrations, rewrites, { partial = false } = {}) {
+  for (const item of rewrites) {
+    const migration = migrations.find(x => x.name === item.migration);
+    assert(migration || partial, 'unknown-migration-rewrite');
+    if (migration) assert(migration.sha256 === item.to, 'migration-rewrite-mismatch');
+  }
+  return migrations.map(migration => {
+    const declared = rewrites.filter(item => item.migration === migration.name);
+    return declared.length ? { ...migration, rewrites: declared.map(({ from, reason }) => ({ from, reason })) } : migration;
+  });
+}
 export async function query(api, id, sql) {
   const rows = await api.request(`/d1/database/${id}/query`,{method:'POST',body:{sql}});
   assert(Array.isArray(rows) && rows.length > 0 && rows.every(x => x.success === true && Array.isArray(x.results)), 'd1-query-failed');
@@ -38,7 +74,7 @@ export async function migrate(api, id, migrations, { apply = true, upgrade = app
   }
   if (pending.length) {
     const final = (await query(api,id,`SELECT name, sha256, state FROM ${ledger} ORDER BY id`))[0].results;
-    assert(final.length === migrations.length && final.every((x,i) => x.state === 'applied' && x.name === migrations[i].name && x.sha256 === migrations[i].sha256), 'migration-readback-mismatch');
+    assert(final.length === migrations.length && final.every((x,i) => x.state === 'applied' && recorded(x, migrations[i])), 'migration-readback-mismatch');
   }
   return { applied:pending.map(x => x.name), history:migrations.map(({name,sha256}) => ({name,sha256})) };
 }

package/modules/deploy-kit/owner-cli.mjs

@@ -7,13 +7,14 @@ import { assert, hexId } from './validation.mjs';
 import { regularBytes } from './artifact.mjs';
 import { packageBuild } from './prepare.mjs';
 import { cloudflare } from './provider.mjs';
-import { ownerTarget, ownerPlan, ownerDeploy, ownerHealth, settleOwnerState } from './owner.mjs';
+import { ownerTarget, ownerPlan, ownerDeploy, ownerHealth, settleOwnerState, sameDeployment, localOnlyBinding, withStateLock, readOwnerState, writeOwnerState } from './owner.mjs';
+import { activeWorker } from './worker.mjs';
 import { ownerSecret } from './owner-secret.mjs';
 import { ownerRemove } from './owner-remove.mjs';
 import { refuseLocalModels } from './local-only.mjs';
 
 export const cronNotice = 'This Worker has a Cron Trigger. Cloudflare may take up to about two hours to start its first scheduled run on some accounts.';
-const usage = 'usage: owner-cli.mjs deploy|health|remove --declaration <file> --environment <name> [--product <dir>] [--state <file>] | secret ... --set NAME|--unset NAME';
+const usage = 'usage: owner-cli.mjs deploy|health|remove|inspect|record-owner --declaration <file> --environment <name> [--product <dir>] [--state <file>] [--outcome claimed|kept] | secret ... --set NAME|--unset NAME';
 
 /** The owner's committed source and existing local build. Run the seed's build first. */
 async function ownerArtifact(root, product) {
@@ -24,13 +25,14 @@ async function ownerArtifact(root, product) {
 }
 
 /** Inputs: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, plus the secrets the declaration names on first deploy. */
-export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, localOnlyKeys = [], notice = line => console.error(line), onCreated} = {}) {
+export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, settle, localOnlyKeys = [], notice = line => console.error(line), onCreated} = {}) {
   let parsed;
-  try { parsed = parseArgs({args:argv,allowPositionals:true,strict:true,options:{declaration:{type:'string'},environment:{type:'string'},product:{type:'string',default:''},state:{type:'string'},set:{type:'string'},unset:{type:'string'}}}); }
+  try { parsed = parseArgs({args:argv,allowPositionals:true,strict:true,options:{declaration:{type:'string'},environment:{type:'string'},product:{type:'string',default:''},state:{type:'string'},set:{type:'string'},unset:{type:'string'},outcome:{type:'string'}}}); }
   catch { throw new Error('usage'); }
   const {positionals:[command,...rest],values} = parsed;
-  if (!['deploy','health','secret','remove'].includes(command) || rest.length || !values.declaration || !values.environment) throw new Error('usage');
+  if (!['deploy','health','secret','remove','inspect','record-owner'].includes(command) || rest.length || !values.declaration || !values.environment) throw new Error('usage');
   if ((command === 'secret') !== (values.set !== undefined || values.unset !== undefined) || values.set !== undefined && values.unset !== undefined) throw new Error('usage');
+  if (values.outcome !== undefined && command !== 'record-owner' || command === 'record-owner' && !['claimed','kept'].includes(values.outcome)) throw new Error('usage');
   await refuseLocalModels(resolve(cwd));
   const missing = ['CLOUDFLARE_ACCOUNT_ID','CLOUDFLARE_API_TOKEN'].filter(key => typeof env[key] !== 'string' || !env[key].trim());
   if (missing.length) { const error = new Error('missing-input'); error.inputs = missing; throw error; }
@@ -48,10 +50,29 @@ export async function main(argv = process.argv.slice(2), env = process.env, {fet
     const binding = values.set ?? values.unset, item = (Array.isArray(declaration.secrets) ? declaration.secrets : []).find(entry => entry?.binding === binding);
     if (!item) { const error = new Error('undeclared-secret'); error.resource = `secret:${binding}`; throw error; }
     const value = values.set === undefined ? undefined : env[item.environment];
-    return {ok:true,...await ownerSecret({api,target,statePath,binding,value}).catch(error => { throw api.annotateFailure(error,'secrets'); })};
+    return {ok:true,...await ownerSecret({api,target,statePath,binding,value,fetch,healthOptions}).catch(error => { throw api.annotateFailure(error,'secrets'); })};
   }
   // A secret rer retired (the spent setup token) is no longer part of the plan.
-  const {retiredSecrets = []} = await settleOwnerState({api,target,statePath});
+  const state = await settleOwnerState({api,target,statePath});
+  const {retiredSecrets = []} = state;
+  if (command === 'record-owner') return withStateLock(statePath, async () => {
+    const current = await readOwnerState(statePath, target);
+    assert(current.receipt && !current.pendingUpload && !current.pendingSecret, 'missing-owner-receipt');
+    const live = await activeWorker(api, target.worker);
+    assert(live && sameDeployment(live, current.receipt.provider), 'owned-resource-replaced');
+    current.ownerClaim = { outcome: values.outcome };
+    await writeOwnerState(statePath, current);
+    return {ok:true, owner:values.outcome};
+  });
+  if (command === 'inspect') {
+    assert(!localOnlyBinding(declaration, localOnlyKeys), 'local-only-binding');
+    assert(state.receipt && !state.pendingUpload && !state.pendingSecret, 'missing-owner-receipt');
+    const live = await activeWorker(api, target.worker);
+    assert(live && sameDeployment(live, state.receipt.provider), 'owned-resource-replaced');
+    const rows = await api.request(`/workers/scripts/${target.worker}/secrets`);
+    assert(Array.isArray(rows), 'invalid-secret-list');
+    return {ok:true, origin:target.origin, versionId:live.versionId, retiredSecrets, ownerClaim:state.ownerClaim, liveSecrets:rows.map(row => row.name)};
+  }
   const current = retiredSecrets.length && Array.isArray(declaration.secrets) ? {...declaration,secrets:declaration.secrets.filter(item => !retiredSecrets.includes(item?.binding))} : declaration;
   const artifact = await ownerArtifact(root,values.product);
   const plan = ownerPlan(target,current,artifact,{localOnlyKeys});
@@ -61,11 +82,11 @@ export async function main(argv = process.argv.slice(2), env = process.env, {fet
   }
   // Dispatch is the provider's: on some accounts a new Cron starts only at the account scheduler's next refresh.
   if (plan.crons.length) notice(cronNotice);
-  const {receipt,created,sentSecrets} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions}).catch(error => {
+  const {receipt,created,sentSecrets} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions,settle}).catch(error => {
     api.annotateFailure(error,error.message.startsWith('missing-secret-') ? 'secrets' : undefined);
     throw error;
   });
-  return {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,sentSecrets,retiredSecrets,state:statePath};
+  return {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,sentSecrets,retiredSecrets,...(state.ownerClaim ? {ownerClaim:state.ownerClaim} : {}),state:statePath};
 }
 
 /** Prints refusal codes and resource names only; never inputs, tokens or provider bodies. */

package/modules/deploy-kit/owner-remove.mjs

@@ -43,7 +43,7 @@ export async function ownerRemove({api: provider, target, statePath, clock, slee
   const api = withSettledLists(withScopeHints(provider));
   return withStateLock(statePath, async () => {
     const state = await readOwnerState(statePath, target);
-    if (await settlePendingSecret(api, target.worker, state)) await writeOwnerState(statePath, state);
+    if (await settlePendingSecret(api, target.worker, state, {preflight:true})) await writeOwnerState(statePath, state);
     const owned = KINDS.flatMap(kind => Object.entries(state.owned[kind]).map(([name, entry]) => ({kind, name, entry})));
     assert(state.owned.worker || owned.length, 'nothing-to-remove');
     // Preflight, read-only.
@@ -94,7 +94,10 @@ export async function ownerRemove({api: provider, target, statePath, clock, slee
     if (remaining.length) {
       // Keep the record of what is left, so a later --remove finishes it.
       for (const kind of KINDS) for (const name of Object.keys(state.owned[kind])) if (!remaining.includes(`${kind}:${name}`)) delete state.owned[kind][name];
-      if (!remaining.includes(`worker:${target.worker}`)) { state.owned.worker = null; state.receipt = null; delete state.pendingUpload; }
+      if (!remaining.includes(`worker:${target.worker}`)) {
+        state.owned.worker = null; state.receipt = null; delete state.pendingUpload;
+        delete state.ownerClaim; delete state.retiredSecrets;
+      }
       await writeOwnerState(statePath, state);
       const error = new Error('remove-incomplete'); error.remaining = remaining; error.failed = failed; error.removed = removed;
       throw error;

package/modules/deploy-kit/owner-secret.mjs

@@ -1,49 +1,94 @@
 import { assert, identifier } from './validation.mjs';
-import { activeWorker, deployedFingerprint } from './worker.mjs';
+import { activeWorker } from './worker.mjs';
+import { waitHealth } from './health-request.mjs';
+import { definiteProviderRefusal } from './provider.mjs';
 import { readOwnerState, writeOwnerState, withStateLock, withScopeHints, sameDeployment, refuse, recordSecretChange, settlePendingSecret } from './owner.mjs';
 
 /** Set (`value` given) or remove one Worker secret of the owner's last deployment, then
  * record the Worker version the change made in the state file, so the next deploy
  * recognises its own Worker. A Worker someone else replaced is refused untouched.
  * The change is recorded as pending first: if the provider applies it but rer never
- * sees it settle, a later run adopts it (see settlePendingSecret). A change the provider
- * answered with an error clears the pending record. The secret listing
- * and active deployment lag a change, so they are read until they show it, up to `windowMs`.
+ * sees it settle, a later run can recognise its immediate successor (see settlePendingSecret).
+ * Both success and ambiguous failure read back for up to `windowMs`. An explicit refusal
+ * clears the pending record. An accepted write keeps its intent until confirmed.
+ * An ambiguous failure clears it only when readback corroborates that the receipt's
+ * deployment is still live. An ambiguous rotation
+ * re-PUTs the value before accepting its successor as proof of the rotation.
  * A removed declared secret is retired: later plans omit it until it is set again. */
-export async function ownerSecret({api: provider, target, statePath, binding, value, windowMs = 30000, clock = () => performance.now(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms))}) {
+export async function ownerSecret({api: provider, target, statePath, binding, value, fetch = globalThis.fetch, healthOptions = {}, windowMs = 30000, clock = () => performance.now(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms))}) {
   const api = withScopeHints(provider);
   assert(identifier(binding), 'invalid-secret-name');
   assert(value === undefined || typeof value === 'string' && value.trim(), `missing-secret-${binding}`);
   return withStateLock(statePath, async () => {
     const state = await readOwnerState(statePath, target);
     assert(state.receipt && !state.pendingUpload, 'missing-owner-receipt');
-    if (await settlePendingSecret(api, target.worker, state)) await writeOwnerState(statePath, state);
+    if (await settlePendingSecret(api, target.worker, state, {preflight:true})) await writeOwnerState(statePath, state);
     const live = await activeWorker(api, target.worker);
     if (!live) throw refuse('owned-resource-missing', 'worker', target.worker);
     if (!sameDeployment(live, state.receipt.provider)) throw refuse('owned-resource-replaced', 'worker', target.worker);
     const path = `/workers/scripts/${target.worker}/secrets`, present = value !== undefined;
     const names = async () => { const rows = await api.request(path); assert(Array.isArray(rows), 'invalid-secret-list'); return rows.map(row => row.name); };
-    const changed = present || (await names()).includes(binding);
-    state.pendingSecret = {binding, present}; await writeOwnerState(statePath, state);
+    const existed = (await names()).includes(binding), changed = present || existed;
+    state.pendingSecret = {binding, present, versionId:state.receipt.provider.versionId}; await writeOwnerState(statePath, state);
+    let failure, unchanged = false, confirming = false;
+    const put = () => api.request(path, {method:'PUT', body:{name:binding, text:value, type:'secret_text'}});
     try {
-      if (present) await api.request(path, {method:'PUT', body:{name:binding, text:value, type:'secret_text'}});
+      if (present) await put();
       else if (changed) await api.request(`${path}/${binding}`, {method:'DELETE'});
     } catch (error) {
-      // The provider answered and refused: nothing changed, so nothing is pending. Only a lost
-      // response (no answer at all) may have applied the change.
-      if (error.status !== undefined) { delete state.pendingSecret; await writeOwnerState(statePath, state); }
-      throw error;
+      if (definiteProviderRefusal(error)) { delete state.pendingSecret; await writeOwnerState(statePath, state); throw error; }
+      failure = error;
     }
-    let current;
-    for (const start = clock(); ; await sleep(2000)) {
-      current = await activeWorker(api, target.worker);
-      if (current && (!changed || !sameDeployment(current, live)) && (await names()).includes(binding) === present) break;
-      if (clock() - start + 2000 > windowMs) throw new Error('secret-change-unsettled');
+    try {
+      if (!changed) recordSecretChange(state, live, state.pendingSecret);
+      else for (const start = clock(); ; await sleep(2000)) {
+        try {
+          if (await settlePendingSecret(api, target.worker, state, {
+            observe: current => { unchanged = sameDeployment(current, state.receipt.provider); },
+            ...(failure && present && existed ? {confirm: async current => {
+              confirming = true;
+              state.pendingSecret.repeatVersionId = current.versionId;
+              await writeOwnerState(statePath, state);
+              await put();
+              confirming = false;
+            }} : {})
+          })) break;
+        }
+        catch (error) {
+          unchanged = false;
+          // Another ambiguous PUT cannot prove a rotation by presence either.
+          // Keep both starting versions for recovery; do not report it done.
+          if (confirming) throw error;
+          if (error.message !== 'provider-transport-failed' && !(error.status >= 500 && error.status < 600)) throw error;
+        }
+        if (clock() - start + 2000 > windowMs) throw failure ?? new Error('secret-change-unsettled');
+      }
+    } catch (error) {
+      if (unchanged && failure) delete state.pendingSecret;
+      await writeOwnerState(statePath, state);
+      throw failure ?? error;
     }
-    // A secret change makes a new version of the same code: the script and build fingerprint must not move.
-    assert(current.etag === live.etag && deployedFingerprint(current.settings) === deployedFingerprint(live.settings), 'secret-change-drift');
-    recordSecretChange(state, current, {binding, present});
+    const result = {worker:target.worker, binding, present, versionId:state.receipt.provider.versionId};
+    // Settlement is durable before readiness: a failed hosted check must never
+    // erase the applied mutation or cause the next command to reject our version.
+    state.receipt.health = {ok:false,versionId:result.versionId};
     await writeOwnerState(statePath, state);
-    return {worker:target.worker, binding, present, versionId:current.versionId};
+    try {
+      if (state.receipt.origin) await waitHealth({
+        origin:state.receipt.origin, receipt:state.receipt, versionId:result.versionId, request:fetch,
+        timeoutMs:healthOptions.timeoutMs,
+        clock:healthOptions.now, sleep:healthOptions.sleep, ...healthOptions.readiness,
+      });
+      const after = await activeWorker(api, target.worker);
+      assert(after && sameDeployment(after, state.receipt.provider), 'deployment-changed-during-health');
+      // Response prefixes belong only in the caller's redacted diagnostic, never
+      // in the ownership record: an unhealthy app may accidentally echo a secret.
+      state.receipt.health = {ok:true,versionId:result.versionId};
+      await writeOwnerState(statePath, state);
+      return result;
+    } catch (error) {
+      error.secretChange = result;
+      throw error;
+    }
   });
 }