@oxy.so/protocol 1.0.0

package/dist/types/node/didWebResolver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `createDidWebResolver` — a {@link VerificationMethodResolver} for arbitrary
+ * `did:web` subjects, backing the chain engine on multi-subject relay/ingest
+ * paths (where the signer is NOT a local account but any DID that publishes a
+ * DID document).
+ *
+ * It resolves a `did:web:<host>[:<path>]` subject to its `did.json`, fetched via
+ * an INJECTED {@link NodeFetch} — Oxy passes an adapter over `@oxy.so/core/server`
+ * `safeFetch` (so the SSRF/transport policy stays in core); a test passes a
+ * stub. The subject's current verification keys are read from the DID document's
+ * `verificationMethod[].publicKeyHex` (the active assertion methods), and the
+ * engine's `isAuthorizedKey` then applies the uniform self-issued rule.
+ *
+ * `did:web` → URL mapping (W3C did:web):
+ *  - `did:web:example.com`        → `https://example.com/.well-known/did.json`
+ *  - `did:web:example.com:u:123`  → `https://example.com/u/123/did.json`
+ *  - a `%3A` in the host segment is decoded to `:` (an explicit port).
+ */
+import type { VerificationMethodResolver } from '../identity/resolver';
+import { type NodeFetch } from './httpFetch';
+/** Options for {@link createDidWebResolver}. */
+export interface DidWebResolverOptions {
+    /** Time-to-first-byte deadline for the `did.json` fetch (ms). */
+    headersTimeoutMs?: number;
+    /** Redirect budget for the `did.json` fetch (each re-validated by the transport). */
+    maxRedirects?: number;
+    /** Bounded read ceiling for the fetched `did.json`. */
+    maxBytes?: number;
+    /**
+     * Notified when a subject cannot be resolved (mapping/fetch/parse failure).
+     * `resolve` still returns `null` (the engine treats that as "no authorized
+     * key") — this hook gives the failure visibility without a silent catch.
+     */
+    onError?: (err: unknown, subjectDid: string) => void;
+}
+/**
+ * Map a `did:web` DID to its `did.json` URL, or `null` when `did` is not a
+ * well-formed `did:web` identifier.
+ */
+export declare function didWebToUrl(did: string): string | null;
+/**
+ * Build a {@link VerificationMethodResolver} that resolves `did:web` subjects via
+ * the injected `fetch`. Returns `null` for any subject that is not a `did:web`
+ * DID, whose `did.json` cannot be fetched, or whose document fails schema
+ * validation — the engine then treats the signer as unauthorized.
+ */
+export declare function createDidWebResolver(fetch: NodeFetch, options?: DidWebResolverOptions): VerificationMethodResolver;

package/dist/types/node/httpFetch.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The injected HTTP transport the node {@link ./nodeClient.NodeClient} and the
+ * {@link ./didWebResolver} drive — plus the bounded-read helpers that make a
+ * response stream safe to consume.
+ *
+ * The protocol package is app-agnostic and MUST NOT depend on `@oxy.so/core`
+ * (core depends on protocol). So instead of importing `@oxy.so/core/server`'s
+ * `safeFetch` directly, the node client/resolver accept a {@link NodeFetch} —
+ * Oxy supplies an adapter over `safeFetch` (HTTPS-only, DNS-pinned, private-IP
+ * denylist, bounded redirects); a test supplies an in-process stub. Either way
+ * the SSRF/transport policy stays in the injected implementation, and the
+ * bounded body read (the cap that stops a malicious node streaming forever)
+ * stays here, close to the parsing.
+ *
+ * A Node `IncomingMessage` (what `safeFetch` returns) satisfies
+ * {@link NodeFetchResponse.body} directly — it is an `AsyncIterable<Buffer>`,
+ * and `Buffer` is a `Uint8Array`.
+ */
+/** Per-request options the client passes to the injected transport. */
+export interface NodeFetchInit {
+    /** HTTP method (`GET` / `POST` / `PUT`). */
+    method: string;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** Request body (for `POST` / `PUT`); omitted for `GET`. */
+    body?: Uint8Array;
+    /** Time-to-first-byte deadline in milliseconds. */
+    headersTimeoutMs?: number;
+    /** Redirect budget (each hop re-validated by the implementation). */
+    maxRedirects?: number;
+}
+/** The streamed, non-redirect response the transport returns. */
+export interface NodeFetchResponse {
+    /** HTTP status code. */
+    status: number;
+    /** Response headers (a Node `IncomingHttpHeaders` satisfies this). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Async-iterable byte body — read with the bounded helpers below. */
+    body: AsyncIterable<Uint8Array>;
+    /** Release the underlying stream when a bounded read is cut short. */
+    destroy(): void;
+}
+/**
+ * The injected transport. Oxy adapts `@oxy.so/core/server`'s `safeFetch` to this
+ * shape; tests pass an in-process stub.
+ */
+export type NodeFetch = (url: string, init: NodeFetchInit) => Promise<NodeFetchResponse>;
+/** Thrown when a response body exceeds the caller's byte ceiling. */
+export declare class ResponseTooLargeError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+/**
+ * Read a response body into a single buffer, aborting (and destroying the
+ * stream) the moment it exceeds `maxBytes`. The bound is the defence against a
+ * node that streams an unbounded body.
+ */
+export declare function readBoundedBytes(res: NodeFetchResponse, maxBytes: number): Promise<Buffer>;
+/** Read a bounded response body and parse it as JSON. */
+export declare function readBoundedJson(res: NodeFetchResponse, maxBytes: number): Promise<unknown>;

package/dist/types/node/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@oxy.so/protocol/node` — the runnable node substrate.
+ *
+ * The Node-only half of the protocol: the Express app factory that backs any
+ * Oxy-protocol data node ({@link createNodeApp}), the HTTP {@link NodeClient}
+ * that drives a node's routes, the `did:web` verification-method resolver, the
+ * record verifier, and the node-protocol shape constants. A SEPARATE subpath
+ * from the package root so this Express/Node-only code never enters React
+ * Native / web bundles that import `@oxy.so/protocol`.
+ *
+ * Reused by `@oxy.so/node` (the runnable node), a future `mention-node` (an
+ * env-only deployment of the same base), and oxy-api's node sync (which drives
+ * a node via `NodeClient`).
+ */
+export { createNodeApp, BlobHashMismatchError } from './nodeApp';
+export type { NodeApp, NodeAppDependencies, NodeAppConfig, NodeStoreLike, OwnerAuth, NodeLogger, } from './nodeApp';
+export { createRateLimiter, DEFAULT_WRITE_RATE_LIMIT, DEFAULT_MAX_RATE_LIMIT_ENTRIES, } from './rateLimit';
+export type { RateLimitConfig, RateLimiter } from './rateLimit';
+export { verifyNodeRecordEnvelope } from './verifyRecord';
+export type { NodeVerifyResult, NodeVerifyRejectionReason } from './verifyRecord';
+export { NodeClient, NodeClientError, trimTrailingSlashes } from './nodeClient';
+export type { NodeClientOptions, NodeHead, NodeLogPage, NodeWriteResult, NodeBlobPutResult, NodeBlobPinAuth, } from './nodeClient';
+export { readBoundedBytes, readBoundedJson, ResponseTooLargeError } from './httpFetch';
+export type { NodeFetch, NodeFetchInit, NodeFetchResponse } from './httpFetch';
+export { createDidWebResolver, didWebToUrl } from './didWebResolver';
+export type { DidWebResolverOptions } from './didWebResolver';
+export { PROTOCOL_VERSION, DEFAULT_WELL_KNOWN_PATH, DEFAULT_SERVICE_TYPE, DEFAULT_APP_NAMESPACE, DEFAULT_PORT, DEFAULT_LOG_LIMIT, MAX_LOG_LIMIT, DEFAULT_MAX_BLOB_BYTES, MAX_SYNC_BATCH, JSON_BODY_LIMIT, OWNER_AUTH_HEADERS, OWNER_AUTH_MAX_AGE_MS, NODE_MODES, OWNER_ACTION_BLOB_PIN, SHA256_HEX, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, NODE_BLOBS_PATH, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, DEFAULT_DID_DOC_MAX_BYTES, } from './constants';
+export type { NodeMode } from './constants';

package/dist/types/node/nodeApp.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `createNodeApp` — the app-agnostic Express factory for an Oxy-protocol data
+ * node. A node stores and serves ONE owner's append-only signed-record log
+ * (their "personal repo") plus the content-addressed blobs the records point at.
+ *
+ * This is the engine extracted from `@oxy.so/node` so the SAME code can back many
+ * app-node deployments (the Oxy identity node, a future Mention node) that
+ * differ only by ENV: the namespace they serve, their well-known manifest path,
+ * their advertised protocol id + service-type, and their owner key. Everything
+ * app-specific is INJECTED:
+ *
+ *  - `store`     — a {@link RecordStore} + {@link BlobStore} (the node's SQLite
+ *                  store, or a test stub). The node holds exactly one subject's
+ *                  repo, so the store keys a single global chain and ignores the
+ *                  subject argument; `createNodeApp` passes the node's own key as
+ *                  a stable sentinel.
+ *  - `ownerAuth` — the single write authority. Records and blob pins are
+ *                  authorized against the node's configured owner key. This is
+ *                  injected (rather than importing `@oxy.so/core/server`) so the
+ *                  protocol package never depends on core.
+ *  - `config`    — the wire-shape knobs (well-known path, protocol id,
+ *                  service-type, mode, blob ceiling, collection allowlist).
+ *  - `logger`    — structured logging for the terminal error handler.
+ *
+ * Endpoints:
+ *  - `GET  <wellKnownPath>` — node identity + liveness (a probe target).
+ *  - `GET  /oxy/head`       — chain head `{ seq, headRecordId, recordCount }`.
+ *  - `GET  /oxy/log`        — ordered envelopes from a cursor (ingest).
+ *  - `POST /records`        — owner writes a single signed envelope.
+ *  - `POST /sync/push`      — owner pushes a batch of signed envelopes.
+ *  - `GET  /blobs/:hash`    — serve a content-addressed blob.
+ *  - `PUT  /blobs/:hash`    — owner pins a blob (signed-header auth).
+ *  - `GET  /health`         — container liveness.
+ */
+import { type Express } from 'express';
+import type { RecordStore, BlobStore } from '../chain/recordStore';
+import { type RateLimitConfig } from './rateLimit';
+/**
+ * The Express app returned by {@link createNodeApp}, augmented with a {@link stop}
+ * hook that releases the app's background resources (currently the rate-limiter's
+ * sweep timer). The node bootstrap calls it from the graceful-shutdown path.
+ */
+export interface NodeApp extends Express {
+    /**
+     * Release the app's background resources (the rate-limiter sweep timer).
+     * Idempotent and safe to call on shutdown; not required for process exit (the
+     * timer is `unref()`'d) but keeps long-lived test harnesses leak-free.
+     */
+    stop(): void;
+}
+/**
+ * Thrown by a {@link BlobStore.putBlob} implementation when bytes do not hash to
+ * the supplied address. Defined here (rather than in `@oxy.so/node`) so the node
+ * app can map it to `hash_mismatch` without importing the store implementation.
+ */
+export declare class BlobHashMismatchError extends Error {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
+/** The store a node app drives — the chain log plus the blob store. */
+export type NodeStoreLike = RecordStore & BlobStore;
+/**
+ * The owner authority for node writes (the single write principal). Injected so
+ * the protocol package stays free of `@oxy.so/core` — `@oxy.so/node` provides an
+ * implementation bound to its configured owner key.
+ */
+export interface OwnerAuth {
+    /** True iff `publicKey` is the node's configured owner key (constant-time). */
+    isOwnerKey(publicKey: string): boolean;
+    /**
+     * Verify an owner-signed authorization for a blob pin over `hash` (a fresh
+     * signed header proving control, since the body is raw bytes not an envelope).
+     */
+    verifyBlobPin(hash: string, auth: {
+        publicKey: string;
+        signature: string;
+        timestamp: number;
+    }): Promise<boolean>;
+}
+/** The wire-shape configuration a node app advertises + enforces. */
+export interface NodeAppConfig {
+    /** Path the liveness manifest is served at (e.g. `/.well-known/oxy-node.json`). */
+    readonly wellKnownPath: string;
+    /** Node-protocol id advertised as `version` in the manifest (e.g. `oxy-node/1`). */
+    readonly protocolId: string;
+    /** Service-type label advertised in the manifest (e.g. `OxyPersonalDataNode`). */
+    readonly serviceType: string;
+    /** Operating mode advertised in the manifest (`self-hosted` / `managed`). */
+    readonly mode: string;
+    /** The node's advertised public key (its single-chain subject sentinel). */
+    readonly nodePublicKey: string;
+    /** Upper bound on a single pinned blob, in bytes. */
+    readonly maxBlobBytes: number;
+    /**
+     * Collection allowlist. EMPTY = accept any collection (the existing Oxy node
+     * behaviour). NON-EMPTY = only these collections may be written (else
+     * `foreign_collection`) and the public log is filtered to them.
+     */
+    readonly collections: readonly string[];
+    /**
+     * Per-IP rate budget for the owner-authorized WRITE routes (`POST /records`,
+     * `POST /sync/push`, `PUT /blobs/:hash`). Defence-in-depth on the
+     * unauthenticated edge, capping request rate BEFORE signature verification.
+     * Defaults to {@link DEFAULT_WRITE_RATE_LIMIT} (60/min) — generous for the
+     * single-writer model.
+     */
+    readonly writeRateLimit?: RateLimitConfig;
+}
+/** Minimal structured logger (a pino `Logger` satisfies this structurally). */
+export interface NodeLogger {
+    error(obj: object, msg?: string): void;
+}
+export interface NodeAppDependencies {
+    store: NodeStoreLike;
+    config: NodeAppConfig;
+    ownerAuth: OwnerAuth;
+    logger: NodeLogger;
+}
+export declare function createNodeApp(deps: NodeAppDependencies): NodeApp;

package/dist/types/node/nodeClient.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `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 } from './httpFetch';
+/** 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 declare class NodeClientError extends Error {
+    readonly status?: number | undefined;
+    readonly reason?: string | undefined;
+    constructor(message: string, status?: number | undefined, reason?: string | undefined);
+}
+/** 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;
+}
+/**
+ * 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 declare function trimTrailingSlashes(value: string): string;
+export declare class NodeClient {
+    private readonly baseUrl;
+    private readonly fetch;
+    private readonly headersTimeoutMs;
+    private readonly maxRedirects;
+    private readonly headMaxBytes;
+    private readonly logMaxBytes;
+    private readonly writeResponseMaxBytes;
+    private readonly blobMaxBytes;
+    constructor(options: NodeClientOptions);
+    /** Base request options shared by every call (timeout + redirect budget). */
+    private init;
+    /** The node's current chain head. Throws {@link NodeClientError} on a non-2xx. */
+    head(): Promise<NodeHead>;
+    /**
+     * 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.
+     */
+    log(sinceSeq: number, limit: number): Promise<NodeLogPage>;
+    /**
+     * 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.
+     */
+    writeRecord(envelope: SignedRecordEnvelope): Promise<NodeWriteResult>;
+    /**
+     * 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`).
+     */
+    pushRecords(envelopes: SignedRecordEnvelope[]): Promise<{
+        accepted: number;
+        results: Array<{
+            ok: boolean;
+            recordId?: string;
+            seq?: number;
+            reason?: string;
+        }>;
+    }>;
+    /** Fetch a content-addressed blob. Returns `null` on a 404; throws on other non-2xx. */
+    getBlob(hash: string): Promise<Buffer | null>;
+    /**
+     * 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.
+     */
+    putBlob(hash: string, bytes: Uint8Array, auth: NodeBlobPinAuth): Promise<NodeBlobPutResult>;
+}

package/dist/types/node/rateLimit.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 type { Request, Response, NextFunction } from 'express';
+/**
+ * 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 declare function clientRateLimitKey(req: Request): string;
+/** 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 declare const DEFAULT_WRITE_RATE_LIMIT: RateLimitConfig;
+/**
+ * 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 declare const DEFAULT_MAX_RATE_LIMIT_ENTRIES = 10000;
+/**
+ * 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 declare function createRateLimiter(config: RateLimitConfig): RateLimiter;

package/dist/types/node/verifyRecord.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { type SignedRecordEnvelope } from '@oxy.so/contracts';
+/** 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 declare function verifyNodeRecordEnvelope(input: unknown): Promise<NodeVerifyResult>;

package/dist/types/platform/crypto.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Platform Crypto / Storage — Default Variant (Node.js, Browser, generic bundlers)
+ *
+ * Provides lazy access to platform-specific crypto and storage modules.
+ *
+ * # Variants
+ *
+ * This module ships in two physical variants on disk, selected per consumer
+ * by the bundler / runtime:
+ *
+ * - `crypto.js`           — this file. Used by Node.js, Vite, webpack,
+ *                           Rollup, esbuild, and anything that does not match
+ *                           Metro's `*.native.js` source-extension preference.
+ * - `crypto.native.js`    — sibling file. Picked up automatically by Metro's
+ *                           resolver (which prefers `*.<platform>.js` and
+ *                           `*.native.js` over plain `*.js` when
+ *                           `preferNativePlatform` is true — Expo sets this for
+ *                           all non-web builds).
+ *
+ * The `package.json#exports` map also declares a `"react-native"` condition
+ * pointing at the same `dist/esm/index.js` entry — that entry transitively
+ * imports `./platform/crypto`, and Metro's per-file source-extension lookup
+ * substitutes the `.native.js` sibling automatically inside `dist/`. The
+ * package's top-level `"react-native"` map additionally pins the built
+ * `platform/crypto.js` (under both `dist/cjs` and `dist/esm`) to its
+ * `crypto.native.js` sibling belt-and-braces. This means consumers never have
+ * to add resolver shims; Metro Just Works.
+ *
+ * Both variants expose the EXACT same public API; importers don't need to know
+ * which one they got. The variant difference is purely about which underlying
+ * native modules each one references:
+ *
+ *   ┌──────────────────┬───────────────────────┬───────────────────────────────┐
+ *   │ Function         │ Default variant       │ React Native variant          │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadNodeCrypto   │ `await import('crypto')` (Node built-in)              │
+ *   │                  │                       │ throws — Node crypto is not   │
+ *   │                  │                       │ available on Hermes/RN        │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadExpoCrypto   │ throws — expo-crypto  │ optional `require('expo-      │
+ *   │                  │ is not part of a      │ crypto')`                     │
+ *   │                  │ Node/Vite bundle      │                               │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadSecureStore  │ throws (web/Node have │ optional `require('expo-      │
+ *   │                  │ their own storage)    │ secure-store')`               │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadAsyncStorage │ throws (web/Node have │ optional `require('@react-    │
+ *   │                  │ their own storage)    │ native-async-storage/...')`   │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ getRandomBytesRN │ throws (RN-only)      │ direct call into expo-crypto  │
+ *   └──────────────────┴───────────────────────┴───────────────────────────────┘
+ *
+ * Crucially, the default variant references ONLY Node's `'crypto'`. It never
+ * mentions `expo-*` or `@react-native-async-storage/*` — so Vite, webpack,
+ * esbuild, Rollup, and Node itself can bundle / require it without ever
+ * attempting to resolve those RN-only packages.
+ *
+ * The React Native variant references ONLY the RN packages, each behind
+ * Metro's optional-dependency mechanism (a literal `require()` inside a `try`)
+ * because they are declared OPTIONAL peer dependencies. It never mentions
+ * `'crypto'` — so Metro and Hermes have nothing to choke on.
+ *
+ * # Why not a single file with dynamic import?
+ *
+ * A previous iteration used a "bundler-opaque" `new Function('s', 'return
+ * import(s)')` trick so a single file could service every platform. It
+ * bundled cleanly on Metro but Hermes refused to PARSE the resulting
+ * `import()` expression inside a Function-constructor body
+ * (`SyntaxError: Invalid expression encountered` at the `(` of `import(`).
+ * The platform-extension split is the only approach that lets each runtime
+ * see a file containing only specifiers it can understand — no tricks, no
+ * runtime parsing risks.
+ */
+import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
+export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+export declare function loadNodeCrypto(): Promise<typeof import('crypto')>;
+export declare function loadExpoCrypto(): Promise<ExpoCryptoLike>;
+export declare function loadSecureStore(): Promise<ExpoSecureStoreLike>;
+export declare function loadAsyncStorage(): Promise<{
+    default: {
+        getItem: (key: string) => Promise<string | null>;
+        setItem: (key: string, value: string) => Promise<void>;
+        removeItem: (key: string) => Promise<void>;
+    };
+}>;
+/**
+ * Synchronous random-bytes via `expo-crypto.getRandomBytes`. Only available
+ * in the React Native variant. The default variant throws because Node and
+ * browsers have their own native CSPRNGs (`crypto.randomBytes` and
+ * `crypto.getRandomValues` respectively) — callers should use those.
+ */
+export declare function getRandomBytesRN(_byteCount: number): Uint8Array;
+export declare function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null>;