@runeditrun/rer 0.0.0-stage → 0.1.0

package/onboarding/server.mjs

@@ -0,0 +1,188 @@
+import { loadInstallerSeed } from './setup-manifest.mjs';
+import { readSettings } from './adapter-settings.mjs';
+import { createAppProcesses } from './app-processes.mjs';
+import { installationFailureMessage } from './failures.mjs';
+import { agentHandoff } from './agent-handoff.mjs';
+import { validateAnswers } from './prefill.mjs';
+import { setupInputLimit } from './input-limits.mjs';
+import { createSecretVault } from './secrets.mjs';
+import { credentialValues } from './redaction.mjs';
+import { discoverProviders, connectProvider } from './providers.mjs';
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createState } from './state.mjs';
+import { metadata } from './metadata.mjs';
+import { loadSeedTheme } from './theme-files.mjs';
+// A browser keeps a connection open; close waits this long for in-flight replies.
+const connectionGraceMs=1000;
+export async function startInstaller(root,{seed,port=0,answers,secretInput,noPrefill=false,resume=false,agent=false}={}){
+ root=resolve(root);
+ seed=await loadInstallerSeed(root,seed);
+ if(!seed?.product||typeof seed.install!=='function')throw Error('Provide a seed onboarding contract selecting rer-setup.json.');
+ const validate=value=>validateAnswers(value,seed.model);
+ const inputLimit=setupInputLimit(seed.model);
+ const accent=seed.branding?.accent;
+ const accentStyle=/^#[0-9a-f]{6}$/i.test(accent||'')?`<style>:root{--installer-accent:${accent};--installer-accent-text:${[1,3,5].map((start,i)=>parseInt(accent.slice(start,start+2),16)*[.299,.587,.114][i]).reduce((a,b)=>a+b,0)>150?'#173753':'#ffffff'}}</style>`:'';
+ const theme=seed.theme?await loadSeedTheme(root,seed.theme):null;
+ const uiRoot=fileURLToPath(new URL('./ui/',import.meta.url));
+ if(resume&&noPrefill)throw Error('--resume cannot be combined with --no-prefill.');
+ const store=await createState(root,seed),token=randomBytes(32).toString('hex'),cookie=randomBytes(32).toString('hex');let origin,work,connection,starting=false,mutations=0;const apps=createAppProcesses();const abort=new AbortController();let attemptAbort,attemptProcesses;
+ store.setupManifest=seed.manifest;
+ const vault=createSecretVault(seed.model,store.addSecrets);store.addSecrets([token,cookie]);
+ const invalidateSecrets=async draft=>{vault.invalidate(draft);await store.invalidateSecrets(vault.invalidated());};
+ const saveDraft=async (draft,source,keys)=>{await invalidateSecrets(draft);await store.draft(draft,source,keys);};
+ store.state.sessionId=randomBytes(16).toString('hex');store.addSecrets(store.state.sessionId);
+ const savedSettings=noPrefill||!seed.settings?{}:(await readSettings(root,seed.settings)).values;
+ const configuredEnv=noPrefill?{}:{...process.env,...savedSettings};
+ const declaredSecrets=seed.manifest.fields.filter(field=>field.kind==='secret').map(field=>field.name);
+ // Seed callbacks may capture commands too. Register declared values before
+ // artwork/default hooks, including inherited values when prefill is disabled.
+ store.addSecrets([...credentialValues(process.env,declaredSecrets),...credentialValues(savedSettings,declaredSecrets)]);
+ const {workspaceArt,artworkBridge,imageLimit}=seed.artwork?await seed.artwork(root,store):{};
+ if(agent)store.state.agent.mode='connecting';
+ if(noPrefill&&(answers||secretInput||Object.keys(store.state.draft).length))throw Error('--no-prefill requires a fresh checkout with no saved installer draft or supplied answers. Existing drafts are preserved.');
+ if(!noPrefill&&!resume){
+ const info=await metadata(root);const savedAnswers=Object.fromEntries(seed.model.safeKeys.filter(key=>typeof savedSettings[key]==='string').map(key=>[key,savedSettings[key]]));
+ const defaults=validate({...seed.model.initialDraft({}),...await seed.defaults?.(info,{root,env:configuredEnv}),...savedAnswers});store.state.known={...store.state.known,...info,suggestedFields:Object.keys(defaults).filter(key=>!store.state.answered.includes(key))};store.state.draft={...defaults,...store.state.draft};
+ }
+ // Saved credentials retain the identity from settings, before resumed answers.
+ // Durable invalidations prevent a later return to that identity from reviving them.
+ if(resume&&!noPrefill)store.state.draft={...seed.model.initialDraft({}),...Object.fromEntries(seed.model.safeKeys.filter(key=>typeof savedSettings[key]==='string').map(key=>[key,savedSettings[key]])),...store.state.draft};
+ const savedDraft={...seed.model.initialDraft({}),...Object.fromEntries(seed.model.safeKeys.filter(key=>typeof savedSettings[key]==='string').map(key=>[key,savedSettings[key]]))};
+ const savedSecrets=Object.fromEntries(Object.keys(seed.model.secretScopes).filter(key=>!store.isInvalidatedSecret(key,savedSettings[key])&&seed.model.fields[key].valid(savedSettings[key])).map(key=>[key,savedSettings[key]]));
+ vault.set(savedSecrets,savedDraft);await invalidateSecrets(store.state.draft);
+ if(answers){const validated=validate(answers);await saveDraft({...store.state.draft,...validated},'agent',Object.keys(validated));}
+ if(secretInput){vault.set(secretInput,store.state.draft);if(Object.keys(secretInput).length)store.activity.secrets();secretInput=undefined;}
+ await workspaceArt?.request();
+ store.state.known.providers=noPrefill||(!seed.features?.hosting&&!seed.features?.github)?{}:(await discoverProviders(root,{signal:abort.signal})).providers;
+ const assets={'/setup-manifest.mjs':['../setup-manifest.mjs','text/javascript'],'/installer-inputs.mjs':['../installer-inputs.mjs','text/javascript'],'/schema/setup-validation.mjs':['../schema/setup-validation.mjs','text/javascript'],'/schema/dependencies.mjs':['../schema/dependencies.mjs','text/javascript'],'/schema/json-schema.mjs':['../schema/json-schema.mjs','text/javascript'],'/ui/model-core.mjs':['model-core.mjs','text/javascript'],'/seed.mjs':[seed.browserModule,'text/javascript'],'/model-core.mjs':['model-core.mjs','text/javascript'],'/workspace-art.js':['workspace-art.js','text/javascript'],'/activity.js':['activity.js','text/javascript'], '/':['index.html','text/html'], '/app.js':['app.js','text/javascript'], '/address-client.mjs':['address-client.mjs','text/javascript'], '/model.mjs':['model.mjs','text/javascript'], '/style.css':['style.css','text/css'], '/theme.css':['theme.css','text/css'], '/ocean.png':[null,seed.background?.endsWith('.svg')?'image/svg+xml':'image/png']};
+ for(const path of theme?.files.keys()??[])if(assets[path])throw Error(`Seed theme file ${path} collides with an installer path; serve it at another path.`);
+ const equal=(a,b)=>typeof a==='string'&&a.length===b.length&&timingSafeEqual(Buffer.from(a),Buffer.from(b));
+ const server=createServer(async(req,res)=>{
+  let mutation=false;
+  const json=(status,body)=>{res.writeHead(status,{'Content-Type':'application/json','Cache-Control':'no-store'});res.end(JSON.stringify(body))};
+  try{
+   if(abort.signal.aborted)return json(503,{error:'The installer is closing.'});
+   if(req.headers.host!==new URL(origin).host)return json(403,{error:'Invalid installer host.'});
+   const path=new URL(req.url,origin).pathname;
+   res.setHeader('X-Content-Type-Options','nosniff');res.setHeader('Referrer-Policy','no-referrer');res.setHeader('Cache-Control','no-store');
+   if(path.startsWith('/api/')){
+    if(!path.startsWith('/api/workspace-art'))req.setEncoding('utf8');
+    if(req.headers.origin&&req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+    const session=req.headers.cookie?.split(';').map(s=>s.trim()).find(s=>s.startsWith('rer_installer='))?.slice(14);
+    if(!equal(req.headers['x-installer-token'],token)||!equal(session,cookie))return json(403,{error:'Reload the installer page.'});
+    if(req.method==='POST'&&['/api/draft','/api/prefill','/api/secrets','/api/activity','/api/address','/api/connect'].includes(path)){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||['running','complete'].includes(store.state.phase))return json(409,{error:'Installation has already started.'});
+     mutation=true;mutations++;
+    }
+    if(req.method==='POST'&&path.startsWith('/api/workspace-art')){
+     if(!workspaceArt)return json(404,{error:'This seed does not support workspace artwork.'});
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     const chunks=[];let size=0;for await(const chunk of req){size+=chunk.length;if(size>(path==='/api/workspace-art/image'?imageLimit:8000))return json(413,{error:'Too much input.'});chunks.push(chunk);}
+     try{
+      if(path==='/api/workspace-art/image'){
+       if(req.headers['content-type']!=='image/png')return json(415,{error:'Supply a PNG image.'});
+       return json(200,await workspaceArt?.complete({id:req.headers['x-artwork-job'],revision:req.headers['x-artwork-revision'],sessionId:req.headers['x-installer-session'],kind:req.headers['x-artwork-kind']},Buffer.concat(chunks)));
+      }
+      const input=JSON.parse(Buffer.concat(chunks).toString());
+      if(path==='/api/workspace-art')return json(200,await workspaceArt?.request(input));
+      if(path==='/api/workspace-art/job')return json(200,await workspaceArt?.report(input));
+      return json(404,{error:'Unknown workspace artwork action.'});
+     }catch(error){return json(409,{error:error.message});}
+    }
+    // The dev key reaches only this authenticated page, never saved state or logs.
+    if(req.method==='GET'&&path==='/api/open-app'){
+     const key=store.state.phase==='complete'&&store.state.devOpen?/^RER_DEV_KEY=([A-Za-z0-9_-]{43,256})$/m.exec(await readFile(join(root,'.rer/local/dev-key.env'),'utf8').catch(()=>''))?.[1]:undefined;
+     if(!key)return json(404,{error:'No dev key for this installation.'});
+     const app=new URL(store.state.appUrl);return json(200,{url:`${app.origin}/__dev/key#${new URLSearchParams({'rer-dev':key,next:'/__dev/outbox'})}`});
+    }
+    if(req.method==='GET'&&path==='/api/agent-handoff')return json(200,(seed.handoff||agentHandoff)(root,origin,store.state.sessionId,seed));
+    if(req.method==='GET'&&path==='/api/state'){await workspaceArt?.refresh();store.state.known.secretReadiness=vault.readiness(store.state.draft);return json(200,store.state);}
+    if(req.method==='POST'&&path==='/api/activity'){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||['running','complete'].includes(store.state.phase))return json(409,{error:'Installation has already started.'});
+     let body='';for await(const chunk of req){body+=chunk;if(body.length>1000)return json(413,{error:'Too much input.'})}
+     try{const activity=store.activity.agent(JSON.parse(body));await workspaceArt?.request();return json(200,{activity})}catch{return json(400,{error:'Choose a supported activity phase and topic.'})}
+    }
+    if(req.method==='POST'&&path==='/api/address'){
+     if(!seed.resolveAddress)return json(404,{error:'This seed does not support address discovery.'});
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||['running','complete'].includes(store.state.phase))return json(409,{error:'Installation has already started.'});
+     let body='';for await(const chunk of req){body+=chunk;if(body.length>8000)return json(413,{error:'Too much input.'})}
+     let input;try{input=JSON.parse(body);if(!input||typeof input!=='object'||Array.isArray(input))throw Error()}catch{return json(400,{error:'Provide your workspace name and Cloudflare account.',code:'invalid_input'})}
+     const merged=vault.merge(input,store.state.draft);await store.invalidateSecrets(vault.invalidated());store.addSecrets(credentialValues(merged,Object.keys(seed.model.secretScopes||{})));
+     try{return json(200,await seed.resolveAddress(root,{name:input.name,accountId:input.accountId,prefix:input.prefix,apiToken:merged.apiToken},{env:configuredEnv}));}
+     catch(error){if(typeof error.code==='string')return json(error.code==='invalid_input'?400:422,{error:error.message,code:error.code});return json(502,{error:'Cloudflare could not confirm your app address.',code:'cloudflare_unavailable'});}
+     finally{merged.apiToken='';input.apiToken='';}
+    }
+    if(req.method==='POST'&&['/api/prefill','/api/secrets'].includes(path)){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||['running','complete'].includes(store.state.phase))return json(409,{error:'Installation has already started.'});
+     let body='';for await(const chunk of req){body+=chunk;if(Buffer.byteLength(body)>inputLimit)return json(413,{error:'Too much input.'})}
+     try{const input=JSON.parse(body);if(path==='/api/prefill'){const answers=Object.fromEntries(Object.entries(validate(input)).filter(([key])=>store.state.sources[key]!=='browser'));await saveDraft({...store.state.draft,...answers},'agent',Object.keys(answers));await workspaceArt?.request();}else {if(input.revision!==store.state.lastUpdate.revision)throw Error('Setup details changed; read them again before supplying credentials.');vault.set(input.secrets,store.state.draft);if(Object.keys(input.secrets).length)store.activity.secrets();}}catch{return json(400,{error:'Invalid setup input. Use supported nonsecret answers or the secure credential endpoint.'})}
+     return json(200,{saved:true,revision:store.state.lastUpdate.revision,updatedFields:store.state.lastUpdate.keys,secretReadiness:vault.readiness(store.state.draft)});
+    }
+    if(req.method==='POST'&&path==='/api/connect'){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||['running','complete'].includes(store.state.phase)||connection)return json(409,{error:'Another operation is running.'});
+     let body='';for await(const chunk of req){body+=chunk;if(body.length>1000)return json(413,{error:'Too much input.'})}
+     let provider;try{provider=JSON.parse(body).provider;if(!['cloudflare','github'].includes(provider)||(provider==='cloudflare'&&!seed.features?.hosting)||(provider==='github'&&!seed.features?.github))throw Error()}catch{return json(400,{error:'Select Cloudflare or GitHub.'})}
+     store.state.connection={provider,state:'starting'};store.activity.provider(provider,'starting');json(202,{started:true});
+     connection=connectProvider(root,provider,{signal:abort.signal,onProgress:value=>{store.state.connection=value;store.activity.provider(provider,value.state)}}).then(result=>{store.state.known.providers[provider]=result;store.state.connection={provider,state:result.operation.state};store.activity.provider(provider,result.operation.state);}).catch(()=>{store.state.connection={provider,state:'failed'};store.activity.provider(provider,'failed');}).finally(()=>{connection=null});return;
+    }
+    if(req.method==='POST'&&path==='/api/draft'){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||['running','complete'].includes(store.state.phase))return json(409,{error:'Installation has already started.'});
+     let body='';for await(const chunk of req){body+=chunk;if(Buffer.byteLength(body)>inputLimit)return json(413,{error:'Too much input.'})}
+     let draft;try{draft=JSON.parse(body);if(!draft||typeof draft!=='object'||Array.isArray(draft)||Object.values(draft).some(value=>typeof value!=='string'))throw Error()}catch{return json(400,{error:'Provide nonsecret setup details.'})}
+     try{draft=validate(draft)}catch{return json(400,{error:'Provide supported nonsecret setup details.'})}
+     await saveDraft({...store.state.draft,...draft},'browser',Object.keys(draft));return json(200,{saved:true});
+    }
+    if(req.method==='POST'&&path==='/api/stop'){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(store.state.phase!=='running'||!attemptAbort)return json(409,{error:'No installation is running.'});
+     attemptAbort.abort();void attemptProcesses?.stop();return json(202,{stopping:true});
+    }
+    if(req.method==='POST'&&path==='/api/start'){
+     if(req.headers.origin!==origin)return json(403,{error:'Use the local installer page.'});
+     if(starting||mutations||connection||['running','complete'].includes(store.state.phase))return json(409,{error:'Installation is already running.'});
+     starting=true;
+     try{
+     let body='';for await(const chunk of req){body+=chunk;if(Buffer.byteLength(body)>inputLimit)return json(413,{error:'Too much input.'})}
+     let input;try{const merged=vault.merge({...store.state.draft,...JSON.parse(body)},store.state.draft);await store.invalidateSecrets(vault.invalidated());input=seed.model.validateInput(merged,{...store.state.known,secretReadiness:vault.readiness(store.state.draft)})}catch(error){return json(400,{error:error.message})}
+     store.addSecrets(credentialValues(input,Object.keys(seed.model.secretScopes||{})));
+     await store.draft(input);await workspaceArt?.deliverSidebar();delete store.state.error;await store.phase('running');
+     if(abort.signal.aborted)return json(503,{error:'The installer is closing.'});
+     vault.clear();json(202,{started:true});const attempt=createAppProcesses();attemptProcesses=attempt;attemptAbort=new AbortController();
+     const cancelAttempt=()=>attemptAbort.abort();abort.signal.addEventListener('abort',cancelAttempt,{once:true});if(abort.signal.aborted)cancelAttempt();store.setCommandSignal(attemptAbort.signal);
+     work=Promise.resolve().then(()=>seed.install(root,input,store,child=>{
+      apps.register(child);attempt.register(child);
+     },attemptAbort.signal,artworkBridge)).then(async()=>{
+      // Only a completed adapter may renew an explicitly supplied credential.
+      // Hidden or failed credentials keep their durable invalidation.
+      if(store.state.phase==='complete')await store.acceptSecrets(input);
+     }).catch(async(error)=>{
+      attemptAbort.abort();await Promise.all([attempt.stop(),store.stopCommands(attemptAbort.signal)]);store.state.error=installationFailureMessage(error);await store.phase('failed');
+     }).finally(()=>{abort.signal.removeEventListener('abort',cancelAttempt);for(const key of Object.keys(seed.model.secretScopes||{}))input[key]='';});void work;return;
+     }finally{starting=false;}
+    }
+    return json(404,{error:'Unknown installer action.'});
+   }
+   if(req.method==='GET'&&path==='/rer-setup.json'){res.writeHead(200,{'Content-Type':'application/json'});res.end(seed.manifestBytes);return;}
+   if(req.method==='GET'&&path==='/SETUP.schema.json'){res.writeHead(200,{'Content-Type':'application/json'});res.end(seed.schemaBytes);return;}
+   if(req.method==='GET'&&path==='/model-options.json'){json(200,seed.modelOptions);return;}
+   const themeFile=req.method==='GET'&&theme?.files.get(path);
+   if(themeFile){res.writeHead(200,{'Content-Type':themeFile.type});res.end(themeFile.bytes);return;}
+   if(req.method!=='GET'||!assets[path]||(path==='/theme.css'&&!theme))return json(404,{error:'Not found.'});
+   const [file,type]=assets[path];let content=await readFile(file?(path==='/seed.mjs'?join(root,file):join(uiRoot,file)):join(root,seed.background));
+   if(path==='/'){content=content.toString().replaceAll('{{product}}',String(seed.product).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]))).replace('</head>',`${accentStyle}<meta name="installer-token" content="${token}"></head>`);if(theme)content=content.replace('<html lang="en">','<html lang="en" class="rer-themed">').replace('<link rel="stylesheet" href="/style.css">','<link rel="stylesheet" href="/style.css"><link rel="stylesheet" href="/rer-theme.css"><link rel="stylesheet" href="/theme.css">');res.setHeader('Set-Cookie',`rer_installer=${cookie}; Path=/; HttpOnly; SameSite=Strict`);res.setHeader('Content-Security-Policy',"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'")}
+   res.writeHead(200,{'Content-Type':type});res.end(content);
+  }catch{json(500,{error:'The installer could not complete this request.'})}finally{if(mutation)mutations--;}
+ });
+ await new Promise(resolve=>server.listen(port,'127.0.0.1',resolve));origin=`http://127.0.0.1:${server.address().port}`;
+ return {origin,state:store.state,close:async()=>{artworkBridge?.close();vault.clear();abort.abort();const stopped=apps.stop();await work;await stopped;await apps.stop();await connection;await store.closeCommands();await new Promise(resolve=>{server.close(resolve);server.closeIdleConnections();setTimeout(()=>server.closeAllConnections(),connectionGraceMs).unref();})}};
+}

package/onboarding/setup-manifest.mjs

@@ -0,0 +1,116 @@
+import {parseSetupManifestBytes, validateSetupManifest, setupConditionMatches, validateSetupValue} from './schema/setup-validation.mjs';
+import {createModel} from './ui/model-core.mjs';
+import {installerInputs} from './installer-inputs.mjs';
+
+const legacy=['fields','safeKeys','setupGroups','requiredKeys','secretScopes','summaryDefaults','initialValues','installInput'];
+export function refuseLegacySetup(value) {
+ for(const source of [value,value?.model,value?.presentation])
+  for(const name of legacy)if(source&&Object.hasOwn(source,name))throw Error(`Declare ${name} in rer-setup.json, not the seed or browser module.`);
+ if(value?.settings?.generate!==undefined)throw Error('Declare generated secrets in rer-setup.json.');
+ if(value?.features?.email!==undefined)throw Error('Declare email delivery inputs in rer-setup.json; features.email is retired.');
+}
+
+export function readSetupManifestBytes(bytes,schemaBytes,file='rer-setup.json') {
+ try {
+  const manifest=parseSetupManifestBytes(bytes),schema=JSON.parse(new TextDecoder().decode(schemaBytes));
+  const errors=validateSetupManifest(schema,manifest);
+  if(errors.length)throw Error(errors.join('; '));
+  return manifest;
+ }catch(error){throw Error(`Invalid setup manifest ${file}: ${error.message}`);}
+}
+
+// Browser and server call this with the same validated committed bytes.
+export function createInstallerModel(manifest,presentation={},options={}) {
+ refuseLegacySetup(presentation);
+ const {ownerBootstrap=false,supplied=[]}=options;
+ for(const field of manifest.fields)if(field.kind==='secret'&&field.input!=='entered'&&!field.generate&&
+  (field.required||field.presentations?.some(item=>item.required))&&!supplied.includes(field.name))throw Error(`rer-setup.json: required managed secret ${field.name} needs adapter supplied declaration.`);
+ const own=installerInputs({...presentation.features,ownerBootstrap});
+ // Compile browser roles once from the manifest, preserving its input names.
+ // The first required text field names the workspace; URL/colour fields provide
+ // artwork context. Installer-owned hosting inputs are outside that context.
+ const nameKey=manifest.fields.find(field=>field.kind==='text'&&field.required)?.name;
+ const fields={},secretScopes={...own.secretScopes};
+ function active(field,draft){
+  if(field.when&&!setupConditionMatches(field.when,draft))return null;
+  if(!field.presentations)return field;
+  const matched=field.presentations.find(item=>setupConditionMatches(item.when,draft));
+  if(!matched)return null;
+  const {when,...metadata}=matched;return {...field,...metadata};
+ }
+ for(const field of manifest.fields){
+  fields[field.name]={
+   ...field,type:field.kind==='secret'?'password':field.kind==='colour'?'color':field.kind==='email'?'email':field.kind==='url'?'url':'text',
+   artwork:field.name===nameKey||['url','colour'].includes(field.kind),
+   autocomplete:field.kind==='secret'&&field.input==='entered'?'new-password':'off',
+   optional:!field.required,options:field.options?.map(option=>[option.value,option.label]),
+   valid(value){if(typeof value!=='string'||!value)return false;try{validateSetupValue(field,value);return true;}catch{return false;}},
+   visible:draft=>Boolean(active(field,draft))&& (field.kind!=='secret'||field.input==='entered'),
+   definition(draft){const current=active(field,draft)??field;return {...fields[field.name],...current,type:fields[field.name].type,options:fields[field.name].options,optional:!current.required};},
+  };
+  if(field.kind==='secret'&&field.input==='entered')secretScopes[field.name]=[...new Set([field.when?.field,...(field.presentations??[]).map(item=>item.when.field)].filter(Boolean))];
+ }
+ for(const key of Object.keys(own.fields))if(Object.hasOwn(fields,key))throw Error(`rer-setup.json: ${key} conflicts with an installer input.`);
+ Object.assign(fields,own.fields);
+ const groupIds=new Set(manifest.groups.map(group=>group.id));
+ const generatedId=preferred=>{let id=preferred,index=1;while(groupIds.has(id))id=preferred+'-'+index++;groupIds.add(id);return id;};
+ const groups=[...(manifest.fields.some(field=>!field.group)?[{id:generatedId('ungrouped'),title:manifest.title,keys:manifest.fields.filter(field=>!field.group).map(field=>field.name)}]:[]),
+  ...manifest.groups.map(group=>({...group,title:group.label,keys:manifest.fields.filter(field=>field.group===group.id).map(field=>field.name)})),...own.groups.map(group=>({...group,id:generatedId(group.id)}))];
+ const safeKeys=Object.keys(fields).filter(key=>fields[key].type!=='password');
+ const defaults=Object.fromEntries(manifest.fields.filter(field=>field.kind!=='secret'&&field.default!==undefined).map(field=>[field.name,field.default]));
+ const internal={...presentation,product:presentation.product??{name:manifest.title},fields,safeKeys,secretScopes,setupGroups:groups,
+  summaryDefaults:Object.keys(defaults),initialValues:()=>defaults,nameKey,
+  requiredKeys(draft){return [...manifest.fields.filter(field=>{const current=active(field,draft);return current?.required&&(field.kind!=='secret'||field.input==='entered');}).map(field=>field.name),...Object.keys(own.fields).filter(key=>!own.fields[key].optional)];},
+ };
+ const model=createModel(internal);
+ model.secretScopes=secretScopes;
+ model.nameKey=internal.nameKey;
+ model.fieldVisible=(key,draft)=>fields[key]?.visible?.(draft)??true;
+ model.fieldDefinition=(key,draft)=>fields[key]?.definition?.(draft)??fields[key];
+ const originalSummaryKeys=model.summaryKeys;
+ model.summaryKeys=(draft,state)=>originalSummaryKeys(draft,state).filter(key=>model.fieldVisible(key,draft));
+ model.groupDefinition=(group,draft)=>{const variant=group.presentations?.find(item=>setupConditionMatches(item.when,draft));return {...group,...variant,title:variant?.label??group.title};};
+ model.groupKeys=(group,draft)=>group.keys.filter(key=>model.fieldVisible(key,draft)).map((key,index)=>({key,index,order:model.fieldDefinition(key,draft).order??index})).sort((a,b)=>a.order-b.order||a.index-b.index).map(item=>item.key);
+ model.validateInput=(input,known={})=>{
+  if(!input||typeof input!=='object'||Array.isArray(input))throw Error('Provide setup inputs from rer-setup.json.');
+  const draft={...defaults,...input};
+  for(const [key,value] of Object.entries(input)){
+   if(!Object.hasOwn(fields,key))throw Error(`Undeclared setup input ${key} in rer-setup.json.`);
+   if(value!==''&&value!==undefined&&!fields[key].valid(value))throw Error(`Invalid setup input ${key}.`);
+  }
+  const readiness=model.setupModel(draft,known);
+  if(!readiness.ready)throw Error(`Provide required setup inputs: ${[...readiness.missing,...readiness.connections].join(', ')}.`);
+  return model.installInput(draft);
+ };
+ return model;
+}
+
+// The Node branch is loaded only by the server/CLI, never by the browser.
+export async function loadInstallerSeed(root,seed) {
+ refuseLegacySetup(seed);
+ const file=seed?.setup?.manifestFile;
+ const {readFile,lstat}=await import('node:fs/promises');
+ const {resolve,join}=await import('node:path');
+ const {pathToFileURL}=await import('node:url');
+ const privateName=/^(?:\.env(?:\..*)?|\.dev\.vars(?:\..*)?|\.npmrc|\.yarnrc(?:\.yml)?|\.?netrc|_netrc|\.pypirc|\.git-credentials|\.gitconfig|\.dockercfg|(?:owner|providers)\.json|credentials(?:\.(?:json|ini|toml|yaml|yml))?|id_(?:rsa|ed25519|ecdsa|dsa)(?:\..*)?|.*\.(?:pem|key|p12|pfx))$/i;
+ const privateDirectories=new Set(['.git','.seed','.ssh','.aws','.wrangler','node_modules']);
+ const reserved=new Set(['release-provenance.json','rer-broker-entry.js']);
+ if(typeof file!=='string'||!/\.json$/i.test(file)||file.length>512||/^[a-z]:/i.test(file)||/[\x00-\x1f\x7f"\\]/.test(file)||file.split('/').some(part=>!part||part==='.'||part==='..'||privateName.test(part)||privateDirectories.has(part.toLowerCase())||reserved.has(part.toLowerCase())))throw Error(`Select a root-relative JSON setup manifest ${file??'rer-setup.json'} without .. or symlinks.`);
+ let bytes;
+ try{
+  let path=resolve(root);const parts=file.split('/');
+  for(const [index,part]of parts.entries()){
+   path=join(path,part);const stat=await lstat(path);
+   if(stat.isSymbolicLink())throw Error('symlink refused');
+   if(index<parts.length-1?!stat.isDirectory():!stat.isFile())throw Error('expected a regular manifest file');
+  }
+  bytes=await readFile(path);
+ }catch(error){throw Error(`Cannot read setup manifest ${file}: ${error.message}`);}
+ const schemaBytes=await readFile(new URL('./schema/SETUP.schema.json',import.meta.url));
+ const manifest=readSetupManifestBytes(bytes,schemaBytes,file);
+ let presentation=seed.presentation??{product:{name:seed.product},features:seed.features};
+ if(seed.browserModule){presentation=await import(pathToFileURL(join(resolve(root),seed.browserModule)).href+'?installer='+Date.now());refuseLegacySetup(presentation);}
+ const options={ownerBootstrap:seed.ownerBootstrap===true,supplied:seed.supplied??[]};
+ const model=createInstallerModel(manifest,presentation,options);
+ return {...seed,manifest,manifestBytes:bytes,schemaBytes,model,modelOptions:options,features:presentation.features??seed.features??{}};
+}

package/onboarding/state.mjs

@@ -0,0 +1,46 @@
+import { credentialFingerprint } from './secrets.mjs';
+import { createCommands } from './commands.mjs';
+import { createActivity } from './activity.mjs';
+import { rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { privateDirectory, readPrivateFile, writePrivateFile } from './private-files.mjs';
+export async function createState(root,seed) {
+ const fields=seed.model.safeKeys;
+ const directory=await privateDirectory(root,['.seed','installer']);
+ const file=join(directory,'state.json'); let saved={};
+ try { const value=JSON.parse(await readPrivateFile(file)); if(value&&typeof value==='object') saved=value; } catch(error) { if(error.code!=='ENOENT' && !(error instanceof SyntaxError)) throw error; }
+ if(saved.product&&saved.product!==seed.product)throw Error('Saved installer details belong to another seed.');
+ saved.draft=Object.fromEntries(Object.entries(saved.draft||{}).filter(([key,value])=>fields.includes(key)&&typeof value==='string'));
+ // Older receipts did not distinguish suggestions from answers. Preserve their
+ // saved owner details; newly written receipts carry the exact answer set.
+ const answered=(Array.isArray(saved.answered)?saved.answered:Object.keys(saved.draft)).filter(key=>typeof key==='string'&&Object.hasOwn(saved.draft,key));
+ const state={phase:'ready',step:'Ready to install',logs:[],answered:[...new Set(answered)],sources:Object.fromEntries(Object.entries(saved.sources||{}).filter(([key,value])=>fields.includes(key)&&['agent','browser','saved'].includes(value))),lastUpdate:{revision:Number.isSafeInteger(saved.lastUpdate?.revision)?saved.lastUpdate.revision:0,source:'saved',keys:[]},draft:saved.draft||{},known:{product:seed.product,root,nodeVersion:process.version},...(saved.phase==='running'?{error:'The previous run was interrupted. Review the details before starting again.'}:{})};
+ // Remember invalidated credential identities privately, never their bytes.
+ // A replacement written to settings has a different identity and can resume.
+ const invalidatedSecrets=new Map((Array.isArray(saved.invalidatedSecrets)?saved.invalidatedSecrets:[]).filter(item=>item&&Object.hasOwn(seed.model.secretScopes||{},item.name)&&/^[a-f0-9]{64}$/.test(item.fingerprint)).map(item=>[item.name+':'+item.fingerprint,{name:item.name,fingerprint:item.fingerprint}]));
+ const activity=createActivity(state,fields);
+ const commands=await createCommands(directory,state);
+ let pending=Promise.resolve();
+ const persist=()=>{const content=JSON.stringify({product:seed.product,phase:state.phase,draft:state.draft,answered:state.answered,sources:state.sources,lastUpdate:state.lastUpdate,invalidatedSecrets:[...invalidatedSecrets.values()]});pending=pending.then(async()=>{await writePrivateFile(file+'.tmp',content);await rename(file+'.tmp',file)});return pending};
+ return {state,activity,...commands,
+  isInvalidatedSecret(name,value){return typeof value==='string'&&invalidatedSecrets.has(name+':'+credentialFingerprint(value));},
+  async invalidateSecrets(keys){
+   let changed=false;for(const item of keys){const key=item.name+':'+item.fingerprint;if(!invalidatedSecrets.has(key)){invalidatedSecrets.set(key,item);changed=true;}}
+   if(changed)await persist();else await pending;
+  },
+  async acceptSecrets(input){
+   let changed=false;for(const name of Object.keys(seed.model.secretScopes||{}))if(typeof input[name]==='string')changed=invalidatedSecrets.delete(name+':'+credentialFingerprint(input[name]))||changed;
+   if(changed)await persist();else await pending;
+  },
+  async draft(input,source='browser',updatedKeys=Object.keys(input)){
+   const keys=updatedKeys.filter(key=>fields.includes(key)&&typeof input[key]==='string');
+   for(const key of keys)if(source==='agent'||input[key]!==state.draft[key])state.sources[key]=source;
+   state.lastUpdate={source,keys,revision:state.lastUpdate.revision+1};
+   state.answered=[...new Set([...state.answered,...keys])].filter(key=>fields.includes(key)&&typeof input[key]==='string');
+   state.draft=Object.fromEntries(fields.filter(key=>typeof input[key]==='string').map(key=>[key,input[key]]));
+   await persist();if(source==='agent')activity.filled(keys);
+  },
+  async step(label){label=commands.redact(label);state.step=label;commands.report(label);activity.step(label);await persist()},
+  async phase(phase){state.phase=phase;activity.phase(phase);await persist()}
+ };
+}

package/onboarding/theme-files.mjs

@@ -0,0 +1,37 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { readTheme } from './theme.mjs';
+
+const types = { '.css': 'text/css', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf', '.svg': 'image/svg+xml', '.png': 'image/png', '.webp': 'image/webp' };
+const limit = 8 * 1024 * 1024;
+
+async function regularFile(root, relative) {
+ let path = resolve(root);
+ const parts = relative.split('/');
+ for (const [index, part] of parts.entries()) {
+  path = join(path, part);
+  const stat = await lstat(path);
+  if (stat.isSymbolicLink()) throw Error(`${relative} is a symlink.`);
+  if (index < parts.length - 1 ? !stat.isDirectory() : !stat.isFile()) throw Error(`${relative} is not a regular file.`);
+ }
+ return readFile(path);
+}
+
+// `file` is root-relative and sits at the root of the directory the app serves
+// as "/", so every url("/path") in the theme names a file beside it there.
+// Returns the served files keyed by installer path, read once at start.
+export async function loadSeedTheme(root, file) {
+ if (typeof file !== 'string' || !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\.css$/.test(file) || file.split('/').some(part => part === '..' || part === '.'))
+  throw Error(`Declare the seed theme as a root-relative .css path without .. (got ${JSON.stringify(file)}).`);
+ const text = (await regularFile(root, file).catch(error => { throw Error(`Cannot read seed theme ${file}: ${error.message}`); })).toString('utf8');
+ const theme = readTheme(text, file), served = dirname(file);
+ const files = new Map([['/rer-theme.css', { type: 'text/css', bytes: Buffer.from(text) }]]);
+ let total = text.length;
+ for (const path of theme.assets) {
+  const bytes = await regularFile(root, join(served, path.slice(1))).catch(error => { throw Error(`Seed theme ${file} names ${path}, which the app does not serve from ${served}/: ${error.message}`); });
+  total += bytes.length;
+  if (total > limit) throw Error(`Seed theme ${file} and its files exceed 8 MiB.`);
+  files.set(path, { type: types[path.slice(path.lastIndexOf('.'))], bytes });
+ }
+ return { ...theme, files };
+}

package/onboarding/theme.mjs

@@ -0,0 +1,118 @@
+// A seed theme is one plain CSS file that the seed's app already serves:
+// `:root { --rer-*: value }` tokens plus `@font-face` rules for font files the
+// app serves itself. Base frames link that file; this module is the one place
+// that reads it, refuses anything outside the grammar and checks contrast.
+const colour = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const family = String.raw`(?:"[A-Za-z0-9 _-]+"|'[A-Za-z0-9 _-]+'|[A-Za-z][A-Za-z0-9 _-]*)`;
+const stack = new RegExp(String.raw`^${family}(?:\s*,\s*${family})*$`);
+const assetPath = /^\/(?!.*\/\/)(?!.*\/\.)[A-Za-z0-9._~/-]{1,200}$/;
+const url = /^url\(\s*(["']?)([^"')]+)\1\s*\)$/;
+
+export const themeTokens = Object.freeze({
+ '--rer-page': 'colour', '--rer-surface': 'colour', '--rer-text': 'colour', '--rer-muted': 'colour',
+ '--rer-border': 'colour', '--rer-focus': 'colour', '--rer-accent': 'colour', '--rer-accent-text': 'colour',
+ '--rer-link': 'colour', '--rer-font-body': 'stack', '--rer-font-heading': 'stack', '--rer-radius': 'radius', '--rer-logo': 'logo',
+});
+const required = ['--rer-page', '--rer-surface', '--rer-text', '--rer-muted', '--rer-border', '--rer-focus'];
+
+// WCAG 2.2: 4.5:1 for text, 3:1 for focus indicators and control boundaries.
+const pairs = [
+ ['--rer-text', '--rer-page', 4.5], ['--rer-text', '--rer-surface', 4.5], ['--rer-muted', '--rer-surface', 4.5], ['--rer-muted', '--rer-page', 4.5],
+ ['--rer-link', '--rer-surface', 4.5], ['--rer-accent-text', '--rer-accent', 4.5],
+ ['--rer-focus', '--rer-page', 3], ['--rer-focus', '--rer-surface', 3], ['--rer-border', '--rer-surface', 3],
+];
+
+const faceDescriptors = {
+ 'font-family': value => new RegExp(`^${family}$`).test(value),
+ 'font-style': value => /^(?:normal|italic|oblique)$/.test(value),
+ 'font-weight': value => /^(?:normal|bold|\d{1,3}(?:\s+\d{1,3})?)$/.test(value),
+ 'font-display': value => /^(?:auto|block|swap|fallback|optional)$/.test(value),
+ 'unicode-range': value => /^U\+[0-9A-F?]{1,6}(?:-[0-9A-F]{1,6})?(?:\s*,\s*U\+[0-9A-F?]{1,6}(?:-[0-9A-F]{1,6})?)*$/i.test(value),
+ 'size-adjust': value => /^\d{1,3}(?:\.\d+)?%$/.test(value),
+ 'ascent-override': value => /^(?:normal|\d{1,3}(?:\.\d+)?%)$/.test(value),
+ 'descent-override': value => /^(?:normal|\d{1,3}(?:\.\d+)?%)$/.test(value),
+ 'line-gap-override': value => /^(?:normal|\d{1,3}(?:\.\d+)?%)$/.test(value),
+ src: null,
+};
+
+function asset(value, extensions, what) {
+ const path = url.exec(value)?.[2];
+ if (!path || !assetPath.test(path) || !extensions.test(path)) throw Error(`${what} must be url("/path") to a file the app serves (${extensions.source.match(/\w+/g).join(', ')}).`);
+ return path;
+}
+
+function declarations(body, where) {
+ const result = [];
+ for (const part of body.split(';')) {
+  if (!part.trim()) continue;
+  const index = part.indexOf(':');
+  if (index < 0) throw Error(`${where}: expected "name: value" in "${part.trim().slice(0, 60)}".`);
+  const name = part.slice(0, index).trim(), value = part.slice(index + 1).trim().replace(/\s+/g, ' ');
+  if (!name || !value) throw Error(`${where}: empty declaration.`);
+  if (result.some(entry => entry[0] === name)) throw Error(`${where}: ${name} is declared twice.`);
+  result.push([name, value]);
+ }
+ return result;
+}
+
+function luminance(hex) {
+ const full = hex.length === 4 ? '#' + [...hex.slice(1)].map(c => c + c).join('') : hex;
+ const [r, g, b] = [1, 3, 5].map(i => parseInt(full.slice(i, i + 2), 16) / 255).map(v => v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a, b) {
+ const [high, low] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+ return (high + 0.05) / (low + 0.05);
+}
+
+// Returns {tokens, faces, assets}; throws one error naming every problem.
+export function readTheme(css, file = 'rer-theme.css') {
+ if (typeof css !== 'string' || css.length > 64 * 1024) throw Error(`${file}: a theme is a CSS file of at most 64 KiB.`);
+ if (/[\\<]/.test(css)) throw Error(`${file}: escapes and "<" are not part of the theme grammar.`);
+ let rest = css.replace(/\/\*[\s\S]*?\*\//g, ' ');
+ if (rest.includes('/*')) throw Error(`${file}: unterminated comment.`);
+ const tokens = {}, faces = [], assets = new Set();
+ while ((rest = rest.trim())) {
+  const block = /^(:root|@font-face)\s*\{([^{}]*)\}/.exec(rest);
+  if (!block) throw Error(`${file}: only :root { --rer-* } and @font-face { } blocks are allowed, found "${rest.slice(0, 40)}".`);
+  rest = rest.slice(block[0].length);
+  if (block[1] === ':root') {
+   for (const [name, value] of declarations(block[2], ':root')) {
+    const kind = themeTokens[name];
+    if (!kind) throw Error(`${file}: ${name} is not a theme token. Use ${Object.keys(themeTokens).join(', ')}.`);
+    if (Object.hasOwn(tokens, name)) throw Error(`${file}: ${name} is declared twice.`);
+    if (kind === 'colour' && !colour.test(value)) throw Error(`${file}: ${name} must be a #rgb or #rrggbb colour.`);
+    if (kind === 'stack' && !stack.test(value)) throw Error(`${file}: ${name} must be a font stack of family names.`);
+    if (kind === 'radius' && !/^\d{1,2}(?:\.\d+)?(?:px|rem)$/.test(value)) throw Error(`${file}: ${name} must be a length in px or rem.`);
+    if (kind === 'logo') assets.add(asset(value, /\.(?:svg|png|webp)$/, name));
+    tokens[name] = value;
+   }
+  } else {
+   const face = Object.fromEntries(declarations(block[2], '@font-face'));
+   for (const [name, value] of Object.entries(face)) {
+    if (!Object.hasOwn(faceDescriptors, name)) throw Error(`${file}: @font-face ${name} is not supported.`);
+    if (name !== 'src' && !faceDescriptors[name](value)) throw Error(`${file}: @font-face ${name} "${value}" is not valid.`);
+   }
+   if (!face['font-family'] || !face.src) throw Error(`${file}: @font-face needs font-family and src.`);
+   for (const source of face.src.split(',').map(value => value.trim())) {
+    if (/^local\(\s*(["'])[A-Za-z0-9 _-]+\1\s*\)$/.test(source)) continue;
+    const [location, format] = source.split(/\s+(?=format\()/);
+    if (format && !/^format\(\s*(["'])(?:woff2|woff|truetype|opentype)\1\s*\)$/.test(format)) throw Error(`${file}: @font-face format ${format} is not supported.`);
+    assets.add(asset(location, /\.(?:woff2|woff|ttf|otf)$/, '@font-face src'));
+   }
+   faces.push(face);
+  }
+ }
+ const problems = [];
+ for (const name of required) if (!tokens[name]) problems.push(`declare ${name}`);
+ if (Boolean(tokens['--rer-accent']) !== Boolean(tokens['--rer-accent-text'])) problems.push('declare --rer-accent and --rer-accent-text together');
+ const value = name => tokens[name] ?? (name === '--rer-link' ? tokens['--rer-text'] : undefined);
+ for (const [foreground, background, minimum] of pairs) {
+  if (!value(foreground) || !value(background)) continue;
+  const ratio = contrast(value(foreground), value(background));
+  if (ratio < minimum) problems.push(`${foreground} ${value(foreground)} on ${background} ${value(background)} is ${ratio.toFixed(2)}:1, below ${minimum}:1`);
+ }
+ if (problems.length) throw Error(`${file}: ${problems.join('; ')}.`);
+ return Object.freeze({ tokens: Object.freeze(tokens), faces: Object.freeze(faces), assets: Object.freeze([...assets]) });
+}