@mdbase-dev/connect-protocol 0.1.0-beta.21 → 0.1.0-beta.23

package/dist/files.js

@@ -0,0 +1,417 @@
+export const FILE_PROTOCOL_VERSION = 1;
+export const FILE_TRANSFER_PROTOCOL_VERSION = 1;
+export const DEFAULT_FILE_CHUNK_BYTES = 1024 * 1024;
+export const MAX_FILE_CHUNK_BYTES = 4 * 1024 * 1024;
+export const MAX_FILE_FRAME_HEADER_BYTES = 16 * 1024;
+export const FILE_FRAME_PREFIX_BYTES = 16;
+export const FILE_FRAME_MAGIC = "MDBF";
+export const MAX_FILE_FRAME_BYTES = FILE_FRAME_PREFIX_BYTES
+    + MAX_FILE_FRAME_HEADER_BYTES
+    + MAX_FILE_CHUNK_BYTES
+    + 16;
+export const RELAY_FILE_PROTOCOL_VERSION = 1;
+export const RELAY_FILE_PREFIX_BYTES = 16;
+export const MAX_RELAY_FILE_HEADER_BYTES = 1024;
+export const MAX_RELAY_FILE_PAYLOAD_BYTES = MAX_FILE_FRAME_BYTES;
+export const RELAY_FILE_MAGIC = "MDBR";
+const FILE_FRAME_MAGIC_BYTES = new Uint8Array([0x4d, 0x44, 0x42, 0x46]);
+const FILE_FRAME_VERSION = 1;
+const FILE_FRAME_FLAGS = 0;
+const RELAY_FILE_MAGIC_BYTES = new Uint8Array([0x4d, 0x44, 0x42, 0x52]);
+const RELAY_FILE_FRAME_VERSION = 1;
+const RELAY_FILE_FRAME_FLAGS = 0;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export class FileFrameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "FileFrameError";
+    }
+}
+export class RelayFileFrameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RelayFileFrameError";
+    }
+}
+function frameKindCode(kind) {
+    return kind === "upload_chunk" ? 1 : 2;
+}
+function frameKindFromCode(code) {
+    if (code === 1)
+        return "upload_chunk";
+    if (code === 2)
+        return "download_chunk";
+    throw new FileFrameError("invalid_kind", `Unknown file frame kind ${code}`);
+}
+function expectObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new FileFrameError("invalid_header", "File frame header must be a JSON object");
+    }
+    return value;
+}
+function expectString(object, name) {
+    const value = object[name];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new FileFrameError("invalid_header", `File frame header ${name} must be a non-empty string`);
+    }
+    return value;
+}
+function expectUuid(object, name) {
+    const value = expectString(object, name);
+    if (!UUID_PATTERN.test(value)) {
+        throw new FileFrameError("invalid_header", `File frame header ${name} must be a UUID`);
+    }
+    return value;
+}
+function expectInteger(object, name, maximum = Number.MAX_SAFE_INTEGER) {
+    const value = object[name];
+    if (!Number.isSafeInteger(value) || value < 0 || value > maximum) {
+        throw new FileFrameError("invalid_header", `File frame header ${name} is outside its allowed range`);
+    }
+    return value;
+}
+function canonicalHeader(header) {
+    if (header.protocol_version !== FILE_TRANSFER_PROTOCOL_VERSION) {
+        throw new FileFrameError("unsupported_version", `Unsupported file transfer protocol ${header.protocol_version}`);
+    }
+    if (header.protection !== "grant_aead_v1" && header.protection !== "transport_tls") {
+        throw new FileFrameError("invalid_header", "Unknown file transfer protection");
+    }
+    if (header.direction !== "upload" && header.direction !== "download") {
+        throw new FileFrameError("invalid_header", "Unknown file transfer direction");
+    }
+    for (const [name, value] of [
+        ["grant_id", header.grant_id],
+        ["authority_id", header.authority_id],
+        ["collection_id", header.collection_id],
+        ["transfer_id", header.transfer_id]
+    ]) {
+        if (!UUID_PATTERN.test(value)) {
+            throw new FileFrameError("invalid_header", `File frame header ${name} must be a UUID`);
+        }
+    }
+    for (const [name, value, maximum] of [
+        ["chunk_size", header.chunk_size, MAX_FILE_CHUNK_BYTES],
+        ["chunk_index", header.chunk_index, Number.MAX_SAFE_INTEGER],
+        ["offset", header.offset, Number.MAX_SAFE_INTEGER],
+        ["plaintext_length", header.plaintext_length, MAX_FILE_CHUNK_BYTES],
+        ["total_size", header.total_size, Number.MAX_SAFE_INTEGER]
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 0 || value > maximum) {
+            throw new FileFrameError("invalid_header", `File frame header ${name} is outside its allowed range`);
+        }
+    }
+    if (header.chunk_size < 64 * 1024) {
+        throw new FileFrameError("invalid_header", "File frame chunk_size is below the protocol minimum");
+    }
+    if (!Number.isSafeInteger(header.scope_epoch) || header.scope_epoch < 1) {
+        throw new FileFrameError("invalid_header", "File frame header scope_epoch must be a positive integer");
+    }
+    if (header.protection === "grant_aead_v1" && !header.key_id) {
+        throw new FileFrameError("invalid_header", "AEAD-protected file frames require key_id");
+    }
+    return {
+        protocol_version: FILE_TRANSFER_PROTOCOL_VERSION,
+        protection: header.protection,
+        grant_id: header.grant_id,
+        authority_id: header.authority_id,
+        collection_id: header.collection_id,
+        transfer_id: header.transfer_id,
+        direction: header.direction,
+        chunk_size: header.chunk_size,
+        chunk_index: header.chunk_index,
+        offset: header.offset,
+        plaintext_length: header.plaintext_length,
+        total_size: header.total_size,
+        scope_epoch: header.scope_epoch,
+        ...(header.key_id === undefined ? {} : { key_id: header.key_id })
+    };
+}
+function parseHeader(bytes) {
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new FileFrameError("invalid_header", "File frame header is not valid UTF-8");
+    }
+    let object;
+    try {
+        object = expectObject(JSON.parse(source));
+    }
+    catch (error) {
+        if (error instanceof FileFrameError)
+            throw error;
+        throw new FileFrameError("invalid_header", "File frame header is not valid JSON");
+    }
+    const allowed = new Set([
+        "protocol_version", "protection", "grant_id", "authority_id", "collection_id",
+        "transfer_id", "direction", "chunk_size", "chunk_index", "offset", "plaintext_length",
+        "total_size", "scope_epoch", "key_id"
+    ]);
+    if (Object.keys(object).some((key) => !allowed.has(key))) {
+        throw new FileFrameError("invalid_header", "File frame header contains an unknown field");
+    }
+    const protocolVersion = expectInteger(object, "protocol_version");
+    if (protocolVersion !== FILE_TRANSFER_PROTOCOL_VERSION) {
+        throw new FileFrameError("unsupported_version", `Unsupported file transfer protocol ${protocolVersion}`);
+    }
+    const protection = expectString(object, "protection");
+    const direction = expectString(object, "direction");
+    const keyId = object.key_id === undefined ? undefined : expectString(object, "key_id");
+    const header = canonicalHeader({
+        protocol_version: FILE_TRANSFER_PROTOCOL_VERSION,
+        protection: protection,
+        grant_id: expectUuid(object, "grant_id"),
+        authority_id: expectUuid(object, "authority_id"),
+        collection_id: expectUuid(object, "collection_id"),
+        transfer_id: expectUuid(object, "transfer_id"),
+        direction: direction,
+        chunk_size: expectInteger(object, "chunk_size", MAX_FILE_CHUNK_BYTES),
+        chunk_index: expectInteger(object, "chunk_index"),
+        offset: expectInteger(object, "offset"),
+        plaintext_length: expectInteger(object, "plaintext_length", MAX_FILE_CHUNK_BYTES),
+        total_size: expectInteger(object, "total_size"),
+        scope_epoch: expectInteger(object, "scope_epoch"),
+        ...(keyId === undefined ? {} : { key_id: keyId })
+    });
+    if (JSON.stringify(header) !== source) {
+        throw new FileFrameError("invalid_header", "File frame header must use the canonical field order without duplicate fields or whitespace");
+    }
+    return header;
+}
+function validateFrameSemantics(kind, header, payloadLength) {
+    const expectedDirection = kind === "upload_chunk" ? "upload" : "download";
+    if (header.direction !== expectedDirection) {
+        throw new FileFrameError("invalid_header", `Frame kind ${kind} requires direction ${expectedDirection}`);
+    }
+    const expectedOffset = header.chunk_index * header.chunk_size;
+    if (!Number.isSafeInteger(expectedOffset) || header.offset !== expectedOffset) {
+        throw new FileFrameError("invalid_header", "Chunk offset does not match its index and protocol chunk size");
+    }
+    if (header.offset + header.plaintext_length > header.total_size) {
+        throw new FileFrameError("invalid_header", "Chunk extends past the declared transfer size");
+    }
+    const expectedPayloadLength = header.protection === "grant_aead_v1"
+        ? header.plaintext_length + 16
+        : header.plaintext_length;
+    if (payloadLength !== expectedPayloadLength) {
+        throw new FileFrameError("invalid_length", "Payload length does not match the protected plaintext length");
+    }
+}
+function expectedFileFramePayloadLength(header) {
+    return header.plaintext_length + (header.protection === "grant_aead_v1" ? 16 : 0);
+}
+/** Prefix and canonical header authenticated by the file chunk AEAD profile. */
+export function fileFrameAuthenticatedData(kind, input) {
+    const header = canonicalHeader(input);
+    const payloadLength = expectedFileFramePayloadLength(header);
+    validateFrameSemantics(kind, header, payloadLength);
+    const headerBytes = new TextEncoder().encode(JSON.stringify(header));
+    if (headerBytes.byteLength > MAX_FILE_FRAME_HEADER_BYTES) {
+        throw new FileFrameError("limit_exceeded", "File frame header exceeds the protocol limit");
+    }
+    const output = new Uint8Array(FILE_FRAME_PREFIX_BYTES + headerBytes.byteLength);
+    output.set(FILE_FRAME_MAGIC_BYTES, 0);
+    const view = new DataView(output.buffer, output.byteOffset, output.byteLength);
+    view.setUint8(4, FILE_FRAME_VERSION);
+    view.setUint8(5, frameKindCode(kind));
+    view.setUint16(6, FILE_FRAME_FLAGS, false);
+    view.setUint32(8, headerBytes.byteLength, false);
+    view.setUint32(12, payloadLength, false);
+    output.set(headerBytes, FILE_FRAME_PREFIX_BYTES);
+    return output;
+}
+export function encodeFileFrame(frame) {
+    const header = canonicalHeader(frame.header);
+    validateFrameSemantics(frame.kind, header, frame.payload.byteLength);
+    if (frame.payload.byteLength > MAX_FILE_CHUNK_BYTES + 16) {
+        throw new FileFrameError("limit_exceeded", "File frame payload exceeds the protocol limit");
+    }
+    const authenticatedData = fileFrameAuthenticatedData(frame.kind, header);
+    const output = new Uint8Array(authenticatedData.byteLength + frame.payload.byteLength);
+    output.set(authenticatedData, 0);
+    output.set(frame.payload, authenticatedData.byteLength);
+    return output;
+}
+export function decodeFileFrame(bytes, limits = {}) {
+    if (bytes.byteLength < FILE_FRAME_PREFIX_BYTES) {
+        throw new FileFrameError("invalid_length", "File frame is shorter than its fixed prefix");
+    }
+    if (!FILE_FRAME_MAGIC_BYTES.every((byte, index) => bytes[index] === byte)) {
+        throw new FileFrameError("invalid_magic", "File frame magic is not MDBF");
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const version = view.getUint8(4);
+    if (version !== FILE_FRAME_VERSION) {
+        throw new FileFrameError("unsupported_version", `Unsupported file frame version ${version}`);
+    }
+    const kind = frameKindFromCode(view.getUint8(5));
+    if (view.getUint16(6, false) !== FILE_FRAME_FLAGS) {
+        throw new FileFrameError("unsupported_flags", "File frame uses unsupported flags");
+    }
+    const headerLength = view.getUint32(8, false);
+    const payloadLength = view.getUint32(12, false);
+    const maxHeaderBytes = limits.maxHeaderBytes ?? MAX_FILE_FRAME_HEADER_BYTES;
+    const maxPayloadBytes = limits.maxPayloadBytes ?? MAX_FILE_CHUNK_BYTES + 16;
+    if (headerLength === 0) {
+        throw new FileFrameError("invalid_length", "File frame header must not be empty");
+    }
+    if (headerLength > maxHeaderBytes || payloadLength > maxPayloadBytes) {
+        throw new FileFrameError("limit_exceeded", "File frame exceeds the configured decode limits");
+    }
+    const expectedLength = FILE_FRAME_PREFIX_BYTES + headerLength + payloadLength;
+    if (!Number.isSafeInteger(expectedLength) || expectedLength !== bytes.byteLength) {
+        throw new FileFrameError("invalid_length", "File frame lengths do not match the supplied bytes");
+    }
+    const headerEnd = FILE_FRAME_PREFIX_BYTES + headerLength;
+    const header = parseHeader(bytes.subarray(FILE_FRAME_PREFIX_BYTES, headerEnd));
+    validateFrameSemantics(kind, header, payloadLength);
+    return { kind, header, payload: bytes.slice(headerEnd) };
+}
+export function encodeRelayFileFrame(frame) {
+    const header = canonicalRelayHeader(frame.header);
+    validateRelayFrame(frame.kind, header, frame.payload.byteLength);
+    const headerBytes = new TextEncoder().encode(JSON.stringify(header));
+    if (headerBytes.byteLength > MAX_RELAY_FILE_HEADER_BYTES
+        || frame.payload.byteLength > MAX_RELAY_FILE_PAYLOAD_BYTES) {
+        throw new RelayFileFrameError("limit_exceeded", "Relay file frame exceeds protocol limits");
+    }
+    const output = new Uint8Array(RELAY_FILE_PREFIX_BYTES + headerBytes.byteLength + frame.payload.byteLength);
+    output.set(RELAY_FILE_MAGIC_BYTES, 0);
+    const view = new DataView(output.buffer, output.byteOffset, output.byteLength);
+    view.setUint8(4, RELAY_FILE_FRAME_VERSION);
+    view.setUint8(5, relayFileKindCode(frame.kind));
+    view.setUint16(6, RELAY_FILE_FRAME_FLAGS, false);
+    view.setUint32(8, headerBytes.byteLength, false);
+    view.setUint32(12, frame.payload.byteLength, false);
+    output.set(headerBytes, RELAY_FILE_PREFIX_BYTES);
+    output.set(frame.payload, RELAY_FILE_PREFIX_BYTES + headerBytes.byteLength);
+    return output;
+}
+export function decodeRelayFileFrame(bytes) {
+    if (bytes.byteLength < RELAY_FILE_PREFIX_BYTES) {
+        throw new RelayFileFrameError("invalid_length", "Relay file frame is shorter than its prefix");
+    }
+    if (!RELAY_FILE_MAGIC_BYTES.every((byte, index) => bytes[index] === byte)) {
+        throw new RelayFileFrameError("invalid_magic", "Relay file frame magic is not MDBR");
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint8(4) !== RELAY_FILE_FRAME_VERSION) {
+        throw new RelayFileFrameError("unsupported_version", "Unsupported relay file frame version");
+    }
+    const kind = relayFileKindFromCode(view.getUint8(5));
+    if (view.getUint16(6, false) !== RELAY_FILE_FRAME_FLAGS) {
+        throw new RelayFileFrameError("unsupported_flags", "Relay file frame uses unsupported flags");
+    }
+    const headerLength = view.getUint32(8, false);
+    const payloadLength = view.getUint32(12, false);
+    if (headerLength === 0) {
+        throw new RelayFileFrameError("invalid_length", "Relay file frame header must not be empty");
+    }
+    if (headerLength > MAX_RELAY_FILE_HEADER_BYTES
+        || payloadLength > MAX_RELAY_FILE_PAYLOAD_BYTES) {
+        throw new RelayFileFrameError("limit_exceeded", "Relay file frame exceeds protocol limits");
+    }
+    const expectedLength = RELAY_FILE_PREFIX_BYTES + headerLength + payloadLength;
+    if (!Number.isSafeInteger(expectedLength) || expectedLength !== bytes.byteLength) {
+        throw new RelayFileFrameError("invalid_length", "Relay file frame lengths do not match its bytes");
+    }
+    const headerEnd = RELAY_FILE_PREFIX_BYTES + headerLength;
+    const headerBytes = bytes.subarray(RELAY_FILE_PREFIX_BYTES, headerEnd);
+    let source;
+    let parsed;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true }).decode(headerBytes);
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new RelayFileFrameError("invalid_header", "Relay file frame header is not valid JSON");
+    }
+    const header = parseRelayHeader(parsed);
+    if (JSON.stringify(header) !== source) {
+        throw new RelayFileFrameError("invalid_header", "Relay file frame header is not canonical JSON");
+    }
+    validateRelayFrame(kind, header, payloadLength);
+    return { kind, header, payload: bytes.slice(headerEnd) };
+}
+function canonicalRelayHeader(header) {
+    if (header.protocol_version !== RELAY_FILE_PROTOCOL_VERSION) {
+        throw new RelayFileFrameError("unsupported_version", "Unsupported relay file protocol");
+    }
+    if (!relayFileKinds.includes(header.type)) {
+        throw new RelayFileFrameError("invalid_kind", "Unknown relay file message type");
+    }
+    for (const [name, value] of [
+        ["request_id", header.request_id],
+        ["grant_id", header.grant_id],
+        ["transfer_id", header.transfer_id]
+    ]) {
+        if (!UUID_PATTERN.test(value)) {
+            throw new RelayFileFrameError("invalid_header", `Relay file header ${name} must be a UUID`);
+        }
+    }
+    if (!Number.isSafeInteger(header.chunk_index) || header.chunk_index < 0) {
+        throw new RelayFileFrameError("invalid_header", "Relay file chunk index is invalid");
+    }
+    return {
+        protocol_version: RELAY_FILE_PROTOCOL_VERSION,
+        type: header.type,
+        request_id: header.request_id,
+        grant_id: header.grant_id,
+        transfer_id: header.transfer_id,
+        chunk_index: header.chunk_index
+    };
+}
+function parseRelayHeader(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new RelayFileFrameError("invalid_header", "Relay file header must be an object");
+    }
+    const object = value;
+    const allowed = new Set([
+        "protocol_version", "type", "request_id", "grant_id", "transfer_id", "chunk_index"
+    ]);
+    if (Object.keys(object).some((key) => !allowed.has(key))) {
+        throw new RelayFileFrameError("invalid_header", "Relay file header contains an unknown field");
+    }
+    return canonicalRelayHeader({
+        protocol_version: object.protocol_version,
+        type: object.type,
+        request_id: object.request_id,
+        grant_id: object.grant_id,
+        transfer_id: object.transfer_id,
+        chunk_index: object.chunk_index
+    });
+}
+const relayFileKinds = [
+    "upload_chunk",
+    "upload_acknowledged",
+    "download_request",
+    "download_chunk",
+    "rejected"
+];
+function relayFileKindCode(kind) {
+    const index = relayFileKinds.indexOf(kind);
+    if (index < 0)
+        throw new RelayFileFrameError("invalid_kind", "Unknown relay file frame kind");
+    return index + 1;
+}
+function relayFileKindFromCode(code) {
+    const kind = relayFileKinds[code - 1];
+    if (!kind)
+        throw new RelayFileFrameError("invalid_kind", `Unknown relay file frame kind ${code}`);
+    return kind;
+}
+function validateRelayFrame(kind, header, payloadLength) {
+    if (kind !== header.type) {
+        throw new RelayFileFrameError("invalid_header", "Relay file kind does not match its header");
+    }
+    const carriesPayload = kind === "upload_chunk" || kind === "download_chunk";
+    if (carriesPayload !== (payloadLength > 0)) {
+        throw new RelayFileFrameError("invalid_length", "Relay file payload does not match its kind");
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import type { ConnectProblem } from "./connect-problems.generated.js";
+import type { ApplicationFileRequirement, CollectionFileDescriptor, FileCapability } from "./files.js";
+export * from "./connect-problems.generated.js";
+export * from "./files.js";
 export declare const CONTROL_PROTOCOL_VERSION: 1;
 export declare const ENCRYPTED_RELAY_PROTOCOL_VERSION: 1;
 export declare const LOOPBACK_PROTOCOL_VERSION: 1;
@@ -5,8 +9,9 @@ export declare const DEFAULT_LOOPBACK_PORT: 28485;
 export declare const RELAY_ENCRYPTION_SUITE: "P256-HKDF-SHA256-AES256GCM";
 export declare const SYNC_PROTOCOL_VERSION: 1;
 export declare const CONTRACT_SETUP_CAPABILITY: "contract-setup-v1";
+export declare const FILE_RELAY_CAPABILITY: "file-relay-v1";
 export declare const RELAY_REQUIRED_CAPABILITIES: readonly ["authorization-activation", "encrypted-relay", "policy-ack"];
-export declare const RELAY_CAPABILITIES: readonly ["authorization-activation", "encrypted-relay", "policy-ack", "contract-setup-v1"];
+export declare const RELAY_CAPABILITIES: readonly ["authorization-activation", "encrypted-relay", "policy-ack", "contract-setup-v1", "file-relay-v1"];
 export declare const AUTHORITY_PROOF_VERSION: 1;
 export declare const AUTHORITY_PROOF_ALGORITHM: "P256-SHA256";
 export declare const AUTHORITY_PROOF_DOMAIN: "mdbase-authority-request-proof-v1";
@@ -29,6 +34,7 @@ export declare const CONNECT_SCHEMA_IDS: {
     readonly eventActionInterop: "https://mdbase.dev/schemas/interop/v0.1/profile.schema.json";
     readonly protocol: "https://mdbase.dev/connect/schemas/connect-protocol.v1.json";
     readonly encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v1.json";
+    readonly files: "https://mdbase.dev/connect/schemas/files.v1.json";
     readonly sync: "https://mdbase.dev/connect/schemas/sync.v1.json";
 };
 export type CollectionOperation = "describe" | "changes" | "read" | "query" | "list_views" | "execute_view" | "read_view_source" | "create_view_source" | "update_view_source" | "delete_view_source" | "validate" | "create" | "update" | "delete" | "rename" | "read_type" | "create_type" | "update_type" | "install_type_pack" | "list_timers" | "put_timer" | "cancel_timer" | "reconcile_timers" | "sync";
@@ -143,6 +149,8 @@ export interface ApplicationRequirements {
     access?: "contract" | "full_collection";
     /** Restrict authorization to durable provider-backed collections. */
     collection_kind?: "hosted";
+    /** First-class non-Markdown file access requested independently of records. */
+    files?: ApplicationFileRequirement;
 }
 export interface TypePackManifestResource {
     kind: "contract" | "type" | "schema";
@@ -217,17 +225,19 @@ export interface RelayOperationRequest {
     operation: CollectionOperation;
     input: unknown;
 }
-export interface RelayOperationResponse {
+export type RelayOperationResponse = {
     type: "operation_response";
     protocol_version: 1;
     request_id: string;
-    ok: boolean;
-    result?: unknown;
-    error?: {
-        code: string;
-        message: string;
-    };
-}
+    ok: true;
+    result: unknown;
+} | {
+    type: "operation_response";
+    protocol_version: 1;
+    request_id: string;
+    ok: false;
+    problem: ConnectProblem;
+};
 export interface MdbaseOperationRequest<Input = unknown> {
     protocol_version: 1;
     request_id: string;
@@ -242,11 +252,7 @@ export type MdbaseOperationResponse<Result = unknown> = {
     protocol_version: 1;
     request_id: string;
     ok: false;
-    error: {
-        code: string;
-        message: string;
-        details?: unknown;
-    };
+    problem: ConnectProblem;
 };
 export interface GrantPolicy {
     id: string;
@@ -268,6 +274,7 @@ export interface GrantPolicy {
     notification_criteria?: NotificationCriterion[];
     created_at: string;
     encryption?: GrantEncryption;
+    file_capability?: FileCapability;
 }
 export interface GrantEncryption {
     protocol_version: 1;
@@ -287,12 +294,14 @@ export interface EncryptedRelayEnvelope {
     application_id: string;
     connector_id: string;
     collection_id: string;
-    operation: CollectionOperation;
+    operation: EncryptedRelayOperation;
     scope_epoch: number;
     key_id: string;
     counter: string;
     ciphertext: string;
 }
+/** Encrypted control namespaces share grant authentication but not record permissions. */
+export type EncryptedRelayOperation = CollectionOperation | "file_control";
 export interface SyncRecord<Frontmatter extends JsonObject = JsonObject> {
     record_id: string;
     path: string;
@@ -327,6 +336,7 @@ export interface AuthoritySnapshot<Frontmatter extends JsonObject = JsonObject>
     manifest_digest: string;
     resources: SyncCollectionResources;
     records: Array<AuthoritySnapshotRecord<Frontmatter>>;
+    files: CollectionFileDescriptor[];
 }
 export interface AuthorityImportManifest {
     protocol_version: 1;
@@ -336,6 +346,8 @@ export interface AuthorityImportManifest {
     manifest_digest: string;
     resources: SyncCollectionResources;
     record_count: number;
+    file_count: number;
+    files: CollectionFileDescriptor[];
 }
 export interface AuthorityImportRecord {
     record_id: string;
@@ -350,6 +362,7 @@ export interface AuthorityImportSnapshot {
     manifest_digest: string;
     resources: SyncCollectionResources;
     records: AuthorityImportRecord[];
+    files: CollectionFileDescriptor[];
 }
 export interface AuthorityImportRecordPage {
     protocol_version: 1;
@@ -380,6 +393,16 @@ export interface SyncSnapshotRecord<Frontmatter extends JsonObject = JsonObject>
     /** Exact bytes whose SHA-256 revision and parsed metadata match this record. */
     document: string;
 }
+/** Manifest-only snapshot page. File bytes are fetched by digest via the file data plane. */
+export interface SyncFileSnapshotPage {
+    protocol_version: 1;
+    type: "file_snapshot_page";
+    snapshot_id: string;
+    scope_epoch: number;
+    cursor: number;
+    files: CollectionFileDescriptor[];
+    next_page?: string;
+}
 export type SyncChange<Frontmatter extends JsonObject = JsonObject> = {
     sequence: number;
     type: "put";
@@ -390,6 +413,16 @@ export type SyncChange<Frontmatter extends JsonObject = JsonObject> = {
     record_id: string;
     previous_path: string;
     revision: string;
+} | {
+    sequence: number;
+    type: "file_put";
+    file: CollectionFileDescriptor;
+} | {
+    sequence: number;
+    type: "file_remove";
+    file_id: string;
+    previous_path: string;
+    revision: string;
 };
 export interface SyncChangesPage<Frontmatter extends JsonObject = JsonObject> {
     protocol_version: 1;
@@ -411,6 +444,31 @@ export interface SyncMutation {
     created_at: string;
     causal_predecessor?: string;
 }
+interface SyncFileMutationBase {
+    mutation_id: string;
+    replica_id: string;
+    scope_epoch: number;
+    file_id: string;
+    created_at: string;
+    causal_predecessor?: string;
+}
+export type SyncFileMutation = (SyncFileMutationBase & {
+    operation: "file_put";
+    base_revision?: string;
+    path: string;
+    transfer_id: string;
+    content_digest: `sha256:${string}`;
+    size: number;
+    media_type?: string;
+}) | (SyncFileMutationBase & {
+    operation: "file_move";
+    base_revision: string;
+    path: string;
+    update_references: boolean;
+}) | (SyncFileMutationBase & {
+    operation: "file_delete";
+    base_revision: string;
+});
 export interface SyncConflict<Frontmatter extends JsonObject = JsonObject> {
     record_id: string;
     mutation: SyncMutation;
@@ -434,6 +492,29 @@ export type SyncMutationReceipt<Frontmatter extends JsonObject = JsonObject> = {
         message: string;
     };
 };
+export interface SyncFileConflict {
+    file_id: string;
+    mutation: SyncFileMutation;
+    current?: CollectionFileDescriptor;
+    current_revision?: string;
+}
+export type SyncFileMutationReceipt = {
+    mutation_id: string;
+    status: "file_applied" | "file_previously_applied";
+    sequence: number;
+    file?: CollectionFileDescriptor;
+} | {
+    mutation_id: string;
+    status: "file_conflicted";
+    conflict: SyncFileConflict;
+} | {
+    mutation_id: string;
+    status: "file_rejected";
+    error: {
+        code: string;
+        message: string;
+    };
+};
 export type EncryptedRelayOperationRequest = EncryptedRelayEnvelope & {
     type: "encrypted_operation_request";
 };
@@ -516,6 +597,7 @@ export interface ConnectorCollection {
 }
 export type JsonObject = Record<string, unknown>;
 export interface MdbaseDiagnostic {
+    [key: string]: unknown;
     severity: "error" | "warning" | "info";
     code: string;
     message: string;
@@ -753,4 +835,3 @@ export interface CollectionChangesPage {
     has_more: boolean;
     reset: boolean;
 }
-export {};

package/dist/index.js

@@ -1,3 +1,5 @@
+export * from "./connect-problems.generated.js";
+export * from "./files.js";
 export const CONTROL_PROTOCOL_VERSION = 1;
 export const ENCRYPTED_RELAY_PROTOCOL_VERSION = 1;
 export const LOOPBACK_PROTOCOL_VERSION = 1;
@@ -5,6 +7,7 @@ export const DEFAULT_LOOPBACK_PORT = 28_485;
 export const RELAY_ENCRYPTION_SUITE = "P256-HKDF-SHA256-AES256GCM";
 export const SYNC_PROTOCOL_VERSION = 1;
 export const CONTRACT_SETUP_CAPABILITY = "contract-setup-v1";
+export const FILE_RELAY_CAPABILITY = "file-relay-v1";
 export const RELAY_REQUIRED_CAPABILITIES = [
     "authorization-activation",
     "encrypted-relay",
@@ -12,7 +15,8 @@ export const RELAY_REQUIRED_CAPABILITIES = [
 ];
 export const RELAY_CAPABILITIES = [
     ...RELAY_REQUIRED_CAPABILITIES,
-    CONTRACT_SETUP_CAPABILITY
+    CONTRACT_SETUP_CAPABILITY,
+    FILE_RELAY_CAPABILITY
 ];
 export const AUTHORITY_PROOF_VERSION = 1;
 export const AUTHORITY_PROOF_ALGORITHM = "P256-SHA256";
@@ -53,5 +57,6 @@ export const CONNECT_SCHEMA_IDS = {
     eventActionInterop: "https://mdbase.dev/schemas/interop/v0.1/profile.schema.json",
     protocol: "https://mdbase.dev/connect/schemas/connect-protocol.v1.json",
     encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v1.json",
+    files: "https://mdbase.dev/connect/schemas/files.v1.json",
     sync: "https://mdbase.dev/connect/schemas/sync.v1.json"
 };