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

package/dist/resolver.js

@@ -0,0 +1,386 @@
+/**
+ * Finding other servers and their keys: resolution (spec section 3), server and agent documents (section 4),
+ * and key continuity (section 11.1, continuity.ts).
+ *
+ *   - **Caching.** Within the spec's bounds (`resolutionCacheMs`): a `server` answer for ten minutes, the
+ *     TTL assumed since c-ares does not report one; `not_found` for ten minutes; `temporary` for a minute,
+ *     so a failing domain costs one lookup a minute, however often it is asked for. Documents are cached
+ *     ten minutes, and a server document that failed for now one minute.
+ *   - **Refetching.** A signature that fails against a cached document is checked again against a fresh
+ *     one, though a server document is fetched at most once a minute (anyone can name any server).
+ *   - **Bounded outbound work.** Concurrent asks for the same answer share one lookup, and every lookup is
+ *     paid for by whoever caused it (`Payer`): an unauthenticated client, counted before each lookup; a
+ *     carrier whose signature verified, for the work its delivery asks (its recipients' domains, its
+ *     claims, its author's document); or this server itself, for an agent's send and its outbox. Each runs
+ *     in its own bounded pool, and a carrier has at most MAX_LOOKUPS_PER_CARRIER of its pool (more are
+ *     refused for now, 503), so nothing another server or an unauthenticated client asks for can starve
+ *     the server's own sending (spec section 11.2). The server's own work for an agent here, its send's and
+ *     its messages' deliveries, has at most MAX_LOOKUPS_PER_AGENT of the own pool (more are refused for now,
+ *     and a delivery retried), so no agent's recipients, slow as they may be, hold up another's.
+ *   - **The bound before a signature verifies** (spec section 11.2). Every lookup an unauthenticated caller
+ *     causes counts against its client network (`lookup`, in this process) and against the registrable
+ *     domain of the name looked up (`lookupDomain`, by the Public Suffix List's ICANN section, in the store,
+ *     so it holds for every process sharing it). Only lookups made count: a cache hit, or a lookup another
+ *     ask already has underway, costs nothing. Past either bound the lookup is `429`, and it is not counted.
+ */
+import { addressSegment, DOCUMENT_CACHE_MS, MAX_DOCUMENT_BYTES, readAgentDocument, readServerDocument, resolutionCacheMs, resolveDomain, SERVER_DOCUMENT_REFETCH_MS, TEMPORARY_CACHE_MS, } from '@agnt-sdk/simon-protocol';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Continuity } from "./continuity.js";
+import { rateLimited, unavailable } from "./errors.js";
+import { registrableDomain, shippedPublicSuffixes } from "./net/psl.js";
+import { Unreachable } from "./net/fetch.js";
+/** The TTL taken for a `server` answer, whose DNS TTL or HTTP freshness this resolver does not read. */
+const SERVER_TTL_MS = 10 * 60_000;
+/** Lookups at once: for unauthenticated callers, for carriers whose signature verified, and for this server's own work. */
+const MAX_LOOKUPS = { charged: 24, carrier: 32, own: 16 };
+/** A carrier's lookups at once, of the carrier pool. */
+export const MAX_LOOKUPS_PER_CARRIER = 8;
+/**
+ * The lookups at once of every carrier whose deliveries come from one network (`networkKey`): carriers cost
+ * nothing to make up, networks do. Twice a carrier's share, so carriers behind one egress network, the
+ * tenants of a host behind one NAT for instance, do not share one carrier's share, while no one network
+ * holds more than half the carrier pool.
+ */
+export const MAX_LOOKUPS_PER_NETWORK = 2 * MAX_LOOKUPS_PER_CARRIER;
+/**
+ * An agent here's lookups at once, of the own pool: its send's and its messages' deliveries'. Not shared by
+ * the agents of a domain, as every agent of a hosted domain is on it.
+ */
+export const MAX_LOOKUPS_PER_AGENT = 4;
+const MAX_CACHED = 10_000;
+const FETCH_TIMEOUT_MS = 10_000;
+/** A small TTL cache that forgets its oldest entries first. */
+class Cache {
+    #entries = new Map();
+    get(key, now) {
+        const hit = this.#entries.get(key);
+        if (!hit || hit.until <= now)
+            return null;
+        return hit;
+    }
+    set(key, value, now, ttl) {
+        this.#entries.delete(key);
+        if (ttl <= 0)
+            return;
+        this.#entries.set(key, { value, until: now + ttl, at: now });
+        if (this.#entries.size > MAX_CACHED)
+            this.#entries.delete(this.#entries.keys().next().value);
+    }
+}
+/** The pool a payer's lookups run in. */
+const poolOf = (payer) => payer === undefined || (typeof payer === 'object' && 'agent' in payer)
+    ? 'own'
+    : typeof payer === 'function'
+        ? 'charged'
+        : 'carrier';
+const REFUSED = Symbol('refused');
+/** Mark an error as a lookup refused before it was made: for room, or by its payer's rate or domain bound. */
+function refused(e) {
+    if (typeof e === 'object' && e !== null)
+        Object.defineProperty(e, REFUSED, { value: true });
+    return e;
+}
+/** Whether an error is a lookup refused before it was made, so nothing was looked up. */
+export const isRefusal = (e) => typeof e === 'object' && e !== null && REFUSED in e;
+/** Store scope of the per-registrable-domain counts of lookups made before a signature verifies. */
+const DOMAIN_LOOKUPS = 'lookup-domain';
+/** A failure that may pass, as a cached document lookup remembers it. */
+const TEMPORARY = 'temporary';
+export class Resolver {
+    #d;
+    #domains = new Cache();
+    #servers = new Cache();
+    #agents = new Cache();
+    #pending = new Map();
+    #continuity;
+    #lookups = { charged: 0, carrier: 0, own: 0 };
+    /** The carrier pool's lookups underway, per carrier and per network. */
+    #shares = new Map();
+    /** The tally of the `tallied` call underway, which lookups made (or joined) within it mark. */
+    #tally = new AsyncLocalStorage();
+    constructor(deps) {
+        this.#d = deps;
+        this.#continuity = new Continuity({
+            store: deps.store,
+            now: deps.now,
+            log: deps.log,
+            holdSeconds: deps.config.keyChangeHoldSeconds,
+            // Confirming a held change is work for the server that changed, in its own share of the carrier pool,
+            // counted against its carrierLookup rate as its other lookups are.
+            confirm: async (domain, server, keys) => {
+                const payer = { carrier: server, charge: () => deps.chargeCarrier?.(server) };
+                const again = await this.resolve(domain, { fresh: true, charge: payer });
+                if (again.outcome !== 'server' || again.server !== server)
+                    return false;
+                const doc = await this.serverDocument(server, { force: true, charge: payer });
+                return (!!doc &&
+                    doc.keys
+                        .map(k => k.key)
+                        .sort()
+                        .join() === [...keys].sort().join());
+            },
+        });
+    }
+    get #self() {
+        return this.#d.config.origin;
+    }
+    /** Resolution of a domain, from the cache unless `fresh`. */
+    async resolve(domain, opts = {}) {
+        const now = this.#d.now().getTime();
+        const hit = opts.fresh ? null : this.#domains.get(domain, now);
+        if (hit)
+            return hit.value;
+        const override = this.#d.config.devResolve[domain];
+        if (override)
+            return { outcome: 'server', server: override.replace(/\/$/, ''), via: 'dns' };
+        return this.#once(`resolve ${domain}`, opts.charge, domain, async () => {
+            const r = await resolveDomain(domain, { txt: name => this.#d.dns.txt(name), get: url => this.#wellKnown(url) }, { allowHttp: this.#d.config.dev });
+            this.#domains.set(domain, r, this.#d.now().getTime(), resolutionCacheMs(r, SERVER_TTL_MS));
+            return r;
+        });
+    }
+    /** Whether a resolution of `domain` is cached now, so a fresh one might answer otherwise. */
+    isCached(domain) {
+        return this.#domains.get(domain, this.#d.now().getTime()) !== null;
+    }
+    /** Whether a domain names this server now. Throws 503 when that cannot be known. */
+    async servesHere(domain, charge, fresh = false) {
+        const r = await this.resolve(domain, { charge, fresh });
+        if (r.outcome === 'temporary')
+            throw unavailable(`Could not resolve ${domain} just now.`);
+        return r.outcome === 'server' && r.server === this.#self;
+    }
+    /**
+     * The server a domain names and its document, trusted under key continuity's listing check. `document`
+     * is null when the server serves no readable one. Throws 503 when resolution or the document failed for
+     * now, or while a key change is held.
+     */
+    async peer(domain, charge, opts = {}) {
+        const r = await this.resolve(domain, { charge, fresh: opts.fresh });
+        if (r.outcome === 'temporary')
+            throw unavailable(`Could not resolve ${domain} just now.`);
+        if (r.outcome !== 'server')
+            return r;
+        const document = await this.serverDocument(r.server, { charge, refresh: opts.fresh });
+        if (document && r.server !== this.#self)
+            await this.#continuity.listed(domain, r.server, keysOf(document));
+        return { outcome: 'server', server: r.server, document };
+    }
+    /** A signature by `key` from a domain's server, under `document`: held unless `key` is trusted to sign. */
+    trustSigner(domain, server, key, document) {
+        return this.#continuity.signed(domain, server, key, keysOf(document));
+    }
+    /** A trusted signer signed afresh under `document`, vouching for each key it lists. */
+    vouch(domain, document) {
+        return this.#continuity.vouch(domain, keysOf(document));
+    }
+    /**
+     * A server's document, or null when it serves none that is readable. `refresh` fetches again when the
+     * cached one is a minute old or more; `force` always does. Throws 503 on a failure that may pass.
+     */
+    async serverDocument(origin, opts = {}) {
+        if (origin === this.#self)
+            return this.#d.ownDocument();
+        const now = this.#d.now().getTime();
+        const hit = this.#servers.get(origin, now);
+        const stale = hit && (opts.force || (opts.refresh && now - hit.at >= SERVER_DOCUMENT_REFETCH_MS));
+        const doc = hit && !stale
+            ? hit.value
+            : await this.#once(`server ${origin}`, opts.charge, new URL(origin).hostname, async () => {
+                let fetched;
+                try {
+                    const res = await this.#getDocument(`${origin}/simon/server`);
+                    fetched = res && readServerDocument(res.body, origin, this.#d.now());
+                }
+                catch {
+                    fetched = TEMPORARY;
+                }
+                // A failure for now does not hide a document already known, but is remembered for a minute.
+                const ttl = fetched === TEMPORARY ? TEMPORARY_CACHE_MS : DOCUMENT_CACHE_MS;
+                if (fetched !== TEMPORARY || !hit)
+                    this.#servers.set(origin, fetched, this.#d.now().getTime(), ttl);
+                return fetched;
+            });
+        if (doc === TEMPORARY)
+            throw unavailable(`Could not fetch the server document of ${origin} just now.`);
+        return doc;
+    }
+    /**
+     * An agent's kind and keys: from the store for an agent here, otherwise from its signed agent document
+     * on `server`. Null when there is no readable document. `refresh` skips the cache (a signature failed).
+     * `charge` names who pays for the fetch, as `resolve`'s does.
+     */
+    async agentKeys(address, server, refresh = false, charge) {
+        if (server === this.#self)
+            return this.#d.localAgent(address);
+        const now = this.#d.now();
+        const key = `${server} ${address}`;
+        // A cached answer that there is no document is kept against an unauthenticated caller's refetch too, as
+        // section 4 allows, so naming an agent that does not exist costs one lookup in ten minutes, not one each.
+        const hit = this.#agents.get(key, now.getTime());
+        if (hit && (!refresh || (hit.value === null && typeof charge === 'function')))
+            return hit.value;
+        const res = await this.#once(`agent ${key}`, charge, new URL(server).hostname, () => this.#getDocument(`${server}/simon/agents/${addressSegment(address)}`));
+        let agent = null;
+        if (res) {
+            const read = async (opts = {}) => {
+                // The server document is fetched for whoever pays for the agent's, never on this server's own account.
+                const doc = await this.serverDocument(server, { ...opts, charge });
+                return doc && readAgentDocument(res.body, address, doc.keys, now);
+            };
+            // A document signed by a key the cached server document lacks: that document may be stale.
+            agent = (await read()) ?? (await read({ refresh: true }));
+        }
+        this.#agents.set(key, agent, now.getTime(), DOCUMENT_CACHE_MS);
+        return agent;
+    }
+    /** How many more lookups a payer may start now: its pool's room, and for a carrier, its shares'. */
+    room(payer) {
+        const pool = poolOf(payer);
+        const shares = this.#sharesOf(payer).map(([k, max]) => max - (this.#shares.get(k) ?? 0));
+        return Math.max(0, Math.min(MAX_LOOKUPS[pool] - this.#lookups[pool], ...shares));
+    }
+    /**
+     * The shares of its pool a payer's lookups count against, with their caps: a carrier's and its network's, or
+     * an agent's.
+     */
+    #sharesOf(payer) {
+        if (typeof payer !== 'object')
+            return [];
+        if ('agent' in payer)
+            return [[`agent ${payer.agent}`, MAX_LOOKUPS_PER_AGENT]];
+        const network = payer.network ? [[`network ${payer.network}`, MAX_LOOKUPS_PER_NETWORK]] : [];
+        return [[`carrier ${payer.carrier}`, MAX_LOOKUPS_PER_CARRIER], ...network];
+    }
+    /**
+     * Run `fn`, setting `tally.made` when a lookup is made within it (one it starts, or one underway that it
+     * joins). A lookup refused before it was made, or answered from the cache, sets nothing.
+     */
+    tallied(tally, fn) {
+        return this.#tally.run(tally, fn);
+    }
+    /**
+     * Network work, bounded: one lookup per key at a time (concurrent asks share it), charged to whoever pays
+     * before it starts (and only when there is room for it), and at most MAX_LOOKUPS of its pool at once,
+     * MAX_LOOKUPS_PER_CARRIER for one carrier and MAX_LOOKUPS_PER_NETWORK for one network. A lookup for an unauthenticated caller also
+     * counts against the registrable domain of `name`, the name looked up (`#chargeDomain`).
+     */
+    #once(key, payer, name, work) {
+        const pending = this.#pending.get(key);
+        if (pending) {
+            const tally = this.#tally.getStore();
+            return pending.then(value => {
+                if (tally)
+                    tally.made = true;
+                return value;
+            }, error => {
+                if (tally && !isRefusal(error))
+                    tally.made = true;
+                throw error;
+            });
+        }
+        const pool = poolOf(payer);
+        const shares = this.#sharesOf(payer);
+        const full = shares.some(([k, max]) => (this.#shares.get(k) ?? 0) >= max);
+        if (this.#lookups[pool] >= MAX_LOOKUPS[pool] || full) {
+            throw refused(unavailable('This server is busy with lookups; try again shortly.', 5));
+        }
+        this.#lookups[pool]++;
+        for (const [k] of shares)
+            this.#shares.set(k, (this.#shares.get(k) ?? 0) + 1);
+        const charged = pool === 'charged' ? this.#chargeDomain(name) : Promise.resolve(undefined);
+        const tally = this.#tally.getStore();
+        const p = charged
+            .then(async (releaseDomain) => {
+            try {
+                // Both admissions must succeed before either account pays for outbound work.
+                (typeof payer === 'function' ? payer : payer && 'charge' in payer ? payer.charge : undefined)?.();
+            }
+            catch (error) {
+                await releaseDomain?.();
+                throw refused(error);
+            }
+            if (tally)
+                tally.made = true;
+            return work();
+        })
+            .finally(() => {
+            this.#lookups[pool]--;
+            for (const [k] of shares) {
+                const n = this.#shares.get(k) - 1;
+                if (n)
+                    this.#shares.set(k, n);
+                else
+                    this.#shares.delete(k);
+            }
+            this.#pending.delete(key);
+        });
+        this.#pending.set(key, p);
+        return p;
+    }
+    /**
+     * Count one lookup made before a signature verifies against the registrable domain of `name`, in a store
+     * counter per window, so every process on the store shares the bound; `429` past it, and the lookup is not
+     * made. A reservation refused here or by the caller's quota is returned without consuming a lookup.
+     */
+    async #chargeDomain(name) {
+        const { store, config } = this.#d;
+        const rate = config.rates.lookupDomain;
+        const now = this.#d.now().getTime();
+        const window = Math.floor(now / (rate.seconds * 1000));
+        const ends = (window + 1) * rate.seconds * 1000;
+        const id = `${registrableDomain(name, this.#d.publicSuffixes ?? shippedPublicSuffixes())} ${window}`;
+        const at = new Date(now).toISOString();
+        const count = await store.count(DOMAIN_LOOKUPS, id, new Date(ends).toISOString(), at);
+        const release = async () => {
+            await store.count(DOMAIN_LOOKUPS, id, new Date(ends).toISOString(), at, -1);
+        };
+        if (count <= rate.limit)
+            return release;
+        await release();
+        throw refused(rateLimited(Math.max(1, Math.ceil((ends - now) / 1000))));
+    }
+    /** GET a document: the answer when 200, null when there is none, 503 on a failure that may pass. */
+    async #getDocument(url) {
+        let res;
+        try {
+            res = await this.#d.http.request({
+                method: 'GET',
+                url,
+                maxBytes: MAX_DOCUMENT_BYTES,
+                timeoutMs: FETCH_TIMEOUT_MS,
+            });
+        }
+        catch (e) {
+            const kind = e instanceof Unreachable ? e.kind : 'failed';
+            if (kind === 'absent' || kind === 'forbidden' || kind === 'too_large')
+                return null;
+            throw unavailable(`Could not fetch ${url} just now.`);
+        }
+        if (res.status === 429 || res.status >= 500)
+            throw unavailable(`${url} answered ${res.status}.`);
+        return res.status === 200 ? res : null;
+    }
+    /**
+     * The well-known fetch as resolution needs it: null when there is no answer to be had (no such host, a
+     * refused connection, a certificate not valid for the host, an address this server may not call, or an
+     * answer too large to be one); a throw for a failure that may pass.
+     */
+    async #wellKnown(url) {
+        try {
+            return await this.#d.http.request({
+                method: 'GET',
+                url,
+                maxBytes: MAX_DOCUMENT_BYTES,
+                timeoutMs: FETCH_TIMEOUT_MS,
+            });
+        }
+        catch (e) {
+            const kind = e instanceof Unreachable ? e.kind : 'failed';
+            if (['absent', 'forbidden', 'refused', 'certificate', 'too_large'].includes(kind))
+                return null;
+            throw e;
+        }
+    }
+}
+const keysOf = (doc) => doc.keys.map(k => k.key);

package/dist/send.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `POST /simon/send` (CLIENT.md): an agent here hands over a message for delivery. Checked in the order the
+ * client API gives: the message as a delivery would check it (spec section 6.3, steps 1, 3 and 4); a
+ * version this server implements; `from` the agent's own address, on a domain that still names this
+ * server; the author's signature; the paired or solo rule; the 24-hour window; no message with an audience
+ * carried whole (spec section 7.1); every content-addressed
+ * part held for this agent, uploaded or received, so a part it received can be forwarded. Then the message,
+ * this server's claims about it signed for it (spec section 6.2), and one delivery row per recipient domain
+ * are stored as one, and the answer is given; delivery follows.
+ *
+ * A repeat answers as the first call did, and stores again whatever rows a store lost, so a client that
+ * retries after a crash never leaves its message undelivered.
+ */
+import { type AnyMessage, type Hints } from '@agnt-sdk/simon-protocol';
+import { type Context } from './context.ts';
+import { type Reply, type Request } from './http.ts';
+export declare function send(ctx: Context, req: Request): Promise<Reply>;
+/** `send` for an extension's own agent, with the message as an object: checked from step 4 on. */
+export declare function sendAs(ctx: Context, m: AnyMessage, hints?: Hints): Promise<{
+    id: string;
+    receivedAt: string;
+}>;
+/**
+ * The files a version 1 message names by content address: its own, and those of every message it carries
+ * whole, which count as its own (spec section 5.3). A later version's are not known here.
+ */
+export declare function contentParts(m: AnyMessage): {
+    sha256: string;
+    size: number;
+}[];

package/dist/send.js

@@ -0,0 +1,216 @@
+/**
+ * `POST /simon/send` (CLIENT.md): an agent here hands over a message for delivery. Checked in the order the
+ * client API gives: the message as a delivery would check it (spec section 6.3, steps 1, 3 and 4); a
+ * version this server implements; `from` the agent's own address, on a domain that still names this
+ * server; the author's signature; the paired or solo rule; the 24-hour window; no message with an audience
+ * carried whole (spec section 7.1); every content-addressed
+ * part held for this agent, uploaded or received, so a part it received can be forwarded. Then the message,
+ * this server's claims about it signed for it (spec section 6.2), and one delivery row per recipient domain
+ * are stored as one, and the answer is given; delivery follows.
+ *
+ * A repeat answers as the first call did, and stores again whatever rows a store lost, so a client that
+ * retries after a crash never leaves its message undelivered.
+ */
+import { carriedMessages, checkEnvelopeShape, claimsBytes, checkMessage, checkPrincipal, checkSupportedVersion, deliveryWindow, domainOf, invalid, isFresh, isJsonObject, judgeClaims, messageId, namedFiles, parseMessage, parseStrict, SEND_WINDOW_MS, sign, unauthorized, verifyMessage, } from '@agnt-sdk/simon-protocol';
+import { authenticateAgent } from "./auth.js";
+import { iso, later } from "./context.js";
+import { badRequest, conflict } from "./errors.js";
+import { json } from "./http.js";
+import { MOVE_WINDOW_MS, SERVING_SINCE } from "./outbox.js";
+import { changed } from "./sync.js";
+const DAY_MS = 86_400_000;
+export async function send(ctx, req) {
+    const agent = await authenticateAgent(ctx, req);
+    const m = parseMessage(req.body, ctx.config.limits);
+    return json(await write(ctx, agent, m, readHintsHeader(req.headers['simon-hints'])));
+}
+/** `send` for an extension's own agent, with the message as an object: checked from step 4 on. */
+export async function sendAs(ctx, m, hints) {
+    const agent = await ctx.store.agentByAddress(m.from);
+    if (!agent || agent.retiredAt)
+        throw invalid(`${m.from} is not an agent here.`, { field: 'from' });
+    return write(ctx, agent, checkMessage(m, ctx.config.limits), hints ?? {});
+}
+/** The checks after the message's own, then storage. Answers the id and when it was received. */
+async function write(ctx, agent, m, hints) {
+    checkSupportedVersion(m);
+    const id = messageId(m);
+    const now = ctx.now();
+    const earlier = await ctx.store.message(id);
+    if (earlier && earlier.message.from === agent.address && earlier.carrier === ctx.config.origin) {
+        // The claims that travel, as the first call checked them: without this server's judgement.
+        checkHints(ctx, hints, m, earlier.signedClaims?.claims ?? []);
+        await ctx.store.putMessage(earlier, { deliveries: deliveriesFor(earlier, hints) });
+        ctx.wake();
+        return { id, receivedAt: earlier.receivedAt };
+    }
+    if (m.from !== agent.address)
+        throw invalid(`This agent sends only as ${agent.address}.`, { field: 'from' });
+    const domain = domainOf(agent.address);
+    // Its lookups are the agent's, in its share of the server's own pool (resolver.ts).
+    const payer = { agent: agent.address };
+    if (!(await ctx.resolver.servesHere(domain, payer))) {
+        await ctx.store.setValue(SERVING_SINCE, domain, null, iso(now));
+        throw conflict('address_not_served', `${domain} no longer names this server.`);
+    }
+    await notedServing(ctx, domain, now);
+    if (!verifyMessage(m, agent.keys)) {
+        throw unauthorized('bad_signature', "The message does not verify with the author's keys valid at its sentAt.", now);
+    }
+    checkPrincipal(m, agent.principal === null ? { kind: 'solo' } : { kind: 'paired', for: agent.principal });
+    if (!isFresh(m, now, SEND_WINDOW_MS)) {
+        throw invalid('sentAt is more than 24 hours old or more than 5 minutes ahead.', { field: 'sentAt' });
+    }
+    checkCarriedAudience(m);
+    for (const p of contentParts(m)) {
+        if (!(await holds(ctx, agent.address, p))) {
+            throw badRequest('part_not_uploaded', `Upload part ${p.sha256} (${p.size} bytes) first.`, { sha256: p.sha256 });
+        }
+    }
+    const made = await ctx.hooks.claimsFor(m, agent);
+    const claims = await judgeClaims(m, made, agent.kind, ctx.config.origin, d => ctx.resolver.resolve(d, { charge: payer }));
+    // What travels, and is signed for the message, is the claims considered, without this server's judgement.
+    const sent = claims.map(({ authoritative: _, ...c }) => c);
+    checkHints(ctx, hints, m, sent);
+    ctx.rate.hit('send', agent.address);
+    ctx.rate.distinct('destinations', agent.address, m.to.map(domainOf));
+    const record = {
+        id,
+        message: m,
+        carrier: ctx.config.origin,
+        claims,
+        signedClaims: sent.length ? { claims: sent, signature: sign(ctx.config.serverKey, claimsBytes(sent, id)) } : null,
+        receivedAt: iso(now),
+        expiresAt: later(now, ctx.config.retentionDays * DAY_MS),
+    };
+    const stored = await ctx.store.putMessage(record, { deliveries: deliveriesFor(record, hints) });
+    ctx.defer(() => ctx.hooks.emit('stored', { message: stored }));
+    await changed(ctx, agent.address);
+    return { id, receivedAt: stored.receivedAt };
+}
+/** How often a send renews what it noted about serving its domain, at most. */
+const SERVING_CHECKED_EVERY_MS = 10 * 60_000;
+/**
+ * Note when this server began serving an agent's domain, as far as it can tell: the outbox retries a 403 for
+ * an hour after it, while receivers' caches may still name the server before (spec section 6.3). The note
+ * lapses an hour after the last send that found the domain naming this server, so a domain that moved away
+ * and back unseen in between begins again, rather than keeping a beginning from before it left.
+ */
+async function notedServing(ctx, domain, now) {
+    const noted = await ctx.store.value(SERVING_SINCE, domain, iso(now));
+    const expires = later(now, MOVE_WINDOW_MS);
+    const fresh = { since: iso(now), checked: iso(now) };
+    if (!noted) {
+        await ctx.store.valueOnce(SERVING_SINCE, domain, fresh, expires, iso(now));
+    }
+    else if (typeof noted !== 'object') {
+        // An earlier version noted a bare time that never lapsed; it is read as lapsed, and the note begins anew.
+        await ctx.store.setValue(SERVING_SINCE, domain, fresh, expires);
+    }
+    else if (now.getTime() - Date.parse(noted.checked) >= SERVING_CHECKED_EVERY_MS) {
+        await ctx.store.setValue(SERVING_SINCE, domain, { since: noted.since, checked: iso(now) }, expires);
+    }
+}
+/**
+ * A message with an `audience` header is never forwarded or quoted whole (spec section 7.1): a message that
+ * carries one inline, at any depth, is refused as the message checks refuse a part (`400 invalid`, `parts`).
+ * One carried by content address is not seen here; its bytes are the client's to keep to itself.
+ */
+function checkCarriedAudience(m) {
+    for (const inner of carriedMessages(m)) {
+        const headers = inner.headers;
+        if (inner.v === 1 && isJsonObject(headers) && Object.hasOwn(headers, 'audience')) {
+            throw invalid('A message with an audience is never forwarded or quoted whole (spec section 7.1).', {
+                field: 'parts',
+            });
+        }
+    }
+}
+/**
+ * Verify possession at the declared size and retain received bytes as this sender's own source. Its new
+ * naming message then pins that copy even after earlier messages and their inbox grants expire.
+ */
+async function holds(ctx, address, p) {
+    for (const source of await ctx.store.heldFor(p.sha256, address, ctx.config.origin)) {
+        if (source.size !== p.size)
+            continue;
+        const bytes = await ctx.store.part(p.sha256, source);
+        if (bytes?.length !== p.size)
+            continue;
+        if (!('uploader' in source) || source.uploader !== address) {
+            await ctx.store.putPart(p.sha256, bytes, { uploader: address }, iso(ctx.now()));
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * The files a version 1 message names by content address: its own, and those of every message it carries
+ * whole, which count as its own (spec section 5.3). A later version's are not known here.
+ */
+export function contentParts(m) {
+    const seen = new Set();
+    return namedFiles(m).filter(p => !seen.has(p.sha256) && seen.add(p.sha256));
+}
+/**
+ * The `simon-hints` header: one JSON object, in ASCII (CLIENT.md send), or `{}` when absent. A byte outside
+ * printable ASCII is refused rather than read as Latin-1 and passed on changed.
+ */
+function readHintsHeader(header) {
+    if (header === undefined)
+        return {};
+    if (typeof header === 'string' && /[^\x20-\x7e]/.test(header)) {
+        throw invalid('simon-hints is ASCII: escape every other character as \\uXXXX.', { field: 'simon-hints' });
+    }
+    try {
+        const hints = typeof header === 'string' ? parseStrict(header) : null;
+        if (isJsonObject(hints))
+            return hints;
+    }
+    catch {
+        // Refused below, as any other value that is not a JSON object.
+    }
+    throw invalid('simon-hints is one JSON object keyed by recipient address.', { field: 'simon-hints' });
+}
+/**
+ * Hints: an object keyed by recipients in `to`, of objects of strings, small enough to travel in an
+ * envelope beside this server's claims, checked as the envelope they will travel in. The message's own
+ * signature stands in for the envelope's: only the shape is checked here.
+ */
+function checkHints(ctx, hints, m, claims) {
+    if (isJsonObject(hints) && Object.keys(hints).length === 0)
+        return;
+    if (m.to.length === 0)
+        throw invalid('A public message has no recipients to give hints to.', { field: 'simon-hints' });
+    const envelope = {
+        message: m,
+        server: ctx.config.origin,
+        recipients: m.to,
+        ...(claims.length ? { claims, claimsSignature: m.signature } : {}),
+        hints,
+        signature: m.signature,
+    };
+    checkEnvelopeShape(envelope, ctx.config.dev);
+}
+/**
+ * One delivery row per recipient domain, each with its recipients' hints, first due at `sentAt` (never
+ * before it) and ending at the delivery deadline (spec section 6.3).
+ */
+function deliveriesFor(record, hints) {
+    const accepted = new Date(record.receivedAt);
+    const { earliest, deadline } = deliveryWindow(record.message, accepted);
+    const byDomain = Map.groupBy(record.message.to, domainOf);
+    return [...byDomain].map(([domain, recipients]) => ({
+        id: record.id,
+        domain,
+        recipients,
+        hints: Object.fromEntries(recipients.filter(r => hints[r]).map(r => [r, hints[r]])),
+        server: null,
+        status: 'pending',
+        reason: null,
+        attempts: 0,
+        nextAttemptAt: iso(earliest > accepted ? earliest : accepted),
+        createdAt: record.receivedAt,
+        deadline: iso(deadline),
+    }));
+}