@volter/world-core 3.0.17 → 3.0.19

package/src/pack-fetch.ts

@@ -6,7 +6,7 @@
 // one of them is answered over the contract's context, which the kernel opens: a pack opens none, reads the tree and
 // writes it only through one.
 import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
-import { TWIN_PREFIX_HEADER } from './twin-fetch.ts';
+import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
 import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
@@ -17,6 +17,13 @@ import { getActiveWorldStore } from './world-store.ts';
 import { runWithCorrelationId } from './actions.ts';
 import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError } from './head.ts';
 import { withCors } from './cors.ts';
+import type { ApplicationStandIn } from './events.ts';
+import { contentAddressOf } from './content-route.ts';
+import { getPack, type HostRule } from './packRegistry.ts';
+import { hostRules } from '../vendor-hosts.cjs';
+
+/** A descriptor's host rules, as data. */
+type PackDescriptorHosts = ReadonlyArray<HostRule> | undefined;
 import { socketUpgrade, type SocketEngine } from './sockets.ts';
 import { MACHINE_POOL, POOL_KINDS } from './machines.ts';
 import { applyTwinWrite } from './serve.ts';
@@ -68,12 +75,23 @@ export type PackParts = {
 export type PackScenario<Req = any> = { adapter: PackScenarioAdapter<Req>; operations: ReadonlyArray<string>; request: (ctx: HandlerContext) => Req | undefined };
 
 /** A lane as its vendor's fetch is given it: its own pack fetch, and its manifest (the doors it declares). */
-export type LanePart = { fetch: ((request: Request) => Promise<Response>) & { serves?: (method: string, path: string) => boolean; boards?: boolean; draws?: (url: string) => boolean }; manifest: { doors?: ReadonlyArray<{ method: string; path: string }> } };
+export type LanePart = {
+  fetch: ((request: Request) => Promise<Response>) & {
+    serves?: (method: string, path: string) => boolean; boards?: boolean; draws?: (url: string) => boolean;
+    /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
+    contentHosts?: ReadonlyArray<string>;
+  };
+  manifest: { doors?: ReadonlyArray<{ method: string; path: string }> };
+};
 
 /** Where a pack serves: its World's root, whether it was started read-only, the World instant when a caller pins it, the
  *  World's managed Postgres the runtime binds a pack declaring `managedDatabase` to (a handler's `ctx.engine`), and the
  *  World's scenario file for a model vendor's turns (`scenarioPath`, the runtime's `--scenario`). */
-export type PackFetchOptions = { root?: string; readOnly?: boolean; clock?: () => string; database?: string; scenarioPath?: string };
+export type PackFetchOptions = {
+  root?: string; readOnly?: boolean; clock?: () => string; database?: string; scenarioPath?: string;
+  /** the application a walk stands in for (a life's `application` answers): this fetch's `ctx.ask` is answered by it */
+  application?: ApplicationStandIn;
+};
 
 type Match = { params: Record<string, string> };
 /** A declared path (`/{account}/r2/api-tokens`, `/<room>`, a door's `/_twin/users/{email}`) as a matcher of a request's
@@ -160,6 +178,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     ...(options.clock ? { clock: options.clock } : {}),
     ...(options.database !== undefined ? { database: options.database, readOnly: options.readOnly ?? false } : {}),
     ...(parts.tenant ? { tenant: parts.tenant } : {}),
+    ...(options.application ? { application: options.application } : {}),
   };
   // a command table's surface (Redis's, a vendor that carries Redis over HTTP) names no HTTP operation: its wire is the
   // pack's front (its `around`), and the table is the denominator the grade counts
@@ -295,6 +314,68 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   };
   const rootServes = (method: string, path: string): boolean => Boolean(matchOperation(routes, method, path));
   const lane = m.lanes ? laneRouter(m.vendor, m.lanes, parts.lanes ?? {}, rootServes) : undefined;
+  // at a World's place, a page's asset or upload on another of the pack's content hosts is `<base>/@<host>/<path>`
+  // (architecture, "A page at a World's place"): answered by the built content screen that names that host exactly,
+  // routed from it, and by nothing else; a request naming no such host is general routing's
+  const contentScreens = screens.filter((s) => s.decl.kind === 'content');
+  for (const s of contentScreens) if (s.decl.yieldsToApi) throw new Error(`${m.vendor}: the content screen ${s.decl.id} declares yieldsToApi; a content screen answers its host's requests alone (architecture, "Screens")`);
+  const contentHosts = [...new Set(contentScreens.flatMap((s) => [s.decl.host, ...(s.decl.hosts ?? [])]).filter((h) => !/[{<]/.test(h)).map((h) => h.toLowerCase()))];
+  const contentNotFound = (host: string, path: string): Response => {
+    const nf = m.notFound;
+    return vendorError(m, { status: nf.status, message: nf.message.replace(/\{object\}/g, host).replace(/\{id\}/g, path), ...(nf.code !== undefined ? { code: nf.code } : {}), ...(nf.kind !== undefined ? { kind: nf.kind } : {}) });
+  };
+  /** A request at a World's place for `/@<host>/<path>`, `<host>` one a built content screen of this unit names exactly:
+   *  that screen's answer, or the pack's not-found for what the host or the screen does not take. The path is held to
+   *  the descriptor's host rules (`rules`: this unit's, or its vendor's for a lane), read as the injector reads them.
+   *  Undefined for any other request. */
+  // the descriptor's host rules: this unit's, or, for a lane (which declares none), its vendor's as registered
+  const descriptorHosts = (): PackDescriptorHosts => m.descriptor?.hosts ?? getPack(m.vendor)?.hosts;
+  const atContentHost = async (request: Request, rules: PackDescriptorHosts = descriptorHosts()): Promise<Response | undefined> => {
+    if (!request.headers.has(TWIN_PREFIX_HEADER)) return undefined;
+    const url = new URL(request.url);
+    const address = contentAddressOf(url.pathname);
+    if (!address || !contentHosts.includes(address.host)) return undefined;
+    const { host, path: inner } = address;
+    if (address.refused) return contentNotFound(host, inner);
+    const declared = hostRules(rules);
+    if (declared.names(host) && !declared.takes(host, inner)) return contentNotFound(host, inner);
+    const onHost = contentScreens.filter((s) => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => h.toLowerCase() === host));
+    const method = request.method.toUpperCase();
+    const allowed = (s: (typeof screens)[number]): boolean => method === 'GET' || method === 'HEAD' || (method === 'POST' && (s.decl.takes ?? []).includes('POST'));
+    // the request as it reaches the content host, through the pack's own routing of a host (its path prefix and labels)
+    url.pathname = inner;
+    const headers = new Headers(request.headers);
+    headers.set('x-volter-twin-original-host', host);
+    const sent = method === 'POST' && request.body ? { body: request.body, duplex: 'half' } : {};
+    const there = routed(new Request(url, { method, headers, signal: request.signal, ...sent } as RequestInit));
+    const path = new URL(there.url).pathname.replace(/\/+$/, '') || '/';
+    const hit = onHost.map((s) => ({ s, hit: s.path(path) })).find((x) => x.hit && allowed(x.s));
+    if (!hit) return contentNotFound(host, inner);
+    const asked = options.readOnly && !isReadOnlyRequest(there) ? withHeaders(there, new Headers([...there.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : there;
+    if (method === 'POST' && ((options.readOnly ?? false) || isReadOnlyRequest(asked))) return refusedReadOnly();
+    if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(asked.url, m.tenant ? { headers: asked.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+    return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit!.params }));
+  };
+  /** A request as the kernel reads it: the headers only the kernel names taken off, its body decoded (undefined when it
+   *  does not decode as its Content-Encoding says). */
+  const prepared = async (arrived: Request): Promise<Request | undefined> => {
+    if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
+      const headers = new Headers(arrived.headers);
+      headers.delete(SCENARIO_DECISION_HEADER);
+      headers.delete(PREFIX_PARAMS_HEADER);
+      arrived = new Request(arrived, { headers });
+    }
+    return decoded(m, arrived);
+  };
+  const undecodable = (arrived: Request): Response => vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+  /** The content route at the request's arrival: the answer, or undefined when this unit's content screens name no such
+   *  host. */
+  const answerContent = async (arrived: Request): Promise<Response | undefined> => {
+    const address = arrived.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(arrived.url).pathname) : undefined;
+    if (!address || !contentHosts.includes(address.host)) return undefined;
+    const readable = await prepared(arrived);
+    return readable ? atContentHost(readable) : undecodable(arrived);
+  };
   const fetch = async (arrived: Request): Promise<Response> => {
     // the discovery door is the pack's own, whichever lane would take its path
     const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
@@ -307,17 +388,15 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
       const frames = await parts.board(await open(request, 'board', 'GET', '/twin/board', {}));
       return Response.json({ frames: frames.map((f) => ({ ...f, drawn: drawsUrl(f.url) })) });
     }
+    // `<base>/@<host>/<path>` at a World's place, for a host a built content screen of this pack names, is that screen's
+    // alone (only the kernel names a scenario's decision or a path prefix's parameters: `prepared` takes them off); for
+    // one a lane's names, the lane router sends it to that lane's own fetch, wrapped as any request to it is
+    const own = await answerContent(arrived);
+    if (own) return own;
     const toLane = discovery ? undefined : lane?.(arrived);
     if (toLane) return toLane(arrived);
-    // only the kernel names a scenario's decision, or a path prefix's parameters
-    if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
-      const headers = new Headers(arrived.headers);
-      headers.delete(SCENARIO_DECISION_HEADER);
-      headers.delete(PREFIX_PARAMS_HEADER);
-      arrived = new Request(arrived, { headers });
-    }
-    const readable = await decoded(m, arrived);
-    if (!readable) return vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+    const readable = await prepared(arrived);
+    if (!readable) return undecodable(arrived);
     const incoming = routed(readable);
     // a twin started read-only marks every request so, so every context it opens knows (isReadOnlyRequest)
     const request = options.readOnly && !isReadOnlyRequest(incoming) ? withHeaders(incoming, new Headers([...incoming.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : incoming;
@@ -368,8 +447,10 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // whichever host the twin is reached (its links carry the twin's own base), never a root screen off its own host
     const host = hostOf(request);
     const exact = (s: (typeof screens)[number]): boolean => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => !/[{<]/.test(h) && h.toLowerCase() === host);
-    const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit);
     const apiPath = Boolean(matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers));
+    // a screen that yields to the API draws only what no operation names, wherever it would answer (architecture,
+    // "Screens": Hacker News's /login page, whose form posts to POST /login)
+    const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit && !(apiPath && x.s.decl.yieldsToApi));
     // reached at a World's place for the twin (`x-forwarded-prefix`, served-world's wire), the host is the World's: a
     // workspace is shown there by its path alone, its root too (the console frames it so)
     const placed = request.headers.has(TWIN_PREFIX_HEADER);
@@ -424,7 +505,9 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     headers.set('content-type', m.jsonContentType!);
     return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
   };
-  const served = m.cors ? withCors(m.cors, labelled) : labelled;
+  const cors = m.cors ? withCors(m.cors, labelled) : labelled;
+  // at a World's place every cookie the twin sets is kept to the twin's base path (twin-fetch.ts, placedCookies)
+  const served = async (request: Request): Promise<Response> => placedCookies(request, await cors(request));
   // which paths this pack's API serves, for a vendor's lane router that asks (unlessOnlyRoot)
   const serves = (method: string, path: string): boolean => Boolean(matchOperation(routes, method, path));
   // the vendor's sockets: a request to a declared socket's path opens a session of its engine, over a context of the
@@ -436,7 +519,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     async (asked) => engineOf()?.serve(asked)) : undefined;
   // what serves each operation: the pack's own, and each lane's
   const owners = (): Record<string, DerivedOwner> => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, ...(upgrade ? { upgrade } : {}) }));
+  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
 }
 
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
@@ -473,6 +556,12 @@ function laneRouter(vendor: string, decl: LanesDecl, lanes: Record<string, LaneP
   });
   const fallback = decl.default !== undefined ? served(decl.default) : undefined;
   return (request) => {
+    // `<base>/@<host>/<path>` at a World's place, for a host a lane's built content screen names, goes to that lane, before
+    // any lane is picked by the request's host or path: its own fetch answers it by its content route, under the vendor's
+    // host rules (architecture, "A page at a World's place")
+    const address = request.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(request.url).pathname) : undefined;
+    const content = address && Object.keys(lanes).find((l) => lanes[l]!.fetch.contentHosts?.includes(address.host));
+    if (content) return served(content);
     const path = new URL(request.url).pathname.replace(/\/{2,}/g, '/');
     if (path.startsWith('/_twin/')) {
       const door = doors.find((d) => d.method === request.method && d.matches(path));

package/src/runtime.ts

@@ -13,7 +13,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 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 { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, 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';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';

package/src/twin-fetch.ts

@@ -44,17 +44,32 @@ export function twinPublicBase(request: Request): string {
 }
 
 /** Where a World shows a hostname its twins answer (a Workers Custom Domain, an R2 public domain): the address a person
- *  opens it at, `{host}` standing for the hostname (`http://{host}.<world>--<org>.localhost:<port>`). A World that routes
- *  its sites to a browser sends it on every request it forwards to a twin. */
+ *  opens it at, from the World's sites template. `{host}` stands for the hostname as it is, where the host's names nest
+ *  (`http://{host}.<world>--<org>.localhost:<port>`); `{site}` for the hostname as one DNS label, its dots as hyphens,
+ *  where one wildcard certificate covers the host's names (`https://{site}--<world>--<org>.volterdev.com`). A World that
+ *  routes its sites to a browser sends the template on every request it forwards to a twin. */
 export const TWIN_SITES_HEADER = 'x-volter-world-sites';
 
+/** A hostname as one DNS label: its dots as hyphens (`www.volter.ai` is `www-volter-ai`). */
+export const siteLabel = (hostname: string): string => hostname.toLowerCase().replace(/\./g, '-');
+
+/** The address a sites template gives `hostname`, or null where the template is not one or the name makes no address
+ *  (a label over 63 characters). */
+export function siteUrlOf(template: string, hostname: string): string | null {
+  const host = hostname.toLowerCase();
+  if (!/^[a-z0-9.-]+$/.test(host)) return null;
+  // a one-label site is never an IDN's (`xn--…` would be read as punycode, and is no address)
+  const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', host)
+    : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', siteLabel(host)) : null;
+  try { return filled && new URL(filled).hostname.split('.').every((l) => l.length > 0 && l.length <= 63) ? filled : null; } catch { return null; }
+}
+
 /** Where a page links a hostname the twin answers: the World's address for it when the World shows sites, else the
  *  hostname itself (reached through the World's proxy, or the vendor). A pack's screen links a site from this, as it
  *  mints its own URLs from twinPublicBase. */
 export function twinSiteUrl(request: Request, hostname: string): string {
   const at = request.headers.get(TWIN_SITES_HEADER);
-  const host = hostname.toLowerCase();
-  return at && /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(at) && /^[a-z0-9.-]+$/.test(host) ? at.replace('{host}', host) : `https://${host}`;
+  return (at ? siteUrlOf(at, hostname) : null) ?? `https://${hostname.toLowerCase()}`;
 }
 
 /** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves
@@ -215,3 +230,29 @@ async function readScoped(run: (asReadOnly?: boolean) => TwinFetchHandlerResult
   if (!out.refused) return out.value;
   return { status: 405, body: { error: 'read_only', message: out.refused.message } };
 }
+
+/** A twin's answer at a World's place with its cookies kept to the twin: every cookie it sets is scoped to the twin's
+ *  base path there (`Path=/` and no Path become `Path=<prefix>`, which RFC 6265's path-match gives the twin's root
+ *  `<prefix>` and every path under it and no sibling; a path under the vendor's root, `Path=/x`, becomes `<prefix>/x`),
+ *  so one twin's sign-in never reaches a sibling twin served from the same pages origin (architecture, "A page at a
+ *  World's place"). A `__Host-` cookie, which a browser takes only at `Path=/`, is left as set. An answer off a place, at
+ *  a prefix the World never sends (outside `/[A-Za-z0-9._~/-]*`, which twinPublicBase refuses too), or setting no cookie
+ *  is the answer as it is. */
+export function placedCookies(request: Request, response: Response): Response {
+  const prefix = request.headers.get(TWIN_PREFIX_HEADER)?.replace(/\/+$/, '');
+  if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix)) return response;
+  const cookies = response.headers.getSetCookie?.() ?? [];
+  if (!cookies.length || response.status < 200) return response;
+  const scoped = cookies.map((cookie) => {
+    if (/^\s*__Host-/i.test(cookie)) return cookie;
+    const path = /;\s*path=([^;]*)/i.exec(cookie)?.[1]?.trim();
+    // already scoped (a lane's answer its vendor passes on): as it is
+    if (path !== undefined && (path === prefix || path.startsWith(`${prefix}/`))) return cookie;
+    const at = !path || path === '/' ? prefix : `${prefix}${path.startsWith('/') ? path : `/${path}`}`.replace(/\/+$/, '');
+    return path === undefined ? `${cookie}; Path=${at}` : cookie.replace(/(;\s*)path=[^;]*/i, `$1Path=${at}`);
+  });
+  const headers = new Headers(response.headers);
+  headers.delete('set-cookie');
+  for (const cookie of scoped) headers.append('set-cookie', cookie);
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}

package/vendor-hosts.cjs

@@ -55,6 +55,39 @@ const COMPILED = new Map();
 /** The hand table's keys, before any pack's rules: a pack installed later replaces its hand entry in place (keeping its
  *  position, which decides who answers a shared host first), where the built-in facts may not declare one twice. */
 const HAND = new Set(Object.keys(VENDOR_HOSTS));
+/** One host rule as a predicate over (hostname, pathname?): its one selector (host | suffix | hostPattern) and its
+ *  pathPattern, a path left out matching any. */
+function compileHostRule(rule, where) {
+  const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
+  if (selectors !== 1) throw new Error(`inject: ${where} rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
+  const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
+  const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
+  return (h, p) =>
+    (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
+    && (pathRe === null || p === undefined || pathRe.test(p));
+}
+
+/** A pack's host rules (its descriptor's `hosts`) read as the injector reads them: `names(host)`, whether any include
+ *  rule's selector names the host, whatever the path; `takes(host, path)`, whether the request is the pack's (under
+ *  one of its keys, an include matches and no exclude does). The content route at a World's place holds a
+ *  `<base>/@<host>/<path>` to it (pack-fetch.ts). */
+function hostRules(rules) {
+  const byKey = new Map();
+  for (const rule of rules || []) {
+    const key = rule.key === undefined ? '' : rule.key;
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(rule);
+  }
+  const keys = [...byKey.values()].map((keyRules) => ({
+    includes: keyRules.filter((r) => r.exclude !== true).map((r) => compileHostRule(r, 'a pack')),
+    excludes: keyRules.filter((r) => r.exclude === true).map((r) => compileHostRule(r, 'a pack')),
+  }));
+  return {
+    names: (h) => keys.some((k) => k.includes.some((m) => m(h))),
+    takes: (h, p) => keys.some((k) => k.includes.some((m) => m(h, p)) && !k.excludes.some((m) => m(h, p))),
+  };
+}
+
 function compilePackHosts(packs, overlay) {
   for (const vendor of Object.keys(packs)) {
     const rules = packs[vendor].hosts;
@@ -77,15 +110,7 @@ function compilePackHosts(packs, overlay) {
       if (VENDOR_HOSTS[key] && !(overlay && HAND.has(key))) {
         throw new Error(`inject: key "${key}" (pack ${vendor}) is declared twice — on this descriptor and in the hand VENDOR_HOSTS table or another pack's descriptor; a key has one home.`);
       }
-      const compile = (rule) => {
-        const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
-        if (selectors !== 1) throw new Error(`inject: key "${key}" (pack ${vendor}) rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
-        const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
-        const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
-        return (h, p) =>
-          (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
-          && (pathRe === null || p === undefined || pathRe.test(p));
-      };
+      const compile = (rule) => compileHostRule(rule, `key "${key}" (pack ${vendor})`);
       const includes = keyRules.filter((r) => r.exclude !== true).map(compile);
       const excludes = keyRules.filter((r) => r.exclude === true).map(compile);
       VENDOR_HOSTS[key] = (h, p) => includes.some((m) => m(h, p)) && !excludes.some((m) => m(h, p));
@@ -141,4 +166,4 @@ function twinOrigins(env) {
   return map;
 }
 
-module.exports = { VENDOR_HOSTS, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };
+module.exports = { VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/vendor-hosts.d.cts

@@ -6,3 +6,6 @@ export function vendorsOfHost(hostname: string): string[];
 export function twinEnvStem(vendor: string): string;
 /** The vendors whose twin `env` points at, each with its origin. */
 export function twinOrigins(env: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/** A pack's host rules (its descriptor's `hosts`, as data) read as the injector reads them: whether any include names a
+ *  host whatever the path, and whether a request to a host and path is the pack's. */
+export function hostRules(rules: ReadonlyArray<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };