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

package/dist/server.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `createServer`: the core assembled from its configuration, its store, the outside world (DNS, HTTP, a
+ * clock, a code sender) and any extensions. Everything outside is injectable, so tests run whole
+ * federations in one process on a fake network and a movable clock.
+ */
+import http from 'node:http';
+import type { Config } from './config.ts';
+import { type MailboxSender } from './context.ts';
+import { type Extension, type Log, type ServerApi } from './extensions.ts';
+import { type Reply, type Request } from './http.ts';
+import { type Dns } from './net/dns.ts';
+import { type Http } from './net/fetch.ts';
+import { type Store, type SweepCounts } from './store/store.ts';
+export interface ServerOptions {
+    config: Config;
+    store: Store;
+    extensions?: Extension[];
+    /** DNS through c-ares (and DNS-over-HTTPS confirmation when configured) by default. */
+    dns?: Dns;
+    /** Outbound HTTP through the SSRF guard by default. */
+    http?: Http;
+    now?: () => Date;
+    log?: Log;
+    /** How codes, and the news of a recovery, reach an address. Default: logged in development, none in production. */
+    mailbox?: MailboxSender | null;
+    /** Run the worker loop in this process (default true). Tests turn it off and call `work()`. */
+    worker?: boolean;
+    /**
+     * Public retirement evidence is host policy. Default: `config.retiredAgentDocuments`, which is `private`
+     * unless chosen otherwise; `public` serves signed retired documents and is an explicit opt-in.
+     */
+    retiredAgentDocuments?: 'public' | 'private';
+}
+export interface SimonServer {
+    /** What extensions see. */
+    api: ServerApi;
+    /** Answer one request, in-process. */
+    handle(req: Request): Promise<Reply>;
+    /** The node:http listener, for a server of your own. */
+    listener: http.RequestListener;
+    /** Listen on a port (the configured one by default; 0 for any), over https when `config.tls` is set; resolves to the port. */
+    listen(port?: number, host?: string): Promise<number>;
+    /**
+     * Background work until it settles, waited for: arrivals offered, inbox events told, part fetches and
+     * deliveries attempted, as far as they are due now.
+     */
+    work(): Promise<void>;
+    /** Remove what retention says has expired. */
+    sweep(): Promise<SweepCounts>;
+    close(): Promise<void>;
+}
+export declare function createServer(opts: ServerOptions): SimonServer;

package/dist/server.js

@@ -0,0 +1,234 @@
+/**
+ * `createServer`: the core assembled from its configuration, its store, the outside world (DNS, HTTP, a
+ * clock, a code sender) and any extensions. Everything outside is injectable, so tests run whole
+ * federations in one process on a fake network and a movable clock.
+ */
+import http from 'node:http';
+import https from 'node:https';
+import { bodyTooLarge, WireError } from '@agnt-sdk/simon-protocol';
+import { addKey, cancelRecovery, endGrant, getAccount, getRecovery, revokeKey, unpair } from "./account.js";
+import { authenticateAgent } from "./auth.js";
+import { iso } from "./context.js";
+import { deliver } from "./deliver.js";
+import { notFound, unavailable } from "./errors.js";
+import { Hooks } from "./extensions.js";
+import { fanOut, processArrivals, takeIntoInbox, tellInboxEvents } from "./fanout.js";
+import { errorReply, nodeListener, Router } from "./http.js";
+import { systemDns } from "./net/dns.js";
+import { guardedHttp } from "./net/fetch.js";
+import { loadPublicSuffixes } from "./net/psl.js";
+import { Outbox } from "./outbox.js";
+import { Fetcher, partRoutes } from "./parts.js";
+import { ownDocument, publicRoutes } from "./public.js";
+import { publishedRoutes } from "./published.js";
+import { RateLimiter } from "./rate.js";
+import { recover, register } from "./register.js";
+import { Resolver } from "./resolver.js";
+import { send, sendAs } from "./send.js";
+import { sendSignal, signal } from "./signal.js";
+import { Changes, sent, sync } from "./sync.js";
+import { StoreCapacityError } from "./store/store.js";
+import { WebhookPoster, webhookRoutes } from "./webhooks.js";
+import { startWorker } from "./worker.js";
+/** Uploads no message names are kept this long, so an agent can send the message after uploading. */
+const UPLOAD_GRACE_MS = 48 * 3600_000;
+/**
+ * Connections: headers within 10 s and a whole request within two minutes (a part of 25 MiB at 200 KiB/s),
+ * idle keep-alive connections closed after `config.keepAliveSeconds`, and at most `config.maxConnections`
+ * at once, so a client holding connections open (slowloris) cannot exhaust the server.
+ */
+const HTTP_OPTIONS = { headersTimeout: 10_000, requestTimeout: 120_000 };
+/** Passes `work()` runs at most to let one burst of work settle. */
+const SETTLE_PASSES = 10;
+const defaultLog = (level, message, fields) => {
+    if (level !== 'debug')
+        console.error(JSON.stringify({ time: new Date().toISOString(), level, message, ...fields }));
+};
+export function createServer(opts) {
+    const retiredAgentDocuments = opts.retiredAgentDocuments === undefined
+        ? (opts.config.retiredAgentDocuments ?? 'private')
+        : opts.retiredAgentDocuments;
+    if (retiredAgentDocuments !== 'public' && retiredAgentDocuments !== 'private')
+        throw new TypeError('retiredAgentDocuments is public or private.');
+    const { config, store } = opts;
+    const now = opts.now ?? (() => new Date());
+    const log = opts.log ?? defaultLog;
+    const dns = opts.dns ?? systemDns({ doh: config.dohResolvers, servers: config.dnsServers });
+    const outbound = opts.http ?? guardedHttp({ dns, dev: config.dev, trustedNetworks: config.trustedNetworks });
+    const deferred = new Set();
+    let worker = null;
+    let docCache = null;
+    const ctx = {
+        config,
+        store,
+        now,
+        log,
+        http: outbound,
+        resolver: new Resolver({
+            config,
+            store,
+            http: outbound,
+            dns,
+            now,
+            log,
+            ownDocument: () => (docCache ??= ownDocument(ctx)),
+            localAgent: async (address) => {
+                const agent = await store.agentByAddress(address);
+                return agent && !agent.retiredAt ? { kind: agent.kind, keys: agent.keys } : null;
+            },
+            publicSuffixes: config.publicSuffixFile ? loadPublicSuffixes(config.publicSuffixFile) : undefined,
+            chargeCarrier: carrier => ctx.rate.hit('carrierLookup', carrier),
+        }),
+        rate: new RateLimiter(config.rates, now, config.rateExemptNetworks),
+        hooks: new Hooks(opts.extensions ?? [], () => api),
+        mailbox: opts.mailbox !== undefined
+            ? opts.mailbox
+            : config.dev
+                ? async (address, { type, ...note }) => 
+                // Logged, never sent: a conformance run reads the codes from the `register code` lines.
+                log('info', `${type === 'code' ? 'register code' : type} (development: not sent)`, { address, ...note })
+                : null,
+        changes: new Changes(),
+        wake: () => worker?.wake(),
+        defer(task) {
+            const p = task()
+                .catch(e => log('error', 'deferred work failed', { error: String(e) }))
+                .finally(() => deferred.delete(p));
+            deferred.add(p);
+        },
+    };
+    const api = {
+        config,
+        store,
+        now,
+        log,
+        authenticate: req => authenticateAgent(ctx, req),
+        async admit(address, id) {
+            const record = await store.message(id);
+            return !!record && takeIntoInbox(ctx, address, record);
+        },
+        async offer(address, id) {
+            const record = await store.message(id);
+            return !!record && fanOut(ctx, record, [address], {});
+        },
+        send: (message, hints) => sendAs(ctx, message, hints),
+        retire: address => store.retireAgent(address, iso(now())),
+    };
+    const router = new Router();
+    const core = (method, path, handle) => router.add({ method, path, handle: req => handle(ctx, req) });
+    core('POST', '/simon/register', register);
+    core('GET', '/simon/account', getAccount);
+    core('POST', '/simon/recovery', recover);
+    core('GET', '/simon/recovery', getRecovery);
+    core('POST', '/simon/keys', addKey);
+    core('DELETE', '/simon/keys/:key', revokeKey);
+    core('DELETE', '/simon/grants/:id', endGrant);
+    core('POST', '/simon/recovery/cancel', cancelRecovery);
+    core('POST', '/simon/unpair', unpair);
+    core('POST', '/simon/send', send);
+    core('GET', '/simon/sync', sync);
+    core('GET', '/simon/sent/:id', sent);
+    core('POST', '/simon/deliver', deliver);
+    core('POST', '/simon/signal', signal);
+    core('POST', '/simon/send-signal', sendSignal);
+    for (const route of [
+        ...publicRoutes(ctx, retiredAgentDocuments),
+        ...publishedRoutes(ctx),
+        ...partRoutes(ctx),
+        ...webhookRoutes(ctx),
+        ...ctx.hooks.routes,
+    ]) {
+        router.add(route);
+    }
+    const bodyLimit = (method, path) => router.match(method, path)?.route.maxBody ?? config.limits.requestBodyBytes;
+    async function handle(req) {
+        try {
+            ctx.rate.hitClient('request', req.ip);
+            const match = router.match(req.method, req.path);
+            if (!match)
+                throw notFound();
+            const limit = match.route.maxBody ?? config.limits.requestBodyBytes;
+            if (req.body.length > limit)
+                throw bodyTooLarge(limit);
+            return await match.route.handle({ ...req, params: match.params }, api);
+        }
+        catch (e) {
+            if (e instanceof StoreCapacityError)
+                return errorReply(unavailable('The server is temporarily at capacity.', 60));
+            if (e instanceof WireError)
+                return errorReply(e);
+            log('error', 'request failed', { method: req.method, path: req.path, error: String(e?.stack ?? e) });
+            return errorReply(new WireError(500, 'internal', 'This server failed; try again later.'));
+        }
+    }
+    const outbox = new Outbox(ctx);
+    const fetcher = new Fetcher(ctx);
+    const webhooks = new WebhookPoster(ctx);
+    const settle = async () => {
+        while (deferred.size)
+            await Promise.all(deferred);
+    };
+    const drain = async (step) => {
+        let total = 0;
+        for (let n; (n = await step(ctx)) > 0;)
+            total += n;
+        return total;
+    };
+    /** Every stage of background work, each on its own: one that fails stops no other. Returns the work begun. */
+    const pass = async () => {
+        let begun = 0;
+        const stages = [
+            () => drain(processArrivals),
+            () => drain(tellInboxEvents),
+            () => fetcher.tick(),
+            () => outbox.tick(),
+            () => webhooks.tick(),
+        ];
+        for (const stage of stages) {
+            begun += await stage().catch(e => (log('error', 'worker stage failed', { error: String(e) }), 0));
+        }
+        return begun;
+    };
+    const sweep = () => store.sweep(iso(now()), iso(new Date(now().getTime() - UPLOAD_GRACE_MS)));
+    if (opts.worker ?? true) {
+        worker = startWorker(async () => void (await pass()), async () => void (await sweep()), e => log('error', 'worker pass failed', { error: String(e) }));
+    }
+    const listener = nodeListener({ bodyLimit, handle }, config);
+    let httpServer = null;
+    return {
+        api,
+        handle,
+        listener,
+        listen(port = config.port, host = config.listenHost ?? undefined) {
+            const options = { ...HTTP_OPTIONS, keepAliveTimeout: config.keepAliveSeconds * 1000 };
+            httpServer = config.tls
+                ? https.createServer({ ...options, cert: config.tls.cert, key: config.tls.key }, listener)
+                : http.createServer(options, listener);
+            httpServer.maxConnections = config.maxConnections;
+            return new Promise((resolve, reject) => {
+                httpServer.once('error', reject);
+                httpServer.listen(port, host, () => resolve(httpServer.address().port));
+            });
+        },
+        async work() {
+            for (let i = 0; i < SETTLE_PASSES; i++) {
+                const begun = await pass();
+                await Promise.all([outbox.idle(), fetcher.idle(), webhooks.idle(), settle()]);
+                if (!begun)
+                    return;
+            }
+        },
+        sweep,
+        async close() {
+            ctx.changes.close();
+            await worker?.stop();
+            await new Promise(resolve => {
+                if (!httpServer)
+                    return resolve();
+                httpServer.close(() => resolve());
+                httpServer.closeAllConnections();
+            });
+            await Promise.all([outbox.idle(), fetcher.idle(), webhooks.idle(), settle()]);
+        },
+    };
+}

package/dist/signal.d.ts

@@ -0,0 +1,5 @@
+import { type Context } from './context.ts';
+import { type Reply, type Request } from './http.ts';
+export declare function signal(ctx: Context, req: Request): Promise<Reply>;
+/** A signed-in client asks its server to carry a transient signal to parties of a held message. */
+export declare function sendSignal(ctx: Context, req: Request): Promise<Reply>;

package/dist/signal.js

@@ -0,0 +1,137 @@
+/**
+ * `POST /simon/signal` (spec section 6.4): a short-lived note from another server about a message, checked in
+ * the section's order, answering the first failure:
+ *
+ *   1-3  body size and parse, shape, and the signal for this server, with no lookup     (parseSignal)
+ *   4    the `from` domain resolves to another server                                  (403 otherwise)
+ *   5    the signal verifies with that server's keys valid now
+ *   6    every recipient on a domain served here
+ *   7    `at` within 300 seconds
+ *   8    202, whatever happens next
+ *
+ * After the answer, which signals reach whom is this server's own policy (any server may drop any signal):
+ * this one passes a signal to a recipient here who holds the message it is about, from that message's author
+ * or one of its recipients, and drops the rest (docs/REFERENCE-SERVER.md). Nothing
+ * keeps it beyond five minutes: it enters the recipient's sync stream and is told to the extensions' `signal` listeners, which show it now or never, and is then gone.
+ */
+import { canonicalBytes, checkServed, checkSignalFreshness, domainOf, forbidden, invalid, isAddress, isHeaderName, isJsonObject, parseJson, signSignal, parseSignal, signedByAny, signingBytes, } from '@agnt-sdk/simon-protocol';
+import { authenticateAgent } from "./auth.js";
+import { conflict } from "./errors.js";
+import { iso, later } from "./context.js";
+import { servedDomains } from "./deliver.js";
+import { json } from "./http.js";
+import { clientKey, networkKey } from "./net/ip.js";
+import { changed } from "./sync.js";
+const ACCEPTED = { accepted: true };
+export async function signal(ctx, req) {
+    const client = clientKey(req.ip);
+    const charge = () => ctx.rate.hit('lookup', client);
+    const { origin, dev: allowHttp, limits } = ctx.config;
+    const s = parseSignal(req.body, { origin, allowHttp }, limits);
+    const domain = domainOf(s.from);
+    const peer = await ctx.resolver.peer(domain, charge);
+    if (peer.outcome !== 'server' || peer.server === origin) {
+        throw forbidden('bad_signature', `${domain} names no other SIMON server, so no signal from it verifies.`);
+    }
+    const failures = `${client} ${peer.server}`;
+    ctx.rate.check('badSignature', failures);
+    const bytes = signingBytes('SIMON-SIGNAL', s);
+    const signs = (doc) => !!doc && signedByAny(doc.keys, ctx.now(), bytes, s.signature);
+    if (!signs(peer.document) && !signs(await ctx.resolver.serverDocument(peer.server, { refresh: true, charge }))) {
+        ctx.rate.hit('badSignature', failures);
+        throw forbidden('bad_signature', `The signal is not signed by a key of ${peer.server} valid now.`);
+    }
+    ctx.rate.hit('deliver', peer.server);
+    const carrier = {
+        carrier: peer.server,
+        network: networkKey(req.ip),
+        charge: () => ctx.rate.hit('carrierLookup', peer.server),
+    };
+    checkServed(s.to, await servedDomains(ctx, s.to, carrier), 'to');
+    checkSignalFreshness(s, ctx.now());
+    ctx.defer(() => pass(ctx, s));
+    return json(ACCEPTED, 202);
+}
+/** Tell the listeners of each recipient here who holds the message the signal is about, from a party to it. */
+async function pass(ctx, s) {
+    const record = await ctx.store.message(s.about);
+    if (!record || !(record.message.from === s.from || record.message.to.includes(s.from)))
+        return;
+    for (const recipient of s.to) {
+        const agent = await ctx.store.agentByAddress(recipient);
+        if (!agent || agent.retiredAt)
+            continue;
+        if (record.message.from === recipient || (await ctx.store.inInbox(recipient, record.id))) {
+            await ctx.store.holdSignal(recipient, { type: s.type, from: s.from, about: s.about, at: s.at }, later(ctx.now(), 300_000), iso(ctx.now()));
+            await changed(ctx, recipient);
+            await ctx.hooks.emit('signal', { recipient, signal: s });
+        }
+    }
+}
+/** A signed-in client asks its server to carry a transient signal to parties of a held message. */
+export async function sendSignal(ctx, req) {
+    const agent = await authenticateAgent(ctx, req);
+    const body = parseJson(req.body);
+    if (!isJsonObject(body) ||
+        !isHeaderName(body.type) ||
+        typeof body.about !== 'string' ||
+        !/^[0-9a-f]{64}$/.test(body.about) ||
+        !Array.isArray(body.to) ||
+        !body.to.length ||
+        body.to.length > ctx.config.limits.recipients ||
+        !body.to.every(isAddress) ||
+        new Set(body.to).size !== body.to.length)
+        throw invalid('A signal names a type, message id and distinct recipient addresses.');
+    const type = body.type, about = body.about, to = body.to;
+    ctx.rate.hit('send', agent.address);
+    const record = await ctx.store.message(about);
+    if (!record || !(record.message.from === agent.address || (await ctx.store.inInbox(agent.address, about)))) {
+        return json(ACCEPTED, 202);
+    }
+    const parties = new Set([record.message.from, ...record.message.to]);
+    const recipients = to.filter(address => parties.has(address) && address !== agent.address);
+    if (!(await ctx.resolver.servesHere(domainOf(agent.address)))) {
+        throw conflict('address_not_served', 'This address is no longer served here.');
+    }
+    const at = iso(ctx.now());
+    // Validate the complete signed shape and canonical size before accepting, without a recipient lookup.
+    const sample = signSignal({ type, from: agent.address, to, about, at, server: ctx.config.origin }, ctx.config.serverKey);
+    parseSignal(canonicalBytes(sample), { origin: ctx.config.origin, allowHttp: ctx.config.dev }, ctx.config.limits);
+    ctx.defer(async () => {
+        const groups = new Map();
+        const charge = () => ctx.rate.hit('lookup', clientKey(req.ip));
+        for (const recipient of recipients) {
+            try {
+                const resolved = await ctx.resolver.resolve(domainOf(recipient), { charge });
+                if (resolved.outcome !== 'server')
+                    continue;
+                const group = groups.get(resolved.server) ?? [];
+                group.push(recipient);
+                groups.set(resolved.server, group);
+            }
+            catch {
+                /* Transient signals may be dropped. */
+            }
+        }
+        for (const [server, to] of groups) {
+            try {
+                const s = signSignal({ type, from: agent.address, to, about, at, server }, ctx.config.serverKey);
+                if (server === ctx.config.origin)
+                    await pass(ctx, s);
+                else
+                    await ctx.http.request({
+                        method: 'POST',
+                        url: `${server}/simon/signal`,
+                        headers: { 'content-type': 'application/json' },
+                        body: canonicalBytes(s),
+                        maxBytes: 16_384,
+                        timeoutMs: 10_000,
+                    });
+            }
+            catch {
+                /* No retries: a signal is useful only now. */
+            }
+        }
+    });
+    return json(ACCEPTED, 202);
+}

package/dist/store/contract.d.ts

@@ -0,0 +1,4 @@
+import type { Store, RetractionCapacity } from './store.ts';
+export declare function storeContract(name: string, make: () => Store | Promise<Store>): void;
+/** Host admission boundary tests; factories supply the same options to their adapter constructor. */
+export declare function retractionCapacityContract(name: string, make: (limits: Partial<RetractionCapacity>) => Store | Promise<Store>): void;