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

package/dist/account.js

@@ -0,0 +1,244 @@
+/**
+ * The agent's address and keys (CLIENT.md), beside `register` (register.ts):
+ *
+ *   GET    /simon/account           the agent's address, keys, grants and pending recovery
+ *   POST   /simon/keys              a key added, by the new key's proof
+ *   DELETE /simon/keys/<key>        a key revoked: by itself or a key added before it, never the agent's last
+ *   DELETE /simon/grants/<id>       none: this server keeps no key to sign for an agent, so it offers no grants
+ *   POST   /simon/recovery/cancel   a pending recovery cancelled: by a key the agent held before it started,
+ *                                  once in 30 days, or by the cancel code sent to the address
+ *   POST   /simon/unpair            a key principal's unpairing: the address retires, whatever its keys say
+ *
+ * A cancel by code and an unpairing are authorised by what they carry, so any key may sign them (spec
+ * section 8, "Exceptions"); every other call is signed by a key the agent holds. Ranking keys by age and
+ * letting a key cancel once in 30 days are this server's practice, CLIENT.md's "Recommended host practice".
+ */
+import crypto from 'node:crypto';
+import { addKeyProofString, canonicalBytes, invalid, isJsonObject, isPublicKey, normalizeAddress, parseJson, readSignedHeaders, unauthorized, verify, verifyUnpairing, WireError, } from '@agnt-sdk/simon-protocol';
+import { authenticateAgent, authenticateAgentKey, checkActor, verifyAnyKey } from "./auth.js";
+import { iso } from "./context.js";
+import { badRequest, conflict, notFound } from "./errors.js";
+import { json } from "./http.js";
+import { agentDocument } from "./public.js";
+/** The value scope of an address's pending recovery. */
+export const RECOVERY = 'recovery';
+/**
+ * The value scope of a cancel code, by the address and the code's hash: the nonce of the recovery it
+ * cancels. A recovery may have several, one for each time the address was told of it.
+ */
+export const CANCEL_CODE = 'recovery-cancel-code';
+/** The mark scope of an address whose recovery a key cancelled, kept 30 days. */
+const KEY_CANCELLED = 'recovery-cancelled-by-key';
+const KEY_CANCEL_MS = 30 * 86_400_000;
+const LABEL_CHARACTERS = 64;
+/**
+ * A body of these calls: a JSON object whose members named in `members` are strings when present. Other
+ * members are ignored, unless an extension defines them.
+ */
+export function readBody(bytes, members) {
+    const body = parseJson(bytes);
+    if (!isJsonObject(body))
+        throw invalid('The body is a JSON object.', { field: 'body' });
+    for (const name of members) {
+        if (body[name] !== undefined && typeof body[name] !== 'string') {
+            throw invalid(`${name} is a string when present.`, { field: name });
+        }
+    }
+    return body;
+}
+export const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
+/** Whether `code` is the one whose SHA-256 is `hash`, compared in constant time. */
+export const matches = (code, hash) => crypto.timingSafeEqual(Buffer.from(sha256(code), 'hex'), Buffer.from(hash, 'hex'));
+/** Whether a key may cancel a recovery starting now: not within 30 days after a key cancelled one. */
+export const keysMayCancel = async (ctx, address) => {
+    const now = iso(ctx.now());
+    const cancelled = await ctx.store.value('recovery-key-cancelled-at', address, now);
+    const agent = await ctx.store.agentByAddress(address);
+    const recent = agent?.recoveryKeyCancelledAt;
+    return (!(await ctx.store.marked(KEY_CANCELLED, address, now)) &&
+        !(await ctx.store.marked('recovery-key-cancelled', address, now)) &&
+        !(cancelled && Date.parse(cancelled) > ctx.now().getTime() - KEY_CANCEL_MS) &&
+        !(recent && Date.parse(recent) > ctx.now().getTime() - KEY_CANCEL_MS));
+};
+/** Evaluate the exact final signed projection inside the Store's atomic key admission. */
+export function canPublishAgent(ctx, agent) {
+    try {
+        const doc = agentDocument(ctx, agent);
+        const allActive = agent.keys.filter(k => k.revoked === null || Date.parse(k.revoked) > ctx.now().getTime());
+        return (doc.keys.length <= 32 &&
+            canonicalBytes(doc).length <= 131072 &&
+            allActive.every(k => doc.keys.some(listed => listed.key === k.key)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether `signer` may cancel a recovery: a key the agent held when it started and holds still. */
+function mayCancel(recovery, agent, signer, now) {
+    const key = agent.keys.find(k => k.key === signer);
+    return (!recovery.keyCancelBlocked &&
+        recovery.byKey === true &&
+        typeof recovery.startedAt === 'string' &&
+        key !== undefined &&
+        (!agent.authorizedKeys || agent.authorizedKeys.includes(signer)) &&
+        (key.revoked === null || Date.parse(key.revoked) > now.getTime()) &&
+        Date.parse(key.added) <= Date.parse(recovery.startedAt));
+}
+/** The account as it stands, for the key that asked: `cancellable` says whether it may cancel the recovery. */
+export async function account(ctx, agent, signer) {
+    const recovery = await ctx.store.value(RECOVERY, agent.address, iso(ctx.now()));
+    return json({
+        address: agent.address,
+        keys: agent.keys,
+        grants: [],
+        recovery: recovery && {
+            completesAt: recovery.completesAt,
+            cancellable: mayCancel(recovery, agent, signer, ctx.now()),
+        },
+    });
+}
+/** The agent's state as it stands after a call that changed it. */
+const accountNow = async (ctx, address, signer) => account(ctx, (await ctx.store.agentByAddress(address)), signer);
+export async function getAccount(ctx, req) {
+    const { agent, key } = await authenticateAgentKey(ctx, req);
+    return account(ctx, agent, key.key);
+}
+/** A device's key added with its own proof, so no agent lists a key it does not hold. */
+export async function addKey(ctx, req) {
+    const { agent, key: signer } = await authenticateAgentKey(ctx, req);
+    const body = readBody(req.body, ['key', 'proof', 'label']);
+    const key = body.key;
+    if (!isPublicKey(key))
+        throw invalid('key is a key of an algorithm this server implements.', { field: 'key' });
+    if (body.label !== undefined && [...body.label].length > LABEL_CHARACTERS) {
+        throw invalid(`label is at most ${LABEL_CHARACTERS} characters.`, { field: 'label' });
+    }
+    if (!verify(key, addKeyProofString(agent.address, key), body.proof)) {
+        throw unauthorized('bad_proof', "proof is the new key's signature over the add-key string.", ctx.now(), {
+            proofString: addKeyProofString(agent.address, key),
+        });
+    }
+    const held = agent.keys.find(k => k.key === key);
+    if (held) {
+        if (held.revoked !== null)
+            throw conflict('key_in_use', 'That key was revoked, and a revoked key never returns.');
+        return account(ctx, agent, signer.key);
+    }
+    const entry = { key, added: iso(ctx.now()), revoked: null };
+    if (body.label !== undefined)
+        entry.label = body.label;
+    const result = await ctx.store.addKey(agent.address, entry, ctx.config.maxAgentKeys, candidate => (!candidate.authorizedKeys || candidate.authorizedKeys.includes(signer.key)) &&
+        candidate.keys.some(k => k.key === signer.key && (k.revoked === null || Date.parse(k.revoked) > ctx.now().getTime())) &&
+        candidate.keys.filter(k => k.revoked === null || Date.parse(k.revoked) > ctx.now().getTime()).length <=
+            ctx.config.maxAgentKeys &&
+        canPublishAgent(ctx, candidate));
+    if (result === 'too_many_keys') {
+        throw badRequest('too_many_keys', 'The key addition exceeds active-key, stored-history or published-document bounds.');
+    }
+    // This server's policy: a key serves one address, forever, so no reader can link two addresses by it.
+    if (result === 'key_in_use')
+        throw conflict('key_in_use', 'That key belongs to another agent.');
+    return accountNow(ctx, agent.address, signer.key);
+}
+/**
+ * A key revoked at once. Keys rank by age: a key may revoke itself and any key added after it, never one
+ * added before it, so a thief who copies a newer device's key cannot evict the older ones.
+ */
+export async function revokeKey(ctx, req) {
+    const { agent, key: signer } = await authenticateAgentKey(ctx, req);
+    const rank = (key) => agent.keys.findIndex(k => k.key === key);
+    const target = agent.keys.find(k => k.key === req.params.key);
+    if (!target || target.revoked !== null)
+        throw notFound('This agent holds no such active key.');
+    if (rank(target.key) < rank(signer.key)) {
+        throw conflict('key_senior', 'A key may revoke itself and keys added after it, never one added before it.');
+    }
+    const result = await ctx.store.revokeKey(agent.address, target.key, iso(ctx.now()), candidate => (!candidate.authorizedKeys || candidate.authorizedKeys.includes(signer.key)) &&
+        candidate.keys.some(k => k.key === signer.key && (k.revoked === null || Date.parse(k.revoked) > ctx.now().getTime())));
+    if (result === 'not_found')
+        throw notFound('This agent holds no such active key.');
+    if (result === 'last_key')
+        throw conflict('last_key', "That is the agent's last active key.");
+    ctx.log('info', 'key revoked', { address: agent.address });
+    return accountNow(ctx, agent.address, signer.key);
+}
+export async function endGrant(ctx, req) {
+    await authenticateAgent(ctx, req);
+    throw notFound('This server offers no grants.');
+}
+/** A pending recovery cancelled by a key of the agent (`{}`), or by its cancel code (`{"address","cancelCode"}`). */
+export async function cancelRecovery(ctx, req) {
+    const body = readBody(req.body, ['address', 'cancelCode']);
+    if (body.cancelCode !== undefined)
+        return cancelByCode(ctx, req, body.address, body.cancelCode);
+    const { agent, key } = await authenticateAgentKey(ctx, req);
+    const now = ctx.now();
+    const recovery = await ctx.store.value(RECOVERY, agent.address, iso(now));
+    if (!recovery)
+        throw notFound('No recovery of this address is pending.');
+    if (!mayCancel(recovery, agent, key.key, now)) {
+        throw conflict('recovery_not_cancellable', 'A key may cancel a recovery only if the agent held it when the recovery started, and once in 30 days; ' +
+            'the cancel code sent to the address cancels any.');
+    }
+    if (!(await ctx.store.cancelRecovery(agent.address, recovery, iso(now), candidate => mayCancel(recovery, candidate, key.key, now), iso(now)))) {
+        throw notFound('No cancellable recovery of this address is pending.');
+    }
+    ctx.log('info', 'recovery cancelled by a key', { address: agent.address });
+    // Whoever holds the mailbox learns of it: a thief with a stolen key delays them once, never for good.
+    await ctx.mailbox?.(agent.address, { type: 'recoveryCancelled' });
+    return json({ status: 'cancelled', address: agent.address });
+}
+/**
+ * A cancel code sent with the news of a recovery cancels that recovery while it is pending. It is never
+ * locked by wrong tries, which would let anyone disarm it, and every refusal is the same 422, so no
+ * stranger learns whether an address is being recovered.
+ */
+async function cancelByCode(ctx, req, address, cancelCode) {
+    const now = ctx.now();
+    const headers = readSignedHeaders(req.headers, now, { agent: true, optionalAgent: true });
+    const named = normalizeAddress(address);
+    if (named === null)
+        throw invalid('address is the address whose recovery the code cancels.', { field: 'address' });
+    checkActor(headers, named, now);
+    await verifyAnyKey(ctx, req, headers);
+    const recovery = await ctx.store.value(RECOVERY, named, iso(now));
+    const cancels = await ctx.store.value(CANCEL_CODE, `${named}\n${sha256(cancelCode)}`, iso(now));
+    const legacyMatches = recovery?.cancelHash !== undefined && matches(cancelCode, recovery.cancelHash);
+    if (!recovery || !(legacyMatches || (recovery.nonce !== undefined && cancels === recovery.nonce))) {
+        throw new WireError(422, 'wrong_code', 'That cancel code cancels no pending recovery.');
+    }
+    if (!(await ctx.store.cancelRecovery(named, recovery, iso(now))))
+        throw new WireError(422, 'wrong_code', 'That cancel code cancels no pending recovery.');
+    ctx.log('info', 'recovery cancelled by its cancel code', { address: named });
+    return json({ status: 'cancelled', address: named });
+}
+/**
+ * A key principal ends its pairing: the address retires at once, its keys revoked, whatever they say. The
+ * unpairing is the authority, so any key may sign the request; a repeat answers as the first call did.
+ */
+export async function unpair(ctx, req) {
+    const now = ctx.now();
+    const headers = readSignedHeaders(req.headers, now, { agent: true, optionalAgent: true });
+    const body = readBody(req.body, ['address', 'unpairing']);
+    const named = normalizeAddress(body.address);
+    checkActor(headers, named, now);
+    await verifyAnyKey(ctx, req, headers);
+    const agent = named === null ? null : await ctx.store.agentByAddress(named);
+    // One answer for every refusal, with nothing in it: a principal is shown only to its agent's recipients.
+    if (!agent?.principal || !verifyUnpairing(agent.address, agent.principal, body.unpairing)) {
+        throw unauthorized('bad_proof', "unpairing is the key principal's signature over SIMON-UNPAIR, the address and the principal.", now);
+    }
+    if (!agent.retiredAt) {
+        await ctx.store.retireAgent(agent.address, iso(now), body.unpairing);
+        ctx.log('info', 'unpaired by its principal', { address: agent.address });
+    }
+    return json({ status: 'retired', address: agent.address });
+}
+/** Recovery status is reserved to a currently authorized agent key. */
+export async function getRecovery(ctx, req) {
+    const { agent, key } = await authenticateAgentKey(ctx, req);
+    const r = await ctx.store.value(RECOVERY, agent.address, iso(ctx.now()));
+    return json({
+        recovery: r ? { completesAt: r.completesAt, cancellable: mayCancel(r, agent, key.key, ctx.now()) } : null,
+    });
+}

package/dist/auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Signed requests (spec section 8): agents sign their calls here, and servers sign their part fetches. The
+ * protocol library checks the headers, the clock, the key and the signature, and asks for the nonce last;
+ * the nonce is recorded here only once the signature verified, so a request nobody could sign never uses
+ * one up. Recording is a store mark, which only one of two racing requests can set.
+ */
+import { type KeyEntry, type SignedHeaders } from '@agnt-sdk/simon-protocol';
+import { type Context } from './context.ts';
+import type { Request } from './http.ts';
+import type { Agent, AgentKey } from './store/store.ts';
+/** Check a request's signature by `entry` (null: an unknown key), then record its nonce. */
+export declare function verifySigned(ctx: Context, req: Request, headers: SignedHeaders, entry: KeyEntry | null, now?: Date): Promise<void>;
+/** The agent here that signed this request, named by its `simon-agent`, and the key it signed with; or a 401. */
+export declare function authenticateAgentKey(ctx: Context, req: Request): Promise<{
+    agent: Agent;
+    key: AgentKey;
+}>;
+/** The agent here that signed this request, named by its `simon-agent`, or a 401. */
+export declare const authenticateAgent: (ctx: Context, req: Request) => Promise<Agent>;
+/**
+ * A call authorised by what it carries rather than by its key (spec section 8, "Exceptions": register,
+ * unpair, a cancel by code) may name no agent. When it names one, that must be `address`, the address the
+ * call acts on, so the signature covers it.
+ */
+export declare function checkActor(headers: SignedHeaders, address: string | null, now: Date): void;
+/** Check the signature of such a call: any key may sign it, known here or not, and it is verified with that key. */
+export declare const verifyAnyKey: (ctx: Context, req: Request, headers: SignedHeaders) => Promise<void>;
+/**
+ * The agent, here or elsewhere, that signed this request, or a 401 (spec section 8, an agent request to
+ * another server): `simon-key` must be a key of the `simon-agent` address's agent document valid now, read
+ * from the server the address's domain resolves to. An agent here is read from the store. Looking up a
+ * stranger's domain is charged to the client, as every lookup an unauthenticated caller causes is.
+ */
+export declare function authenticateReader(ctx: Context, req: Request): Promise<string>;
+/**
+ * The origin of the server that signed this request, or a 401: `simon-key` must be a key of the
+ * `simon-server` origin's server document valid now, a document this server reads itself. Anyone can name
+ * any origin, so fetching it is charged to the client, as every lookup an unauthenticated caller causes is.
+ */
+export declare function authenticateServer(ctx: Context, req: Request): Promise<string>;
+export declare const isServerSigned: (req: Request) => boolean;
+export declare const isAgentSigned: (req: Request) => boolean;

package/dist/auth.js

@@ -0,0 +1,96 @@
+/**
+ * Signed requests (spec section 8): agents sign their calls here, and servers sign their part fetches. The
+ * protocol library checks the headers, the clock, the key and the signature, and asks for the nonce last;
+ * the nonce is recorded here only once the signature verified, so a request nobody could sign never uses
+ * one up. Recording is a store mark, which only one of two racing requests can set.
+ */
+import { actorOf, checkSignedRequest, domainOf, nonceExpiry, readSignedHeaders, unauthorized, } from '@agnt-sdk/simon-protocol';
+import { iso } from "./context.js";
+import { clientKey } from "./net/ip.js";
+const nonceId = (h) => `${h['simon-key']}\n${h['simon-nonce']}`;
+/** Check a request's signature by `entry` (null: an unknown key), then record its nonce. */
+export async function verifySigned(ctx, req, headers, entry, now = ctx.now()) {
+    await checkSignedRequest({ method: req.method, origin: ctx.config.origin, actor: actorOf(req.headers), target: req.target, body: req.body }, headers, { now, entry, nonceSeen: () => ctx.store.marked('nonce', nonceId(headers), iso(now)) });
+    // Kept until the request's own timestamp leaves the window, so no replay inside it ever finds it gone.
+    const expires = new Date(nonceExpiry(headers['simon-timestamp'])).toISOString();
+    if (!(await ctx.store.mark('nonce', nonceId(headers), expires, iso(now)))) {
+        throw unauthorized('replayed_request', 'This key already used this nonce inside the window.', now);
+    }
+}
+/** The agent here that signed this request, named by its `simon-agent`, and the key it signed with; or a 401. */
+export async function authenticateAgentKey(ctx, req) {
+    const headers = readSignedHeaders(req.headers, ctx.now(), { agent: true });
+    const agent = await ctx.store.agentByAddress(headers['simon-agent']);
+    const now = ctx.now();
+    const held = agent?.keys.find(k => k.key === headers['simon-key']) ?? null;
+    const authorized = agent && !agent.retiredAt && (!agent.authorizedKeys || agent.authorizedKeys.includes(headers['simon-key']));
+    // Preserve a recorded revocation's diagnostic only when it must reject at this same verification time.
+    // A retired or privately excluded key whose historical interval is still open remains unknown here.
+    const revoked = held?.revoked != null && Date.parse(held.revoked) <= now.getTime();
+    const key = authorized || revoked ? held : null;
+    await verifySigned(ctx, req, headers, key, now);
+    return { agent: agent, key: key };
+}
+/** The agent here that signed this request, named by its `simon-agent`, or a 401. */
+export const authenticateAgent = async (ctx, req) => (await authenticateAgentKey(ctx, req)).agent;
+/**
+ * A call authorised by what it carries rather than by its key (spec section 8, "Exceptions": register,
+ * unpair, a cancel by code) may name no agent. When it names one, that must be `address`, the address the
+ * call acts on, so the signature covers it.
+ */
+export function checkActor(headers, address, now) {
+    if (headers['simon-agent'] !== undefined && headers['simon-agent'] !== address) {
+        throw unauthorized('signature_required', 'simon-agent names another address than the one this call acts on.', now, {
+            header: 'simon-agent',
+        });
+    }
+}
+/** Check the signature of such a call: any key may sign it, known here or not, and it is verified with that key. */
+export const verifyAnyKey = (ctx, req, headers) => verifySigned(ctx, req, headers, { key: headers['simon-key'], added: iso(ctx.now()), revoked: null });
+/**
+ * The agent, here or elsewhere, that signed this request, or a 401 (spec section 8, an agent request to
+ * another server): `simon-key` must be a key of the `simon-agent` address's agent document valid now, read
+ * from the server the address's domain resolves to. An agent here is read from the store. Looking up a
+ * stranger's domain is charged to the client, as every lookup an unauthenticated caller causes is.
+ */
+export async function authenticateReader(ctx, req) {
+    const now = ctx.now();
+    const headers = readSignedHeaders(req.headers, now, { agent: true });
+    const address = headers['simon-agent'];
+    const charge = () => ctx.rate.hit('lookup', clientKey(req.ip));
+    const r = await ctx.resolver.resolve(domainOf(address), { charge });
+    let keys = [];
+    if (r.outcome === 'server') {
+        if (r.server === ctx.config.origin) {
+            // This host's current authorization can end before a preserved historical revocation timestamp.
+            const agent = await ctx.store.agentByAddress(address);
+            if (agent && !agent.retiredAt)
+                keys = agent.keys.filter(k => !agent.authorizedKeys || agent.authorizedKeys.includes(k.key));
+        }
+        else {
+            const find = async (refresh) => (await ctx.resolver.agentKeys(address, r.server, refresh, charge))?.keys ?? [];
+            keys = await find(false);
+            if (!keys.some(k => k.key === headers['simon-key']))
+                keys = await find(true);
+        }
+    }
+    await verifySigned(ctx, req, headers, keys.find(k => k.key === headers['simon-key']) ?? null);
+    return address;
+}
+/**
+ * The origin of the server that signed this request, or a 401: `simon-key` must be a key of the
+ * `simon-server` origin's server document valid now, a document this server reads itself. Anyone can name
+ * any origin, so fetching it is charged to the client, as every lookup an unauthenticated caller causes is.
+ */
+export async function authenticateServer(ctx, req) {
+    const now = ctx.now();
+    const headers = readSignedHeaders(req.headers, now, { server: true, allowHttp: ctx.config.dev });
+    const origin = headers['simon-server'];
+    const charge = () => ctx.rate.hit('lookup', clientKey(req.ip));
+    const find = async (opts = {}) => (await ctx.resolver.serverDocument(origin, { ...opts, charge }))?.keys.find(k => k.key === headers['simon-key']) ??
+        null;
+    await verifySigned(ctx, req, headers, (await find()) ?? (await find({ refresh: true })));
+    return origin;
+}
+export const isServerSigned = (req) => req.headers['simon-server'] !== undefined;
+export const isAgentSigned = (req) => req.headers['simon-agent'] !== undefined;

package/dist/config.d.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 { type KeyObject } from 'node:crypto';
+import { type Limits } from '@agnt-sdk/simon-protocol';
+import { type Network } from './net/ip.ts';
+/** A limit of `limit` events per `seconds`, per key. */
+export interface Rate {
+    limit: number;
+    seconds: number;
+}
+/** What each rate counts, and per what. */
+export declare const DEFAULT_RATES: {
+    /** Every request, per client IP (IPv6 by /64). */
+    request: {
+        limit: number;
+        seconds: number;
+    };
+    /** New registrations, per client IP. */
+    register: {
+        limit: number;
+        seconds: number;
+    };
+    /** Codes asked for, per address. */
+    code: {
+        limit: number;
+        seconds: number;
+    };
+    /** Codes asked for, per client IP, so no one client spends the allowance of every address. */
+    codeClient: {
+        limit: number;
+        seconds: number;
+    };
+    /** Messages sent, per agent. */
+    send: {
+        limit: number;
+        seconds: number;
+    };
+    /** Distinct recipient domains written to, per agent: what spam needs most. */
+    destinations: {
+        limit: number;
+        seconds: number;
+    };
+    /** Part uploads, per agent. */
+    upload: {
+        limit: number;
+        seconds: number;
+    };
+    /** Deliveries and signals past the signature check, per carrying server, repeats included. */
+    deliver: {
+        limit: number;
+        seconds: number;
+    };
+    /**
+     * 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: number;
+        seconds: number;
+    };
+    /**
+     * 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: number;
+        seconds: number;
+    };
+    /**
+     * 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: number;
+        seconds: number;
+    };
+    /** Envelope or message signatures that failed, per (client IP, claimed server), before any more work. */
+    badSignature: {
+        limit: number;
+        seconds: number;
+    };
+    /**
+     * 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: number;
+        seconds: number;
+    };
+};
+export type RateName = keyof typeof DEFAULT_RATES;
+export interface Config {
+    origin: string;
+    dev: boolean;
+    hostedDomains: string[];
+    leaseDomain: string | null;
+    serverKey: KeyObject;
+    nextServerKey: KeyObject | null;
+    database: string;
+    port: number;
+    trustedClaimServers: string[];
+    dohResolvers: string[];
+    /** DNS servers c-ares asks instead of the system's (a tailnet's resolver, for one); empty for the system's. */
+    dnsServers: string[];
+    rates: Record<RateName, Rate>;
+    /**
+     * Networks whose clients the per-client `request`, `register`, `codeClient` and `agentMiss` rates do not count: a
+     * service that registers and speaks for many agents from a few addresses. Per-agent and per-address
+     * rates still apply.
+     */
+    rateExemptNetworks: Network[];
+    keyChangeHoldSeconds: number;
+    /** How long a code recovery waits when the agent still holds a valid key; 0 recovers at once. */
+    recoveryWaitSeconds: number;
+    /** Connections the HTTP server serves at once; more are closed as they arrive. */
+    maxConnections: number;
+    retentionDays: number;
+    /** How long `sync` shows what entered an agent's stream, published as `syncDays` (CLIENT.md sync). */
+    syncDays: number;
+    /** The limits this server publishes and enforces. */
+    limits: Limits;
+    /**
+     * Bytes of parts fetched from one carrying server per hour, counted at each attempt whatever came of it,
+     * so the budget never depends on whether a recipient here admitted the message. A fetch past it waits.
+     */
+    fetchBytesPerHour: number;
+    /**
+     * This server's bound on everything in an envelope but its message, in canonical bytes (docs/REFERENCE-SERVER.md).
+     * Its own limit, not a protocol rule. By default the most a spec-valid envelope can hold at its `recipients`
+     * limit (`envelopeBesideBytes`), so it never refuses one.
+     */
+    envelopeExtrasBytes: number;
+    /** Active keys one agent may hold. */
+    maxAgentKeys: number;
+    /** Development only: resolution answers by domain, consulted before DNS. */
+    devResolve: Record<string, string>;
+    /**
+     * Networks outside the public internet that outbound calls may reach, such as a Tailscale tailnet's
+     * 100.64.0.0/10. None by default: the SSRF guard then calls public addresses only.
+     */
+    trustedNetworks: Network[];
+    /** A certificate chain and private key, both PEM, to serve https directly; null serves plain http. */
+    tls: {
+        cert: string;
+        key: string;
+    } | null;
+    /** The address to listen on; null for every interface. */
+    listenHost: string | null;
+    /** A header proxies set to the client's address; null reads none, and the connection's address is the client's. */
+    clientIpHeader: string | null;
+    /**
+     * Networks whose connections are proxies that `clientIpHeader` is believed from, such as a load balancer's
+     * subnets. This machine is always one, for a tunnel's connector.
+     */
+    trustedProxies: Network[];
+    /** Seconds an idle keep-alive connection stays open. Behind a load balancer, longer than its idle timeout. */
+    keepAliveSeconds: number;
+    /** A copy of the Public Suffix List to read at startup; null for the snapshot that ships with the server. */
+    publicSuffixFile: string | null;
+    /**
+     * Whether a retired address answers its signed retired document (`public`) or the same 404 as an unknown
+     * address (`private`). Private by default; public retirement evidence is an explicit host choice.
+     */
+    retiredAgentDocuments: 'public' | 'private';
+}
+export type ConfigInput = Partial<Omit<Config, 'origin' | 'rates' | 'serverKey' | 'trustedNetworks' | 'trustedProxies' | 'rateExemptNetworks'>> & {
+    origin: string;
+    serverKey?: KeyObject;
+    rates?: Partial<Record<RateName, Rate>>;
+    /** CIDR notation, each /8 or narrower. */
+    trustedNetworks?: string[];
+    /** CIDR notation, each /8 or narrower. */
+    trustedProxies?: string[];
+    /** CIDR notation, each /8 or narrower. */
+    rateExemptNetworks?: string[];
+};
+export declare function defineConfig(input: ConfigInput): Config;
+/** The configuration the environment describes (see the table at the top of this file). */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;