@volter/world-core 3.0.11 → 3.0.12

package/attach.cjs

@@ -25,15 +25,40 @@ if (ref) {
     // a blocking fetch at module load: spawn a child that prints the manifest
     const probe = spawnSync(
       process.execPath,
-      ['-e', 'fetch(process.argv[1],process.argv[2]?{headers:{authorization:"Bearer "+process.argv[2]}}:undefined).then(r=>{if(!r.ok)throw new Error(r.status);return r.text()}).then(t=>process.stdout.write(t)).catch(e=>{console.error(String(e));process.exit(1)})', url, ...(token ? [token] : [])],
+      // the token by the child's environment, never its arguments: another user on this machine can list arguments
+      ['-e', 'const t=process.env.VOLTER_ATTACH_PROBE_TOKEN;fetch(process.argv[1],t?{headers:{authorization:"Bearer "+t}}:undefined).then(r=>{if(!r.ok)throw new Error(r.status);return r.text()}).then(t=>process.stdout.write(t)).catch(e=>{console.error(String(e));process.exit(1)})', url],
       // the child must NOT inherit NODE_OPTIONS/VOLTER_WORLD — it would
       // re-run this very file at its own startup (a spawn recursion bomb)
-      { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+      { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '', ...(token ? { VOLTER_ATTACH_PROBE_TOKEN: token } : {}) } },
     );
     if (probe.status !== 0) {
       throw new Error(`[twin-attach] could not fetch the world manifest from ${url}: ${(probe.stderr || '').trim()}`);
     }
     const manifest = JSON.parse(probe.stdout);
+    // a served World's twins as loopback listeners that add its key (./http-bridge.cjs), so a client with its own HTTP
+    // stack (wrangler's undici, which neither patch reaches) reaches them as it would a local World's: the twin URLs and
+    // every endpoint variable naming a twin's place point at the listener. Ports are chosen by a blocking child, the
+    // listeners bound on the next turn, before any client can connect, and never hold the process open.
+    // the key the World echoed to this caller, as the injector carries it; else the token given
+    const key = manifest.env?.VOLTER_TWINS_KEY ?? token;
+    const served = Object.entries(manifest.vendors ?? {}).filter(([, origin]) => key && /^https?:\/\//.test(String(origin)));
+    if (served.length) {
+      const picked = spawnSync(
+        process.execPath,
+        ['-e', 'const n=require("node:net");const k=+process.argv[1];const s=[];const d=()=>{if(s.length<k){const v=n.createServer().listen(0,"127.0.0.1",()=>{s.push(v);d()})}else{process.stdout.write(s.map(v=>v.address().port).join(","));s.forEach(v=>v.close())}};d()', String(served.length)],
+        { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+      );
+      if (picked.status !== 0) throw new Error(`[twin-attach] could not choose loopback ports for the world's twins: ${(picked.stderr || '').trim()}`);
+      const ports = picked.stdout.split(',').map(Number);
+      const { bridgeHttp, bridgeSecret, pointAt } = require('./http-bridge.cjs');
+      served.forEach(([vendor], i) => {
+        const secret = bridgeSecret();
+        const at = pointAt(manifest, vendor, `http://127.0.0.1:${ports[i]}/${secret}`);
+        bridgeHttp(at, key, ports[i], secret, manifest.ca || undefined).then((server) => server.unref(), (error) => {
+          process.stderr.write(`[twin-attach] ${at}: could not listen on 127.0.0.1:${ports[i]}: ${error.message}\n`);
+        });
+      });
+    }
     for (const [vendor, origin] of Object.entries(manifest.vendors ?? {})) {
       const key = `${vendor.toUpperCase()}_TWIN_URL`;
       if (process.env[key] === undefined) process.env[key] = origin;
@@ -55,7 +80,7 @@ if (ref) {
       if (picked.status !== 0) throw new Error(`[twin-attach] could not choose loopback ports for the world's streams: ${(picked.stderr || '').trim()}`);
       const ports = picked.stdout.split(',').map(Number);
       const { bridgeStream, streamEnv } = require('./stream-bridge.cjs');
-      const streamToken = token ?? manifest.env?.VOLTER_TWINS_KEY ?? '';
+      const streamToken = manifest.env?.VOLTER_TWINS_KEY ?? token ?? '';
       streams.forEach((stream, i) => {
         for (const [key, value] of Object.entries(streamEnv(stream.env, ports[i]))) {
           if (process.env[key] === undefined) process.env[key] = value;

package/dist/attach.cjs

@@ -25,15 +25,40 @@ if (ref) {
     // a blocking fetch at module load: spawn a child that prints the manifest
     const probe = spawnSync(
       process.execPath,
-      ['-e', 'fetch(process.argv[1],process.argv[2]?{headers:{authorization:"Bearer "+process.argv[2]}}:undefined).then(r=>{if(!r.ok)throw new Error(r.status);return r.text()}).then(t=>process.stdout.write(t)).catch(e=>{console.error(String(e));process.exit(1)})', url, ...(token ? [token] : [])],
+      // the token by the child's environment, never its arguments: another user on this machine can list arguments
+      ['-e', 'const t=process.env.VOLTER_ATTACH_PROBE_TOKEN;fetch(process.argv[1],t?{headers:{authorization:"Bearer "+t}}:undefined).then(r=>{if(!r.ok)throw new Error(r.status);return r.text()}).then(t=>process.stdout.write(t)).catch(e=>{console.error(String(e));process.exit(1)})', url],
       // the child must NOT inherit NODE_OPTIONS/VOLTER_WORLD — it would
       // re-run this very file at its own startup (a spawn recursion bomb)
-      { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+      { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '', ...(token ? { VOLTER_ATTACH_PROBE_TOKEN: token } : {}) } },
     );
     if (probe.status !== 0) {
       throw new Error(`[twin-attach] could not fetch the world manifest from ${url}: ${(probe.stderr || '').trim()}`);
     }
     const manifest = JSON.parse(probe.stdout);
+    // a served World's twins as loopback listeners that add its key (./http-bridge.cjs), so a client with its own HTTP
+    // stack (wrangler's undici, which neither patch reaches) reaches them as it would a local World's: the twin URLs and
+    // every endpoint variable naming a twin's place point at the listener. Ports are chosen by a blocking child, the
+    // listeners bound on the next turn, before any client can connect, and never hold the process open.
+    // the key the World echoed to this caller, as the injector carries it; else the token given
+    const key = manifest.env?.VOLTER_TWINS_KEY ?? token;
+    const served = Object.entries(manifest.vendors ?? {}).filter(([, origin]) => key && /^https?:\/\//.test(String(origin)));
+    if (served.length) {
+      const picked = spawnSync(
+        process.execPath,
+        ['-e', 'const n=require("node:net");const k=+process.argv[1];const s=[];const d=()=>{if(s.length<k){const v=n.createServer().listen(0,"127.0.0.1",()=>{s.push(v);d()})}else{process.stdout.write(s.map(v=>v.address().port).join(","));s.forEach(v=>v.close())}};d()', String(served.length)],
+        { encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: '', VOLTER_WORLD: '' } },
+      );
+      if (picked.status !== 0) throw new Error(`[twin-attach] could not choose loopback ports for the world's twins: ${(picked.stderr || '').trim()}`);
+      const ports = picked.stdout.split(',').map(Number);
+      const { bridgeHttp, bridgeSecret, pointAt } = require('./http-bridge.cjs');
+      served.forEach(([vendor], i) => {
+        const secret = bridgeSecret();
+        const at = pointAt(manifest, vendor, `http://127.0.0.1:${ports[i]}/${secret}`);
+        bridgeHttp(at, key, ports[i], secret, manifest.ca || undefined).then((server) => server.unref(), (error) => {
+          process.stderr.write(`[twin-attach] ${at}: could not listen on 127.0.0.1:${ports[i]}: ${error.message}\n`);
+        });
+      });
+    }
     for (const [vendor, origin] of Object.entries(manifest.vendors ?? {})) {
       const key = `${vendor.toUpperCase()}_TWIN_URL`;
       if (process.env[key] === undefined) process.env[key] = origin;
@@ -55,7 +80,7 @@ if (ref) {
       if (picked.status !== 0) throw new Error(`[twin-attach] could not choose loopback ports for the world's streams: ${(picked.stderr || '').trim()}`);
       const ports = picked.stdout.split(',').map(Number);
       const { bridgeStream, streamEnv } = require('./stream-bridge.cjs');
-      const streamToken = token ?? manifest.env?.VOLTER_TWINS_KEY ?? '';
+      const streamToken = manifest.env?.VOLTER_TWINS_KEY ?? token ?? '';
       streams.forEach((stream, i) => {
         for (const [key, value] of Object.entries(streamEnv(stream.env, ports[i]))) {
           if (process.env[key] === undefined) process.env[key] = value;

package/dist/http-bridge.cjs

@@ -0,0 +1,92 @@
+// THE HTTP BRIDGE: a served World's twins as loopback listeners, for a client the injector cannot reach because it brings
+// its own HTTP stack (wrangler bundles undici; a Go binary, curl). Each forwards to its twin's place in the World with
+// the World's key added, so the client needs only its vendor credential, as at a local World's twin. Used by the attach
+// entry, beside the stream bridge (./stream-bridge.cjs).
+//
+// The key is the World's, so the listener lends it only to whoever holds the listener's own address: a random path
+// prefix the attaching process's environment carries, as it carries the key. A request without it (another user on
+// this machine, a page in a browser) is refused, as is any that names a path outside the twin's place.
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+const { randomBytes } = require('node:crypto');
+
+// the transports as Node has them, taken before the injector patches them: the bridge adds the key itself
+const request = { 'http:': http.request, 'https:': https.request };
+
+/** A listener's secret prefix: the path every request to it begins with. */
+function bridgeSecret() { return randomBytes(18).toString('hex'); }
+
+/** Serve the twin at `target` (its place in the World, `<origin>/<org>/<world>/<vendor>`) on 127.0.0.1:`port` (0: any),
+ *  under `/<secret>`. A redirect to the twin's place is answered at the bridge's own address. */
+function bridgeHttp(target, key, port = 0, secret = bridgeSecret(), ca = undefined) {
+  const base = new URL(target.replace(/\/$/, ''));
+  const mine = `/${secret}`;
+  const refuse = (res, status, why) => { res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' }); res.end(`[twin-http] ${why}\n`); };
+  const server = http.createServer((req, res) => {
+    // a browser's request carries its page's origin: never the attaching process's own
+    if (req.headers.origin) return refuse(res, 403, 'a page in a browser does not borrow the World\'s key');
+    const raw = req.url ?? '';
+    if (!(raw === mine || raw.startsWith(`${mine}/`) || raw.startsWith(`${mine}?`))) return refuse(res, 404, 'not this listener\'s address');
+    const rest = raw.slice(mine.length);
+    const to = new URL(`${base.pathname}${rest.startsWith('/') || rest === '' ? rest : `/${rest}`}`, base.origin);
+    // the URL resolved (dot segments, encoded or not): still under the twin's place, or refused
+    if (to.pathname !== base.pathname && !to.pathname.startsWith(`${base.pathname}/`)) return refuse(res, 403, 'outside the twin\'s place');
+    // the host and path the client sent, which a signature over the request (SigV4's canonical request) covers
+    const headers = { ...req.headers, host: base.host, 'x-twins-key': key, 'x-volter-twin-original-host': req.headers.host ?? '', 'x-volter-original-path': raw.split('?')[0] };
+    for (const h of ['connection', 'keep-alive', 'proxy-connection', 'upgrade']) delete headers[h];
+    const here = `http://127.0.0.1:${server.address().port}${mine}`;
+    // a World served behind its session CA is trusted by it here, as the injector's forwards are
+    const up = request[base.protocol](to, { method: req.method, headers, ...(ca && base.protocol === 'https:' ? { ca } : {}) }, (answer) => {
+      const out = { ...answer.headers };
+      delete out.connection; delete out['keep-alive'];
+      if (typeof out.location === 'string') {
+        // a redirect within the twin's place, absolute or by path, is answered at the listener
+        const loc = out.location;
+        if (loc === base.href || loc.startsWith(`${base.href}/`) || loc.startsWith(`${base.href}?`)) out.location = `${here}${loc.slice(base.href.length)}`;
+        else if (loc === base.pathname || loc.startsWith(`${base.pathname}/`)) out.location = `${here}${loc.slice(base.pathname.length)}`;
+      }
+      res.writeHead(answer.statusCode ?? 502, answer.statusMessage, out);
+      answer.on('error', () => res.destroy());
+      answer.pipe(res);
+    });
+    up.on('error', (error) => { if (res.headersSent) res.destroy(); else refuse(res, 502, `${base.href}: ${error.message}`); });
+    req.on('error', () => up.destroy());
+    res.on('close', () => { if (!res.writableFinished) up.destroy(); });
+    req.pipe(up);
+  });
+  // a socket a client upgrades (a log tail's WebSocket) is not carried yet: said, not dropped
+  server.on('upgrade', (_req, socket) => { socket.end('HTTP/1.1 501 Not Implemented\r\ncontent-type: text/plain\r\n\r\n[twin-http] a WebSocket is not carried through the listener\n'); });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve(server));
+  });
+}
+
+/** Point a World manifest's twin at a local listener: its twin URL, and every endpoint variable naming its place (itself,
+ *  or a path or query under it; never another twin whose name it begins). */
+function pointAt(manifest, vendor, local) {
+  const at = String(manifest.vendors[vendor]).replace(/\/$/, '');
+  const under = (value) => value === at || value.startsWith(`${at}/`) || value.startsWith(`${at}?`);
+  manifest.vendors[vendor] = local;
+  for (const [name, value] of Object.entries(manifest.env ?? {})) if (typeof value === 'string' && under(value)) manifest.env[name] = `${local}${value.slice(at.length)}`;
+  return at;
+}
+
+/** Every served twin of a World manifest bridged (`volter-world attach`, a command in any language): its listener up, and
+ *  the manifest pointed at it. Resolves to the listeners, unref'd. */
+async function bridgeTwins(manifest, key, ca = undefined) {
+  const servers = [];
+  for (const [vendor, origin] of Object.entries(manifest.vendors ?? {})) {
+    if (!key || !/^https?:\/\//.test(String(origin))) continue;
+    const secret = bridgeSecret();
+    const server = await bridgeHttp(String(origin), key, 0, secret, ca);
+    server.unref();
+    pointAt(manifest, vendor, `http://127.0.0.1:${server.address().port}/${secret}`);
+    servers.push(server);
+  }
+  return servers;
+}
+
+module.exports = { bridgeHttp, bridgeSecret, bridgeTwins, pointAt };

package/dist/src/derived-real.js

@@ -325,6 +325,9 @@ function refreshOf(units, service) {
     return async (execute, opts) => {
         const observed = [];
         const complete = [];
+        // what the root's credential may not read (a token scoped to some of the account): left as the World holds it, said
+        const unread = [];
+        let answered = 0;
         for (const unit of units) {
             const { manifest: m, surface } = unit;
             // parents before children, however deep
@@ -344,17 +347,31 @@ function refreshOf(units, service) {
                     const limit = m.list?.limit && (op.query ?? []).some((q) => q.name === m.list.limit.param) ? { [m.list.limit.param]: String(m.list.limit.max) } : {};
                     let page = { ...limit };
                     for (let taken = 0;;) {
-                        const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => encodeURIComponent(n === decl.parent?.param ? String(parent) : ''));
+                        let unfilled = false;
+                        const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => { const v = n === decl.parent?.param && parent !== undefined ? String(parent) : ''; if (!v)
+                            unfilled = true; return encodeURIComponent(v); });
                         // a parent the operation names in its query, not its path (Slack's conversations.history `channel`)
                         const byQuery = decl.parent?.param && parent !== undefined && !op.path.includes(`{${decl.parent.param}}`) ? { [decl.parent.param]: String(parent) } : {};
                         const q = new URLSearchParams({ ...page, ...byQuery });
                         const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path, ...(unit.lane ? { lane: unit.lane } : {}) });
-                        if (answer.status === 401 || answer.status === 403)
-                            throw new Error(`${answer.status}: the vendor refused the root's credential; nothing folded`);
+                        if (answer.status === 401)
+                            throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
+                        if (answer.status === 403) {
+                            unread.push({ type, path, status: 403 });
+                            whole = false;
+                            break;
+                        }
                         if (answer.status === 429)
                             throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
+                        // one subject read by its parent and not there (an account with no workers.dev subdomain): nothing to observe. A
+                        // path missing a parameter (an empty segment) is the kernel's mistake, never the vendor's absence
+                        if ('get' in scope && answer.status === 404 && !unfilled) {
+                            answered += 1;
+                            break;
+                        }
                         if (answer.status >= 400)
                             throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+                        answered += 1;
                         const parsed = parse(answer);
                         const items = 'get' in scope ? [object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {}]
                             : 'items' in scope && scope.items ? (at(parsed, scope.items) ?? []).map((x) => object(x)).filter((x) => x !== undefined) : itemsOf(op, parsed);
@@ -411,8 +428,12 @@ function refreshOf(units, service) {
                     complete.push({ type, field: decl.parent.field, within: parents.map(String) });
             }
         }
+        // every read refused is a credential the vendor refuses, never an account that holds nothing
+        if (unread.length && !answered)
+            throw new Error(`403: the vendor refused the root's credential for every read (${unread.map((u) => u.path).join(', ')}); nothing folded`);
         adopt(service, opts.root, units, observed);
-        return observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
+        const report = observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
+        return unread.length ? { ...report, unread } : report;
     };
 }
 /** A vendor's subject's stored id: its key template filled from its fields (its parent's among them), else its id

package/dist/src/pack-fetch.js

@@ -69,12 +69,18 @@ const DECODE = { gzip: gunzipSync, zstd: zstdDecompressSync, deflate: inflateSyn
 /** A request with its body decoded as its Content-Encoding says, when the manifest's `encodings` reads that coding;
  *  undefined when the bytes are not what the header names. */
 async function decoded(m, request) {
-    const coding = (request.headers.get('content-encoding') ?? '').trim().toLowerCase();
-    if (!m.encodings?.request?.includes(coding) || request.method === 'GET' || request.method === 'HEAD')
+    if (request.method === 'GET' || request.method === 'HEAD' || request.body === null)
         return request;
+    // the body read once, here, and every part of the pack given a request made again from its bytes: a served request's
+    // body read through a clone and then read again (an `around` that checks a body before its handler does) tees a stream
+    // whose second branch a Bun server never finishes, and the request hung
+    const raw = new Uint8Array(await request.arrayBuffer());
+    const coding = (request.headers.get('content-encoding') ?? '').trim().toLowerCase();
+    if (!m.encodings?.request?.includes(coding))
+        return new Request(request.url, { method: request.method, headers: request.headers, body: raw });
     let body;
     try {
-        body = DECODE[coding](new Uint8Array(await request.arrayBuffer()));
+        body = DECODE[coding](raw);
     }
     catch {
         return undefined;
@@ -213,11 +219,16 @@ export function createPackFetch(parts, options = {}) {
     const workspaces = () => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
     /** Whether a built screen a person views (a workspace or a flow, never content an API client reads) draws a url: its host
      *  one the screen names, its path the screen's or under it (a root screen draws its root alone). */
+    // by what the pack declares built (a screen drawn by another's handler, as X's profile is by its web pages, is built)
+    const viewed = (m.screens ?? []).filter((s) => s.status === 'done' && s.kind !== 'content').map((s) => {
+        const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
+        return { root: s.path.replace(/\/+$/, '') === '', host: (h) => hosts.some((match) => match(h)), path: pathMatcher(s.path, true) };
+    });
     const drawsUrl = (at) => {
         try {
             const u = new URL(at);
             const path = u.pathname.replace(/\/+$/, '') || '/';
-            return screens.some((s) => s.decl.kind !== 'content' && Boolean(s.host(u.hostname.toLowerCase())) && (s.decl.path.replace(/\/+$/, '') === '' ? path === '/' : Boolean(s.path(path))));
+            return viewed.some((s) => s.host(u.hostname.toLowerCase()) && (s.root ? path === '/' : Boolean(s.path(path))));
         }
         catch {
             return false;
@@ -246,7 +257,9 @@ export function createPackFetch(parts, options = {}) {
             return request;
         // the path the client sent, which a signature over the request (SigV4's canonical URI) covers
         const headers = new Headers(request.headers);
-        headers.set(ORIGINAL_PATH_HEADER, url.pathname);
+        // the path as first sent: a front before this (an attach bridge) may have named the one its client signed
+        if (!headers.has(ORIGINAL_PATH_HEADER))
+            headers.set(ORIGINAL_PATH_HEADER, url.pathname);
         if (Object.keys(groups).length)
             headers.set(PREFIX_PARAMS_HEADER, JSON.stringify(groups));
         url.pathname = path;

package/dist/src/runtime.d.ts

@@ -3,6 +3,7 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.js';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
+export { ORIGINAL_PATH_HEADER } from './sigv4.js';
 export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';

package/dist/src/runtime.js

@@ -11,6 +11,7 @@ export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullP
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
+export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";

package/http-bridge.cjs

@@ -0,0 +1,92 @@
+// THE HTTP BRIDGE: a served World's twins as loopback listeners, for a client the injector cannot reach because it brings
+// its own HTTP stack (wrangler bundles undici; a Go binary, curl). Each forwards to its twin's place in the World with
+// the World's key added, so the client needs only its vendor credential, as at a local World's twin. Used by the attach
+// entry, beside the stream bridge (./stream-bridge.cjs).
+//
+// The key is the World's, so the listener lends it only to whoever holds the listener's own address: a random path
+// prefix the attaching process's environment carries, as it carries the key. A request without it (another user on
+// this machine, a page in a browser) is refused, as is any that names a path outside the twin's place.
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+const { randomBytes } = require('node:crypto');
+
+// the transports as Node has them, taken before the injector patches them: the bridge adds the key itself
+const request = { 'http:': http.request, 'https:': https.request };
+
+/** A listener's secret prefix: the path every request to it begins with. */
+function bridgeSecret() { return randomBytes(18).toString('hex'); }
+
+/** Serve the twin at `target` (its place in the World, `<origin>/<org>/<world>/<vendor>`) on 127.0.0.1:`port` (0: any),
+ *  under `/<secret>`. A redirect to the twin's place is answered at the bridge's own address. */
+function bridgeHttp(target, key, port = 0, secret = bridgeSecret(), ca = undefined) {
+  const base = new URL(target.replace(/\/$/, ''));
+  const mine = `/${secret}`;
+  const refuse = (res, status, why) => { res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' }); res.end(`[twin-http] ${why}\n`); };
+  const server = http.createServer((req, res) => {
+    // a browser's request carries its page's origin: never the attaching process's own
+    if (req.headers.origin) return refuse(res, 403, 'a page in a browser does not borrow the World\'s key');
+    const raw = req.url ?? '';
+    if (!(raw === mine || raw.startsWith(`${mine}/`) || raw.startsWith(`${mine}?`))) return refuse(res, 404, 'not this listener\'s address');
+    const rest = raw.slice(mine.length);
+    const to = new URL(`${base.pathname}${rest.startsWith('/') || rest === '' ? rest : `/${rest}`}`, base.origin);
+    // the URL resolved (dot segments, encoded or not): still under the twin's place, or refused
+    if (to.pathname !== base.pathname && !to.pathname.startsWith(`${base.pathname}/`)) return refuse(res, 403, 'outside the twin\'s place');
+    // the host and path the client sent, which a signature over the request (SigV4's canonical request) covers
+    const headers = { ...req.headers, host: base.host, 'x-twins-key': key, 'x-volter-twin-original-host': req.headers.host ?? '', 'x-volter-original-path': raw.split('?')[0] };
+    for (const h of ['connection', 'keep-alive', 'proxy-connection', 'upgrade']) delete headers[h];
+    const here = `http://127.0.0.1:${server.address().port}${mine}`;
+    // a World served behind its session CA is trusted by it here, as the injector's forwards are
+    const up = request[base.protocol](to, { method: req.method, headers, ...(ca && base.protocol === 'https:' ? { ca } : {}) }, (answer) => {
+      const out = { ...answer.headers };
+      delete out.connection; delete out['keep-alive'];
+      if (typeof out.location === 'string') {
+        // a redirect within the twin's place, absolute or by path, is answered at the listener
+        const loc = out.location;
+        if (loc === base.href || loc.startsWith(`${base.href}/`) || loc.startsWith(`${base.href}?`)) out.location = `${here}${loc.slice(base.href.length)}`;
+        else if (loc === base.pathname || loc.startsWith(`${base.pathname}/`)) out.location = `${here}${loc.slice(base.pathname.length)}`;
+      }
+      res.writeHead(answer.statusCode ?? 502, answer.statusMessage, out);
+      answer.on('error', () => res.destroy());
+      answer.pipe(res);
+    });
+    up.on('error', (error) => { if (res.headersSent) res.destroy(); else refuse(res, 502, `${base.href}: ${error.message}`); });
+    req.on('error', () => up.destroy());
+    res.on('close', () => { if (!res.writableFinished) up.destroy(); });
+    req.pipe(up);
+  });
+  // a socket a client upgrades (a log tail's WebSocket) is not carried yet: said, not dropped
+  server.on('upgrade', (_req, socket) => { socket.end('HTTP/1.1 501 Not Implemented\r\ncontent-type: text/plain\r\n\r\n[twin-http] a WebSocket is not carried through the listener\n'); });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve(server));
+  });
+}
+
+/** Point a World manifest's twin at a local listener: its twin URL, and every endpoint variable naming its place (itself,
+ *  or a path or query under it; never another twin whose name it begins). */
+function pointAt(manifest, vendor, local) {
+  const at = String(manifest.vendors[vendor]).replace(/\/$/, '');
+  const under = (value) => value === at || value.startsWith(`${at}/`) || value.startsWith(`${at}?`);
+  manifest.vendors[vendor] = local;
+  for (const [name, value] of Object.entries(manifest.env ?? {})) if (typeof value === 'string' && under(value)) manifest.env[name] = `${local}${value.slice(at.length)}`;
+  return at;
+}
+
+/** Every served twin of a World manifest bridged (`volter-world attach`, a command in any language): its listener up, and
+ *  the manifest pointed at it. Resolves to the listeners, unref'd. */
+async function bridgeTwins(manifest, key, ca = undefined) {
+  const servers = [];
+  for (const [vendor, origin] of Object.entries(manifest.vendors ?? {})) {
+    if (!key || !/^https?:\/\//.test(String(origin))) continue;
+    const secret = bridgeSecret();
+    const server = await bridgeHttp(String(origin), key, 0, secret, ca);
+    server.unref();
+    pointAt(manifest, vendor, `http://127.0.0.1:${server.address().port}/${secret}`);
+    servers.push(server);
+  }
+  return servers;
+}
+
+module.exports = { bridgeHttp, bridgeSecret, bridgeTwins, pointAt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.11",
+  "version": "3.0.12",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
@@ -24,6 +24,7 @@
     "inject.cjs",
     "attach.cjs",
     "stream-bridge.cjs",
+    "http-bridge.cjs",
     "network-policy.cjs",
     "network-policy.d.cts",
     "app-route.cjs",
@@ -75,6 +76,7 @@
     "./inject": "./inject.cjs",
     "./attach": "./attach.cjs",
     "./stream-bridge": "./stream-bridge.cjs",
+    "./http-bridge": "./http-bridge.cjs",
     "./network-policy": {
       "types": "./network-policy.d.cts",
       "default": "./network-policy.cjs"

package/src/derived-real.ts

@@ -280,6 +280,9 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
   return async (execute, opts) => {
     const observed: ObservedResource[] = [];
     const complete: Completed[] = [];
+    // what the root's credential may not read (a token scoped to some of the account): left as the World holds it, said
+    const unread: Array<{ type: string; path: string; status: number }> = [];
+    let answered = 0;
     for (const unit of units) {
       const { manifest: m, surface } = unit;
       // parents before children, however deep
@@ -298,14 +301,20 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
           const limit = m.list?.limit && (op.query ?? []).some((q) => q.name === m.list!.limit.param) ? { [m.list.limit.param]: String(m.list.limit.max) } : {};
           let page: Record<string, string> = { ...limit };
           for (let taken = 0; ;) {
-            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => encodeURIComponent(n === decl.parent?.param ? String(parent) : ''));
+            let unfilled = false;
+            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => { const v = n === decl.parent?.param && parent !== undefined ? String(parent) : ''; if (!v) unfilled = true; return encodeURIComponent(v); });
             // a parent the operation names in its query, not its path (Slack's conversations.history `channel`)
             const byQuery = decl.parent?.param && parent !== undefined && !op.path.includes(`{${decl.parent.param}}`) ? { [decl.parent.param]: String(parent) } : {};
             const q = new URLSearchParams({ ...page, ...byQuery });
             const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path, ...(unit.lane ? { lane: unit.lane } : {}) });
-            if (answer.status === 401 || answer.status === 403) throw new Error(`${answer.status}: the vendor refused the root's credential; nothing folded`);
+            if (answer.status === 401) throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
+            if (answer.status === 403) { unread.push({ type, path, status: 403 }); whole = false; break; }
             if (answer.status === 429) throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
+            // one subject read by its parent and not there (an account with no workers.dev subdomain): nothing to observe. A
+            // path missing a parameter (an empty segment) is the kernel's mistake, never the vendor's absence
+            if ('get' in scope && answer.status === 404 && !unfilled) { answered += 1; break; }
             if (answer.status >= 400) throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+            answered += 1;
             const parsed = parse(answer);
             const items = 'get' in scope ? [object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {}]
               : 'items' in scope && scope.items ? ((at(parsed, scope.items) as unknown[] | undefined) ?? []).map((x) => object(x)).filter((x): x is Row => x !== undefined) : itemsOf(op, parsed);
@@ -344,8 +353,11 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
         else if (whole && parents.length) complete.push({ type, field: decl.parent!.field, within: parents.map(String) });
       }
     }
+    // every read refused is a credential the vendor refuses, never an account that holds nothing
+    if (unread.length && !answered) throw new Error(`403: the vendor refused the root's credential for every read (${unread.map((u) => u.path).join(', ')}); nothing folded`);
     adopt(service, opts.root, units, observed);
-    return observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
+    const report = observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
+    return unread.length ? { ...(report as object), unread } : report;
   };
 }
 

package/src/pack-fetch.ts

@@ -124,10 +124,15 @@ const DECODE = { gzip: gunzipSync, zstd: zstdDecompressSync, deflate: inflateSyn
 /** A request with its body decoded as its Content-Encoding says, when the manifest's `encodings` reads that coding;
  *  undefined when the bytes are not what the header names. */
 async function decoded(m: DerivedManifest, request: Request): Promise<Request | undefined> {
+  if (request.method === 'GET' || request.method === 'HEAD' || request.body === null) return request;
+  // the body read once, here, and every part of the pack given a request made again from its bytes: a served request's
+  // body read through a clone and then read again (an `around` that checks a body before its handler does) tees a stream
+  // whose second branch a Bun server never finishes, and the request hung
+  const raw = new Uint8Array(await request.arrayBuffer());
   const coding = (request.headers.get('content-encoding') ?? '').trim().toLowerCase() as keyof typeof DECODE;
-  if (!m.encodings?.request?.includes(coding) || request.method === 'GET' || request.method === 'HEAD') return request;
+  if (!m.encodings?.request?.includes(coding)) return new Request(request.url, { method: request.method, headers: request.headers, body: raw });
   let body: Uint8Array;
-  try { body = DECODE[coding](new Uint8Array(await request.arrayBuffer())); } catch { return undefined; }
+  try { body = DECODE[coding](raw); } catch { return undefined; }
   const headers = new Headers(request.headers);
   headers.delete('content-encoding');
   headers.delete('content-length');
@@ -249,10 +254,15 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   const workspaces = (): Workspace[] => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
   /** Whether a built screen a person views (a workspace or a flow, never content an API client reads) draws a url: its host
    *  one the screen names, its path the screen's or under it (a root screen draws its root alone). */
+  // by what the pack declares built (a screen drawn by another's handler, as X's profile is by its web pages, is built)
+  const viewed = (m.screens ?? []).filter((s) => s.status === 'done' && s.kind !== 'content').map((s) => {
+    const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
+    return { root: s.path.replace(/\/+$/, '') === '', host: (h: string) => hosts.some((match) => match(h)), path: pathMatcher(s.path, true) };
+  });
   const drawsUrl = (at: string): boolean => {
     try {
       const u = new URL(at); const path = u.pathname.replace(/\/+$/, '') || '/';
-      return screens.some((s) => s.decl.kind !== 'content' && Boolean(s.host(u.hostname.toLowerCase())) && (s.decl.path.replace(/\/+$/, '') === '' ? path === '/' : Boolean(s.path(path))));
+      return viewed.some((s) => s.host(u.hostname.toLowerCase()) && (s.root ? path === '/' : Boolean(s.path(path))));
     } catch { return false; }
   };
   // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
@@ -277,7 +287,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (path === url.pathname && !Object.keys(groups).length) return request;
     // the path the client sent, which a signature over the request (SigV4's canonical URI) covers
     const headers = new Headers(request.headers);
-    headers.set(ORIGINAL_PATH_HEADER, url.pathname);
+    // the path as first sent: a front before this (an attach bridge) may have named the one its client signed
+    if (!headers.has(ORIGINAL_PATH_HEADER)) headers.set(ORIGINAL_PATH_HEADER, url.pathname);
     if (Object.keys(groups).length) headers.set(PREFIX_PARAMS_HEADER, JSON.stringify(groups));
     url.pathname = path;
     return new Request(url, { method: request.method, headers, body: request.body, ...(request.body ? { duplex: 'half' } : {}) } as RequestInit);

package/src/runtime.ts

@@ -12,6 +12,7 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.ts';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
+export { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';