@runeditrun/rer 0.2.75 → 0.2.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +7 -2
  2. package/cli/README.md +55 -0
  3. package/cli/contract.mjs +1 -1
  4. package/cli/deploy-command.mjs +4 -2
  5. package/cli/deploy-inputs.mjs +15 -3
  6. package/cli/deploy-installation-key.mjs +71 -0
  7. package/cli/deploy-secrets.mjs +2 -0
  8. package/cli/deploy.mjs +13 -2
  9. package/cli/deployment-record.mjs +2 -0
  10. package/cli/listing.mjs +20 -0
  11. package/cli/main.mjs +2 -1
  12. package/cli/parse.mjs +5 -3
  13. package/cli/portability-migrations.mjs +46 -0
  14. package/cli/portability-worker.mjs +7 -20
  15. package/cli/portability.mjs +5 -4
  16. package/cli/runtime-front-door.mjs +1 -1
  17. package/cli/server-registry.mjs +43 -18
  18. package/cli/server-resources.mjs +38 -9
  19. package/global/CHANGELOG.md +14 -0
  20. package/global/README.md +7 -2
  21. package/global/launch/state.mjs +5 -4
  22. package/global/launch/stop.mjs +30 -8
  23. package/global/main.mjs +2 -1
  24. package/modules/dependencies/README.md +71 -1
  25. package/modules/dependencies/auth.mjs +4 -4
  26. package/modules/dependencies/crypto.mjs +6 -1
  27. package/modules/dependencies/custody.mjs +16 -0
  28. package/modules/dependencies/index.d.mts +1 -1
  29. package/modules/dependencies/index.mjs +6 -5
  30. package/modules/dependencies/schema/keys-sealed.sql +4 -0
  31. package/modules/dependencies/sealing.mjs +55 -0
  32. package/modules/dependencies/store.mjs +62 -9
  33. package/modules/deploy-kit/README.md +1 -0
  34. package/modules/deploy-kit/owner-cli.mjs +4 -2
  35. package/modules/deploy-kit/owner-rekey.mjs +69 -0
  36. package/modules/job-queue/command.mjs +8 -3
  37. package/modules/operator-auth/docs/native-accounts.md +4 -1
  38. package/modules/operator-auth/identity/oidc/aes-gcm.mjs +21 -0
  39. package/modules/operator-auth/identity/oidc/crypto.mjs +5 -12
  40. package/modules/operator-auth/index.d.mts +1 -1
  41. package/modules/portability/README.md +40 -11
  42. package/modules/portability/backfills.mjs +29 -16
  43. package/modules/portability/bridge.mjs +24 -29
  44. package/modules/portability/import.mjs +1 -2
  45. package/modules/portability/index.d.mts +1 -1
  46. package/modules/portability/ledgers.mjs +22 -0
  47. package/modules/portability/migration-history.mjs +2 -2
  48. package/modules/release/README.md +135 -3
  49. package/modules/release/catalogue.mjs +6 -2
  50. package/modules/release/listing.mjs +64 -0
  51. package/modules/release/look.mjs +26 -0
  52. package/modules/release/previous-listing.mjs +44 -0
  53. package/modules/release/produce.mjs +3 -0
  54. package/modules/release/screenshots.mjs +51 -0
  55. package/modules/release/signature.mjs +3 -2
  56. package/modules/release/source.mjs +19 -6
  57. package/modules/release/statement.mjs +8 -4
  58. package/onboarding/local/environment.mjs +2 -2
  59. package/onboarding/process-cleanup.mjs +5 -5
  60. package/onboarding/process-scope.mjs +1 -1
  61. package/onboarding/process-table.mjs +6 -4
  62. package/onboarding/process-tree.mjs +4 -4
  63. package/onboarding/schema/json-schema.mjs +4 -1
  64. package/package.json +1 -1
  65. package/scripts/publish-check/README.md +14 -0
  66. package/scripts/publish-check/assignment.py +48 -0
  67. package/scripts/publish-check/credential_assignments.mjs +75 -0
  68. package/scripts/publish-check/credential_assignments.py +70 -0
  69. package/scripts/publish-check/credential_literals.mjs +66 -0
  70. package/scripts/publish-check/credential_syntax.mjs +29 -0
  71. package/scripts/publish-check/env_values.py +14 -1
  72. package/scripts/publish-check/history_scan.py +9 -2
package/README.md CHANGED
@@ -190,8 +190,13 @@ or does not report its own (`rer describe` reports `defaults`), so a current
190
190
  checkout never records a limit you did not set.
191
191
  A start is never refused for machine load alone unless `RER_SERVERS_LOAD_THRESHOLD`
192
192
  or `RER_JOBS_LOAD_THRESHOLD` is set; memory and disk guards stay. The disk guard
193
- needs 15 GiB free; `RER_SERVERS_DISK_FLOOR_GIB=N` changes it (CI runners may set
194
- it lower, for example 4; people should not).
193
+ measures installed `node_modules` and `.wrangler` (including local D1 state). It
194
+ requires twice those bytes plus 256 MiB, with a 1 GiB minimum, on the checkout,
195
+ the selected temporary directory (`TMPDIR`, then `TMP`/`TEMP`, then the OS
196
+ default), and the actual `RER_SERVERS_DIR` or home registry directory. A refusal
197
+ names the path and exact free and required bytes.
198
+ `RER_SERVERS_DISK_FLOOR_GIB=N` explicitly replaces this estimate (GiB, decimals
199
+ allowed, 0 disables the floor).
195
200
 
196
201
  ## The front door
197
202
 
package/cli/README.md CHANGED
@@ -455,3 +455,58 @@ contain only the filename, path, size and modification time. Sensitive-looking
455
455
  outbound names are dropped entirely and counted in `withheld`. Symlinks, build
456
456
  outputs and dependency trees are skipped. Unsupported syntax yields no signal;
457
457
  an empty result is not proof that a repository has no business dependencies.
458
+
459
+ `INSTALLATION_KEY` has a dedicated rotation path: `rer deploy --rotate-secret INSTALLATION_KEY`
460
+ saves current and previous values privately before publishing both as one Worker
461
+ version, reseals and verifies all dependency keys in the recorded D1, then retires
462
+ the previous binding. Routine rotation uses only the current/previous pair;
463
+ older retired keys require explicit reopen. By default, every retired key remains
464
+ in the same private 0600,
465
+ Git-ignored `.rer/deploy/<environment>.secrets.env` custody as `SESSION_SECRET`,
466
+ in `INSTALLATION_KEY_RETIRED=<kid>:<value>[,<kid>:<value>...]`. Retired values
467
+ never enter routine Worker bindings or installation archives. Back up this file
468
+ securely and copy it when moving the deployment to another checkout. If rotation
469
+ stops, run the same command again; it resumes the saved pair. Manual set/unset of
470
+ these bindings is refused.
471
+
472
+ Retain each retired key until no D1 Time Travel recovery point or exported backup
473
+ predates the completed rotation that retired it or otherwise needs that key.
474
+ After any rotation or reopen has finished, edit
475
+ `.rer/deploy/<environment>.secrets.env` and remove only its `<kid>:<value>` entry
476
+ from `INSTALLATION_KEY_RETIRED`, keeping valid comma separators; remove the
477
+ assignment if no entries remain. Preserve the current key, all other entries
478
+ and the file's owned 0600 permissions. There is no per-key removal command;
479
+ reopening a removed ID refuses before provider writes unless its custody is restored.
480
+
481
+ A D1 backup or Time Travel restore from before a rotation can restore ciphertext
482
+ that needs retired keys. Select a retained key explicitly:
483
+
484
+ ```sh
485
+ rer deploy --reopen-installation-key KID
486
+ ```
487
+
488
+ Use the envelope's installation `kid` or its entry in private retired custody;
489
+ this ID is different from the signing JWK's ID. Include the original deployment's
490
+ `--environment` and `--env-file` when applicable. This command publishes the
491
+ current key and selected retired key as `INSTALLATION_KEY_PREVIOUS`, reseals all
492
+ dependency keys through the recorded D1, verifies them under the current key,
493
+ then removes the previous binding while retaining all retired custody. It skips
494
+ the build and upload hook. CLI-side reopen rekey receives every validated retired key
495
+ in custody, allowing a mid-rotation snapshot with multiple retired envelope IDs
496
+ to reopen with either ID; these additional keys are never Worker bindings.
497
+ Reopen/rekey prints the D1 `key_ids` tail and custody availability for each history
498
+ ID before opening rows, even when the tail is unavailable. A whole pre-rotation
499
+ restore whose history tail is unavailable reports `installation_key_unavailable`;
500
+ `installation_key_version_unknown` applies to a known row ID only after that
501
+ history custody check succeeds.
502
+ A failure preserves the exact pair and reopen marker;
503
+ repeat the same command before other deploy changes. Missing retired custody
504
+ refuses with `installation_key_unavailable` before any provider write: recover
505
+ the private file before reopening. For backups spanning several rotations,
506
+ retain every historical key they need; unrelated ciphertext never silently regenerates keys.
507
+
508
+ Base versions before #367 cannot open sealed dependency keys. Roll forward to a
509
+ sealing-capable Base version after restoring D1; rolling code back cannot decrypt
510
+ the rows. The CLI has no old-Base capability receipt or code rollback command,
511
+ so it cannot preflight an out-of-band provider rollback. Current Base rejects a
512
+ sealed key passed to its plaintext signing path with `installation_key_sealed_rollback`.
package/cli/contract.mjs CHANGED
@@ -11,7 +11,7 @@ const definitions = {
11
11
  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.'],
12
12
  verify: [[], 'Run the complete internal verification target.'],
13
13
  reset: [['--yes'], 'Confirmed removal of the declared local inventory only.'],
14
- deploy: [['--owner-name', '--environment', '--dry-run', '--site', '--demo', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port', '--remove', '--yes', '--set-secret', '--unset-secret', '--rotate-secret'], 'Owner-account deployment and health; dry run validates/builds locally and reads target secret bindings with Cloudflare credentials, without provider writes. Missing required secrets fail as in deploy; missing credentials or unreadable target secrets also fail. Builds and deploy hooks run with the checkout\'s local settings files moved aside, and a build output holding one (.dev.vars, .env) is refused. 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. rer keeps the secrets it generates in .rer/deploy/ENVIRONMENT.secrets.env (0600) and reuses them on every redeploy; it refuses to generate a replacement for one a live Worker holds, and --rotate-secret NAME[,NAME] replaces them on purpose. After a healthy deploy rer claims the setup owner on the hosted app with the saved setup owner name and the one-time setup token, then removes the token. If the installer declares an owner-name field and no name is saved, deploy asks once and saves it; --non-interactive requires --owner-name NAME before any upload. --set-secret NAME[,NAME] (each value from the environment or --env-file; repeat the flag or join names with commas) and --unset-secret NAME[,NAME] change those secrets of the deployed Worker without a build, all of them in one new Worker version or none, and record that version; a missing value refuses before any change. --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. --demo deploys the hosted demo instead (deploy-demo.json): a front Worker on demo.<domain> giving each visitor their own signed-in, throwaway native Worker isolate of this seed with real public reads/checks and simulated external writes; --dry-run writes it to .rer/demo-host with no provider request; --demo --remove --yes deletes that demo (its Worker, demo.<domain> Custom Domain, each only while the record its deploy left proves it the demo\'s), reads back that each is gone, and is a no-op once it is.'],
14
+ deploy: [['--owner-name', '--environment', '--dry-run', '--site', '--demo', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port', '--remove', '--yes', '--set-secret', '--unset-secret', '--rotate-secret', '--reopen-installation-key'], 'Owner-account deployment and health; dry run validates/builds locally and reads target secret bindings with Cloudflare credentials, without provider writes. Missing required secrets fail as in deploy; missing credentials or unreadable target secrets also fail. Builds and deploy hooks run with the checkout\'s local settings files moved aside, and a build output holding one (.dev.vars, .env) is refused. 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. rer keeps the secrets it generates in .rer/deploy/ENVIRONMENT.secrets.env (0600) and reuses them on every redeploy; it refuses to generate a replacement for one a live Worker holds, and --rotate-secret NAME[,NAME] replaces them on purpose. After a healthy deploy rer claims the setup owner on the hosted app with the saved setup owner name and the one-time setup token, then removes the token. If the installer declares an owner-name field and no name is saved, deploy asks once and saves it; --non-interactive requires --owner-name NAME before any upload. --set-secret NAME[,NAME] (each value from the environment or --env-file; repeat the flag or join names with commas) and --unset-secret NAME[,NAME] change those secrets of the deployed Worker without a build, all of them in one new Worker version or none, and record that version; a missing value refuses before any change. --reopen-installation-key KID temporarily binds a retired installation key from private custody, reseals restored dependency keys under the current key, verifies them and removes the previous binding. --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. --demo deploys the hosted demo instead (deploy-demo.json): a front Worker on demo.<domain> giving each visitor their own signed-in, throwaway native Worker isolate of this seed with real public reads/checks and simulated external writes; --dry-run writes it to .rer/demo-host with no provider request; --demo --remove --yes deletes that demo (its Worker, demo.<domain> Custom Domain, each only while the record its deploy left proves it the demo\'s), reads back that each is gone, and is a no-op once it is.'],
15
15
  export: [['--target', '--output', '--origin', '--session-file'], 'For owner move-in, run rer dev and open /app/import: export people there, then upload through the destination door. Developer-only installation backup: complete supported archive of the local copy on this computer, with integrity and exclusions, written to --output. The hosted install cannot be exported yet: --origin or --target remote refuses (exit 2) before any effect and names the command that saves the hosted database.'],
16
16
  import: [['--target', '--input', '--journal', '--origin', '--session-file', '--yes', '--legacy-v1', '--acknowledge-unverified-metadata', '--output'], 'For owner move-in, run rer dev and open /app/import: upload, review and apply through the door. Developer-only installation recovery: 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.'],
17
17
  doctor: [[], 'Read-only installed tool, configuration and state diagnostics.'],
@@ -26,7 +26,7 @@ import { withoutLocalSettings, refuseLocalEnvOutput } from './local-env.mjs';
26
26
  import { deployProductDirectory, deployProductArguments, DeployProductError } from './deploy-product.mjs';
27
27
 
28
28
  export function validateDeployOptions(options) {
29
- const changes = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret', options.rotateSecret && '--rotate-secret'].filter(Boolean);
29
+ const changes = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret', options.rotateSecret && '--rotate-secret', options.reopenInstallationKey && '--reopen-installation-key'].filter(Boolean);
30
30
  if (changes.length > 1 || changes.length && options.dryRun) throw invalid(`Use ${changes.join(', ')}${options.dryRun ? ' and --dry-run' : ''} on separate runs.`);
31
31
  if (options.remove && !options.yes) throw invalid(`${deployAgain(options)} --remove deletes this environment's Worker and every D1, R2, KV and queue rer created for it, with their data. Add --yes to confirm.`);
32
32
  }
@@ -86,11 +86,13 @@ export async function deployCommand(context) {
86
86
  const { signIn } = await requireProductionAuth({ root, declaration, env: production.env, setupManifest, setupSeed: context.setupSeed, adapter, declarationPath: path, options }) ?? {};
87
87
  const needed = neededForRealDeploy({ declaration, env: production.env, signIn, secretsChecked: true });
88
88
  reportNeeded(store, needed);
89
+ if (declaration.secrets?.some(item => item.binding === 'INSTALLATION_KEY')) store.report('deploy: INSTALLATION_KEY is a private generated binding; INSTALLATION_KEY_PREVIOUS is optional and managed only during rotation or an explicit retired-key reopen. Values are withheld.');
89
90
  return needed.length && result && typeof result === 'object' ? { ...result, neededForRealDeploy: needed } : result;
90
91
  };
91
92
  // Custom hooks historically ignored these flags. Only the ownership controller
92
93
  // may perform them; neither a build nor a custom upload runs here.
93
- if (options.remove || options.setSecret || options.unsetSecret) return ownerDeploy(path, adapter)(context);
94
+ if (options.remove || options.setSecret || options.unsetSecret || options.reopenInstallationKey) return ownerDeploy(path, adapter)(context);
95
+ if (options.rotateSecret?.split(',').includes('INSTALLATION_KEY')) return ownerDeploy(path, adapter)(context);
94
96
  // A hook that deployed through the kit keeps what its Worker holds: rotate there as a secret change.
95
97
  if (options.rotateSecret && !adapter.deploy.managesHostedOwner && await hookState(root, options.environment ?? 'production')) return ownerDeploy(path, adapter)(context);
96
98
  if (adapter.deploy.managesHostedOwner) { const result = await adapter.deploy(context); return options.dryRun ? dryRun(result) : result; }
@@ -1,7 +1,7 @@
1
1
  import { randomBytes } from 'node:crypto';
2
2
  import { relative } from 'node:path';
3
3
  import { shared } from './shared.mjs';
4
- import { invalid } from './errors.mjs';
4
+ import { invalid, refuse } from './errors.mjs';
5
5
  import { readDeployEnvFile } from '../modules/deploy-kit/env-file.mjs';
6
6
  import { publicOrigin } from '../modules/deploy-kit/public-origin.mjs';
7
7
  import { keptSecrets, rotations, savedSecrets } from './deploy-secrets.mjs';
@@ -39,12 +39,24 @@ export async function deployEnvironment({ root, options, declaration, setupManif
39
39
  }
40
40
  // withDeployEnvironment reads only the --env-file, with no declaration to rotate in.
41
41
  const kept = keptSecrets(declaration, setupManifest), rotate = setupManifest || declaration.project ? rotations(options, kept, env) : [];
42
- const saved = kept.some(absent) ? await savedSecrets(root, options.environment ?? 'production') : {};
42
+ const saved = kept.some(absent) || kept.some(item => item.binding === 'INSTALLATION_KEY') ? await savedSecrets(root, options.environment ?? 'production') : {};
43
+ if (kept.some(item => item.binding === 'INSTALLATION_KEY')) {
44
+ const installation = kept.find(item => item.binding === 'INSTALLATION_KEY'), previous = secrets.find(item => item.binding === 'INSTALLATION_KEY_PREVIOUS');
45
+ if (previous && env[previous.environment]?.trim()) throw refuse('INSTALLATION_KEY_PREVIOUS is managed by --rotate-secret INSTALLATION_KEY; leave it unset in the environment and --env-file.');
46
+ if (saved.INSTALLATION_KEY && env[installation.environment]?.trim() && env[installation.environment] !== saved.INSTALLATION_KEY) throw refuse('A supplied INSTALLATION_KEY differs from this environment\'s private custody. Use --rotate-secret INSTALLATION_KEY to change it safely.');
47
+ if ((options.setSecret ?? options.unsetSecret ?? '').split(',').some(name => ['INSTALLATION_KEY', 'INSTALLATION_KEY_PREVIOUS'].includes(name))) throw refuse('Installation keys cannot be set or removed manually. Use --rotate-secret INSTALLATION_KEY to publish both keys, reseal dependency keys and retire the previous key safely.');
48
+ if (saved.INSTALLATION_KEY_PREVIOUS && !options.remove) {
49
+ if (saved.INSTALLATION_KEY_REOPEN && options.reopenInstallationKey !== saved.INSTALLATION_KEY_REOPEN) throw refuse(`Installation key reopen is unfinished. Run the same deploy command with --reopen-installation-key ${saved.INSTALLATION_KEY_REOPEN} to resume before another deployment or secret change.`);
50
+ if (!saved.INSTALLATION_KEY_REOPEN && !rotate.includes('INSTALLATION_KEY')) throw refuse('Installation key rotation is unfinished. Run the same deploy command with --rotate-secret INSTALLATION_KEY to resume before another deployment or secret change.');
51
+ }
52
+ if (rotate.includes('INSTALLATION_KEY') && !saved.INSTALLATION_KEY) throw refuse('Installation key rotation requires the current key in the private deployment secrets file. Restore that file from the checkout that deployed this environment; generating a replacement would lose access to dependency keys.');
53
+ }
43
54
  const generated = [], reused = [];
44
55
  for (const field of setupManifest?.fields ?? []) {
45
56
  const item = field.kind === 'secret' && field.generate ? secrets.find(entry => entry?.binding === field.name) : undefined;
46
57
  if (!absent(item)) continue;
47
- const keep = kept.includes(item), value = keep && !rotate.includes(item.binding) ? saved[item.binding] : undefined;
58
+ const keep = kept.includes(item), resuming = item.binding === 'INSTALLATION_KEY' && saved.INSTALLATION_KEY_PREVIOUS;
59
+ const value = keep && (!rotate.includes(item.binding) || resuming) ? saved[item.binding] : undefined;
48
60
  env[item.environment] = value ?? randomBytes(32).toString(field.generate);
49
61
  supplied.push(item.binding);
50
62
  if (value) reused.push(item.binding); else if (keep) generated.push(item.binding);
@@ -0,0 +1,71 @@
1
+ import { savedSecrets, saveSecrets, savedSecretsFile, liveSecretNames } from './deploy-secrets.mjs';
2
+ import { refuse, RerError } from './errors.mjs';
3
+ import { installationKeyId } from '../modules/dependencies/sealing.mjs';
4
+ import { retiredInstallationKeys as parseRetiredKeys } from '../modules/dependencies/custody.mjs';
5
+ import { shared } from './shared.mjs';
6
+ import { join } from 'node:path';
7
+
8
+ /** Save the first deployment key before a Worker can receive it, including when
9
+ * its upload answer is lost. Never confuse a newly generated value with a live key. */
10
+ export async function keepInstallationKey({ root, environment, declaration, env, generated }) {
11
+ const secret = declaration.secrets?.find(item => item.binding === 'INSTALLATION_KEY');
12
+ if (!secret || (await savedSecrets(root, environment)).INSTALLATION_KEY) return;
13
+ if (generated.includes(secret.binding) && (await liveSecretNames(env, declaration, environment)).includes(secret.binding)) throw refuse('The Worker already holds INSTALLATION_KEY, but this checkout has no current key. Restore the private deployment secrets file before continuing.');
14
+ if (env[secret.environment]) await saveSecrets(root, environment, { INSTALLATION_KEY: env[secret.environment] });
15
+ }
16
+
17
+ /** Persist both keys before publishing either; a retry always uses this exact pair. */
18
+ export async function rotateInstallationKey({ root, environment, declaration, env, owner, state, report, addSecrets }) {
19
+ const current = declaration.secrets?.find(item => item.binding === 'INSTALLATION_KEY');
20
+ const previous = declaration.secrets?.find(item => item.binding === 'INSTALLATION_KEY_PREVIOUS');
21
+ if (!current || !previous?.optional) throw refuse('Installation key rotation requires declared INSTALLATION_KEY and optional INSTALLATION_KEY_PREVIOUS bindings.');
22
+ const saved = await savedSecrets(root, environment);
23
+ if (!saved.INSTALLATION_KEY) throw refuse('Restore the current installation key in the private deployment secrets file before rotating it.');
24
+ if (saved.INSTALLATION_KEY_REOPEN) throw refuse('Installation key reopen is unfinished. Resume --reopen-installation-key with the saved key ID before rotating.');
25
+ const pair = { INSTALLATION_KEY: saved.INSTALLATION_KEY_PREVIOUS ? saved.INSTALLATION_KEY : env[current.environment], INSTALLATION_KEY_PREVIOUS: saved.INSTALLATION_KEY_PREVIOUS ?? saved.INSTALLATION_KEY };
26
+ if (!pair.INSTALLATION_KEY || pair.INSTALLATION_KEY === pair.INSTALLATION_KEY_PREVIOUS) throw refuse('Installation key rotation requires distinct current and previous keys.');
27
+ const retired = await retiredInstallationKeys(saved);
28
+ retired.set(await installationKeyId(pair.INSTALLATION_KEY_PREVIOUS), pair.INSTALLATION_KEY_PREVIOUS);
29
+ addSecrets([...Object.values(pair), ...retired.values()]);
30
+ await saveSecrets(root, environment, { ...pair, INSTALLATION_KEY_RETIRED: serializeRetired(retired) });
31
+ // Routine rotation must not revive envelopes from older retired eras.
32
+ await resealAndRetire({root, environment, current, previous, pair, retired:new Map(), env, state, owner, report});
33
+ report('Rotated INSTALLATION_KEY, resealed every dependency key, and removed INSTALLATION_KEY_PREVIOUS after verifying the owned Worker. Retired keys remain in private custody for older D1 restores.');
34
+ }
35
+
36
+ /** Explicitly reopen one retained historical key without changing current custody. */
37
+ export async function reopenInstallationKey({ root, environment, declaration, env, owner, state, kid, report, addSecrets }) {
38
+ const current = declaration.secrets?.find(item => item.binding === 'INSTALLATION_KEY');
39
+ const previous = declaration.secrets?.find(item => item.binding === 'INSTALLATION_KEY_PREVIOUS');
40
+ if (!current || !previous?.optional) throw refuse('Installation key reopen requires declared INSTALLATION_KEY and optional INSTALLATION_KEY_PREVIOUS bindings.');
41
+ const saved = await savedSecrets(root, environment), retired = await retiredInstallationKeys(saved);
42
+ if (!saved.INSTALLATION_KEY || !retired.has(kid)) throw unavailable('The requested retired installation key is not in this environment\'s private custody. Restore the private deployment secrets file from the deploying checkout, or relink dependencies. Nothing was uploaded.');
43
+ if (saved.INSTALLATION_KEY_PREVIOUS && (saved.INSTALLATION_KEY_REOPEN !== kid || saved.INSTALLATION_KEY_PREVIOUS !== retired.get(kid))) throw refuse('Another installation key operation is unfinished. Resume its recorded rotation or reopen first.');
44
+ const pair = { INSTALLATION_KEY: saved.INSTALLATION_KEY, INSTALLATION_KEY_PREVIOUS: retired.get(kid) };
45
+ addSecrets([...Object.values(pair), ...retired.values()]);
46
+ await saveSecrets(root, environment, {...pair, INSTALLATION_KEY_REOPEN:kid});
47
+ await resealAndRetire({root, environment, current, previous, pair, retired, env, state, owner, report});
48
+ report(`Reopened retired installation key ${kid}, resealed and verified every dependency key with the current key, and removed INSTALLATION_KEY_PREVIOUS. Retired custody is retained.`);
49
+ }
50
+
51
+ const unavailable = message => new RerError('installation_key_unavailable', message, 4);
52
+ const serializeRetired = retired => [...retired].map(([kid, value]) => `${kid}:${value}`).join(',');
53
+
54
+ async function retiredInstallationKeys(saved) {
55
+ try { return await parseRetiredKeys(saved.INSTALLATION_KEY_RETIRED); }
56
+ catch { throw unavailable('Retired installation key custody is invalid. Restore the private deployment secrets file before rotating or reopening. Nothing was uploaded.'); }
57
+ }
58
+
59
+ async function resealAndRetire({root, environment, current, previous, pair, retired, env, state, owner, report}) {
60
+ const values = { ...env, [current.environment]: pair.INSTALLATION_KEY, [previous.environment]: pair.INSTALLATION_KEY_PREVIOUS };
61
+ const extra = state ? ['--state', state] : [];
62
+ await owner('secret', ['--set', current.binding, '--set', previous.binding, ...extra], values);
63
+ await owner('rekey', extra, {...values, INSTALLATION_KEY_RETIRED:serializeRetired(retired)}, {notice:report});
64
+ await owner('secret', ['--unset', previous.binding, ...extra], values);
65
+ // The retired key stays private after its binding is read back absent.
66
+ const retained = await savedSecrets(root, environment);
67
+ delete retained.INSTALLATION_KEY_PREVIOUS;
68
+ delete retained.INSTALLATION_KEY_REOPEN;
69
+ const { writePrivateFile } = await shared('private-files.mjs');
70
+ await writePrivateFile(join(root, savedSecretsFile(environment)), Object.entries(retained).map(([name, value]) => `${name}=${value}\n`).join(''));
71
+ }
@@ -87,6 +87,8 @@ export async function keepHookSecrets({ root, environment, declaration, setupMan
87
87
  const held = kept.filter(item => fresh.includes(item.binding) && live.includes(item.binding));
88
88
  if (held.length) throw refuseRotation({ worker: ownerWorkerName(declaration.project, environment), held, environment, again });
89
89
  }
90
+ const { keepInstallationKey } = await import('./deploy-installation-key.mjs');
91
+ await keepInstallationKey({ root, environment, declaration, env, generated });
90
92
  await keepSecrets({ root, environment, kept, env, generated, reused, report });
91
93
  }
92
94
 
package/cli/deploy.mjs CHANGED
@@ -20,6 +20,7 @@ import { cloudflareCredentials, missingCredentialsMessage } from './deploy-needs
20
20
  import { keptSecrets, keepSecrets, forgetSecrets } from './deploy-secrets.mjs';
21
21
  import { withoutLocalSettings, refuseLocalEnvOutput } from './local-env.mjs';
22
22
  import { deployProductDirectory, deployProductArguments } from './deploy-product.mjs';
23
+ import { rotateInstallationKey, reopenInstallationKey, keepInstallationKey } from './deploy-installation-key.mjs';
23
24
 
24
25
  export function ownerDeploy(declarationPath, lifecycle) {
25
26
  // rer verify serves the build with this declaration's vars and secrets.
@@ -31,9 +32,9 @@ export function ownerDeploy(declarationPath, lifecycle) {
31
32
  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.`);
32
33
  const environment = options.environment ?? 'production';
33
34
  const again = deployAgain(options);
34
- const change = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret', options.rotateSecret && '--rotate-secret'].filter(Boolean);
35
+ const change = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret', options.rotateSecret && '--rotate-secret', options.reopenInstallationKey && '--reopen-installation-key'].filter(Boolean);
35
36
  // The command that finishes what this run started: the same verb, never a plain deploy in its place.
36
- const retry = options.remove ? `${again} --remove --yes` : options.setSecret ? `${again} --set-secret ${options.setSecret}` : options.unsetSecret ? `${again} --unset-secret ${options.unsetSecret}` : options.rotateSecret ? `${again} --rotate-secret ${options.rotateSecret}` : again;
37
+ const retry = options.remove ? `${again} --remove --yes` : options.setSecret ? `${again} --set-secret ${options.setSecret}` : options.unsetSecret ? `${again} --unset-secret ${options.unsetSecret}` : options.rotateSecret ? `${again} --rotate-secret ${options.rotateSecret}` : options.reopenInstallationKey ? `${again} --reopen-installation-key ${options.reopenInstallationKey}` : again;
37
38
  if (change.length > 1 || change.length && options.dryRun) throw invalid(`Use ${change.join(', ')}${options.dryRun ? ' and --dry-run' : ''} on separate runs.`);
38
39
  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.`);
39
40
  const productDirectory = change.length ? undefined : deployProductDirectory(declaration);
@@ -81,10 +82,19 @@ export function ownerDeploy(declarationPath, lifecycle) {
81
82
  store.report(`Removed ${result.removed.join(', ') || 'nothing (already gone)'}; read back: none of them remains.`);
82
83
  return { removed: result.removed, deployed: false };
83
84
  }
85
+ if (options.reopenInstallationKey) {
86
+ step = 'secrets';
87
+ await reopenInstallationKey({ root, environment, declaration, env, owner, state, kid: options.reopenInstallationKey, report: line => store.report(line), addSecrets: values => { redaction.addSecrets(values); store.addSecrets?.(values); } });
88
+ return { reopened: options.reopenInstallationKey, deployed: false };
89
+ }
84
90
  if (options.rotateSecret) {
85
91
  // The kit never replaces a secret its Worker holds: rotation is this explicit change, kept once it is live.
86
92
  step = 'secrets';
87
93
  for (const binding of rotated) {
94
+ if (binding === 'INSTALLATION_KEY') {
95
+ await rotateInstallationKey({ root, environment, declaration, env, owner, state, report: line => store.report(line), addSecrets: values => { redaction.addSecrets(values); store.addSecrets?.(values); } });
96
+ continue;
97
+ }
88
98
  await owner('secret', ['--set', binding, ...(state ? ['--state', state] : [])]);
89
99
  await keepSecrets({ root, environment, kept, env, generated: [binding], reused: [], report: () => {} });
90
100
  store.report(`Rotated ${binding} on this environment's Worker to a fresh value kept in .rer/deploy/${environment}.secrets.env, recorded its new version and verified hosted readiness.`);
@@ -99,6 +109,7 @@ export function ownerDeploy(declarationPath, lifecycle) {
99
109
  return { bindings, present: Boolean(options.setSecret), deployed: false };
100
110
  }
101
111
  store.report(`Deploying the ${environment} environment to your Cloudflare account.`);
112
+ await keepInstallationKey({ root, environment, declaration, env, generated });
102
113
  deployed = await owner('deploy', [], env, { notice: line => store.report(line), onCreated: resource => created.push(redaction.redact(resource)) });
103
114
  // A generated value the kit did not send stays unknown: the Worker kept its own.
104
115
  const sent = supplied.filter(name => deployed.sentSecrets.includes(name)), keptSent = [...generated, ...reused].filter(name => sent.includes(name));
@@ -48,6 +48,8 @@ function commandFor(options, environment) {
48
48
  if (options.verb === 'signin') return again.replace(/^rer deploy/, 'rer signin');
49
49
  if (options.remove) return `${again} --remove --yes`;
50
50
  if (options.setSecret) return `${again} --set-secret ${options.setSecret}`;
51
+ if (options.reopenInstallationKey) return `${again} --reopen-installation-key ${options.reopenInstallationKey}`;
52
+ if (options.rotateSecret) return `${again} --rotate-secret ${options.rotateSecret}`;
51
53
  if (options.unsetSecret) return `${again} --unset-secret ${options.unsetSecret}`;
52
54
  return again;
53
55
  }
@@ -0,0 +1,20 @@
1
+ import { writeListing } from '../modules/release/listing.mjs';
2
+ import { previousListing } from '../modules/release/previous-listing.mjs';
3
+
4
+ export async function dispatchListing(args) {
5
+ if (args.length === 1 && args[0] === '--help') {
6
+ console.log('Usage: rer listing --repo DIR --ref COMMIT --output NEW_DIR\n\nRead committed listing facts and assets without gates, signing or tags.\nWrites listing.json and its relative asset paths. --ref defaults to HEAD.');
7
+ return 0;
8
+ }
9
+ try {
10
+ const options = {};
11
+ for (let index = 0; index < args.length; index++) {
12
+ const flag = args[index];
13
+ if (!['--repo', '--ref', '--output'].includes(flag) || options[flag.slice(2)] !== undefined || !args[index + 1] || args[index + 1].startsWith('--')) throw Error('Invalid listing arguments');
14
+ options[flag.slice(2)] = args[++index];
15
+ }
16
+ if (!options.repo || !options.output) throw Error('Listing requires --repo and --output');
17
+ console.log(JSON.stringify(writeListing(options, previousListing), null, 2));
18
+ return 0;
19
+ } catch (error) { console.error(error.message); return 2; }
20
+ }
package/cli/main.mjs CHANGED
@@ -18,6 +18,7 @@ export async function main(argv = process.argv.slice(2)) {
18
18
  options = parse(argv,process.cwd(),{deferTail:true}); out = output(options);
19
19
  if (options.help) return showHelp(options,out);
20
20
  if (options.verb === 'archive') return (await import('./archive.mjs')).archiveCommand(options.archiveArgs,out);
21
+ if (options.verb === 'listing') return (await import('./listing.mjs')).dispatchListing(options.listingArgs);
21
22
  if (options.verb === 'release') return (await import('./release.mjs')).dispatchRelease(options.releaseArgs);
22
23
  const independent = await parsingProfile(options.cwd)==='independent'&&!['describe','check','doctor'].includes(options.verb);
23
24
  options=parse(argv,process.cwd(),{independent});out=output(options);
@@ -63,7 +64,7 @@ export async function main(argv = process.argv.slice(2)) {
63
64
  }
64
65
  // A hosted address never exports this computer's copy under its name.
65
66
  if (options.verb === 'export' && project.profile === 'first-party') await (await import('./hosted-export.mjs')).refuseHostedExport(project, options);
66
- if (options.verb === 'deploy' && !options.site && !options.demo && !options.remove && !options.setSecret && !options.unsetSecret) {
67
+ if (options.verb === 'deploy' && !options.site && !options.demo && !options.remove && !options.setSecret && !options.unsetSecret && !options.reopenInstallationKey) {
67
68
  const { deliveryDeclarationClauses } = await import('./delivery-declarations.mjs');
68
69
  const failures = (await deliveryDeclarationClauses(project.root)).filter(clause => !clause.ok);
69
70
  if (failures.length) throw new RerError('invalid_deployment_declaration', failures.map(clause => clause.message).join('\n'), 1);
package/cli/parse.mjs CHANGED
@@ -17,6 +17,7 @@ export const origin = (host, port) => `http://${host === '::1' ? '[::1]' : host}
17
17
  export function parse(argv, cwd = process.cwd(), { independent = false, deferTail = false } = {}) {
18
18
  const [verb, ...args] = argv;
19
19
  if (!verb || verb === '--help') return { help: true };
20
+ if (verb === 'listing') return { verb, listingArgs: args };
20
21
  // Release validates its own flags, including its integer publication scan timeout.
21
22
  if (verb === 'release') return { verb, releaseArgs: args };
22
23
  if (verb === 'archive') return { verb, archiveArgs: args };
@@ -93,9 +94,10 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
93
94
  options[key] = names.join(',');
94
95
  }
95
96
  if (options.rotateSecret !== undefined && !/^[A-Z][A-Z0-9_]{0,63}(?:,[A-Z][A-Z0-9_]{0,63}){0,15}$/.test(options.rotateSecret)) throw invalid('--rotate-secret names generated secret bindings, separated by commas, such as SESSION_SECRET.');
96
- if(verb==='deploy'&&options.demo&&(options.site||['platform','image','bindAddress','httpPort','httpsPort','envFile','host','setSecret','unsetSecret','rotateSecret'].some(key=>options[key]!==undefined)))throw invalid('--demo takes only --environment, --dry-run and --remove --yes: the hosted demo is its own Worker on demo.<domain>.');
97
+ if (options.reopenInstallationKey !== undefined && !/^[A-Za-z0-9_-]{43}$/.test(options.reopenInstallationKey)) throw invalid('--reopen-installation-key takes the installation key ID from a sealed envelope or private retired custody.');
98
+ if(verb==='deploy'&&options.demo&&(options.site||['platform','image','bindAddress','httpPort','httpsPort','envFile','host','setSecret','unsetSecret','rotateSecret','reopenInstallationKey'].some(key=>options[key]!==undefined)))throw invalid('--demo takes only --environment, --dry-run and --remove --yes: the hosted demo is its own Worker on demo.<domain>.');
97
99
  if(verb==='deploy'&&options.demo&&options.remove&&(options.dryRun||!options.yes))throw invalid(options.dryRun?'Use --remove and --dry-run on separate runs.':'deploy --demo --remove deletes the hosted demo\'s Worker, its demo.<domain> Custom Domain. Add --yes to confirm.');
98
- if ((options.remove || options.setSecret || options.unsetSecret || options.rotateSecret) && options.site) throw invalid('--remove, --set-secret, --unset-secret and --rotate-secret act on the application Worker, not the run site.');
100
+ if ((options.remove || options.setSecret || options.unsetSecret || options.rotateSecret || options.reopenInstallationKey) && options.site) throw invalid('--remove, --set-secret, --unset-secret, --rotate-secret and --reopen-installation-key act on the application Worker, not the run site.');
99
101
  if (options.origin !== undefined) {
100
102
  let url; try { url = new URL(options.origin); } catch { throw invalid('Provide a valid credential-free origin.'); }
101
103
  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.');
@@ -105,7 +107,7 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
105
107
  }
106
108
 
107
109
  export function help(verb) {
108
- if (!verb) return `Usage: rer VERB [FLAGS]\nCommands: ${Object.keys(verbs).join(', ')}, signin, release\nRun rer VERB --help for flags.\n`;
110
+ if (!verb) return `Usage: rer VERB [FLAGS]\nCommands: ${Object.keys(verbs).join(', ')}, signin, release, listing\nRun rer VERB --help for flags.\n`;
109
111
  const known = verbs[verb] ?? (verb === 'signin' ? signinVerb : undefined);
110
112
  const door = ['export', 'import'].includes(verb) ? 'To move records, start the app and open its signed-in owner import door:\n\n rer dev\n\nOpen /app/import, then export or upload and review supported records there.\n\nTo back up or restore this installation:\n' : '';
111
113
  return `${door}Usage: rer ${verb} [FLAGS]\nFlags: ${(known?.flags ?? commonFlags).join(', ')}\n${known?.effects ?? 'Execute the declared OPERATIONS v2 argv with explicit arguments after --.'}\n`;
@@ -0,0 +1,46 @@
1
+ import { join } from 'node:path';
2
+ import { createHash } from 'node:crypto';
3
+ import { readFile, readdir } from 'node:fs/promises';
4
+ import { migrationStatements } from '../modules/portability/migration-sql.mjs';
5
+ import { destinationLedger, matchMigrationLedger } from '../modules/portability/ledgers.mjs';
6
+ import { all, insist } from '../modules/portability/storage.mjs';
7
+ import { parseJsonc } from './jsonc.mjs';
8
+
9
+ // Seed-owned declarations, never archive metadata: the deploymentSpec prefix
10
+ // for this binding's directory, and data-only seeds without schema files.
11
+ export function platformMigrationDeclaration(input={}) {
12
+ insist(input && typeof input==='object' && !Array.isArray(input) && Object.keys(input).every(key=>['prefix','dataOnly'].includes(key)),'invalid_platform_migrations',409);
13
+ const {prefix,dataOnly=[]}=input;
14
+ insist(prefix===undefined || typeof prefix==='string' && /^[\w.-]*$/.test(prefix),'invalid_platform_migrations',409);
15
+ insist(Array.isArray(dataOnly) && dataOnly.every(name=>typeof name==='string' && /^[\w.-]+\.sql$/.test(name)) && new Set(dataOnly).size===dataOnly.length,'invalid_platform_migrations',409);
16
+ return {prefix,dataOnly};
17
+ }
18
+
19
+ // Reproduce the runner's stored SQL text, then recover SQLite's statement
20
+ // boundaries (migration-sql.mjs).
21
+ async function inventory(root,binding,{prefix},split) {
22
+ const config=parseJsonc(await readFile(join(root,'wrangler.jsonc'),'utf8'));
23
+ const directory=join(root,config.d1_databases.find(entry=>entry.binding===binding).migrations_dir ?? 'migrations');
24
+ return Promise.all((await readdir(directory)).filter(name=>name.endsWith('.sql')).sort().map(async name=>{
25
+ const bytes=await readFile(join(directory,name));
26
+ return {name,statements:migrationStatements(bytes.toString('utf8'),split),sha256:createHash('sha256').update(bytes).digest('hex'),...(prefix===undefined?{}:{aliases:[prefix+name]})};
27
+ }));
28
+ }
29
+
30
+ // Preserve the runner's applied order, resolving file identities by hash.
31
+ export async function appliedMigrations(root,db,binding,declaration,split) {
32
+ const ledger=await destinationLedger(db) ?? [],files=await inventory(root,binding,declaration,split);
33
+ return matchMigrationLedger(ledger,files,declaration).map(name=>files.find(file=>file.name===name));
34
+ }
35
+
36
+ // Wrangler cannot see Platform's ledger. Keep Platform as the sole authority;
37
+ // pending files must be applied by that runner before a local transfer.
38
+ export async function platformMigrationPreflight(root,db,binding,declaration,split) {
39
+ const tables=(await all(db,"SELECT name FROM sqlite_master WHERE type='table' AND name IN ('rer_migrations','d1_migrations','_rer_deploy_migrations')")).map(row=>row.name);
40
+ if(!tables.includes('rer_migrations'))return {platformLedger:false};
41
+ insist(tables.length===1,'migration_ledger:multiple:rer_migrations',409);
42
+ const files=await inventory(root,binding,declaration,split),ledger=await destinationLedger(db);
43
+ const applied=matchMigrationLedger(ledger,files,declaration);
44
+ for(const file of files)insist(applied.includes(file.name),'migration_ledger:unapplied:'+file.name,409);
45
+ return {platformLedger:true};
46
+ }
@@ -4,10 +4,7 @@ import { readLegacyArchive } from '../modules/portability/format.mjs';
4
4
  import { recoverLegacyArchive } from '../modules/portability/legacy-files.mjs';
5
5
  import { legacyTargetState, requireLegacyEmpty } from '../modules/portability/legacy-safety.mjs';
6
6
  import { migrationReplay } from '../modules/portability/migration-history.mjs';
7
- import { migrationStatements } from '../modules/portability/migration-sql.mjs';
8
- import { appliedMigrations as appliedMigrationNames } from '../modules/portability/bridge.mjs';
9
7
  import { join } from 'node:path';
10
- import { createHash } from 'node:crypto';
11
8
  import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
12
9
  import { createRequire } from 'node:module';
13
10
  import { createPortability, PortabilityError, readArchive } from '../modules/portability/index.mjs';
@@ -15,19 +12,7 @@ import { transferProgress } from '../modules/portability/progress.mjs';
15
12
  import { nativeFailure, stateBytes } from './portability-progress.mjs';
16
13
  import { parseJsonc } from './jsonc.mjs';
17
14
  import { loadPolicy } from './portability-policy.mjs';
18
-
19
- // The migrations this installation applied, in its ledger's order, with each
20
- // file's hash, so a restore can place an older archive within them. Reproduce
21
- // the runner's stored SQL text, then recover SQLite's statement boundaries.
22
- async function appliedMigrations(root, db, binding, split) {
23
- const config = parseJsonc(await readFile(join(root, 'wrangler.jsonc'), 'utf8'));
24
- const directory = join(root, config.d1_databases.find(entry => entry.binding === binding).migrations_dir ?? 'migrations');
25
- const names = await appliedMigrationNames(db) ?? [];
26
- return Promise.all(names.map(async name => {
27
- const bytes = await readFile(join(directory, name));
28
- return { name, statements: migrationStatements(bytes.toString('utf8'), split), sha256: createHash('sha256').update(bytes).digest('hex') };
29
- }));
30
- }
15
+ import { appliedMigrations, platformMigrationDeclaration, platformMigrationPreflight } from './portability-migrations.mjs';
31
16
 
32
17
  // Transfers read only the D1 database and R2 buckets. A configuration with just
33
18
  // those keeps the app's other bindings out of the proxy: a Durable Object class
@@ -40,7 +25,7 @@ async function dataConfiguration(root) {
40
25
  return path;
41
26
  }
42
27
 
43
- async function run(direction, { root, path, journal, binding, buckets, policy, policyModule, transient, legacyRecovery }) {
28
+ async function run(direction, { root, path, journal, binding, buckets, policy, policyModule, transient, legacyRecovery, platformMigrations }) {
44
29
  // Lines for the person go to the CLI over IPC, which prints them as the command's progress.
45
30
  const progress = transferProgress(line => process.send({ progress: line }));
46
31
  if (!legacyRecovery && ['export', 'import'].includes(direction)) progress({ phase: 'start', direction, bytes: direction === 'export' ? await stateBytes(join(root, '.wrangler/state')) : (await stat(path)).size });
@@ -51,6 +36,7 @@ async function run(direction, { root, path, journal, binding, buckets, policy, p
51
36
  if(journal)for await(const record of fileRecords(journal)) {}
52
37
  }
53
38
  policy = await loadPolicy(root, policy, policyModule);
39
+ const declaration=platformMigrationDeclaration(platformMigrations);
54
40
  if (direction === 'policy-preflight') return { checkedPolicy: true };
55
41
  const { getPlatformProxy, unstable_splitSqlQuery } = createRequire(join(root, 'package.json'))('wrangler');
56
42
 
@@ -59,7 +45,8 @@ async function run(direction, { root, path, journal, binding, buckets, policy, p
59
45
  let proxy;
60
46
  try {
61
47
  proxy = await getPlatformProxy({ configPath, persist: { path: join(root, '.wrangler/state/v3') }, remoteBindings: false });
62
- const migrations=async()=>migrationReplay(await appliedMigrations(root,proxy.env[binding],binding,unstable_splitSqlQuery),policy);
48
+ if(direction==='migration-preflight')return await platformMigrationPreflight(root,proxy.env[binding],binding,declaration,unstable_splitSqlQuery);
49
+ const migrations=async()=>migrationReplay(await appliedMigrations(root,proxy.env[binding],binding,declaration,unstable_splitSqlQuery),policy,declaration);
63
50
  const options={ db: proxy.env[binding], buckets: Object.fromEntries(Object.entries(buckets).map(([name, binding]) => [name, proxy.env[binding]])), policy, migrations };
64
51
  if(direction==='legacy-preflight') {
65
52
  await requireLegacyEmpty(options,await legacyTargetState(options.db,options.migrations));
@@ -81,10 +68,10 @@ const reply = message => new Promise(resolve => process.send(message, () => { pr
81
68
  try { await reply({ ok: true, ...await run(process.argv[2], JSON.parse(process.argv[3])) }); }
82
69
  catch (error) {
83
70
  // Erasure-fence refusals name the fence: an older archive is refused, not a failed transfer.
84
- const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal', 'staged_validation'].includes(error.code.split(':')[0]));
71
+ const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'migration_ledger', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal', 'staged_validation'].includes(error.code.split(':')[0]));
85
72
  const exitCode = error.message === 'archive_json' ? 2 : refusal || error.code === 'EEXIST' ? 4 : 1;
86
73
  // Report only symbolic codes; native database errors can contain private data.
87
- const reason = error instanceof PortabilityError ? error.code.split(':')[0] : /^[A-Z_]+$/.test(error.code ?? '') ? error.code : error.message === 'archive_json' ? 'archive_json' : 'native_error';
74
+ const reason = error instanceof PortabilityError ? (error.code.startsWith('migration_ledger:') ? error.code : error.code.split(':')[0]) : /^[A-Z_]+$/.test(error.code ?? '') ? error.code : error.message === 'archive_json' ? 'archive_json' : 'native_error';
88
75
  // A later migration that changes restorable data is named: it is a file of this installation.
89
76
  const migration = error instanceof PortabilityError && error.code.startsWith('schema_mismatch:migration_data:') ? error.code.slice('schema_mismatch:migration_data:'.length) : undefined;
90
77
  // A populated destination names its table or bucket: schema names, never row data.
@@ -10,7 +10,7 @@ import { shared } from './shared.mjs';
10
10
 
11
11
  // Seeds declare their real bindings and data policy. The shared module owns the
12
12
  // archive format and atomic restore; the shared runner owns its native children.
13
- export function localPortability({ database, binding = 'DB', buckets = {}, policy, policyModule, transient = [] }) {
13
+ export function localPortability({ database, binding = 'DB', buckets = {}, policy, policyModule, transient = [], platformMigrations }) {
14
14
  async function run({ root, path, journal, store, signal, operationToken, platform, legacyRecovery }, direction) {
15
15
  if (direction === 'export') {
16
16
  if (await lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; })) throw refuse('Export requires a new archive path.');
@@ -46,18 +46,19 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
46
46
  throw refuse(`Local portability policy refused (${error.code}). Executable policies require a seed-owned policyModule with a valid default policy export; policyModule requires native local transport.`);
47
47
  }
48
48
  if(platform==='container') return (await import('./container-transfer.mjs')).containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy:declaration.policy,transient});
49
- const input={ root, path, journal, binding, buckets, ...declaration, transient, legacyRecovery };
49
+ const input={ root, path, journal, binding, buckets, ...declaration, transient, legacyRecovery, platformMigrations };
50
50
  // Check the executable policy before migrations; the transfer worker imports
51
51
  // it again in its own process so module closures are retained during restore.
52
52
  if (policyModule !== undefined) await nativeWorker(store,'policy-preflight',input,signal);
53
53
  // Do not apply pending product migrations to a populated recovery target.
54
54
  // Check real existing bindings first; finalize repeats this under the lock.
55
55
  if(legacyRecovery)await nativeWorker(store,'legacy-preflight',input,signal);
56
+ const {platformLedger}=await nativeWorker(store,'migration-preflight',input,signal);
56
57
  // Local migrations need no provider account: wrangler runs without credentials.
57
58
  // Its info lines (the local location and "Use --remote if you want to access
58
59
  // the remote instance") only confuse a local backup; warnings and errors print.
59
60
  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
60
- await store.run('Applying local data migrations', 'pnpm', ['exec', 'wrangler', 'd1', 'migrations', 'apply', database, '--local', '--persist-to', '.wrangler/state', '--config', 'wrangler.jsonc'], {
61
+ if(!platformLedger)await store.run('Applying local data migrations', 'pnpm', ['exec', 'wrangler', 'd1', 'migrations', 'apply', database, '--local', '--persist-to', '.wrangler/state', '--config', 'wrangler.jsonc'], {
61
62
  cwd: root, signal, env: { ...dependencyEnvironment(), RER_LOCAL_OPERATION: operationToken, WRANGLER_SEND_METRICS: 'false', WRANGLER_LOG: 'warn' },
62
63
  });
63
64
  const receipt=await nativeWorker(store,direction,input,signal);
@@ -70,7 +71,7 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
70
71
  async function nativeWorker(store,direction,input,signal) {
71
72
  // The notice filter loads before the worker links its static node:sqlite import.
72
73
  const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url)), notice = new URL('./sqlite-notice.mjs', import.meta.url).href;
73
- const child = store.spawn(`${direction === 'policy-preflight' ? 'Checking archive policy' : direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
74
+ const child = store.spawn(`${direction === 'migration-preflight' ? 'Checking migration history for' : direction === 'policy-preflight' ? 'Checking archive policy' : direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
74
75
  ['--import', notice, worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' }, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
75
76
  let receipt;
76
77
  // Progress lines come first, as {progress}; the last message is the receipt.
@@ -21,7 +21,7 @@ export async function runtimeFrontDoor({ host, port, activity, door, devKey, ori
21
21
  // ports to every other socket (the runtime's own listeners, outbound requests),
22
22
  // so the runtime's bind could find it taken. Choose a free port the OS never
23
23
  // assigns on its own instead.
24
- async function runtimeLoopbackPort(publicPort) {
24
+ export async function runtimeLoopbackPort(publicPort) {
25
25
  const [first, last] = await ephemeralRange();
26
26
  const candidates = [[10000, first - 1], [last + 1, 65535]].filter(([low, high]) => low <= high);
27
27
  if (!candidates.length) throw Error(`The OS assigns every local port from 10000 (ephemeral range ${first}-${last}); leave part of that space outside the range for the local runtime.`);