@agnt-sdk/simon-server 0.0.0-stage → 0.1.0

package/dist/config.js

@@ -0,0 +1,300 @@
+/**
+ * Configuration: every setting in one place, validated once. `loadConfig(env)` reads the environment (the
+ * table below, mirrored in README.md); `defineConfig(input)` builds the same thing from code. Any invalid
+ * value throws at startup, never at the first request that needs it.
+ *
+ *   SIMON_ORIGIN                  this server's origin, https://host[:port]                     required
+ *   SIMON_DEV                     1: development (http and local hosts, codes logged, a throwaway key)
+ *   SIMON_HOSTED_DOMAINS          domains whose names agents take at once, comma separated
+ *   SIMON_LEASE_DOMAIN            the domain addresses are leased on, for `register` with a key alone
+ *   SIMON_SERVER_KEY              the signing key: <alg>:<base64url 32-byte seed>               or ..._FILE
+ *   SIMON_SERVER_KEY_FILE         the signing key as a PKCS #8 PEM file
+ *   SIMON_NEXT_SERVER_KEY         a key announced for rotation: listed, not yet used           or ..._FILE
+ *   SIMON_NEXT_SERVER_KEY_FILE
+ *   SIMON_DB                      the sqlite file (default simon.sqlite; :memory: for none)
+ *   SIMON_PORT                    the port to listen on (default 8080)
+ *   SIMON_LISTEN_HOST             the address to listen on, 127.0.0.1 behind a tunnel (default every interface)
+ *   SIMON_CLIENT_IP_HEADER        a header proxies set to the client's address, x-forwarded-for or cf-connecting-ip:
+ *                                read only from this machine (a tunnel) and from SIMON_TRUSTED_PROXIES
+ *   SIMON_TRUSTED_PROXIES         networks a load balancer connects from, CIDR, comma separated (/8 or narrower)
+ *   SIMON_KEEP_ALIVE_TIMEOUT      seconds an idle connection is kept open (default 5; above a load balancer's own)
+ *   SIMON_TRUSTED_CLAIM_SERVERS   origins whose claims agents here are shown, comma separated
+ *   SIMON_DOH_RESOLVERS           two or more DNS-over-HTTPS JSON endpoints that must agree on every TXT answer
+ *   SIMON_DNS_SERVERS             DNS servers to ask instead of the system's, IP addresses, comma separated
+ *   SIMON_RATES                   overrides, name=count/seconds,...  (names: see DEFAULT_RATES)
+ *   SIMON_RATE_EXEMPT_NETWORKS    networks the per-client rates (request, register, codeClient, agentMiss) do not
+ *                                count, CIDR, comma separated (/8 or narrower): a hosting service's own, acting for
+ *                                many agents
+ *   SIMON_KEY_CHANGE_HOLD         seconds to hold a domain whose server keys changed (default 3600)
+ *   SIMON_RECOVERY_WAIT           seconds a code recovery waits while the agent holds a valid key (default 259200)
+ *   SIMON_MAX_CONNECTIONS         connections served at once (default 1024)
+ *   SIMON_RETENTION_DAYS          how long messages are kept (default 30, at least 7)
+ *   SIMON_SYNC_DAYS               how long sync shows what entered an agent's stream (default 7, at most the retention)
+ *   SIMON_DEV_RESOLVE             development only: domain=origin,... answered without DNS
+ *   SIMON_TRUSTED_NETWORKS        private networks outbound calls may reach, CIDR, comma separated (/8 or narrower)
+ *   SIMON_TLS_CERT_FILE           serve https with this PEM certificate chain                   with ..._KEY_FILE
+ *   SIMON_TLS_KEY_FILE            and this PEM private key
+ *   SIMON_PUBLIC_SUFFIX_LIST      a newer copy of the Public Suffix List to judge registrable domains by
+ *                                (default: the snapshot that ships with the server)
+ *   SIMON_RETIRED_AGENT_DOCUMENTS private or public: whether a retired address answers its signed retired document
+ *                                (public) or the same 404 as an unknown address (private, the default)
+ */
+import crypto, {} from 'node:crypto';
+import { isIP } from 'node:net';
+import fs from 'node:fs';
+import { ALGORITHM_NAMES, fromB64url, envelopeBesideBytes, MAX_ENVELOPE_EXTRAS_BYTES, MINIMUM_LIMITS, normalizeDomain, privateKeyFromSeed, serverOrigin, } from '@agnt-sdk/simon-protocol';
+import { parseNetwork } from "./net/ip.js";
+/** What each rate counts, and per what. */
+export const DEFAULT_RATES = {
+    /** Every request, per client IP (IPv6 by /64). */
+    request: { limit: 1200, seconds: 60 },
+    /** New registrations, per client IP. */
+    register: { limit: 20, seconds: 3600 },
+    /** Codes asked for, per address. */
+    code: { limit: 5, seconds: 3600 },
+    /** Codes asked for, per client IP, so no one client spends the allowance of every address. */
+    codeClient: { limit: 20, seconds: 3600 },
+    /** Messages sent, per agent. */
+    send: { limit: 600, seconds: 3600 },
+    /** Distinct recipient domains written to, per agent: what spam needs most. */
+    destinations: { limit: 100, seconds: 3600 },
+    /** Part uploads, per agent. */
+    upload: { limit: 200, seconds: 3600 },
+    /** Deliveries and signals past the signature check, per carrying server, repeats included. */
+    deliver: { limit: 6000, seconds: 3600 },
+    /**
+     * Resolutions and server documents fetched for deliveries, per client IP, counted before each is made:
+     * deliver makes them on behalf of anyone, before it knows who is asking.
+     */
+    lookup: { limit: 300, seconds: 3600 },
+    /**
+     * The same lookups, made before any signature verifies, per registrable domain of the name looked up (by the
+     * Public Suffix List's ICANN section), counted in the store so every process shares it (spec section 11.2).
+     */
+    lookupDomain: { limit: 3600, seconds: 3600 },
+    /**
+     * Resolutions made for a delivery or signal past the signature check, per carrying server, counted before
+     * each is made: its recipients' domains, and the identifiers its claims name.
+     */
+    carrierLookup: { limit: 3000, seconds: 3600 },
+    /** Envelope or message signatures that failed, per (client IP, claimed server), before any more work. */
+    badSignature: { limit: 20, seconds: 3600 },
+    /**
+     * Agent documents asked for addresses with no agent here, per client IP: what probing for addresses
+     * costs. Past it, the client is refused every agent document until the window ends, known address or
+     * not. Verifying a message asks for an agent that wrote it, so verification seldom counts.
+     */
+    agentMiss: { limit: 100, seconds: 3600 },
+};
+class ConfigError extends Error {
+    constructor(message) {
+        super(`Configuration: ${message}`);
+        this.name = 'ConfigError';
+    }
+}
+export function defineConfig(input) {
+    const dev = input.dev ?? false;
+    const origin = serverOrigin(input.origin, dev);
+    if (!origin)
+        throw new ConfigError(`origin ${input.origin} is not https://host[:port]${dev ? ' or http:' : ''}.`);
+    const domains = (list, what) => list.map(d => normalizeDomain(d) ?? fail(`${what}: ${d} is not a domain.`));
+    const origins = (list, what) => list.map(o => serverOrigin(o, dev) ?? fail(`${what}: ${o} is not a server origin.`));
+    const dohResolvers = input.dohResolvers ?? [];
+    if (dohResolvers.length === 1)
+        fail('dohResolvers: confirming takes two or more resolvers.');
+    for (const url of dohResolvers)
+        if (!/^https:\/\/[^/]+\//.test(url))
+            fail(`dohResolvers: ${url} is not https.`);
+    const dnsServers = input.dnsServers ?? [];
+    for (const ip of dnsServers)
+        if (!isIP(ip))
+            fail(`dnsServers: ${ip} is not an IP address.`);
+    const devResolve = input.devResolve ?? {};
+    if (Object.keys(devResolve).length && !dev)
+        fail('devResolve answers resolution without DNS: development only.');
+    for (const [d, o] of Object.entries(devResolve)) {
+        if (normalizeDomain(d) !== d || !serverOrigin(o, true))
+            fail(`devResolve: ${d}=${o} is not domain=origin.`);
+    }
+    const rates = { ...DEFAULT_RATES, ...input.rates };
+    for (const [name, r] of Object.entries(rates)) {
+        if (!(name in DEFAULT_RATES))
+            fail(`rates: no rate is named ${name}.`);
+        if (!(r.limit >= 1 && r.seconds >= 1) || !Number.isSafeInteger(r.limit) || !Number.isSafeInteger(r.seconds)) {
+            fail(`rates: ${name} needs a whole count and seconds, at least 1.`);
+        }
+    }
+    const networks = (list, what) => list.map(text => {
+        const network = parseNetwork(text);
+        return typeof network === 'string' ? fail(`${what}: ${network}`) : network;
+    });
+    const limits = { ...MINIMUM_LIMITS, ...input.limits };
+    for (const [name, n] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(n) || n < MINIMUM_LIMITS[name])
+            fail(`limits: ${name} is below the minimum.`);
+    }
+    const config = {
+        origin,
+        dev,
+        hostedDomains: domains(input.hostedDomains ?? [], 'hostedDomains'),
+        leaseDomain: input.leaseDomain ? domains([input.leaseDomain], 'leaseDomain')[0] : null,
+        serverKey: input.serverKey ?? (dev ? crypto.generateKeyPairSync('ed25519').privateKey : fail('serverKey is required.')),
+        nextServerKey: input.nextServerKey ?? null,
+        database: input.database ?? 'simon.sqlite',
+        port: whole(input.port ?? 8080, 'port', 0, 65535),
+        trustedClaimServers: origins(input.trustedClaimServers ?? [], 'trustedClaimServers'),
+        dohResolvers,
+        dnsServers,
+        rates,
+        rateExemptNetworks: networks(input.rateExemptNetworks ?? [], 'rateExemptNetworks'),
+        keyChangeHoldSeconds: whole(input.keyChangeHoldSeconds ?? 3600, 'keyChangeHoldSeconds', 0),
+        recoveryWaitSeconds: whole(input.recoveryWaitSeconds ?? 72 * 3600, 'recoveryWaitSeconds', 0),
+        maxConnections: whole(input.maxConnections ?? 1024, 'maxConnections', 1),
+        retentionDays: whole(input.retentionDays ?? 30, 'retentionDays', 7),
+        syncDays: whole(input.syncDays ?? 7, 'syncDays', 1),
+        limits,
+        fetchBytesPerHour: whole(input.fetchBytesPerHour ?? 256 * 1024 ** 2, 'fetchBytesPerHour', 0),
+        envelopeExtrasBytes: whole(input.envelopeExtrasBytes ?? envelopeBesideBytes(limits.recipients), 'envelopeExtrasBytes', MAX_ENVELOPE_EXTRAS_BYTES),
+        maxAgentKeys: whole(input.maxAgentKeys ?? 8, 'maxAgentKeys', 1, 32),
+        devResolve,
+        trustedNetworks: networks(input.trustedNetworks ?? [], 'trustedNetworks'),
+        tls: input.tls ?? null,
+        listenHost: input.listenHost
+            ? isIP(input.listenHost)
+                ? input.listenHost
+                : fail(`listenHost: ${input.listenHost} is not an IP address.`)
+            : null,
+        clientIpHeader: input.clientIpHeader
+            ? /^[a-z0-9-]+$/.test(input.clientIpHeader.toLowerCase())
+                ? input.clientIpHeader.toLowerCase()
+                : fail(`clientIpHeader: ${input.clientIpHeader} is not a header name.`)
+            : null,
+        trustedProxies: networks(input.trustedProxies ?? [], 'trustedProxies'),
+        keepAliveSeconds: whole(input.keepAliveSeconds ?? 5, 'keepAliveSeconds', 1),
+        publicSuffixFile: input.publicSuffixFile ?? null,
+        retiredAgentDocuments: retiredPolicy(input.retiredAgentDocuments ?? 'private', 'retiredAgentDocuments'),
+    };
+    if (config.tls && !config.origin.startsWith('https:'))
+        fail('tls is set, so the origin is https.');
+    if (config.trustedProxies.length && !config.clientIpHeader) {
+        fail('trustedProxies are trusted to set clientIpHeader, so it is set too.');
+    }
+    if (config.syncDays > config.retentionDays)
+        fail('syncDays is at most retentionDays: sync shows what is kept.');
+    if (config.leaseDomain && config.hostedDomains.includes(config.leaseDomain)) {
+        fail('leaseDomain is for leased names only; it cannot also be a hosted domain.');
+    }
+    return config;
+}
+/** The configuration the environment describes (see the table at the top of this file). */
+export function loadConfig(env = process.env) {
+    const list = (name) => (env[name] ?? '')
+        .split(',')
+        .map(s => s.trim())
+        .filter(Boolean);
+    const number = (name) => (env[name] === undefined ? undefined : Number(env[name]));
+    const dev = env.SIMON_DEV === '1';
+    if (env.SIMON_DEV !== undefined && env.SIMON_DEV !== '0' && !dev)
+        fail('SIMON_DEV is 1 or 0.');
+    if (!env.SIMON_ORIGIN)
+        fail('SIMON_ORIGIN is required.');
+    return defineConfig({
+        origin: env.SIMON_ORIGIN,
+        dev,
+        hostedDomains: list('SIMON_HOSTED_DOMAINS'),
+        leaseDomain: env.SIMON_LEASE_DOMAIN || null,
+        serverKey: readKey(env, 'SIMON_SERVER_KEY') ?? undefined,
+        nextServerKey: readKey(env, 'SIMON_NEXT_SERVER_KEY'),
+        database: env.SIMON_DB,
+        port: number('SIMON_PORT'),
+        trustedClaimServers: list('SIMON_TRUSTED_CLAIM_SERVERS'),
+        dohResolvers: list('SIMON_DOH_RESOLVERS'),
+        dnsServers: list('SIMON_DNS_SERVERS'),
+        rates: Object.fromEntries(list('SIMON_RATES').map(parseRate)),
+        rateExemptNetworks: list('SIMON_RATE_EXEMPT_NETWORKS'),
+        keyChangeHoldSeconds: number('SIMON_KEY_CHANGE_HOLD'),
+        recoveryWaitSeconds: number('SIMON_RECOVERY_WAIT'),
+        maxConnections: number('SIMON_MAX_CONNECTIONS'),
+        retentionDays: number('SIMON_RETENTION_DAYS'),
+        syncDays: number('SIMON_SYNC_DAYS'),
+        devResolve: Object.fromEntries(list('SIMON_DEV_RESOLVE').map(pair => pair.split('=', 2))),
+        trustedNetworks: list('SIMON_TRUSTED_NETWORKS'),
+        tls: readTls(env),
+        listenHost: env.SIMON_LISTEN_HOST || null,
+        clientIpHeader: env.SIMON_CLIENT_IP_HEADER || null,
+        trustedProxies: list('SIMON_TRUSTED_PROXIES'),
+        keepAliveSeconds: number('SIMON_KEEP_ALIVE_TIMEOUT'),
+        publicSuffixFile: env.SIMON_PUBLIC_SUFFIX_LIST || null,
+        retiredAgentDocuments: env.SIMON_RETIRED_AGENT_DOCUMENTS === undefined
+            ? undefined
+            : retiredPolicy(env.SIMON_RETIRED_AGENT_DOCUMENTS, 'SIMON_RETIRED_AGENT_DOCUMENTS'),
+    });
+}
+/** The certificate chain and key from SIMON_TLS_CERT_FILE and SIMON_TLS_KEY_FILE: both, or neither. */
+function readTls(env) {
+    const certFile = env.SIMON_TLS_CERT_FILE;
+    const keyFile = env.SIMON_TLS_KEY_FILE;
+    if (!certFile && !keyFile)
+        return null;
+    if (!certFile || !keyFile)
+        fail('set SIMON_TLS_CERT_FILE and SIMON_TLS_KEY_FILE together.');
+    const read = (file, name) => {
+        try {
+            return fs.readFileSync(file, 'utf8');
+        }
+        catch (e) {
+            return fail(`${name}: ${e.message}`);
+        }
+    };
+    const tls = { cert: read(certFile, 'SIMON_TLS_CERT_FILE'), key: read(keyFile, 'SIMON_TLS_KEY_FILE') };
+    try {
+        crypto.createPrivateKey(tls.key);
+        new crypto.X509Certificate(tls.cert);
+    }
+    catch (e) {
+        fail(`SIMON_TLS_CERT_FILE and SIMON_TLS_KEY_FILE are a PEM certificate and its key: ${e.message}`);
+    }
+    return tls;
+}
+/** `<alg>:<base64url seed>` from `NAME`, or a PKCS #8 PEM from `NAME_FILE`; never both. */
+function readKey(env, name) {
+    const inline = env[name];
+    const file = env[`${name}_FILE`];
+    if (inline && file)
+        fail(`set ${name} or ${name}_FILE, not both.`);
+    if (file) {
+        try {
+            return crypto.createPrivateKey(fs.readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            return fail(`${name}_FILE: ${e.message}`);
+        }
+    }
+    if (!inline)
+        return null;
+    const m = /^([a-z0-9-]+):(.+)$/.exec(inline);
+    const seed = m && fromB64url(m[2]);
+    if (!m || !ALGORITHM_NAMES.includes(m[1]) || seed?.length !== 32) {
+        fail(`${name} is <alg>:<base64url of a 32-byte seed>, the alg one of ${ALGORITHM_NAMES.join(', ')}.`);
+    }
+    return privateKeyFromSeed(m[1], seed);
+}
+function parseRate(entry) {
+    const m = /^([a-zA-Z]+)=(\d+)\/(\d+)$/.exec(entry);
+    if (!m)
+        fail(`SIMON_RATES: ${entry} is not name=count/seconds.`);
+    return [m[1], { limit: Number(m[2]), seconds: Number(m[3]) }];
+}
+function retiredPolicy(value, name) {
+    if (value !== 'public' && value !== 'private')
+        fail(`${name} is private or public.`);
+    return value;
+}
+function whole(n, name, min, max = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(n) || n < min || n > max)
+        fail(`${name} must be a whole number from ${min} to ${max}.`);
+    return n;
+}
+function fail(message) {
+    throw new ConfigError(message);
+}

package/dist/context.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What every part of the core shares: built once by `createServer`, passed to each module.
+ */
+import type { Config } from './config.ts';
+import type { Hooks, Log } from './extensions.ts';
+import type { Http } from './net/fetch.ts';
+import type { RateLimiter } from './rate.ts';
+import type { Resolver } from './resolver.ts';
+import type { Store } from './store/store.ts';
+import type { Changes } from './sync.ts';
+/**
+ * What this server sends an address's mailbox (CLIENT.md register and "Recommended host practice"): the
+ * code that binds the address to a key; the news of a recovery waiting until `completesAt`, with the code
+ * that cancels it; in place of a code asked for while one waits, the news that it is pending, with another
+ * code that cancels it; and the news that a key of the agent cancelled one.
+ */
+export type MailboxNote = {
+    type: 'code';
+    code: string;
+} | {
+    type: 'recovery';
+    key: string;
+    completesAt: string;
+    cancelCode: string;
+} | {
+    type: 'recoveryPending';
+    key: string;
+    completesAt: string;
+    cancelCode: string;
+} | {
+    type: 'recoveryCancelled';
+};
+/** Sends a note to an address, by whatever channel reaches its mailbox. */
+export type MailboxSender = (address: string, note: MailboxNote) => Promise<void>;
+export interface Context {
+    config: Config;
+    store: Store;
+    now: () => Date;
+    log: Log;
+    http: Http;
+    resolver: Resolver;
+    rate: RateLimiter;
+    hooks: Hooks;
+    /** Null when no sender is configured: the code flow is then unavailable. */
+    mailbox: MailboxSender | null;
+    /** Syncs held open, waiting for news of their agents. */
+    changes: Changes;
+    /** Ask the worker to run soon: work is waiting. */
+    wake(): void;
+    /**
+     * Start work the answer does not wait for: it begins at once and runs on beside the answer, tracked so the
+     * server can wait for it on close.
+     */
+    defer(task: () => Promise<unknown>): void;
+}
+export declare const iso: (d: Date) => string;
+export declare const later: (now: Date, ms: number) => string;

package/dist/context.js

@@ -0,0 +1,2 @@
+export const iso = (d) => d.toISOString();
+export const later = (now, ms) => new Date(now.getTime() + ms).toISOString();

package/dist/continuity.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Key continuity, by possession (spec section 11.1). For each domain this server remembers two sets of its
+ * server's keys:
+ *
+ *   listed   the keys of the last document it trusted, which a newly read document must overlap;
+ *   signers  the keys it trusts to sign: those of a document under which a trusted signer signed afresh.
+ *
+ * Listing a key proves nothing, since anyone can copy a public key into a document of their own. So a
+ * document that lists a trusted key still has to sign with one: a signature by any other key is held, and
+ * the new keys are trusted only once the change is confirmed after the hold. An honest rotation is never
+ * held, because the server lists its new key beside the old one and keeps signing with the old one, which
+ * vouches for the new one, until the change completes.
+ *
+ * A hold names the server and keys it holds. Once it is over, the change is confirmed from fresh answers
+ * (`confirm`) before it is trusted; a domain whose server goes back to keys already trusted is not held.
+ */
+import { type Context } from './context.ts';
+export interface ContinuityDeps extends Pick<Context, 'store' | 'now' | 'log'> {
+    holdSeconds: number;
+    /** Whether fresh answers still name this server with exactly these keys. */
+    confirm(domain: string, server: string, keys: string[]): Promise<boolean>;
+}
+export declare class Continuity {
+    #private;
+    constructor(deps: ContinuityDeps);
+    /** A document read for a domain's server: trusted when it lists a key trusted before, else held (503). */
+    listed(domain: string, server: string, keys: string[]): Promise<void>;
+    /** A signature by `key`, under a document listing `keys`: trusted when `key` is a trusted signer, else held. */
+    signed(domain: string, server: string, key: string, keys: string[]): Promise<void>;
+    /**
+     * A trusted signer signed afresh (not a repeat) under a document listing `keys`: its holder vouches for
+     * every key the document lists, so the next key of an honest rotation is trusted before it is used.
+     */
+    vouch(domain: string, keys: string[]): Promise<void>;
+}

package/dist/continuity.js

@@ -0,0 +1,74 @@
+/**
+ * Key continuity, by possession (spec section 11.1). For each domain this server remembers two sets of its
+ * server's keys:
+ *
+ *   listed   the keys of the last document it trusted, which a newly read document must overlap;
+ *   signers  the keys it trusts to sign: those of a document under which a trusted signer signed afresh.
+ *
+ * Listing a key proves nothing, since anyone can copy a public key into a document of their own. So a
+ * document that lists a trusted key still has to sign with one: a signature by any other key is held, and
+ * the new keys are trusted only once the change is confirmed after the hold. An honest rotation is never
+ * held, because the server lists its new key beside the old one and keeps signing with the old one, which
+ * vouches for the new one, until the change completes.
+ *
+ * A hold names the server and keys it holds. Once it is over, the change is confirmed from fresh answers
+ * (`confirm`) before it is trusted; a domain whose server goes back to keys already trusted is not held.
+ */
+import { later } from "./context.js";
+import { unavailable } from "./errors.js";
+const SCOPE = 'continuity';
+const sorted = (keys) => [...keys].sort();
+const same = (a, b) => sorted(a).join() === sorted(b).join();
+export class Continuity {
+    #d;
+    constructor(deps) {
+        this.#d = deps;
+    }
+    /** A document read for a domain's server: trusted when it lists a key trusted before, else held (503). */
+    listed(domain, server, keys) {
+        return this.#check(domain, server, keys, s => keys.some(k => s.listed.includes(k)));
+    }
+    /** A signature by `key`, under a document listing `keys`: trusted when `key` is a trusted signer, else held. */
+    signed(domain, server, key, keys) {
+        return this.#check(domain, server, keys, s => s.signers.includes(key));
+    }
+    /**
+     * A trusted signer signed afresh (not a repeat) under a document listing `keys`: its holder vouches for
+     * every key the document lists, so the next key of an honest rotation is trusted before it is used.
+     */
+    async vouch(domain, keys) {
+        const s = await this.#state(domain);
+        if (s && !s.held && !same(s.signers, keys))
+            await this.#save(domain, { listed: keys, signers: keys });
+    }
+    async #check(domain, server, keys, trusted) {
+        const s = await this.#state(domain);
+        if (!s)
+            return this.#save(domain, { listed: keys, signers: keys });
+        const held = s.held && s.held.server === server && same(s.held.keys, keys) ? s.held : null;
+        if (held) {
+            const now = this.#d.now();
+            if (now < new Date(held.until))
+                throw this.#holding(domain, held.until);
+            if (await this.#d.confirm(domain, server, keys)) {
+                this.#d.log('warn', 'domain server keys replaced after hold', { domain, server });
+                return this.#save(domain, { listed: keys, signers: keys });
+            }
+        }
+        else if (trusted(s)) {
+            if (s.held || !same(s.listed, keys))
+                await this.#save(domain, { listed: keys, signers: s.signers });
+            return;
+        }
+        const until = later(this.#d.now(), this.#d.holdSeconds * 1000);
+        this.#d.log('warn', 'domain server keys changed; holding', { domain, server, until });
+        await this.#save(domain, { listed: s.listed, signers: s.signers, held: { server, keys, until } });
+        throw this.#holding(domain, until);
+    }
+    #state = (domain) => this.#d.store.value(SCOPE, domain, this.#d.now().toISOString());
+    #save = (domain, s) => this.#d.store.setValue(SCOPE, domain, s, null);
+    #holding(domain, until) {
+        const seconds = Math.max(1, Math.ceil((Date.parse(until) - this.#d.now().getTime()) / 1000));
+        return unavailable(`${domain}'s server keys changed; holding it before trusting the new ones.`, seconds);
+    }
+}

package/dist/deliver.d.ts

@@ -0,0 +1,22 @@
+import { type Context } from './context.ts';
+import { type Reply, type Request } from './http.ts';
+import { type Payer } from './resolver.ts';
+export declare function deliver(ctx: Context, req: Request): Promise<Reply>;
+/** How long step 8 may go on starting lookups of recipients' domains; a lookup underway ends by its own deadline. */
+export declare const RECIPIENT_LOOKUPS_MS = 20000;
+/** A domain is resolved again without the cache, before a 403 at step 7 or a 400 at step 8, this often at most. */
+export declare const RERESOLVE_EVERY_MS = 60000;
+/**
+ * Resolve a domain again without the cache with `lookup`, at most once a minute for one domain across processes
+ * (a store value only one caller takes), or answer null without looking when that minute's re-resolution is
+ * taken. A call refused before it made any lookup (the payer out of room or rate) gives the minute back, so
+ * a forger out of budget cannot use it up for everyone; one refused after a lookup was made keeps it.
+ */
+export declare function reresolve<T>(ctx: Context, domain: string, lookup: () => Promise<T>): Promise<T | null>;
+/**
+ * Step 8 for deliver and signal: whether each address's domain is served here, hosted or leased on, or
+ * resolving here. The domains needing a lookup are resolved side by side, as many at once as the
+ * payer's free share (at most MAX_LOOKUPS_PER_CARRIER), each paid for by `payer`; once RECIPIENT_LOOKUPS_MS
+ * have passed no more are started, and the answer is 503.
+ */
+export declare function servedDomains(ctx: Context, addresses: readonly string[], payer: Payer): Promise<(d: string) => boolean>;