@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/container/remote/resources.py

@@ -0,0 +1,157 @@
+"""Operate only on fresh Docker inventory, never on stored executable config."""
+import subprocess, socket, io, tarfile
+
+
+def docker(*args, input=None):
+    result = subprocess.run(['docker', *args], input=input, capture_output=True, text=not isinstance(input, bytes), timeout=120)
+    if result.returncode:
+        # Docker may echo environment/configuration. Never propagate its output.
+        refuse('Docker host operation failed: ' + args[0])
+    return (result.stdout.decode() if isinstance(result.stdout, bytes) else result.stdout).strip()
+
+
+def inspect(kind, names):
+    return json.loads(docker(kind, 'inspect', *names)) if names else []
+
+
+def labels_for(plan, role):
+    return {**plan['labels'], 'io.runeditrun.role': role}
+
+
+def check_labels(plan, role, actual):
+    if any((actual or {}).get(key) != value for key, value in labels_for(plan, role).items()):
+        refuse('Docker resource ownership mismatch: ' + role)
+
+
+def inventory(plan):
+    resources = {'container': {}, 'volume': {}, 'network': {}}
+    # Inventory every container so foreign mounts, network peers and occupied
+    # bindings are accounted for, even when they carry no RER label at all.
+    containers = inspect('container', docker('container', 'ls', '-aq').split())
+    for item in containers:
+        resources['container'][item['Name'].lstrip('/')] = item
+    for kind in ('volume', 'network'):
+        names = docker(kind, 'ls', '--format', '{{.Name}}').splitlines()
+        for item in inspect(kind, names):
+            resources[kind][item['Name']] = item
+    expected = {'container': ['app', 'caddy'], 'volume': ['data', 'caddy', 'caddy-config'], 'network': ['ingress']}
+    owned = {'container': {}, 'volume': {}, 'network': {}}
+    for kind, objects in resources.items():
+        for name, item in objects.items():
+            labels = item.get('Config', {}).get('Labels') if kind == 'container' else item.get('Labels')
+            matching_name = name in [plan['name'] + '-' + role for role in expected[kind]]
+            matching_owner = (labels or {}).get('io.runeditrun.installation') == plan['labels']['io.runeditrun.installation']
+            # Old compose-labelled extra services can otherwise be selected by
+            # compose down. Refuse these too rather than silently adopting them.
+            matching_compose = (labels or {}).get('com.docker.compose.project') == plan['name']
+            if matching_name or matching_owner or matching_compose:
+                role = name.removeprefix(plan['name'] + '-')
+                if role not in expected[kind] or name != plan['name'] + '-' + role:
+                    refuse('Unexpected Docker installation resource')
+                check_labels(plan, role, labels)
+                owned[kind][role] = item
+                if kind == 'volume' and (item.get('Driver') != 'local' or item.get('Options')):
+                    refuse('Unsafe Docker volume driver/options')
+                if kind == 'network' and (item.get('Driver') != 'bridge' or item.get('Options') or item.get('Internal') or item.get('ConfigOnly')):
+                    refuse('Unsafe Docker ingress network')
+    owned_ids = {item['Id'] for item in owned['container'].values()}
+    for item in containers:
+        if item['Id'] not in owned_ids:
+            if any(mount.get('Name') in {v['Name'] for v in owned['volume'].values()} for mount in item.get('Mounts', [])):
+                refuse('Foreign container uses installation volume')
+    for network in owned['network'].values():
+        if any(key not in owned_ids for key in (network.get('Containers') or {})):
+            refuse('Foreign container uses installation network')
+    return owned, containers
+
+
+def admit_ports(plan, owned, containers):
+    own_ids = {item['Id'] for item in owned['container'].values()}
+    for binding in plan['ports']:
+        address, port, _ = binding.split(':')
+        occupied_by_own = False
+        for item in containers:
+            if not item.get('State', {}).get('Running'):
+                continue
+            for entries in (item.get('NetworkSettings', {}).get('Ports') or {}).values():
+                for entry in entries or []:
+                    overlap = address == '0.0.0.0' or entry['HostIp'] in ('0.0.0.0', '::', address)
+                    if entry['HostPort'] == port and overlap:
+                        if item['Id'] not in own_ids:
+                            refuse('Host ingress binding is already occupied')
+                        occupied_by_own = True
+        if not occupied_by_own:
+            with socket.socket() as listener:
+                try:
+                    listener.bind((address, int(port)))
+                except OSError:
+                    refuse('Host ingress binding is unavailable')
+
+
+def label_args(plan, role):
+    return [arg for key, value in labels_for(plan, role).items() for arg in ('--label', key + '=' + value)]
+
+
+def prepare_resources(plan, owned):
+    # Images and persistent resources must be available before stopping service.
+    app = json.loads(docker('image', 'inspect', plan['digest']))[0]
+    if app['Id'] != plan['digest']:
+        refuse('Application image identity mismatch')
+    caddy = None
+    if not plan['local']:
+        if not docker('image', 'ls', '--quiet', 'caddy:2.10.2'):
+            docker('image', 'pull', 'caddy:2.10.2')
+        caddy = json.loads(docker('image', 'inspect', 'caddy:2.10.2'))[0]['Id']
+    for role in (['data'] if plan['local'] else ['data', 'caddy', 'caddy-config']):
+        if role not in owned['volume']:
+            docker('volume', 'create', *label_args(plan, role), plan['name'] + '-' + role)
+    if 'ingress' not in owned['network']:
+        docker('network', 'create', '--driver', 'bridge', *label_args(plan, 'ingress'), plan['name'] + '-ingress')
+    return caddy
+
+
+def replace_containers(plan, validate, files, caddy):
+    # Configuration is the exact content checked in the owned generation.
+    # Never ask either Docker client or daemon to reopen a host pathname after
+    # shutdown; their filesystem/process namespaces may also be different.
+    archive = io.BytesIO()
+    if caddy:
+        content = files['Caddyfile'].encode()
+        with tarfile.open(fileobj=archive, mode='w') as bundle:
+            entry = tarfile.TarInfo('Caddyfile')
+            entry.size, entry.mode = len(content), 0o600
+            bundle.addfile(entry, io.BytesIO(content))
+    owned, containers = inventory(plan)
+    admit_ports(plan, owned, containers)
+    validate()
+    # Stop by immutable IDs, with fresh labels on each individual operation.
+    # rm never uses -v: persistent data survives replacement and failures.
+    for role, item in owned['container'].items():
+        current = inspect('container', [item['Id']])[0]
+        check_labels(plan, role, current['Config'].get('Labels'))
+        validate()
+        docker('container', 'stop', '--time', '10', item['Id'])
+        check_labels(plan, role, inspect('container', [item['Id']])[0]['Config'].get('Labels'))
+        docker('container', 'rm', item['Id'])
+    common = ['--restart', 'unless-stopped', '--network', plan['name'] + '-ingress']
+    app = ['container', 'create', '--name', plan['name'] + '-app', *label_args(plan, 'app'), *common, '--network-alias', 'app', '--env-file', '/dev/stdin', '--env', 'PORT=8080', '--env', 'RER_IMAGE_DIGEST=' + plan['digest'], '--mount', 'type=volume,source=' + plan['name'] + '-data,target=/data']
+    if plan['local']:
+        for binding in plan['ports']:
+            app.extend(['--publish', binding])
+    else:
+        app.extend(['--env', 'TRUSTED_PROXY=caddy'])
+    app.append(plan['digest'])
+    inventory(plan)
+    app_id = docker(*app, input=files['settings.env'])
+    if caddy:
+        args = ['container', 'create', '--name', plan['name'] + '-caddy', *label_args(plan, 'caddy'), *common, '--network-alias', 'caddy', '--mount', 'type=volume,source=' + plan['name'] + '-caddy,target=/data', '--mount', 'type=volume,source=' + plan['name'] + '-caddy-config,target=/config']
+        for binding in plan['ports']:
+            args.extend(['--publish', binding])
+        args.append(caddy)
+        inventory(plan)
+        caddy_id = docker(*args)
+        check_labels(plan, 'caddy', inspect('container', [caddy_id])[0]['Config'].get('Labels'))
+        docker('container', 'cp', '-', caddy_id + ':/etc/caddy/', input=archive.getvalue())
+        docker('container', 'start', caddy_id)
+    check_labels(plan, 'app', inspect('container', [app_id])[0]['Config'].get('Labels'))
+    docker('container', 'start', app_id)

package/modules/container/runner.mjs

@@ -0,0 +1,10 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+export function superviseRunner({ root, manifest, settings, failed }) {
+ if (!manifest.runner) return { running:()=>true, async close(){} };
+ const child=spawn(process.execPath,[join(root,'runner',manifest.runner.entry)],{cwd:join(root,'runner'),env:{...process.env,...settings},stdio:['ignore','ignore','ignore']});
+ let stopping=false;
+ child.once('error',()=>{if(!stopping)failed();});
+ child.once('exit',()=>{if(!stopping)failed();});
+ return { running:()=>child.exitCode===null&&child.signalCode===null, async close(){stopping=true;if(child.exitCode!==null||child.signalCode!==null)return;child.kill('SIGTERM');await new Promise(resolve=>{const timer=setTimeout(()=>child.kill('SIGKILL'),35000);child.once('exit',()=>{clearTimeout(timer);resolve();});});} };
+}

package/modules/container/ssh-plan.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { ingressBindings } from '../deploy-kit/container-config.mjs';
+export { ingressBindings } from '../deploy-kit/container-config.mjs';
+
+export function installationIdentity(project, environment = 'production') {
+ if (typeof project !== 'string' || !/^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/.test(project) || project.length > 512 || !/^[a-z][a-z0-9-]{0,39}$/.test(environment)) throw Error('Invalid installation identity');
+ const identity = createHash('sha256').update(JSON.stringify([project, environment])).digest('hex');
+ return { name: `rer-${identity}`, labels: { 'io.runeditrun.managed': 'ssh-v1', 'io.runeditrun.installation': identity, 'io.runeditrun.project': project, 'io.runeditrun.environment': environment } };
+}
+
+
+export function deploymentPlan({ declaration, settings, environment, digest, ingress }) {
+ const { name, labels } = installationIdentity(declaration.project, environment);
+ if (!/^sha256:[a-f0-9]{64}$/.test(digest)) throw Error('Invalid Docker image digest');
+ const origin = settings[declaration.originVar] ?? settings.PUBLIC_ORIGIN;
+ if (!origin) throw Error('Declare the public origin in the private env file');
+ const url = new URL(origin);
+ if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw Error('Invalid public origin');
+ const local = /^(localhost|127\.0\.0\.1|\[::1\])$/.test(url.hostname);
+ if (!local && url.protocol !== 'https:') throw Error('Production ingress requires HTTPS');
+ if (local && url.protocol !== 'http:') throw Error('Loopback qualification requires an HTTP origin');
+ const hostnames = [url.hostname];
+ for (const variable of declaration.container?.hostVariables ?? []) {
+  const hostname = settings[variable];
+  if (!hostname || !/^(?=.{1,253}$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i.test(hostname)) throw Error('Invalid declared ingress hostname');
+  if (!hostnames.includes(hostname)) hostnames.push(hostname);
+ }
+ const bindings = ingressBindings({ ...declaration.container?.ingress, ...ingress });
+ const roleLabels = role => ({ ...labels, 'io.runeditrun.role': role });
+ const volume = role => ({ name: `${name}-${role}`, labels: roleLabels(role) });
+ const ports = local ? [`127.0.0.1:${url.port || 80}:8080`] : [`${bindings.address}:${bindings.httpPort}:80`, `${bindings.address}:${bindings.httpsPort}:443`];
+ const compose = { name, services: { app: { image: digest, container_name: `${name}-app`, labels: roleLabels('app'), restart: 'unless-stopped', environment: { RER_IMAGE_DIGEST: digest, PORT: '8080', ...(local ? {} : { TRUSTED_PROXY: 'caddy' }) }, env_file: [{ path: 'settings.env', format: 'raw' }], volumes: ['data:/data'], networks: ['ingress'], ...(local ? { ports } : {}) } }, volumes: { data: volume('data') }, networks: { ingress: { name: `${name}-ingress`, labels: roleLabels('ingress') } } };
+ if (!local) {
+  compose.services.caddy = { image: 'caddy:2.10.2', container_name: `${name}-caddy`, labels: roleLabels('caddy'), restart: 'unless-stopped', ports, configs: [{ source: 'caddy', target: '/etc/caddy/Caddyfile' }], volumes: ['caddy:/data', 'caddy-config:/config'], networks: ['ingress'] };
+  compose.volumes.caddy = volume('caddy'); compose.volumes['caddy-config'] = volume('caddy-config');
+ }
+ // Listener ports are internal. A TCP/SNI proxy must preserve the public
+ // authority and route ACME HTTP/TLS challenges to these private bindings.
+ const sites = hostnames.map(hostname => `https://${hostname}`).join(', ');
+ const redirects = hostnames.map(hostname => `http://${hostname} {\n redir https://${hostname}${url.port ? ':' + url.port : ''}{uri} permanent\n}`).join('\n');
+ const caddyfile = `{\n auto_https disable_redirects\n}\n${sites} {\n reverse_proxy app:8080\n}\n${redirects}\n`;
+ if (!local) compose.configs = { caddy: { content: caddyfile } };
+ return { name, labels, origin, digest, local, ports, compose, caddyfile };
+}

package/modules/container/ssh.mjs

@@ -0,0 +1,63 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { deploymentPlan } from './ssh-plan.mjs';
+import { deployInputs } from './deploy-input.mjs';
+const execute=promisify(execFile);
+export const quote=value=>"'"+String(value).replaceAll("'","'\\''")+"'";
+export function sshTarget(value){
+ let url;try{url=new URL(value);}catch{throw new Error('Host must be ssh://user@host[:port]');}
+ if(url.protocol!=='ssh:'||url.password||url.search||url.hash||!['','/'].includes(url.pathname)||!url.username||!/^[a-zA-Z0-9_.-]+$/.test(url.username)||!/^([a-zA-Z0-9.-]+|\[[0-9a-fA-F:]+\])$/.test(url.hostname))throw new Error('Invalid ssh host');
+ const args=['-o','BatchMode=yes','-o','StrictHostKeyChecking=yes'];
+ if(process.env.RER_SSH_IDENTITY)args.push('-i',resolve(process.env.RER_SSH_IDENTITY));
+ if(process.env.RER_SSH_KNOWN_HOSTS)args.push('-o','UserKnownHostsFile='+resolve(process.env.RER_SSH_KNOWN_HOSTS));
+ if(url.port)args.push('-p',url.port);args.push(url.username+'@'+url.hostname.replace(/^\[|\]$/g,''));return args;
+}
+export async function deploySSH({root,host,image,envFile,environment='production',localOnlyKeys=[],dryRun=false,ingress}) {
+ const ssh=sshTarget(host),{declaration,settings,encoded}=await deployInputs({root,envFile,localOnlyKeys});
+ const {stdout:digestText}=await execute('docker',['image','inspect','--format','{{.Id}}',image]);
+ const plan=deploymentPlan({declaration,settings,environment,digest:digestText.trim(),ingress});
+ const directory=join(root,'.rer/container/deploy');await mkdir(directory,{recursive:true,mode:0o700});
+ await writeFile(join(directory,'compose.yaml'),JSON.stringify(plan.compose,null,2)+'\n',{mode:0o600});
+ await writeFile(join(directory,'Caddyfile'),plan.caddyfile,{mode:0o600});
+ if(dryRun)return{dryRun:true,deployed:false,origin:plan.origin,installation:'.rer-host/'+plan.name,compose:join(directory,'compose.yaml')};
+ // The code is transferred from this installation's maintained CLI. No remote
+ // Python, shell or compose file is ever imported or executed from disk.
+ const source=(await Promise.all(['files','resources','deploy'].map(name=>readFile(new URL('./remote/'+name+'.py',import.meta.url),'utf8')))).join('\n');
+ const command='python3 -I -c '+quote(source);
+ const remote=async payload=>{
+  const child=spawn('ssh',[...ssh,command],{stdio:['pipe','pipe','pipe']});
+  const result=completed(child,true);child.stdin.on('error',()=>{});child.stdin.end(JSON.stringify(payload));return result;
+ };
+ // This also proves Python and Docker availability, filesystem custody and
+ // existing resource ownership before loading an image or sending secrets.
+ await remote({plan,phase:'check'});
+ const load=spawn('ssh',[...ssh,'docker load'],{stdio:['pipe','pipe','pipe']}),save=spawn('docker',['save',plan.digest],{stdio:['ignore','pipe','pipe']});
+ load.stdin.on('error',()=>{});save.stdout.pipe(load.stdin);
+ try{await Promise.all([completed(save),completed(load)]);}finally{if(save.exitCode===null)save.kill('SIGTERM');if(load.exitCode===null)load.kill('SIGTERM');}
+ const result=JSON.parse(await remote({plan,files:{'settings.env':encoded,'compose.yaml':JSON.stringify(plan.compose,null,2)+'\n','Caddyfile':plan.caddyfile}}));
+ const end=Date.now()+60000;
+ while(Date.now()<end){
+  try{const response=await fetch(plan.origin+'/health',{signal:AbortSignal.timeout(3000)});if(response.ok){const health=await response.json();if(health.platform==='container'&&health.deployment?.versionId===plan.digest)return{deployed:true,origin:plan.origin,imageDigest:plan.digest,...result};}}catch{}
+  await new Promise(resolve=>setTimeout(resolve,250));
+ }
+ throw new Error('Container public health did not become ready; inspect host logs');
+}
+
+const hostRefusals=new Set(['Unsafe host path ownership, permissions or type','Unsafe account home','Account home is not owned by login user','Host deployment path changed','Host deployment file changed','Installation ownership mismatch','Unexpected deployment file','Unexpected installation path','Unexpected Docker installation resource','Unsafe Docker volume driver/options','Unsafe Docker ingress network','Foreign container uses installation volume','Foreign container uses installation network','Host ingress binding is already occupied','Host ingress binding is unavailable','Application image identity mismatch','Host deployment refused: unsafe path or failed operation']);
+function hostFailure(stderr){
+ const reason=stderr.trim();
+ const message=hostRefusals.has(reason)||/^Docker resource ownership mismatch: (app|caddy|caddy-config|data|ingress)$/.test(reason)||/^Docker host operation failed: (image|volume|network|container)$/.test(reason)?reason:'SSH host operation failed';
+ return Object.assign(Error(message),{code:'SSH_HOST_REFUSAL'});
+}
+function completed(child, capture=false) {
+ return new Promise((resolve,reject)=>{
+  let stdout='',stderr='';
+  const timer=setTimeout(()=>{child.kill('SIGTERM');reject(Error('Host operation timed out'));},120000);
+  child.stdout?.on('data',chunk=>{if(capture&&stdout.length<1024*1024)stdout+=chunk;});
+  child.stderr?.on('data',chunk=>{if(capture&&stderr.length<2048)stderr+=chunk;});
+  child.once('error',()=>{clearTimeout(timer);reject(Error('Host operation failed'));});
+  child.once('close',code=>{clearTimeout(timer);code===0?resolve(stdout):reject(capture?hostFailure(stderr):Error('Host operation failed'));});
+ });
+}

package/modules/container/transfer.mjs

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { D1 } from './adapters/d1.mjs';
+import { Objects } from './adapters/objects.mjs';
+import { ensurePortabilitySchema } from './portability-schema.mjs';
+import { migrate } from './migrations.mjs';
+import { createPortability } from '../portability/index.mjs';
+import { migrationReplay } from '../portability/migration-history.mjs';
+import { exportArchive, importArchive } from '../portability/files.mjs';
+let db,platform,worker;
+try {
+ const spec=JSON.parse(await readFile('/private/transfer.json','utf8')),manifest=JSON.parse(await readFile('/app/container.json','utf8'));
+ const buckets={};
+ if(manifest.engine==='node'){
+  db=new D1('/data/'+spec.binding+'.sqlite');await migrate(db,manifest.migrations[spec.binding]);await ensurePortabilitySchema(db,manifest.portabilityMigrations);
+  platform=new DatabaseSync('/data/platform.sqlite');
+  for(const [name,binding]of Object.entries(spec.buckets))buckets[name]=new Objects(platform,'/data/objects',binding);
+ }else{
+  const {workerEngine}=await import('./worker-engine.mjs');worker=await workerEngine({root:'/app',data:'/data',manifest,settings:{}});db=worker.databases[spec.binding];
+  for(const [name,binding]of Object.entries(spec.buckets))buckets[name]=worker.objects[binding];
+ }
+ const service=await createPortability({db,buckets,policy:spec.policy,migrations:async()=>migrationReplay(manifest.migrations[spec.binding],spec.policy)});
+ const receipt=await(spec.direction==='export'?exportArchive:importArchive)(service,'/archive/'+spec.file,spec.transient,spec.journal);
+ console.log(JSON.stringify(receipt));
+}catch(cause){console.error('Container transfer refused or failed:',cause.name);process.exitCode=1;}
+finally{await worker?.close();await db?.close?.();platform?.close();}

package/modules/container/worker-engine.mjs

@@ -0,0 +1,32 @@
+import { Miniflare, convertV4MiniflareOptions } from 'miniflare';
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { rootCertificates } from 'node:tls';
+import { ensurePortabilitySchema } from './portability-schema.mjs';
+import { migrate } from './migrations.mjs';
+async function files(root) { const result = []; for (const item of await readdir(root, { withFileTypes: true })) { const path = join(root, item.name); if (item.isDirectory()) result.push(...await files(path)); else if (/\.(m?js)$/.test(item.name)) result.push(path); } return result; }
+export async function workerEngine({ root, data, manifest, settings, edge }) {
+ const config = manifest.config, directory = join(root, 'dist/server'), entry = join(root, manifest.entry);
+ const modules = [entry, ...(await files(directory)).filter(path => path !== entry)].map(path => ({ type: 'ESModule', path }));
+ const app = { name:'app', modules, modulesRoot:directory, compatibilityDate:config.compatibility_date, compatibilityFlags:config.compatibility_flags,
+  bindings:{ ...config.vars, ...settings }, d1Databases:Object.fromEntries((config.d1_databases ?? []).map(item => [item.binding, item.database_name])),
+  r2Buckets:Object.fromEntries((config.r2_buckets ?? []).map(item => [item.binding, item.bucket_name])),
+  durableObjects:Object.fromEntries((config.durable_objects?.bindings ?? []).map(item => [item.name, { className:item.class_name, useSQLite:true }])),
+  queueProducers:Object.fromEntries((config.queues?.producers ?? []).map(item => [item.binding, item.queue])),
+  queueConsumers:Object.fromEntries((config.queues?.consumers ?? []).map(item => [item.queue, { maxBatchSize:item.max_batch_size, maxRetries:item.max_retries }])),
+  assets:{ directory:join(root, 'dist/client'), binding:config.assets?.binding ?? 'ASSETS', routerConfig:{ has_user_worker:true }, run_worker_first:config.assets?.run_worker_first ?? false },
+  outboundService: edge ? request => edge(request, request => mf.getWorker('egress').then(worker => worker.fetch(request))) : 'egress',
+ };
+ const mf = new Miniflare(convertV4MiniflareOptions({ host:'127.0.0.1',port:0,cf:false,resourcePersistencePath:data,unsafeLocalExplorer:false,
+  workers:[{ name:'ingress',modules:true,script:`export default {fetch(request,env){const observed=request.headers.get('x-rer-original-url');if(!observed)return new Response(null,{status:400});const url=new URL(observed),headers=new Headers(request.headers);headers.delete('x-rer-original-url');headers.set('host',url.host);return env.APP.fetch(new Request(url,{method:request.method,headers,redirect:'manual',...(!['GET','HEAD'].includes(request.method)?{body:request.body}:{})}))}}`,serviceBindings:{ APP:'app' } }, app,
+   { name:'egress',modules:true,script:'export default {fetch(request,env){return env.NETWORK.fetch(request)}}',serviceBindings:{ NETWORK:{ network:{ allow:['public'],tlsOptions:{ trustBrowserCas:true,trustedCertificates:[...rootCertificates] } } } } }],
+ }));
+ await mf.ready; const databases = {}, objects = {};
+ for (const [binding, plan] of Object.entries(manifest.migrations)) { const db = await mf.getD1Database(binding, 'app'); databases[binding] = db; await migrate(db, plan); await ensurePortabilitySchema(db, manifest.portabilityMigrations); }
+ for (const bucket of config.r2_buckets ?? []) objects[bucket.binding] = await mf.getR2Bucket(bucket.binding, 'app');
+ const worker = await mf.getWorker('app');
+ return { mf, databases, objects, app:worker,
+  fetch(request) { const headers = new Headers(request.headers); headers.set('x-rer-original-url', request.url); return mf.dispatchFetch(request.url, { method:request.method,headers,body:request.body,duplex:'half',redirect:'manual' }); },
+  scheduled:event => worker.scheduled(event), async drain() {}, dead:() => 0, close:() => mf.dispose(),
+ };
+}

package/modules/dependencies/README.md

@@ -0,0 +1,211 @@
+# Application dependency links
+
+This module implements the application side of the pull-link protocol. Auth's
+provider implementation (auth-7) is separate. `createDependencies` mounts the
+well-known routes and owner controls; `AuthConfig.dependencies: true` resolves
+OIDC client settings from the persisted link and the server-generated key.
+No client ID or private-key environment answer is needed. The default seed and
+composed foundation declare an optional `oidc-provider@1` dependency using the
+`IDENTITY_PROVIDER` URL answer. A blank answer keeps email-link access working.
+Other interfaces use the same handshake, storage and callback; only the OIDC
+adapter adds OIDC discovery, sessions, domain policy and owner claims.
+
+## Discovery and registration
+
+`GET /.well-known/rer-dependencies` returns `name`, `version: 1`, the exact
+`origin`, stable `sector_id`, `provides`, `dependencies`, `claim`, `callback`, and
+`jwks_uri`. Each dependency has `interface` (for example `oidc-provider@1`),
+`optional`, `cardinality: 1`, selected `provider` origin or null, registered
+same-origin `paths` as absolute URLs, and a per-interface `jwks_uri`.
+`GET /.well-known/rer-link/jwks/INTERFACE` publishes an ES256 public JWK only.
+The unqualified JWKS URL selects the identity interface. The application retains
+its private key in the server database. Sector/install identity survives re-link,
+provider moves and export/import. Keys are isolated per interface.
+
+Provider origins and metadata endpoints require HTTPS. The application's local
+runtime explicitly permits loopback HTTP; deployed registration requires HTTPS.
+Every provider serves `/.well-known/rer-dependencies` with the same graph fields,
+including its `provides` list and selected dependency provider origins. The CLI
+traverses these documents before setup effects, including selected optional
+edges, and refuses cycles, invalid references and oversized graphs.
+
+A provider serves `GET /.well-known/rer-provider` with `issuer`, `version: 1`,
+`interface` or `provides`, and absolute `initiate`, `redeem`, `deregister` URLs.
+All three endpoints must be HTTPS on exactly that issuer, with no query,
+fragment or URL credentials. OIDC additionally serves standards discovery with
+`rer_interfaces: ["oidc-provider@1.0.0"]` and compatible authorization, token,
+JWKS, ES256 and private_key_jwt support. The application pins those metadata and
+interface versions; callback input cannot select an endpoint or change the pin.
+
+## Owner approval and pull handshake
+
+1. The provider owner approves this exact app origin, interface and callback set.
+   For unattended `rer setup` or `rer deploy`, the provider issues an opaque,
+   one-use approval lasting at most one hour. Save it in an untracked 0600 file
+   named by `RER_LINK_TOKEN_FILE`. For multiple interfaces, use
+   `RER_LINK_TOKEN_FILES` instead: a JSON map such as
+   `{"oidc-provider@1":"auth-approval.json","error-sink@1":"errors-approval.json"}`.
+   Each interface needs a distinct private file; all pending approvals are
+   validated before setup effects and each consumed file is deleted. Its JSON envelope is
+   `{token, issuer, interface, origin, callbacks, issuedAt, expiresAt}`; times are
+   integer epoch milliseconds. `callbacks` is exactly the fixed link callback
+   plus the dependency's registered paths. Git-tracked files are refused.
+2. Before any provider callback, the app must hold its own ten-minute approval.
+   On an empty app, `POST /auth/dependencies/setup` accepts `{issuer,interface,token}`
+   using the app's private setup token, or the local CLI proof on loopback only.
+   Local onboarding opens these approvals before native bootstrap. Hosted deploy
+   uses the deployed app's setup token, never a local HMAC. Base account bootstrap binds
+   pending setup approvals to that owner's version and exact bootstrap session;
+   callback commit requires that session to remain active, unrevoked and unexpired.
+   A signed IdP owner claim may convert that same session to OIDC while sibling
+   setup approvals remain pending. Those approvals also require enabled provider
+   sign-in, the current policy generation and the session's matching linked
+   provider pin, including when claim completes during callback redemption.
+   After claim, use the current owner's fresh email proof at
+   `/auth/dependencies/relink`.
+   The CLI posts `{origin, interface, token}` to the provider's pinned `initiate`
+   endpoint. Interactive provider-owned approval can start the same pull without
+   a CLI token. The provider fetches the app's document and public JWKS, verifies
+   its approval against that origin and exact callback set, and stores the key,
+   sector, interface and registration paths with a short one-use code.
+3. The provider posts only `{issuer, interface, code}` to the fixed app URL
+   `/.well-known/rer-link/callback`. The app accepts only its configured/trusted
+   issuer named by that fresh app-local approval. Every callback, including an
+   unchanged link or a link after unlink, requires a new approval. The exact
+   attempt, owner/session authority and link snapshot are rechecked atomically
+   after redemption; replacing an approval invalidates in-flight callbacks. It never
+   follows a callback URL supplied in the request.
+4. The app durably consumes the code digest and posts to the pinned `redeem`
+   endpoint: `{code, interface, origin, callback, client_assertion_type,
+   client_assertion}`. Assertion type is
+   `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. Its signed ES256 JWT
+   has `iss` and `sub` equal to the app origin, `aud` equal to the redeem URL,
+   `iat`, `exp` at most 60 seconds later, unique `jti`, `code`, `interface`,
+   `sector_id` and the fixed `callback`.
+5. The provider verifies the signature against the key fetched at approval,
+   audience, times, unique assertion/code use and every bound registration
+   property. Code redemption is atomic: concurrent requests have one winner.
+   The response contains `{issuer, interface, origin, callback, sector_id,
+   client_id}`. For an existing same-provider link it must retain the client ID
+   and provide `continuity: "previous-key"` after proving the previous key, or
+   `continuity: "provider-owner"` after fresh provider-owner approval. A new key
+   alone is never continuity proof. The app checks these values and commits the
+   link and OIDC pins in one transaction. The provider returns `{linked:true}`
+   from initiation only after the app accepted the callback.
+6. The CLI checks the app's accepted link then deletes its approval file. The
+   token never enters public answers, runtime variables, logs or exports. An
+   unchanged completed link needs no token on later setup. An explicitly supplied
+   token is always validated. Changed provider answers retain the old link and
+   require a new app-local approval and provider approval.
+
+Provider implementations must enforce code and token expiry, one-use redemption,
+origin/callback binding and key continuity themselves. The application-side
+network tests model those provider obligations without contacting a live service.
+
+## App owner controls and claims
+
+Normal Base account setup claims the native owner first, then links. Only that first setup's
+successful identity link enables `idpSignIn` automatically. The setup attempt
+ must have been opened before that native claim; a native claim without one
+ closes eligibility in its transaction. A link completed before a native claim
+ cannot authorize a later relink to enable sign-in. The CLI closes that
+first-setup eligibility after successful setup, including a blank optional
+provider. Existing and imported installs remain off until their current owner
+enables the app setting. `GET/POST /auth/settings/identity` has JSON and plain HTML
+forms, requires the current owner, records effective changes in `oa_auth_audit`,
+and never accepts platform authority. Any valid settings POST closes setup
+eligibility, including an unchanged value, without auditing a nonexistent change
+or advancing the session generation. Turning off increments a session generation
+and revokes provider sessions. In-flight callbacks cannot cross that generation;
+turning on never restores old sessions. Provider identity or roles alone grant no
+app membership: accounts or invitations remain authoritative.
+
+An app linked before claim advertises `claim: true` and requests the OIDC `claim`
+scope. SETUP owner-claim mode `idp` names the declared identity dependency and
+`/auth/owner-claim`. The provider can return `install_owner` from link redemption
+or an OIDC ID token containing the grant. The former value is itself a signed JWT;
+the latter is the signed ID token. Both use the pinned issuer, client audience,
+subject, fresh verified designated email, unique jti, iat and exp (at most five
+minutes), and `install_owner: {client_id, sector_id, subject, email}`. The app
+requires all four properties to match its own installation and designated owner.
+The existing bootstrap transaction commits owner, grant consumption, binding,
+setting audit and provider session together. Durable issuer/client uniqueness
+allows one owner grant even after a restart; the grant never becomes an ordinary
+role or a general sign-in credential. CLI readiness also verifies the local owner
+exists; linking alone is insufficient.
+
+`POST /auth/dependencies/relink` with `{interface,issuer}` requires the current
+owner's fresh app-local email proof. It creates a ten-minute pending approval
+bound to interface, issuer, exact callback set, owner, owner version and session. A provider move
+keeps existing principal bindings immutable; new-issuer access needs a newly
+proved email matching an existing account/invitation. `POST
+/auth/dependencies/unlink` with `{interface}` uses the same owner proof, deletes
+that interface's link, key and pending approval while retaining the sector, revokes only its provider sessions, and lifts only its
+provider domain rules before any network call. Signed deregistration is best
+effort; offline providers cannot prevent local removal.
+
+## Sessions, logout and portability
+
+Provider sessions record issuer, subject, sid and policy generation and last at
+most 24 hours. OIDC sessions also record their provider pin. Each completed
+re-link advances that provider's monotonic link timestamp, including an unchanged
+metadata re-link in the same millisecond. Binding, invitation acceptance and
+session issuance check the captured pin inside their transaction; session reads
+and privileged writes also require that pin to remain linked. Unrelated
+providers and native sessions retain their own authority. Existing consumers
+apply `accounts/schema/provider-pins.sql` as a new numbered migration (the
+default seed uses `0014_provider_pins.sql`). Existing consumers also apply
+`operator-auth/accounts/schema/dependency-setup.sql` and
+`dependencies/schema/approval-attempt.sql` as new migrations (default-seed
+`0015` and `0016`). Native-account consumers apply only the latter alongside
+their own native migrations; they must not install the OA setup schema. The
+latter invalidates older pending approvals. Auth email proof must be dated, valid and no older than 30 days,
+even for a bound account. Explicit mappings between an upstream subject and email remain
+supported only when they do not contradict an asserted stale proof.
+
+`POST /auth/oidc/auth/logout` accepts `logout_token` and ignores other fields.
+Use a signed JWT with `typ: "logout+jwt"`, pinned issuer/client audience, current
+iat/exp, nonempty durable one-use jti, no nonce property, and sub or sid. When
+both selectors exist they must agree. `events` must contain an empty object at
+`http://schemas.openid.net/event/backchannel-logout` or
+`https://runeditrun.com/events/identity-fence`; unknown events are refused.
+The fence event increments only the selected person's durable identity fence.
+All their fenced sessions and minted credentials then fail admission, while
+other people remain active. Ordinary ID tokens with any `events` property are
+refused. Credential consumers must record/check the fence; the provided
+`mintCredential`/`authenticateCredential` functions also refuse legacy credentials
+with no recorded fence. Editor grants require the actual current install owner;
+OIDC sessions must also match that owner's current issuer/subject account binding.
+
+Exports omit server link keys, approvals, code state, provider sessions and OIDC
+transients, preserve durable people/bindings/grant use/sector, set sign-in off and
+mark links as needing re-link. Import checks these conditions and requires an
+explicit fresh provider approval. Local `rer import` returns `needsRelink: true`
+and `nextCommand: "rer setup"`; that setup continuation consumes the fresh approval
+and retains the imported sector and bindings. `rer doctor` reports dangling providers or a
+needed re-link without reading or emitting private keys or approvals.
+
+## Native accounts
+
+Native `createOperatorAuth` composition reuses this protocol with
+`accounts.dependencies: NativeDependencyAuthority<R>`. Missing capabilities
+refuse enablement. Native authority checks and revocation statements join the
+same D1 link/unlink transaction; verified logout consumption uses the native
+binding/session/fence store atomically. No OA account tables are queried.
+Every native callback requires a new local owner approval, including initial
+and unchanged links. Shared code fences the exact attempt and approving
+person/session/version snapshot at preflight and commit; native contributions
+repeat their own current authority. Ordinary owner linking preserves disabled
+identity regardless of stale setup flags. Unlink deletes the link, key and
+pending approval while preserving the sector.
+
+Native dependency setup before a first owner is currently unsupported:
+`/auth/dependencies/setup` and `auth.authorizeDependencySetup` explicitly refuse
+with `native_capability_unavailable` (501) before pending/key mutation or OA
+setup SQL. Claim the native owner through the seed's supported bootstrap, then
+confirm a local email proof and approve at `/auth/dependencies/relink`. A native
+`claimOwner` capability alone does not make an empty installation's initial IdP
+link/claim journey available. Static incumbent providers remain available beside
+linked Auth.
+See [the exact native contract](../operator-auth/docs/native-accounts.md) for
+method arguments, migration selection, proof fences and adoption steps.

package/modules/dependencies/approval.mjs

@@ -0,0 +1,51 @@
+import { providerPinFence } from '../operator-auth/accounts/provider-pin.mjs';
+import { ownerFence } from './authority.mjs';
+import { CALLBACK, insist } from './protocol.mjs';
+
+export const callbacksFor = (origin, declared) => JSON.stringify([origin+CALLBACK,...declared.paths.map(path=>origin+path)].sort());
+export async function approveSetup({db,auth,request,input,contract,callbacks,clock}) {
+ // Native setup needs durable native bootstrap provenance. Until that optional
+ // capability exists, refuse before touching pending approvals or OA tables.
+ insist(!auth.native,'native_capability_unavailable',501);
+ await auth.authorizeDependencySetup(request,input);
+ const attempt=crypto.randomUUID(),expires=clock()+600000,guard=crypto.randomUUID();
+ await db.batch([
+  db.prepare('INSERT INTO rer_dependency_codes(digest,created_at) SELECT ?,CASE WHEN NOT EXISTS(SELECT 1 FROM oa_operators) AND NOT EXISTS(SELECT 1 FROM oa_bootstrap) THEN ? ELSE -1 END').bind(guard,clock()),
+  db.prepare("INSERT INTO rer_dependency_pending(interface,issuer,approved_by,expires_at,approved_session,approved_version,callbacks,attempt_id) VALUES(?,?,'setup',?,?,0,?,?) ON CONFLICT(interface) DO UPDATE SET issuer=excluded.issuer,approved_by=excluded.approved_by,expires_at=excluded.expires_at,approved_session=excluded.approved_session,approved_version=excluded.approved_version,callbacks=excluded.callbacks,attempt_id=excluded.attempt_id").bind(contract,input.issuer,expires,attempt,callbacks,attempt),
+  db.prepare('INSERT INTO oa_setup_links(interface,attempt_id,expires_at) VALUES(?,?,?) ON CONFLICT(interface) DO UPDATE SET attempt_id=excluded.attempt_id,expires_at=excluded.expires_at,owner_id=NULL,owner_version=NULL,session_id=NULL,completed=0').bind(contract,attempt,expires),
+ ]);
+}
+export async function approveOwner({store,actor,input,contract,callbacks,clock,native}) {
+ const fence=native?await native.ownerFence(actor,clock()):ownerFence(actor,clock());
+ const approval=await store.run(`INSERT INTO rer_dependency_pending(interface,issuer,approved_by,expires_at,approved_session,approved_version,callbacks,attempt_id) SELECT ?,?,?,?,?,?,?,? WHERE ${fence.sql} ON CONFLICT(interface) DO UPDATE SET issuer=excluded.issuer,approved_by=excluded.approved_by,expires_at=excluded.expires_at,approved_session=excluded.approved_session,approved_version=excluded.approved_version,callbacks=excluded.callbacks,attempt_id=excluded.attempt_id`,contract,input.issuer,actor.operator.id,clock()+600000,actor.id,actor.operator.version,callbacks,crypto.randomUUID(),...fence.args);
+ insist(approval.meta.changes===1,'authority_changed',409);
+}
+// Snapshot the attempt before network I/O. Every authority and exact attempt
+// predicate is executed again in the transaction that installs the link.
+export async function approvalFence(pending,contract,issuer,callbacks,now,pendingPin,native) {
+ const base={sql:'EXISTS(SELECT 1 FROM rer_dependency_pending p WHERE p.interface=? AND p.issuer=? AND p.callbacks=? AND p.expires_at>? AND p.attempt_id=?',args:[contract,issuer,callbacks,now,pending.attempt_id]};
+ if(native) {
+  const authority=await native.approvalFence({pending,contract,issuer,callbacks,now});
+  // The shared protocol owns attempt/snapshot equality. An adopter contributes
+  // native authority only; replacing any approval invalidates this callback.
+  return {sql:`${base.sql} AND p.approved_by=? AND p.approved_session=? AND p.approved_version=?) AND (${authority.sql})`,args:[...base.args,pending.approved_by,pending.approved_session,pending.approved_version,...authority.args]};
+ }
+ // A signed IdP claim converts the bootstrap session in the same transaction.
+ // Resolve its live provenance here: a callback may have started before claim.
+ if(pending.approved_by==='setup')return {
+  sql:base.sql+` AND EXISTS(SELECT 1 FROM oa_setup_links l WHERE l.interface=p.interface AND l.attempt_id=p.attempt_id AND l.completed=0 AND l.expires_at>?
+   AND ((l.owner_id IS NULL AND l.owner_version IS NULL AND l.session_id IS NULL AND NOT EXISTS(SELECT 1 FROM oa_operators) AND NOT EXISTS(SELECT 1 FROM oa_bootstrap))
+    OR EXISTS(SELECT 1 FROM oa_bootstrap b JOIN oa_operators o ON o.id=b.claim_id JOIN oa_sessions s ON s.operator_id=o.id
+     WHERE o.id=l.owner_id AND o.role='owner' AND o.status='active' AND o.version=l.owner_version
+     AND s.id=l.session_id AND s.operator_version=l.owner_version AND s.revoked_at IS NULL AND s.expires_at>?
+     AND (s.kind='native' OR (s.kind='oidc' AND EXISTS(
+      SELECT 1 FROM oa_provider_sessions ps
+      JOIN oa_auth_settings a ON a.singleton=1 AND a.idp_sign_in=1 AND a.generation=ps.generation
+      JOIN oa_provider_session_pins pin ON pin.session_id=ps.session_id AND pin.provider_id='auth' AND pin.issuer=ps.issuer
+      JOIN oa_identity_providers provider ON provider.provider_id=pin.provider_id AND provider.status='linked'
+       AND provider.issuer=pin.issuer AND provider.client_id=pin.client_id AND provider.linked_at=pin.linked_at
+      WHERE ps.session_id=s.id)))))))`,args:[...base.args,now,now],
+ };
+ const pin=providerPinFence(pendingPin);
+ return {sql:`${pin.sql} AND ${base.sql} AND p.approved_by=? AND p.approved_session=? AND p.approved_version=? AND EXISTS(SELECT 1 FROM oa_operators o JOIN oa_sessions s ON s.operator_id=o.id WHERE o.id=p.approved_by AND o.version=p.approved_version AND s.id=p.approved_session AND s.operator_version=o.version AND s.revoked_at IS NULL AND s.expires_at>? AND o.status='active' AND o.id=(SELECT a.id FROM oa_operators a LEFT JOIN oa_bootstrap b ON b.claim_id=a.id WHERE a.role='owner' AND a.status='active' ORDER BY b.claim_id IS NULL,a.created_at,a.id LIMIT 1)))`,args:[...pin.args,...base.args,pending.approved_by,pending.approved_session,pending.approved_version,now]};
+}