@mdbase-dev/connect 0.1.0-beta.100

package/dist/local-file-transport.js

@@ -0,0 +1,457 @@
+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 { GrantKeyLeaseSet, retainCurrentGrantToken } from "./grant-key-leases.js";
+import { directFallbackStatus, loopbackRequest } from "./operation-helpers.js";
+import { apiError, decodeJsonResponse } from "./runtime-utils.js";
+import { isConnectorBusy, isExplicitConnectorBusyResponse, MAX_CONNECTOR_BUSY_RETRIES, waitForConnectorAvailability } from "./transient-retry.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) {
+        const leases = this.grantKeyLeases(token.collectionId);
+        try {
+            token = await this.retainEntryToken(token, leases, signal);
+            return await this.controlAttempt(token, method, path, input, signal, false, 0, leases);
+        }
+        finally {
+            leases.release();
+        }
+    }
+    async controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries, leases) {
+        requireEncryption(token);
+        const controlInput = localFileControlInput(method, path, input);
+        let encryptedRequest = await this.encryptControl(token, controlInput);
+        let response;
+        const triedDirect = await this.options.shouldAttemptDirect(token);
+        if (triedDirect) {
+            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)
+                || await isExplicitConnectorBusyResponse(response))) {
+                if (response.ok)
+                    this.options.onDirectAvailable();
+                return this.decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried, connectorBusyRetries, leases);
+            }
+            if (response)
+                this.options.onDirectUnavailable();
+        }
+        if (triedDirect && method === "GET") {
+            token = token.expiresAt > Date.now() + 30_000
+                ? token
+                : await this.options.refreshAuthorization(signal);
+            token = await this.retainEntryToken(token, leases, signal);
+            requireLocalFileToken(token);
+            encryptedRequest = await this.encryptControl(token, controlInput);
+        }
+        response = await this.sendRelayControl(token, encryptedRequest, signal);
+        if (await refreshableBindingFailure(response, token)) {
+            token = await this.options.refreshAuthorization(signal);
+            token = await this.retainEntryToken(token, leases, signal);
+            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, method, path, input, signal, encryptedRequest, response, freshReadRetried, connectorBusyRetries, leases);
+    }
+    async decryptControlResponse(token, method, path, input, signal, encryptedRequest, response, freshReadRetried, connectorBusyRetries, leases) {
+        const body = await decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file control response.");
+        if (!response.ok) {
+            const error = apiError(body, "operation_failed", "Collection file request failed.", response.status);
+            if (isConnectorBusy(error)
+                && connectorBusyRetries < MAX_CONNECTOR_BUSY_RETRIES) {
+                await waitForConnectorAvailability(connectorBusyRetries, signal);
+                return this.controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries + 1, leases);
+            }
+            if (error.code === "fresh_request_required"
+                && method === "GET"
+                && !freshReadRetried) {
+                return this.controlAttempt(token, method, path, input, signal, true, connectorBusyRetries, leases);
+            }
+            throw error;
+        }
+        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
+            && decrypted.problem.code === "fresh_request_required"
+            && method === "GET"
+            && !freshReadRetried) {
+            return this.controlAttempt(token, method, path, input, signal, true, connectorBusyRetries, leases);
+        }
+        if (!decrypted.ok) {
+            const error = encryptedProblem(decrypted.problem);
+            if (isConnectorBusy(error)
+                && connectorBusyRetries < MAX_CONNECTOR_BUSY_RETRIES) {
+                await waitForConnectorAvailability(connectorBusyRetries, signal);
+                return this.controlAttempt(token, method, path, input, signal, freshReadRetried, connectorBusyRetries + 1, leases);
+            }
+            throw error;
+        }
+        return decrypted.result;
+    }
+    async uploadChunk(session, chunkIndex, bytes, signal, authorizedToken) {
+        const token = authorizedToken ?? await this.localFileToken(session, "upload", signal);
+        const leases = this.grantKeyLeases(token.collectionId);
+        try {
+            const current = await this.retainEntryToken(token, leases, signal);
+            validateLocalFileToken(current, session, "upload");
+            return await this.uploadChunkWithLease(current, leases, session, chunkIndex, bytes, signal);
+        }
+        finally {
+            leases.release();
+        }
+    }
+    async uploadChunkWithLease(token, leases, session, chunkIndex, bytes, signal) {
+        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)
+                || await isExplicitConnectorBusyResponse(response))) {
+                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(signal);
+            deliveryToken = await this.retainEntryToken(deliveryToken, leases, signal);
+            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 decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file upload response.");
+            throw apiError(body, "operation_failed", "Encrypted file chunk upload failed.", response.status);
+        }
+        this.options.onRelayAvailable();
+    }
+    async downloadChunk(session, chunkIndex, signal, authorizedToken) {
+        let token = authorizedToken ?? await this.localFileToken(session, "download", signal);
+        const leases = this.grantKeyLeases(token.collectionId);
+        try {
+            token = await this.retainEntryToken(token, leases, signal);
+            validateLocalFileToken(token, session, "download");
+            return await this.downloadChunkWithLease(token, leases, session, chunkIndex, signal);
+        }
+        finally {
+            leases.release();
+        }
+    }
+    async downloadChunkWithLease(token, leases, session, chunkIndex, signal) {
+        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)
+                || await isExplicitConnectorBusyResponse(response))) {
+                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(signal);
+            token = await this.retainEntryToken(token, leases, signal);
+            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 decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file download response.");
+            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, signal) {
+        const token = await this.options.authorizedToken(signal);
+        validateLocalFileToken(token, session, direction);
+        return token;
+    }
+    grantKeyLeases(collectionId) {
+        return new GrantKeyLeaseSet(collectionId, this.options.acquireGrantKeyLease
+            ?? (() => Promise.resolve(() => undefined)));
+    }
+    async retainEntryToken(snapshot, leases, signal) {
+        if (!this.options.currentToken) {
+            await leases.retain(snapshot, signal);
+            return snapshot;
+        }
+        const current = await retainCurrentGrantToken(this.options.currentToken, leases, signal);
+        if (current)
+            return current;
+        throw connectError("not_authorized", "Reconnect this application to continue.");
+    }
+}
+function validateLocalFileToken(token, session, direction) {
+    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);
+}
+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 decodeJsonResponse(response, "invalid_operation_response", "The collection authority returned an invalid file transfer response.");
+    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 decodeJsonResponse(response.clone(), "invalid_operation_response", "The collection authority returned an invalid file response.").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 encryptedProblem(problem) {
+    return 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/mdbase-connect.d.ts

@@ -0,0 +1,28 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import type { MdbaseConnectOptions } from "./connect-options.js";
+import { MdbaseConnection, type MdbaseAuthorizationOutcome, type MdbaseAuthorizationResult, type MdbaseAuthorizeOptions, type MdbaseConnectEnvironment } from "./connection.js";
+import type { MdbaseConnectionInfo } from "./connection-types.js";
+import { type AuthorizationProblemCode, type ConnectOutcome, type RegistrationProblemCode } from "./outcomes.js";
+import { MdbaseApplicationSession, type MdbaseApplicationSessionOptions } from "./application-session.js";
+import type { MdbaseUnavailableReason } from "./session.js";
+import type { Application } from "./internal-types.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
+export declare class MdbaseConnect<Frontmatter extends JsonObject = JsonObject> {
+    private readonly internals;
+    constructor(options: MdbaseConnectOptions);
+    register(options?: ConnectRequestOptions): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
+    authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
+    /** The ordinary application lifecycle entry point. */
+    application(options: MdbaseApplicationSessionOptions): MdbaseApplicationSession<Frontmatter>;
+    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<import("./application-contract.js").MdbaseApplicationManifest, RegistrationProblemCode>>;
+    environment(): MdbaseConnectEnvironment;
+    completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
+    connections(): MdbaseConnectionInfo[];
+    connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
+    unavailableReason(collectionId: string): MdbaseUnavailableReason | null;
+    connectionApplicationId(collectionId: string): string | null;
+    onConnectionsChange(listener: (connections: MdbaseConnectionInfo[]) => void): () => void;
+    forgetAll(): void;
+    /** Forget a public TOFU pin after independently verifying a replaced connector. */
+    forgetConnectorIdentity(connectorId: string): void;
+}

package/dist/mdbase-connect.js

@@ -0,0 +1,53 @@
+import { MdbaseConnectInternals } from "./connect.js";
+import { defaultCallbackUrl } from "./runtime-utils.js";
+import { AUTHORIZATION_PROBLEM_CODES, REGISTRATION_PROBLEM_CODES, captureConnectOutcome } from "./outcomes.js";
+import { MdbaseApplicationSession } from "./application-session.js";
+export class MdbaseConnect {
+    internals;
+    constructor(options) {
+        this.internals = new MdbaseConnectInternals(options);
+    }
+    register(options) {
+        return captureConnectOutcome(() => this.internals.register(options), REGISTRATION_PROBLEM_CODES);
+    }
+    authorize(options = {}) {
+        return captureConnectOutcome(() => this.internals.authorize(options), AUTHORIZATION_PROBLEM_CODES);
+    }
+    /** The ordinary application lifecycle entry point. */
+    application(options) {
+        return new MdbaseApplicationSession(this, options, this.internals.timeouts);
+    }
+    manifest(options) {
+        return captureConnectOutcome(() => this.internals.manifestDeclaration(options), REGISTRATION_PROBLEM_CODES);
+    }
+    environment() {
+        return this.internals.environment();
+    }
+    completeAuthorization(callbackUrl, options) {
+        return captureConnectOutcome(() => this.internals.completeAuthorization(callbackUrl === undefined ? defaultCallbackUrl() : String(callbackUrl), options), AUTHORIZATION_PROBLEM_CODES);
+    }
+    connections() {
+        return this.internals.connections();
+    }
+    connection(collectionId) {
+        return this.internals.connection(collectionId);
+    }
+    unavailableReason(collectionId) {
+        return this.internals.unavailableReason(collectionId);
+    }
+    connectionApplicationId(collectionId) {
+        return this.internals.connectionApplicationId(collectionId);
+    }
+    onConnectionsChange(listener) {
+        return this.internals.onConnectionsChange(listener);
+    }
+    forgetAll() {
+        for (const connection of this.connections()) {
+            this.connection(connection.collectionId)?.forget();
+        }
+    }
+    /** Forget a public TOFU pin after independently verifying a replaced connector. */
+    forgetConnectorIdentity(connectorId) {
+        this.internals.forgetConnectorIdentity(connectorId);
+    }
+}

package/dist/notifications.d.ts

@@ -0,0 +1,48 @@
+import type { ConnectRequestOptions } from "./operation-types.js";
+export interface MdbaseNotificationRegistrationOptions extends ConnectRequestOptions {
+    serviceWorker: ServiceWorkerRegistration;
+    /** Manifest criterion IDs to enable. Omit to enable every declared criterion. */
+    criteria?: string[];
+    /** Stable per-installation ID. The SDK persists one when omitted. */
+    installationId?: string;
+}
+export interface MdbaseNotificationRegistration {
+    channelId: string;
+    installationId: string;
+    criteria: string[];
+}
+export interface MdbaseNativeNotificationRegistrationOptions extends ConnectRequestOptions {
+    /** Current FCM registration token. Refresh by calling this method again. */
+    token: string;
+    /** Manifest criterion IDs to enable. Omit to enable every declared criterion. */
+    criteria?: string[];
+    /** Stable per-installation ID. The SDK persists one when omitted. */
+    installationId?: string;
+}
+export interface MdbaseNativeNotificationRegistration extends MdbaseNotificationRegistration {
+    transport: "fcm";
+}
+export interface MdbaseNativeNotificationData {
+    type: "mdbase.notification";
+    version: 1;
+    signal_id: string;
+    criterion_id: string;
+    cursor: string;
+}
+export interface MdbasePushPayload {
+    type: "mdbase.notification";
+    version: 1;
+    signal_id: string;
+    criterion_id: string;
+    cursor: string;
+    presentation: {
+        title: string;
+        body?: string;
+        tag?: string;
+    };
+}
+export declare function parseMdbasePushPayload(value: unknown): MdbasePushPayload;
+/** Parse the string-valued data attached to an APNs/FCM notification. */
+export declare function parseMdbaseNativeNotificationData(value: unknown): MdbaseNativeNotificationData;
+/** Display a validated mdbase push from a service worker `push` handler. */
+export declare function showMdbasePushNotification(registration: Pick<ServiceWorkerRegistration, "showNotification">, value: unknown): Promise<void>;

package/dist/notifications.js

@@ -0,0 +1,52 @@
+import { connectError } from "./errors.js";
+export function parseMdbasePushPayload(value) {
+    if (!value || typeof value !== "object") {
+        throw connectError("invalid_push_payload", "The push payload is not an object.");
+    }
+    const payload = value;
+    if (payload.type !== "mdbase.notification"
+        || payload.version !== 1
+        || typeof payload.signal_id !== "string"
+        || typeof payload.criterion_id !== "string"
+        || typeof payload.cursor !== "string"
+        || !payload.presentation
+        || typeof payload.presentation.title !== "string") {
+        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 connectError("invalid_push_payload", "The native notification data is not an object.");
+    }
+    const data = value;
+    if (data.type !== "mdbase.notification"
+        || (data.version !== 1 && data.version !== "1")
+        || typeof data.signal_id !== "string"
+        || typeof data.criterion_id !== "string"
+        || typeof data.cursor !== "string") {
+        throw connectError("invalid_push_payload", "The native notification data is not an mdbase notification.");
+    }
+    return {
+        type: "mdbase.notification",
+        version: 1,
+        signal_id: data.signal_id,
+        criterion_id: data.criterion_id,
+        cursor: data.cursor
+    };
+}
+/** Display a validated mdbase push from a service worker `push` handler. */
+export function showMdbasePushNotification(registration, value) {
+    const payload = parseMdbasePushPayload(value);
+    return registration.showNotification(payload.presentation.title, {
+        ...(payload.presentation.body ? { body: payload.presentation.body } : {}),
+        ...(payload.presentation.tag ? { tag: payload.presentation.tag } : {}),
+        data: {
+            type: payload.type,
+            signal_id: payload.signal_id,
+            criterion_id: payload.criterion_id,
+            cursor: payload.cursor
+        }
+    });
+}

package/dist/operation-helpers.d.ts

@@ -0,0 +1,27 @@
+import { type CollectionOperation, type ConnectProblem, type EncryptedRelayOperationRequest } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError } from "./errors.js";
+import type { StoredToken } from "./internal-types.js";
+import type { DeleteInput, DeletePreflightResult, MutationEstimate, RenameInput, RenamePreflightResult } from "./operation-types.js";
+export type LoopbackRequestInit = RequestInit & {
+    targetAddressSpace?: "loopback";
+};
+export declare function loopbackRequest(init: RequestInit): LoopbackRequestInit;
+export declare function localNetworkPermission(): Promise<PermissionState | null>;
+export declare function directFallbackStatus(status: number): boolean;
+export declare function isMutation(operation: CollectionOperation, input?: unknown): boolean;
+export declare function withOperationDeadline(request: EncryptedRelayOperationRequest, deadlineUnixMs?: number): EncryptedRelayOperationRequest;
+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, pendingRequestId: string | undefined, unavailableCode: "hosted_provider_unavailable" | "relay_unavailable"): Error;
+export declare function encryptedOperationError(problem: ConnectProblem): MdbaseConnectError;
+export declare function fetchOperationRequest(url: string, accessToken: string, proof: Record<string, string>, body: string, signal?: AbortSignal): Promise<Response>;
+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;
+export declare function renameEstimate(input: RenameInput, preview: RenamePreflightResult): MutationEstimate;
+export declare function deleteEstimate(preview: DeletePreflightResult): MutationEstimate;
+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 unknownMutationOutcome(requestId: string, cause: unknown): MdbaseConnectError;