@mdbase-dev/connect 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/hosted-file-request.js

@@ -0,0 +1,63 @@
+import { connectError } from "./errors.js";
+import { apiError } from "./runtime-utils.js";
+export async function sendHostedFileRequest(token, method, path, input, signal, proofHeaders) {
+    if (!token.authority) {
+        throw connectError("not_remote_authority", "This authorization has no remote authority endpoint.");
+    }
+    const suffix = path === "" || path.startsWith("?") ? path : `/${path}`;
+    const url = `${token.authority.filesUrl}${suffix}`;
+    const body = input === undefined ? undefined : JSON.stringify(input);
+    const proof = await proofHeaders(token, method, url, body, token.authority.accessToken);
+    return fetch(url, {
+        method,
+        redirect: "error",
+        headers: {
+            authorization: `Bearer ${token.authority.accessToken}`,
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+            ...proof
+        },
+        ...(body === undefined ? {} : { body }),
+        ...(signal ? { signal } : {})
+    });
+}
+export async function performHostedFileRequest(token, method, path, input, signal, refresh, proofHeaders) {
+    let active = token;
+    let response = await sendHostedFileRequest(active, method, path, input, signal, proofHeaders);
+    if (response.status === 401 && active.refreshToken) {
+        active = await refresh();
+        if (!active.authority || !active.fileCapability) {
+            throw connectError("authority_authorization_changed", "Reconnect this collection before accessing its files.");
+        }
+        response = await sendHostedFileRequest(active, method, path, input, signal, proofHeaders);
+    }
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        throw apiError(body, "operation_failed", "Collection file request failed.", response.status);
+    }
+    return body;
+}
+export async function performHostedFilePartRequest(token, path, expectedLength, signal, refresh, proofHeaders) {
+    let active = token;
+    let response = await sendHostedFileRequest(active, "GET", path, undefined, signal, proofHeaders);
+    if (response.status === 401 && active.refreshToken) {
+        active = await refresh();
+        if (!active.authority || !active.fileCapability) {
+            throw connectError("authority_authorization_changed", "Reconnect this collection before accessing its files.");
+        }
+        response = await sendHostedFileRequest(active, "GET", path, undefined, signal, proofHeaders);
+    }
+    if (!response.ok) {
+        const body = await response.json().catch(() => ({}));
+        throw apiError(body, "operation_failed", "Collection file range request failed.", response.status);
+    }
+    const contentLength = response.headers.get("content-length");
+    if (contentLength === null || !/^(0|[1-9][0-9]*)$/u.test(contentLength)
+        || Number(contentLength) !== expectedLength) {
+        await response.body?.cancel().catch(() => undefined);
+        throw connectError("invalid_operation_response", "The hosted file response declared an unexpected byte length.");
+    }
+    if (!response.body) {
+        throw connectError("invalid_operation_response", "The hosted file response did not contain a byte stream.");
+    }
+    return response.body;
+}

package/dist/index.d.ts

@@ -1,13 +1,16 @@
 export { decryptRelayResponse, encryptRelayRequest, IndexedDbGrantKeyStore, MemoryGrantKeyStore, RelayCryptoError, type RelayBinding, type GrantKeyRecord, type GrantKeyStore } from "./crypto.js";
+export { FileTransferCryptoError, GrantFileTransferCipher, type FileTransferBinding } from "./file-crypto.js";
 export * from "./authorization-types.js";
 export * from "./collection-client.js";
 export * from "./connect.js";
 export * from "./connection.js";
 export * from "./connection-types.js";
 export * from "./errors.js";
+export * from "./files.js";
 export * from "./notifications.js";
+export * from "./outcomes.js";
 export * from "./operation-types.js";
 export * from "./selection.js";
 export * from "./session.js";
 export { createPkce } from "./runtime-utils.js";
-export type { ApplicationProvisions, ApplicationRequirements, ApplicationNotifications, CollectionChange, CollectionChangesPage, CollectionContractDescriptor, CollectionDescription, CollectionFileMetadata, CollectionOperation as MdbaseOperation, CollectionTypeDescriptor, CollectionTypeDocument, ContractRequirement, DataContractViewIdentity, GrantScope, JsonObject, MdbaseAppManifest, NotificationCriterion, MdbaseDiagnostic, MdbaseOperationEnvelope, RecordDocument, QueryRecord, SavedNamedView, SavedViewDocument, SavedViewExecution, SavedViewList, SavedViewPresentation, SavedViewProperty, SavedViewSource, SavedViewSourceDocument, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, TypePackManifest, TypePackManifestResource, TypePackInstallResult, TypePackProvision, TypePackResourceDiff, TypePackSourceResource } from "@mdbase-dev/connect-protocol";
+export type { ApplicationProvisions, ApplicationRequirements, ApplicationNotifications, CollectionChange, CollectionChangesPage, CollectionContractDescriptor, CollectionDescription, CollectionFileMetadata, CollectionOperation as MdbaseOperation, CollectionTypeDescriptor, CollectionTypeDocument, ConnectOperationOutcome, ConnectProblem, ConnectProblemCategory, ConnectProblemCode, ConnectProblemDetailsByCode, ConnectRecoveryAction, ContractRequirement, DataContractViewIdentity, GrantScope, JsonObject, MdbaseAppManifest, NotificationCriterion, MdbaseDiagnostic, MdbaseOperationEnvelope, KnownConnectProblem, RecordDocument, QueryRecord, SavedNamedView, SavedViewDocument, SavedViewExecution, SavedViewList, SavedViewPresentation, SavedViewProperty, SavedViewSource, SavedViewSourceDocument, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, TypePackManifest, TypePackManifestResource, TypePackInstallResult, TypePackProvision, TypePackResourceDiff, TypePackSourceResource, UnknownConnectProblem } from "@mdbase-dev/connect-protocol";

package/dist/index.js

@@ -1,11 +1,14 @@
 export { decryptRelayResponse, encryptRelayRequest, IndexedDbGrantKeyStore, MemoryGrantKeyStore, RelayCryptoError } from "./crypto.js";
+export { FileTransferCryptoError, GrantFileTransferCipher } from "./file-crypto.js";
 export * from "./authorization-types.js";
 export * from "./collection-client.js";
 export * from "./connect.js";
 export * from "./connection.js";
 export * from "./connection-types.js";
 export * from "./errors.js";
+export * from "./files.js";
 export * from "./notifications.js";
+export * from "./outcomes.js";
 export * from "./operation-types.js";
 export * from "./selection.js";
 export * from "./session.js";

package/dist/internal-types.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationNotifications, CollectionOperation, EncryptedRelayOperationRequest, GrantEncryption, GrantScope } from "@mdbase-dev/connect-protocol";
+import type { ApplicationNotifications, CollectionOperation, EncryptedRelayOperationRequest, GrantEncryption, FileCapability, GrantScope } from "@mdbase-dev/connect-protocol";
 import { encryptRelayRequest } from "./crypto.js";
 export interface Application {
     id: string;
@@ -34,12 +34,14 @@ export interface StoredToken {
     refreshExpiresAt?: number;
     grantId?: string;
     encryption?: GrantEncryption;
+    fileCapability?: FileCapability;
     applicationOrigin?: string;
     keyHandle?: string;
     savedAt: number;
     authority?: {
         operationsUrl: string;
         syncUrl: string;
+        filesUrl: string;
         replicaId: string;
         accessToken: string;
         proofPublicKey?: string;

package/dist/local-file-transport.d.ts

@@ -0,0 +1,30 @@
+import type { FileTransferSession } from "@mdbase-dev/connect-protocol";
+import { type GrantKeyStore } from "./crypto.js";
+import type { StoredToken } from "./internal-types.js";
+interface LocalFileTransportOptions {
+    keyStore: GrantKeyStore;
+    serverUrl: string;
+    loopbackUrl: string;
+    authorizedToken(): Promise<StoredToken | null>;
+    refreshAuthorization(): Promise<StoredToken>;
+    shouldAttemptDirect(token: StoredToken): Promise<boolean>;
+    onDirectAvailable(): void;
+    onDirectUnavailable(): void;
+    onRelayAvailable(): void;
+}
+/** Keeps grant-bound file crypto and loopback framing out of the operation transport. */
+export declare class LocalFileTransport {
+    private readonly options;
+    constructor(options: LocalFileTransportOptions);
+    control<Result>(token: StoredToken, method: "GET" | "POST" | "DELETE", path: string, input: unknown, signal?: AbortSignal): Promise<Result>;
+    private decryptControlResponse;
+    uploadChunk(session: FileTransferSession, chunkIndex: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>;
+    downloadChunk(session: FileTransferSession, chunkIndex: number, signal?: AbortSignal): Promise<Uint8Array>;
+    private decryptDownloadResponse;
+    private encryptControl;
+    private sendRelayControl;
+    private sendRelayUpload;
+    private sendRelayDownload;
+    private localFileToken;
+}
+export {};

package/dist/local-file-transport.js

@@ -0,0 +1,367 @@
+import { decodeFileFrame, FILE_PROTOCOL_VERSION, FILE_TRANSFER_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
+import { decryptRelayResponse, encryptRelayRequest } from "./crypto.js";
+import { MdbaseConnectError, connectError, serverConnectError } from "./errors.js";
+import { GrantFileTransferCipher } from "./file-crypto.js";
+import { directFallbackStatus, loopbackRequest } from "./operation-helpers.js";
+import { apiError } from "./runtime-utils.js";
+/** Keeps grant-bound file crypto and loopback framing out of the operation transport. */
+export class LocalFileTransport {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async control(token, method, path, input, signal) {
+        requireEncryption(token);
+        const controlInput = localFileControlInput(method, path, input);
+        let encryptedRequest = await this.encryptControl(token, controlInput);
+        let response;
+        if (await this.options.shouldAttemptDirect(token)) {
+            try {
+                response = await fetch(`${this.options.loopbackUrl}/v1/files/control`, loopbackRequest({
+                    method: "POST",
+                    headers: { "content-type": "application/mdbase-connect+json" },
+                    body: JSON.stringify(encryptedRequest),
+                    signal
+                }));
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                this.options.onDirectUnavailable();
+            }
+            if (response && !directFallbackStatus(response.status)) {
+                if (response.ok)
+                    this.options.onDirectAvailable();
+                return this.decryptControlResponse(token, encryptedRequest, response);
+            }
+            if (response)
+                this.options.onDirectUnavailable();
+        }
+        response = await this.sendRelayControl(token, encryptedRequest, signal);
+        if (await refreshableBindingFailure(response, token)) {
+            token = await this.options.refreshAuthorization();
+            requireLocalFileToken(token);
+            encryptedRequest = await this.encryptControl(token, controlInput);
+            response = await this.sendRelayControl(token, encryptedRequest, signal);
+        }
+        if (response.ok)
+            this.options.onRelayAvailable();
+        return this.decryptControlResponse(token, encryptedRequest, response);
+    }
+    async decryptControlResponse(token, encryptedRequest, response) {
+        const body = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            throw apiError(body, "operation_failed", "Collection file request failed.", response.status);
+        }
+        const encryptedResponse = body?.envelope;
+        if (!encryptedResponse) {
+            throw connectError("invalid_encrypted_response", "The connector omitted its encrypted file response.");
+        }
+        const decrypted = await decryptRelayResponse(this.options.keyStore, token.keyHandle, relayBinding(token), encryptedRequest, encryptedResponse);
+        if (!decrypted.ok)
+            throwEncryptedProblem(decrypted.problem);
+        return decrypted.result;
+    }
+    async uploadChunk(session, chunkIndex, bytes, signal) {
+        const token = await this.localFileToken(session, "upload");
+        let deliveryToken = token;
+        let encoded = await encryptedUploadChunk(this.options.keyStore, deliveryToken, session, chunkIndex, bytes);
+        let response;
+        if (await this.options.shouldAttemptDirect(deliveryToken)) {
+            try {
+                response = await fetch(`${this.options.loopbackUrl}/v1/files/upload`, loopbackRequest(fileUploadRequest(encoded, signal)));
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                this.options.onDirectUnavailable();
+            }
+            if (response && !directFallbackStatus(response.status)) {
+                if (response.ok)
+                    this.options.onDirectAvailable();
+                return requireSuccessfulChunkResponse(response, "Encrypted file chunk upload failed.");
+            }
+            if (response)
+                this.options.onDirectUnavailable();
+        }
+        response = await this.sendRelayUpload(deliveryToken, encoded, signal);
+        if (response.status === 401 && deliveryToken.refreshToken) {
+            deliveryToken = await this.options.refreshAuthorization();
+            requireLocalFileToken(deliveryToken);
+            encoded = await encryptedUploadChunk(this.options.keyStore, deliveryToken, session, chunkIndex, bytes);
+            response = await this.sendRelayUpload(deliveryToken, encoded, signal);
+        }
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw apiError(body, "operation_failed", "Encrypted file chunk upload failed.", response.status);
+        }
+        this.options.onRelayAvailable();
+    }
+    async downloadChunk(session, chunkIndex, signal) {
+        let token = await this.localFileToken(session, "download");
+        let response;
+        if (await this.options.shouldAttemptDirect(token)) {
+            try {
+                response = await fetch(`${this.options.loopbackUrl}/v1/files/download/${encodeURIComponent(token.grantId)}/${encodeURIComponent(session.transfer_id)}/${chunkIndex}`, loopbackRequest({ method: "GET", signal }));
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                this.options.onDirectUnavailable();
+            }
+            if (response && !directFallbackStatus(response.status)) {
+                if (response.ok)
+                    this.options.onDirectAvailable();
+                return this.decryptDownloadResponse(token, session, chunkIndex, response);
+            }
+            if (response)
+                this.options.onDirectUnavailable();
+        }
+        response = await this.sendRelayDownload(token, session, chunkIndex, signal);
+        if (response.status === 401 && token.refreshToken) {
+            token = await this.options.refreshAuthorization();
+            requireLocalFileToken(token);
+            response = await this.sendRelayDownload(token, session, chunkIndex, signal);
+        }
+        if (response.ok)
+            this.options.onRelayAvailable();
+        return this.decryptDownloadResponse(token, session, chunkIndex, response);
+    }
+    async decryptDownloadResponse(token, session, chunkIndex, response) {
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw apiError(body, "operation_failed", "Encrypted file chunk download failed.", response.status);
+        }
+        if (response.headers.get("content-type")?.split(";", 1)[0]
+            !== "application/mdbase-connect-file") {
+            throw connectError("invalid_operation_response", "The connector returned an invalid file response media type.");
+        }
+        const encoded = new Uint8Array(await response.arrayBuffer());
+        let plaintext;
+        try {
+            validateDownloadFrame(session, chunkIndex, encoded);
+            plaintext = await (await fileCipher(this.options.keyStore, token, session))
+                .decryptChunk(encoded);
+        }
+        catch (cause) {
+            if (cause instanceof MdbaseConnectError)
+                throw cause;
+            throw connectError("invalid_operation_response", "The connector returned an invalid encrypted file frame.", { cause });
+        }
+        if (plaintext.byteLength !== expectedFramedChunkLength(session, chunkIndex)) {
+            throw connectError("invalid_operation_response", "The connector returned a truncated file chunk.");
+        }
+        return plaintext;
+    }
+    encryptControl(token, input) {
+        requireEncryption(token);
+        return encryptRelayRequest(this.options.keyStore, token.keyHandle, relayBinding(token), "file_control", input);
+    }
+    sendRelayControl(token, encryptedRequest, signal) {
+        return fetch(`${this.options.serverUrl}/v1/authorities/${encodeURIComponent(token.collectionId)}/files/control`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token.accessToken}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify(encryptedRequest),
+            signal
+        });
+    }
+    sendRelayUpload(token, encoded, signal) {
+        return fetch(`${this.options.serverUrl}/v1/authorities/${encodeURIComponent(token.collectionId)}/files/upload`, {
+            ...fileUploadRequest(encoded, signal),
+            headers: {
+                authorization: `Bearer ${token.accessToken}`,
+                "content-type": "application/mdbase-connect-file"
+            }
+        });
+    }
+    sendRelayDownload(token, session, chunkIndex, signal) {
+        return fetch(`${this.options.serverUrl}/v1/authorities/${encodeURIComponent(token.collectionId)}/files/download/${encodeURIComponent(session.transfer_id)}/${chunkIndex}`, {
+            method: "GET",
+            headers: { authorization: `Bearer ${token.accessToken}` },
+            signal
+        });
+    }
+    async localFileToken(session, direction) {
+        const token = await this.options.authorizedToken();
+        if (!token || token.authority || !token.fileCapability || !token.encryption
+            || !token.grantId || !token.keyHandle
+            || session.direction !== direction
+            || session.protection !== "grant_aead_v1") {
+            throw connectError("not_authorized", "This connection cannot use encrypted local file delivery.");
+        }
+        framedChunkSize(session);
+        return token;
+    }
+}
+function requireLocalFileToken(token) {
+    if (token.authority || !token.fileCapability) {
+        throw connectError("not_authorized", "This connection cannot use encrypted local file delivery.");
+    }
+    requireEncryption(token);
+}
+async function encryptedUploadChunk(keyStore, token, session, chunkIndex, bytes) {
+    const header = fileFrameHeader(token, session, chunkIndex, bytes.byteLength);
+    return (await fileCipher(keyStore, token, session))
+        .encryptChunk("upload_chunk", header, bytes);
+}
+function fileUploadRequest(encoded, signal) {
+    return {
+        method: "POST",
+        headers: { "content-type": "application/mdbase-connect-file" },
+        body: Uint8Array.from(encoded).buffer,
+        signal
+    };
+}
+async function requireSuccessfulChunkResponse(response, message) {
+    if (response.ok)
+        return;
+    const body = await response.json().catch(() => ({}));
+    throw apiError(body, "operation_failed", message, response.status);
+}
+async function refreshableBindingFailure(response, token) {
+    if (!token.refreshToken)
+        return false;
+    if (response.status === 401)
+        return true;
+    if (response.status !== 409)
+        return false;
+    const body = await response.clone().json().catch(() => null);
+    return body?.error?.code === "encryption_binding_stale";
+}
+function requireEncryption(token) {
+    if (!token.encryption || !token.grantId || !token.keyHandle) {
+        throw connectError("missing_grant_key", "Reconnect this application to restore encrypted file access.");
+    }
+}
+function relayBinding(token) {
+    requireEncryption(token);
+    return {
+        grantId: token.grantId,
+        applicationId: token.clientId,
+        encryption: token.encryption
+    };
+}
+function fileCipher(keyStore, token, session) {
+    requireEncryption(token);
+    return GrantFileTransferCipher.open(keyStore, token.keyHandle, {
+        ...relayBinding(token),
+        authorityId: token.encryption.connector_id,
+        transferId: session.transfer_id,
+        direction: session.direction
+    });
+}
+function fileFrameHeader(token, session, chunkIndex, plaintextLength) {
+    requireEncryption(token);
+    const chunkSize = framedChunkSize(session);
+    const expectedLength = expectedFramedChunkLength(session, chunkIndex);
+    if (plaintextLength !== expectedLength) {
+        throw connectError("invalid_request", "The file chunk has the wrong byte length.");
+    }
+    return {
+        protocol_version: FILE_TRANSFER_PROTOCOL_VERSION,
+        protection: "grant_aead_v1",
+        grant_id: token.grantId,
+        authority_id: token.encryption.connector_id,
+        collection_id: token.collectionId,
+        transfer_id: session.transfer_id,
+        direction: session.direction,
+        chunk_size: chunkSize,
+        chunk_index: chunkIndex,
+        offset: chunkIndex * chunkSize,
+        plaintext_length: plaintextLength,
+        total_size: session.total_size,
+        scope_epoch: token.encryption.scope_epoch,
+        key_id: token.encryption.key_id
+    };
+}
+function validateDownloadFrame(session, chunkIndex, encoded) {
+    const frame = decodeFileFrame(encoded);
+    const expectedLength = expectedFramedChunkLength(session, chunkIndex);
+    const chunkSize = framedChunkSize(session);
+    if (frame.kind !== "download_chunk"
+        || frame.header.chunk_index !== chunkIndex
+        || frame.header.chunk_size !== chunkSize
+        || frame.header.offset !== chunkIndex * chunkSize
+        || frame.header.plaintext_length !== expectedLength
+        || frame.header.total_size !== session.total_size) {
+        throw connectError("invalid_operation_response", "The connector returned a file frame for a different chunk.");
+    }
+}
+function throwEncryptedProblem(problem) {
+    throw serverConnectError(problem.code === "unknown" ? problem.server_code : problem.code, problem.message, {
+        details: problem.details,
+        operationOutcome: problem.operation_outcome ?? "rejected",
+        traceId: problem.trace_id
+    });
+}
+function localFileControlInput(method, path, input) {
+    if (method === "GET" && (path === "" || path.startsWith("?"))) {
+        const query = new URLSearchParams(path.startsWith("?") ? path.slice(1) : path);
+        const limit = query.get("limit");
+        return {
+            protocol_version: FILE_PROTOCOL_VERSION,
+            type: "list_files",
+            ...(query.get("folder") ? { folder: query.get("folder") } : {}),
+            ...(query.get("after") ? { after: query.get("after") } : {}),
+            ...(limit ? { limit: Number(limit) } : {})
+        };
+    }
+    const segments = path.split("/");
+    if (method === "GET" && segments.length === 2 && segments[0] === "transfers") {
+        return transferControl("get_file_transfer_status", segments[1]);
+    }
+    if (method === "DELETE" && segments.length === 2 && segments[0] === "transfers") {
+        return transferControl("abort_file_transfer", segments[1]);
+    }
+    if (method === "POST" && isRecord(input)) {
+        const expectedType = path === "uploads"
+            ? "open_file_upload"
+            : path === "downloads"
+                ? "open_file_download"
+                : segments.length === 3 && segments[0] === "uploads" && segments[2] === "commit"
+                    ? "commit_file_upload"
+                    : segments.length === 2 && segments[1] === "move"
+                        && input.file_id === decodeURIComponent(segments[0])
+                        ? "move_file"
+                        : segments.length === 2 && segments[1] === "delete"
+                            && input.file_id === decodeURIComponent(segments[0])
+                            ? "delete_file"
+                            : null;
+        if (expectedType && input.type === expectedType)
+            return { ...input };
+    }
+    throw connectError("invalid_request", "The file control request path is invalid.");
+}
+function transferControl(type, encodedId) {
+    return {
+        protocol_version: FILE_PROTOCOL_VERSION,
+        type,
+        transfer_id: decodeURIComponent(encodedId)
+    };
+}
+function framedChunkSize(session) {
+    if (session.strategy.kind !== "framed_chunks"
+        || !Number.isSafeInteger(session.strategy.chunk_size)
+        || session.strategy.chunk_size <= 0) {
+        throw connectError("invalid_operation_response", "The connector returned an invalid framed transfer strategy.");
+    }
+    return session.strategy.chunk_size;
+}
+function expectedFramedChunkLength(session, chunkIndex) {
+    const chunkSize = framedChunkSize(session);
+    if (!Number.isSafeInteger(chunkIndex) || chunkIndex < 0
+        || !Number.isSafeInteger(session.total_size) || session.total_size < 0) {
+        throw connectError("invalid_request", "The file chunk index is invalid.");
+    }
+    const offset = chunkIndex * chunkSize;
+    if (!Number.isSafeInteger(offset) || offset >= session.total_size) {
+        throw connectError("invalid_request", "The file chunk index is outside the transfer.");
+    }
+    return Math.min(chunkSize, session.total_size - offset);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/notifications.js

@@ -1,7 +1,7 @@
-import { MdbaseConnectError } from "./errors.js";
+import { connectError } from "./errors.js";
 export function parseMdbasePushPayload(value) {
     if (!value || typeof value !== "object") {
-        throw new MdbaseConnectError("invalid_push_payload", "The push payload is not an object.");
+        throw connectError("invalid_push_payload", "The push payload is not an object.");
     }
     const payload = value;
     if (payload.type !== "mdbase.notification"
@@ -11,14 +11,14 @@ export function parseMdbasePushPayload(value) {
         || typeof payload.cursor !== "string"
         || !payload.presentation
         || typeof payload.presentation.title !== "string") {
-        throw new MdbaseConnectError("invalid_push_payload", "The push payload is not an mdbase notification.");
+        throw connectError("invalid_push_payload", "The push payload is not an mdbase notification.");
     }
     return payload;
 }
 /** Parse the string-valued data attached to an APNs/FCM notification. */
 export function parseMdbaseNativeNotificationData(value) {
     if (!value || typeof value !== "object") {
-        throw new MdbaseConnectError("invalid_push_payload", "The native notification data is not an object.");
+        throw connectError("invalid_push_payload", "The native notification data is not an object.");
     }
     const data = value;
     if (data.type !== "mdbase.notification"
@@ -26,7 +26,7 @@ export function parseMdbaseNativeNotificationData(value) {
         || typeof data.signal_id !== "string"
         || typeof data.criterion_id !== "string"
         || typeof data.cursor !== "string") {
-        throw new MdbaseConnectError("invalid_push_payload", "The native notification data is not an mdbase notification.");
+        throw connectError("invalid_push_payload", "The native notification data is not an mdbase notification.");
     }
     return {
         type: "mdbase.notification",

package/dist/operation-helpers.d.ts

@@ -12,7 +12,7 @@ export declare function isMutation(operation: CollectionOperation, input?: unkno
 export declare function uniqueOperations(operations: CollectionOperation[]): CollectionOperation[];
 export declare function sameAuthorization(left: StoredToken, right: StoredToken): boolean;
 export declare function throwIfCancelled(signal?: AbortSignal): void;
-export declare function operationTransportError(error: unknown, signal: AbortSignal | undefined, outcomeUnknown: boolean): Error;
+export declare function operationTransportError(error: unknown, signal: AbortSignal | undefined, outcomeUnknown: boolean, unavailableCode: "hosted_provider_unavailable" | "relay_unavailable"): Error;
 export declare function isCancellation(error: unknown, signal?: AbortSignal): boolean;
 export declare function assertRenamePreview(input: RenameInput, preview: RenamePreflightResult): void;
 export declare function assertDeletePreview(input: DeleteInput, preview: DeletePreflightResult): void;
@@ -21,4 +21,4 @@ export declare function deleteEstimate(preview: DeletePreflightResult): Mutation
 export declare function operationFingerprint(operation: CollectionOperation, input: unknown): Promise<string>;
 export declare function canonicalJson(value: unknown): string;
 export declare function sortJson(value: unknown): unknown;
-export declare function uncertainDirectMutation(cause: unknown): MdbaseConnectError;
+export declare function unknownMutationOutcome(cause: unknown): MdbaseConnectError;

package/dist/operation-helpers.js

@@ -1,4 +1,4 @@
-import { MdbaseConnectError } from "./errors.js";
+import { MdbaseConnectError, connectError } from "./errors.js";
 import { bytesToBase64Url } from "./base64.js";
 export function loopbackRequest(init) {
     return { ...init, credentials: "omit", targetAddressSpace: "loopback" };
@@ -53,22 +53,26 @@ export function sameAuthorization(left, right) {
 export function throwIfCancelled(signal) {
     if (!signal?.aborted)
         return;
-    throw new MdbaseConnectError("operation_cancelled", "The operation was cancelled before it changed the collection.", { recovery: "none", cause: signal.reason });
-}
-export function operationTransportError(error, signal, outcomeUnknown) {
+    throw connectError("operation_cancelled", "The operation was cancelled before it changed the collection.", { operationOutcome: "not_sent", cause: signal.reason });
+}
+export function operationTransportError(error, signal, outcomeUnknown, unavailableCode) {
+    // Problems raised before transport dispatch already describe the
+    // authoritative outcome. Do not overwrite them merely because an older
+    // pending mutation also exists in storage.
+    if (error instanceof MdbaseConnectError)
+        return error;
     if (signal?.aborted) {
-        return new MdbaseConnectError("operation_cancelled", outcomeUnknown
-            ? "Waiting was cancelled after the mutation was sent. Resume the pending mutation to recover its authoritative result."
-            : "The operation was cancelled before it changed the collection.", {
-            outcomeUnknown,
-            recovery: outcomeUnknown ? "resolve_outcome" : "none",
-            cause: error
-        });
+        if (outcomeUnknown)
+            return unknownMutationOutcome(error);
+        return connectError("operation_cancelled", "The operation was cancelled before it changed the collection.", { operationOutcome: "not_sent", cause: error });
     }
     if (outcomeUnknown) {
-        if (error instanceof MdbaseConnectError && error.outcomeUnknown)
-            return error;
-        return uncertainDirectMutation(error);
+        return unknownMutationOutcome(error);
+    }
+    if (error instanceof TypeError) {
+        return connectError(unavailableCode, unavailableCode === "hosted_provider_unavailable"
+            ? "The hosted collection provider is unavailable."
+            : "The Connect relay is unavailable.", { cause: error });
     }
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -79,12 +83,12 @@ export function isCancellation(error, signal) {
 export function assertRenamePreview(input, preview) {
     if (preview.dry_run !== true || preview.would_rename !== true
         || preview.from !== input.from || preview.to !== input.to) {
-        throw new MdbaseConnectError("invalid_preflight", "The rename preview does not match this mutation. Run the preview again.", { recovery: "fix_request" });
+        throw connectError("invalid_preflight", "The rename preview does not match this mutation. Run the preview again.");
     }
 }
 export function assertDeletePreview(input, preview) {
     if (preview.dry_run !== true || preview.would_delete !== true || preview.path !== input.path) {
-        throw new MdbaseConnectError("invalid_preflight", "The delete preview does not match this mutation. Run the preview again.", { recovery: "fix_request" });
+        throw connectError("invalid_preflight", "The delete preview does not match this mutation. Run the preview again.");
     }
 }
 export function renameEstimate(input, preview) {
@@ -124,6 +128,6 @@ export function sortJson(value) {
     }
     return value;
 }
-export function uncertainDirectMutation(cause) {
-    return new MdbaseConnectError("direct_outcome_unknown", "The direct write may have completed, and mdbase could not recover its receipt through the relay. Retry the exact same write to recover safely.", { cause });
+export function unknownMutationOutcome(cause) {
+    return connectError("operation_outcome_unknown", "The write may have completed, but mdbase could not recover its authoritative result. Retry the exact same write to recover safely.", { operationOutcome: "unknown", cause });
 }