@oxy.so/protocol 1.0.0

package/dist/cjs/node/constants.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DID_DOC_MAX_BYTES = exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = exports.DEFAULT_LOG_MAX_BYTES = exports.DEFAULT_HEAD_MAX_BYTES = exports.DEFAULT_CLIENT_MAX_REDIRECTS = exports.DEFAULT_CLIENT_TIMEOUT_MS = exports.NODE_BLOBS_PATH = exports.NODE_SYNC_PUSH_PATH = exports.NODE_RECORDS_PATH = exports.NODE_LOG_PATH = exports.NODE_HEAD_PATH = exports.SHA256_HEX = exports.OWNER_ACTION_BLOB_PIN = exports.NODE_MODES = exports.OWNER_AUTH_MAX_AGE_MS = exports.OWNER_AUTH_HEADERS = exports.JSON_BODY_LIMIT = exports.MAX_SYNC_BATCH = exports.DEFAULT_MAX_BLOB_BYTES = exports.MAX_LOG_LIMIT = exports.DEFAULT_LOG_LIMIT = exports.DEFAULT_PORT = exports.DEFAULT_APP_NAMESPACE = exports.DEFAULT_SERVICE_TYPE = exports.DEFAULT_WELL_KNOWN_PATH = exports.PROTOCOL_VERSION = void 0;
+/**
+ * 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).
+ */
+exports.PROTOCOL_VERSION = 'oxy-node/1';
+/** Default well-known manifest path (the existing `@oxy.so/node` value). */
+exports.DEFAULT_WELL_KNOWN_PATH = '/.well-known/oxy-node.json';
+/** Default DID-document service-type label advertised by a node deployment. */
+exports.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.
+ */
+exports.DEFAULT_APP_NAMESPACE = 'app.oxy';
+/** Default HTTP port when the port env var is unset (always overridable). */
+exports.DEFAULT_PORT = 4000;
+/** Default and maximum number of log entries returned by `GET /oxy/log`. */
+exports.DEFAULT_LOG_LIMIT = 100;
+exports.MAX_LOG_LIMIT = 500;
+/** Default upper bound on a single pinned blob's size when unset (25 MiB). */
+exports.DEFAULT_MAX_BLOB_BYTES = 25 * 1024 * 1024;
+/** Maximum number of envelopes accepted in one `POST /sync/push` batch. */
+exports.MAX_SYNC_BATCH = 200;
+/** Body-size ceiling for JSON request bodies (`/records`, `/sync/push`). */
+exports.JSON_BODY_LIMIT = '5mb';
+/** HTTP headers carrying an owner-signed action authorization (blob pins). */
+exports.OWNER_AUTH_HEADERS = {
+    publicKey: 'x-oxy-node-public-key',
+    signature: 'x-oxy-node-signature',
+    timestamp: 'x-oxy-node-timestamp',
+};
+/**
+ * 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.
+ */
+exports.OWNER_AUTH_MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
+/** Operating modes a node can advertise. */
+exports.NODE_MODES = ['self-hosted', 'managed'];
+/** The node operation an owner can authorize with a signed header. */
+exports.OWNER_ACTION_BLOB_PIN = 'blob-pin';
+/** A 32-byte (64 hex char) lowercase SHA-256 digest, used as the blob address. */
+exports.SHA256_HEX = /^[0-9a-f]{64}$/;
+/* -------------------------------------------------------------------------- */
+/*  HTTP NodeClient — the node-facing routes a client drives                  */
+/* -------------------------------------------------------------------------- */
+/** Chain head endpoint (`GET`). */
+exports.NODE_HEAD_PATH = '/oxy/head';
+/** Ordered log endpoint (`GET ?since=&limit=`). */
+exports.NODE_LOG_PATH = '/oxy/log';
+/** Single-record write endpoint (`POST`, owner-signed envelope). */
+exports.NODE_RECORDS_PATH = '/records';
+/** Batch push endpoint (`POST`, owner-signed envelopes). */
+exports.NODE_SYNC_PUSH_PATH = '/sync/push';
+/** Content-addressed blob endpoint prefix (`GET|PUT /blobs/:hash`). */
+exports.NODE_BLOBS_PATH = '/blobs';
+/** Default time-to-first-byte deadline for a NodeClient request (ms). */
+exports.DEFAULT_CLIENT_TIMEOUT_MS = 8000;
+/** Default redirect budget for a NodeClient request (each re-validated upstream). */
+exports.DEFAULT_CLIENT_MAX_REDIRECTS = 1;
+/** Default bounded read for a `/oxy/head` response (tiny JSON). */
+exports.DEFAULT_HEAD_MAX_BYTES = 64 * 1024;
+/** Default bounded read for a `/oxy/log` page response. */
+exports.DEFAULT_LOG_MAX_BYTES = 2 * 1024 * 1024;
+/** Default bounded read for a small JSON write response (`/records`, blob pin). */
+exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = 64 * 1024;
+/** Default bounded read for a fetched `<did>.json` document. */
+exports.DEFAULT_DID_DOC_MAX_BYTES = 256 * 1024;

package/dist/cjs/node/didWebResolver.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * `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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didWebToUrl = didWebToUrl;
+exports.createDidWebResolver = createDidWebResolver;
+const contracts_1 = require("@oxy.so/contracts");
+const httpFetch_1 = require("./httpFetch");
+const constants_1 = require("./constants");
+/**
+ * Map a `did:web` DID to its `did.json` URL, or `null` when `did` is not a
+ * well-formed `did:web` identifier.
+ */
+function didWebToUrl(did) {
+    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) {
+    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) {
+    const byId = new Map(doc.verificationMethod
+        .filter(isSecp256k1Vm)
+        .map((vm) => [vm.id, vm.publicKeyHex]));
+    const keys = [];
+    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.
+ */
+function createDidWebResolver(fetch, options = {}) {
+    const headersTimeoutMs = options.headersTimeoutMs ?? constants_1.DEFAULT_CLIENT_TIMEOUT_MS;
+    const maxRedirects = options.maxRedirects ?? constants_1.DEFAULT_CLIENT_MAX_REDIRECTS;
+    const maxBytes = options.maxBytes ?? constants_1.DEFAULT_DID_DOC_MAX_BYTES;
+    return {
+        async resolve(subjectDid) {
+            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 (0, httpFetch_1.readBoundedJson)(res, maxBytes);
+                const parsed = contracts_1.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/dist/cjs/node/httpFetch.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseTooLargeError = void 0;
+exports.readBoundedBytes = readBoundedBytes;
+exports.readBoundedJson = readBoundedJson;
+/** Thrown when a response body exceeds the caller's byte ceiling. */
+class ResponseTooLargeError extends Error {
+    constructor(maxBytes) {
+        super(`response exceeded ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = 'ResponseTooLargeError';
+    }
+}
+exports.ResponseTooLargeError = 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.
+ */
+async function readBoundedBytes(res, maxBytes) {
+    const chunks = [];
+    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. */
+async function readBoundedJson(res, maxBytes) {
+    const bytes = await readBoundedBytes(res, maxBytes);
+    return JSON.parse(bytes.toString('utf8'));
+}

package/dist/cjs/node/index.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * `@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`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DID_DOC_MAX_BYTES = exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = exports.DEFAULT_LOG_MAX_BYTES = exports.DEFAULT_HEAD_MAX_BYTES = exports.DEFAULT_CLIENT_MAX_REDIRECTS = exports.DEFAULT_CLIENT_TIMEOUT_MS = exports.NODE_BLOBS_PATH = exports.NODE_SYNC_PUSH_PATH = exports.NODE_RECORDS_PATH = exports.NODE_LOG_PATH = exports.NODE_HEAD_PATH = exports.SHA256_HEX = exports.OWNER_ACTION_BLOB_PIN = exports.NODE_MODES = exports.OWNER_AUTH_MAX_AGE_MS = exports.OWNER_AUTH_HEADERS = exports.JSON_BODY_LIMIT = exports.MAX_SYNC_BATCH = exports.DEFAULT_MAX_BLOB_BYTES = exports.MAX_LOG_LIMIT = exports.DEFAULT_LOG_LIMIT = exports.DEFAULT_PORT = exports.DEFAULT_APP_NAMESPACE = exports.DEFAULT_SERVICE_TYPE = exports.DEFAULT_WELL_KNOWN_PATH = exports.PROTOCOL_VERSION = exports.didWebToUrl = exports.createDidWebResolver = exports.ResponseTooLargeError = exports.readBoundedJson = exports.readBoundedBytes = exports.trimTrailingSlashes = exports.NodeClientError = exports.NodeClient = exports.verifyNodeRecordEnvelope = exports.DEFAULT_MAX_RATE_LIMIT_ENTRIES = exports.DEFAULT_WRITE_RATE_LIMIT = exports.createRateLimiter = exports.BlobHashMismatchError = exports.createNodeApp = void 0;
+// ── Express app factory ───────────────────────────────────────────────────────
+var nodeApp_1 = require("./nodeApp");
+Object.defineProperty(exports, "createNodeApp", { enumerable: true, get: function () { return nodeApp_1.createNodeApp; } });
+Object.defineProperty(exports, "BlobHashMismatchError", { enumerable: true, get: function () { return nodeApp_1.BlobHashMismatchError; } });
+// ── Per-IP write rate limiter ──────────────────────────────────────────────────
+var rateLimit_1 = require("./rateLimit");
+Object.defineProperty(exports, "createRateLimiter", { enumerable: true, get: function () { return rateLimit_1.createRateLimiter; } });
+Object.defineProperty(exports, "DEFAULT_WRITE_RATE_LIMIT", { enumerable: true, get: function () { return rateLimit_1.DEFAULT_WRITE_RATE_LIMIT; } });
+Object.defineProperty(exports, "DEFAULT_MAX_RATE_LIMIT_ENTRIES", { enumerable: true, get: function () { return rateLimit_1.DEFAULT_MAX_RATE_LIMIT_ENTRIES; } });
+// ── Record verification (signature + v2 + content address) ─────────────────────
+var verifyRecord_1 = require("./verifyRecord");
+Object.defineProperty(exports, "verifyNodeRecordEnvelope", { enumerable: true, get: function () { return verifyRecord_1.verifyNodeRecordEnvelope; } });
+// ── HTTP client ────────────────────────────────────────────────────────────────
+var nodeClient_1 = require("./nodeClient");
+Object.defineProperty(exports, "NodeClient", { enumerable: true, get: function () { return nodeClient_1.NodeClient; } });
+Object.defineProperty(exports, "NodeClientError", { enumerable: true, get: function () { return nodeClient_1.NodeClientError; } });
+Object.defineProperty(exports, "trimTrailingSlashes", { enumerable: true, get: function () { return nodeClient_1.trimTrailingSlashes; } });
+// ── Injected transport contract + bounded readers ──────────────────────────────
+var httpFetch_1 = require("./httpFetch");
+Object.defineProperty(exports, "readBoundedBytes", { enumerable: true, get: function () { return httpFetch_1.readBoundedBytes; } });
+Object.defineProperty(exports, "readBoundedJson", { enumerable: true, get: function () { return httpFetch_1.readBoundedJson; } });
+Object.defineProperty(exports, "ResponseTooLargeError", { enumerable: true, get: function () { return httpFetch_1.ResponseTooLargeError; } });
+// ── did:web verification-method resolver ───────────────────────────────────────
+var didWebResolver_1 = require("./didWebResolver");
+Object.defineProperty(exports, "createDidWebResolver", { enumerable: true, get: function () { return didWebResolver_1.createDidWebResolver; } });
+Object.defineProperty(exports, "didWebToUrl", { enumerable: true, get: function () { return didWebResolver_1.didWebToUrl; } });
+// ── Node-protocol shape constants ──────────────────────────────────────────────
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return constants_1.PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "DEFAULT_WELL_KNOWN_PATH", { enumerable: true, get: function () { return constants_1.DEFAULT_WELL_KNOWN_PATH; } });
+Object.defineProperty(exports, "DEFAULT_SERVICE_TYPE", { enumerable: true, get: function () { return constants_1.DEFAULT_SERVICE_TYPE; } });
+Object.defineProperty(exports, "DEFAULT_APP_NAMESPACE", { enumerable: true, get: function () { return constants_1.DEFAULT_APP_NAMESPACE; } });
+Object.defineProperty(exports, "DEFAULT_PORT", { enumerable: true, get: function () { return constants_1.DEFAULT_PORT; } });
+Object.defineProperty(exports, "DEFAULT_LOG_LIMIT", { enumerable: true, get: function () { return constants_1.DEFAULT_LOG_LIMIT; } });
+Object.defineProperty(exports, "MAX_LOG_LIMIT", { enumerable: true, get: function () { return constants_1.MAX_LOG_LIMIT; } });
+Object.defineProperty(exports, "DEFAULT_MAX_BLOB_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_MAX_BLOB_BYTES; } });
+Object.defineProperty(exports, "MAX_SYNC_BATCH", { enumerable: true, get: function () { return constants_1.MAX_SYNC_BATCH; } });
+Object.defineProperty(exports, "JSON_BODY_LIMIT", { enumerable: true, get: function () { return constants_1.JSON_BODY_LIMIT; } });
+Object.defineProperty(exports, "OWNER_AUTH_HEADERS", { enumerable: true, get: function () { return constants_1.OWNER_AUTH_HEADERS; } });
+Object.defineProperty(exports, "OWNER_AUTH_MAX_AGE_MS", { enumerable: true, get: function () { return constants_1.OWNER_AUTH_MAX_AGE_MS; } });
+Object.defineProperty(exports, "NODE_MODES", { enumerable: true, get: function () { return constants_1.NODE_MODES; } });
+Object.defineProperty(exports, "OWNER_ACTION_BLOB_PIN", { enumerable: true, get: function () { return constants_1.OWNER_ACTION_BLOB_PIN; } });
+Object.defineProperty(exports, "SHA256_HEX", { enumerable: true, get: function () { return constants_1.SHA256_HEX; } });
+Object.defineProperty(exports, "NODE_HEAD_PATH", { enumerable: true, get: function () { return constants_1.NODE_HEAD_PATH; } });
+Object.defineProperty(exports, "NODE_LOG_PATH", { enumerable: true, get: function () { return constants_1.NODE_LOG_PATH; } });
+Object.defineProperty(exports, "NODE_RECORDS_PATH", { enumerable: true, get: function () { return constants_1.NODE_RECORDS_PATH; } });
+Object.defineProperty(exports, "NODE_SYNC_PUSH_PATH", { enumerable: true, get: function () { return constants_1.NODE_SYNC_PUSH_PATH; } });
+Object.defineProperty(exports, "NODE_BLOBS_PATH", { enumerable: true, get: function () { return constants_1.NODE_BLOBS_PATH; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_TIMEOUT_MS", { enumerable: true, get: function () { return constants_1.DEFAULT_CLIENT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_MAX_REDIRECTS", { enumerable: true, get: function () { return constants_1.DEFAULT_CLIENT_MAX_REDIRECTS; } });
+Object.defineProperty(exports, "DEFAULT_HEAD_MAX_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_HEAD_MAX_BYTES; } });
+Object.defineProperty(exports, "DEFAULT_LOG_MAX_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_LOG_MAX_BYTES; } });
+Object.defineProperty(exports, "DEFAULT_WRITE_RESPONSE_MAX_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_WRITE_RESPONSE_MAX_BYTES; } });
+Object.defineProperty(exports, "DEFAULT_DID_DOC_MAX_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_DID_DOC_MAX_BYTES; } });