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

package/dist/deliver.js

@@ -0,0 +1,208 @@
+/**
+ * `POST /simon/deliver` (spec section 6.3): an envelope from another server, checked in exactly the
+ * section's order, answering the first failure:
+ *
+ *   1-5  body size and parse, envelope shape, canonical message, message rules, and the envelope for this
+ *        server with its recipients in `to`, all without a lookup                (parseEnvelope)
+ *   6    the `from` domain resolves to another server                             (403 otherwise)
+ *   7    the envelope, and its claims, verify with that server's keys valid now, by a key trusted under
+ *        continuity
+ *   8    every recipient on a domain served here: only now, with the carrier known, may that need a lookup
+ *   9    a repeat for recipients all accepted here in the last 168 hours is 202
+ *   10   `sentAt` fresh
+ *   11   the author's agent document readable, and the message verifies at its `sentAt`
+ *   12   202: accepted once per (id, recipient)
+ *
+ * Deliver is the one call anyone can make that sends this server out to the network, so the one lookup it
+ * makes before the carrier is known, the `from` domain, is counted against the client's network (`lookup`).
+ * Every lookup after it is the carrier's: its recipients' domains and its claims count against its
+ * `carrierLookup` rate, and those and its author's document run in the carrier's share of a pool of their
+ * own, never in the one the server's own sending uses. Recipients' domains are resolved side by side, as
+ * many at once as the carrier's share allows, and none is started past RECIPIENT_LOOKUPS_MS, so an envelope
+ * naming many slow domains holds a delivery a bounded time. Before step 7, the (client network, claimed
+ * server) pair must have signature failures to spare: a sender whose signatures keep failing costs one counter read, not a
+ * verification. Every delivery past step 7, a repeat as much as a new one, counts against the carrier's
+ * `deliver` rate. Accepting stores the message whoever the recipients are, and queues the fetch of its parts
+ * (spec section 7.2), so the answer, its timing and the fetches say nothing about them; offering it to them
+ * happens afterwards, in the worker.
+ */
+import crypto from 'node:crypto';
+import { checkAuthorSignature, checkEnvelopeBeside, checkFreshness, checkServed, claimsBytes, domainOf, forbidden, isRepeat, judgeClaims, messageId, parseEnvelope, parseTimestamp, REPEAT_WINDOW_MS, signedByAny, signingBytes, verifyMessage, WireError, } from '@agnt-sdk/simon-protocol';
+import { iso, later } from "./context.js";
+import { arrivalsFor } from "./fanout.js";
+import { queuePrefetch } from "./parts.js";
+import { json } from "./http.js";
+import { clientKey, networkKey } from "./net/ip.js";
+import { unavailable } from "./errors.js";
+import { isRefusal } from "./resolver.js";
+const DAY_MS = 86_400_000;
+const ACCEPTED = { accepted: true };
+export async function deliver(ctx, req) {
+    const now = ctx.now();
+    const client = clientKey(req.ip);
+    const charge = () => ctx.rate.hit('lookup', client);
+    // Steps 1 to 5 need no lookup, so an envelope meant for another server, or for no one here, costs none.
+    const { origin, dev: allowHttp } = ctx.config;
+    const envelope = parseEnvelope(req.body, ctx.config.limits, { origin, allowHttp });
+    checkEnvelopeBeside(envelope, ctx.config.envelopeExtrasBytes);
+    const m = envelope.message;
+    const domain = domainOf(m.from);
+    let cached = ctx.resolver.isCached(domain);
+    let peer = await ctx.resolver.peer(domain, charge);
+    const noServer = () => forbidden('bad_signature', `${domain} names no other SIMON server, so no envelope from it verifies.`);
+    // Even a cached absence or our own old route can hide a move to the actual carrying server.
+    if (cached && (peer.outcome !== 'server' || peer.server === ctx.config.origin)) {
+        peer = (await reresolve(ctx, domain, () => ctx.resolver.peer(domain, charge, { fresh: true }))) ?? peer;
+        cached = false;
+    }
+    if (peer.outcome !== 'server' || peer.server === ctx.config.origin)
+        throw noServer();
+    let server = peer.server;
+    const failures = `${client} ${server}`;
+    ctx.rate.check('badSignature', failures);
+    const fail = (e) => {
+        if (e.code === 'bad_signature')
+            ctx.rate.hit('badSignature', failures);
+        return e;
+    };
+    let signed = signer(envelope, peer.document, now) ??
+        signer(envelope, await ctx.resolver.serverDocument(server, { refresh: true, charge }), now);
+    // Step 7's last chance: a domain that just moved its server is found at the new one. Resolved and read
+    // again without the cache, when the resolution came from it, at most once a minute for one domain (a mark
+    // in the store, which every process shares); a re-resolution that fails for now is 503.
+    const again = !signed && cached ? await reresolve(ctx, domain, () => ctx.resolver.peer(domain, charge, { fresh: true })) : null;
+    if (again) {
+        peer = again;
+        if (peer.outcome !== 'server' || peer.server === ctx.config.origin)
+            throw fail(noServer());
+        server = peer.server;
+        signed = signer(envelope, peer.document, now);
+    }
+    if (!signed) {
+        throw fail(forbidden('bad_signature', `The envelope is not signed by a key of ${server} valid now.`));
+    }
+    await ctx.resolver.trustSigner(domain, server, signed.key, signed.document);
+    ctx.rate.hit('deliver', server);
+    const network = networkKey(req.ip);
+    const carrier = { carrier: server, network, charge: () => ctx.rate.hit('carrierLookup', server) };
+    checkServed(envelope.recipients, await servedDomains(ctx, envelope.recipients, carrier));
+    const id = messageId(m);
+    const accepted = new Set();
+    for (const r of envelope.recipients)
+        if (await ctx.store.marked('accepted', `${id}\n${r}`, iso(now)))
+            accepted.add(r);
+    if (isRepeat(envelope, accepted, now))
+        return json(ACCEPTED, 202);
+    checkFreshness(m, now);
+    const authorOf = (refresh) => ctx.resolver.agentKeys(m.from, server, refresh, { carrier: server, network });
+    let author = await authorOf(false);
+    if (!author || !verifyMessage(m, author.keys))
+        author = await authorOf(true);
+    if (!author)
+        throw fail(forbidden('bad_signature', `${server} serves no agent document for ${m.from}.`));
+    try {
+        checkAuthorSignature(m, author.keys);
+    }
+    catch (e) {
+        throw e instanceof WireError ? fail(e) : e;
+    }
+    const fresh = envelope.recipients.filter(r => !accepted.has(r));
+    const record = await ctx.store.putMessage({
+        id,
+        message: m,
+        carrier: server,
+        claims: await judgeClaims(m, envelope.claims, author.kind, server, d => ctx.resolver.resolve(d, { charge: carrier })),
+        signedClaims: envelope.claims ? { claims: envelope.claims, signature: envelope.claimsSignature } : null,
+        receivedAt: iso(now),
+        expiresAt: later(now, ctx.config.retentionDays * DAY_MS),
+    }, { arrivals: arrivalsFor(id, fresh, envelope.hints ?? {}, now) });
+    await queuePrefetch(ctx, record);
+    const until = new Date(parseTimestamp(m.sentAt) + REPEAT_WINDOW_MS).toISOString();
+    for (const r of fresh)
+        await ctx.store.mark('accepted', `${id}\n${r}`, until, iso(now));
+    await ctx.resolver.vouch(domain, signed.document);
+    ctx.wake();
+    return json(ACCEPTED, 202);
+}
+/**
+ * The carrier key that signed the envelope, and its claims, among `document`'s keys valid now, or null. The
+ * signed bytes are made once, however many keys the document lists.
+ */
+function signer(e, document, now) {
+    if (!document)
+        return null;
+    const envelopeBytes = signingBytes('SIMON-ENVELOPE', e);
+    const claims = e.claims && claimsBytes(e.claims, messageId(e.message));
+    const key = document.keys.find(k => signedByAny([k], now, envelopeBytes, e.signature));
+    if (!key || (claims && !signedByAny(document.keys, now, claims, e.claimsSignature)))
+        return null;
+    return { key: key.key, document };
+}
+/** How long step 8 may go on starting lookups of recipients' domains; a lookup underway ends by its own deadline. */
+export const RECIPIENT_LOOKUPS_MS = 20_000;
+/** 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 const RERESOLVE_EVERY_MS = 60_000;
+/**
+ * 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 async function reresolve(ctx, domain, lookup) {
+    const token = crypto.randomUUID();
+    const until = later(ctx.now(), RERESOLVE_EVERY_MS);
+    if ((await ctx.store.valueOnce('reresolve', domain, token, until, iso(ctx.now()))) !== token)
+        return null;
+    const tally = { made: false };
+    try {
+        return await ctx.resolver.tallied(tally, lookup);
+    }
+    catch (e) {
+        if (isRefusal(e) && !tally.made)
+            await ctx.store.releaseValue('reresolve', domain, token);
+        throw e;
+    }
+}
+/**
+ * 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 async function servedDomains(ctx, addresses, payer) {
+    const { hostedDomains, leaseDomain } = ctx.config;
+    const domains = [...new Set(addresses.map(domainOf))];
+    const served = new Set(domains.filter(d => hostedDomains.includes(d) || d === leaseDomain));
+    const queue = domains.filter(d => !served.has(d));
+    const wasCached = new Set(queue.filter(d => ctx.resolver.isCached(d)));
+    const deadline = ctx.now().getTime() + RECIPIENT_LOOKUPS_MS;
+    let stopped = false;
+    const lookups = async () => {
+        for (let d; !stopped && (d = queue.shift()) !== undefined;) {
+            if (ctx.now().getTime() > deadline)
+                throw unavailable("Could not resolve the recipients' domains in time.");
+            if (await ctx.resolver.servesHere(d, payer))
+                served.add(d);
+        }
+    };
+    // As many side by side as the payer's free share allows now, so its other deliveries' lookups underway
+    // never make this one refuse itself; at least one, which a full share refuses for now (503).
+    const width = Math.max(1, ctx.resolver.room(payer));
+    const workers = Array.from({ length: Math.min(queue.length, width) }, lookups);
+    await Promise.all(workers).catch(e => {
+        stopped = true;
+        throw e;
+    });
+    // Before answering 400 for a domain whose answer came from the cache, it is resolved again without it, at
+    // most once a minute for one domain, so a domain that has just moved here is found (spec section 6.3 step 8);
+    // within the same deadline, past which the answer is 503.
+    for (const d of wasCached) {
+        if (served.has(d))
+            continue;
+        if (ctx.now().getTime() > deadline)
+            throw unavailable("Could not resolve the recipients' domains in time.");
+        if (await reresolve(ctx, d, () => ctx.resolver.servesHere(d, payer, true)))
+            served.add(d);
+    }
+    return (d) => served.has(d);
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Errors in the protocol's shape (spec section 9, RFC 9457) beyond the ones @agnt-sdk/simon-protocol makes. A 429 or
+ * 503 says when to retry in `details.retryAfter`, in seconds, which also goes out as Retry-After.
+ */
+import { WireError } from '@agnt-sdk/simon-protocol';
+export declare const notFound: (what?: string) => WireError;
+export declare const conflict: (code: string, message: string, details?: Record<string, unknown>) => WireError;
+export declare const badRequest: (code: string, message: string, details?: Record<string, unknown>) => WireError;
+export declare const rateLimited: (retryAfter: number) => WireError;
+/** A lookup or fetch this server needed failed just now. */
+export declare const unavailable: (message: string, retryAfter?: number) => WireError;

package/dist/errors.js

@@ -0,0 +1,11 @@
+/**
+ * Errors in the protocol's shape (spec section 9, RFC 9457) beyond the ones @agnt-sdk/simon-protocol makes. A 429 or
+ * 503 says when to retry in `details.retryAfter`, in seconds, which also goes out as Retry-After.
+ */
+import { WireError } from '@agnt-sdk/simon-protocol';
+export const notFound = (what = 'Nothing is here.') => new WireError(404, 'not_found', what);
+export const conflict = (code, message, details) => new WireError(409, code, message, details);
+export const badRequest = (code, message, details) => new WireError(400, code, message, details);
+export const rateLimited = (retryAfter) => new WireError(429, 'rate_limited', `Too many requests; retry in ${retryAfter} s.`, { retryAfter });
+/** A lookup or fetch this server needed failed just now. */
+export const unavailable = (message, retryAfter = 30) => new WireError(503, 'unavailable', message, { retryAfter });

package/dist/extensions.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The extension seam: how an application adds a directory, recipient policy, an owner window or a bridge
+ * without editing the core. An extension is a plain object; the server takes an array of them, and every
+ * hook is the list of all extensions' hooks, in the order given. No hook is a single slot.
+ *
+ *   routes           more HTTP routes (they may not replace the core's)
+ *   admit            the admit chain: whether a recipient here takes a message
+ *   claimsFor        claims this server makes about the author of a message sent here
+ *   allowAddress     who may take a new name on a hosted domain, or a lease
+ *   verifyPrincipal  pairing with a principal the core cannot verify itself (mailto:, tel:)
+ *   upload           whether an agent's upload is kept (a malware scan, a volume limit)
+ *   admitsReader     whether a published message's audience label admits a reader
+ *   on               events: stored, inbox, delivered, deliveryFailed, unroutable, recovered, signal
+ */
+import type { AnyMessage, Claim, Hints, Json, Signal } from '@agnt-sdk/simon-protocol';
+import type { Config } from './config.ts';
+import type { Request, Route } from './http.ts';
+import type { Agent, Store, StoredMessage } from './store/store.ts';
+export type Log = (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>) => void;
+/** What extensions may use of the server. */
+export interface ServerApi {
+    readonly config: Config;
+    readonly store: Store;
+    now(): Date;
+    log: Log;
+    /** The agent here that signed this request (spec section 8), or a 401 in the protocol's shape. */
+    authenticate(req: Request): Promise<Agent>;
+    /** Take a message an admit hook answered `later` into a recipient's inbox; false if it already was. */
+    admit(address: string, id: string): Promise<boolean>;
+    /** Offer a stored message to an agent here through the admit chain, as delivery does; true when it took or holds it. */
+    offer(address: string, id: string): Promise<boolean>;
+    /**
+     * Send a message written by an agent here (an application's own agents: notices, a bridge), checked and
+     * delivered exactly as `POST /simon/send` would; `hints` as its `simon-hints` header carries them.
+     */
+    send(message: AnyMessage, hints?: Hints): Promise<{
+        id: string;
+        receivedAt: string;
+    }>;
+    /** Retire an address (spec section 2.2): its keys revoked, its document gone, never registered again. */
+    retire(address: string): Promise<void>;
+}
+/** A message offered to one recipient here. */
+export interface Arrival {
+    id: string;
+    message: AnyMessage;
+    recipient: string;
+    /** The origin of the server that carried it; this server's own for a message written here. */
+    carrier: string;
+    /**
+     * The claims agents here are shown (spec section 6.2): authoritative ones always, the rest only from a
+     * carrier this server trusts. Each acts-for and identifier claim carries `authoritative`.
+     */
+    claims: Claim[];
+    /** This recipient's hints from the envelope or from `simon-hints`. */
+    hints: Record<string, string>;
+}
+/**
+ * One link of the admit chain, read like Postfix's restrictions: `accept` takes the message and ends the
+ * chain, `refuse` drops it and ends the chain, `later` holds it (the extension calls `api.admit` when it
+ * decides) and ends the chain, and `undefined` has no opinion. When no link decides, the message is taken.
+ * The sender learns none of this: the answer was 202 either way.
+ */
+export type Decision = 'accept' | 'refuse' | 'later' | undefined;
+/** A registration of a new address, by the key that would hold it. */
+export interface AddressRequest {
+    /**
+     * The address being registered: the one named, or the one leased. The core asks only about an address
+     * no agent holds and none ever retired, so an extension never decides, or sends a code, for one it
+     * cannot have.
+     */
+    address: string;
+    key: string;
+    /** The whole register body, for members of the extension's own, such as a code or a proof. */
+    body: Record<string, Json>;
+}
+/**
+ * Whether a key may take a new address on a hosted domain or the lease domain, whose names are this
+ * server's to give: `allow` or `refuse` ends the chain, `undefined` has no opinion. When no extension
+ * decides, the key takes it, first come, first served. A refusal is `409 address_taken`, the answer a held
+ * name gets; a thrown WireError is answered as itself. The hook only decides: it is asked on every call
+ * that would create the address, each round trip of a pairing included, and an `allow` may still end in
+ * no address (a pairing that fails, another key first), so it uses nothing up.
+ */
+export type AddressDecision = 'allow' | 'refuse' | undefined;
+/** A registration naming a principal of a kind the core does not verify. */
+export interface PrincipalRequest extends AddressRequest {
+    principal: string;
+}
+/**
+ * `verified`: pair the agent with the principal. `pending`: answer 202 with `body` and wait for another
+ * call. `undefined`: not this extension's kind of principal. A refusal throws a WireError.
+ */
+export type PrincipalAnswer = {
+    status: 'verified';
+} | {
+    status: 'pending';
+    body: Record<string, Json>;
+} | undefined;
+/** Bytes an agent here uploaded, before they are kept. */
+export interface Upload {
+    address: string;
+    sha256: string;
+    bytes: Buffer;
+}
+/**
+ * A reader asking for a published message whose `audience` header is `audience` (spec section 7.1). `reader`
+ * is the address that signed the request with a key of its own agent document, or null when nobody in
+ * particular asks.
+ */
+export interface ReaderRequest {
+    message: AnyMessage;
+    audience: string;
+    reader: string | null;
+}
+/** `admit` or `refuse` ends the chain; `undefined` has no opinion. With no decision, only the author reads it. */
+export type ReaderDecision = 'admit' | 'refuse' | undefined;
+export interface Events {
+    /**
+     * A message was kept: sent by an agent here, or accepted from another server and taken or held by a
+     * recipient here. A message nobody here took is never kept, and never reported.
+     */
+    stored: {
+        message: StoredMessage;
+    };
+    /**
+     * A message entered an agent's inbox. Told at least once: the event is written with the entry and told
+     * afterwards, so a crash between the two repeats it rather than losing it. A listener dedupes by
+     * (address, message id) if it must.
+     */
+    inbox: {
+        address: string;
+        message: StoredMessage;
+    };
+    /** A server answered 202 for these recipients (this server, for its own agents). */
+    delivered: {
+        id: string;
+        server: string;
+        recipients: string[];
+    };
+    /** Delivery to these recipients ended without a 202; `reason` is a resolution outcome or an error code. */
+    deliveryFailed: {
+        id: string;
+        server: string | null;
+        recipients: string[];
+        reason: string;
+    };
+    /**
+     * These recipients' domain names no SIMON server (`not_found`). A bridge may reach them another way: a
+     * listener that answers `true` took them, and their delivery counts as delivered rather than failed.
+     */
+    unroutable: {
+        id: string;
+        domain: string;
+        recipients: string[];
+        message: AnyMessage;
+    };
+    /**
+     * An agent's keys were replaced by `key`: `by` its address's mailbox, a code sent there, so whoever holds
+     * the mailbox now holds the agent; or `by` its key principal, the agent's root of trust.
+     */
+    recovered: {
+        address: string;
+        key: string;
+        by: 'mailbox' | 'principal';
+    };
+    /**
+     * A signal passed for an agent here, about a message it holds, from a party to that message (spec section
+     * 6.4; this server's policy). Nothing keeps it: a listener shows it now or never.
+     */
+    signal: {
+        recipient: string;
+        signal: Signal;
+    };
+}
+/** What a listener answers: only an `unroutable` listener may answer, `true` when it took the recipients. */
+type Answer<E extends keyof Events> = E extends 'unroutable' ? boolean | void : void;
+export type Listeners = {
+    [E in keyof Events]?: (event: Events[E], api: ServerApi) => Answer<E> | Promise<Answer<E>>;
+};
+export interface Extension {
+    name: string;
+    routes?: Route<ServerApi>[];
+    admit?(arrival: Arrival, api: ServerApi): Decision | Promise<Decision>;
+    claimsFor?(message: AnyMessage, agent: Agent, api: ServerApi): Claim[] | Promise<Claim[]>;
+    allowAddress?(request: AddressRequest, api: ServerApi): AddressDecision | Promise<AddressDecision>;
+    verifyPrincipal?(request: PrincipalRequest, api: ServerApi): PrincipalAnswer | Promise<PrincipalAnswer>;
+    /** Refuse an upload by throwing a WireError; return to let it be kept. */
+    upload?(upload: Upload, api: ServerApi): void | Promise<void>;
+    admitsReader?(request: ReaderRequest, api: ServerApi): ReaderDecision | Promise<ReaderDecision>;
+    on?: Listeners;
+}
+/** All extensions' hooks, run as one. */
+export declare class Hooks {
+    #private;
+    constructor(extensions: Extension[], api: () => ServerApi);
+    get routes(): Route<ServerApi>[];
+    /** The first decision in the chain, or `accept` when none decides. */
+    admit(arrival: Arrival): Promise<'accept' | 'refuse' | 'later'>;
+    claimsFor(message: AnyMessage, agent: Agent): Promise<Claim[]>;
+    /** The first decision on a new hosted or leased address, or `allow` when none decides. */
+    allowAddress(request: AddressRequest): Promise<'allow' | 'refuse'>;
+    /** The first extension's answer for this principal, or undefined when none verifies its kind. */
+    verifyPrincipal(request: PrincipalRequest): Promise<PrincipalAnswer>;
+    /** The first decision on a reader of a message with an audience, or `refuse` when none decides. */
+    admitsReader(request: ReaderRequest): Promise<'admit' | 'refuse'>;
+    /** Every extension's check of an upload, in order; the first refusal throws. */
+    upload(upload: Upload): Promise<void>;
+    /**
+     * Tell every listener, in order. A listener that fails is logged; it never fails the core's work. For
+     * `unroutable`, the first listener that answers `true` takes the recipients, and the rest are not told.
+     * Answers whether one did.
+     */
+    emit<E extends keyof Events>(event: E, payload: Events[E]): Promise<boolean>;
+}
+export {};

package/dist/extensions.js

@@ -0,0 +1,75 @@
+/** All extensions' hooks, run as one. */
+export class Hooks {
+    #extensions;
+    #api;
+    constructor(extensions, api) {
+        this.#extensions = extensions;
+        this.#api = api;
+    }
+    get routes() {
+        return this.#extensions.flatMap(e => e.routes ?? []);
+    }
+    /** The first decision in the chain, or `accept` when none decides. */
+    async admit(arrival) {
+        for (const e of this.#extensions) {
+            const decision = await e.admit?.(arrival, this.#api());
+            if (decision !== undefined)
+                return decision;
+        }
+        return 'accept';
+    }
+    async claimsFor(message, agent) {
+        const all = await Promise.all(this.#extensions.map(e => e.claimsFor?.(message, agent, this.#api()) ?? []));
+        return all.flat();
+    }
+    /** The first decision on a new hosted or leased address, or `allow` when none decides. */
+    async allowAddress(request) {
+        for (const e of this.#extensions) {
+            const decision = await e.allowAddress?.(request, this.#api());
+            if (decision !== undefined)
+                return decision;
+        }
+        return 'allow';
+    }
+    /** The first extension's answer for this principal, or undefined when none verifies its kind. */
+    async verifyPrincipal(request) {
+        for (const e of this.#extensions) {
+            const answer = await e.verifyPrincipal?.(request, this.#api());
+            if (answer !== undefined)
+                return answer;
+        }
+        return undefined;
+    }
+    /** The first decision on a reader of a message with an audience, or `refuse` when none decides. */
+    async admitsReader(request) {
+        for (const e of this.#extensions) {
+            const decision = await e.admitsReader?.(request, this.#api());
+            if (decision !== undefined)
+                return decision;
+        }
+        return 'refuse';
+    }
+    /** Every extension's check of an upload, in order; the first refusal throws. */
+    async upload(upload) {
+        for (const e of this.#extensions)
+            await e.upload?.(upload, this.#api());
+    }
+    /**
+     * Tell every listener, in order. A listener that fails is logged; it never fails the core's work. For
+     * `unroutable`, the first listener that answers `true` takes the recipients, and the rest are not told.
+     * Answers whether one did.
+     */
+    async emit(event, payload) {
+        for (const e of this.#extensions) {
+            const listener = e.on?.[event];
+            try {
+                if ((await listener?.(payload, this.#api())) === true && event === 'unroutable')
+                    return true;
+            }
+            catch (err) {
+                this.#api().log('error', `extension ${e.name} failed on ${event}`, { error: String(err) });
+            }
+        }
+        return false;
+    }
+}

package/dist/fanout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Fan-out: offering a stored message to its recipients here, after the answer was given, so no answer and
+ * no timing depends on who is here or what they decide (spec section 6.3, "Policy is silent").
+ *
+ *   - **Arrivals.** A message accepted for recipients here waits as one arrival per recipient. Each is
+ *     offered on its own: an arrival whose offer fails (an extension that throws, a store error) is tried
+ *     again later, with backoff, and holds up no other.
+ *   - **The admit chain** decides for each recipient. A message from another server that no recipient here
+ *     took or holds is not kept.
+ *   - **Inbox events** are written with the inbox entry and told afterwards, at least once: a crash between
+ *     the two repeats the event, never loses it.
+ */
+import type { Claim, Hints } from '@agnt-sdk/simon-protocol';
+import { type Context } from './context.ts';
+import type { QueuedArrival, StoredMessage } from './store/store.ts';
+/** Whether this server shows its agents a carrier's claims that are not authoritative: its own, or one trusted. */
+export declare const trustsClaimsOf: (ctx: Context, carrier: string) => boolean;
+/**
+ * The claims an agent here is shown with a message (CLIENT.md sync): the authoritative ones always, and
+ * the others only from a carrier this server trusts. Each acts-for and identifier claim carries `authoritative`.
+ */
+export declare const shownClaims: (ctx: Context, carrier: string, claims: Claim[]) => Claim[];
+/** One arrival per recipient, each with its own hints, due now. */
+export declare const arrivalsFor: (id: string, recipients: string[], hints: Hints, now: Date) => QueuedArrival[];
+/** Offer due arrivals, each on its own. Returns how many were taken up. */
+export declare function processArrivals(ctx: Context): Promise<number>;
+/** Offer a stored message to those of `recipients` who are agents here. True when any took it or holds it. */
+export declare function fanOut(ctx: Context, record: StoredMessage, recipients: string[], hints: Hints): Promise<boolean>;
+/** Put a message into an agent's inbox once; its inbox event is told by `tellInboxEvents`. */
+export declare function takeIntoInbox(ctx: Context, address: string, record: StoredMessage, generation?: string): Promise<boolean>;
+/** Tell the extensions of new inbox entries, at least once each. Returns how many were told. */
+export declare function tellInboxEvents(ctx: Context): Promise<number>;

package/dist/fanout.js

@@ -0,0 +1,79 @@
+import { iso, later } from "./context.js";
+import { changed } from "./sync.js";
+const BATCH = 50;
+const MIN_BACKOFF_MS = 60_000;
+const MAX_BACKOFF_MS = 3600_000;
+/** Whether this server shows its agents a carrier's claims that are not authoritative: its own, or one trusted. */
+export const trustsClaimsOf = (ctx, carrier) => carrier === ctx.config.origin || ctx.config.trustedClaimServers.includes(carrier);
+/**
+ * The claims an agent here is shown with a message (CLIENT.md sync): the authoritative ones always, and
+ * the others only from a carrier this server trusts. Each acts-for and identifier claim carries `authoritative`.
+ */
+export const shownClaims = (ctx, carrier, claims) => trustsClaimsOf(ctx, carrier) ? claims : claims.filter(c => c.authoritative === true);
+/** One arrival per recipient, each with its own hints, due now. */
+export const arrivalsFor = (id, recipients, hints, now) => recipients.map(recipient => ({ id, recipient, hints: hints[recipient] ?? {}, attempts: 0, dueAt: iso(now) }));
+/** Offer due arrivals, each on its own. Returns how many were taken up. */
+export async function processArrivals(ctx) {
+    const due = await ctx.store.arrivals(iso(ctx.now()), BATCH);
+    for (const { arrival, message: record, generation } of due) {
+        try {
+            const kept = await offer(ctx, record, arrival.recipient, arrival.hints, generation);
+            if ((await ctx.store.arrivalDone(record.id, arrival.recipient, kept, generation)) === 'kept') {
+                await ctx.hooks.emit('stored', { message: record });
+            }
+        }
+        catch (e) {
+            const delay = Math.min(MIN_BACKOFF_MS * 2 ** arrival.attempts, MAX_BACKOFF_MS);
+            ctx.log('error', 'offering an arrival failed; retrying', {
+                id: record.id,
+                recipient: arrival.recipient,
+                error: String(e),
+            });
+            await ctx.store.arrivalRetry(record.id, arrival.recipient, later(ctx.now(), delay), generation);
+        }
+    }
+    return due.length;
+}
+/** Offer a stored message to those of `recipients` who are agents here. True when any took it or holds it. */
+export async function fanOut(ctx, record, recipients, hints) {
+    let kept = false;
+    for (const address of recipients)
+        if (await offer(ctx, record, address, hints[address] ?? {}))
+            kept = true;
+    return kept;
+}
+/** Offer a message to one recipient here through the admit chain: true when it took or holds it. */
+async function offer(ctx, record, address, hints, generation) {
+    const agent = await ctx.store.agentByAddress(address);
+    if (!agent || agent.retiredAt)
+        return false;
+    const decision = await ctx.hooks.admit({
+        id: record.id,
+        message: record.message,
+        recipient: address,
+        carrier: record.carrier,
+        claims: shownClaims(ctx, record.carrier, record.claims),
+        hints,
+    });
+    if (decision === 'accept')
+        await takeIntoInbox(ctx, address, record, generation);
+    return decision !== 'refuse';
+}
+/** Put a message into an agent's inbox once; its inbox event is told by `tellInboxEvents`. */
+export async function takeIntoInbox(ctx, address, record, generation) {
+    const added = await ctx.store.addToInbox(address, record.id, iso(ctx.now()), generation, later(ctx.now(), ctx.config.syncDays * 86_400_000));
+    if (added)
+        await changed(ctx, address);
+    return added;
+}
+/** Tell the extensions of new inbox entries, at least once each. Returns how many were told. */
+export async function tellInboxEvents(ctx) {
+    const entries = await ctx.store.inboxEvents(BATCH);
+    for (const e of entries) {
+        const message = await ctx.store.message(e.id);
+        if (message)
+            await ctx.hooks.emit('inbox', { address: e.address, message });
+        await ctx.store.inboxEventDone(e.cursor);
+    }
+    return entries.length;
+}