@volter/world-core 2.0.37 → 3.0.1

package/src/events.ts

@@ -0,0 +1,449 @@
+// DECLARED EVENTS (docs/contributing/architecture.md, "What an author writes, and how": the events row) — the webhook a
+// vendor sends for a write, as data the kernel executes. A pack declares which write sends which event type, the
+// event's envelope, the scheme that signs it and where the World's endpoints are kept; the kernel renders, signs,
+// delivers (through the World's application route and egress rule) and records each delivery. The one thing a pack
+// may write is how its vendor renders an event's `data` (`semantics/events.ts`), when it is not the written object.
+//
+// Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
+// delivery is made, never when a browser client imports the kernel.
+import { createHash, createHmac } from 'node:crypto';
+import { applyTwinWrite, twinResources } from './serve.ts';
+import { equalSecrets as same } from './signing.ts';
+import { deliveryTraceHeaders } from './trace-context.ts';
+
+/** How the vendor signs a delivery. */
+export type EventScheme =
+  /** A message id, a timestamp and a signature header (the Standard Webhooks shape): `<prefix>-id`,
+   *  `<prefix>-timestamp` (seconds) and `<prefix>-signature: v1,<base64 HMAC-SHA256>` over `${id}.${timestamp}.${body}`,
+   *  keyed by the base64 part of the secret after `secretPrefix`, or by the secret's own UTF-8 bytes (`secretKey: 'utf8'`:
+   *  Polar's, whose SDK base64-encodes the secret as it is before verifying). */
+  | { kind: 'webhook-id'; prefix: string; secretPrefix?: string; secretKey?: 'base64' | 'utf8' }
+  /** One header of a timestamp and its signatures: `<header>: t=<seconds>,v1=<hex HMAC-SHA256>` over `${t}.${body}`,
+   *  keyed by the secret as it is. */
+  | { kind: 'timestamp-v1'; header: string }
+  /** One HMAC header over the body (`X-Hub-Signature-256: sha256=<hex>`, GitHub's), or over `${timestamp}.${body}` when
+   *  the vendor sends its timestamp in `timestampHeader`; `signed` names what is signed otherwise, `{t}` the timestamp
+   *  and `{body}` the body (Slack's `v0:{t}:{body}`), and `algorithm` the hash (SHA-256 unless named: GitHub's older
+   *  `X-Hub-Signature` is SHA-1). */
+  | { kind: 'hmac'; header: string; encoding: 'hex' | 'base64'; prefix?: string; timestampHeader?: string; signed?: string; algorithm?: 'sha1' | 'sha256'; secretKey?: 'base64' | 'utf8' }
+  /** One header of a plain hash (not an HMAC) of the secret and the body (HubSpot's v1 `X-HubSpot-Signature`: the SHA-256
+   *  of the app's client secret followed by the request body); `signed` names the input, `{secret}` and `{body}` */
+  | { kind: 'hash'; header: string; signed: string; encoding: 'hex' | 'base64'; algorithm?: 'sha256' };
+
+/** Where the World's endpoints of one kind are kept (a door the vendor's dashboard stands in for writes them): their
+ *  stored type and the fields holding the URL, the signing secret, the event types an endpoint takes (all when absent,
+ *  `*` and `<family>.*` patterns) and whether it is disabled (`disabled` true), not enabled (`enabled` false) or not live
+ *  (`status`). A field may be a dotted path into the row (`config.url`). */
+export type EndpointsDecl = {
+  storedAs: string; url: string; secret: string; filter?: string; disabled?: string; enabled?: string;
+  /** An endpoint that is live only while a field holds one value (Stripe's `status: 'enabled'`). */
+  status?: { field: string; live: string };
+  /** Which events an endpoint takes by whom they are about: one whose `field` is true takes only events whose
+   *  envelope value `value` is set (Stripe's Connect endpoint, `connect: true`, takes connected accounts' events, those
+   *  with an `$account`), and any other only events where it is not. */
+  scope?: { field: string; value: string };
+  /** Endpoint fields that must equal an event's values (field → `$value`, or a literal): a repository's hook takes only
+   *  its repository's events (GitHub's `{ repository: '$repository' }`), an organization's its organization's. A list
+   *  field takes the event when it holds the value. Several matches: the endpoint takes the event when any holds (a
+   *  GitHub App's installation: its own events, its account's when it covers all the account's repositories, a listed
+   *  repository's). */
+  match?: Record<string, string> | ReadonlyArray<Record<string, string>>;
+  /** Related rows an endpoint's fields read through (`app.hook_url`): each join's name, the stored type it names and the
+   *  endpoint's field holding its id (a GitHub installation's URL, secret and events are its App's). */
+  joins?: Record<string, { storedAs: string; by: string }>;
+  /** The event types this kind of endpoint takes (every type when absent), or those it does not (`skip`): two kinds over
+   *  the same rows, one taking a type under a `match` the other has no need of (a Slack app is sent `app_mention` only
+   *  when a message mentions it, and every `message` its subscription names). */
+  types?: ReadonlyArray<string>;
+  skip?: ReadonlyArray<string>;
+  /** What each delivery's answer writes on the endpoint, when the vendor keeps score (Daily's webhook): a success (2xx)
+   *  resets `failures` and writes `success` (templates: `$time.iso`, `$time.s`), a failure adds one to `failures`, and
+   *  `after` failures in a row make `move`, the vendor's transition of a state field, asked of the endpoint's machine,
+   *  on every endpoint but one matching `unless` (Daily's `exponential` retry never breaks). */
+  outcome?: EndpointOutcome;
+};
+
+/** An endpoint kind's delivery outcome (EndpointsDecl.outcome). */
+export type EndpointOutcome = {
+  failures: string;
+  success?: Record<string, string>;
+  after?: number;
+  move?: { field: string; to: string; operation: string };
+  unless?: { field: string; equals: unknown };
+};
+
+/** A delivery's answer as the kernel reads it: the endpoint kind and row it went to, and the receiver's status (0 when
+ *  the World refused it or nothing answered). */
+export type DeliveryAnswer = { kind: EndpointsDecl; row: Record<string, unknown>; status: number; occurredAt: string };
+
+/** Whether an endpoint takes an event by its `match`: every field of one match (any, when several) equal to the event's
+ *  value, or, a list, holding it. */
+function matches(row: Record<string, unknown>, match: EndpointsDecl['match'], filled: Record<string, unknown>): boolean {
+  if (match === undefined) return true;
+  const one = (m: Record<string, string>): boolean => Object.entries(m).every(([field, value]) => {
+    const want = value.startsWith('$') ? filled[value] : value;
+    const have = at(row, field);
+    // a list value takes a row whose field is one of it (the apps a Slack message mentions)
+    if (Array.isArray(want)) return want.some((w) => String(w) === String(have));
+    return Array.isArray(have) ? have.some((h) => String(h) === String(want)) : have === want || (have !== undefined && want !== undefined && String(have) === String(want));
+  });
+  return Array.isArray(match) ? match.some(one) : one(match as Record<string, string>);
+}
+
+/** The events a pack's writes send. */
+export type EventsDecl = {
+  /** how each delivery is signed; several schemes each add their headers (GitHub's SHA-256 and SHA-1 signatures) */
+  scheme: EventScheme | ReadonlyArray<EventScheme>;
+  /** further headers each delivery carries, templates as the envelope's are, plus `$endpoint.<field>` for the endpoint
+   *  it goes to (GitHub's `X-GitHub-Event`, `X-GitHub-Delivery` and `X-GitHub-Hook-ID`) */
+  headers?: Record<string, string>;
+  /** A write's kernel operation (`user.create`) → the vendor's event type (`user.created`), or several (a Slack message
+   *  sends `message` and `app_mention`; `values` withholds one the write does not warrant); a write not named sends none. */
+  types: Record<string, string | ReadonlyArray<string>>;
+  /** The event types the vendor enumerates, when it names every write's event by its resource: an operation that is
+   *  one of them sends it, and `<resource>.create|update|delete` sends `<resource>.created|updated|deleted` when that is
+   *  one of them (a vendor whose spec lists its event types: Stripe's). `types` is read first. */
+  known?: ReadonlyArray<string>;
+  /** The vendor's own resource each event is also kept as (its Events API: Stripe's `GET /v1/events`), the envelope as
+   *  its fields under the event's id, whether or not an endpoint takes it. */
+  store?: string;
+  /** The event as the vendor sends it, a template: a string `$type`, `$data`, `$id`, `$time.ms`, `$time.s`, `$time.iso`,
+   *  `$request.client_ip` or `$request.user_agent` is replaced by that value; everything else is sent as written. */
+  envelope: unknown;
+  /** Where the World's endpoints are kept: one kind, or several (GitHub's repository and organization hooks). */
+  endpoints: EndpointsDecl | ReadonlyArray<EndpointsDecl>;
+  /** The bookkeeping type each delivery is kept as (`_webhook_message`): what a World reads to see what was sent. */
+  record?: string;
+  /** The bookkeeping type a World states its receivers' answers in (`{url, status}`, Daily's `_receiver`), for receivers
+   *  it runs no server for: a delivery whose URL starts with a stated `url` (the longest) is answered that status, and
+   *  nothing is sent. */
+  receivers?: string;
+};
+
+/** An event's further envelope values (`$`-named) the pack computes for a write, from the vendor's own state (the
+ *  connected account it is about, the API version it is rendered in): the pack's `semantics/events.ts` `values`. A
+ *  value left undefined drops its key from the envelope; `$send: false` keeps the event (stored) but sends it to no
+ *  endpoint (an account the vendor no longer reports to). */
+export type EventValues<C> = (ctx: C, write: EventWrite, type: string) => Record<string, unknown>;
+
+/** The write an event reports, as the kernel's write hook sees it. */
+export type EventWrite = { operation: string; storedType: string; body: Record<string, unknown>; root?: string; occurredAt: string; request?: Request };
+
+/** How the vendor renders an event's `data` for a write, when it is not the written object as its operation answered
+ *  it: the pack's `semantics/events.ts`, under the handler contract's read-only context, for each type the write sends
+ *  (a Slack message renders as `message` and as `app_mention`). */
+export type EventRender<C> = (ctx: C, write: EventWrite, type: string) => Record<string, unknown>;
+
+/** A delivery made: where it went and exactly what was sent. */
+export type EventDelivery = { url: string; body: string; headers: Record<string, string> };
+
+/** The transport a delivery is made over; the World's by default, a test's own when given. */
+export type EventTransport = (url: string, body: string, headers: Record<string, string>) => Promise<number | void>;
+
+const digest = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+/** A `webhook-id` scheme's key: the base64 part of the secret, after its prefix when it carries one. */
+const webhookKey = (scheme: { secretPrefix?: string; secretKey?: 'base64' | 'utf8' }, secret: string): Buffer =>
+  scheme.secretKey === 'utf8' ? Buffer.from(secret, 'utf8') : Buffer.from(scheme.secretPrefix && secret.startsWith(scheme.secretPrefix) ? secret.slice(scheme.secretPrefix.length) : secret, 'base64');
+
+/** A signature scheme's headers for one delivery: deterministic (the id is derived from the delivery itself). */
+/** `seq` tells apart two identical deliveries at one instant (a frozen World clock): the World's count of deliveries
+ *  made before this one, so a receiver that deduplicates by id drops neither. */
+export function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
+  if (scheme.kind === 'webhook-id') {
+    const id = `msg_twin_${digest(`${url}|${seconds}|${seq}|${body}`).slice(0, 24)}`;
+    const p = scheme.prefix.toLowerCase();
+    const signature = createHmac('sha256', webhookKey(scheme, secret)).update(`${id}.${seconds}.${body}`, 'utf8').digest('base64');
+    return { [`${p}-id`]: id, [`${p}-timestamp`]: String(seconds), [`${p}-signature`]: `v1,${signature}` };
+  }
+  if (scheme.kind === 'timestamp-v1') {
+    const signature = createHmac('sha256', secret).update(`${seconds}.${body}`, 'utf8').digest('hex');
+    return { [scheme.header.toLowerCase()]: `t=${seconds},v1=${signature}` };
+  }
+  if (scheme.kind === 'hash') return { [scheme.header.toLowerCase()]: hashOf(scheme, secret, body) };
+  // the key is the secret as it is, or its base64 decoded (`secretKey: 'base64'`, Daily's)
+  const mac = createHmac(scheme.algorithm ?? 'sha256', scheme.secretKey === 'base64' ? Buffer.from(secret, 'base64') : secret).update(hmacBase(scheme, seconds, body), 'utf8').digest(scheme.encoding);
+  return { [scheme.header.toLowerCase()]: `${scheme.prefix ?? ''}${mac}`, ...(scheme.timestampHeader ? { [scheme.timestampHeader.toLowerCase()]: String(seconds) } : {}) };
+}
+
+/** A `hash` scheme's value: the digest of its `signed` template with the secret and the body put in. */
+const hashOf = (scheme: { signed: string; encoding: 'hex' | 'base64'; algorithm?: 'sha256' }, secret: string, body: string): string =>
+  createHash(scheme.algorithm ?? 'sha256').update(scheme.signed.replaceAll('{secret}', secret).replaceAll('{body}', body), 'utf8').digest(scheme.encoding);
+
+/** What an `hmac` scheme signs: its `signed` template, else `${t}.${body}` with a timestamp header, else the body. */
+const hmacBase = (scheme: { timestampHeader?: string; signed?: string }, seconds: number, body: string): string =>
+  scheme.signed !== undefined ? scheme.signed.replaceAll('{t}', String(seconds)).replaceAll('{body}', body) : scheme.timestampHeader ? `${seconds}.${body}` : body;
+
+/** Every scheme's headers for one delivery, merged. */
+export function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
+  return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme: EventScheme) => signEvent(scheme, secret, body, seconds, url, seq)));
+}
+
+/** A delivery's signature checked as its receiver checks it (a Standard Webhooks verifier, a timestamp-v1 verifier, a plain
+ *  HMAC header): true when one of its signatures is the one the secret makes (constant time), and its timestamp,
+ *  when the scheme sends one, is within `tolerance` seconds of `now`. */
+export function verifyEvent(scheme: EventScheme, secret: string, body: string, headers: Record<string, string>, opts: { tolerance?: number; now?: number } = {}): boolean {
+  const h = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+  // a check given the time holds the timestamp to five minutes unless it says otherwise (Standard Webhooks' default)
+  const fresh = (seconds: number): boolean => opts.now === undefined || Math.abs(opts.now - seconds) <= (opts.tolerance ?? 300);
+  if (secret === '') return false;
+  if (scheme.kind === 'webhook-id') {
+    const p = scheme.prefix.toLowerCase();
+    const id = h[`${p}-id`]; const seconds = Number(h[`${p}-timestamp`]); const given = h[`${p}-signature`];
+    if (!id || !given || !Number.isFinite(seconds) || !fresh(seconds)) return false;
+    const expected = createHmac('sha256', webhookKey(scheme, secret)).update(`${id}.${seconds}.${body}`, 'utf8').digest('base64');
+    return given.split(' ').some((part) => part.startsWith('v1,') && same(part.slice('v1,'.length), expected));
+  }
+  if (scheme.kind === 'timestamp-v1') {
+    const parts = (h[scheme.header.toLowerCase()] ?? '').split(',').map((p) => p.split('=') as [string, string]);
+    const seconds = Number(parts.find(([k]) => k === 't')?.[1]);
+    if (!Number.isFinite(seconds) || !fresh(seconds)) return false;
+    const expected = createHmac('sha256', secret).update(`${seconds}.${body}`, 'utf8').digest('hex');
+    return parts.some(([k, v]) => k === 'v1' && v !== undefined && same(v, expected));
+  }
+  if (scheme.kind === 'hash') { const given = h[scheme.header.toLowerCase()]; return given !== undefined && same(given, hashOf(scheme, secret, body)); }
+  const seconds = scheme.timestampHeader ? Number(h[scheme.timestampHeader.toLowerCase()]) : undefined;
+  if (seconds !== undefined && (!Number.isFinite(seconds) || !fresh(seconds))) return false;
+  const expected = `${scheme.prefix ?? ''}${createHmac(scheme.algorithm ?? 'sha256', secret).update(hmacBase(scheme, seconds ?? 0, body), 'utf8').digest(scheme.encoding)}`;
+  return same(h[scheme.header.toLowerCase()] ?? '', expected);
+}
+
+/** The envelope template filled for one event, and for one endpoint when it names `$endpoint.<field>` (left out when
+ *  there is none: the event as kept). A `...` key spreads its filled value into the object. */
+export function fillEnvelope(template: unknown, values: Record<string, unknown>, endpoint?: Record<string, unknown>): unknown {
+  if (typeof template === 'string') {
+    if (template.startsWith('$endpoint.')) return endpoint ? at(endpoint, template.slice('$endpoint.'.length)) ?? undefined : undefined;
+    return template.startsWith('$') && template in values ? values[template] : template;
+  }
+  if (Array.isArray(template)) return template.map((item) => fillEnvelope(item, values, endpoint));
+  // a key whose value is a `$` value left undefined is not sent (an event about no connected account has no `account`)
+  if (template && typeof template === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(template)) {
+      const filled = fillEnvelope(value, values, endpoint);
+      if (key === '...') { if (filled && typeof filled === 'object' && !Array.isArray(filled)) Object.assign(out, filled); continue; }
+      if (filled !== undefined) out[key] = filled;
+    }
+    return out;
+  }
+  return template;
+}
+
+/** Whether an envelope template names an endpoint's fields (so each delivery's body is its own). */
+const perEndpoint = (template: unknown): boolean => JSON.stringify(template ?? null).includes('"$endpoint.');
+
+/** A row's field by a dotted path (`config.url`). */
+function at(row: Record<string, unknown>, path: string): unknown {
+  let v: unknown = row;
+  for (const key of path.split('.')) v = v && typeof v === 'object' ? (v as Record<string, unknown>)[key] : undefined;
+  return v;
+}
+
+/** A delivery's further headers: each a `$` value, an endpoint's `$endpoint.<field>`, or written as it is. */
+function headersFor(templates: Record<string, string>, values: Record<string, unknown>, endpoint: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, template] of Object.entries(templates)) {
+    // a literal may stand before an endpoint's field (`Basic $endpoint.basicAuth`); the header is dropped when it is empty
+    const prefixed = /^(.+?)\$endpoint\.([\w.]+)$/.exec(template);
+    const field = prefixed ? at(endpoint, prefixed[2]!) : undefined;
+    const value = prefixed ? (field === undefined || field === null || field === '' ? undefined : `${prefixed[1]}${String(field)}`)
+      : template.startsWith('$endpoint.') ? at(endpoint, template.slice('$endpoint.'.length)) : template.startsWith('$') ? values[template] : template;
+    if (value !== undefined && value !== null) out[name.toLowerCase()] = String(value);
+  }
+  return out;
+}
+
+const knownSets = new WeakMap<ReadonlyArray<string>, Set<string>>();
+/** The event types a write's operation sends: `types`, else the vendor's enumerated types (`known`). */
+export function eventTypesOf(decl: Pick<EventsDecl, 'types' | 'known'>, operation: string): string[] {
+  const named = decl.types[operation];
+  if (named !== undefined) return typeof named === 'string' ? [named] : [...named];
+  const one = eventTypeOf(decl, operation);
+  return one === undefined ? [] : [one];
+}
+
+/** The event type a write's operation sends, if any: its first under `types`, else the vendor's enumerated types
+ *  (`known`). */
+export function eventTypeOf(decl: Pick<EventsDecl, 'types' | 'known'>, operation: string): string | undefined {
+  const given = decl.types[operation];
+  const named = typeof given === 'string' || given === undefined ? given : given[0];
+  if (named !== undefined || !decl.known) return named;
+  let known = knownSets.get(decl.known);
+  if (!known) knownSets.set(decl.known, known = new Set(decl.known));
+  if (known.has(operation)) return operation;
+  const verb = /^(.+)\.(create|update|delete)$/.exec(operation);
+  return verb && known.has(`${verb[1]}.${verb[2]}d`) ? `${verb[1]}.${verb[2]}d` : undefined;
+}
+
+/** Whether an endpoint's list of event types takes a type: every type when the list is empty, `*` or `<family>.*`
+ *  its patterns, else the type itself. */
+export function takesEvent(list: unknown, type: string): boolean {
+  if (!Array.isArray(list) || list.length === 0) return true;
+  return list.some((p) => { const s = String(p); return s === '*' || s === type || (s.endsWith('.*') && type.startsWith(s.slice(0, -1))); });
+}
+
+/** The request that made the write, as an event's attributes name it: the client's address (the first hop a proxy
+ *  names) and its user agent. */
+function requestValues(request: Request | undefined): Record<string, string> {
+  const forwarded = request?.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
+  return {
+    '$request.client_ip': forwarded ?? request?.headers.get('x-real-ip') ?? '',
+    '$request.user_agent': request?.headers.get('user-agent') ?? '',
+  };
+}
+
+/** The World's transport: its application route (the app's own hostnames reach it inside the World) and its egress
+ *  rule (a refused destination is dropped as an unreachable endpoint is), never awaited by the write that sent it (deliverEvents schedules it after the answer). Loaded at
+ *  the first delivery, so importing the kernel stays free of Node's http. */
+const worldTransport: EventTransport = async (url, body, headers) => {
+  const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
+    import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<unknown> }>,
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,
+  ]);
+  if (!appDestination(url) && worldEgressRefusal(url) !== null) return 0;
+  try { return ((await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body })) as { status: number }).status; } catch { return 0; }
+};
+
+/** A message a vendor sends the application's own server that is no declared event (Google Calendar's push notification:
+ *  a bodiless POST with its X-Goog headers), over the same transport: the receiver's status, or 0 when the World lets
+ *  no request out to it or it cannot be reached. The vendor waits on it, as the sender of such a message does. */
+export async function deliverToApplication(url: string, init: RequestInit): Promise<number> {
+  const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
+    import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<{ status: number }> }>,
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,
+  ]);
+  if (!appDestination(url) && worldEgressRefusal(url) !== null) return 0;
+  // the request that caused the message is its trace's parent (trace-context.ts)
+  const headers = new Headers(init.headers);
+  for (const [k, v] of Object.entries(deliveryTraceHeaders())) if (!headers.has(k)) headers.set(k, v);
+  try { return (await appFetch(url, { ...init, headers })).status; } catch { return 0; }
+}
+
+/** What the application's server answered a message the vendor waits on, or why it did not answer: `missed` when the
+ *  World let no request out to it or it could not be reached (`unreachable`), or it did not answer in time (`timeout`). */
+export type ApplicationAnswer = { status: number; body: string; missed?: 'timeout' | 'unreachable' };
+
+/** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
+ *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds. */
+export async function askApplication(url: string, init: RequestInit, within: number): Promise<ApplicationAnswer> {
+  const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
+    import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<{ status: number; text(): Promise<string> }> }>,
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,
+  ]);
+  if (!appDestination(url) && worldEgressRefusal(url) !== null) return { status: 0, body: '', missed: 'unreachable' };
+  const headers = new Headers(init.headers);
+  for (const [k, v] of Object.entries(deliveryTraceHeaders())) if (!headers.has(k)) headers.set(k, v);
+  try {
+    const res = await appFetch(url, { ...init, headers, signal: AbortSignal.timeout(within) });
+    return { status: res.status, body: await res.text() };
+  } catch (e) {
+    return { status: 0, body: '', missed: e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError') ? 'timeout' : 'unreachable' };
+  }
+}
+
+/** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
+ *  that takes it, and recorded. */
+export async function deliverEvents(
+  service: string,
+  decl: EventsDecl,
+  write: EventWrite,
+  data: (type: string) => Promise<Record<string, unknown>>,
+  transport: EventTransport = worldTransport,
+  values?: (type: string) => Promise<Record<string, unknown>>,
+  onAnswer?: (answer: DeliveryAnswer) => Promise<void>,
+): Promise<EventDelivery[]> {
+  if (write.storedType === decl.store) return [];
+  const sent: EventDelivery[] = [];
+  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type, onAnswer)));
+  return sent;
+}
+
+/** One event type a write sends: to the live endpoints that take it, stored when the vendor keeps its events. */
+async function deliverEventType(
+  service: string,
+  decl: EventsDecl,
+  write: EventWrite,
+  data: (type: string) => Promise<Record<string, unknown>>,
+  transport: EventTransport,
+  values: ((type: string) => Promise<Record<string, unknown>>) | undefined,
+  type: string,
+  onAnswer?: (answer: DeliveryAnswer) => Promise<void>,
+): Promise<EventDelivery[]> {
+  const all = twinResources(service, write.root) as unknown as Array<Record<string, unknown>>;
+  const kinds = Array.isArray(decl.endpoints) ? decl.endpoints : [decl.endpoints as EndpointsDecl];
+  // an endpoint's row with its joined rows under their names (`app.hook_url` reads the installation's App)
+  const joined = (kind: EndpointsDecl, r: Record<string, unknown>): Record<string, unknown> => {
+    if (!kind.joins) return r;
+    const out: Record<string, unknown> = { ...r, id: r.id };
+    for (const [name, j] of Object.entries(kind.joins)) out[name] = all.find((x) => x.type === j.storedAs && x.deleted !== true && String(x.id) === String(at(r, j.by)));
+    return out;
+  };
+  const live = kinds.filter((kind) => (!kind.types || kind.types.includes(type)) && !kind.skip?.includes(type)).flatMap((kind) => all
+    .filter((r) => r.type === kind.storedAs && r.deleted !== true)
+    .map((r) => joined(kind, r as Record<string, unknown>))
+    .filter((r) => (kind.disabled === undefined || at(r, kind.disabled) !== true) && (kind.enabled === undefined || at(r, kind.enabled) !== false) && (kind.status === undefined || at(r, kind.status.field) === kind.status.live))
+    .filter((r) => typeof at(r, kind.url) === 'string' && typeof at(r, kind.secret) === 'string')
+    .filter((r) => kind.filter === undefined || takesEvent(at(r, kind.filter), type))
+    .map((row) => ({ row, kind })));
+  if (live.length === 0 && decl.store === undefined) return [];
+  const millis = Date.parse(write.occurredAt) || 0;
+  const seconds = Math.floor(millis / 1000);
+  const eventData = await data(type);
+  const extra = values ? await values(type) : {};
+  // the World's count of events kept so far tells apart two identical events at one instant (a frozen clock)
+  const kept = decl.store !== undefined ? all.filter((r) => r.type === decl.store).length : 0;
+  const filled: Record<string, unknown> = {
+    $type: type, $data: eventData,
+    $id: `evt_twin_${digest(`${type}|${write.occurredAt}|${kept}|${JSON.stringify(eventData)}`).slice(0, 24)}`,
+    '$time.ms': millis, '$time.s': seconds, '$time.iso': write.occurredAt,
+    ...requestValues(write.request),
+    ...extra,
+  };
+  const envelope = fillEnvelope(decl.envelope, filled);
+  if (decl.store !== undefined) {
+    await applyTwinWrite(service, { operation: `${decl.store}.record`, subjectType: decl.store, subjectId: String(filled.$id), fields: envelope as Record<string, unknown>, occurredAt: write.occurredAt, actor: { kind: 'system' } }, write.root);
+  }
+  if (extra.$send === false) return [];
+  const endpoints = live
+    .filter(({ row, kind }) => kind.scope === undefined || (at(row, kind.scope.field) === true) === (filled[kind.scope.value] !== undefined))
+    .filter(({ row, kind }) => matches(row, kind.match, filled));
+  if (endpoints.length === 0) return [];
+  const shared = JSON.stringify(envelope);
+  const each = perEndpoint(decl.envelope);
+  const sent: EventDelivery[] = [];
+  const to: Array<{ kind: EndpointsDecl; row: Record<string, unknown> }> = [];
+  const before = decl.record !== undefined ? all.filter((r) => r.type === decl.record).length : 0;
+  for (const [i, { row, kind }] of endpoints.entries()) {
+    const body = each ? JSON.stringify(fillEnvelope(decl.envelope, filled, row)) : shared;
+    const url = String(at(row, kind.url));
+    const seq = before + i;
+    const extraHeaders = decl.headers ? headersFor(decl.headers, filled, row) : {};
+    const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq) };
+    sent.push({ url, body, headers });
+    to.push({ kind, row });
+    // kept with the write, by an id of the delivery itself (two made at once never take the same one)
+    if (decl.record !== undefined) {
+      await applyTwinWrite(service, {
+        operation: `${decl.record.slice(1)}.record`, subjectType: decl.record, subjectId: `${decl.record.slice(1)}_${digest(`${url}|${seconds}|${seq}|${body}`).slice(0, 16)}`,
+        fields: { url, body, headers, event_type: type, sent_at: millis }, occurredAt: write.occurredAt, actor: { kind: 'system' },
+      }, write.root);
+    }
+  }
+  // sent after the write's answer, as a vendor sends it: the caller never waits on its receiver, and a receiver that is
+  // slow or down fails no request
+  // the write's trace is read now, inside its request, and carried on each delivery (W3C trace continuation)
+  const trace = deliveryTraceHeaders();
+  // each answer is read as the vendor reads it, when the endpoint kind keeps score (its `outcome`)
+  const stated = (url: string): number | undefined => {
+    const r = decl.receivers === undefined ? undefined : all.filter((x) => x.type === decl.receivers && x.deleted !== true && url.startsWith(String(x.url)))
+      .sort((x, y) => String(y.url).length - String(x.url).length)[0];
+    return r === undefined ? undefined : Number(r.status);
+  };
+  for (const [i, { url, body: payload, headers }] of sent.entries()) setTimeout(() => {
+    const answered = stated(url);
+    (answered !== undefined ? Promise.resolve(answered) : transport(url, payload, { ...headers, ...trace }))
+      .then((status) => (onAnswer && to[i]!.kind.outcome ? onAnswer({ ...to[i]!, status: typeof status === 'number' ? status : 0, occurredAt: write.occurredAt }) : undefined))
+      .catch(() => {});
+  }, 0);
+  return sent;
+}

package/src/executor.ts

@@ -8,6 +8,7 @@
 import type { CredentialPayload } from './credential.ts';
 import type { RemoteExecute } from './remote-execute.ts';
 import type { HostRule } from './packRegistry.ts';
+import { RateBudget } from './rateBudget.ts';
 
 /**
  * HOW A VENDOR AUTHENTICATES — a fact about the vendor, declared by the pack (`TwinPack.auth`) and
@@ -218,9 +219,30 @@ async function awsSigV4Headers(input: {
 /** Where a credential is kept (the head's and refresh's root: head.ts rootCustody): `key` names the credential stably
  *  across rotations and anew when another is sealed in its place (the token cache is keyed by it, not by the secret's value), `open` reads it as sealed now, `seal` keeps a rotated one. */
 export type CredentialCustody = { key: string; open: () => Promise<CredentialPayload>; seal: (credential: CredentialPayload) => Promise<void> | void };
-export type RemoteExecuteOptions = { custody?: CredentialCustody };
+/** `vendor`: the vendor whose rate budget every call is charged to (D8): the call is priced and reserved before it is
+ *  made, refused when the budget is spent, and settled with the vendor's answer (its back-off honoured). */
+export type RemoteExecuteOptions = { custody?: CredentialCustody; vendor?: string };
 export function buildRemoteExecute(origin: URL, credential: CredentialPayload, auth?: TwinAuthStrategy, vendorHosts?: readonly HostRule[], options: RemoteExecuteOptions = {}): RemoteExecute {
-  if (auth?.in === 'exchange') return exchangeExecute(origin, credential, auth, vendorHosts, options.custody);
+  const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts);
+  return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
+}
+
+/** Every live call charged to the vendor's rate budget (rateBudget.ts, D8): a call the budget refuses is never made;
+ *  the ledger is the credential's (only its hash names it). */
+function budgeted(vendor: string, execute: RemoteExecute, token: string): RemoteExecute {
+  const budget = new RateBudget({ vendor, token });
+  return async (request) => {
+    const url = new URL(request.path, 'http://budget.invalid');
+    const weight = budget.weightFor(`${request.method.toUpperCase()} ${url.pathname}`, Object.fromEntries(url.searchParams));
+    const reservation = budget.checkBudget(weight);
+    const answer = await execute(request);
+    budget.recordCall(weight, answer.headers, { status: answer.status, reservation });
+    return answer;
+  };
+}
+
+/** The call made as the root's credential is applied by the strategy (header replacement when none). */
+function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinAuthStrategy, { in: 'exchange' }>, vendorHosts?: readonly HostRule[]): RemoteExecute {
   return async ({ method, path, headers, body, responseType, presigned }) => {
     // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
     // sealed credential never goes with it, whatever host it names. A host other than the root's

package/src/file-response.ts

@@ -20,3 +20,30 @@ export function fileResponse(path: string, init?: ResponseInit): Response {
   if (!headers.has('content-type')) headers.set('content-type', contentTypeOf(path));
   return new Response(readFileSync(path), { ...init, headers });
 }
+
+/**
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range that does not parse, a
+ * first-byte-pos past its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed
+ * range that starts past the end is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ */
+export function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl = 'public, max-age=604800, immutable'): Response {
+  const total = bytes.length;
+  const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': cacheControl };
+  const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
+  let start = 0;
+  let end = total - 1;
+  const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && Number(range[1]) > Number(range[2]));
+  if (valid) {
+    if (range[1] === '') { start = Math.max(0, total - Number(range[2])); } else {
+      start = Number(range[1]);
+      end = range[2] === '' ? total - 1 : Math.min(Number(range[2]), total - 1);
+    }
+    if (start >= total || (range[1] === '' && Number(range[2]) === 0)) return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
+  }
+  const partial = start !== 0 || end !== total - 1;
+  const body = bytes.slice(start, end + 1);
+  return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+    status: partial ? 206 : 200,
+    headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+  });
+}

package/src/fork.ts

@@ -3,7 +3,7 @@ import { captureHistory, historyEntries, historyLength, historyPrefix, readHisto
 // The kernel registers parent ownership before publishing the pointer. Lifecycle removal
 // refuses while a child depends on that storage; direct filesystem deletion bypasses it.
 import { dirname, join } from 'node:path';
-import { checkParent, withAncestryLock } from './ancestry.ts';
+import { checkParent, withHistoryLock } from './ancestry.ts';
 import { getActiveWorldStore } from './world-store.ts';
 import { position, wholeLog, writeBranchMeta , assertBatchBoundary } from './log.ts';
 import { twinResources } from './serve.ts';
@@ -41,7 +41,8 @@ export function forkTwin(opts: {
   view?: string;
   expectedGeneration?: string;
 }): ForkMeta {
-  return withAncestryLock(() => {
+  // under the new branch's history lock; capturing the base nests the base's inside it (child before ancestor)
+  return withHistoryLock(worldPaths(opts.service, opts.toRoot).dir, () => {
   // A BRANCH IS A POINTER (log.ts): the base root and the position in its logs, nothing copied.
   // The branch reads the base's parent view and branch log up to that position as its own
   // parent, and records only its own entries from there. The base keeps appending past the

package/src/git/history.ts

@@ -175,3 +175,22 @@ export function mergeText(base: string, ours: string, theirs: string): string |
   for (const h of edits) result.splice(h.start, h.end - h.start, ...h.lines);
   return result.map(line => JSON.parse(line) as string).join('');
 }
+
+/** The blob at a path in a commit (walking its trees segment by segment), or null when the commit, a directory on the
+ *  way or the file is not there. A host that serves a file at a revision (the Hugging Face Hub's `resolve`) reads it. */
+export async function blobAt(store: GitObjectStore, commit: string, path: string): Promise<{ sha: string; mode: string; bytes: Uint8Array } | null> {
+  const c = await store.read(commit);
+  if (!c || c.type !== 'commit') return null;
+  let tree = decodeCommit(c.payload).tree;
+  const parts = path.split('/').filter(Boolean);
+  for (const [i, name] of parts.entries()) {
+    const t = await store.read(tree);
+    if (!t || t.type !== 'tree') return null;
+    const e = decodeTree(t.payload).find((x) => x.name === name);
+    if (!e) return null;
+    if (i < parts.length - 1) { tree = e.sha; continue; }
+    const b = await store.read(e.sha);
+    return b && b.type === 'blob' ? { sha: e.sha, mode: e.mode, bytes: b.payload } : null;
+  }
+  return null;
+}

package/src/git/index.ts

@@ -4,3 +4,4 @@ export * from './pack.ts';
 export * from './refs.ts';
 export * from './smart-http.ts';
 export * from './history.ts';
+export * from './lfs.ts';