@runeditrun/rer 0.2.1 → 0.2.2

package/README.md

@@ -22,8 +22,11 @@ refuses archives with absolute paths, `..` entries, links or devices, then runs
 the package's own `rer cli install`. A failed or refused download leaves the
 version you had selected.
 
-No installer edits shell profiles. When `~/.local/bin` is not on your PATH, the
-install prints the exact line to add for your shell. The launcher runs `node` from
+No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
+When that directory is absent from PATH, installation also links it into an
+existing writable, user-owned PATH directory if available, preserving foreign
+commands. Otherwise it prints one activation line to run in the current shell:
+`export PATH="$HOME/.local/bin:$PATH"` (with fish syntax for fish). The launcher runs `node` from
 PATH, so a Node upgrade does not break it. A re-run with the same build changes
 nothing; a different build is installed beside the current one, the previous one
 is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
@@ -267,3 +270,10 @@ Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
 `rer queue NAME -- COMMAND`, `rer --version` and `rer --help`.
 
 Licence: MIT.
+
+First-party commands acquire the exact `packageManager` pnpm pin when PATH lacks
+it, verify its registry sha512 integrity and cache it under `$HOME/.rer/pnpm`.
+No global package manager installation or sudo is needed. Independent projects
+continue to run their declared commands with their own tools. Server and job
+state default to `$HOME/.rer/servers` and `$HOME/.rer/jobs`; supplied
+`RER_SERVERS_DIR` and `RER_JOBS_DIR` take precedence and are passed to older pins.

package/cli/auth-copy.mjs

@@ -7,16 +7,17 @@ import { contained } from './project.mjs';
 // bytes of the Base revision it pinned. A seed records its copies in
 // base-copies.json (edition authoring) or composition.lock.json /
 // foundation.lock.json (composed foundations); each records the SHA-256 of the
-// Base bytes it copied. Two groups are checked on their own: the application,
-// runtime and schema copies (one revision pins them all, since they are coupled)
-// and the CLI's bundled tooling under scripts/base-cli (one revision of its
-// own, which a CLI refresh moves without touching the application's auth). Each
-// drifted, missing or unrecorded file in either group is named. A seed that
-// imports Base in place has no copy.
+// Base bytes it copied. Application runtime and schema sources share one pin;
+// the CLI's bundled tooling has its own. Numbered SQL under migrations keeps
+// its historical revision independently: refreshing runtime must not rewrite
+// SQL a database may already have applied. Every copy still needs a valid pin
+// and exact bytes. A seed that imports Base in place has no copy.
 const ORIGIN = 'modules/operator-auth';
 const CLI_ROOT = 'scripts/base-cli';
 const within = (path, prefix) => path === prefix || path.startsWith(`${prefix}/`);
-const groupOf = path => typeof path === 'string' && within(path, CLI_ROOT) ? 'cli' : 'application';
+const groupOf = path => typeof path === 'string' && within(path, CLI_ROOT) ? 'cli'
+ : /(?:^|\/)migrations\/(?:[^/]+\/)*\d+[^/]*\.sql$/.test(path) ? 'migration' : 'application';
+const pinned = revision => typeof revision === 'string' && /^[a-f0-9]{40}$/.test(revision);
 const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
 async function json(root, path) { try { return JSON.parse(await readFile(await contained(root, path), 'utf8')); } catch { return null; } }
 
@@ -30,22 +31,24 @@ async function walk(root, path) {
  return files;
 }
 
-// [{ group, path, revision, files: { local path: sha256 } }] for every recorded auth copy.
+// [{ path, revision, files: { local path: sha256 } }] for every recorded auth copy.
 async function recordedCopies(root) {
  const copies = [];
  const record = await json(root, 'base-copies.json');
  for (const copy of record?.copies ?? []) {
-  if (typeof copy?.originPath === 'string' && within(copy.originPath, ORIGIN) && copy.files && typeof copy.files === 'object') copies.push({ path: copy.path, revision: copy.revision, files: copy.files, directory: copy.originPath === ORIGIN, group: groupOf(copy.path) });
+  if (typeof copy?.originPath !== 'string' || !within(copy.originPath, ORIGIN)) continue;
+  const files = copy.files && typeof copy.files === 'object' && !Array.isArray(copy.files) ? copy.files : {};
+  copies.push({ path: copy.path, revision: copy.revision, files, directory: copy.originPath === ORIGIN || Object.keys(files).some(path => path !== copy.path && within(path, copy.path)) });
  }
  for (const name of ['composition.lock.json', 'foundation.lock.json']) {
   const lock = await json(root, name);
   if (!lock?.files) continue;
   const revision = lock.repositories?.base?.commit ?? lock.base?.commit;
-  for (const group of ['application', 'cli']) {
-   const entries = Object.entries(lock.files).filter(([path, file]) => groupOf(path) === group && typeof file?.source === 'string' && within(file.source, ORIGIN));
-   const files = Object.fromEntries(entries.filter(([, file]) => typeof file.sha256 === 'string').map(([path, file]) => [path, file.sha256]));
+  for (const cli of [false, true]) {
+   const entries = Object.entries(lock.files).filter(([path, file]) => (groupOf(path) === 'cli') === cli && typeof file?.source === 'string' && within(file.source, ORIGIN));
+   const files = Object.fromEntries(entries.map(([path, file]) => [path, file.sha256]));
    const directories = [...new Set(entries.filter(([, file]) => !file.source.endsWith('.sql')).map(([path, file]) => path.slice(0, path.length - (file.source.length - ORIGIN.length))))];
-   if (Object.keys(files).length) copies.push({ path: directories[0] ?? null, revision, files, directory: directories.length === 1, group });
+   if (Object.keys(files).length) copies.push({ path: directories[0] ?? null, revision, files, directory: directories.length === 1 });
   }
  }
  return copies;
@@ -55,18 +58,22 @@ export async function authCopyClauses(root) {
  const copies = await recordedCopies(root);
  if (!copies.length) return [];
  const clauses = [];
- for (const [group, id, scope] of [['application', 'SC-05.auth-copy.pin', 'the application, runtime and schema copies'], ['cli', 'SC-05.auth-copy.cli-pin', `the CLI's bundled copy under ${CLI_ROOT}`]]) {
-  const grouped = copies.filter(copy => copy.group === group);
+ for (const [group, id, scope] of [['application', 'SC-05.auth-copy.pin', 'the application runtime and schema sources'], ['cli', 'SC-05.auth-copy.cli-pin', `the CLI's bundled copy under ${CLI_ROOT}`]]) {
+  const grouped = copies.filter(copy => Object.keys(copy.files).some(path => groupOf(path) === group));
   if (!grouped.length) continue;
   const revisions = [...new Set(grouped.map(copy => copy.revision))];
-  clauses.push([id, revisions.length === 1 && /^[a-f0-9]{40}$/.test(revisions[0] ?? ''), `Copy ${scope} of operator-auth from one pinned Base revision; the seed records ${revisions.join(', ') || 'none'}.`]);
+  clauses.push([id, revisions.length === 1 && pinned(revisions[0]), `Copy ${scope} of operator-auth from one pinned Base revision; the seed records ${revisions.join(', ') || 'none'}.`]);
  }
  for (const copy of copies) {
+  if (!Object.keys(copy.files).length) clauses.push([`SC-05.auth-copy.${copy.path}`, false, `${copy.path} has no recorded bytes; record its copied files and their SHA-256 digests.`]);
   for (const [path, expected] of Object.entries(copy.files)) {
+   if (groupOf(path) === 'migration') clauses.push([`SC-05.auth-copy.migration-pin.${path}`, pinned(copy.revision), `${path} must retain a valid pinned Base revision for its historical SQL; the seed records ${copy.revision ?? 'none'}.`]);
    let actual = null; try { actual = sha256(await readFile(await contained(root, path))); } catch {}
-   clauses.push([`SC-05.auth-copy.${path}`, actual === expected, actual === null
+   clauses.push([`SC-05.auth-copy.${path}`, actual !== null && actual === expected, actual === null
     ? `${path} is missing; restore it from Base ${copy.revision}.`
-    : `${path} differs from Base ${copy.revision}; restore the copied bytes or record a new pin with refresh-base.`]);
+    : groupOf(path) === 'migration'
+     ? `${path} differs from Base ${copy.revision}; restore its historical bytes and put schema changes in a new migration.`
+     : `${path} differs from Base ${copy.revision}; restore the copied bytes or record a new pin with refresh-base.`]);
   }
   if (copy.directory && copy.path) {
    for (const path of await walk(root, copy.path)) {

package/cli/bounded.mjs

@@ -16,7 +16,7 @@ export async function boundedCommand(project,options,argv,out){
  const policy=await commandPolicy();
  const childArgs=[...argv];const cwdIndex=childArgs.indexOf('--cwd');if(cwdIndex>=0&&(childArgs.indexOf('--')<0||cwdIndex<childArgs.indexOf('--')))childArgs[cwdIndex+1]=project.root;
  const directory=await mkdtemp(join(tmpdir(),'rer-bounded-'));
- let store,result,finalEvent,errorEvent,buffer='';
+ let store,result,finalEvent,errorEvent,buffer='';const unclosed=[];
  const cancellation=new AbortController();
  const handlers=new Map(['SIGINT','SIGTERM'].map(name=>[name,()=>cancellation.abort(name)]));
  for(const [name,handler] of handlers)process.on(name,handler);
@@ -47,11 +47,18 @@ export async function boundedCommand(project,options,argv,out){
      const held=await recoverInterrupted(project.root);await held?.release();
     }
    }
+  }).catch(error=>{
+   // The workflow already reported its outcome; only stopping its process group
+   // failed. Keep that outcome, and say so, instead of losing it.
+   if(!finalEvent||cancellation.signal.aborted)throw error;
+   unclosed.push(error);return {code:finalEvent.exitCode};
   });
  }finally{
-  try{await store?.closeCommands();await policy.close();await rm(directory,{recursive:true,force:true});}
-  finally{for(const [name,handler] of handlers)process.off(name,handler);}
+  // Every closer runs: a policy socket left listening keeps this process alive.
+  for(const close of [()=>store?.closeCommands(),()=>policy.close(),()=>rm(directory,{recursive:true,force:true})]){try{await close();}catch(error){unclosed.push(error);}}
+  for(const [name,handler] of handlers)process.off(name,handler);
  }
+ if(unclosed.length)out.progress(`Local cleanup could not confirm that every helper process stopped (${unclosed.map(error=>store?.redact?.(String(error?.message))??'unknown cause').join('; ')}). The ${options.verb} itself finished.\n`);
  const termination=cancellation.signal.aborted?cancellation.signal.reason:undefined;
  if(!result&&!termination)return null;
  const exitCode=termination?(termination==='SIGINT'?130:143):result.code;
@@ -61,7 +68,9 @@ export async function boundedCommand(project,options,argv,out){
  }else if(finalEvent&&finalEvent.exitCode===exitCode){
   if(errorEvent)out.error(new RerError(errorEvent.code,store.redact(errorEvent.message),exitCode));
   const {version,verb,event,ok,exitCode:childExit,...details}=finalEvent;
-  out.result(exitCode===0,exitCode,JSON.parse(store.redact(JSON.stringify(details))));
+  // Redaction can cut through a value that matches a credential; the outcome stands without its details.
+  let shown;try{shown=JSON.parse(store.redact(JSON.stringify(details)));}catch{shown={};}
+  out.result(exitCode===0,exitCode,shown);
  }else{
   const error=new RerError('command_failed',result.supervisorEnded?store.redact(result.error):'Bounded command ended before its result; owned children and private files were recovered.',exitCode||1);
   out.error(error);out.result(false,error.exitCode);return {exitCode:error.exitCode};

package/cli/contract.mjs

@@ -11,7 +11,7 @@ const definitions = {
  build: [['--site'], 'Production build with private local settings excluded and restored. --site instead writes the static run site (homepage, /run, docs) to its declared folder and prints that folder.'],
  verify: [[], 'Run the complete internal verification target.'],
  reset: [['--yes'], 'Confirmed removal of the declared local inventory only.'],
- deploy: [['--environment', '--dry-run', '--site', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port'], 'Owner-account deployment and health; dry run performs local validation/build only. --site deploys the run site instead: an assets-only Worker on its custom domain with www redirected; with --dry-run it builds the site and prints the plan with no provider request.'],
+ deploy: [['--environment', '--dry-run', '--site', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port', '--remove', '--yes', '--set-secret', '--unset-secret'], 'Owner-account deployment and health; dry run performs local validation/build only. Declared secrets come from the environment or --env-file (an owned 0600 KEY=VALUE file); a new Worker gets the local setup owner and fresh generated secrets when they are not given. After a healthy deploy rer claims the setup owner on the hosted app with the one-time setup token, then removes the token. --set-secret NAME (value from the environment or --env-file) and --unset-secret NAME change one secret of the deployed Worker without a build and record its new version. --remove --yes deletes what this environment\'s deploy record says rer created (Worker, D1, R2, KV, queues), reads back that each is gone, and touches nothing else. --site deploys the run site instead: an assets-only Worker on its custom domain with www redirected; with --dry-run it builds the site and prints the plan with no provider request.'],
  export: [['--target', '--output', '--origin', '--session-file'], 'Complete supported installation archive with integrity and exclusions.'],
  import: [['--target', '--input', '--journal', '--origin', '--session-file', '--yes', '--legacy-v1', '--acknowledge-unverified-metadata', '--output'], 'Confirmed atomic restore into an empty destination; --journal LATER_ARCHIVE also fences rows that installation erased since. Backup-only local v1 recovery requires --legacy-v1 --acknowledge-unverified-metadata and a new --output v2 archive; --journal requires normal v2 import.'],
  outbox: [['--port', '--host', '--owner-email', '--open'], 'Credential-free local outbox URL; optional ordinary sign-in request and explicit browser opening.'],

package/cli/deploy-inputs.mjs

@@ -0,0 +1,33 @@
+import { randomBytes } from 'node:crypto';
+import { shared } from './shared.mjs';
+import { invalid } from './errors.mjs';
+import { readDeployEnvFile } from '../modules/deploy-kit/env-file.mjs';
+
+// The values a Workers deploy reads for its declared secrets: this process's
+// environment, then the --env-file (which wins), then what rer supplies itself:
+// the local setup owner's email, and a fresh value for each secret the setup
+// manifest generates (a session secret, the one-time setup token). A value only
+// reaches a Worker that lacks that secret; an existing one is kept unchanged.
+export async function deployEnvironment({ root, options, declaration, setupManifest, settings, localOnlyKeys = [] }) {
+ const env = { ...process.env }, supplied = [];
+ if (options.envFile) {
+  let values;
+  try { values = await readDeployEnvFile(root, options.envFile, localOnlyKeys); }
+  catch (error) { throw invalid(`The --env-file ${options.envFile} could not be used: ${error.code === 'ENOENT' ? 'no such file' : error.message}.`); }
+  Object.assign(env, values);
+ }
+ const secrets = Array.isArray(declaration.secrets) ? declaration.secrets : [];
+ const absent = item => item && !env[item.environment]?.trim();
+ const emailField = setupManifest?.steps?.find(step => step.type === 'owner-claim')?.emailField;
+ const email = secrets.find(item => item?.binding === emailField);
+ if (absent(email) && settings) {
+  const { readSettings } = await shared('adapter-settings.mjs');
+  const owner = (await readSettings(root, settings)).values[emailField];
+  if (typeof owner === 'string' && owner.includes('@')) { env[email.environment] = owner; supplied.push(email.binding); }
+ }
+ for (const field of setupManifest?.fields ?? []) {
+  const item = field.kind === 'secret' && field.generate ? secrets.find(entry => entry?.binding === field.name) : undefined;
+  if (absent(item)) { env[item.environment] = randomBytes(32).toString(field.generate); supplied.push(item.binding); }
+ }
+ return { env, supplied };
+}

package/cli/deploy-owner.mjs

@@ -0,0 +1,61 @@
+import { randomBytes } from 'node:crypto';
+
+// After a healthy deploy, the hosted app's first owner is the setup owner: rer
+// claims it with the one-time setup token through the seed's standard owner step
+// (Base operator-auth POST /auth/bootstrap), then removes that token from the
+// Worker and records the new Worker version. A Worker still holding a token rer
+// did not upload this run gets a fresh one first, unless the person supplied the
+// token (environment or --env-file): that value is the deployed token and is used. A seed with its own owner step
+// function, an identity-provider claim, or no declared token secret is left to it.
+// `beforeClaim(token)` runs while the token is live (dependency approvals need it).
+export async function claimHostedOwner({ hook, setupManifest, declaration, deployed, env, supplied = [], secret, addSecret, beforeClaim, fetch = globalThis.fetch, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), boundMs = 90000 }) {
+ if (!hook || typeof hook !== 'object' || Array.isArray(hook) || !deployed.origin) return undefined;
+ const claim = setupManifest?.steps?.find(step => step.type === 'owner-claim');
+ if (claim?.mode === 'idp') return undefined;
+ const tokenKey = hook.tokenKey ?? claim?.tokenField ?? 'SETUP_TOKEN';
+ const item = (Array.isArray(declaration.secrets) ? declaration.secrets : []).find(entry => entry?.binding === tokenKey);
+ if (!item || deployed.retiredSecrets?.includes(tokenKey)) return undefined;
+ const given = env[item.environment]?.trim() && !supplied.includes(tokenKey);
+ let token = deployed.sentSecrets?.includes(tokenKey) || given ? env[item.environment] : undefined;
+ if (!token) {
+  token = randomBytes(32).toString('hex'); addSecret(token);
+  const { versionId } = await secret(['--set', tokenKey], { ...env, [item.environment]: token });
+  // A secret change is a new Worker version; claim once the app answers from it.
+  await servingVersion({ origin: deployed.origin, versionId, fetch, sleep, boundMs });
+ }
+ await beforeClaim?.(token);
+ const displayName = (typeof hook.displayName === 'function' ? hook.displayName({}) : undefined) || 'Owner';
+ let response, code;
+ // Edge locations can briefly answer from the previous version, which lacks this token.
+ for (let attempt = 1; ; attempt++) {
+  try {
+   response = await fetch(new URL(hook.path ?? '/auth/bootstrap', deployed.origin), { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(30000),
+    headers: { Origin: deployed.origin, 'Content-Type': 'application/json' }, body: JSON.stringify({ token, displayName, returnTo: hook.returnTo ?? '/' }) });
+  } catch { throw ownerFailure('the hosted application did not answer'); }
+  code = 'no code';
+  if (response.status !== 303) { try { const body = await response.json(); if (typeof body?.error === 'string' && /^[a-z_]{1,64}$/.test(body.error)) code = body.error; } catch {} }
+  else await response.body?.cancel();
+  if (response.status !== 403 || code !== 'invalid_setup_token' || attempt === 3) break;
+  await sleep(5000);
+ }
+ const outcome = response.status === 303 ? 'claimed' : response.status === 409 && code === 'already_initialized' ? 'kept' : undefined;
+ if (!outcome) throw ownerFailure(`HTTP ${response.status} (${code})${code === 'invalid_setup_token' && given ? `; the ${item.environment} you supplied is not the deployed setup token: leave it unset and rer issues a fresh one` : ''}`);
+ await secret(['--unset', tokenKey], env);
+ return outcome;
+}
+
+async function servingVersion({ origin, versionId, fetch, sleep, boundMs }) {
+ const deadline = Date.now() + boundMs;
+ while (true) {
+  try {
+   const response = await fetch(new URL('/health', origin), { redirect: 'manual', signal: AbortSignal.timeout(10000), headers: { 'Cache-Control': 'no-cache', Accept: 'application/json' } });
+   if ((await response.json().catch(() => null))?.deployment?.versionId === versionId) return;
+  } catch {}
+  if (Date.now() >= deadline) throw ownerFailure(`the hosted app did not answer from the Worker version holding the new setup token within ${Math.round(boundMs / 1000)} seconds`);
+  await sleep(2000);
+ }
+}
+
+function ownerFailure(cause) {
+ const error = new Error('owner-claim-failed'); error.cause = cause; return error;
+}

package/cli/deploy.mjs

@@ -1,24 +1,33 @@
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
 import { deployDiagnostic } from '../modules/deploy-kit/diagnostics.mjs';
 import { shared } from './shared.mjs';
 import { contained } from './project.mjs';
-import { missing, invalid, refuse } from './errors.mjs';
+import { missing, invalid, refuse, RerError } from './errors.mjs';
 import { ownerPlan, ownerWorkerName, localOnlyBinding } from '../modules/deploy-kit/owner.mjs';
 import { packageBuild } from '../modules/deploy-kit/prepare.mjs';
 import { refuseLocalModels } from '../modules/deploy-kit/local-only.mjs';
+import { deployEnvironment } from './deploy-inputs.mjs';
+import { claimHostedOwner } from './deploy-owner.mjs';
 
 export function ownerDeploy(declarationPath, lifecycle) {
  // rer verify serves the build with this declaration's vars and secrets.
- return Object.assign(async ({ root, options, store, signal, operationToken, localOnlyKeys = [], checkBuild = async () => {} }) => {
+ return Object.assign(async ({ root, options, store, signal, operationToken, localOnlyKeys = [], checkBuild = async () => {}, setupManifest, linkDependencies }) => {
   try { await refuseLocalModels(root); } catch { throw refuse('Deploy refuses the local-only key file .rer/local/models.json. Remove live-dev credentials before deployment.'); }
   const path = await contained(root, declarationPath);
   let declaration; try { declaration = JSON.parse(await readFile(path, 'utf8')); } catch { throw invalid('Malformed owner-account deploy declaration.'); }
   const local = localOnlyBinding(declaration, localOnlyKeys);
   if (local) throw refuse(`${declarationPath} names the local-only key ${local} as a deploy binding or secret. Remove it; local dev keys never reach a deployment.`);
   const environment = options.environment ?? 'production';
-  await lifecycle.run(root, {}, store, () => {}, signal, { verb: 'build', operationToken });
-  await checkBuild();
+  const again = `rer deploy --environment ${environment}`;
+  const change = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret'].filter(Boolean);
+  // The command that finishes what this run started: the same verb, never a plain deploy in its place.
+  const retry = options.remove ? `${again} --remove --yes` : options.setSecret ? `${again} --set-secret ${options.setSecret}` : options.unsetSecret ? `${again} --unset-secret ${options.unsetSecret}` : again;
+  if (change.length > 1 || change.length && options.dryRun) throw invalid(`Use ${change.join(', ')}${options.dryRun ? ' and --dry-run' : ''} on separate runs.`);
+  if (options.remove && !options.yes) throw invalid(`${again} --remove deletes this environment's Worker and every D1, R2, KV and queue rer created for it, with their data. Add --yes to confirm.`);
+  if (!change.length) {
+   await lifecycle.run(root, {}, store, () => {}, signal, { verb: 'build', operationToken });
+   await checkBuild();
+  }
   if (options.dryRun) {
    // Locally validate the real declaration/artifact without ownerTarget's
    // account lookup. This synthetic target is validation data, not a provider.
@@ -30,22 +39,85 @@ export function ownerDeploy(declarationPath, lifecycle) {
   }
   const names = ['CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN'];
   if (names.some(name => !process.env[name]?.trim())) throw missing('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required. See the deploy-kit owner-account instructions.');
+  const { env, supplied } = await deployEnvironment({ root, options, declaration, setupManifest, settings: lifecycle.settings, localOnlyKeys });
   const { main } = await import('../modules/deploy-kit/owner-cli.mjs');
-  const argv = ['deploy', '--declaration', declarationPath, '--environment', environment];
-  const {createRedaction,credentialValues} = await shared('redaction.mjs');
+  const { createRedaction, credentialValues } = await shared('redaction.mjs');
   const redaction = createRedaction();
-  redaction.addSecrets([...credentialValues(process.env),process.env.CLOUDFLARE_ACCOUNT_ID,...(declaration.secrets ?? []).map(item=>process.env[item.environment]).filter(Boolean)]);
+  redaction.addSecrets([...credentialValues(env), env.CLOUDFLARE_ACCOUNT_ID, ...(declaration.secrets ?? []).map(item => env[item.environment]).filter(Boolean)]);
+  const claim = setupManifest?.steps?.find(item => item.type === 'owner-claim');
+  const declared = binding => (Array.isArray(declaration.secrets) ? declaration.secrets : []).find(item => item?.binding === binding);
+  const owner = (command, extra = [], values = env, more = {}) => main([command, '--declaration', declarationPath, '--environment', environment, ...extra], values, { cwd: root, localOnlyKeys, ...more });
   // Keep confirmed creation events across deploy and the independent health call.
   const created = [];
+  let step = 'deploy', deployed;
   try {
-   const result = await main(argv, process.env, { cwd: root, localOnlyKeys, notice: line => store.report(line), onCreated: resource => created.push(redaction.redact(resource)) });
-   await main(['health', ...argv.slice(1)], process.env, { cwd: root, localOnlyKeys });
-   return { deployed: true, origin: result.origin };
+   if (options.remove) {
+    step = 'remove';
+    const result = await owner('remove');
+    store.report(`Removed ${result.removed.join(', ') || 'nothing (already gone)'}; read back: none of them remains.`);
+    return { removed: result.removed, deployed: false };
+   }
+   if (change.length) {
+    step = 'secrets';
+    const binding = options.setSecret ?? options.unsetSecret;
+    await owner('secret', [options.setSecret ? '--set' : '--unset', binding]);
+    store.report(`${options.setSecret ? `Set ${binding}` : `Removed ${binding}`} on this environment's Worker and recorded its new version; the next ${again} updates it.`);
+    return { binding, present: Boolean(options.setSecret), deployed: false };
+   }
+   deployed = await owner('deploy', [], env, { notice: line => store.report(line), onCreated: resource => created.push(redaction.redact(resource)) });
+   const sent = supplied.filter(name => deployed.sentSecrets.includes(name));
+   if (sent.length) store.report(`rer supplied ${sent.join(', ')} from the local setup owner and fresh generated values.`);
+   step = 'health';
+   await owner('health');
+   step = 'claim owner';
+   const linked = token => linkDependencies?.(deployed.origin, token);
+   const claimed = await claimHostedOwner({ hook: lifecycle.hooks?.owner, setupManifest, declaration, deployed, env, supplied, addSecret: value => redaction.addSecrets([value]),
+    secret: (extra, values) => owner('secret', extra, values), beforeClaim: linked });
+   // A seed that claims its owner its own way links with the token it was given.
+   if (claimed === undefined) await linked(env[declared(claim?.tokenField ?? 'SETUP_TOKEN')?.environment]);
+   // The app claims the OWNER_EMAIL the Worker holds: the local one only when this run uploaded it.
+   const email = declared(claim?.emailField);
+   const named = !email ? '' : deployed.sentSecrets.includes(email.binding) && env[email.environment] ? ` (${env[email.environment]})` : ` (the ${email.binding} already set on the Worker)`;
+   if (claimed) store.report(`${claimed === 'claimed' ? 'Claimed the hosted owner' : 'The hosted owner was already claimed and was kept'}${named}; the one-time setup token was used and removed. Sign in by email at ${deployed.origin}.`);
+   return { deployed: true, origin: deployed.origin, ...(claimed ? { owner: claimed } : {}), dependenciesLinked: true };
   } catch (error) {
-   const diagnostic = deployDiagnostic(error,redaction.redact);
-   const code = /^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? redaction.redact(error.message) : 'deploy-failed';
-   const {commandFailure} = await shared('failures.mjs');
-   throw commandFailure(`Deploy failed at ${diagnostic?.step ?? 'prepare deploy'}: ${diagnostic?.code ?? code}${diagnostic?.providerCodes?.length ? ` (provider ${diagnostic.providerCodes.join(', ')})` : ''}.\nFirst redacted output lines:\n${diagnostic?.output ?? '(no provider output)'}\nResources created this attempt: ${created.join(', ') || 'none recorded'}.`);
+   if (error instanceof RerError) throw error;
+   const { commandFailure } = await shared('failures.mjs');
+   throw commandFailure(failureText({ error, step, created, again, retry, secretChange: Boolean(change.length && !options.remove), deployed, redact: redaction.redact }));
   }
  }, { declaration: declarationPath });
 }
+
+// The failing step, its redacted cause, what this run created and the command that continues.
+function failureText({ error, step, created, again, retry, secretChange, deployed, redact }) {
+ const diagnostic = deployDiagnostic(error, redact);
+ const code = diagnostic?.code ?? (/^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? redact(error.message) : 'deploy-failed');
+ const at = step === 'deploy' ? diagnostic?.step ?? 'prepare deploy' : step;
+ const input = /^missing-secret-([A-Z][A-Z0-9_]*)$/.exec(code)?.[1];
+ if (input) return `Deploy needs ${input}, which the deploy declaration lists as a secret and the Worker does not hold it. Set ${input} in the environment or in an --env-file file (an owned 0600 file of KEY=VALUE lines), then run the same command again. Nothing was uploaded.${created.length ? ` Resources created this attempt: ${created.join(', ')}.` : ''}`;
+ if (code === 'remove-incomplete') return `Removal stopped with ${error.remaining.join(', ')} still present${error.failed.length ? ` (${error.failed.map(item => `${item.resource}: ${item.code}`).join('; ')})` : ''}. Removed: ${error.removed.join(', ') || 'nothing'}. An R2 bucket must be empty before it can be deleted. Run ${again} --remove --yes again to finish.`;
+ if (code === 'nothing-to-remove') return `This checkout has no rer deployment record for this environment, so --remove deletes nothing. Run it from the checkout that deployed it.`;
+ if (code === 'owner-claim-failed') return `The application is deployed at ${deployed?.origin}, but claiming its owner failed: ${redact(String(error.cause))}. The setup token is still on the Worker; run ${again} again to retry the claim.`;
+ const resource = diagnostic?.resource ?? (error.resource ? redact(String(error.resource)) : undefined);
+ const lines = [`Deploy failed at ${at}: ${code}${resource ? ` (${resource})` : ''}${diagnostic?.providerCodes?.length ? ` (provider ${diagnostic.providerCodes.join(', ')})` : ''}.`];
+ if (diagnostic?.output && diagnostic.output !== '(no provider output)') lines.push(`First redacted output lines:\n${diagnostic.output}`);
+ lines.push(`Resources created this attempt: ${created.join(', ') || 'none'}.`);
+ lines.push(recovery({ code, at, resource, again, retry, secretChange }));
+ return lines.join('\n');
+}
+
+function recovery({ code, at, resource, again, retry, secretChange }) {
+ const remove = `${again} --remove --yes`, removing = retry === remove;
+ if (code === 'owned-resource-replaced' || code === 'resource-name-collision') return `rer refuses to change a resource it did not create or that was replaced after it did; nothing was changed. Choose another --environment name, or remove the other resource yourself.`;
+ // A lost create answer: the resource may exist, and rer cannot prove it made it.
+ if (resource && (code === 'uncertain-resource-create' || code === 'provider-transport-failed' && at.startsWith('create '))) {
+  if (resource.startsWith('worker:')) return `Possibly created: ${resource}. The answer to its first upload was lost and the live Worker does not match the build rer sent, so rer cannot prove it is its own. Deploy the same commit again to recover it, or inspect it in the Cloudflare dashboard: if it is the Worker from the interrupted run and its Durable Object data is disposable, delete it, then run ${retry} again.`;
+  return `Possibly created: ${resource}. The provider's answer to its create was lost, so rer cannot prove it made it. Inspect it in the Cloudflare dashboard: if it exists and is the empty one from the interrupted run, delete it, then run ${retry} again.${removing || resource.startsWith('queues:') ? '' : ` Or run ${remove}: it deletes it once it confirms it is empty, together with everything else this environment created.`}`;
+ }
+ if (code === 'uncertain-resource-not-empty') return `Possibly created: ${resource}, but it holds data, so it may not be the one rer's interrupted run made and rer will not delete it. Inspect it in the Cloudflare dashboard; delete it yourself only if its data is disposable, then run ${retry} again.`;
+ if (code === 'uncertain-resource-unverifiable') return `Possibly created: ${resource}. rer cannot read whether a queue holds messages, so it will not delete it. Inspect it in the Cloudflare dashboard: if it is the empty one from the interrupted run, delete it, then run ${retry} again.`;
+ if (code === 'changed-or-uncertain-migration-history') return `${resource ?? 'A D1 database'} holds a migration rer started but could not confirm, or one changed since it was applied; rer never retries or guesses a migration. Inspect it in the Cloudflare dashboard: if it is the empty one from this interrupted first deploy, delete it with ${remove} (that deletes everything this environment created), then run ${again} again. If it holds data, resolve the interrupted migration by hand first (deploy-kit README, Migration safety).`;
+ if (removing) return `Fix the cause, then run ${retry} again.`;
+ if (secretChange) return `Fix the cause, then run ${retry} again; a plain ${again} does not make this change.`;
+ return `Fix the cause, then run ${again} again: it continues with what was created. To delete what this environment created instead: ${remove}.`;
+}

package/cli/door.mjs

@@ -36,7 +36,7 @@ export const doorChallengeHeader = 'x-rer-door-challenge';
 export const doorIdentityPath = '/__rer/door/identity';
 export const doorDefaults = Object.freeze({ serverLimit: 10, idleSeconds: 43200 });
 
-export const doorDirectory = (env = process.env) => resolve(env.RER_DOOR_DIR ?? join(userInfo().homedir, '.rer/door'));
+export const doorDirectory = (env = process.env) => resolve(env.RER_DOOR_DIR ?? join(env.HOME || userInfo().homedir, '.rer/door'));
 export const doorOrigin = (name, port) => `http://${name}.localhost:${port}`;
 export const doorHost = (name, port) => `${name}.localhost:${port}`;
 

package/cli/inspect.mjs

@@ -7,7 +7,7 @@ import { aliases, pins, requiredHooks, serverDefaults, verbs, releaseFlags } fro
 import { runningVersion } from './version.mjs';
 import { contained, readPackage } from './project.mjs';
 import { shared } from './shared.mjs';
-import { missing, RerError } from './errors.mjs';
+import { missing } from './errors.mjs';
 import { projectNodePin } from './node-runtime-discovery.mjs';
 import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { localAiDiagnostics } from './ai-local.mjs';
@@ -18,6 +18,7 @@ import { commandArgv, commandLine, declaredPackage, exactVersion, lockedPackage,
 import { vendoredCalls } from './package-calls.mjs';
 import { doorProtocol } from './door.mjs';
 import { savedOrigin } from './door-mode.mjs';
+import { probePnpm } from './pnpm-probe.mjs';
 
 // cliVersion: the rer version of the code answering (absent for a vendored copy
 // too old to record one). defaults: what a server start applies when the person
@@ -31,7 +32,16 @@ export async function describe(project) {
  };
  const capabilities = project.adapter?.verbs ?? {};
  return { contractVersion: 1, ...versioned, profile: 'first-party', defaults, pins: { node: pkg.engines?.node, pnpm: pkg.packageManager?.replace(/^pnpm@/, '') },
-  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects: verbs[verb]?.effects ?? 'Produce releases; keygen writes a public anchor and, on success, its private key to non-terminal stdout; sign writes a detached signature and prints (but does not execute) the GitHub upload command; receipt verifies against local anchors offline.' }])),
+  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => {
+   const adapterEffects = capability.effects;
+   const operationsEffects = project.descriptor.commands?.[verb]?.effects;
+   const effects = typeof adapterEffects === 'string' && adapterEffects.trim()
+    ? adapterEffects
+    : typeof operationsEffects === 'string' && operationsEffects.trim()
+     ? operationsEffects
+     : verbs[verb]?.effects ?? 'Produce releases; keygen writes a public anchor and, on success, its private key to non-terminal stdout; sign writes a detached signature and prints (but does not execute) the GitHub upload command; receipt verifies against local anchors offline.';
+   return [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects }];
+  })),
   aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === commandLine(verb, declaredPackage(pkg) !== undefined))),
   local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), origin: await savedOrigin(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
   // This pin serves a checkout through the machine's front door (rer door).
@@ -137,25 +147,20 @@ async function packageClauses(root, pkg) {
 export async function tools(root, store, signal) {
  const node = await projectNodePin(root);
  if (node && process.versions.node !== node) throw missing(`Node ${node} is required. Run it with rer, with automatic project runtime selection enabled.`);
- const found = await probePnpm(root, store, signal).catch(error => { if (signal?.aborted) throw error; return null; });
- if (found === pins.pnpm) return;
- const { cachedPnpm, downloadPnpm } = await import('./pnpm-runtime.mjs');
- let directory = await cachedPnpm(pins.pnpm);
- if (!directory) {
-  store.report?.(`Fetching pnpm ${pins.pnpm} for this project (PATH has ${found ? `pnpm ${found}` : 'no pnpm'}); rer keeps it in its own cache.`);
-  try { directory = await downloadPnpm(pins.pnpm, signal); }
-  catch (error) { if (signal?.aborted || error instanceof RerError) throw error; throw missing(`pnpm ${pins.pnpm} is required and could not be fetched (${error.message}). Check the connection, or install pnpm ${pins.pnpm} yourself.`); }
- }
- usePnpm(directory);
- if (await probePnpm(root, store, signal) !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. The pnpm rer provides did not report it; install pnpm ${pins.pnpm} yourself.`);
+ const { ensureProjectPnpm } = await import('./project-pnpm.mjs');
+ await ensureProjectPnpm(root, { signal, store, report: text => store.report?.(text) });
 }
-const usePnpm = directory => { process.env.PATH = [dirname(process.execPath), directory, process.env.PATH].filter(Boolean).join(delimiter); };
+const usePnpm = directory => { process.env.PATH = [directory, dirname(process.execPath), process.env.PATH].filter(Boolean).join(delimiter); };
 
 export async function doctor(project, store, signal) {
  const { inspectOperations } = await import('../operations/operations.mjs');
  const diagnostic = await inspectOperations(project.root);
  const { localVariables } = await shared('local/environment.mjs');
- let values = {}, pnpm, stateValid = true;
+ let values = {}, pnpm, expectedPnpm, pnpmIssue, stateValid = true;
+ if (project.profile === 'first-party') {
+  try { expectedPnpm = await (await import('./project-pnpm.mjs')).projectPnpmPin(project.root); }
+  catch (error) { pnpmIssue = error.message; }
+ }
  if (project.profile === 'first-party') {
   const { selectLocalState } = await shared('local/state.mjs');
   try { await selectLocalState(project.root, project.adapter.state); } catch { stateValid = false; }
@@ -170,8 +175,8 @@ export async function doctor(project, store, signal) {
   } catch {}
   try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; }
   // A pnpm rer already provides counts; doctor never fetches one.
-  if (pnpm !== pins.pnpm) {
-   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(pins.pnpm).catch(() => undefined);
+  if (expectedPnpm && pnpm !== expectedPnpm) {
+   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(expectedPnpm).catch(() => undefined);
    if (directory) { usePnpm(directory); try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; } }
   }
  }
@@ -181,27 +186,14 @@ export async function doctor(project, store, signal) {
  const keys = localSettingKeys(project);
  const inputs = project.profile === 'first-party' ? requiredLocalSettings(project, values) : [];
  const warnings = project.profile === 'first-party' ? await cacheWarnings(project.root) : [];
- return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (process.versions.node === expectedNode && pnpm === pins.pnpm)),
+ return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (Boolean(expectedPnpm) && process.versions.node === expectedNode && pnpm === expectedPnpm)),
   node: { actual: process.versions.node, expected: expectedNode },
-  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: pins.pnpm } : undefined,
+  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: expectedPnpm ?? null, ...(pnpmIssue ? { issue: pnpmIssue } : {}) } : undefined,
   ai: { issues: aiIssues },
   missingInputs: [...new Set([...diagnostic.missingEnvironment, ...inputs])],
   sources: project.descriptor.environmentSources ?? {}, state: { path: project.adapter?.state, safe: stateValid }, scope: 'local-inputs-only' };
 }
 
-// Diagnostics and execution use the same identity-checked process custody.
-// Exit starts cleanup even if a descendant still holds the output pipes.
-async function probePnpm(root, store, signal) {
- const probeSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean));
- const child = store.spawn('Checking pinned pnpm', 'pnpm', ['--version'], { cwd: root, signal: probeSignal });
- let version = '';
- child.stdout.on('data', chunk => { version = (version + chunk).slice(-1024); });
- const code = await new Promise(resolve => { child.once('error', () => resolve(null)); child.once('exit', code => resolve(code)); });
- await store.stop(child);
- if (probeSignal.aborted || code !== 0) throw missing('The pinned pnpm version probe failed. Select the documented tool.');
- return version.trim();
-}
-
 // SC-05: a seed declaring devIdentity loads the dev layer only from a local-only
 // entry that its dev configuration names, never from the deployed main, lets
 // rer build scan its output, and keeps one end-to-end email-link test.

package/cli/lifecycle.mjs

@@ -19,7 +19,7 @@ import { announceDoorRoute, routeRunning, verifyDoorFor } from './door-mode.mjs'
 export async function runCommand(project, options, out) {
  if(project.profile==='first-party'&&['dev','preview'].includes(options.verb))return (await import('./managed-server.mjs')).managedServer(project,options,out);
  const cancellation = new AbortController(), signal = cancellation.signal;
- let termination, operation, store, temporary, proxy;
+ let termination, operation, store, temporary, proxy, failed = false;
  const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { if (!termination) { termination = name; cancellation.abort(name); } }]));
  for (const [name, handler] of handlers) process.on(name, handler);
  try {
@@ -85,8 +85,10 @@ export async function runCommand(project, options, out) {
   if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
   if (options.verb === 'deploy') {
    if (typeof adapter.deploy !== 'function') throw refuse('Owner-account deploy declaration is missing.');
-   const deployed = await adapter.deploy({ root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity) });
-   if(deployed.deployed && !options.dryRun) await linkDependencies({project,input:await savedSetupAnswers(project,project.setupSeed.model),origin:deployed.origin,store,signal,appSetupToken:process.env[project.setupManifest?.steps.find(step=>step.type==='owner-claim')?.tokenField??'SETUP_TOKEN']});
+   const link = async (origin, appSetupToken) => linkDependencies({project,input:project.setupSeed?await savedSetupAnswers(project,project.setupSeed.model):undefined,origin,store,signal,appSetupToken});
+   const deployed = await adapter.deploy({ root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity), setupManifest: project.setupManifest, linkDependencies: link });
+   // Base's owner-account deploy links while its setup token is live; another deploy hook is linked here.
+   if(deployed.deployed && !options.dryRun && !deployed.dependenciesLinked) await link(deployed.origin,process.env[project.setupManifest?.steps.find(step=>step.type==='owner-claim')?.tokenField??'SETUP_TOKEN']);
    return deployed;
   }
   // Setup writes the checkout's dev key; its temporary app and the CLI's own
@@ -135,10 +137,18 @@ export async function runCommand(project, options, out) {
   } else if (options.verb !== 'build') throw refuse('The requested first-party capability is unavailable.');
   return {};
  } catch (error) {
+  failed = true;
   if (error instanceof RerError) throw error;
   throw await lifecycleError(error, store);
  } finally {
-  await store?.closeCommands(); await proxy?.close(); await operation?.release();
+  // Every closer runs: one that fails must not leave the job-queue policy socket
+  // listening (the process would never exit) or the local operation held, and
+  // must not turn a finished command into a failure or hide the real one.
+  const unclosed = [];
+  for (const close of [() => store?.closeCommands(), () => proxy?.close(), () => operation?.release()]) {
+   try { await close(); } catch (error) { unclosed.push(store?.redact?.(String(error?.message)) ?? 'unknown cause'); }
+  }
+  if (unclosed.length && !failed) out.progress(`Local cleanup could not confirm that every helper process stopped (${unclosed.join('; ')}). The ${options.verb} itself finished.\n`);
   if (temporary) await rm(temporary, { recursive: true, force: true });
   for (const [name, handler] of handlers) process.removeListener(name, handler);
   if (termination) throw new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143);

package/cli/parse.mjs

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { commonFlags, serverDefaults, verbs } from './contract.mjs';
 import { invalid, refuse } from './errors.mjs';
 import { isLoopbackHost } from '../modules/operator-auth/loopback.mjs';
-const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--door', '--direct', '--site']);
+const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--door', '--direct', '--site', '--remove']);
 export const mailbox = value => typeof value === 'string' && value.length <= 254 && /^[a-zA-Z0-9.!+_%\-]+@[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+$/.test(value);
 // A loopback host: the shared predicate (including `*.localhost` door names),
 // plus `::1` as --host and a bracket-stripped hostname spell it.
@@ -72,6 +72,8 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
  if (options.target !== undefined && !['local', 'remote'].includes(options.target)) throw invalid('Target must be local or remote.');
  if (options.profile !== undefined && options.profile !== 'first-party') throw invalid('The supported explicit profile is first-party.');
  if (options.environment !== undefined && !/^[a-z][a-z0-9-]{0,39}$/.test(options.environment)) throw invalid('Provide a valid deployment environment name.');
+ for (const key of ['setSecret', 'unsetSecret']) if (options[key] !== undefined && !/^[A-Z][A-Z0-9_]{0,63}$/.test(options[key])) throw invalid('Name a declared secret binding, such as SESSION_SECRET.');
+ if ((options.remove || options.setSecret || options.unsetSecret) && options.site) throw invalid('--remove, --set-secret and --unset-secret act on the application Worker, not the run site.');
  if (options.origin !== undefined) {
   let url; try { url = new URL(options.origin); } catch { throw invalid('Provide a valid credential-free origin.'); }
   if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw invalid('Provide a credential-free HTTP origin without a path.');