@oxy.so/protocol 1.0.0

package/src/node/nodeClient.ts

@@ -0,0 +1,322 @@
+/**
+ * `NodeClient` — the HTTP client that drives an Oxy-protocol data node's
+ * routes (head / log / records / blobs). It is the OUTBOUND half of the node
+ * protocol: oxy-api uses it to PULL a user's chain back from their node; a
+ * future Mention backend (B3) uses it to drive a node + push records/blobs.
+ *
+ * The client is transport-agnostic — it takes an injected {@link NodeFetch} so
+ * the protocol package never depends on `@oxy.so/core`. Oxy supplies an adapter
+ * over `@oxy.so/core/server`'s `safeFetch` (HTTPS-only, DNS-pinned, private-IP
+ * denylist, bounded redirects); a test supplies an in-process stub. Every
+ * response body is read with a hard byte ceiling, so a node cannot stream an
+ * unbounded body into the caller.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import {
+  type NodeFetch,
+  type NodeFetchInit,
+  readBoundedBytes,
+  readBoundedJson,
+} from './httpFetch';
+import {
+  DEFAULT_CLIENT_MAX_REDIRECTS,
+  DEFAULT_CLIENT_TIMEOUT_MS,
+  DEFAULT_HEAD_MAX_BYTES,
+  DEFAULT_LOG_MAX_BYTES,
+  DEFAULT_MAX_BLOB_BYTES,
+  DEFAULT_WRITE_RESPONSE_MAX_BYTES,
+  NODE_BLOBS_PATH,
+  NODE_HEAD_PATH,
+  NODE_LOG_PATH,
+  NODE_RECORDS_PATH,
+  NODE_SYNC_PUSH_PATH,
+  OWNER_AUTH_HEADERS,
+} from './constants';
+
+/** The chain head a node reports at `GET /oxy/head`. */
+export interface NodeHead {
+  seq: number | null;
+  headRecordId: string | null;
+  recordCount: number;
+}
+
+/** One ordered page of a node's log (`GET /oxy/log`). */
+export interface NodeLogPage {
+  /**
+   * The raw log items, returned VERBATIM (not re-parsed) — the caller validates
+   * + verifies each against the envelope schema. Preserves the node's exact wire
+   * shape so a puller's own verification is the trust boundary.
+   */
+  records: unknown[];
+  count: number;
+  head: { seq: number; headRecordId: string } | null;
+}
+
+/** Outcome of an owner write (`POST /records`). */
+export interface NodeWriteResult {
+  recordId: string;
+  seq: number;
+}
+
+/** Outcome of an owner blob pin (`PUT /blobs/:hash`). */
+export interface NodeBlobPutResult {
+  hash: string;
+  size: number;
+}
+
+/** Owner-signed authorization for a blob pin (caller signs; client sends headers). */
+export interface NodeBlobPinAuth {
+  publicKey: string;
+  signature: string;
+  timestamp: number;
+}
+
+/** A non-2xx node response (or a node that returned a malformed body). */
+export class NodeClientError extends Error {
+  constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly reason?: string,
+  ) {
+    super(message);
+    this.name = 'NodeClientError';
+  }
+}
+
+/** Construction options for a {@link NodeClient}. */
+export interface NodeClientOptions {
+  /** The node's HTTPS base URL (no trailing slash). */
+  baseUrl: string;
+  /** The injected transport (an adapter over `safeFetch`, or a test stub). */
+  fetch: NodeFetch;
+  /** Time-to-first-byte deadline per request (ms). */
+  headersTimeoutMs?: number;
+  /** Redirect budget per request (each re-validated by the transport). */
+  maxRedirects?: number;
+  /** Bounded read ceiling for a `/oxy/head` response. */
+  headMaxBytes?: number;
+  /** Bounded read ceiling for a `/oxy/log` page response. */
+  logMaxBytes?: number;
+  /** Bounded read ceiling for a small write/JSON response. */
+  writeResponseMaxBytes?: number;
+  /** Bounded read ceiling for a fetched blob. */
+  blobMaxBytes?: number;
+}
+
+function readError(body: unknown): string | undefined {
+  if (typeof body === 'object' && body !== null && typeof (body as { error?: unknown }).error === 'string') {
+    return (body as { error: string }).error;
+  }
+  return undefined;
+}
+
+/**
+ * Trim every trailing slash from a base URL in LINEAR time.
+ *
+ * Replaces an anchored-quantifier regex (`/\/+$/`) whose backtracking is a
+ * polynomial-ReDoS sink on a long all-slash input; a single-pass scan is O(n)
+ * with no ReDoS surface.
+ */
+export function trimTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
+
+export class NodeClient {
+  private readonly baseUrl: string;
+  private readonly fetch: NodeFetch;
+  private readonly headersTimeoutMs: number;
+  private readonly maxRedirects: number;
+  private readonly headMaxBytes: number;
+  private readonly logMaxBytes: number;
+  private readonly writeResponseMaxBytes: number;
+  private readonly blobMaxBytes: number;
+
+  constructor(options: NodeClientOptions) {
+    this.baseUrl = trimTrailingSlashes(options.baseUrl);
+    this.fetch = options.fetch;
+    this.headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
+    this.maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
+    this.headMaxBytes = options.headMaxBytes ?? DEFAULT_HEAD_MAX_BYTES;
+    this.logMaxBytes = options.logMaxBytes ?? DEFAULT_LOG_MAX_BYTES;
+    this.writeResponseMaxBytes = options.writeResponseMaxBytes ?? DEFAULT_WRITE_RESPONSE_MAX_BYTES;
+    this.blobMaxBytes = options.blobMaxBytes ?? DEFAULT_MAX_BLOB_BYTES;
+  }
+
+  /** Base request options shared by every call (timeout + redirect budget). */
+  private init(extra: Partial<NodeFetchInit> & Pick<NodeFetchInit, 'method'>): NodeFetchInit {
+    return {
+      headersTimeoutMs: this.headersTimeoutMs,
+      maxRedirects: this.maxRedirects,
+      ...extra,
+    };
+  }
+
+  /** The node's current chain head. Throws {@link NodeClientError} on a non-2xx. */
+  async head(): Promise<NodeHead> {
+    const res = await this.fetch(`${this.baseUrl}${NODE_HEAD_PATH}`, this.init({ method: 'GET' }));
+    if (res.status < 200 || res.status >= 300) {
+      res.destroy();
+      throw new NodeClientError(`node ${NODE_HEAD_PATH} responded HTTP ${res.status}`, res.status);
+    }
+    const body = await readBoundedJson(res, this.headMaxBytes);
+    const obj = (typeof body === 'object' && body !== null ? body : {}) as Record<string, unknown>;
+    return {
+      seq: typeof obj.seq === 'number' ? obj.seq : null,
+      headRecordId: typeof obj.headRecordId === 'string' ? obj.headRecordId : null,
+      recordCount: typeof obj.recordCount === 'number' ? obj.recordCount : 0,
+    };
+  }
+
+  /**
+   * One ordered page of the node's log strictly after `sinceSeq` (pass `-1` from
+   * genesis), capped at `limit`. Throws {@link NodeClientError} on a non-2xx or a
+   * response missing the `records` array.
+   */
+  async log(sinceSeq: number, limit: number): Promise<NodeLogPage> {
+    // A genesis cursor (`sinceSeq < 0`) is expressed by OMITTING `since` — the
+    // node reads an absent cursor as "from genesis". A negative numeric `since`
+    // is not a valid cursor on the wire (only an absent one, a non-negative seq,
+    // or a recordId), so omitting it is the correct way to request the whole log.
+    const sinceParam = sinceSeq >= 0 ? `since=${encodeURIComponent(String(sinceSeq))}&` : '';
+    const url = `${this.baseUrl}${NODE_LOG_PATH}?${sinceParam}limit=${encodeURIComponent(String(limit))}`;
+    const res = await this.fetch(url, this.init({ method: 'GET' }));
+    if (res.status < 200 || res.status >= 300) {
+      res.destroy();
+      throw new NodeClientError(`node ${NODE_LOG_PATH} responded HTTP ${res.status}`, res.status);
+    }
+    const body = await readBoundedJson(res, this.logMaxBytes);
+    const records = (body as { records?: unknown }).records;
+    if (!Array.isArray(records)) {
+      throw new NodeClientError(`node ${NODE_LOG_PATH} returned no records array`, res.status);
+    }
+    const headRaw = (body as { head?: unknown }).head;
+    const head =
+      typeof headRaw === 'object' &&
+      headRaw !== null &&
+      typeof (headRaw as { seq?: unknown }).seq === 'number' &&
+      typeof (headRaw as { headRecordId?: unknown }).headRecordId === 'string'
+        ? { seq: (headRaw as { seq: number }).seq, headRecordId: (headRaw as { headRecordId: string }).headRecordId }
+        : null;
+    return { records, count: records.length, head };
+  }
+
+  /**
+   * Write a single owner-signed envelope (`POST /records`). Throws
+   * {@link NodeClientError} (carrying the node's `reason`) on any non-2xx — a
+   * chain rejection (`chain_gap`/`chain_fork`/`bad_seq`/`chain_conflict`) or an
+   * authorization failure.
+   */
+  async writeRecord(envelope: SignedRecordEnvelope): Promise<NodeWriteResult> {
+    const res = await this.fetch(
+      `${this.baseUrl}${NODE_RECORDS_PATH}`,
+      this.init({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: Buffer.from(JSON.stringify(envelope), 'utf8'),
+      }),
+    );
+    const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+    if (res.status < 200 || res.status >= 300) {
+      const reason = readError(body);
+      throw new NodeClientError(
+        `node ${NODE_RECORDS_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`,
+        res.status,
+        reason,
+      );
+    }
+    const obj = body as { recordId?: unknown; seq?: unknown };
+    if (typeof obj.recordId !== 'string' || typeof obj.seq !== 'number') {
+      throw new NodeClientError(`node ${NODE_RECORDS_PATH} returned a malformed write result`, res.status);
+    }
+    return { recordId: obj.recordId, seq: obj.seq };
+  }
+
+  /**
+   * Push a batch of owner-signed envelopes (`POST /sync/push`). Returns the
+   * node's per-item results. Throws {@link NodeClientError} only on a non-2xx
+   * batch-level failure (`invalid_batch` / `batch_too_large`).
+   */
+  async pushRecords(
+    envelopes: SignedRecordEnvelope[],
+  ): Promise<{ accepted: number; results: Array<{ ok: boolean; recordId?: string; seq?: number; reason?: string }> }> {
+    const res = await this.fetch(
+      `${this.baseUrl}${NODE_SYNC_PUSH_PATH}`,
+      this.init({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: Buffer.from(JSON.stringify({ records: envelopes }), 'utf8'),
+      }),
+    );
+    const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+    if (res.status < 200 || res.status >= 300) {
+      const reason = readError(body);
+      throw new NodeClientError(
+        `node ${NODE_SYNC_PUSH_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`,
+        res.status,
+        reason,
+      );
+    }
+    const obj = body as { accepted?: unknown; results?: unknown };
+    return {
+      accepted: typeof obj.accepted === 'number' ? obj.accepted : 0,
+      results: Array.isArray(obj.results)
+        ? (obj.results as Array<{ ok: boolean; recordId?: string; seq?: number; reason?: string }>)
+        : [],
+    };
+  }
+
+  /** Fetch a content-addressed blob. Returns `null` on a 404; throws on other non-2xx. */
+  async getBlob(hash: string): Promise<Buffer | null> {
+    const res = await this.fetch(`${this.baseUrl}${NODE_BLOBS_PATH}/${encodeURIComponent(hash)}`, this.init({ method: 'GET' }));
+    if (res.status === 404) {
+      res.destroy();
+      return null;
+    }
+    if (res.status < 200 || res.status >= 300) {
+      res.destroy();
+      throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}`, res.status);
+    }
+    return readBoundedBytes(res, this.blobMaxBytes);
+  }
+
+  /**
+   * Pin a content-addressed blob with an owner-signed authorization
+   * (`PUT /blobs/:hash`). The caller signs the pin (it holds the owner key) and
+   * passes the resulting `{ publicKey, signature, timestamp }`; the client sets
+   * the owner-auth headers. Throws {@link NodeClientError} on a non-2xx.
+   */
+  async putBlob(hash: string, bytes: Uint8Array, auth: NodeBlobPinAuth): Promise<NodeBlobPutResult> {
+    const res = await this.fetch(
+      `${this.baseUrl}${NODE_BLOBS_PATH}/${encodeURIComponent(hash)}`,
+      this.init({
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          [OWNER_AUTH_HEADERS.publicKey]: auth.publicKey,
+          [OWNER_AUTH_HEADERS.signature]: auth.signature,
+          [OWNER_AUTH_HEADERS.timestamp]: String(auth.timestamp),
+        },
+        body: bytes,
+      }),
+    );
+    const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+    if (res.status < 200 || res.status >= 300) {
+      const reason = readError(body);
+      throw new NodeClientError(
+        `node ${NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`,
+        res.status,
+        reason,
+      );
+    }
+    const obj = body as { hash?: unknown; size?: unknown };
+    if (typeof obj.hash !== 'string' || typeof obj.size !== 'number') {
+      throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash returned a malformed pin result`, res.status);
+    }
+    return { hash: obj.hash, size: obj.size };
+  }
+}

package/src/node/rateLimit.ts

@@ -0,0 +1,233 @@
+/**
+ * A small, dependency-free fixed-window per-IP rate limiter for the node app's
+ * owner-authorized write routes.
+ *
+ * The node is a single-writer model (only the owner key may write), so the
+ * limiter is a defence-in-depth budget on the unauthenticated edge — it caps the
+ * request rate BEFORE signature verification so a flood of bogus envelopes can't
+ * pin CPU on crypto. It is intentionally process-local (a single node serves one
+ * owner's repo); there is no shared store to coordinate.
+ *
+ * Fixed-window counting, one budget per client: each key gets `max` requests per
+ * `windowMs`, and the window resets lazily on the first request after it elapses.
+ * The key is a SALTED HASH of the client address, never the address itself — see
+ * {@link clientRateLimitKey}.
+ *
+ * Bounded memory (defence against a key-rotation DoS — spoofed IPs / many DIDs
+ * growing the map without limit → memory exhaustion):
+ *  - An ACTIVE periodic sweep on an `unref()`'d interval deletes every entry
+ *    whose window has fully elapsed, so keys that are never touched again do not
+ *    leak forever (lazy expiry-on-access alone cannot reclaim them). The
+ *    interval is `unref()`'d so it never keeps the node process alive, and
+ *    {@link RateLimiter.stop} clears it for a clean lifecycle teardown.
+ *  - A hard cap on the number of tracked keys ({@link RateLimitConfig.maxEntries})
+ *    evicts the OLDEST window (insertion-order LRU) when exceeded — a synchronous
+ *    backstop against a burst that arrives between sweeps.
+ */
+
+import { createHmac, randomBytes } from 'node:crypto';
+import type { Request, Response, NextFunction } from 'express';
+
+// The package's `lib` includes `DOM` (the isomorphic root code uses Web Crypto),
+// so the ambient `setInterval` overload TypeScript picks for a bare call is the
+// browser one returning `number` — which has no `.unref()`. This `node/` subpath
+// is Node-only; reach the Node timer globals through their `@types/node`
+// signatures so the handle is correctly `NodeJS.Timeout` (no cast, no shadowing).
+// Resolved at call time (not captured at module load) so test fake-timers that
+// swap the globals still drive the sweep.
+function nodeSetInterval(handler: () => void, ms: number): NodeJS.Timeout {
+  const set: (handler: () => void, ms: number) => NodeJS.Timeout = globalThis.setInterval;
+  return set(handler, ms);
+}
+function nodeClearInterval(timer: NodeJS.Timeout): void {
+  const clear: (timer: NodeJS.Timeout) => void = globalThis.clearInterval;
+  clear(timer);
+}
+
+/**
+ * The HMAC key under which client addresses are hashed into rate-limit keys.
+ * 256 CSPRNG bits, minted once when this module is first loaded and held only in
+ * memory — never read from a config, never written anywhere, never sent.
+ *
+ * ## Why the salt is deliberately EPHEMERAL, and what a stable one would cost
+ *
+ * A rate-limit window is short-lived (`windowMs`, seconds to a minute) and this
+ * limiter is process-local by design — a node serves one owner's repo and there
+ * is no shared store to coordinate. So nothing here needs a key to mean the same
+ * thing after a restart, or to mean the same thing on another node. That makes a
+ * per-process salt not merely sufficient but BETTER than a configured one:
+ *
+ *   - there is no value to distribute, so there is nothing for a node operator to
+ *     get wrong, nothing to rotate, and nothing to leak from an env file, a
+ *     process listing or a container image;
+ *   - the mapping dies with the process, so the same address hashes to a
+ *     different key after every restart and the keys correlate to nothing once
+ *     the process exits.
+ *
+ * A stable salt (an env var, a file) would buy exactly one thing this limiter
+ * does not want — a client identifier that survives a restart and can be compared
+ * across nodes — in exchange for a config burden and a secret at rest. That is
+ * the trade, and it is why this is not configurable.
+ *
+ * ## What the hash does and does not buy, stated honestly
+ *
+ * It removes the raw address from the process's data structures: the limiter's
+ * Map holds digests, so an address is no longer sitting in memory as a key for
+ * the lifetime of a window, and nothing downstream can casually read one back
+ * out. What it does NOT claim is secrecy against an attacker who already has the
+ * live process — the salt is in the same heap, and with it the IPv4 space is
+ * enumerable. That is the general reason hashing is not an acceptable AT-REST
+ * form for an address anywhere in Oxy; this value is never at rest.
+ */
+const CLIENT_KEY_SALT = randomBytes(32);
+
+/**
+ * The rate-limit key for a request: a salted hash of the client address, or the
+ * `'unknown'` sentinel when Express resolved no address at all (a request whose
+ * address is unknown cannot be budgeted individually, so all of them share one
+ * bucket — the same behaviour this limiter has always had).
+ *
+ * Truncated to 96 bits, which keeps a tracked entry to a short string beside its
+ * two numbers (the memory-bounding rationale on {@link RateLimitConfig.maxEntries}
+ * assumes exactly that). At the 10 000-entry cap a collision — two clients
+ * sharing one budget — has probability around 10⁸/2⁹⁷, i.e. never.
+ *
+ * Residue, named rather than left implicit: the address is hashed VERBATIM, so an
+ * IPv6 client that rotates through its /64 still mints a fresh key per address,
+ * exactly as it did before this was hashed. oxy-api's `hashedIpKey` buckets IPv6
+ * to /56 first to close that; doing the same here is a rate-limiting change with
+ * its own reasoning (it makes a whole prefix share one budget) and is deliberately
+ * not folded into a privacy fix.
+ *
+ * Exported for {@link createRateLimiter}'s own tests, not part of
+ * `@oxy.so/protocol/node`'s public surface — it is not re-exported by the barrel.
+ */
+export function clientRateLimitKey(req: Request): string {
+  const ip = req.ip;
+  if (!ip) {
+    return 'unknown';
+  }
+  // Single-purpose salt: it derives this key and nothing else, so there is no
+  // second derivation to namespace against (oxy-api's `hashedIpKey` prefixes
+  // `rl|` because its salt is shared with deviceId derivation). A future second
+  // use of this salt would need a namespace, or its own salt.
+  return createHmac('sha256', CLIENT_KEY_SALT).update(ip).digest('hex').slice(0, 24);
+}
+
+/** A request-rate budget: at most `max` requests per `windowMs`. */
+export interface RateLimitConfig {
+  /** The rolling window length, in milliseconds. */
+  readonly windowMs: number;
+  /** The maximum number of requests permitted within one window. */
+  readonly max: number;
+  /**
+   * Hard cap on the number of distinct keys (client identifiers) tracked at
+   * once. When the map exceeds this, the oldest-inserted window is evicted as a
+   * synchronous backstop against a burst of distinct keys arriving between
+   * sweeps. Defaults to {@link DEFAULT_MAX_RATE_LIMIT_ENTRIES}.
+   */
+  readonly maxEntries?: number;
+}
+
+/** Default budget for owner write routes (generous — single-writer model). */
+export const DEFAULT_WRITE_RATE_LIMIT: RateLimitConfig = { windowMs: 60_000, max: 60 };
+
+/**
+ * Default hard cap on tracked keys. Sized so the map's worst-case footprint
+ * stays small (each entry is a short string key + two numbers) while never
+ * evicting a legitimately active key for the single-writer node — the owner
+ * drives traffic from a handful of IPs, far below this ceiling.
+ */
+export const DEFAULT_MAX_RATE_LIMIT_ENTRIES = 10_000;
+
+interface WindowCounter {
+  /** Epoch ms when the current window started. */
+  start: number;
+  /** Requests counted in the current window. */
+  count: number;
+}
+
+/**
+ * The Express middleware returned by {@link createRateLimiter}, carrying a
+ * {@link stop} hook so the owning app can clear the background sweep on shutdown.
+ */
+export interface RateLimiter {
+  (req: Request, res: Response, next: NextFunction): void;
+  /**
+   * Stop the background sweep timer. Idempotent. Called by the node app's
+   * graceful-shutdown path; not required for process exit (the timer is
+   * `unref()`'d) but keeps long-lived test harnesses leak-free.
+   */
+  stop(): void;
+}
+
+/**
+ * Build an Express middleware enforcing a fixed-window per-client rate limit.
+ * Exceeding the budget responds `429 { error: 'rate_limited' }` and does not call
+ * `next`. The key is {@link clientRateLimitKey} — a salted hash of Express's
+ * resolved client IP, so no address is held in the tracked map.
+ *
+ * The returned middleware owns a background sweep timer; call {@link RateLimiter.stop}
+ * to release it (e.g. on app shutdown).
+ */
+export function createRateLimiter(config: RateLimitConfig): RateLimiter {
+  const windows = new Map<string, WindowCounter>();
+  const maxEntries = config.maxEntries ?? DEFAULT_MAX_RATE_LIMIT_ENTRIES;
+
+  // Active sweep: delete every entry whose window has fully elapsed. Running on
+  // a timer (rather than only on request arrival) reclaims keys that are never
+  // touched again, so a churn of distinct IPs cannot leak memory once traffic
+  // for those keys stops. One pass per window is sufficient: an entry lives at
+  // most `2 * windowMs` before a sweep removes it.
+  function sweepExpired(): void {
+    const now = Date.now();
+    for (const [key, counter] of windows) {
+      if (now - counter.start >= config.windowMs) {
+        windows.delete(key);
+      }
+    }
+  }
+
+  const sweepTimer = nodeSetInterval(sweepExpired, config.windowMs);
+  // Never let the sweep keep the node process alive on its own.
+  sweepTimer.unref();
+
+  function rateLimit(req: Request, res: Response, next: NextFunction): void {
+    const now = Date.now();
+    const key = clientRateLimitKey(req);
+    const counter = windows.get(key);
+
+    if (!counter || now - counter.start >= config.windowMs) {
+      // Hard cap backstop: if a burst of distinct keys outran the sweep, evict
+      // the oldest-inserted window before admitting a new key. A `Map` preserves
+      // insertion order, so its first key is the oldest tracked entry.
+      if (!counter && windows.size >= maxEntries) {
+        const oldest = windows.keys().next().value;
+        if (oldest !== undefined) {
+          windows.delete(oldest);
+        }
+      }
+      windows.set(key, { start: now, count: 1 });
+      next();
+      return;
+    }
+
+    if (counter.count >= config.max) {
+      const retryAfterSec = Math.ceil((counter.start + config.windowMs - now) / 1000);
+      res.setHeader('Retry-After', String(Math.max(retryAfterSec, 1)));
+      res.status(429).json({ error: 'rate_limited' });
+      return;
+    }
+
+    counter.count += 1;
+    next();
+  }
+
+  // Attach the lifecycle hook to the middleware, yielding the `RateLimiter`
+  // callable-with-`stop` without a cast.
+  return Object.assign(rateLimit, {
+    stop(): void {
+      nodeClearInterval(sweepTimer);
+    },
+  });
+}

package/src/node/verifyRecord.ts

@@ -0,0 +1,60 @@
+/**
+ * Record verification for a data node — reuses the protocol envelope primitives
+ * so a record verifies on the node with the EXACT code Oxy uses. No crypto is
+ * re-implemented:
+ *
+ *  - {@link verifyEnvelopeSignature} recomputes the canonical signing input (the
+ *    bytes the signature covers) from the envelope's own fields and checks the
+ *    secp256k1 DER signature against the envelope's embedded `publicKey`.
+ *  - {@link computeRecordId} recomputes `recordId = sha256(signingInput)` — the
+ *    content address used as the chain's `prev` pointer.
+ *
+ * The envelope shape is validated with the shared `signedRecordEnvelopeSchema`.
+ * A node is a v2 hash chain, so only v2 envelopes (carrying
+ * `seq`/`prev`/`collection`/`rkey`) are accepted; v1 singletons have no chain
+ * coordinates.
+ *
+ * Verification here proves the signature is internally consistent with the
+ * embedded `publicKey`. Whether that key is authorized for the node is the OWNER
+ * check (the injected owner-key authority) — on a node the authority is the
+ * configured owner public key, not a DID lookup.
+ */
+
+import { signedRecordEnvelopeSchema, type SignedRecordEnvelope } from '@oxy.so/contracts';
+import { computeRecordId } from '../envelope/recordId';
+import { verifyEnvelopeSignature } from '../envelope/sign';
+
+/** Stable, machine-readable reasons an envelope can fail node verification. */
+export type NodeVerifyRejectionReason = 'invalid_envelope' | 'not_v2' | 'bad_signature';
+
+export type NodeVerifyResult =
+  | { ok: true; envelope: SignedRecordEnvelope; recordId: string }
+  | { ok: false; reason: NodeVerifyRejectionReason };
+
+/**
+ * Validate, signature-check, and content-address a candidate signed record for a
+ * v2 hash-chain node.
+ *
+ * On success the parsed envelope and its `recordId` are returned; the caller
+ * (the node app) still enforces owner authority and chain continuity before the
+ * record is appended.
+ */
+export async function verifyNodeRecordEnvelope(input: unknown): Promise<NodeVerifyResult> {
+  const parsed = signedRecordEnvelopeSchema.safeParse(input);
+  if (!parsed.success) {
+    return { ok: false, reason: 'invalid_envelope' };
+  }
+
+  const envelope = parsed.data;
+  if (envelope.version !== 2) {
+    return { ok: false, reason: 'not_v2' };
+  }
+
+  const signatureValid = await verifyEnvelopeSignature(envelope);
+  if (!signatureValid) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+
+  const recordId = await computeRecordId(envelope);
+  return { ok: true, envelope, recordId };
+}