@mdbase-dev/connect 0.1.0-beta.31 → 0.1.0-beta.32

package/dist/connection-transport.js

@@ -1,9 +1,13 @@
-import { isConnectProblem } from "@mdbase-dev/connect-protocol";
-import { decryptRelayResponse, encryptRelayRequest, RelayCryptoError, signAuthorityRequest } from "./crypto.js";
+import { OPERATION_TRANSPORT_PROTOCOL_VERSION, isConnectProblem, mutationOperationIdentifier } from "@mdbase-dev/connect-protocol";
+import { decryptRelayResponse, encryptRelayRequest, RelayCryptoError } from "./crypto.js";
 import { MdbaseConnectError, connectError, serverConnectError } from "./errors.js";
 import { ConnectionFileTransport } from "./connection-file-transport.js";
+import { authorityProofHeaders } from "./authority-proof.js";
+import { PendingMutationStore } from "./pending-mutation-store.js";
 import { directFallbackStatus, isMutation, localNetworkPermission, loopbackRequest, operationFingerprint, operationTransportError, sameAuthorization, throwIfCancelled, unknownMutationOutcome } from "./operation-helpers.js";
-import { apiError, oauthErrorCode, parseGrantScope, parseStored, validStoredAuthority, validStoredEncryption, validFileCapability } from "./runtime-utils.js";
+import { apiError, decodeJsonResponse, oauthErrorCode, parseStored, } from "./runtime-utils.js";
+import { readStoredToken } from "./stored-token.js";
+import { withCooperativeRequestBudget, withRequestBudget } from "./request-budget.js";
 export class ConnectionTransport {
     serverUrl;
     storage;
@@ -13,6 +17,8 @@ export class ConnectionTransport {
     collectionId;
     internals;
     onChange;
+    timeouts;
+    pendingMutationStore;
     files;
     refreshPromise = null;
     directStatus;
@@ -28,12 +34,14 @@ export class ConnectionTransport {
         this.collectionId = options.collectionId;
         this.internals = options.internals;
         this.onChange = options.onChange;
+        this.timeouts = options.timeouts;
+        this.pendingMutationStore = new PendingMutationStore(this.storage, this.internals.pendingMutationKey(this.collectionId));
         this.files = new ConnectionFileTransport({
             keyStore: this.keyStore,
             serverUrl: this.serverUrl,
             loopbackUrl: this.loopbackUrl,
-            authorizedToken: () => this.authorizedToken(),
-            refreshAuthorization: () => this.refreshAuthorization(),
+            authorizedToken: (signal) => this.authorizedToken({ signal, timeoutMs: null }),
+            refreshAuthorization: (signal) => this.refreshAuthorization(signal),
             shouldAttemptDirect: (token) => this.shouldAttemptDirect(token),
             onDirectAvailable: () => {
                 this.markDirectAvailable();
@@ -41,7 +49,7 @@ export class ConnectionTransport {
             },
             onDirectUnavailable: () => this.markDirectUnavailable(),
             onRelayAvailable: () => this.setRoute("relay"),
-            authorityProofHeaders: (token, method, url, body, credential) => this.authorityProofHeaders(token, method, url, body, credential)
+            authorityProofHeaders: (token, method, url, body, credential) => authorityProofHeaders(this.keyStore, token, method, url, body, credential)
         });
         this.directStatus = this.directAccessMode === "disabled"
             ? "disabled"
@@ -56,7 +64,10 @@ export class ConnectionTransport {
     notifyStorageChanged() {
         this.emitConnection();
     }
-    async checkDirectAccess() {
+    async checkDirectAccess(options = {}) {
+        return withRequestBudget(options, this.timeouts.watchStartMs, (budget) => this.checkDirectAccessWithinBudget(budget.signal));
+    }
+    async checkDirectAccessWithinBudget(signal) {
         const token = this.currentToken();
         if (!this.directEligible(token))
             return this.setDirectStatus("disabled");
@@ -64,22 +75,25 @@ export class ConnectionTransport {
         if (permission === "denied")
             return this.setDirectStatus("denied");
         if ((permission === "prompt" || permission === null)
-            && this.storage.getItem(this.directPreferenceKey()) !== "enabled") {
+            && this.storage.getItem(this.internals.directPreferenceKey()) !== "enabled") {
             return this.setDirectStatus("permission_required");
         }
-        return this.probeDirectAccess();
+        return this.probeDirectAccess(signal);
     }
     /** Call from a user gesture to request browser permission for direct local access. */
-    async requestDirectAccess() {
+    async requestDirectAccess(options = {}) {
+        return withRequestBudget(options, this.timeouts.watchStartMs, (budget) => this.requestDirectAccessWithinBudget(budget.signal));
+    }
+    async requestDirectAccessWithinBudget(signal) {
         const token = this.currentToken();
         if (!this.directCapable(token))
             return this.setDirectStatus("disabled");
-        this.storage.setItem(this.directPreferenceKey(), "enabled");
+        this.storage.setItem(this.internals.directPreferenceKey(), "enabled");
         this.directRetryAt = 0;
-        return this.probeDirectAccess();
+        return this.probeDirectAccess(signal);
     }
     disableDirectAccess() {
-        this.storage.setItem(this.directPreferenceKey(), "disabled");
+        this.storage.setItem(this.internals.directPreferenceKey(), "disabled");
         this.setDirectStatus("disabled");
         this.setRoute("relay");
     }
@@ -88,24 +102,39 @@ export class ConnectionTransport {
      * authority is remote, directly connected, or relay connected.
      * Authority credentials and routing stay private inside the SDK.
      */
-    pendingMutation() {
-        const pending = parseStored(this.storage.getItem(this.pendingMutationKey()));
-        const token = this.currentToken();
-        if (!pending || !token
-            || pending.collectionId !== token.collectionId
-            || pending.grantId !== token.grantId
-            || pending.keyId !== token.encryption?.key_id)
-            return null;
-        return { operation: pending.operation, createdAt: pending.createdAt, resumable: true };
-    }
-    async resumePendingMutation(input, options) {
-        const pending = this.pendingMutation();
+    pendingMutations() {
+        return this.storedPendingMutations().map((pending) => ({
+            requestId: pending.requestId,
+            operation: this.pendingMutationStore.identifier(pending),
+            fingerprint: pending.inputFingerprint,
+            status: "outcome_unknown",
+            createdAt: new Date(pending.createdAt).toISOString()
+        }));
+    }
+    pendingMutation(requestId) {
+        const pending = this.storedPendingMutation(requestId);
+        return pending ? {
+            requestId: pending.requestId,
+            operation: this.pendingMutationStore.identifier(pending),
+            fingerprint: pending.inputFingerprint,
+            status: "outcome_unknown",
+            createdAt: new Date(pending.createdAt).toISOString()
+        } : null;
+    }
+    async recoverPendingMutation(requestId, options) {
+        const pending = this.storedPendingMutation(requestId);
         if (!pending) {
             throw connectError("no_pending_mutation", "There is no interrupted mutation to resume.");
         }
-        return this.performOperation(pending.operation, input, options);
+        return withCooperativeRequestBudget(options, this.timeouts.requestMs, (budget) => this.performOperationWithinBudget(pending.operation, pending.request?.input ?? {}, { ...options, signal: budget.signal }, pending));
     }
     async performOperation(operation, input, options = {}) {
+        return withCooperativeRequestBudget(options, this.timeouts.requestMs, (budget) => this.performOperationWithinBudget(operation, input, {
+            ...options,
+            signal: budget.signal
+        }));
+    }
+    async performOperationWithinBudget(operation, input, options, storedPending) {
         throwIfCancelled(options.signal);
         let token = this.currentToken();
         if (!token)
@@ -121,45 +150,51 @@ export class ConnectionTransport {
         }
         let tryDirect = await this.shouldAttemptDirect(token);
         if (!tryDirect) {
-            token = await this.authorizedToken();
+            token = await this.authorizedToken({ signal: options.signal, timeoutMs: null });
             if (!token)
                 throw connectError("not_authorized", "Reconnect this application to continue.");
         }
+        const pendingRequestId = storedPending?.requestId
+            ?? (isMutation(operation, input) ? crypto.randomUUID() : undefined);
         let attempt;
         try {
-            attempt = await this.sendOperation(token, operation, input, tryDirect, options);
+            attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId);
         }
         catch (error) {
-            throw operationTransportError(error, options.signal, isMutation(operation, input) && this.pendingMutation() !== null, token.authority ? "hosted_provider_unavailable" : "relay_unavailable");
+            throw operationTransportError(error, options.signal, pendingRequestId !== undefined && this.storedPendingMutation(pendingRequestId) !== null
+                ? pendingRequestId
+                : undefined, token.authority ? "hosted_provider_unavailable" : "relay_unavailable");
         }
         let response = attempt.response;
         const staleBinding = response.status === 409
-            && (await response.clone().json().catch(() => null))?.error?.code === "encryption_binding_stale";
+            && (await decodeJsonResponse(response.clone(), "invalid_operation_response", "The collection authority returned an invalid operation response.").catch(() => null))?.error?.code === "encryption_binding_stale";
         if ((response.status === 401 || staleBinding) && token.refreshToken) {
             if (attempt.pendingMutation
                 && (attempt.directDeliveryUncertain
                     || (attempt.encryptedRequest && attempt.resumingMutation))) {
-                throw connectError("operation_outcome_unknown", "The direct operation may have completed, but its encrypted grant changed before the response could be recovered. Refresh before making another change.", { operationOutcome: "unknown" });
+                throw connectError("operation_outcome_unknown", "The direct operation may have completed, but its encrypted grant changed before the response could be recovered. Refresh before making another change.", { operationOutcome: "unknown", details: { request_id: attempt.requestId } });
             }
             if (attempt.pendingMutation)
-                this.clearPendingMutation();
-            token = await this.refreshAuthorization();
+                this.clearPendingMutation(attempt.requestId);
+            token = await this.refreshAuthorization(options.signal);
             tryDirect = await this.shouldAttemptDirect(token);
             try {
-                attempt = await this.sendOperation(token, operation, input, tryDirect, options);
+                attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId);
             }
             catch (error) {
-                throw operationTransportError(error, options.signal, isMutation(operation, input) && this.pendingMutation() !== null, token.authority ? "hosted_provider_unavailable" : "relay_unavailable");
+                throw operationTransportError(error, options.signal, pendingRequestId !== undefined && this.storedPendingMutation(pendingRequestId) !== null
+                    ? pendingRequestId
+                    : undefined, token.authority ? "hosted_provider_unavailable" : "relay_unavailable");
             }
             response = attempt.response;
         }
         let body;
         try {
-            body = await response.json();
+            body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned a response that is not valid JSON.");
         }
         catch (cause) {
             if (attempt.pendingMutation)
-                throw unknownMutationOutcome(cause);
+                throw unknownMutationOutcome(attempt.requestId, cause);
             throw connectError("invalid_operation_response", "The collection authority returned a response that is not valid JSON.", { cause });
         }
         if (!response.ok) {
@@ -167,10 +202,10 @@ export class ConnectionTransport {
             if (attempt.pendingMutation
                 && (attempt.directDeliveryUncertain
                     || (attempt.encryptedRequest && attempt.resumingMutation))) {
-                throw unknownMutationOutcome(error);
+                throw unknownMutationOutcome(attempt.requestId, error);
             }
             if (attempt.pendingMutation && !attempt.directDeliveryUncertain) {
-                this.clearPendingMutation();
+                this.clearPendingMutation(attempt.requestId);
             }
             if (error.code === "direct_operation_rejected" && error.status === 403) {
                 this.invalidateRejectedAuthorization(token);
@@ -179,15 +214,24 @@ export class ConnectionTransport {
         }
         if (attempt.encryptedRequest) {
             const encryptedResponse = body?.envelope;
-            if (!encryptedResponse || !token.encryption || !token.grantId || !token.keyHandle) {
+            const pendingCrypto = attempt.pendingMutationRecord;
+            const responseEncryption = pendingCrypto?.encryption ?? token.encryption;
+            const responseGrantId = pendingCrypto?.grantId ?? token.grantId;
+            const responseApplicationId = pendingCrypto?.applicationId ?? token.clientId;
+            const responseKeyHandle = pendingCrypto?.keyHandle ?? token.keyHandle;
+            if (!encryptedResponse || !responseEncryption || !responseGrantId || !responseKeyHandle) {
                 if (attempt.pendingMutation)
-                    throw unknownMutationOutcome(new Error("Encrypted operation response was missing its envelope."));
+                    throw unknownMutationOutcome(attempt.requestId, new Error("Encrypted operation response was missing its envelope."));
                 throw connectError("invalid_encrypted_response", "The relay did not return an encrypted connector response.");
             }
             try {
-                const decrypted = await decryptRelayResponse(this.keyStore, token.keyHandle, { grantId: token.grantId, applicationId: token.clientId, encryption: token.encryption }, attempt.encryptedRequest, encryptedResponse);
+                const decrypted = await decryptRelayResponse(this.keyStore, responseKeyHandle, {
+                    grantId: responseGrantId,
+                    applicationId: responseApplicationId,
+                    encryption: responseEncryption
+                }, attempt.encryptedRequest, encryptedResponse);
                 if (attempt.pendingMutation)
-                    this.clearPendingMutation();
+                    this.clearPendingMutation(attempt.requestId);
                 if (!decrypted.ok)
                     throw serverConnectError(decrypted.problem.code === "unknown"
                         ? decrypted.problem.server_code
@@ -203,65 +247,79 @@ export class ConnectionTransport {
                     throw error;
                 if (error instanceof RelayCryptoError) {
                     if (attempt.pendingMutation)
-                        throw unknownMutationOutcome(error);
+                        throw unknownMutationOutcome(attempt.requestId, error);
                     throw serverConnectError(error.code, error.message);
                 }
                 throw error;
             }
         }
-        if (body?.protocol_version !== 1 || body?.request_id !== attempt.requestId) {
+        if (body?.protocol_version !== OPERATION_TRANSPORT_PROTOCOL_VERSION
+            || body?.request_id !== attempt.requestId) {
             if (attempt.pendingMutation)
-                throw unknownMutationOutcome(new Error("Operation response protocol or request ID did not match."));
+                throw unknownMutationOutcome(attempt.requestId, new Error("Operation response protocol or request ID did not match."));
             throw connectError("invalid_operation_response", "The collection authority returned a response for a different protocol request.");
         }
         if (body.ok === false) {
             if (!isConnectProblem(body.problem)) {
                 if (attempt.pendingMutation)
-                    throw unknownMutationOutcome(new Error("Operation rejection did not contain a canonical problem."));
+                    throw unknownMutationOutcome(attempt.requestId, new Error("Operation rejection did not contain a canonical problem."));
                 throw connectError("invalid_operation_response", "The collection authority returned an invalid operation problem.");
             }
             if (attempt.pendingMutation)
-                this.clearPendingMutation();
+                this.clearPendingMutation(attempt.requestId);
             throw new MdbaseConnectError(body.problem);
         }
         if (body.ok !== true || !("result" in body)) {
             if (attempt.pendingMutation)
-                throw unknownMutationOutcome(new Error("Successful operation response did not contain a result."));
+                throw unknownMutationOutcome(attempt.requestId, new Error("Successful operation response did not contain a result."));
             throw connectError("invalid_operation_response", "The collection authority returned an incomplete operation response.");
         }
         if (attempt.pendingMutation)
-            this.clearPendingMutation();
+            this.clearPendingMutation(attempt.requestId);
         return body.result;
     }
-    async performAuthoritySyncRequest(collectionId, replicaId, method, path, input) {
-        let token = await this.authorizedToken();
-        if (!token?.authority
-            || token.collectionId !== collectionId
-            || token.authority.replicaId !== replicaId) {
-            throw connectError("authority_authorization_changed", "Reconnect this collection authority before synchronizing.");
-        }
-        let response = await this.sendAuthoritySyncRequest(token, method, path, input);
-        if (response.status === 401 && token.refreshToken) {
-            token = await this.refreshAuthorization();
-            if (!token.authority
+    async performAuthoritySyncRequest(collectionId, replicaId, method, path, input, options = {}) {
+        return withCooperativeRequestBudget(options, this.timeouts.syncMs, async (budget) => {
+            let token = await this.authorizedToken({ signal: budget.signal, timeoutMs: null });
+            if (!token?.authority
                 || token.collectionId !== collectionId
                 || token.authority.replicaId !== replicaId) {
                 throw connectError("authority_authorization_changed", "Reconnect this collection authority before synchronizing.");
             }
-            response = await this.sendAuthoritySyncRequest(token, method, path, input);
-        }
-        const body = await response.json();
-        if (!response.ok)
-            throw apiError(body, "sync_failed", "Collection synchronization failed.", response.status);
-        return body;
+            try {
+                let response = await this.sendAuthoritySyncRequest(token, method, path, input, budget.signal);
+                if (response.status === 401 && token.refreshToken) {
+                    token = await this.refreshAuthorization(budget.signal);
+                    if (!token.authority
+                        || token.collectionId !== collectionId
+                        || token.authority.replicaId !== replicaId) {
+                        throw connectError("authority_authorization_changed", "Reconnect this collection authority before synchronizing.");
+                    }
+                    response = await this.sendAuthoritySyncRequest(token, method, path, input, budget.signal);
+                }
+                const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid synchronization response.");
+                if (!response.ok) {
+                    throw apiError(body, "sync_failed", "Collection synchronization failed.", response.status);
+                }
+                return body;
+            }
+            catch (error) {
+                const mutationRequestId = method === "POST" && path === "mutations"
+                    && input && typeof input === "object"
+                    && typeof input.mutation_id === "string"
+                    ? input.mutation_id
+                    : undefined;
+                throw operationTransportError(error, budget.signal, mutationRequestId, "hosted_provider_unavailable");
+            }
+        });
     }
-    async sendAuthoritySyncRequest(token, method, path, input) {
+    async sendAuthoritySyncRequest(token, method, path, input, signal) {
         if (!token.authority) {
             throw connectError("not_remote_authority", "This authorization has no remote authority endpoint.");
         }
         const url = `${token.authority.syncUrl}/${path}`;
         const body = input === undefined ? undefined : JSON.stringify(input);
-        const proof = await this.authorityProofHeaders(token, method, url, body, token.authority.accessToken);
+        const proof = await authorityProofHeaders(this.keyStore, token, method, url, body, token.authority.accessToken);
         return fetch(url, {
             method,
             headers: {
@@ -269,24 +327,24 @@ export class ConnectionTransport {
                 ...(input === undefined ? {} : { "content-type": "application/json" }),
                 ...proof
             },
-            ...(body === undefined ? {} : { body })
+            ...(body === undefined ? {} : { body }),
+            signal
         });
     }
-    async sendOperation(token, operation, input, tryDirect, options = {}) {
+    async sendOperation(token, operation, input, tryDirect, options = {}, pendingRequestId) {
         let body = input ?? {};
         let encryptedRequest;
         let pendingMutation = false;
         let resumingMutation = false;
-        let requestId = crypto.randomUUID();
+        let requestId = pendingRequestId ?? crypto.randomUUID();
         let pending = null;
         let inputFingerprint;
-        if (isMutation(operation, input)) {
-            inputFingerprint = await operationFingerprint(operation, input);
-            pending = parseStored(this.storage.getItem(this.pendingMutationKey()));
+        if (pendingRequestId !== undefined) {
+            pending = this.storedPendingMutation(pendingRequestId);
+            inputFingerprint = pending?.inputFingerprint
+                ?? await operationFingerprint(operation, input);
             if (pending) {
                 if (pending.collectionId !== token.collectionId
-                    || pending.grantId !== token.grantId
-                    || pending.keyId !== token.encryption?.key_id
                     || pending.operation !== operation
                     || pending.inputFingerprint !== inputFingerprint) {
                     throw connectError("pending_mutation_unresolved", "A previous write still has an unknown outcome. Retry that exact write before making another change.");
@@ -296,6 +354,13 @@ export class ConnectionTransport {
             }
             pendingMutation = true;
         }
+        const mutation = pending?.mutation ?? mutationOperationIdentifier(operation, input);
+        if (pending?.envelope && (token.authority || !token.encryption)) {
+            throw connectError("pending_mutation_unresolved", "The pending write requires its encrypted relay authority. Reconnect that authority before recovery.");
+        }
+        if (pending?.request && token.encryption && !token.authority) {
+            throw connectError("pending_mutation_unresolved", "The pending write belongs to a different authority transport. Reconnect that authority before recovery.");
+        }
         if (token.encryption && !token.authority) {
             if (!token.grantId || !token.keyHandle) {
                 throw connectError("missing_grant_key", "Reconnect this application to restore encrypted access.");
@@ -310,16 +375,20 @@ export class ConnectionTransport {
                     }
                     else {
                         encryptedRequest = await encryptRelayRequest(this.keyStore, token.keyHandle, { grantId: token.grantId, applicationId: token.clientId, encryption: token.encryption }, operation, input, requestId);
-                        this.storage.setItem(this.pendingMutationKey(), JSON.stringify({
+                        this.pendingMutationStore.store({
                             collectionId: token.collectionId,
                             ...(token.grantId ? { grantId: token.grantId } : {}),
                             keyId: token.encryption.key_id,
+                            keyHandle: token.keyHandle,
+                            applicationId: token.clientId,
+                            encryption: token.encryption,
                             operation,
+                            mutation: mutation,
                             inputFingerprint: inputFingerprint,
                             requestId,
                             envelope: encryptedRequest,
                             createdAt: Date.now()
-                        }));
+                        });
                     }
                 }
                 else {
@@ -334,21 +403,23 @@ export class ConnectionTransport {
             body = encryptedRequest;
         }
         else {
-            const request = {
-                protocol_version: 1,
+            const request = pending?.request ?? {
+                protocol_version: OPERATION_TRANSPORT_PROTOCOL_VERSION,
                 request_id: requestId,
                 input: body
             };
             body = request;
             if (pendingMutation && !pending) {
-                this.storage.setItem(this.pendingMutationKey(), JSON.stringify({
+                this.pendingMutationStore.store({
                     collectionId: token.collectionId,
                     ...(token.grantId ? { grantId: token.grantId } : {}),
                     operation,
+                    mutation: mutation,
                     inputFingerprint: inputFingerprint,
                     requestId,
+                    request,
                     createdAt: Date.now()
-                }));
+                });
             }
         }
         if (tryDirect && encryptedRequest && !token.authority) {
@@ -370,6 +441,7 @@ export class ConnectionTransport {
                         requestId,
                         encryptedRequest,
                         pendingMutation,
+                        ...(pendingMutation ? { pendingMutationRecord: pending ?? this.storedPendingMutation(requestId) ?? undefined } : {}),
                         resumingMutation
                     };
                 }
@@ -389,11 +461,11 @@ export class ConnectionTransport {
             try {
                 relayToken = token.expiresAt > Date.now() + 30_000
                     ? token
-                    : await this.refreshAuthorization();
+                    : await this.refreshAuthorization(options.signal);
             }
             catch (error) {
                 if (pendingMutation && (directDeliveryUncertain || resumingMutation))
-                    throw unknownMutationOutcome(error);
+                    throw unknownMutationOutcome(requestId, error);
                 throw error;
             }
             let response;
@@ -410,7 +482,7 @@ export class ConnectionTransport {
             }
             catch (error) {
                 if (pendingMutation && (directDeliveryUncertain || resumingMutation))
-                    throw unknownMutationOutcome(error);
+                    throw unknownMutationOutcome(requestId, error);
                 throw error;
             }
             if (response.ok)
@@ -421,6 +493,7 @@ export class ConnectionTransport {
                 encryptedRequest,
                 directDeliveryUncertain,
                 pendingMutation,
+                ...(pendingMutation ? { pendingMutationRecord: pending ?? this.storedPendingMutation(requestId) ?? undefined } : {}),
                 resumingMutation
             };
         }
@@ -429,7 +502,7 @@ export class ConnectionTransport {
             : `${this.serverUrl}/v1/authorities/${encodeURIComponent(token.collectionId)}/operations/${operation}`;
         const operationBody = JSON.stringify(body);
         const proof = token.authority
-            ? await this.authorityProofHeaders(token, "POST", operationUrl, operationBody, token.authority.accessToken)
+            ? await authorityProofHeaders(this.keyStore, token, "POST", operationUrl, operationBody, token.authority.accessToken)
             : {};
         const response = await fetch(operationUrl, {
             method: "POST",
@@ -443,7 +516,14 @@ export class ConnectionTransport {
         });
         if (response.ok)
             this.setRoute(token.authority ? "remote" : "relay");
-        return { response, requestId, encryptedRequest, pendingMutation, resumingMutation };
+        return {
+            response,
+            requestId,
+            encryptedRequest,
+            pendingMutation,
+            ...(pendingMutation ? { pendingMutationRecord: pending ?? this.storedPendingMutation(requestId) ?? undefined } : {}),
+            resumingMutation
+        };
     }
     directCapable(token) {
         if (!token || token.authority || !token.encryption || !token.grantId || !token.keyHandle)
@@ -463,7 +543,7 @@ export class ConnectionTransport {
     directEligible(token) {
         return token !== null
             && this.directCapable(token)
-            && this.storage.getItem(this.directPreferenceKey()) !== "disabled";
+            && this.storage.getItem(this.internals.directPreferenceKey()) !== "disabled";
     }
     async shouldAttemptDirect(token) {
         if (!this.directEligible(token))
@@ -478,25 +558,26 @@ export class ConnectionTransport {
             return false;
         }
         if ((permission === "prompt" || permission === null)
-            && this.storage.getItem(this.directPreferenceKey()) !== "enabled") {
+            && this.storage.getItem(this.internals.directPreferenceKey()) !== "enabled") {
             this.setDirectStatus("permission_required");
             return false;
         }
         this.setDirectStatus("checking");
         return true;
     }
-    async probeDirectAccess() {
+    async probeDirectAccess(signal) {
         this.setDirectStatus("checking");
         try {
             const response = await fetch(`${this.loopbackUrl}/v1/ready`, loopbackRequest({
                 method: "GET",
-                cache: "no-store"
+                cache: "no-store",
+                signal
             }));
-            const body = await response.json().catch(() => null);
+            const body = await decodeJsonResponse(response, "invalid_operation_response", "The connector returned an invalid readiness response.").catch(() => null);
             if (response.ok
                 && body?.service === "mdbase-connect"
                 && body?.loopback_protocol_version === 1
-                && body?.encrypted_protocol_version === 1) {
+                && body?.operation_transport_protocol_version === OPERATION_TRANSPORT_PROTOCOL_VERSION) {
                 this.markDirectAvailable();
                 return "available";
             }
@@ -536,7 +617,7 @@ export class ConnectionTransport {
         this.onChange();
     }
     invalidateRejectedAuthorization(rejected) {
-        const current = parseStored(this.storage.getItem(this.tokenKey()));
+        const current = parseStored(this.storage.getItem(this.internals.tokenKey(this.collectionId)));
         if (!current || !sameAuthorization(current, rejected))
             return;
         this.internals.removeToken(this.collectionId, current.keyHandle);
@@ -545,73 +626,15 @@ export class ConnectionTransport {
         this.emitConnection();
     }
     currentToken() {
-        const stored = this.storage.getItem(this.tokenKey());
-        const token = parseStored(stored);
-        const invalidate = (keyHandle) => {
-            this.internals.removeToken(this.collectionId, typeof keyHandle === "string" ? keyHandle : undefined, "invalid_stored_grant");
-            return null;
-        };
-        if (!token) {
-            if (stored)
-                invalidate();
-            return null;
-        }
-        if (token.version !== 1
-            || typeof token.accessToken !== "string"
-            || token.accessToken.length === 0
-            || typeof token.clientId !== "string"
-            || token.clientId.length === 0
-            || token.collectionId !== this.collectionId
-            || typeof token.collectionName !== "string"
-            || token.collectionName.length === 0
-            || !Array.isArray(token.operations)
-            || token.operations.some((operation) => typeof operation !== "string")
-            || typeof token.expiresAt !== "number"
-            || !Number.isFinite(token.expiresAt)
-            || (token.refreshToken !== undefined
-                && (typeof token.refreshToken !== "string"
-                    || token.refreshToken.length === 0))
-            || (token.refreshExpiresAt !== undefined
-                && (typeof token.refreshExpiresAt !== "number"
-                    || !Number.isFinite(token.refreshExpiresAt))))
-            return invalidate(token.keyHandle);
-        if (!parseGrantScope(token.scope)) {
-            return invalidate(token.keyHandle);
-        }
-        if (token.fileCapability && !validFileCapability(token.fileCapability)) {
-            return invalidate(token.keyHandle);
-        }
-        if (token.authority
-            && !validStoredAuthority(token.authority, token.collectionId)) {
-            return invalidate(token.keyHandle);
-        }
-        if (this.internals.relayEncryption === "required") {
-            if (token.authority) {
-                if (!token.keyHandle || !token.authority.proofPublicKey) {
-                    return invalidate(token.keyHandle);
-                }
-            }
-            else {
-                if (!token.grantId
-                    || !token.keyHandle
-                    || !validStoredEncryption(token.encryption, token.collectionId)) {
-                    return invalidate(token.keyHandle);
-                }
-            }
-        }
-        if (token.expiresAt <= Date.now()
-            && (!token.refreshToken || (token.refreshExpiresAt ?? 0) <= Date.now())) {
-            // The cloud bearer and the local grant proof have separate lifetimes. Keep an
-            // encrypted local grant usable while the connector still recognizes it; relay
-            // use will require reauthorization, and revocation remains enforced locally.
-            if (this.directCapable(token))
-                return token;
-            this.internals.removeToken(this.collectionId, token.keyHandle);
-            return null;
-        }
-        return token;
+        return readStoredToken({
+            stored: this.storage.getItem(this.internals.tokenKey(this.collectionId)),
+            collectionId: this.collectionId,
+            relayEncryption: this.internals.relayEncryption,
+            invalidate: (keyHandle) => this.internals.removeToken(this.collectionId, keyHandle, "invalid_stored_grant"),
+            directCapable: (token) => this.directCapable(token)
+        });
     }
-    async authorizedToken() {
+    async authorizedToken(options = {}) {
         const token = this.currentToken();
         if (!token)
             return null;
@@ -624,17 +647,17 @@ export class ConnectionTransport {
             this.internals.removeToken(this.collectionId, token.keyHandle);
             return null;
         }
-        return this.refreshAuthorization();
+        return this.refreshAuthorization(options.signal);
     }
-    refreshAuthorization() {
+    refreshAuthorization(signal) {
         if (this.refreshPromise)
             return this.refreshPromise;
-        this.refreshPromise = this.performRefresh().finally(() => {
+        this.refreshPromise = this.performRefresh(signal).finally(() => {
             this.refreshPromise = null;
         });
         return this.refreshPromise;
     }
-    async performRefresh() {
+    async performRefresh(signal) {
         const current = this.currentToken();
         if (!current?.refreshToken) {
             throw connectError("not_authorized", "Reconnect this application to continue.");
@@ -650,7 +673,7 @@ export class ConnectionTransport {
             client_id: current.clientId
         }).toString();
         const proof = current.authority
-            ? await this.authorityProofHeaders(current, "POST", refreshUrl, refreshBody, current.refreshToken)
+            ? await authorityProofHeaders(this.keyStore, current, "POST", refreshUrl, refreshBody, current.refreshToken)
             : {};
         const response = await fetch(refreshUrl, {
             method: "POST",
@@ -658,9 +681,10 @@ export class ConnectionTransport {
                 "content-type": "application/x-www-form-urlencoded",
                 ...proof
             },
-            body: refreshBody
+            body: refreshBody,
+            signal
         });
-        const body = await response.json();
+        const body = await decodeJsonResponse(response, "invalid_token_response", "The authorization service returned an invalid token response.");
         if (!response.ok) {
             const latest = this.currentToken();
             if (latest?.refreshToken && latest.refreshToken !== attemptedRefreshToken) {
@@ -676,28 +700,6 @@ export class ConnectionTransport {
         }
         return this.storeTokenResponse(body, current.clientId, current.keyHandle);
     }
-    async authorityProofHeaders(token, method, url, body, credential) {
-        if (!token.authority?.proofPublicKey)
-            return {};
-        if (!token.keyHandle) {
-            throw connectError("missing_grant_key", "Reconnect this application to restore remote authority request signing.");
-        }
-        try {
-            const target = new URL(url);
-            return await signAuthorityRequest(this.keyStore, token.keyHandle, token.authority.proofPublicKey, {
-                method,
-                target: `${target.pathname}${target.search}`,
-                body,
-                credential
-            });
-        }
-        catch (error) {
-            if (error instanceof RelayCryptoError) {
-                throw serverConnectError(error.code, error.message);
-            }
-            throw error;
-        }
-    }
     storeTokenResponse(body, clientId, keyHandle) {
         if (body.collection_id !== this.collectionId) {
             throw connectError("collection_mismatch", "The refreshed authorization belongs to a different collection.");
@@ -710,19 +712,17 @@ export class ConnectionTransport {
         this.emitConnection();
         return token;
     }
-    tokenKey() {
-        return this.internals.tokenKey(this.collectionId);
-    }
-    notificationKey(transport = "web_push") {
-        return this.internals.notificationKey(this.collectionId, transport);
+    storedPendingMutations() {
+        return this.pendingMutationStore.list(this.currentToken()?.collectionId ?? null);
     }
-    pendingMutationKey() {
-        return this.internals.pendingMutationKey(this.collectionId);
+    storedPendingMutation(requestId) {
+        return this.pendingMutationStore.find(this.currentToken()?.collectionId ?? null, requestId);
     }
-    clearPendingMutation() {
-        this.storage.removeItem(this.pendingMutationKey());
-    }
-    directPreferenceKey() {
-        return this.internals.directPreferenceKey();
+    clearPendingMutation(requestId) {
+        const pending = this.pendingMutationStore.take(requestId);
+        const currentKeyHandle = this.currentToken()?.keyHandle;
+        if (pending?.keyHandle && pending.keyHandle !== currentKeyHandle) {
+            void this.keyStore.delete(pending.keyHandle).catch(() => undefined);
+        }
     }
 }