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

package/dist/published.js

@@ -0,0 +1,140 @@
+/**
+ * Published messages: messages written here with an empty `to` (spec section 7), served to whoever their
+ * audience admits (readers.ts):
+ *
+ *   GET /simon/messages/<id>                  the message and its author's keys valid at its `sentAt`
+ *   GET /simon/feeds/<address>/<feed>         the author's published messages in that feed, newest first
+ *   GET /simon/messages/<id>/related          the relations to it marked listed that this server shows, newest first
+ *
+ * A message a reader may not see, an unknown one and a retired author's are answered alike: `404` for a
+ * message and its relations, an empty page for a feed. Listings page with an opaque cursor, `before`.
+ */
+import { header, invalid, MAX_CURSOR_LENGTH, MAX_LISTING_LIMIT, DEFAULT_LISTING_LIMIT, parseTimestamp, PUBLIC_RELATIONS, validAt, VERSION, } from '@agnt-sdk/simon-protocol';
+import { notFound } from "./errors.js";
+import { json } from "./http.js";
+import { askerOf, mayRead } from "./readers.js";
+/**
+ * Records read from the store for one page at most, so a listing of hidden messages costs a bounded scan. A
+ * scan that ends there ends the listing too: its next cursor would be a hidden message's.
+ */
+const MAX_SCANNED = 5000;
+/** The feed of a published message that names none (spec section 7.3). */
+const DEFAULT_FEED = 'posts';
+const CURSOR = new RegExp(`^[\\x21-\\x7e]{1,${MAX_CURSOR_LENGTH}}$`);
+const EMPTY = { messages: [], cursor: null, more: false };
+const v1Header = (m, name) => (m.v === VERSION ? header(m, name) : null);
+/** The published message written here by an agent not retired, or null. */
+async function published(ctx, id) {
+    const record = await ctx.store.message(id);
+    if (!record || record.carrier !== ctx.config.origin || record.message.to.length !== 0)
+        return null;
+    const author = await ctx.store.agentByAddress(record.message.from);
+    return author && !author.retiredAt ? record : null;
+}
+/** `before` and `limit` of a listing request. */
+function paging(req) {
+    const before = req.query.get('before');
+    if (before !== null && !CURSOR.test(before)) {
+        throw invalid(`before is a cursor this server gave: 1 to ${MAX_CURSOR_LENGTH} printable ASCII characters.`, {
+            field: 'before',
+        });
+    }
+    const limitText = req.query.get('limit');
+    const limit = limitText === null ? DEFAULT_LISTING_LIMIT : /^[0-9]{1,3}$/.test(limitText) ? Number(limitText) : 0;
+    if (limit < 1 || limit > MAX_LISTING_LIMIT) {
+        throw invalid(`limit is 1 to ${MAX_LISTING_LIMIT}.`, { field: 'limit' });
+    }
+    return { before, limit };
+}
+/**
+ * One page of a listing: the records `next` pages through, newest first, that `shows` keeps, up to `limit`.
+ * The cursor is the last record shown, never one the reader may not see, and is null at the end.
+ */
+async function listing(next, shows, before, limit) {
+    const shown = [];
+    let cursor = before;
+    scan: for (let scanned = 0; scanned < MAX_SCANNED;) {
+        const page = await next(cursor, limit + 1);
+        for (const r of page.records) {
+            scanned++;
+            cursor = r.cursor;
+            if (await shows(r.message))
+                shown.push({ cursor: r.cursor, message: r.message.message });
+            if (shown.length > limit)
+                break scan;
+        }
+        if (!page.more)
+            break;
+    }
+    const page = shown.slice(0, limit);
+    const more = shown.length > limit;
+    return { messages: page.map(s => s.message), cursor: more ? page.at(-1).cursor : null, more };
+}
+/**
+ * Whether a relation to a published message is one its author's server lists (spec section 7.4): its writer
+ * marked it `listed`, a plain reply never is; of those, the relations this server shows (PUBLIC_RELATIONS);
+ * and not retracted by its writer since.
+ */
+async function listable(ctx, author, record) {
+    const rel = v1Header(record.message, 'rel');
+    if (v1Header(record.message, 'listed') !== 'yes')
+        return false;
+    if (rel === null || !PUBLIC_RELATIONS.includes(rel))
+        return false;
+    return !(await ctx.store.listingRetracted(author, record.id, record.message.from));
+}
+export function publishedRoutes(ctx) {
+    const readable = async (id, asker) => {
+        const record = await published(ctx, id);
+        return record && (await mayRead(ctx, record.message, asker)) ? record : null;
+    };
+    return [
+        {
+            method: 'GET',
+            path: '/simon/messages/:id',
+            async handle(req) {
+                const record = await readable(req.params.id, await askerOf(ctx, req));
+                if (!record)
+                    throw notFound('No published message has this id here.');
+                const author = (await ctx.store.agentByAddress(record.message.from));
+                const at = new Date(parseTimestamp(record.message.sentAt));
+                const claims = record.signedClaims
+                    ? { claims: record.signedClaims.claims, claimsSignature: record.signedClaims.signature }
+                    : {};
+                return json({
+                    message: record.message,
+                    keys: author.keys.filter(k => validAt(k, at)).map(({ key, added, revoked }) => ({ key, added, revoked })),
+                    ...claims,
+                });
+            },
+        },
+        {
+            method: 'GET',
+            path: '/simon/feeds/:address/:feed',
+            async handle(req) {
+                const { before, limit } = paging(req);
+                const { address, feed } = req.params;
+                const asker = await askerOf(ctx, req);
+                const author = await ctx.store.agentByAddress(address);
+                if (!author || author.retiredAt)
+                    return json(EMPTY);
+                const inFeed = (m) => (v1Header(m, 'feed') ?? DEFAULT_FEED).split(',').includes(feed);
+                const shows = async (r) => inFeed(r.message) && (await mayRead(ctx, r.message, asker));
+                return json(await listing((b, n) => ctx.store.published(address, b, n), shows, before, limit));
+            },
+        },
+        {
+            method: 'GET',
+            path: '/simon/messages/:id/related',
+            async handle(req) {
+                const { before, limit } = paging(req);
+                const record = await readable(req.params.id, await askerOf(ctx, req));
+                if (!record)
+                    throw notFound('No published message has this id here.');
+                const author = record.message.from;
+                const page = (b, n) => ctx.store.repliesTo(author, record.id, b, n);
+                return json(await listing(page, r => listable(ctx, author, r), before, limit));
+            },
+        },
+    ];
+}

package/dist/rate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Rate limits: fixed windows, in this process's memory. Each limit is a count per window per key; a client
+ * IP is keyed by `clientKey` (IPv6 by /64). Memory is bounded: past `maxKeys`, expired windows go first,
+ * then the oldest. A server run as several processes divides each limit by their number, or keeps these
+ * counts in a shared store.
+ */
+import type { Rate, RateName } from './config.ts';
+import { type Network } from './net/ip.ts';
+/**
+ * The rates counted per client that a client's network may be exempt from. `lookup` and `badSignature`
+ * are never exempt: they bound the work deliveries from other servers make, which no exempt client needs.
+ */
+export type ClientRateName = 'request' | 'register' | 'codeClient' | 'agentMiss';
+export declare class RateLimiter {
+    #private;
+    /** `exempt`: networks whose clients the client rates do not count, such as a hosting service's own. */
+    constructor(rates: Record<RateName, Rate>, now: () => Date, exempt?: readonly Network[], maxKeys?: number);
+    /** Count one event, or refuse with 429 when the window is full. */
+    hit(name: RateName, key: string): void;
+    /** Count one event for the client at `ip`, unless its network is exempt. */
+    hitClient(name: ClientRateName, ip: string): void;
+    /** Take back an event `hitClient` counted that turned out not to be one of what the rate counts. */
+    refundClient(name: ClientRateName, ip: string): void;
+    /** Refuse with 429 when the window is full, without counting. */
+    check(name: RateName, key: string): void;
+    /** Count only values not seen in this window (destinations, say), all or none. */
+    distinct(name: RateName, key: string, values: string[]): void;
+}

package/dist/rate.js

@@ -0,0 +1,77 @@
+import { rateLimited } from "./errors.js";
+import { clientKey, inNetworks } from "./net/ip.js";
+export class RateLimiter {
+    #windows = new Map();
+    #rates;
+    #now;
+    #maxKeys;
+    #exempt;
+    /** `exempt`: networks whose clients the client rates do not count, such as a hosting service's own. */
+    constructor(rates, now, exempt = [], maxKeys = 100_000) {
+        this.#rates = rates;
+        this.#now = now;
+        this.#exempt = exempt;
+        this.#maxKeys = maxKeys;
+    }
+    #window(name, key) {
+        const id = `${name}\n${key}`;
+        const now = this.#now().getTime();
+        let w = this.#windows.get(id);
+        if (!w || w.resetAt <= now) {
+            this.#windows.delete(id);
+            if (this.#windows.size >= this.#maxKeys)
+                this.#evict(now);
+            w = { resetAt: now + this.#rates[name].seconds * 1000, count: 0 };
+            this.#windows.set(id, w);
+        }
+        return w;
+    }
+    #evict(now) {
+        for (const [id, w] of this.#windows)
+            if (w.resetAt <= now)
+                this.#windows.delete(id);
+        for (const id of this.#windows.keys()) {
+            if (this.#windows.size < this.#maxKeys)
+                break;
+            this.#windows.delete(id);
+        }
+    }
+    #refuse(w) {
+        throw rateLimited(Math.max(1, Math.ceil((w.resetAt - this.#now().getTime()) / 1000)));
+    }
+    /** Count one event, or refuse with 429 when the window is full. */
+    hit(name, key) {
+        const w = this.#window(name, key);
+        if (w.count >= this.#rates[name].limit)
+            this.#refuse(w);
+        w.count++;
+    }
+    /** Count one event for the client at `ip`, unless its network is exempt. */
+    hitClient(name, ip) {
+        if (!inNetworks(ip, this.#exempt))
+            this.hit(name, clientKey(ip));
+    }
+    /** Take back an event `hitClient` counted that turned out not to be one of what the rate counts. */
+    refundClient(name, ip) {
+        if (inNetworks(ip, this.#exempt))
+            return;
+        const w = this.#window(name, clientKey(ip));
+        w.count = Math.max(0, w.count - 1);
+    }
+    /** Refuse with 429 when the window is full, without counting. */
+    check(name, key) {
+        const w = this.#window(name, key);
+        if (w.count >= this.#rates[name].limit)
+            this.#refuse(w);
+    }
+    /** Count only values not seen in this window (destinations, say), all or none. */
+    distinct(name, key, values) {
+        const w = this.#window(name, key);
+        w.values ??= new Set();
+        const fresh = [...new Set(values)].filter(v => !w.values.has(v));
+        if (w.values.size + fresh.length > this.#rates[name].limit)
+            this.#refuse(w);
+        for (const v of fresh)
+            w.values.add(v);
+    }
+}

package/dist/readers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Who reads a published message, and whether its audience admits them (spec section 7.1).
+ *
+ * A reader proves who it is the way an author does: it signs the request with a key of its own agent
+ * document and names itself in `simon-agent` (section 8). A request that is not signed, or whose signature
+ * fails, asks as nobody in particular, and is answered exactly as one, so a refusal tells nothing about
+ * the message.
+ *
+ * A message with no `audience` header is for anyone. One with a label is for whoever the extensions'
+ * `admitsReader` chain admits; with no extension deciding, for no one but its author.
+ */
+import { type AnyMessage } from '@agnt-sdk/simon-protocol';
+import type { Context } from './context.ts';
+import type { Request } from './http.ts';
+/** Who asks: the reader that signed, null for nobody in particular. */
+export interface Asker {
+    reader(): Promise<string | null>;
+}
+/** An asker already known: an agent here whose own signature this server checked. */
+export declare const asReader: (address: string) => Asker;
+/**
+ * Who asks, settled before anything is looked up for the request: a request naming `simon-agent` is
+ * authenticated at once, its reader's document fetched and charged to the client, whatever it asks for and
+ * whether or not anything matches, so neither the answer nor the fetches it makes tell which ids, feeds or
+ * parts hold audience-limited posts (spec section 7.1).
+ */
+export declare function askerOf(ctx: Context, req: Request): Promise<Asker>;
+/** The audience label a published version 1 message carries, or null for anyone. */
+export declare const audienceOf: (m: AnyMessage) => string | null;
+/** Whether a published message written here may be shown to this asker. */
+export declare function mayRead(ctx: Context, m: AnyMessage, asker: Asker): Promise<boolean>;

package/dist/readers.js

@@ -0,0 +1,48 @@
+/**
+ * Who reads a published message, and whether its audience admits them (spec section 7.1).
+ *
+ * A reader proves who it is the way an author does: it signs the request with a key of its own agent
+ * document and names itself in `simon-agent` (section 8). A request that is not signed, or whose signature
+ * fails, asks as nobody in particular, and is answered exactly as one, so a refusal tells nothing about
+ * the message.
+ *
+ * A message with no `audience` header is for anyone. One with a label is for whoever the extensions'
+ * `admitsReader` chain admits; with no extension deciding, for no one but its author.
+ */
+import { header, VERSION, WireError } from '@agnt-sdk/simon-protocol';
+import { authenticateReader, isAgentSigned } from "./auth.js";
+const NOBODY = { reader: async () => null };
+/** An asker already known: an agent here whose own signature this server checked. */
+export const asReader = (address) => ({ reader: async () => address });
+/**
+ * Who asks, settled before anything is looked up for the request: a request naming `simon-agent` is
+ * authenticated at once, its reader's document fetched and charged to the client, whatever it asks for and
+ * whether or not anything matches, so neither the answer nor the fetches it makes tell which ids, feeds or
+ * parts hold audience-limited posts (spec section 7.1).
+ */
+export async function askerOf(ctx, req) {
+    if (!isAgentSigned(req))
+        return NOBODY;
+    try {
+        return asReader(await authenticateReader(ctx, req));
+    }
+    catch (e) {
+        // A signature that fails asks as nobody, and so does a reader whose document could not be looked up (a
+        // client out of lookups, a pool that is full), as the spec's reader whose document cannot be read for now.
+        if (e instanceof WireError && [401, 429, 503].includes(e.status))
+            return NOBODY;
+        throw e;
+    }
+}
+/** The audience label a published version 1 message carries, or null for anyone. */
+export const audienceOf = (m) => (m.v === VERSION ? header(m, 'audience') : null);
+/** Whether a published message written here may be shown to this asker. */
+export async function mayRead(ctx, m, asker) {
+    const audience = audienceOf(m);
+    if (audience === null)
+        return true;
+    const reader = await asker.reader();
+    if (reader === m.from)
+        return true;
+    return (await ctx.hooks.admitsReader({ message: m, audience, reader })) === 'admit';
+}

package/dist/register.d.ts

@@ -0,0 +1,4 @@
+import { type Context } from './context.ts';
+import { type Reply, type Request } from './http.ts';
+export declare const register: (ctx: Context, req: Request) => Promise<Reply>;
+export declare const recover: (ctx: Context, req: Request) => Promise<Reply>;