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

package/dist/testing.d.ts

@@ -0,0 +1,38 @@
+import type { Reply, Request } from './http.ts';
+import { type Dns } from './net/dns.ts';
+import { type Http, type HttpRequest, type HttpResponse } from './net/fetch.ts';
+export declare class Clock {
+    t: number;
+    now: () => Date;
+    advance(ms: number): void;
+}
+/** TXT records by name; a name in `failing` answers SERVFAIL. */
+export declare class FakeDns implements Dns {
+    readonly records: Map<string, string[][]>;
+    readonly failing: Set<string>;
+    txt(name: string): Promise<string[][]>;
+    addresses(): Promise<string[]>;
+    point(domain: string, origin: string): void;
+}
+type Host = ((req: Request) => Promise<Reply>) | 'down';
+/** Every deadline on the fake network, at most: a tarpit costs a test this long. */
+export declare const TARPIT_MS = 150;
+/**
+ * Origins answered in-process. A request reaches the host's handler as an HTTP request would. Each host has
+ * one address, its own name unless `addresses` maps it to another, so several names can share one machine.
+ */
+export declare class FakeNet implements Http {
+    readonly hosts: Map<string, Host>;
+    readonly addresses: Map<string, string>;
+    /** The client address every request appears to come from. */
+    ip: string;
+    readonly sent: {
+        method: string;
+        url: string;
+    }[];
+    request(r: HttpRequest): Promise<HttpResponse>;
+}
+export declare function toRequest(method: string, url: URL, headers: Record<string, string>, body: Buffer, ip: string): Request;
+/** A reply's body as the node:http adapter would send it. */
+export declare const replyBody: (reply: Reply) => Buffer<ArrayBufferLike>;
+export {};

package/dist/testing.js

@@ -0,0 +1,87 @@
+/**
+ * A fake outside world, for tests of the server and of applications built on it: one movable clock, DNS
+ * answered from a map, and HTTP answered in-process by the origins registered on it.
+ *
+ *   const clock = new Clock();
+ *   const dns = new FakeDns();
+ *   const net = new FakeNet();
+ *   const server = createServer({ config, store, dns, http: net, now: clock.now, worker: false });
+ *   net.hosts.set(config.origin, req => server.handle(req));
+ *   dns.point('example.test', config.origin);
+ */
+import { canonicalize } from '@agnt-sdk/simon-protocol';
+import { DnsFailure } from "./net/dns.js";
+import { Unreachable } from "./net/fetch.js";
+export class Clock {
+    t = Date.parse('2026-10-15T12:00:00.000Z');
+    now = () => new Date(this.t);
+    advance(ms) {
+        this.t += ms;
+    }
+}
+/** TXT records by name; a name in `failing` answers SERVFAIL. */
+export class FakeDns {
+    records = new Map();
+    failing = new Set();
+    async txt(name) {
+        if (this.failing.has(name))
+            throw new DnsFailure(`${name}: SERVFAIL`);
+        return this.records.get(name) ?? [];
+    }
+    async addresses() {
+        return ['203.0.113.10'];
+    }
+    point(domain, origin) {
+        this.records.set(`_simon.${domain}`, [[`v=simon1; server=${origin}`]]);
+    }
+}
+/** Every deadline on the fake network, at most: a tarpit costs a test this long. */
+export const TARPIT_MS = 150;
+/**
+ * Origins answered in-process. A request reaches the host's handler as an HTTP request would. Each host has
+ * one address, its own name unless `addresses` maps it to another, so several names can share one machine.
+ */
+export class FakeNet {
+    hosts = new Map();
+    addresses = new Map();
+    /** The client address every request appears to come from. */
+    ip = '198.51.100.7';
+    sent = [];
+    async request(r) {
+        const url = new URL(r.url);
+        this.sent.push({ method: r.method, url: r.url });
+        const host = this.hosts.get(url.origin);
+        if (!host)
+            throw new Unreachable('absent', `no such host: ${url.host}`);
+        const address = this.addresses.get(url.hostname) ?? url.hostname;
+        if (r.avoid?.(address))
+            throw new Unreachable('refused', `${address} is avoided`, address);
+        if (host === 'down')
+            throw new Unreachable('refused', `${url.host} refuses connections`, address);
+        // Deadlines are honoured, scaled down so a test never waits long for one.
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Unreachable('timeout', `${url.host}: no answer in time`, address)), Math.min(r.timeoutMs ?? TARPIT_MS, TARPIT_MS));
+        });
+        const request = toRequest(r.method, url, r.headers ?? {}, Buffer.from(r.body ?? new Uint8Array()), this.ip);
+        const reply = await Promise.race([host(request), deadline]).finally(() => clearTimeout(timer));
+        const body = replyBody(reply);
+        if (body.length > r.maxBytes)
+            throw new Unreachable('too_large', 'answer too large');
+        return { status: reply.status, headers: { ...reply.headers }, body };
+    }
+}
+export function toRequest(method, url, headers, body, ip) {
+    return {
+        method,
+        target: url.pathname + url.search,
+        path: url.pathname,
+        query: url.searchParams,
+        params: {},
+        headers: Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v])),
+        body,
+        ip,
+    };
+}
+/** A reply's body as the node:http adapter would send it. */
+export const replyBody = (reply) => reply.bytes ?? (reply.json === undefined ? Buffer.alloc(0) : Buffer.from(canonicalize(reply.json)));

package/dist/webhooks.d.ts

@@ -0,0 +1,10 @@
+import { type Context } from './context.ts';
+import { type Route } from './http.ts';
+export declare function webhookRoutes(ctx: Context): Route[];
+/** Each delivery is leased, so a late attempt cannot settle or disable a successor's webhook. */
+export declare class WebhookPoster {
+    #private;
+    constructor(ctx: Context);
+    tick(): Promise<number>;
+    idle(): Promise<void>;
+}

package/dist/webhooks.js

@@ -0,0 +1,162 @@
+/** Verified, signed wakeups for clients that do not hold a sync connection open. */
+import crypto from 'node:crypto';
+import { canonicalBytes, invalid, signRequest } from '@agnt-sdk/simon-protocol';
+import { readBody } from "./account.js";
+import { authenticateAgent } from "./auth.js";
+import { iso, later } from "./context.js";
+import { conflict, notFound } from "./errors.js";
+import { json } from "./http.js";
+const hash = (s) => crypto.createHash('sha256').update(s).digest('hex');
+const matches = (code, expected) => {
+    const actual = Buffer.from(hash(code), 'hex'), wanted = Buffer.from(expected, 'hex');
+    return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
+};
+const LIMIT = 5, CONCURRENCY = 4, TIMEOUT_MS = 10_000, LEASE_MS = 30_000;
+const FAILURE_MS = 3 * 86_400_000;
+async function post(ctx, url, payload) {
+    const body = canonicalBytes(payload);
+    const headers = signRequest(ctx.config.serverKey, {
+        method: 'POST',
+        url,
+        body,
+        now: ctx.now().getTime(),
+        server: ctx.config.origin,
+    });
+    const res = await ctx.http.request({
+        method: 'POST',
+        url,
+        body,
+        headers: { ...headers, 'content-type': 'application/json' },
+        maxBytes: 16_384,
+        timeoutMs: TIMEOUT_MS,
+    });
+    return res.status >= 200 && res.status < 300;
+}
+export function webhookRoutes(ctx) {
+    const owned = async (id, address) => {
+        const row = await ctx.store.webhook(id);
+        if (!row || row.address !== address)
+            throw notFound();
+        return row;
+    };
+    return [
+        {
+            method: 'POST',
+            path: '/simon/webhooks',
+            async handle(req) {
+                const agent = await authenticateAgent(ctx, req);
+                ctx.rate.hit('send', agent.address);
+                const body = readBody(req.body, ['url']);
+                let url;
+                try {
+                    url = new URL(body.url ?? '');
+                }
+                catch {
+                    throw invalid('url must be an HTTPS URL.', { field: 'url' });
+                }
+                if (url.protocol !== 'https:' || url.username || url.password || url.hash || url.href.length > 2000) {
+                    throw invalid('url must be an HTTPS URL without credentials or a fragment, at most 2000 characters.', {
+                        field: 'url',
+                    });
+                }
+                const code = crypto.randomBytes(32).toString('base64url');
+                const row = {
+                    id: crypto.randomUUID(),
+                    address: agent.address,
+                    url: url.href,
+                    codeHash: hash(code),
+                    verified: false,
+                    createdAt: iso(ctx.now()),
+                    failingSince: null,
+                };
+                if (!(await ctx.store.addWebhook(row, LIMIT)))
+                    throw conflict('too_many_webhooks', `An agent holds at most ${LIMIT} webhooks.`);
+                // A failed verification post leaves an unverified row the owner may delete and recreate. It sends
+                // no wakeups, and never deletes a row that the receiver verified while the HTTP answer was delayed.
+                ctx.defer(async () => {
+                    await post(ctx, row.url, { type: 'verify', code });
+                });
+                return json({ id: row.id }, 201);
+            },
+        },
+        {
+            method: 'POST',
+            path: '/simon/webhooks/:id/verify',
+            async handle(req) {
+                const agent = await authenticateAgent(ctx, req);
+                const row = await owned(req.params.id, agent.address);
+                const { code } = readBody(req.body, ['code']);
+                if (typeof code !== 'string' || !matches(code, row.codeHash))
+                    throw invalid('The verification code does not match.', { field: 'code' });
+                await ctx.store.verifyWebhook(row.id);
+                await ctx.store.wakeWebhooks(agent.address, iso(ctx.now()));
+                ctx.wake();
+                return json({ id: row.id, verified: true });
+            },
+        },
+        {
+            method: 'DELETE',
+            path: '/simon/webhooks/:id',
+            async handle(req) {
+                const agent = await authenticateAgent(ctx, req);
+                const row = await owned(req.params.id, agent.address);
+                await ctx.store.deleteWebhook(row.id);
+                return json({ deleted: true });
+            },
+        },
+    ];
+}
+/** Each delivery is leased, so a late attempt cannot settle or disable a successor's webhook. */
+export class WebhookPoster {
+    #ctx;
+    #running = new Set();
+    #active = 0;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    async tick() {
+        const room = CONCURRENCY - this.#active;
+        if (room <= 0)
+            return 0;
+        const ctx = this.#ctx, now = ctx.now(), token = crypto.randomUUID();
+        const rows = await ctx.store.claimWebhooks(iso(now), room, later(now, 1000), {
+            token,
+            until: later(now, LEASE_MS),
+        });
+        this.#active += rows.length;
+        for (const row of rows) {
+            const task = this.#deliver(row, token)
+                .catch(error => ctx.log('error', 'webhook attempt failed', { id: row.id, error: String(error) }))
+                .finally(() => {
+                this.#active--;
+                this.#running.delete(task);
+            });
+            this.#running.add(task);
+        }
+        return rows.length;
+    }
+    async #deliver(row, token) {
+        const ctx = this.#ctx;
+        const current = await ctx.store.webhook(row.id);
+        const agent = await ctx.store.agentByAddress(row.address);
+        if (!current || !current.verified || current.url !== row.url || !agent || agent.retiredAt) {
+            await ctx.store.settleWebhook(row.id, row.failingSince, null, token, true);
+            return;
+        }
+        let success = false;
+        try {
+            success = await post(ctx, row.url, { type: 'changed', agent: row.address });
+        }
+        catch {
+            /* Retry below. */
+        }
+        const now = ctx.now();
+        const failingSince = success ? null : (row.failingSince ?? iso(now));
+        const disable = failingSince !== null && now.getTime() - Date.parse(failingSince) >= FAILURE_MS;
+        await ctx.store.settleWebhook(row.id, failingSince, success || disable ? null : later(now, 60_000), token, disable);
+    }
+    async idle() {
+        while (this.#running.size)
+            await Promise.all(this.#running);
+    }
+}

package/dist/worker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The worker loop: what happens after answers are given. Every second, and at once when woken, it runs a
+ * pass (arrivals offered, inbox events told, part fetches and deliveries started); it sweeps retention
+ * every ten minutes. It runs in the server's process by default.
+ */
+export interface Worker {
+    /** Run a pass soon. */
+    wake(): void;
+    /** Stop the loop and wait for the pass underway. */
+    stop(): Promise<void>;
+}
+export declare function startWorker(pass: () => Promise<void>, sweep: () => Promise<void>, log: (error: unknown) => void, opts?: {
+    intervalMs?: number;
+    sweepMs?: number;
+}): Worker;

package/dist/worker.js

@@ -0,0 +1,33 @@
+export function startWorker(pass, sweep, log, opts = {}) {
+    let running = null;
+    let again = false;
+    let stopped = false;
+    const run = () => {
+        if (stopped)
+            return;
+        if (running)
+            return void (again = true);
+        running = pass()
+            .catch(log)
+            .finally(() => {
+            running = null;
+            if (again) {
+                again = false;
+                run();
+            }
+        });
+    };
+    const interval = setInterval(run, opts.intervalMs ?? 1000);
+    const sweeper = setInterval(() => void sweep().catch(log), opts.sweepMs ?? 10 * 60_000);
+    interval.unref();
+    sweeper.unref();
+    return {
+        wake: () => setImmediate(run),
+        async stop() {
+            stopped = true;
+            clearInterval(interval);
+            clearInterval(sweeper);
+            await running;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@agnt-sdk/simon-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The SIMON reference server: the whole protocol and client API, hardened, with Node's standard library only, and the Store contract any storage proves itself with.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "simon",
+    "agents",
+    "ai-agents",
+    "protocol",
+    "signed-messages",
+    "server",
+    "federation"
+  ],
+  "homepage": "https://github.com/agnt-ai/simon-protocol/tree/main/server#readme",
+  "bugs": {
+    "url": "https://github.com/agnt-ai/simon-protocol/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agnt-ai/simon-protocol.git",
+    "directory": "server"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/store/contract.d.ts",
+      "default": "./dist/store/contract.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "bin": {
+    "simon-server": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=24.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@agnt-sdk/simon-protocol": "0.1.0"
+  },
+  "gitHead": "0047e948e09b664b52ab2ef690a537e0f7d9ba76"
+}