@mdbase-dev/connect 0.1.0-beta.83 → 0.1.0-beta.85

package/dist/browser/mdbase-connect.min.js.sha384

@@ -1 +1 @@
-sha384-yqwzqr0WMJUcmiTnwJyLNuevsaXVJcM5YLftkDrVxhNXp+39bpKQFo/GFL7iXP8T
+sha384-xB4T3sGGjWDwJkOtsrNfSBOhYxSGOGpRstFke++cfSX3EivOO+d2+QWNBH5yh0qc

package/dist/connect.d.ts

@@ -25,6 +25,7 @@ export declare class MdbaseConnectInternals<Frontmatter extends JsonObject> {
     private application;
     private manifestPromise;
     private readonly completionPromises;
+    private readonly grantKeyLeases;
     private readonly connectionCache;
     private readonly listeners;
     private readonly invalidatedConnections;
@@ -39,11 +40,11 @@ export declare class MdbaseConnectInternals<Frontmatter extends JsonObject> {
     private authorizeWeb;
     private authorizePortable;
     completeAuthorization(callbackUrl: string, options?: ConnectRequestOptions): Promise<MdbaseAuthorizationResult<Frontmatter>>;
-    private completeAuthorizationWithinBudget;
     private performAuthorizationCompletion;
     connections(): MdbaseConnectionInfo[];
     connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
     unavailableReason(collectionId: string): MdbaseUnavailableReason | null;
+    connectionApplicationId(collectionId: string): string | null;
     onConnectionsChange(listener: (connections: MdbaseConnectionInfo[]) => void): () => void;
     storeTokenResponse(body: any, clientId: string, keyHandle?: string): StoredToken;
     forgetConnectorIdentity(connectorId: string): void;
@@ -51,6 +52,8 @@ export declare class MdbaseConnectInternals<Frontmatter extends JsonObject> {
     private connectorPinKey;
     private loadApplicationIdentity;
     removeToken(collectionId: string, keyHandle?: string, reason?: MdbaseUnavailableReason, discardPending?: boolean): void;
+    acquireGrantKeyLease(collectionId: string, keyHandle: string, signal?: AbortSignal): Promise<() => void>;
+    deleteGrantKeyWhenUnused(collectionId: string, keyHandle: string): void;
     tokenKey(collectionId: string): string;
     pendingMutationKey(collectionId: string): string;
     notificationKey(collectionId: string, transport?: "web_push" | "fcm"): string;

package/dist/connect.js

@@ -1,5 +1,6 @@
 import { APPLICATION_AUTHORIZATION_PROTOCOL_VERSION, authorizationContractRequirements, DEFAULT_LOOPBACK_PORT, GRANT_ENCRYPTION_PROTOCOL_VERSION, RELAY_ENCRYPTION_SUITE } from "@mdbase-dev/connect-protocol";
 import { abortableDelay } from "./async.js";
+import { authorizationCallbackState } from "./authorization-url.js";
 import { randomBase64Url } from "./base64.js";
 import { ApplicationIdentityStoreError, IndexedDbApplicationIdentityStore, MemoryApplicationIdentityStore, applicationIdentity, applicationInstallationId, signApplicationAuthorization } from "./application-identity.js";
 import { MdbaseConnection } from "./connection.js";
@@ -10,10 +11,13 @@ import { connectError, serverConnectError } from "./errors.js";
 import { DEFAULT_OPERATIONS } from "./internal-types.js";
 import { prepareAuthorizationWindow, publishPopupAuthorizationCompletion, waitForPopupAuthorization } from "./popup-authorization.js";
 import { uniqueOperations } from "./operation-helpers.js";
-import { pendingMutationsUseKey, pendingRecoveryTransports, removePendingMutations } from "./pending-recovery-transports.js";
+import { pendingRecoveryTransports, removePendingMutations } from "./pending-recovery-transports.js";
+import { GrantKeyLeaseRegistry } from "./grant-key-leases.js";
 import { resolveConnectTimeouts, withRequestBudget } from "./request-budget.js";
 import { MemoryStorage, apiError, applicationStorageOrigin, canonicalLoopbackUrl, collectionIdFromTokenKey, connectFetch, createPkce, defaultManifestSource, defaultRedirectUri, defaultStorage, decodeJsonResponse, isOpaquePortableManifest, manifestStorageFingerprint, oauthErrorCode, parseDeviceAuthorization, parseStored, stripTrailingSlash, validAuthorityTokenResponse } from "./runtime-utils.js";
 import { storedTokenFromResponse } from "./token-response.js";
+import { deleteUnusedGrantKey, planRetiredGrantKeys, storedTokenKeyHandles } from "./retired-grant-keys.js";
+import { SharedOperationMap } from "./shared-operation.js";
 export class MdbaseConnectInternals {
     serverUrl;
     manifest;
@@ -30,7 +34,8 @@ export class MdbaseConnectInternals {
     credentialStorage;
     application = null;
     manifestPromise = null;
-    completionPromises = new Map();
+    completionPromises = new SharedOperationMap();
+    grantKeyLeases;
     connectionCache = new Map();
     listeners = new Set();
     invalidatedConnections = new Map();
@@ -61,6 +66,7 @@ export class MdbaseConnectInternals {
         this.loopbackUrl = canonicalLoopbackUrl(String(options.loopbackUrl ?? `http://127.0.0.1:${DEFAULT_LOOPBACK_PORT}`));
         this.navigate = options.navigate;
         this.timeouts = resolveConnectTimeouts(options.timeouts);
+        this.grantKeyLeases = new GrantKeyLeaseRegistry(this.storagePrefix(), (collectionId, keyHandle) => this.deleteGrantKeyWhenUnused(collectionId, keyHandle));
         if (typeof window !== "undefined" && this.storage === window.localStorage) {
             window.addEventListener("storage", (event) => {
                 if (event.storageArea !== this.storage || !event.key?.startsWith(this.storagePrefix()))
@@ -479,32 +485,20 @@ export class MdbaseConnectInternals {
         }
     }
     completeAuthorization(callbackUrl, options = {}) {
-        return withRequestBudget(options, this.timeouts.requestMs, (budget) => this.completeAuthorizationWithinBudget(callbackUrl, budget.signal));
-    }
-    completeAuthorizationWithinBudget(callbackUrl, signal) {
-        const state = new URL(callbackUrl).searchParams.get("state");
+        const state = authorizationCallbackState(callbackUrl);
         if (!state) {
             return Promise.reject(connectError("invalid_callback", "Authorization callback is missing its state."));
         }
         const pending = parseStored(this.storage.getItem(this.pendingKey(state)));
         const popupAttempt = pending?.presentation === "popup";
-        const existing = this.completionPromises.get(state);
-        if (existing)
-            return existing;
-        const completion = publishPopupAuthorizationCompletion({
+        return this.completionPromises.run(state, options, this.timeouts.requestMs, (signal) => publishPopupAuthorizationCompletion({
             storage: this.storage,
             storagePrefix: this.storagePrefix(),
             state,
             pending,
             popupAttempt,
             completion: this.performAuthorizationCompletion(callbackUrl, state, signal)
-        });
-        const shared = completion.finally(() => {
-            if (this.completionPromises.get(state) === shared)
-                this.completionPromises.delete(state);
-        });
-        this.completionPromises.set(state, shared);
-        return shared;
+        }));
     }
     async performAuthorizationCompletion(callbackUrl, state, signal) {
         const callback = new URL(callbackUrl);
@@ -594,6 +588,13 @@ export class MdbaseConnectInternals {
     unavailableReason(collectionId) {
         return this.invalidatedConnections.get(collectionId) ?? null;
     }
+    connectionApplicationId(collectionId) {
+        // Null deliberately means the application must reauthorize.
+        if (!this.connection(collectionId))
+            return null;
+        const token = parseStored(this.storage.getItem(this.tokenKey(collectionId)));
+        return typeof token?.clientId === "string" && token.clientId.length > 0 ? token.clientId : null;
+    }
     onConnectionsChange(listener) {
         this.listeners.add(listener);
         listener(this.connections());
@@ -605,18 +606,19 @@ export class MdbaseConnectInternals {
             throw connectError("invalid_token_response", "Authorization returned no collection ID.");
         }
         const previous = parseStored(this.storage.getItem(this.tokenKey(collectionId)));
+        const retirement = planRetiredGrantKeys(this.storage, this.pendingMutationKey(collectionId), previous, keyHandle, this.grantKeyLeases.handles(collectionId), this.grantKeyLeases.retainAutomaticallyRetiredKeys);
         const token = storedTokenFromResponse({
             body,
             clientId,
             keyHandle,
             previous,
+            retiredKeyHandles: retirement.retained,
             defaultApplicationOrigin: this.defaultApplicationOrigin(),
             pinConnectorIdentity: (connectorId, publicKey) => this.pinConnectorIdentity(connectorId, publicKey)
         });
-        if (previous?.keyHandle && previous.keyHandle !== keyHandle) {
-            void this.keyStore.delete(previous.keyHandle).catch(() => undefined);
-        }
         this.storage.setItem(this.tokenKey(collectionId), JSON.stringify(token));
+        for (const handle of retirement.disposable)
+            this.deleteGrantKeyWhenUnused(collectionId, handle);
         addConnectionId(this.storage, this.storagePrefix(), collectionId);
         this.invalidatedConnections.delete(collectionId);
         this.connectionCache.delete(collectionId);
@@ -650,14 +652,13 @@ export class MdbaseConnectInternals {
     }
     removeToken(collectionId, keyHandle, reason = "authorization_lost", discardPending = false) {
         this.invalidatedConnections.set(collectionId, reason);
-        if (keyHandle && (discardPending || !pendingMutationsUseKey(this.storage, this.pendingMutationKey(collectionId), keyHandle))) {
-            void this.keyStore.delete(keyHandle).catch(() => undefined);
-        }
+        const stored = parseStored(this.storage.getItem(this.tokenKey(collectionId)));
+        const handles = storedTokenKeyHandles(stored, keyHandle);
         this.storage.removeItem(this.tokenKey(collectionId));
         if (discardPending)
-            removePendingMutations(this.storage, this.pendingMutationKey(collectionId), (pendingKeyHandle) => {
-                void this.keyStore.delete(pendingKeyHandle).catch(() => undefined);
-            });
+            removePendingMutations(this.storage, this.pendingMutationKey(collectionId), (pendingKeyHandle) => handles.add(pendingKeyHandle));
+        for (const handle of handles)
+            this.deleteGrantKeyWhenUnused(collectionId, handle);
         for (const transport of ["web_push", "fcm"]) {
             this.storage.removeItem(this.notificationKey(collectionId, transport));
         }
@@ -665,6 +666,12 @@ export class MdbaseConnectInternals {
         this.connectionCache.delete(collectionId);
         this.emitConnections();
     }
+    acquireGrantKeyLease(collectionId, keyHandle, signal) {
+        return this.grantKeyLeases.acquire(collectionId, keyHandle, signal);
+    }
+    deleteGrantKeyWhenUnused(collectionId, keyHandle) {
+        this.grantKeyLeases.deleteExclusive(collectionId, keyHandle, () => deleteUnusedGrantKey(this.storage, this.keyStore, this.pendingMutationKey(collectionId), this.tokenKey(collectionId), keyHandle));
+    }
     tokenKey(collectionId) {
         return `${this.storagePrefix()}:token:${collectionId}`;
     }

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

@@ -6,6 +6,8 @@ export interface ConnectionFileTransportOptions {
     keyStore: GrantKeyStore;
     serverUrl: string;
     loopbackUrl: string;
+    collectionId: string;
+    currentToken(): StoredToken | null;
     authorizedToken(signal?: AbortSignal): Promise<StoredToken | null>;
     refreshAuthorization(signal?: AbortSignal): Promise<StoredToken>;
     shouldAttemptDirect(token: StoredToken): Promise<boolean>;
@@ -13,6 +15,7 @@ export interface ConnectionFileTransportOptions {
     onDirectUnavailable(): void;
     onRelayAvailable(): void;
     authorityProofHeaders: ProofHeaders;
+    acquireGrantKeyLease(collectionId: string, keyHandle: string, signal?: AbortSignal): Promise<() => void>;
 }
 /**
  * Owns every transport concern specific to files. ConnectionTransport only

package/dist/connection-file-transport.js

@@ -1,5 +1,6 @@
 import { connectError } from "./errors.js";
 import { performHostedFilePartRequest, performHostedFileRequest } from "./hosted-file-request.js";
+import { GrantKeyLeaseSet, retainCurrentGrantToken } from "./grant-key-leases.js";
 import { LocalFileTransport } from "./local-file-transport.js";
 /**
  * Owns every transport concern specific to files. ConnectionTransport only
@@ -13,30 +14,72 @@ export class ConnectionFileTransport {
         this.local = new LocalFileTransport(options);
     }
     async control(method, path = "", input, signal) {
-        const token = await this.requireFileToken(signal);
-        if (!token.authority) {
-            return this.local.control(token, method, path, input, signal);
+        const leased = await this.requireFileToken(signal);
+        const token = leased.token;
+        try {
+            if (!token.authority) {
+                return await this.local.control(token, method, path, input, signal);
+            }
+            return await performHostedFileRequest(token, method, path, input, signal, this.options.refreshAuthorization, this.options.authorityProofHeaders, leased.retain);
+        }
+        finally {
+            leased.release();
         }
-        return performHostedFileRequest(token, method, path, input, signal, this.options.refreshAuthorization, this.options.authorityProofHeaders);
     }
-    uploadChunk(session, chunkIndex, bytes, signal) {
-        return this.local.uploadChunk(session, chunkIndex, bytes, signal);
+    async uploadChunk(session, chunkIndex, bytes, signal) {
+        const leased = await this.requireFileToken(signal);
+        try {
+            return await this.local.uploadChunk(session, chunkIndex, bytes, signal, leased.token);
+        }
+        finally {
+            leased.release();
+        }
     }
-    downloadChunk(session, chunkIndex, signal) {
-        return this.local.downloadChunk(session, chunkIndex, signal);
+    async downloadChunk(session, chunkIndex, signal) {
+        const leased = await this.requireFileToken(signal);
+        try {
+            return await this.local.downloadChunk(session, chunkIndex, signal, leased.token);
+        }
+        finally {
+            leased.release();
+        }
     }
     async downloadHostedPart(session, partIndex, expectedLength, signal) {
-        const token = await this.requireFileToken(signal);
-        if (!token.authority) {
-            throw connectError("not_remote_authority", "Hosted file delivery requires a remote authority endpoint.");
+        const leased = await this.requireFileToken(signal);
+        const token = leased.token;
+        try {
+            if (!token.authority) {
+                throw connectError("not_remote_authority", "Hosted file delivery requires a remote authority endpoint.");
+            }
+            return await performHostedFilePartRequest(token, `downloads/${encodeURIComponent(session.transfer_id)}/parts/${partIndex}`, expectedLength, signal, this.options.refreshAuthorization, this.options.authorityProofHeaders, leased.retain);
+        }
+        finally {
+            leased.release();
         }
-        return performHostedFilePartRequest(token, `downloads/${encodeURIComponent(session.transfer_id)}/parts/${partIndex}`, expectedLength, signal, this.options.refreshAuthorization, this.options.authorityProofHeaders);
     }
     async requireFileToken(signal) {
-        const token = await this.options.authorizedToken(signal);
-        if (!token?.fileCapability) {
-            throw connectError("not_authorized", "This connection has no file capability.");
+        const leases = new GrantKeyLeaseSet(this.options.collectionId, this.options.acquireGrantKeyLease);
+        try {
+            await retainCurrentGrantToken(this.options.currentToken, leases, signal);
+            await this.options.authorizedToken(signal);
+            const token = await retainCurrentGrantToken(this.options.currentToken, leases, signal);
+            if (!token?.fileCapability) {
+                throw connectError("not_authorized", "This connection has no file capability.");
+            }
+            return {
+                token,
+                retain: async (_refreshed) => {
+                    const current = await retainCurrentGrantToken(this.options.currentToken, leases, signal);
+                    if (current)
+                        return current;
+                    throw connectError("not_authorized", "Reconnect this application to continue.");
+                },
+                release: () => leases.release()
+            };
+        }
+        catch (error) {
+            leases.release();
+            throw error;
         }
-        return token;
     }
 }

package/dist/connection-transport-internals.d.ts

@@ -5,6 +5,8 @@ export interface ConnectionTransportInternals {
     readonly relayEncryption: "required" | "disabled";
     removeToken(collectionId: string, keyHandle?: string, reason?: "not_authorized" | "authorization_lost" | "invalid_stored_grant", discardPending?: boolean): void;
     storeTokenResponse(body: any, clientId: string, keyHandle?: string): StoredToken;
+    acquireGrantKeyLease(collectionId: string, keyHandle: string, signal?: AbortSignal): Promise<() => void>;
+    deleteGrantKeyWhenUnused(collectionId: string, keyHandle: string): void;
     tokenKey(collectionId: string): string;
     pendingMutationKey(collectionId: string): string;
     directPreferenceKey(): string;

package/dist/connection-transport.d.ts

@@ -17,7 +17,7 @@ export declare class ConnectionTransport {
     private readonly timeouts;
     private readonly pendingMutationStore;
     readonly files: ConnectionFileTransport;
-    private refreshPromise;
+    private readonly refreshOperations;
     private directStatus;
     private currentRoute;
     private directFailures;
@@ -38,6 +38,7 @@ export declare class ConnectionTransport {
     recoverPendingMutation<Result>(requestId: string, options?: ConnectRequestOptions): Promise<Result>;
     performOperation<Result>(operation: CollectionOperation, input: unknown, options?: ConnectRequestOptions): Promise<Result>;
     private performOperationWithinBudget;
+    private performLeasedOperation;
     performAuthoritySyncRequest<Result>(collectionId: string, replicaId: string, method: "GET" | "POST", path: string, input?: unknown, options?: ConnectRequestOptions): Promise<Result>;
     private sendOperation;
     private directCapable;
@@ -59,4 +60,5 @@ export declare class ConnectionTransport {
     private storedPendingMutations;
     private storedPendingMutation;
     private clearPendingMutation;
+    private grantKeyLeases;
 }

package/dist/connection-transport.js

@@ -3,15 +3,19 @@ import { decryptRelayResponse, encryptRelayRequest, RelayCryptoError } from "./c
 import { MdbaseConnectError, connectError, serverConnectError } from "./errors.js";
 import { ConnectionFileTransport } from "./connection-file-transport.js";
 import { authorityProofHeaders } from "./authority-proof.js";
+import { performAuthorizationRefresh } from "./authorization-refresh.js";
 import { PendingMutationStore } from "./pending-mutation-store.js";
 import { directFallbackStatus, encryptedOperationError, fetchOperationRequest, isMutation, localNetworkPermission, loopbackRequest, operationFingerprint, operationTransportError, sameAuthorization, throwIfCancelled, unknownMutationOutcome, withOperationDeadline } from "./operation-helpers.js";
-import { apiError, decodeJsonResponse, oauthErrorCode, parseStored, } from "./runtime-utils.js";
+import { apiError, decodeJsonResponse, parseStored, } from "./runtime-utils.js";
 import { readStoredToken } from "./stored-token.js";
 import { requestOptionsWithinBudget, withCooperativeRequestBudget, withRequestBudget } from "./request-budget.js";
 import { sendAuthoritySyncRequest } from "./authority-sync-request.js";
 import { freshEncryptedRequest } from "./fresh-encrypted-request.js";
+import { GrantKeyLeaseSet, retainCurrentGrantToken } from "./grant-key-leases.js";
+import { SharedOperationMap } from "./shared-operation.js";
 import { isExplicitConnectorBusyResponse, retryExplicitConnectorBusy } from "./transient-retry.js";
 import { probeLoopbackAccess, tokenSupportsDirectAccess } from "./direct-access.js";
+import { decodeHostedOperationResponse } from "./hosted-operation-response.js";
 export class ConnectionTransport {
     serverUrl;
     storage;
@@ -24,7 +28,7 @@ export class ConnectionTransport {
     timeouts;
     pendingMutationStore;
     files;
-    refreshPromise = null;
+    refreshOperations = new SharedOperationMap();
     directStatus;
     currentRoute = "relay";
     directFailures = 0;
@@ -44,8 +48,10 @@ export class ConnectionTransport {
             keyStore: this.keyStore,
             serverUrl: this.serverUrl,
             loopbackUrl: this.loopbackUrl,
+            collectionId: this.collectionId,
+            currentToken: () => this.currentToken(),
             authorizedToken: (signal) => this.authorizedToken({ signal, timeoutMs: null }),
-            refreshAuthorization: (signal) => this.refreshAuthorization(signal),
+            refreshAuthorization: (signal) => this.refreshAuthorization({ signal, timeoutMs: null }),
             shouldAttemptDirect: (token) => this.shouldAttemptDirect(token),
             onDirectAvailable: () => {
                 this.markDirectAvailable();
@@ -53,6 +59,7 @@ export class ConnectionTransport {
             },
             onDirectUnavailable: () => this.markDirectUnavailable(),
             onRelayAvailable: () => this.setRoute("relay"),
+            acquireGrantKeyLease: (collectionId, keyHandle, signal) => this.internals.acquireGrantKeyLease(collectionId, keyHandle, signal),
             authorityProofHeaders: (token, method, url, body, credential) => authorityProofHeaders(this.keyStore, token, method, url, body, credential)
         });
         this.directStatus = this.directAccessMode === "disabled"
@@ -131,9 +138,19 @@ export class ConnectionTransport {
     }
     async performOperationWithinBudget(operation, input, options, storedPending, freshReadRetried = false, connectorBusyRetries = 0, knownRejectedMutationRetry = false) {
         throwIfCancelled(options.signal);
-        let token = this.currentToken();
-        if (!token)
-            throw connectError("not_authorized", "Connect this application before accessing a collection.");
+        const leases = this.grantKeyLeases();
+        try {
+            const token = await retainCurrentGrantToken(() => this.currentToken(), leases, options.signal);
+            if (!token)
+                throw connectError("not_authorized", "Connect this application before accessing a collection.");
+            await leases.retain(storedPending?.keyHandle, options.signal);
+            return await this.performLeasedOperation(token, operation, input, options, leases, storedPending, freshReadRetried, connectorBusyRetries, knownRejectedMutationRetry);
+        }
+        finally {
+            leases.release();
+        }
+    }
+    async performLeasedOperation(token, operation, input, options, leases, storedPending, freshReadRetried = false, connectorBusyRetries = 0, knownRejectedMutationRetry = false) {
         if (!token.operations.includes(operation)) {
             throw connectError("insufficient_access", `This connection does not allow ${operation}.`, {
                 details: {
@@ -145,15 +162,19 @@ export class ConnectionTransport {
         }
         let tryDirect = await this.shouldAttemptDirect(token);
         if (!tryDirect) {
-            token = await this.authorizedToken({ signal: options.signal, timeoutMs: null });
-            if (!token)
+            const authorized = await this.authorizedToken({ signal: options.signal, timeoutMs: null });
+            if (!authorized)
+                throw connectError("not_authorized", "Reconnect this application to continue.");
+            const current = await retainCurrentGrantToken(() => this.currentToken(), leases, options.signal);
+            if (!current)
                 throw connectError("not_authorized", "Reconnect this application to continue.");
+            token = current;
         }
         const pendingRequestId = storedPending?.requestId
             ?? (isMutation(operation, input) ? crypto.randomUUID() : undefined);
         let attempt;
         try {
-            attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId, knownRejectedMutationRetry);
+            attempt = await this.sendOperation(token, operation, input, tryDirect, leases, options, pendingRequestId, knownRejectedMutationRetry);
         }
         catch (error) {
             throw operationTransportError(error, options.signal, pendingRequestId !== undefined && this.storedPendingMutation(pendingRequestId) !== null
@@ -171,10 +192,14 @@ export class ConnectionTransport {
             }
             if (attempt.pendingMutation)
                 this.clearPendingMutation(attempt.requestId);
-            token = await this.refreshAuthorization(options.signal);
+            token = await this.refreshAuthorization({ signal: options.signal, timeoutMs: null });
+            const current = await retainCurrentGrantToken(() => this.currentToken(), leases, options.signal);
+            if (!current)
+                throw connectError("not_authorized", "Reconnect this application to continue.");
+            token = current;
             tryDirect = await this.shouldAttemptDirect(token);
             try {
-                attempt = await this.sendOperation(token, operation, input, tryDirect, options, pendingRequestId, knownRejectedMutationRetry);
+                attempt = await this.sendOperation(token, operation, input, tryDirect, leases, options, pendingRequestId, knownRejectedMutationRetry);
             }
             catch (error) {
                 throw operationTransportError(error, options.signal, pendingRequestId !== undefined && this.storedPendingMutation(pendingRequestId) !== null
@@ -192,17 +217,19 @@ export class ConnectionTransport {
             clearPending: (requestId) => this.clearPendingMutation(requestId),
             retry: (pending, knownRejected) => this.performOperationWithinBudget(operation, input, options, pending, freshReadRetried, connectorBusyRetries + 1, knownRejected)
         });
-        let body;
+        let decoded;
         try {
-            body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned a response that is not valid JSON.");
+            decoded = await decodeHostedOperationResponse(response, token.authority !== undefined);
         }
         catch (cause) {
             if (attempt.pendingMutation)
                 throw unknownMutationOutcome(attempt.requestId, cause);
-            throw connectError("invalid_operation_response", "The collection authority returned a response that is not valid JSON.", { cause });
+            throw cause;
         }
+        const body = decoded.body;
         if (!response.ok) {
-            const error = apiError(body, "operation_failed", "Collection operation failed.", response.status);
+            const error = decoded.httpError
+                ?? apiError(body, "operation_failed", "Collection operation failed.", response.status);
             const recovery = await retryBusy(error);
             if (recovery.retried)
                 return recovery.result;
@@ -304,21 +331,18 @@ export class ConnectionTransport {
     }
     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.");
-            }
+            const leases = this.grantKeyLeases();
             try {
+                let token = await retainCurrentGrantToken(() => this.currentToken(), leases, budget.signal);
+                if (token)
+                    await this.authorizedToken({ signal: budget.signal, timeoutMs: null });
+                token = await retainCurrentGrantToken(() => this.currentToken(), leases, budget.signal);
+                requireSyncAuthorization(token, collectionId, replicaId);
                 let response = await sendAuthoritySyncRequest(this.keyStore, 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.");
-                    }
+                    token = await this.refreshAuthorization({ signal: budget.signal, timeoutMs: null });
+                    token = await retainCurrentGrantToken(() => this.currentToken(), leases, budget.signal);
+                    requireSyncAuthorization(token, collectionId, replicaId);
                     response = await sendAuthoritySyncRequest(this.keyStore, token, method, path, input, budget.signal);
                 }
                 const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid synchronization response.");
@@ -335,9 +359,12 @@ export class ConnectionTransport {
                     : undefined;
                 throw operationTransportError(error, budget.signal, mutationRequestId, "hosted_provider_unavailable");
             }
+            finally {
+                leases.release();
+            }
         });
     }
-    async sendOperation(token, operation, input, tryDirect, options = {}, pendingRequestId, knownRejectedMutationRetry = false) {
+    async sendOperation(token, operation, input, tryDirect, leases, options = {}, pendingRequestId, knownRejectedMutationRetry = false) {
         let body = input ?? {};
         let encryptedRequest;
         let pendingMutation = false;
@@ -472,9 +499,13 @@ export class ConnectionTransport {
             }
             let relayToken;
             try {
-                relayToken = token.expiresAt > Date.now() + 30_000
-                    ? token
-                    : await this.refreshAuthorization(options.signal);
+                if (token.expiresAt <= Date.now() + 30_000) {
+                    await this.refreshAuthorization({ signal: options.signal, timeoutMs: null });
+                }
+                const current = await retainCurrentGrantToken(() => this.currentToken(), leases, options.signal);
+                if (!current)
+                    throw connectError("not_authorized", "Reconnect this application to continue.");
+                relayToken = current;
             }
             catch (error) {
                 if (pendingMutation && (directDeliveryUncertain || resumingMutation))
@@ -636,58 +667,26 @@ export class ConnectionTransport {
             this.internals.removeToken(this.collectionId, token.keyHandle);
             return null;
         }
-        return this.refreshAuthorization(options.signal);
+        return this.refreshAuthorization(options);
     }
-    refreshAuthorization(signal) {
-        if (this.refreshPromise)
-            return this.refreshPromise;
-        this.refreshPromise = this.performRefresh(signal).finally(() => {
-            this.refreshPromise = null;
-        });
-        return this.refreshPromise;
+    refreshAuthorization(options = {}) {
+        return this.refreshOperations.run("refresh", options, this.timeouts.requestMs, (signal) => this.performRefresh(signal));
     }
     async performRefresh(signal) {
-        const current = this.currentToken();
-        if (!current?.refreshToken) {
-            throw connectError("not_authorized", "Reconnect this application to continue.");
-        }
-        if ((current.refreshExpiresAt ?? 0) <= Date.now()) {
-            throw connectError("relay_authorization_expired", "Direct access is still available on this computer, but using the relay requires reconnecting this application.");
-        }
-        const attemptedRefreshToken = current.refreshToken;
-        const refreshUrl = `${this.serverUrl}/oauth/token`;
-        const refreshBody = new URLSearchParams({
-            grant_type: "refresh_token",
-            refresh_token: current.refreshToken,
-            client_id: current.clientId
-        }).toString();
-        const proof = current.authority
-            ? await authorityProofHeaders(this.keyStore, current, "POST", refreshUrl, refreshBody, current.refreshToken)
-            : {};
-        const response = await fetch(refreshUrl, {
-            method: "POST",
-            headers: {
-                "content-type": "application/x-www-form-urlencoded",
-                ...proof
-            },
-            body: refreshBody,
-            signal
-        });
-        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) {
-                return latest;
-            }
-            if (!this.directCapable(current)) {
-                this.internals.removeToken(this.collectionId, current.keyHandle);
-            }
-            if ((oauthErrorCode(body) ?? body?.error?.code) === "invalid_grant") {
-                throw connectError("authorization_expired", body?.error_description ?? body?.error?.message ?? "Reconnect this application to continue.", { status: response.status });
-            }
-            throw apiError(body, "authorization_expired", "Reconnect this application to continue.", response.status);
+        const leases = this.grantKeyLeases();
+        try {
+            const current = await retainCurrentGrantToken(() => this.currentToken(), leases, signal);
+            return await performAuthorizationRefresh({
+                current, serverUrl: this.serverUrl, keyStore: this.keyStore, signal,
+                currentToken: () => this.currentToken(),
+                directCapable: (token) => this.directCapable(token),
+                removeToken: (keyHandle) => this.internals.removeToken(this.collectionId, keyHandle),
+                storeTokenResponse: (body, clientId, keyHandle) => this.storeTokenResponse(body, clientId, keyHandle)
+            });
+        }
+        finally {
+            leases.release();
         }
-        return this.storeTokenResponse(body, current.clientId, current.keyHandle);
     }
     storeTokenResponse(body, clientId, keyHandle) {
         if (body.collection_id !== this.collectionId) {
@@ -709,9 +708,18 @@ export class ConnectionTransport {
     }
     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);
+        if (pending?.keyHandle) {
+            this.internals.deleteGrantKeyWhenUnused(this.collectionId, pending.keyHandle);
         }
     }
+    grantKeyLeases() {
+        return new GrantKeyLeaseSet(this.collectionId, (collectionId, keyHandle, signal) => this.internals.acquireGrantKeyLease(collectionId, keyHandle, signal));
+    }
+}
+function requireSyncAuthorization(token, collectionId, replicaId) {
+    if (token?.authority
+        && token.collectionId === collectionId
+        && token.authority.replicaId === replicaId)
+        return;
+    throw connectError("authority_authorization_changed", "Reconnect this collection authority before synchronizing.");
 }

package/dist/grant-key-leases.d.ts

@@ -0,0 +1,24 @@
+import type { StoredToken } from "./internal-types.js";
+export declare class GrantKeyLeaseRegistry {
+    private readonly namespace;
+    private readonly onFinalRelease;
+    private readonly leases;
+    private readonly locks;
+    readonly retainAutomaticallyRetiredKeys: boolean;
+    constructor(namespace: string, onFinalRelease: (collectionId: string, keyHandle: string) => void);
+    acquire(collectionId: string, keyHandle: string, signal?: AbortSignal): Promise<() => void>;
+    deleteExclusive(collectionId: string, keyHandle: string, action: () => void | Promise<void>): void;
+    has(collectionId: string, keyHandle: string): boolean;
+    handles(collectionId: string): Iterable<string>;
+    private acquireLocal;
+    private lockName;
+}
+export declare class GrantKeyLeaseSet {
+    private readonly collectionId;
+    private readonly acquire;
+    private readonly releases;
+    constructor(collectionId: string, acquire: (collectionId: string, keyHandle: string, signal?: AbortSignal) => Promise<() => void>);
+    retain(tokenOrHandle: StoredToken | string | null | undefined, signal?: AbortSignal): Promise<void>;
+    release(): void;
+}
+export declare function retainCurrentGrantToken(readCurrent: () => StoredToken | null, leases: GrantKeyLeaseSet, signal?: AbortSignal): Promise<StoredToken | null>;