@aigne/aos 0.2.0-beta

package/dist/http/afs-rpc-wire.cjs

@@ -0,0 +1,271 @@
+
+//#region src/http/afs-rpc-wire.ts
+/**
+* afs-rpc wire contract — encoding + validation helpers.
+*
+* Single source of truth for the binary content encoding (base64) and the
+* write/delete body validation rules pinned in
+* `planning/did-integration/mobile-didspace-transport/wire-contract.md`.
+*
+* Both runtime handlers (Node `daemon/server.ts`, Cloudflare `index.ts`) share
+* `createAfsRpcHandler`; this module is where the write/delete dispatch (Phase
+* 4) decodes `content` and enforces field-position rules. Defined in Phase 0
+* so the contract is frozen before any implementation.
+*/
+/** Stable error codes surfaced on the wire (see wire-contract.md §7/§9). */
+const WIRE_ERROR_CODES = {
+	conflict: "AFS_CONFLICT",
+	payloadTooLarge: "PAYLOAD_TOO_LARGE",
+	batchOverBudget: "BATCH_OVER_BUDGET",
+	batchTailSkipped: "BATCH_TAIL_SKIPPED",
+	fileTooLarge: "FILE_TOO_LARGE"
+};
+/**
+* Extract the JWT from an `Authorization: Bearer <jwt>` header, or null when
+* absent/malformed. Shared by both runtimes' `resolveCaller` (Phase 4) so the
+* Bearer parsing is single-sourced and case-insensitive on the scheme.
+*/
+function parseBearerToken(header) {
+	if (!header) return null;
+	const token = /^Bearer\s+(.+)$/i.exec(header)?.[1]?.trim();
+	return token ? token : null;
+}
+/**
+* Decode a base64 string into bytes. Pure; no DOM/Buffer assumptions beyond
+* `atob` (present in workerd + Node 18+ globalThis). Throws on malformed input.
+*/
+function decodeContentBase64(b64) {
+	const binary = atob(b64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+/** Encode bytes into a base64 string. Inverse of {@link decodeContentBase64}. */
+function encodeContentBase64(bytes) {
+	let binary = "";
+	const CHUNK = 32768;
+	for (let i = 0; i < bytes.length; i += CHUNK) binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+	return btoa(binary);
+}
+/**
+* Validate + decode a `write` body per the wire contract.
+*
+* Enforces:
+*  - `content` present and `encoding === "base64"` (missing/other → 400).
+*    The empty string IS present — it is the canonical base64 of a 0-byte
+*    file, which must roundtrip (P6 crafted-sample finding; rejecting it
+*    made empty files unsyncable on every client).
+*  - `content` is valid base64 (bad → 400).
+*
+* Does NOT touch `options.ifMatch` placement: the field-position rule
+* (ifMatch belongs at `options.ifMatch`, never `options.meta.ifMatch` for
+* writes) is enforced by the handler reading ONLY `options.ifMatch`. A
+* misplaced `meta.ifMatch` is simply ignored (treated as absent top-level
+* ifMatch → LWW), per wire-contract.md §8.3.
+*/
+function validateAndDecodeWrite(body) {
+	if (typeof body.content !== "string") return {
+		ok: false,
+		status: 400,
+		error: "Missing 'content' for write"
+	};
+	const encoding = body.encoding ?? "base64";
+	if (encoding !== "base64") return {
+		ok: false,
+		status: 400,
+		error: `Unsupported encoding '${encoding}' (use base64)`
+	};
+	let bytes;
+	try {
+		bytes = decodeContentBase64(body.content);
+	} catch {
+		return {
+			ok: false,
+			status: 400,
+			error: "Invalid base64 in 'content'"
+		};
+	}
+	return {
+		ok: true,
+		bytes
+	};
+}
+/**
+* Read the top-level write ifMatch precondition. The misplaced
+* `options.meta.ifMatch` is intentionally NOT consulted for writes — only
+* `delete` carries ifMatch under `meta`.
+*/
+function readWriteIfMatch(options) {
+	const v = options?.ifMatch;
+	return typeof v === "string" ? v : void 0;
+}
+const MB = 1024 * 1024;
+/** Cloudflare-tier limits (free-tier portability baseline; P0-confirmed). */
+const BATCH_LIMITS_CF = {
+	maxWriteEntries: 20,
+	maxDeleteEntries: 40,
+	maxReadEntries: 20,
+	maxWriteBatchBytes: 1 * MB,
+	maxEntryWriteBytes: 16 * MB,
+	readTailSkipThresholdBytes: 4 * MB,
+	maxEncodedRequestBytes: 24 * MB
+};
+/** Node-daemon limits (no subrequest budget; bounded by memory/UX only). */
+const BATCH_LIMITS_NODE = {
+	maxWriteEntries: 100,
+	maxDeleteEntries: 100,
+	maxReadEntries: 100,
+	maxWriteBatchBytes: 16 * MB,
+	maxEntryWriteBytes: 16 * MB,
+	readTailSkipThresholdBytes: 4 * MB,
+	maxEncodedRequestBytes: 24 * MB
+};
+const BATCH_FORBIDDEN_ENTRY_FIELDS = ["blocklet", "sessionId"];
+function maxEntriesFor(type, limits) {
+	if (type === "batchWrite") return limits.maxWriteEntries;
+	if (type === "batchDelete") return limits.maxDeleteEntries;
+	return limits.maxReadEntries;
+}
+/**
+* Envelope-level validation for the three batch ops (wire-contract §9).
+*
+* Envelope rejections (zero entries executed): entries shape, per-type
+* maxEntries / Σ-decoded-bytes budget (400 BATCH_OVER_BUDGET), forbidden
+* per-entry `blocklet`/`sessionId` fields, invalid/traversal paths, and a
+* single entry over the per-entry decoded cap (413 PAYLOAD_TOO_LARGE — the
+* single-op code).
+*
+* Content-shape problems (missing/empty content, unknown encoding, bad
+* base64) are NOT envelope rejections: single-op parity says each such entry
+* fails alone, so they come back as per-entry decode outcomes in
+* `writeDecodes` for the dispatch loop to surface as `results[i]`.
+*/
+function validateBatchBody(body, limits, sanitizePath) {
+	const type = body.type ?? "";
+	const entries = body.entries;
+	if (!Array.isArray(entries) || entries.length === 0) return {
+		ok: false,
+		status: 400,
+		error: "'entries' must be a non-empty array"
+	};
+	const maxEntries = maxEntriesFor(type, limits);
+	if (entries.length > maxEntries) return {
+		ok: false,
+		status: 400,
+		error: `Too many entries for ${type} (${entries.length} > ${maxEntries})`,
+		code: WIRE_ERROR_CODES.batchOverBudget
+	};
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return {
+			ok: false,
+			status: 400,
+			error: `entries[${i}] must be an object`
+		};
+		for (const field of BATCH_FORBIDDEN_ENTRY_FIELDS) if (field in entry) return {
+			ok: false,
+			status: 400,
+			error: `entries[${i}] must not carry '${field}' (envelope-level field)`
+		};
+		const path = entry.path;
+		if (typeof path !== "string" || sanitizePath(path) === null) return {
+			ok: false,
+			status: 400,
+			error: `entries[${i}] has a missing or invalid 'path'`
+		};
+	}
+	if (type !== "batchWrite") return {
+		ok: true,
+		entries
+	};
+	const writeDecodes = [];
+	let totalDecoded = 0;
+	for (const raw of entries) {
+		const decoded = validateAndDecodeWrite({
+			type: "write",
+			path: raw.path,
+			content: raw.content,
+			encoding: raw.encoding,
+			options: raw.options
+		});
+		if (!decoded.ok) {
+			writeDecodes.push(decoded);
+			continue;
+		}
+		if (decoded.bytes.length > limits.maxEntryWriteBytes) return {
+			ok: false,
+			status: 413,
+			error: `Payload too large (> ${limits.maxEntryWriteBytes} bytes)`,
+			code: WIRE_ERROR_CODES.payloadTooLarge
+		};
+		totalDecoded += decoded.bytes.length;
+		writeDecodes.push(decoded);
+	}
+	if (totalDecoded > limits.maxWriteBatchBytes) return {
+		ok: false,
+		status: 400,
+		error: `Batch decoded bytes over budget (${totalDecoded} > ${limits.maxWriteBatchBytes})`,
+		code: WIRE_ERROR_CODES.batchOverBudget
+	};
+	return {
+		ok: true,
+		entries,
+		writeDecodes
+	};
+}
+/**
+* Read the request body with a hard byte ceiling, BEFORE any JSON parsing.
+*
+* Two layers: a fast Content-Length pre-check (rejects honest oversized
+* declarations without reading), then a bounded stream read (rejects lying
+* Content-Length — declared small, actually large). Returns `{ tooLarge }`
+* instead of throwing so the caller can shape the 413 response.
+*/
+async function readBoundedBody(request, maxBytes) {
+	const declared = Number(request.headers.get("content-length") ?? "");
+	if (Number.isFinite(declared) && declared > maxBytes) return { tooLarge: true };
+	const reader = request.body?.getReader();
+	if (!reader) {
+		const text = await request.text();
+		return text.length > maxBytes ? { tooLarge: true } : {
+			tooLarge: false,
+			text
+		};
+	}
+	const chunks = [];
+	let total = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			try {
+				await reader.cancel();
+			} catch {}
+			return { tooLarge: true };
+		}
+		chunks.push(value);
+	}
+	const buf = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		buf.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return {
+		tooLarge: false,
+		text: new TextDecoder().decode(buf)
+	};
+}
+
+//#endregion
+exports.BATCH_LIMITS_CF = BATCH_LIMITS_CF;
+exports.BATCH_LIMITS_NODE = BATCH_LIMITS_NODE;
+exports.WIRE_ERROR_CODES = WIRE_ERROR_CODES;
+exports.decodeContentBase64 = decodeContentBase64;
+exports.encodeContentBase64 = encodeContentBase64;
+exports.parseBearerToken = parseBearerToken;
+exports.readBoundedBody = readBoundedBody;
+exports.readWriteIfMatch = readWriteIfMatch;
+exports.validateAndDecodeWrite = validateAndDecodeWrite;
+exports.validateBatchBody = validateBatchBody;

package/dist/http/afs-rpc-wire.d.cts

@@ -0,0 +1,195 @@
+//#region src/http/afs-rpc-wire.d.ts
+/**
+ * afs-rpc wire contract — encoding + validation helpers.
+ *
+ * Single source of truth for the binary content encoding (base64) and the
+ * write/delete body validation rules pinned in
+ * `planning/did-integration/mobile-didspace-transport/wire-contract.md`.
+ *
+ * Both runtime handlers (Node `daemon/server.ts`, Cloudflare `index.ts`) share
+ * `createAfsRpcHandler`; this module is where the write/delete dispatch (Phase
+ * 4) decodes `content` and enforces field-position rules. Defined in Phase 0
+ * so the contract is frozen before any implementation.
+ */
+/** Stable error codes surfaced on the wire (see wire-contract.md §7/§9). */
+declare const WIRE_ERROR_CODES: {
+  readonly conflict: "AFS_CONFLICT";
+  readonly payloadTooLarge: "PAYLOAD_TOO_LARGE"; /** Batch envelope rejected up-front (entry count / Σ bytes) — zero entries executed. */
+  readonly batchOverBudget: "BATCH_OVER_BUDGET"; /** batchRead tail entry skipped (encoded-byte threshold reached) — retry next batch. */
+  readonly batchTailSkipped: "BATCH_TAIL_SKIPPED";
+  /**
+   * Declared-size upload rejected BEFORE any bytes move (ingest-prepare early
+   * reject — DID-Space upload-limits, design §8 / D7). Distinct from
+   * `PAYLOAD_TOO_LARGE` ("actual decoded bytes over the cap"): `FILE_TOO_LARGE`
+   * fires on the client-declared size at the planning stage, is per-entry, and
+   * is never auto-retried by the sync engine.
+   */
+  readonly fileTooLarge: "FILE_TOO_LARGE";
+};
+/**
+ * Extract the JWT from an `Authorization: Bearer <jwt>` header, or null when
+ * absent/malformed. Shared by both runtimes' `resolveCaller` (Phase 4) so the
+ * Bearer parsing is single-sourced and case-insensitive on the scheme.
+ */
+declare function parseBearerToken(header: string | null | undefined): string | null;
+/** Only encoding understood today. `bypass` (D-A) is reserved for large blobs. */
+type WireEncoding = "base64";
+/** Shape of a `write` RpcBody after JSON parse, before decoding. */
+interface RpcWriteBody {
+  type: "write";
+  path?: string;
+  content?: string;
+  encoding?: string;
+  contentType?: string;
+  options?: {
+    ifMatch?: unknown;
+    meta?: {
+      deviceId?: unknown;
+      mtime?: unknown;
+      ifMatch?: unknown;
+    };
+  };
+}
+type WireValidation = {
+  ok: true;
+  bytes: Uint8Array;
+} | {
+  ok: false;
+  status: number;
+  error: string;
+  code?: string;
+};
+/**
+ * Decode a base64 string into bytes. Pure; no DOM/Buffer assumptions beyond
+ * `atob` (present in workerd + Node 18+ globalThis). Throws on malformed input.
+ */
+declare function decodeContentBase64(b64: string): Uint8Array;
+/** Encode bytes into a base64 string. Inverse of {@link decodeContentBase64}. */
+declare function encodeContentBase64(bytes: Uint8Array): string;
+/**
+ * Validate + decode a `write` body per the wire contract.
+ *
+ * Enforces:
+ *  - `content` present and `encoding === "base64"` (missing/other → 400).
+ *    The empty string IS present — it is the canonical base64 of a 0-byte
+ *    file, which must roundtrip (P6 crafted-sample finding; rejecting it
+ *    made empty files unsyncable on every client).
+ *  - `content` is valid base64 (bad → 400).
+ *
+ * Does NOT touch `options.ifMatch` placement: the field-position rule
+ * (ifMatch belongs at `options.ifMatch`, never `options.meta.ifMatch` for
+ * writes) is enforced by the handler reading ONLY `options.ifMatch`. A
+ * misplaced `meta.ifMatch` is simply ignored (treated as absent top-level
+ * ifMatch → LWW), per wire-contract.md §8.3.
+ */
+declare function validateAndDecodeWrite(body: RpcWriteBody): WireValidation;
+/**
+ * Read the top-level write ifMatch precondition. The misplaced
+ * `options.meta.ifMatch` is intentionally NOT consulted for writes — only
+ * `delete` carries ifMatch under `meta`.
+ */
+declare function readWriteIfMatch(options: RpcWriteBody["options"]): string | undefined;
+/**
+ * Per-type batch limits — the wire-contract §9 constant table. These are
+ * CONTRACT constants (clients mirror the same numbers when packing batches;
+ * no negotiation endpoint), injected into `createAfsRpcHandler` per runtime.
+ * Derived from the worst-case subrequest costs measured in P0
+ * (planning/afs-rpc-batch/p0-measurements.md).
+ */
+interface BatchLimits {
+  /** Max entries per batchWrite envelope. */
+  maxWriteEntries: number;
+  /** Max entries per batchDelete envelope. */
+  maxDeleteEntries: number;
+  /** Max entries per batchRead envelope. */
+  maxReadEntries: number;
+  /** Σ decoded bytes cap across a batchWrite envelope (400 BATCH_OVER_BUDGET). */
+  maxWriteBatchBytes: number;
+  /** Single-entry decoded cap (413 PAYLOAD_TOO_LARGE — same code as single op). */
+  maxEntryWriteBytes: number;
+  /**
+   * batchRead tail-truncation threshold, accumulated over ENCODED (base64
+   * response) bytes. NOT a hard response cap: the entry that crosses it is
+   * still returned in full (never read-then-discard); subsequent entries get
+   * 503 BATCH_TAIL_SKIPPED without being read.
+   */
+  readTailSkipThresholdBytes: number;
+  /**
+   * Pre-parse cap on the ENCODED request body (whole endpoint, not just
+   * batch): checked against Content-Length AND enforced by bounded read
+   * BEFORE `request.json()`, so an unauthenticated oversized body can't buy
+   * parse CPU/memory. Covers single-op 16MB decoded ≈ 21.4MB encoded + slack.
+   */
+  maxEncodedRequestBytes: number;
+}
+/** Cloudflare-tier limits (free-tier portability baseline; P0-confirmed). */
+declare const BATCH_LIMITS_CF: BatchLimits;
+/** Node-daemon limits (no subrequest budget; bounded by memory/UX only). */
+declare const BATCH_LIMITS_NODE: BatchLimits;
+/** batchWrite entry = single-op write body minus type/blocklet/sessionId. */
+interface BatchWriteWireEntry {
+  path: string;
+  content?: string;
+  encoding?: string;
+  contentType?: string;
+  options?: Record<string, unknown>;
+  /**
+   * Application metadata (createdAt / updatedAt / …) carried on the entry's
+   * top-level `meta` — distinct from `options.meta` (sync provenance). Forwarded
+   * to `AFSWriteEntryPayload.meta` so metadata-aware providers index it.
+   */
+  meta?: Record<string, unknown>;
+}
+/** batchDelete entry — ifMatch/provenance ride options.meta, like single op. */
+interface BatchDeleteWireEntry {
+  path: string;
+  options?: Record<string, unknown>;
+}
+/** batchRead entry — `optional` mirrors the single-op wire field. */
+interface BatchReadWireEntry {
+  path: string;
+  optional?: boolean;
+  options?: Record<string, unknown>;
+}
+type BatchWireEntry = BatchWriteWireEntry & BatchDeleteWireEntry & BatchReadWireEntry;
+/** Per-entry decode outcome for batchWrite (aligned by index with entries). */
+type BatchWriteDecode = {
+  ok: true;
+  bytes: Uint8Array;
+} | {
+  ok: false;
+  status: number;
+  error: string;
+  code?: string;
+};
+type BatchValidation = {
+  ok: true;
+  entries: BatchWireEntry[];
+  writeDecodes?: BatchWriteDecode[];
+} | {
+  ok: false;
+  status: number;
+  error: string;
+  code?: string;
+};
+/**
+ * Envelope-level validation for the three batch ops (wire-contract §9).
+ *
+ * Envelope rejections (zero entries executed): entries shape, per-type
+ * maxEntries / Σ-decoded-bytes budget (400 BATCH_OVER_BUDGET), forbidden
+ * per-entry `blocklet`/`sessionId` fields, invalid/traversal paths, and a
+ * single entry over the per-entry decoded cap (413 PAYLOAD_TOO_LARGE — the
+ * single-op code).
+ *
+ * Content-shape problems (missing/empty content, unknown encoding, bad
+ * base64) are NOT envelope rejections: single-op parity says each such entry
+ * fails alone, so they come back as per-entry decode outcomes in
+ * `writeDecodes` for the dispatch loop to surface as `results[i]`.
+ */
+declare function validateBatchBody(body: {
+  type?: string;
+  entries?: unknown;
+}, limits: BatchLimits, sanitizePath: (path: string) => string | null): BatchValidation;
+//#endregion
+export { BATCH_LIMITS_CF, BATCH_LIMITS_NODE, BatchDeleteWireEntry, BatchLimits, BatchReadWireEntry, BatchWriteWireEntry, RpcWriteBody, WIRE_ERROR_CODES, WireEncoding, WireValidation, decodeContentBase64, encodeContentBase64, parseBearerToken, readWriteIfMatch, validateAndDecodeWrite, validateBatchBody };
+//# sourceMappingURL=afs-rpc-wire.d.cts.map

package/dist/http/afs-rpc-wire.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-rpc-wire.d.cts","names":[],"sources":["../../src/http/afs-rpc-wire.ts"],"mappings":";;AAcA;;;;;;;;;;;AAsBA;AAAA,cAtBa,gBAAA;EAAA;iDAsBqD;EAAA,+CAQ1C;EAAA;EAAA;;AAGxB;;;;;EAHwB;;;;;;;iBARR,gBAAA,CAAiB,MAAA;;KAQrB,YAAA;;UAGK,YAAA;EACf,IAAA;EACA,IAAA;EACA,OAAA;EACA,QAAA;EACA,WAAA;EACA,OAAA;IACE,OAAA;IACA,IAAA;MAAS,QAAA;MAAoB,KAAA;MAAiB,OAAA;IAAA;EAAA;AAAA;AAAA,KAItC,cAAA;EACN,EAAA;EAAU,KAAA,EAAO,UAAA;AAAA;EACjB,EAAA;EAAW,MAAA;EAAgB,KAAA;EAAe,IAAA;AAAA;AA0ChD;;;;AAAA,iBApCgB,mBAAA,CAAoB,GAAA,WAAc,UAAA;;iBAUlC,mBAAA,CAAoB,KAAA,EAAO,UAAA;;;AAgD3C;;;;;AAcA;;;;;;;;;iBApCgB,sBAAA,CAAuB,IAAA,EAAM,YAAA,GAAe,cAAA;;;;AAkE5D;;iBA5CgB,gBAAA,CAAiB,OAAA,EAAS,YAAA;;;AAuD1C;;;;;UAzCiB,WAAA;EAoDmB;EAlDlC,eAAA;EA6Da;EA3Db,gBAAA;EAkDA;EAhDA,cAAA;EAkDA;EAhDA,kBAAA;EAiDU;EA/CV,kBAAA;EAqDO;;;AAIT;;;EAlDE,0BAAA;EAmDA;;;;;AAKF;EAjDE,sBAAA;AAAA;;cAMW,eAAA,EAAiB,WAAA;;cAWjB,iBAAA,EAAmB,WAAA;;UAWf,mBAAA;EACf,IAAA;EACA,OAAA;EACA,QAAA;EACA,WAAA;EACA,OAAA,GAAU,MAAA;EAsBuC;;;;;EAhBjD,IAAA,GAAO,MAAA;AAAA;;UAIQ,oBAAA;EACf,IAAA;EACA,OAAA,GAAU,MAAA;AAAA;;UAIK,kBAAA;EACf,IAAA;EACA,QAAA;EACA,OAAA,GAAU,MAAA;AAAA;AAAA,KAGA,cAAA,GAAiB,mBAAA,GAAsB,oBAAA,GAAuB,kBAAA;;KAG9D,gBAAA;EACN,EAAA;EAAU,KAAA,EAAO,UAAA;AAAA;EACjB,EAAA;EAAW,MAAA;EAAgB,KAAA;EAAe,IAAA;AAAA;AAAA,KAEpC,eAAA;EACN,EAAA;EAAU,OAAA,EAAS,cAAA;EAAkB,YAAA,GAAe,gBAAA;AAAA;EACpD,EAAA;EAAW,MAAA;EAAgB,KAAA;EAAe,IAAA;AAAA;;;;;;;;;;;;;;;iBAwBhC,iBAAA,CACd,IAAA;EAAQ,IAAA;EAAe,OAAA;AAAA,GACvB,MAAA,EAAQ,WAAA,EACR,YAAA,GAAe,IAAA,6BACd,eAAA"}

package/dist/http/afs-rpc-wire.d.mts

@@ -0,0 +1,195 @@
+//#region src/http/afs-rpc-wire.d.ts
+/**
+ * afs-rpc wire contract — encoding + validation helpers.
+ *
+ * Single source of truth for the binary content encoding (base64) and the
+ * write/delete body validation rules pinned in
+ * `planning/did-integration/mobile-didspace-transport/wire-contract.md`.
+ *
+ * Both runtime handlers (Node `daemon/server.ts`, Cloudflare `index.ts`) share
+ * `createAfsRpcHandler`; this module is where the write/delete dispatch (Phase
+ * 4) decodes `content` and enforces field-position rules. Defined in Phase 0
+ * so the contract is frozen before any implementation.
+ */
+/** Stable error codes surfaced on the wire (see wire-contract.md §7/§9). */
+declare const WIRE_ERROR_CODES: {
+  readonly conflict: "AFS_CONFLICT";
+  readonly payloadTooLarge: "PAYLOAD_TOO_LARGE"; /** Batch envelope rejected up-front (entry count / Σ bytes) — zero entries executed. */
+  readonly batchOverBudget: "BATCH_OVER_BUDGET"; /** batchRead tail entry skipped (encoded-byte threshold reached) — retry next batch. */
+  readonly batchTailSkipped: "BATCH_TAIL_SKIPPED";
+  /**
+   * Declared-size upload rejected BEFORE any bytes move (ingest-prepare early
+   * reject — DID-Space upload-limits, design §8 / D7). Distinct from
+   * `PAYLOAD_TOO_LARGE` ("actual decoded bytes over the cap"): `FILE_TOO_LARGE`
+   * fires on the client-declared size at the planning stage, is per-entry, and
+   * is never auto-retried by the sync engine.
+   */
+  readonly fileTooLarge: "FILE_TOO_LARGE";
+};
+/**
+ * Extract the JWT from an `Authorization: Bearer <jwt>` header, or null when
+ * absent/malformed. Shared by both runtimes' `resolveCaller` (Phase 4) so the
+ * Bearer parsing is single-sourced and case-insensitive on the scheme.
+ */
+declare function parseBearerToken(header: string | null | undefined): string | null;
+/** Only encoding understood today. `bypass` (D-A) is reserved for large blobs. */
+type WireEncoding = "base64";
+/** Shape of a `write` RpcBody after JSON parse, before decoding. */
+interface RpcWriteBody {
+  type: "write";
+  path?: string;
+  content?: string;
+  encoding?: string;
+  contentType?: string;
+  options?: {
+    ifMatch?: unknown;
+    meta?: {
+      deviceId?: unknown;
+      mtime?: unknown;
+      ifMatch?: unknown;
+    };
+  };
+}
+type WireValidation = {
+  ok: true;
+  bytes: Uint8Array;
+} | {
+  ok: false;
+  status: number;
+  error: string;
+  code?: string;
+};
+/**
+ * Decode a base64 string into bytes. Pure; no DOM/Buffer assumptions beyond
+ * `atob` (present in workerd + Node 18+ globalThis). Throws on malformed input.
+ */
+declare function decodeContentBase64(b64: string): Uint8Array;
+/** Encode bytes into a base64 string. Inverse of {@link decodeContentBase64}. */
+declare function encodeContentBase64(bytes: Uint8Array): string;
+/**
+ * Validate + decode a `write` body per the wire contract.
+ *
+ * Enforces:
+ *  - `content` present and `encoding === "base64"` (missing/other → 400).
+ *    The empty string IS present — it is the canonical base64 of a 0-byte
+ *    file, which must roundtrip (P6 crafted-sample finding; rejecting it
+ *    made empty files unsyncable on every client).
+ *  - `content` is valid base64 (bad → 400).
+ *
+ * Does NOT touch `options.ifMatch` placement: the field-position rule
+ * (ifMatch belongs at `options.ifMatch`, never `options.meta.ifMatch` for
+ * writes) is enforced by the handler reading ONLY `options.ifMatch`. A
+ * misplaced `meta.ifMatch` is simply ignored (treated as absent top-level
+ * ifMatch → LWW), per wire-contract.md §8.3.
+ */
+declare function validateAndDecodeWrite(body: RpcWriteBody): WireValidation;
+/**
+ * Read the top-level write ifMatch precondition. The misplaced
+ * `options.meta.ifMatch` is intentionally NOT consulted for writes — only
+ * `delete` carries ifMatch under `meta`.
+ */
+declare function readWriteIfMatch(options: RpcWriteBody["options"]): string | undefined;
+/**
+ * Per-type batch limits — the wire-contract §9 constant table. These are
+ * CONTRACT constants (clients mirror the same numbers when packing batches;
+ * no negotiation endpoint), injected into `createAfsRpcHandler` per runtime.
+ * Derived from the worst-case subrequest costs measured in P0
+ * (planning/afs-rpc-batch/p0-measurements.md).
+ */
+interface BatchLimits {
+  /** Max entries per batchWrite envelope. */
+  maxWriteEntries: number;
+  /** Max entries per batchDelete envelope. */
+  maxDeleteEntries: number;
+  /** Max entries per batchRead envelope. */
+  maxReadEntries: number;
+  /** Σ decoded bytes cap across a batchWrite envelope (400 BATCH_OVER_BUDGET). */
+  maxWriteBatchBytes: number;
+  /** Single-entry decoded cap (413 PAYLOAD_TOO_LARGE — same code as single op). */
+  maxEntryWriteBytes: number;
+  /**
+   * batchRead tail-truncation threshold, accumulated over ENCODED (base64
+   * response) bytes. NOT a hard response cap: the entry that crosses it is
+   * still returned in full (never read-then-discard); subsequent entries get
+   * 503 BATCH_TAIL_SKIPPED without being read.
+   */
+  readTailSkipThresholdBytes: number;
+  /**
+   * Pre-parse cap on the ENCODED request body (whole endpoint, not just
+   * batch): checked against Content-Length AND enforced by bounded read
+   * BEFORE `request.json()`, so an unauthenticated oversized body can't buy
+   * parse CPU/memory. Covers single-op 16MB decoded ≈ 21.4MB encoded + slack.
+   */
+  maxEncodedRequestBytes: number;
+}
+/** Cloudflare-tier limits (free-tier portability baseline; P0-confirmed). */
+declare const BATCH_LIMITS_CF: BatchLimits;
+/** Node-daemon limits (no subrequest budget; bounded by memory/UX only). */
+declare const BATCH_LIMITS_NODE: BatchLimits;
+/** batchWrite entry = single-op write body minus type/blocklet/sessionId. */
+interface BatchWriteWireEntry {
+  path: string;
+  content?: string;
+  encoding?: string;
+  contentType?: string;
+  options?: Record<string, unknown>;
+  /**
+   * Application metadata (createdAt / updatedAt / …) carried on the entry's
+   * top-level `meta` — distinct from `options.meta` (sync provenance). Forwarded
+   * to `AFSWriteEntryPayload.meta` so metadata-aware providers index it.
+   */
+  meta?: Record<string, unknown>;
+}
+/** batchDelete entry — ifMatch/provenance ride options.meta, like single op. */
+interface BatchDeleteWireEntry {
+  path: string;
+  options?: Record<string, unknown>;
+}
+/** batchRead entry — `optional` mirrors the single-op wire field. */
+interface BatchReadWireEntry {
+  path: string;
+  optional?: boolean;
+  options?: Record<string, unknown>;
+}
+type BatchWireEntry = BatchWriteWireEntry & BatchDeleteWireEntry & BatchReadWireEntry;
+/** Per-entry decode outcome for batchWrite (aligned by index with entries). */
+type BatchWriteDecode = {
+  ok: true;
+  bytes: Uint8Array;
+} | {
+  ok: false;
+  status: number;
+  error: string;
+  code?: string;
+};
+type BatchValidation = {
+  ok: true;
+  entries: BatchWireEntry[];
+  writeDecodes?: BatchWriteDecode[];
+} | {
+  ok: false;
+  status: number;
+  error: string;
+  code?: string;
+};
+/**
+ * Envelope-level validation for the three batch ops (wire-contract §9).
+ *
+ * Envelope rejections (zero entries executed): entries shape, per-type
+ * maxEntries / Σ-decoded-bytes budget (400 BATCH_OVER_BUDGET), forbidden
+ * per-entry `blocklet`/`sessionId` fields, invalid/traversal paths, and a
+ * single entry over the per-entry decoded cap (413 PAYLOAD_TOO_LARGE — the
+ * single-op code).
+ *
+ * Content-shape problems (missing/empty content, unknown encoding, bad
+ * base64) are NOT envelope rejections: single-op parity says each such entry
+ * fails alone, so they come back as per-entry decode outcomes in
+ * `writeDecodes` for the dispatch loop to surface as `results[i]`.
+ */
+declare function validateBatchBody(body: {
+  type?: string;
+  entries?: unknown;
+}, limits: BatchLimits, sanitizePath: (path: string) => string | null): BatchValidation;
+//#endregion
+export { BATCH_LIMITS_CF, BATCH_LIMITS_NODE, BatchDeleteWireEntry, BatchLimits, BatchReadWireEntry, BatchWriteWireEntry, RpcWriteBody, WIRE_ERROR_CODES, WireEncoding, WireValidation, decodeContentBase64, encodeContentBase64, parseBearerToken, readWriteIfMatch, validateAndDecodeWrite, validateBatchBody };
+//# sourceMappingURL=afs-rpc-wire.d.mts.map

package/dist/http/afs-rpc-wire.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-rpc-wire.d.mts","names":[],"sources":["../../src/http/afs-rpc-wire.ts"],"mappings":";;AAcA;;;;;;;;;;;AAsBA;AAAA,cAtBa,gBAAA;EAAA;iDAsBqD;EAAA,+CAQ1C;EAAA;EAAA;;AAGxB;;;;;EAHwB;;;;;;;iBARR,gBAAA,CAAiB,MAAA;;KAQrB,YAAA;;UAGK,YAAA;EACf,IAAA;EACA,IAAA;EACA,OAAA;EACA,QAAA;EACA,WAAA;EACA,OAAA;IACE,OAAA;IACA,IAAA;MAAS,QAAA;MAAoB,KAAA;MAAiB,OAAA;IAAA;EAAA;AAAA;AAAA,KAItC,cAAA;EACN,EAAA;EAAU,KAAA,EAAO,UAAA;AAAA;EACjB,EAAA;EAAW,MAAA;EAAgB,KAAA;EAAe,IAAA;AAAA;AA0ChD;;;;AAAA,iBApCgB,mBAAA,CAAoB,GAAA,WAAc,UAAA;;iBAUlC,mBAAA,CAAoB,KAAA,EAAO,UAAA;;;AAgD3C;;;;;AAcA;;;;;;;;;iBApCgB,sBAAA,CAAuB,IAAA,EAAM,YAAA,GAAe,cAAA;;;;AAkE5D;;iBA5CgB,gBAAA,CAAiB,OAAA,EAAS,YAAA;;;AAuD1C;;;;;UAzCiB,WAAA;EAoDmB;EAlDlC,eAAA;EA6Da;EA3Db,gBAAA;EAkDA;EAhDA,cAAA;EAkDA;EAhDA,kBAAA;EAiDU;EA/CV,kBAAA;EAqDO;;;AAIT;;;EAlDE,0BAAA;EAmDA;;;;;AAKF;EAjDE,sBAAA;AAAA;;cAMW,eAAA,EAAiB,WAAA;;cAWjB,iBAAA,EAAmB,WAAA;;UAWf,mBAAA;EACf,IAAA;EACA,OAAA;EACA,QAAA;EACA,WAAA;EACA,OAAA,GAAU,MAAA;EAsBuC;;;;;EAhBjD,IAAA,GAAO,MAAA;AAAA;;UAIQ,oBAAA;EACf,IAAA;EACA,OAAA,GAAU,MAAA;AAAA;;UAIK,kBAAA;EACf,IAAA;EACA,QAAA;EACA,OAAA,GAAU,MAAA;AAAA;AAAA,KAGA,cAAA,GAAiB,mBAAA,GAAsB,oBAAA,GAAuB,kBAAA;;KAG9D,gBAAA;EACN,EAAA;EAAU,KAAA,EAAO,UAAA;AAAA;EACjB,EAAA;EAAW,MAAA;EAAgB,KAAA;EAAe,IAAA;AAAA;AAAA,KAEpC,eAAA;EACN,EAAA;EAAU,OAAA,EAAS,cAAA;EAAkB,YAAA,GAAe,gBAAA;AAAA;EACpD,EAAA;EAAW,MAAA;EAAgB,KAAA;EAAe,IAAA;AAAA;;;;;;;;;;;;;;;iBAwBhC,iBAAA,CACd,IAAA;EAAQ,IAAA;EAAe,OAAA;AAAA,GACvB,MAAA,EAAQ,WAAA,EACR,YAAA,GAAe,IAAA,6BACd,eAAA"}