@toon-protocol/relay 2.0.2 → 2.1.0

package/dist/index.d.ts

@@ -4,14 +4,13 @@ import { WebSocket } from 'ws';
 import { SimplePool } from 'nostr-tools/pool';
 import { Context } from 'hono';
 
-/** Package version, surfaced on `GET /health`. */
-declare const VERSION = "0.1.0";
+declare const VERSION: string;
 
 /**
  * Configuration options for the Nostr relay.
  */
 interface RelayServerConfig {
-    /** Port to listen on (default: 7000) */
+    /** Port to listen on (default: 7100) */
     port: number;
     /** Host/IP to bind to (default: '0.0.0.0'). Set to '127.0.0.1' for hidden service mode. */
     host?: string;
@@ -33,12 +32,42 @@ interface RelayServerConfig {
     maxFiltersPerSubscription?: number;
     /** Path to SQLite database file (default: ':memory:' for in-memory) */
     databasePath?: string;
+    /**
+     * Enforce NIP-40 expiration on the live broadcast path (default: true).
+     *
+     * The stored-history path is enforced by the EventStore; this flag covers
+     * the other way an event reaches a subscriber — the fan-out of a freshly
+     * written event. Both are driven from the same launcher setting so a relay
+     * cannot serve an expired event on one path while hiding it on the other.
+     */
+    enforceExpiration?: boolean;
 }
 /**
  * Default relay configuration values.
  */
 declare const DEFAULT_RELAY_CONFIG: Required<RelayServerConfig>;
 
+/**
+ * Construction options shared by every EventStore implementation.
+ */
+interface EventStoreOptions {
+    /**
+     * Enforce NIP-40 expiration at serve time (default: true).
+     *
+     * When true, events past their `expiration` tag are not returned by
+     * `get()` or `query()`. Set false as a KILL SWITCH: it restores the
+     * pre-NIP-40 behaviour of serving every stored event forever, which is the
+     * only recourse if enforcement ever starves discovery (see the launcher's
+     * `enforceExpiration` docs for the failure mode this guards against).
+     */
+    enforceExpiration?: boolean;
+    /**
+     * Operator-blocked event ids (64-char lowercase hex). Blocked events are
+     * refused on write and swept from storage. See `nips/blocklist.ts` for why
+     * this is scoped to ids and to startup configuration.
+     */
+    blockedEventIds?: Iterable<string>;
+}
 /**
  * Interface for event storage backends.
  */
@@ -49,6 +78,11 @@ interface EventStore {
     get(id: string): NostrEvent | undefined;
     /** Query events matching any of the provided filters */
     query(filters: Filter[]): NostrEvent[];
+    /**
+     * Permanently drop events expired for longer than `graceSeconds` (NIP-40).
+     * Optional: a backend may serve-filter only. Returns rows removed.
+     */
+    reapExpired?(nowSeconds: number, graceSeconds?: number): number;
     /** Close the storage backend (optional) */
     close?(): void;
 }
@@ -58,9 +92,30 @@ interface EventStore {
  */
 declare class InMemoryEventStore implements EventStore {
     private events;
+    /** NIP-09 id tombstones: event id -> the pubkey that requested deletion. */
+    private deletedIds;
+    /** NIP-09 address tombstones: `<kind>:<pubkey>:<d>` -> deletion created_at. */
+    private deletedAddresses;
+    private readonly enforceExpiration;
+    private readonly blockedEventIds;
+    constructor(options?: EventStoreOptions);
     store(event: NostrEvent): void;
     get(id: string): NostrEvent | undefined;
     query(filters: Filter[]): NostrEvent[];
+    /**
+     * Drop events expired for longer than `graceSeconds` (NIP-40).
+     *
+     * @param now - Current unix time in seconds.
+     * @param graceSeconds - Extra time an expired event is kept.
+     * @returns The number of events removed.
+     */
+    reapExpired(now: number, graceSeconds?: number): number;
+    /** The NIP-01 addressable coordinate of an event, `<kind>:<pubkey>:<d>`. */
+    private static coordinateOf;
+    /** Whether a NIP-09 request already retracted this event (same author). */
+    private isRetracted;
+    /** Apply a kind:5 request to the author's OWN events only. */
+    private applyDeletion;
     /**
      * Close the storage backend (no-op for in-memory store).
      */
@@ -87,14 +142,25 @@ declare class SqliteEventStore implements EventStore {
     private deleteByPubkeyKindDTagStmt;
     private getByPubkeyKindStmt;
     private getByPubkeyKindDTagStmt;
+    private tombstoneIdStmt;
+    private getTombstoneStmt;
+    private tombstoneAddressStmt;
+    private getAddressTombstoneStmt;
+    private deleteExpiredStmt;
+    private readonly enforceExpiration;
+    private readonly blockedEventIds;
     /**
      * Create a new SqliteEventStore.
      * @param dbPath - Path to the database file. Use ':memory:' for in-memory database.
+     * @param options - Expiry-enforcement and operator-blocklist settings.
      */
-    constructor(dbPath?: string);
+    constructor(dbPath?: string, options?: EventStoreOptions);
     /**
      * Store an event in the database.
-     * Handles replaceable and parameterized replaceable events according to NIP-01.
+     *
+     * Handles replaceable and parameterized replaceable events according to
+     * NIP-01, applies NIP-09 deletion requests, and refuses events the operator
+     * has blocked or that a previous NIP-09 request already retracted.
      */
     store(event: NostrEvent): void;
     /**
@@ -107,8 +173,64 @@ declare class SqliteEventStore implements EventStore {
      * Only keeps the latest event per pubkey+kind+d-tag.
      */
     private storeParameterizedReplaceableEvent;
+    /**
+     * Bind an event to one of the prepared INSERT statements.
+     *
+     * The `expires_at` column is derived here, at the single point every write
+     * funnels through, so no insert path can forget it.
+     */
+    private runInsert;
+    /**
+     * The NIP-01 addressable coordinate of an event, `<kind>:<pubkey>:<d>`.
+     * The `d` value is the empty string for events that carry no `d` tag —
+     * which is every kind:10032 announce on the network today.
+     */
+    private static coordinateOf;
+    /**
+     * Whether a NIP-09 deletion request already retracted this event, so it
+     * must not be re-admitted.
+     *
+     * The id tombstone only bites when the arriving event's OWN pubkey matches
+     * the pubkey that asked for the deletion; otherwise anyone could pre-block
+     * an id they merely predicted. Address tombstones already carry the
+     * author's pubkey inside the coordinate.
+     */
+    private isRetracted;
+    /**
+     * Apply a NIP-09 deletion request: remove the author's own targeted events
+     * and record tombstones so a re-publish cannot resurrect them.
+     *
+     * Every statement here is scoped by `pubkey = <the requester>`, which is
+     * what makes a cross-author deletion a no-op rather than a privilege.
+     */
+    private applyDeletion;
+    /**
+     * Rows for a (kind, pubkey) pair with their parsed tags, so the caller can
+     * compare `d` values in code. SQL cannot distinguish `["d",""]` from a
+     * missing `d` tag, and both mean "the empty identifier".
+     */
+    private findByCoordinate;
+    /**
+     * NIP-40 reaper: permanently delete events whose expiration is further than
+     * `graceSeconds` in the past.
+     *
+     * The grace window is the safety net for enforcement itself. Serve-time
+     * filtering is instantly reversible (flip `enforceExpiration` off and every
+     * still-present event is served again); a DELETE is not. Keeping recently
+     * expired events on disk for a while means an operator who discovers that
+     * enforcement broke discovery can undo it without having lost the data.
+     *
+     * @param nowSeconds - Current unix time in seconds.
+     * @param graceSeconds - Extra time to keep an expired event on disk.
+     * @returns The number of rows deleted.
+     */
+    reapExpired(nowSeconds: number, graceSeconds?: number): number;
     /**
      * Retrieve an event by its ID.
+     *
+     * Returns undefined for an event that is past its NIP-40 expiration while
+     * enforcement is on, even though the row may still be on disk inside the
+     * reaper's grace window.
      */
     get(id: string): NostrEvent | undefined;
     /**
@@ -140,6 +262,190 @@ declare class SqliteEventStore implements EventStore {
  */
 declare function matchFilter(event: NostrEvent, filter: Filter): boolean;
 
+/**
+ * NIP-40 — "Expiration Timestamp".
+ *
+ * An event MAY carry `["expiration", "<unix seconds>"]`. Past that timestamp
+ * the relay SHOULD stop serving it. Until relay#137 this relay parsed no such
+ * tag and enforced nothing, so an announce that said "I am valid for ten
+ * minutes" was still handed to every discovering client a week later (two
+ * such kind:10032 announces — one of them a `g.toon.relay` from an identity
+ * that no longer exists — were live on devnet when this was written).
+ *
+ * This module is deliberately pure: parsing and the expiry predicate only.
+ * WHERE enforcement happens (serve-time filtering, the background reaper) is
+ * the storage layer's and launcher's business.
+ *
+ * @module
+ */
+
+/** The NIP-40 tag name. */
+declare const EXPIRATION_TAG = "expiration";
+/**
+ * Read an event's NIP-40 expiration timestamp, in unix seconds.
+ *
+ * FAIL-OPEN on anything malformed. A tag whose value is not a non-negative
+ * integer (empty, `"soon"`, `"1.5"`, `"-1"`, absent) yields `undefined`, i.e.
+ * "never expires" — the same treatment an event with no tag at all gets.
+ * Dropping an event because its own author wrote a bad timestamp would turn a
+ * publisher-side typo into an unrecoverable read outage, and NIP-40 asks
+ * relays to honour a valid expiration, not to police an invalid one.
+ *
+ * The FIRST syntactically valid expiration tag wins when several are present
+ * (NIP-40 does not define multi-tag behaviour; the event is signed by the
+ * author about the author's own event, so there is no adversary to defend
+ * against here — only a need to be deterministic).
+ *
+ * @param event - Any Nostr event (only `tags` is read).
+ * @returns Unix-seconds expiry, or undefined when the event never expires.
+ */
+declare function getExpiration(event: {
+    tags: string[][];
+}): number | undefined;
+/**
+ * Whether an event is past its NIP-40 expiration at `nowSeconds`.
+ *
+ * Events with no (or a malformed) expiration are never expired.
+ *
+ * @param event - The event to test.
+ * @param nowSeconds - Current unix time in seconds.
+ * @returns True when the event must no longer be served.
+ */
+declare function isExpired(event: Pick<NostrEvent, 'tags'>, nowSeconds: number): boolean;
+
+/**
+ * NIP-09 — "Event Deletion Request".
+ *
+ * A kind:5 event asks the relay to stop serving events the SAME pubkey
+ * published, named either by id (`e` tags) or by addressable coordinate
+ * (`a` tags, `<kind>:<pubkey>:<d-identifier>`).
+ *
+ * THE AUTHORIZATION RULE IS THE WHOLE NIP: a deletion request may only ever
+ * retract events signed by its own author. A kind:5 that names someone else's
+ * event id is not an error and not a partial success — the named target is
+ * simply not deleted. Anything looser turns a public relay into a surface
+ * where one key can erase another's history.
+ *
+ * This module is pure: it parses targets and answers "may this deletion
+ * request retract this event?". Applying that answer to stored rows (and
+ * remembering it, so a re-publish cannot resurrect the event) belongs to the
+ * storage layer.
+ *
+ * @module
+ */
+
+/** The NIP-09 deletion-request kind. */
+declare const DELETION_KIND = 5;
+/** Whether `kind` is a NIP-09 deletion request. */
+declare function isDeletionKind(kind: number): boolean;
+/**
+ * A NIP-01 addressable coordinate, `<kind>:<pubkey>:<d-identifier>`, as
+ * carried by a NIP-09 `a` tag.
+ */
+interface AddressCoordinate {
+    /** Event kind the coordinate addresses. */
+    kind: number;
+    /** Author pubkey (64-char lowercase hex). */
+    pubkey: string;
+    /** The `d` tag value; the empty string when the kind carries no `d`. */
+    identifier: string;
+}
+/** Targets named by a deletion request. */
+interface DeletionTargets {
+    /** Event ids from `e` tags (64-char lowercase hex, de-duplicated). */
+    ids: string[];
+    /** Coordinates from `a` tags (de-duplicated by their raw tag value). */
+    addresses: AddressCoordinate[];
+}
+/**
+ * Parse an `a`-tag value into a coordinate.
+ *
+ * @param value - Raw tag value, `<kind>:<pubkey>:<d-identifier>`.
+ * @returns The coordinate, or undefined when the value is malformed.
+ */
+declare function parseAddressCoordinate(value: string): AddressCoordinate | undefined;
+/**
+ * Collect the targets a deletion request names.
+ *
+ * Malformed tags are skipped rather than failing the whole request: a client
+ * that emits one bad `a` tag alongside three good ones still gets the three.
+ *
+ * @param event - A kind:5 event (the kind is not re-checked here).
+ * @returns De-duplicated ids and coordinates.
+ */
+declare function parseDeletionTargets(event: Pick<NostrEvent, 'tags'>): DeletionTargets;
+/**
+ * Whether `deletion` is allowed to retract `target`.
+ *
+ * Two conditions, both required:
+ *
+ *  1. Same author. This is the trust boundary — see the module comment.
+ *  2. `target.created_at <= deletion.created_at`. A deletion request cannot
+ *     pre-emptively retract a future event; without this, one kind:5 would
+ *     permanently silence every later event a key publishes.
+ *
+ * @param target - The stored event being considered for retraction.
+ * @param deletion - The kind:5 deletion request.
+ * @returns True when the retraction is authorized.
+ */
+declare function isDeletableBy(target: Pick<NostrEvent, 'pubkey' | 'created_at'>, deletion: Pick<NostrEvent, 'pubkey' | 'created_at'>): boolean;
+
+/**
+ * Operator event blocklist — the escape hatch for litter that NEITHER NIP
+ * can clear.
+ *
+ * WHY THIS EXISTS. NIP-01 replacement needs the author's key. NIP-09 deletion
+ * needs the author's key. When a node publishes an announce and then the key
+ * is lost — a throwaway proof rig wiped off an operator workstation, say —
+ * the announce is unretractable BY CONSTRUCTION, and if it also carries no
+ * NIP-40 `expiration` tag then nothing in the protocol will ever remove it.
+ * That is exactly the state devnet was in: a kind:5094-era swap maker
+ * advertising `g.toon.swap.sol` at `ws://127.0.0.1:3401` — a loopback address
+ * that resolves to whatever machine READS it — with no expiry and no key.
+ *
+ * WHY IT IS SHAPED LIKE THIS. Any mechanism that lets an operator remove
+ * other people's events is a censorship surface, so the scope is drawn as
+ * narrowly as the job allows:
+ *
+ *   - **Event ids only, never pubkeys.** Blocking a pubkey silences an
+ *     identity's entire past and future output with one line of config.
+ *     Blocking a 64-hex id removes exactly one event that the operator had to
+ *     name explicitly, having already seen it. A key that is still alive can
+ *     simply publish again, so this cannot be used to suppress a live
+ *     participant — only to sweep a specific dead artifact.
+ *   - **Config at startup, not an API.** There is no admin endpoint, no
+ *     authenticated mutation, nothing network-reachable. The list arrives as
+ *     process configuration (`TOON_BLOCKED_EVENT_IDS`) and changing it means
+ *     restarting the process with a changed deployment — an act that lands in
+ *     a git history and a deploy log rather than in an unlogged HTTP call.
+ *   - **Loud.** The launcher prints every blocked id at startup. A relay that
+ *     is withholding events should say so on every boot.
+ *
+ * A blocked id is refused on write, filtered on read, and swept from the
+ * database — but the block still lives only in ONE relay's configuration.
+ * Other relays serving the same event are unaffected, which is the correct
+ * outcome: this is an operator declining to carry a specific artifact, not a
+ * protocol-level retraction.
+ *
+ * @module
+ */
+/**
+ * Parse an operator blocklist from its configuration string.
+ *
+ * Accepts a comma- and/or whitespace-separated list of 64-char hex event ids.
+ * Case is normalized to lowercase. Entries that are not well-formed event ids
+ * are reported separately rather than silently dropped: a typo in a blocklist
+ * must be visible, because its failure mode (an event the operator believes
+ * is blocked but is still being served) is silent otherwise.
+ *
+ * @param raw - Raw configuration value, or undefined.
+ * @returns The accepted ids and any rejected entries.
+ */
+declare function parseBlockedEventIds(raw: string | undefined): {
+    ids: string[];
+    invalid: string[];
+};
+
 /**
  * Event-signature verification for the paid-write hot path (relay#85).
  *
@@ -414,39 +720,6 @@ declare class NostrRelayServer {
     private handleConnection;
 }
 
-/**
- * TOON event codec.
- *
- * Encodes/decodes Nostr events to and from the TOON text format. Vendored from
- * `@toon-protocol/core` so the relay depends only on the lightweight
- * `@toon-format/toon` encoder rather than core's full transitive tree (which
- * pulls Arweave / web3 wallet stacks the relay does not use). Same MIT
- * license / org.
- *
- * NOTE: this codec is NOT used on the relay's NIP-01 read surface. Outbound
- * EVENT frames are canonical NIP-01 JSON (see
- * `websocket/ConnectionHandler.sendEvent`, #46) so that standard nostr clients
- * can parse events and verify signatures from the wire. The codec remains
- * exported for library consumers that exchange TOON-text events elsewhere.
- *
- * @module
- */
-
-/** Thrown when a Nostr event cannot be encoded to TOON. */
-declare class ToonEncodeError extends Error {
-    readonly code = "TOON_ENCODE_ERROR";
-    constructor(message: string, cause?: Error);
-}
-/** Thrown when TOON data cannot be decoded into a valid Nostr event. */
-declare class ToonDecodeError extends Error {
-    readonly code = "TOON_DECODE_ERROR";
-    constructor(message: string, cause?: Error);
-}
-/** Encode a Nostr event to TOON bytes (UTF-8). */
-declare function encodeEventToToon(event: NostrEvent): Uint8Array;
-/** Decode TOON bytes into a validated Nostr event. */
-declare function decodeEventFromToon(data: Uint8Array): NostrEvent;
-
 /**
  * Subscribe to upstream relays and propagate events into the local EventStore.
  *
@@ -502,14 +775,23 @@ declare class RelaySubscriber {
  * time a write reaches this process it is already proven paid, so the relay
  * simply stores the event and serves reads.
  *
- * Two surfaces:
+ * Three surfaces:
  *
- *   - `POST /write` (TOON_BLS_PORT, default 3100): accepts `{ event }` as JSON,
- *     trusts the injected `X-TOON-Payer`/`-Amount`/`-Chain` headers WITHOUT
- *     re-validating payment, verifies only the event's own signature for
+ *   - `POST /write` (TOON_BLS_PORT, default 3100): accepts `{ event }` as JSON.
+ *     By the time a request reaches this surface it is already proven paid;
+ *     the terminating connector asserts nothing about that payment to this
+ *     relay -- no payer, amount, or chain (`toon-protocol/connector` ADR
+ *     0036) -- so the handler verifies only the event's own signature for
  *     integrity (paid ephemeral kinds skip schnorr by default and keep the
  *     id check -- relay#85, see `verifyEphemeral`), and stores it.
  *     `GET /health` and `GET /metrics` live on the same port.
+ *   - `POST /write-ephemeral` (same port, relay#129): the FREE ephemeral
+ *     write lane. Accepts only ephemeral kinds (NIP-16, 20000 <= kind <
+ *     30000), always runs FULL schnorr verification (no skip -- this lane
+ *     has no payment gate), and never stores. Bounded by a per-key rate
+ *     limit and a body-size cap (see `ephemeralRateLimit` /
+ *     `ephemeralMaxBodyBytes`). Terminated at the connector by its own
+ *     zero-priced route (`deploy/connector.toml`'s `g.toon.relay.ephemeral`).
  *   - Free NIP-01 WebSocket reads (TOON_RELAY_PORT, default 7100).
  *
  * `startRelay()` returns a `RelayInstance` with an explicit `.stop()` for
@@ -566,6 +848,54 @@ interface RelayConfig {
      * caller owns its lifecycle when supplied.
      */
     eventStore?: EventStore;
+    /**
+     * Enforce NIP-40 expiration (default: true; env: TOON_ENFORCE_EXPIRATION).
+     *
+     * When true, an event past its `expiration` tag is not served from history
+     * and not fanned out live. Setting this false is the KILL SWITCH back to
+     * the pre-relay#137 behaviour of serving everything forever.
+     *
+     * ! READ THIS BEFORE ASSUMING THE DEFAULT IS FREE !
+     * On the TOON devnet the only events carrying an `expiration` tag are
+     * kind:10032 node announces, published with a 600s TTL and refreshed by a
+     * shell loop every 240s — 2.5 refresh periods of margin, and the loop's
+     * failure backoff (5s doubling, capped at 240s) needs SEVEN consecutive
+     * failed publishes before an announce goes past its expiry. That margin is
+     * comfortable, but it is a margin, not a guarantee: the store and swap
+     * announce loops PAY for each republish out of a payment channel, so a
+     * drained channel makes every republish fail indefinitely. Before this
+     * flag existed, that failure degraded to "a stale announce is still
+     * served"; with enforcement on, it becomes "the node vanishes from
+     * discovery". That is the intended semantics — a node that cannot afford
+     * to say it is alive should not be advertised — but it is a real change in
+     * blast radius, and this flag is how an operator buys time.
+     */
+    enforceExpiration?: boolean;
+    /**
+     * How long an expired event is kept on disk before the reaper deletes it
+     * (default: 86400 = 24h; env: TOON_EXPIRATION_REAP_GRACE_SECONDS).
+     *
+     * Serve-time filtering is reversible; a DELETE is not. The grace window is
+     * what makes flipping `enforceExpiration` back off an actual recovery
+     * rather than an apology. Set 0 to reap the moment an event expires.
+     */
+    expirationReapGraceSeconds?: number;
+    /**
+     * How often the reaper sweeps (default: 3600 = hourly; env:
+     * TOON_EXPIRATION_REAP_INTERVAL_SECONDS). 0 disables reaping entirely;
+     * serve-time filtering is unaffected.
+     */
+    expirationReapIntervalSeconds?: number;
+    /**
+     * Operator-blocked event ids (env: TOON_BLOCKED_EVENT_IDS, comma-separated).
+     *
+     * The narrow escape hatch for an event that neither NIP-01 replacement nor
+     * NIP-09 deletion can reach because its author's key is gone. Ids only,
+     * never pubkeys; startup configuration only, never an API. See
+     * `nips/blocklist.ts` for the full reasoning and the censorship hazard it
+     * is drawn around.
+     */
+    blockedEventIds?: string[];
     /** Skip event-signature verification on `POST /write` (default: false). */
     devMode?: boolean;
     /**
@@ -589,6 +919,22 @@ interface RelayConfig {
      * loop and jittering ephemeral frame latency (relay#85).
      */
     verifyWorkers?: number;
+    /**
+     * Per-key sliding-window rate limit for `POST /write-ephemeral` (default:
+     * 200 requests / 10s; env: TOON_EPHEMERAL_RATE_LIMIT /
+     * TOON_EPHEMERAL_RATE_WINDOW_MS). This lane has no payment gate, so this
+     * bound (plus `ephemeralMaxBodyBytes`) IS its admission control -- see
+     * `EphemeralWriteHandlerConfig` for the full reasoning.
+     */
+    ephemeralRateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /**
+     * Request-body size cap in bytes for `POST /write-ephemeral` (default:
+     * 8192; env: TOON_EPHEMERAL_MAX_BODY_BYTES).
+     */
+    ephemeralMaxBodyBytes?: number;
     /**
      * Log one line per accepted `POST /write` (default: false). Per-event
      * console I/O is measurable tail jitter on the write hot path (relay#85),
@@ -609,7 +955,16 @@ interface ResolvedRelayConfig {
     devMode: boolean;
     verifyEphemeral: boolean;
     verifyWorkers: number;
+    ephemeralRateLimit: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    ephemeralMaxBodyBytes: number;
     logWrites: boolean;
+    enforceExpiration: boolean;
+    expirationReapGraceSeconds: number;
+    expirationReapIntervalSeconds: number;
+    blockedEventIds: string[];
 }
 /**
  * A running TOON relay node instance returned by `startRelay()`.
@@ -668,6 +1023,12 @@ declare function isInternalBindHost(host: string): boolean;
  * compose deploy the port binds 0.0.0.0 inside the container and is private
  * because it is never host-published (docker `expose:`, not `ports:`).
  *
+ * `POST /write-ephemeral` (relay#129) shares this same port/host but needs
+ * no exposure check of its own: it always runs full verification (no skip
+ * for exposure to weaken) and enforces its own rate limit/size cap
+ * regardless of how a request reaches it. This guard's warning is scoped to
+ * the paid-write skip above, which stays the one exposure risk on this port.
+ *
  * @internal Exported for unit testing.
  */
 declare function warnIfWritePortExposed(writeHost: string, blsPort: number, options: {
@@ -784,6 +1145,21 @@ interface MetricsSnapshot {
         /** Verify-pool worker count (0 = inline on the event loop). */
         workers: number;
     } & DurationStats;
+    /**
+     * Free ephemeral write lane (relay#129, `POST /write-ephemeral`). Always
+     * present -- the lane is always mounted -- and static for the process
+     * lifetime: it has no payment gate, so these bounds ARE its admission
+     * control, and the acceptance criteria requires them to be visible here
+     * alongside the startup log line.
+     */
+    ephemeralWriteLane: {
+        enabled: true;
+        rateLimit: {
+            maxRequests: number;
+            windowMs: number;
+        };
+        maxBodyBytes: number;
+    };
 }
 /** Live registry behind `GET /metrics`. */
 interface MetricsRegistry {
@@ -801,30 +1177,41 @@ interface MetricsRegistry {
  * `recordVerify` into the verify pool's `onMeasure` and serves `snapshot()`
  * from `GET /metrics`.
  *
- * @param info - Static verify metadata surfaced in the snapshot.
+ * @param info - Static verify metadata + ephemeral-lane bounds surfaced in
+ *   the snapshot (relay#129).
  */
 declare function createMetricsRegistry(info: {
     verifyImplementation: string;
     verifyWorkers: number;
+    ephemeralRateLimit: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    ephemeralMaxBodyBytes: number;
 }): MetricsRegistry;
 
 /**
  * Write handler for @toon-protocol/relay.
  *
- * Exposes a plain-HTTP write surface that accepts an event-as-JSON, trusts
- * (but does NOT validate) injected payment headers, verifies ONLY the event
- * signature for integrity, and stores the event.
+ * Exposes a plain-HTTP write surface that accepts an event-as-JSON, verifies
+ * ONLY the event signature for integrity, and stores the event.
  *
  * This handler is intentionally decoupled from any payment layer: it contains
  * no claim/settlement/ILP logic and imports none of it. Payment validation is
- * the upstream terminator's concern; by the time a request reaches this surface
- * the trusted `X-TOON-*` headers are assumed already proven. The handler
- * captures them purely for the response echo and a log line.
+ * the upstream terminator's concern; by the time a request reaches this
+ * surface it is already proven paid.
+ *
+ * What the terminator DOES state, it records. A terminating connector states
+ * `X-TOON-Payer` / `X-TOON-Amount` / `X-TOON-Chain` on a delivery whose
+ * payment it verified at its own client edge (`toon-protocol/connector`
+ * ADR 0040, relay#133); the handler reads them, echoes a well-formed triple
+ * back on the 200, and treats their absence as "this hop was not the one
+ * paid" -- NEVER as "unpaid". See payment-attribution.ts for the contract and
+ * for why the same header names were right to distrust before ADR 0040.
  *
  * Flow:
  * 1. Parse JSON body `{ event }` -> 400 on malformed/missing event
- * 2. Capture trusted X-TOON-Payer / X-TOON-Amount / X-TOON-Chain headers
- * 3. Verify the event signature (skipped in devMode) -> 422 on invalid sig.
+ * 2. Verify the event signature (skipped in devMode) -> 422 on invalid sig.
  *    Verification uses the fast WASM libsecp256k1 path (crypto/verify-event)
  *    rather than noble pure-JS: post-#84 the synchronous ~1.3ms noble verify
  *    on the single event loop WAS the write-path ceiling (~240-260 events/s
@@ -834,17 +1221,18 @@ declare function createMetricsRegistry(info: {
  *    default -- only the SHA-256 id check runs -> 422 on id mismatch. See
  *    the loud comment at the verify step for why this is safe, and
  *    `verifyEphemeral` to turn full verification back on.
- * 4. Store the event in the EventStore -- unless its kind is ephemeral
+ * 3. Store the event in the EventStore -- unless its kind is ephemeral
  *    (NIP-16: 20000 <= kind < 30000), which is delivered live and never
  *    persisted. Skipping the store here is not only NIP-16 semantics: the
  *    synchronous per-event disk write was the serialization point that
  *    capped the whole paid-write pipeline at ~150 events/s globally
  *    (connector#685), and ephemeral traffic -- audio frames -- is exactly
  *    the traffic that hits that path hardest.
- * 5. Fire the optional onStored callback (ephemeral events included: it is
+ * 4. Fire the optional onStored callback (ephemeral events included: it is
  *    the live-broadcast hook, and ephemeral events exist only as that
  *    broadcast)
- * 6. Respond 200 with the event id, storedAt timestamp, and echoed headers
+ * 5. Respond 200 with the event id, storedAt timestamp, and -- when the
+ *    connector stated one -- the payment it attributed the write to
  *
  * @module
  */
@@ -919,4 +1307,227 @@ interface WriteHandler {
  */
 declare function createWriteHandler(config: WriteHandlerConfig): WriteHandler;
 
-export { ConnectionHandler, DEFAULT_RELAY_CONFIG, type DurationStats, type EventStore, type HealthConfig, type HealthResponse, InMemoryEventStore, type MetricsRegistry, type MetricsSnapshot, NostrRelayServer, type RelayConfig, RelayError, type RelayInstance, type RelayServerConfig, RelaySubscriber, type RelaySubscriberConfig, type RelaySubscription, type ResolvedRelayConfig, SqliteEventStore, type Subscription, ToonDecodeError, ToonEncodeError, VERSION, type VerifyPool, type VerifyPoolOptions, type WriteHandler, type WriteHandlerConfig, createHealthResponse, createMetricsRegistry, createVerifyPool, createWriteHandler, decodeEventFromToon, defaultVerifyWorkers, encodeEventToToon, isInternalBindHost, matchFilter, readOpenFilesSoftLimit, serializeEventFrame, startRelay, verifyEventId, verifyEventSignature, verifyImplementation, warnIfWritePortExposed };
+/**
+ * The connector's payment statement, as read off a delivery to `POST /write`.
+ *
+ * A terminating connector states three headers on a delivery whose payment it
+ * verified at its OWN client edge (`toon-protocol/connector` ADR 0040):
+ *
+ * | header          | value                                                       |
+ * | --------------- | ----------------------------------------------------------- |
+ * | `X-TOON-Payer`  | `evm:0x<64 hex>` or `solana:<base58>` -- the client CHANNEL  |
+ * |                 | key whose covering claim that connector verified             |
+ * | `X-TOON-Amount` | the route's flat price (ADR 0020), decimal, base units       |
+ * | `X-TOON-Chain`  | that key's namespace -- `evm` or `solana`                    |
+ *
+ * ! ABSENCE IS NOT "UNPAID" ! The headers are present ONLY when this
+ * connector was the hop that took the payment and the route's price is
+ * non-zero. They are absent -- not empty -- on a peer-wire arrival, a
+ * forwarded packet, and every `price = 0` route (which is why the free
+ * ephemeral lane never sees them). A handler that read absence as "nobody
+ * paid" would reject exactly the deliveries a longer path produced.
+ *
+ * The relay does not, and cannot, re-validate any of this: it holds no chain
+ * state and speaks no ILP. The connector's statement IS the trust model. What
+ * this module adds is that a malformed statement is treated as no statement
+ * at all -- a garbled value from a stale or hostile caller becomes `undefined`
+ * rather than something the relay records and echoes as fact.
+ *
+ * History worth not repeating: relay#122 removed the earlier reading of these
+ * same header NAMES, correctly, because the TypeScript-era connector set
+ * `X-TOON-Payer` to the PREVIOUS HOP -- which on any path longer than one hop
+ * named the wrong party. ADR 0040's successor is a chain-verified channel key
+ * that is never stated by a hop that did not take the payment, so the value
+ * now means what its name says (relay#133).
+ *
+ * @module
+ */
+
+/** A payment the terminating connector states it verified. */
+interface PaymentAttribution {
+    /** The client channel key, namespaced: `evm:0x<64 hex>` / `solana:<base58>`. */
+    payer: string;
+    /** The route's flat price in base units, decimal. */
+    amount: string;
+    /** The payer key's namespace. */
+    chain: 'evm' | 'solana';
+}
+/**
+ * Read the connector's payment statement off a request.
+ *
+ * Returns `undefined` unless ALL THREE headers are present, individually
+ * well-formed, and mutually consistent (the payer's namespace must be the
+ * chain it claims). Anything else -- one header, two headers, a payer from a
+ * chain the `X-TOON-Chain` header disagrees with, a non-decimal amount -- is
+ * discarded whole. Partial attribution is worse than none: it would record
+ * half a fact as if it were the whole one.
+ *
+ * This never rejects the request. A caller that states nothing, or states
+ * nonsense, still gets its write handled on the merits of the event itself;
+ * the payment gate is upstream and has already run by the time anything
+ * reaches this process.
+ */
+declare function readPaymentAttribution(c: Context): PaymentAttribution | undefined;
+
+/**
+ * A minimal in-memory sliding-window rate limiter (relay#129).
+ *
+ * Built for the free ephemeral write lane (`POST /write-ephemeral`,
+ * handlers/write-ephemeral-handler.ts): with no payment gate, request volume
+ * is the only admission control that lane has, so every request must be
+ * checked against a per-key budget before any other work happens.
+ * Dependency-free and small enough to own outright rather than pull in a
+ * library, matching the shape the rest of the launcher already uses for
+ * self-contained stateful helpers (crypto/verify-pool.ts, launcher/metrics.ts).
+ *
+ * Sliding-window LOG, not a fixed-window counter: a fixed window lets a
+ * caller burst up to 2x the limit across a window boundary (all of window
+ * N's budget at :59, all of window N+1's budget at :00). The log costs one
+ * array per active key and O(requests-in-window) work per call, which is
+ * fine at the request volumes a bound like this is meant to police.
+ *
+ * @module
+ */
+/** Options for {@link createRateLimiter}. */
+interface RateLimiterOptions {
+    /** Max requests allowed per key within the trailing window. */
+    maxRequests: number;
+    /** Trailing window length in milliseconds. */
+    windowMs: number;
+    /** Clock override for deterministic tests (default: `Date.now`). */
+    now?: () => number;
+}
+/** A live rate limiter. One instance per bound; keys are caller-defined. */
+interface RateLimiter {
+    /**
+     * Check `key`'s budget. Returns `true` and records this call towards the
+     * budget when the key is under its limit; returns `false` (and records
+     * nothing) when the key is over budget. Never throws.
+     */
+    allow(key: string): boolean;
+}
+/**
+ * Create a sliding-window rate limiter.
+ *
+ * @param options - Bound + optional clock override.
+ */
+declare function createRateLimiter(options: RateLimiterOptions): RateLimiter;
+
+/**
+ * Free ephemeral write handler for @toon-protocol/relay (relay#129, ephemeral
+ * epic toon-meta#393 E2).
+ *
+ * A SECOND write surface, `POST /write-ephemeral`, distinct from the paid
+ * `POST /write` (write-handler.ts). It exists because the connector cannot
+ * carry two prices on one `handler_url` (`ConflictingHandlerPrice`,
+ * connector `route.rs:378-399`) -- a free lane needs its own endpoint,
+ * terminated by its own zero-priced route in the deploy config (see
+ * `deploy/connector.toml`'s `g.toon.relay.ephemeral` route).
+ *
+ * Differences from the paid handler, all deliberate:
+ *
+ * - Accepts ONLY ephemeral kinds (NIP-16, 20000 <= kind < 30000) -- anything
+ *   else is a 400. Persistent kinds have no business on a free lane; letting
+ *   them through would be a free ride around pay-to-write.
+ * - NEVER stores. Ephemeral kinds are never persisted on the paid path
+ *   either (NIP-16; write-handler.ts), so there is nothing this lane would
+ *   ever write to an EventStore -- it does not take one as a dependency.
+ * - Schnorr verification is ALWAYS FULL, with no skip and no config knob to
+ *   add one. The paid path's ephemeral verify-skip (write-handler.ts) is
+ *   safe ONLY because payment is the admission gate; this lane has no
+ *   payment gate, so signature verification IS its only defense against
+ *   forged-signature spam before the bounds below even apply. Reusing that
+ *   skip here would let anyone broadcast garbage to every subscriber for
+ *   free -- exactly the case write-handler.ts's own invariant comment warns
+ *   against.
+ * - Bounds, because free + broadcast = spam surface: a per-key sliding-
+ *   window rate limit (rate-limiter.ts) and a request-body size cap, both
+ *   config-gated with conservative defaults (see
+ *   {@link EphemeralWriteHandlerConfig}).
+ *
+ * Flow:
+ * 1. Rate-limit check, keyed by remote address (falling back to a shared
+ *    bucket when connection info is unavailable -- see `defaultClientKey`)
+ *    -- BEFORE any body is read, so a rate-limited caller costs as little
+ *    work as possible -> 429 over budget.
+ * 2. Body-size check against `maxBodyBytes` -- BEFORE JSON parsing, so an
+ *    oversized payload is never deserialized -> 413 too large.
+ * 3. Parse JSON body `{ event }` -> 400 on malformed/missing event.
+ * 4. Reject non-ephemeral kinds -> 400.
+ * 5. Full schnorr verification, never skipped -> 422 on invalid signature.
+ * 6. Fire the optional onBroadcast callback (the live-broadcast hook).
+ *    Nothing is ever stored.
+ * 7. Respond 200 with the event id.
+ *
+ * @module
+ */
+
+/**
+ * Conservative default rate-limit bound: 200 requests per 10-second window
+ * per key. Sized for presence/typing traffic (the epic's motivating
+ * workload, toon-meta#393), not huddle-frame rates -- that traffic stays on
+ * the paid path. Deliberately generous rather than tight: this is a spam
+ * ceiling, not a fairness scheduler, and a false-positive reject on
+ * legitimate ephemeral traffic (a dropped typing indicator) is silent and
+ * has no client-side retry signal.
+ */
+declare const DEFAULT_EPHEMERAL_RATE_LIMIT: {
+    maxRequests: number;
+    windowMs: number;
+};
+/**
+ * Conservative default body-size cap in bytes. Ephemeral events on this lane
+ * (presence heartbeats, typing indicators) are small JSON; 8 KiB comfortably
+ * covers a signed Nostr event with generous tag/content headroom while
+ * bounding worst-case memory per request on an unpaid surface.
+ */
+declare const DEFAULT_EPHEMERAL_MAX_BODY_BYTES: number;
+/** Configuration for the ephemeral write handler. */
+interface EphemeralWriteHandlerConfig {
+    /**
+     * Signature verifier. Defaults to the inline `verifyEventSignature`; the
+     * launcher injects the worker-pool verifier (crypto/verify-pool.ts),
+     * shared with the paid handler, so verify bursts run off the event loop
+     * (relay#85). May resolve asynchronously -- the handler awaits it.
+     *
+     * There is NO devMode/skip option here, unlike the paid handler --
+     * verification on this lane is always full (see the module doc).
+     */
+    verifyEvent?: (event: NostrEvent) => Promise<boolean> | boolean;
+    /** Optional callback fired after an event passes all checks (broadcast hook). */
+    onBroadcast?: (event: NostrEvent) => void;
+    /** Log one line per accepted write (default: false), matching write-handler.ts. */
+    logWrites?: boolean;
+    /** Rate-limit bound (default {@link DEFAULT_EPHEMERAL_RATE_LIMIT}). */
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /** Request body size cap in bytes (default {@link DEFAULT_EPHEMERAL_MAX_BODY_BYTES}). */
+    maxBodyBytes?: number;
+    /**
+     * Test-only: inject a rate limiter directly (e.g. with a fake clock)
+     * instead of letting the handler build one from `rateLimit`.
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * Test-only: override how a request is keyed for rate limiting. Defaults
+     * to `defaultClientKey` (remote address via `getConnInfo`, falling back to
+     * a shared bucket).
+     */
+    getClientKey?: (c: Context) => string;
+}
+/** Ephemeral write handler instance. */
+interface EphemeralWriteHandler {
+    /** Handle a plain-HTTP ephemeral write request. */
+    handleWrite(c: Context): Promise<Response>;
+}
+/**
+ * Create the ephemeral write handler.
+ *
+ * @param config - Handler configuration.
+ * @returns An EphemeralWriteHandler with a handleWrite method.
+ */
+declare function createEphemeralWriteHandler(config?: EphemeralWriteHandlerConfig): EphemeralWriteHandler;
+
+export { type AddressCoordinate, ConnectionHandler, DEFAULT_EPHEMERAL_MAX_BODY_BYTES, DEFAULT_EPHEMERAL_RATE_LIMIT, DEFAULT_RELAY_CONFIG, DELETION_KIND, type DeletionTargets, type DurationStats, EXPIRATION_TAG, type EphemeralWriteHandler, type EphemeralWriteHandlerConfig, type EventStore, type EventStoreOptions, type HealthConfig, type HealthResponse, InMemoryEventStore, type MetricsRegistry, type MetricsSnapshot, NostrRelayServer, type PaymentAttribution, type RateLimiter, type RateLimiterOptions, type RelayConfig, RelayError, type RelayInstance, type RelayServerConfig, RelaySubscriber, type RelaySubscriberConfig, type RelaySubscription, type ResolvedRelayConfig, SqliteEventStore, type Subscription, VERSION, type VerifyPool, type VerifyPoolOptions, type WriteHandler, type WriteHandlerConfig, createEphemeralWriteHandler, createHealthResponse, createMetricsRegistry, createRateLimiter, createVerifyPool, createWriteHandler, defaultVerifyWorkers, getExpiration, isDeletableBy, isDeletionKind, isExpired, isInternalBindHost, matchFilter, parseAddressCoordinate, parseBlockedEventIds, parseDeletionTargets, readOpenFilesSoftLimit, readPaymentAttribution, serializeEventFrame, startRelay, verifyEventId, verifyEventSignature, verifyImplementation, warnIfWritePortExposed };