@oxy.so/protocol 1.0.0

package/src/node/constants.ts

@@ -0,0 +1,105 @@
+/**
+ * Node-protocol shape constants — the wire-level contract of an Oxy-protocol
+ * data node, shared by the generic node app factory ({@link ./nodeApp}), the
+ * HTTP {@link ./nodeClient.NodeClient}, and any app's node deployment
+ * (`@oxy.so/node`, a future `mention-node`).
+ *
+ * These were previously hardcoded inside `@oxy.so/node`; they live here so the
+ * SAME values drive a server and a client without either side re-declaring (and
+ * drifting) the contract. Deployment-specific knobs (owner key, port, data dir)
+ * are still resolved per-deployment from the environment — only the protocol's
+ * own shape constants live here.
+ */
+
+/**
+ * The node-protocol version advertised at the well-known manifest. Bumped only
+ * on a breaking change to the wire shape of the log / head / record APIs. This
+ * is the DEFAULT `protocolId` a deployment advertises (overridable per app).
+ */
+export const PROTOCOL_VERSION = 'oxy-node/1' as const;
+
+/** Default well-known manifest path (the existing `@oxy.so/node` value). */
+export const DEFAULT_WELL_KNOWN_PATH = '/.well-known/oxy-node.json';
+
+/** Default DID-document service-type label advertised by a node deployment. */
+export const DEFAULT_SERVICE_TYPE = 'OxyPersonalDataNode';
+
+/**
+ * Default application namespace a node deployment serves. The records a node
+ * stores all live under this namespace (e.g. `app.oxy.*`); a `collections`
+ * allowlist (when set) MUST be within it.
+ */
+export const DEFAULT_APP_NAMESPACE = 'app.oxy';
+
+/** Default HTTP port when the port env var is unset (always overridable). */
+export const DEFAULT_PORT = 4000;
+
+/** Default and maximum number of log entries returned by `GET /oxy/log`. */
+export const DEFAULT_LOG_LIMIT = 100;
+export const MAX_LOG_LIMIT = 500;
+
+/** Default upper bound on a single pinned blob's size when unset (25 MiB). */
+export const DEFAULT_MAX_BLOB_BYTES = 25 * 1024 * 1024;
+
+/** Maximum number of envelopes accepted in one `POST /sync/push` batch. */
+export const MAX_SYNC_BATCH = 200;
+
+/** Body-size ceiling for JSON request bodies (`/records`, `/sync/push`). */
+export const JSON_BODY_LIMIT = '5mb';
+
+/** HTTP headers carrying an owner-signed action authorization (blob pins). */
+export const OWNER_AUTH_HEADERS = {
+  publicKey: 'x-oxy-node-public-key',
+  signature: 'x-oxy-node-signature',
+  timestamp: 'x-oxy-node-timestamp',
+} as const;
+
+/**
+ * Freshness window for an owner-signed action (e.g. a blob pin). A signed
+ * authorization header older/newer than this (accounting for clock skew) is
+ * rejected, bounding replay of a captured pin authorization.
+ */
+export const OWNER_AUTH_MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
+
+/** Operating modes a node can advertise. */
+export const NODE_MODES = ['self-hosted', 'managed'] as const;
+export type NodeMode = (typeof NODE_MODES)[number];
+
+/** The node operation an owner can authorize with a signed header. */
+export const OWNER_ACTION_BLOB_PIN = 'blob-pin' as const;
+
+/** A 32-byte (64 hex char) lowercase SHA-256 digest, used as the blob address. */
+export const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/* -------------------------------------------------------------------------- */
+/*  HTTP NodeClient — the node-facing routes a client drives                  */
+/* -------------------------------------------------------------------------- */
+
+/** Chain head endpoint (`GET`). */
+export const NODE_HEAD_PATH = '/oxy/head';
+/** Ordered log endpoint (`GET ?since=&limit=`). */
+export const NODE_LOG_PATH = '/oxy/log';
+/** Single-record write endpoint (`POST`, owner-signed envelope). */
+export const NODE_RECORDS_PATH = '/records';
+/** Batch push endpoint (`POST`, owner-signed envelopes). */
+export const NODE_SYNC_PUSH_PATH = '/sync/push';
+/** Content-addressed blob endpoint prefix (`GET|PUT /blobs/:hash`). */
+export const NODE_BLOBS_PATH = '/blobs';
+
+/** Default time-to-first-byte deadline for a NodeClient request (ms). */
+export const DEFAULT_CLIENT_TIMEOUT_MS = 8_000;
+
+/** Default redirect budget for a NodeClient request (each re-validated upstream). */
+export const DEFAULT_CLIENT_MAX_REDIRECTS = 1;
+
+/** Default bounded read for a `/oxy/head` response (tiny JSON). */
+export const DEFAULT_HEAD_MAX_BYTES = 64 * 1024;
+
+/** Default bounded read for a `/oxy/log` page response. */
+export const DEFAULT_LOG_MAX_BYTES = 2 * 1024 * 1024;
+
+/** Default bounded read for a small JSON write response (`/records`, blob pin). */
+export const DEFAULT_WRITE_RESPONSE_MAX_BYTES = 64 * 1024;
+
+/** Default bounded read for a fetched `<did>.json` document. */
+export const DEFAULT_DID_DOC_MAX_BYTES = 256 * 1024;

package/src/node/didWebResolver.ts

@@ -0,0 +1,162 @@
+/**
+ * `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 {
+  didDocumentSchema,
+  type DidDocument,
+  type Secp256k1VerificationMethod,
+} from '@oxy.so/contracts';
+import type {
+  ResolvedVerificationMethods,
+  VerificationMethodResolver,
+} from '../identity/resolver';
+import { type NodeFetch, readBoundedJson } from './httpFetch';
+import {
+  DEFAULT_CLIENT_MAX_REDIRECTS,
+  DEFAULT_CLIENT_TIMEOUT_MS,
+  DEFAULT_DID_DOC_MAX_BYTES,
+} from './constants';
+
+/** 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 function didWebToUrl(did: string): string | null {
+  const prefix = 'did:web:';
+  if (!did.startsWith(prefix)) {
+    return null;
+  }
+  const msi = did.slice(prefix.length);
+  if (msi.length === 0) {
+    return null;
+  }
+  const [domainPart, ...pathParts] = msi.split(':');
+  const host = domainPart.replace(/%3A/gi, ':');
+  if (host.length === 0 || host.includes('/')) {
+    return null;
+  }
+  const base = `https://${host}`;
+  if (pathParts.length === 0) {
+    return `${base}/.well-known/did.json`;
+  }
+  if (pathParts.some((part) => part.length === 0)) {
+    return null;
+  }
+  return `${base}/${pathParts.join('/')}/did.json`;
+}
+
+/** True for a secp256k1 verification method (carries `publicKeyHex`). */
+function isSecp256k1Vm(
+  vm: DidDocument['verificationMethod'][number],
+): vm is Secp256k1VerificationMethod {
+  return vm.type === 'EcdsaSecp256k1VerificationKey2019';
+}
+
+/**
+ * Collect the subject's current verification keys from its DID document: the
+ * `publicKeyHex` of every secp256k1 verification method referenced by
+ * `assertionMethod` (the keys that may sign assertions/records), deduped. Falls
+ * back to ALL secp256k1 `verificationMethod[]` keys when `assertionMethod`
+ * references nothing local. Non-secp256k1 methods (e.g. the atproto `Multikey`,
+ * which carries the SAME key in multibase form, not hex) are skipped — record
+ * signatures verify against the hex key.
+ */
+function collectCurrentPublicKeys(doc: DidDocument): string[] {
+  const byId = new Map(
+    doc.verificationMethod
+      .filter(isSecp256k1Vm)
+      .map((vm) => [vm.id, vm.publicKeyHex] as const),
+  );
+  const keys: string[] = [];
+  for (const id of doc.assertionMethod) {
+    const key = byId.get(id);
+    if (key && !keys.includes(key)) {
+      keys.push(key);
+    }
+  }
+  if (keys.length === 0) {
+    for (const key of byId.values()) {
+      if (!keys.includes(key)) {
+        keys.push(key);
+      }
+    }
+  }
+  return keys;
+}
+
+/**
+ * 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 function createDidWebResolver(
+  fetch: NodeFetch,
+  options: DidWebResolverOptions = {},
+): VerificationMethodResolver {
+  const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
+  const maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
+  const maxBytes = options.maxBytes ?? DEFAULT_DID_DOC_MAX_BYTES;
+
+  return {
+    async resolve(subjectDid: string): Promise<ResolvedVerificationMethods | null> {
+      const url = didWebToUrl(subjectDid);
+      if (!url) {
+        return null;
+      }
+      try {
+        const res = await fetch(url, { method: 'GET', headersTimeoutMs, maxRedirects });
+        if (res.status < 200 || res.status >= 300) {
+          res.destroy();
+          return null;
+        }
+        const body = await readBoundedJson(res, maxBytes);
+        const parsed = didDocumentSchema.safeParse(body);
+        if (!parsed.success) {
+          return null;
+        }
+        // The DID document `id` MUST match the subject we asked for — a document
+        // served at the subject's URL but claiming another id is not authoritative.
+        if (parsed.data.id !== subjectDid) {
+          return null;
+        }
+        return { currentPublicKeys: collectCurrentPublicKeys(parsed.data) };
+      } catch (err) {
+        options.onError?.(err, subjectDid);
+        return null;
+      }
+    },
+  };
+}

package/src/node/httpFetch.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 class ResponseTooLargeError extends Error {
+  constructor(public readonly maxBytes: number) {
+    super(`response exceeded ${maxBytes} bytes`);
+    this.name = 'ResponseTooLargeError';
+  }
+}
+
+/**
+ * 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 async function readBoundedBytes(res: NodeFetchResponse, maxBytes: number): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  try {
+    for await (const chunk of res.body) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buf.length;
+      if (total > maxBytes) {
+        throw new ResponseTooLargeError(maxBytes);
+      }
+      chunks.push(buf);
+    }
+  } catch (err) {
+    res.destroy();
+    throw err;
+  }
+  return Buffer.concat(chunks);
+}
+
+/** Read a bounded response body and parse it as JSON. */
+export async function readBoundedJson(res: NodeFetchResponse, maxBytes: number): Promise<unknown> {
+  const bytes = await readBoundedBytes(res, maxBytes);
+  return JSON.parse(bytes.toString('utf8'));
+}

package/src/node/index.ts

@@ -0,0 +1,87 @@
+/**
+ * `@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`).
+ */
+
+// ── Express app factory ───────────────────────────────────────────────────────
+export { createNodeApp, BlobHashMismatchError } from './nodeApp';
+export type {
+  NodeApp,
+  NodeAppDependencies,
+  NodeAppConfig,
+  NodeStoreLike,
+  OwnerAuth,
+  NodeLogger,
+} from './nodeApp';
+
+// ── Per-IP write rate limiter ──────────────────────────────────────────────────
+export {
+  createRateLimiter,
+  DEFAULT_WRITE_RATE_LIMIT,
+  DEFAULT_MAX_RATE_LIMIT_ENTRIES,
+} from './rateLimit';
+export type { RateLimitConfig, RateLimiter } from './rateLimit';
+
+// ── Record verification (signature + v2 + content address) ─────────────────────
+export { verifyNodeRecordEnvelope } from './verifyRecord';
+export type { NodeVerifyResult, NodeVerifyRejectionReason } from './verifyRecord';
+
+// ── HTTP client ────────────────────────────────────────────────────────────────
+export { NodeClient, NodeClientError, trimTrailingSlashes } from './nodeClient';
+export type {
+  NodeClientOptions,
+  NodeHead,
+  NodeLogPage,
+  NodeWriteResult,
+  NodeBlobPutResult,
+  NodeBlobPinAuth,
+} from './nodeClient';
+
+// ── Injected transport contract + bounded readers ──────────────────────────────
+export { readBoundedBytes, readBoundedJson, ResponseTooLargeError } from './httpFetch';
+export type { NodeFetch, NodeFetchInit, NodeFetchResponse } from './httpFetch';
+
+// ── did:web verification-method resolver ───────────────────────────────────────
+export { createDidWebResolver, didWebToUrl } from './didWebResolver';
+export type { DidWebResolverOptions } from './didWebResolver';
+
+// ── Node-protocol shape constants ──────────────────────────────────────────────
+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';