@volter/world-core 2.0.37 → 3.0.0

package/dist/src/derived.js

@@ -1,11 +1,54 @@
-// THE DERIVED DISPATCH — the generated wire's router (docs/contributing/architecture.md, "The derived
-// pack"). A derived pack's surface (`src/generated/surface.gen.json`, written by scripts/derive-pack.ts)
-// names every operation the vendor publishes. This matches a request to one of them and hands it to its
-// owner: the pack's semantics handler for that operationId when there is one, otherwise the pack's
-// existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
-// as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
-// move is measured by. Workerd-clean: no fs, no clock, nothing at import.
 import { runWithRequestTrace } from "./trace-context.js";
+/**
+ * A request's body as text, read once per request: the dispatch reads it and tags the request with it, and every clone
+ * made from a tagged request carries the tag, so the malformed-JSON guard, the idempotency signature, the handler's
+ * context and the parameters all take the one string (a publish's body is megabytes, and each read made a copy).
+ */
+const BODY_TEXT = Symbol('volter.bodyText');
+function tagBody(request, text, key = {}) {
+    const tagged = request;
+    tagged[BODY_TEXT] = text;
+    BODY_PARSE_KEY.set(request, key);
+    const clone = request.clone.bind(request);
+    tagged.clone = () => tagBody(clone(), text, key);
+    return request;
+}
+export async function bodyTextOf(request) {
+    const held = request[BODY_TEXT];
+    return held !== undefined ? held : request.text();
+}
+/** The body parsed by the malformed-JSON guard, which only checks it: handed once to the handler's context (that parse
+ *  would be the same), and never shared further, so no reader sees another's changes. */
+const BODY_PARSED = new WeakMap();
+/** The body's text, as JSON, or undefined when it is not JSON; the parse is kept for the first taker. */
+export async function checkJsonBody(request) {
+    const text = await bodyTextOf(request);
+    if (!text)
+        return true;
+    // a body labelled otherwise and not shaped as JSON is the form it is labelled (an OAuth token request), not bad JSON
+    if (!(request.headers.get('content-type') ?? '').includes('json') && !/^\s*[[{]/.test(text))
+        return true;
+    try {
+        const value = JSON.parse(text);
+        const tag = request[BODY_TEXT] !== undefined ? BODY_PARSE_KEY.get(request) : undefined;
+        if (tag)
+            BODY_PARSED.set(tag, { value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The guard's parse of this request's body, taken once (a clone of a tagged request shares its key). */
+export function takeParsedBody(request) {
+    const tag = BODY_PARSE_KEY.get(request);
+    const held = tag ? BODY_PARSED.get(tag) : undefined;
+    if (tag && held)
+        BODY_PARSED.delete(tag);
+    return held;
+}
+/** One key per request as the dispatch received it, shared by every clone made from it. */
+const BODY_PARSE_KEY = new WeakMap();
 class Unmodeled extends Error {
 }
 function compile(operation, basePath, spanning) {
@@ -32,7 +75,9 @@ function compile(operation, basePath, spanning) {
         }).join('');
     })
         .join('/');
-    return { operation, pattern: new RegExp(`^${body}/?$`), names, literals };
+    // a path the spec writes with its trailing slash (Django's `/persons/`) is the same path without it, as a router that
+    // takes both answers it (PostHog's `trailing_slash = r"/?"`)
+    return { operation, pattern: new RegExp(`^${body.replace(/\/$/, '')}/?$`), names, literals };
 }
 const compiled = new WeakMap(); // cache: compiled routes per surface; a surface is immutable generated data
 /** Routes per method, most literal segments first, so `/v1/customers/search` wins over `/v1/customers/{customer}`. */
@@ -78,6 +123,8 @@ export function matchOperation(routes, method, pathname, query, headers) {
     }
     return undefined;
 }
+/** The header the kernel carries a path prefix's named groups in, from routing to the call (never a client's). */
+export const PREFIX_PARAMS_HEADER = 'x-volter-path-prefix-params';
 export function createDerivedFetch(options) {
     const handlers = options.handlers ?? {};
     const known = new Set(options.surface.operations.map((o) => o.id));
@@ -95,7 +142,12 @@ export function createDerivedFetch(options) {
             : matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
         if (!matched)
             return fallback(request, undefined, 'no operation at this path');
-        const call = { request, operation: matched.operation, params: matched.params };
+        // the body read once, as text, for everything the dispatch does with it (bodyTextOf)
+        if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart'))
+            tagBody(request, await request.clone().text());
+        // the path prefix's named groups (pack-fetch.ts, `pathPrefix`) are the call's parameters too
+        const prefixed = request.headers.get(PREFIX_PARAMS_HEADER);
+        const call = { request, operation: matched.operation, params: prefixed ? { ...JSON.parse(prefixed), ...matched.params } : matched.params };
         const around = options.around ?? ((_c, next) => next());
         const handler = handlers[matched.operation.id];
         if (handler)

package/dist/src/emit.js

@@ -6,8 +6,7 @@
 // `TwinEmitter` and registered on its `TwinPack.emitter` (same argument as `browserRouting`:
 // vendor knowledge in the descriptor, kernel stays vendor-agnostic).
 //
-// The operator surface is the PACK's bin (`world-stripe emit …`), exactly like the mirror
-// UIs — the kernel never imports packs, so `volter-twin emit <service>` only works when a
+// The operator surface is the PACK's bin (`world-stripe emit …`) — the kernel never imports packs, so `volter-twin emit <service>` only works when a
 // consumer registered the pack in-process, and otherwise fails loudly pointing at the
 // vendor bin. Unlike the twin's own background emission on state changes (fire-and-forget,
 // vendor-faithful), an explicit DELIVER is an operator asking for exactly this delivery, so

package/dist/src/events.d.ts

@@ -0,0 +1,206 @@
+/** 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;
+};
+/** 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>;
+/** 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 declare function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq?: number): Record<string, string>;
+/** Every scheme's headers for one delivery, merged. */
+export declare function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq?: number): Record<string, string>;
+/** 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 declare function verifyEvent(scheme: EventScheme, secret: string, body: string, headers: Record<string, string>, opts?: {
+    tolerance?: number;
+    now?: number;
+}): boolean;
+/** 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 declare function fillEnvelope(template: unknown, values: Record<string, unknown>, endpoint?: Record<string, unknown>): unknown;
+/** The event types a write's operation sends: `types`, else the vendor's enumerated types (`known`). */
+export declare function eventTypesOf(decl: Pick<EventsDecl, 'types' | 'known'>, operation: string): string[];
+/** The event type a write's operation sends, if any: its first under `types`, else the vendor's enumerated types
+ *  (`known`). */
+export declare function eventTypeOf(decl: Pick<EventsDecl, 'types' | 'known'>, operation: string): string | 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 declare function takesEvent(list: unknown, type: string): boolean;
+/** 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 declare function deliverToApplication(url: string, init: RequestInit): Promise<number>;
+/** 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 declare function askApplication(url: string, init: RequestInit, within: number): Promise<ApplicationAnswer>;
+/** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
+ *  that takes it, and recorded. */
+export declare function deliverEvents(service: string, decl: EventsDecl, write: EventWrite, data: (type: string) => Promise<Record<string, unknown>>, transport?: EventTransport, values?: (type: string) => Promise<Record<string, unknown>>, onAnswer?: (answer: DeliveryAnswer) => Promise<void>): Promise<EventDelivery[]>;

package/dist/src/events.js

@@ -0,0 +1,341 @@
+// 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.js";
+import { equalSecrets as same } from "./signing.js";
+import { deliveryTraceHeaders } from "./trace-context.js";
+/** 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, match, filled) {
+    if (match === undefined)
+        return true;
+    const one = (m) => 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);
+}
+const digest = (s) => 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, secret) => 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, secret, body, seconds, url, seq = 0) {
+    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, secret, body) => 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, seconds, body) => 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, secret, body, seconds, url, seq = 0) {
+    return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme) => 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, secret, body, headers, opts = {}) {
+    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) => 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('='));
+        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, values, endpoint) {
+    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 = {};
+        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) => JSON.stringify(template ?? null).includes('"$endpoint.');
+/** A row's field by a dotted path (`config.url`). */
+function at(row, path) {
+    let v = row;
+    for (const key of path.split('.'))
+        v = v && typeof v === 'object' ? v[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, values, endpoint) {
+    const out = {};
+    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();
+/** The event types a write's operation sends: `types`, else the vendor's enumerated types (`known`). */
+export function eventTypesOf(decl, operation) {
+    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, operation) {
+    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, type) {
+    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) {
+    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 = async (url, body, headers) => {
+    const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
+        import('../app-route.cjs'),
+        import('../network-policy.cjs'),
+    ]);
+    if (!appDestination(url) && worldEgressRefusal(url) !== null)
+        return 0;
+    try {
+        return (await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body })).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, init) {
+    const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
+        import('../app-route.cjs'),
+        import('../network-policy.cjs'),
+    ]);
+    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;
+    }
+}
+/** 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, init, within) {
+    const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
+        import('../app-route.cjs'),
+        import('../network-policy.cjs'),
+    ]);
+    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, decl, write, data, transport = worldTransport, values, onAnswer) {
+    if (write.storedType === decl.store)
+        return [];
+    const sent = [];
+    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, decl, write, data, transport, values, type, onAnswer) {
+    const all = twinResources(service, write.root);
+    const kinds = Array.isArray(decl.endpoints) ? decl.endpoints : [decl.endpoints];
+    // an endpoint's row with its joined rows under their names (`app.hook_url` reads the installation's App)
+    const joined = (kind, r) => {
+        if (!kind.joins)
+            return r;
+        const out = { ...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))
+        .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 = {
+        $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, 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 = [];
+    const to = [];
+    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) => {
+        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;
+}