@mdbase-dev/connect 0.1.0-beta.100

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

@@ -0,0 +1,34 @@
+import type { FileTransferSession } from "@mdbase-dev/connect-protocol";
+import type { GrantKeyStore } from "./crypto.js";
+import type { StoredToken } from "./internal-types.js";
+type ProofHeaders = (token: StoredToken, method: "GET" | "POST" | "DELETE", url: string, body: string | undefined, credential: string) => Promise<Record<string, string>>;
+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>;
+    onDirectAvailable(): void;
+    onDirectUnavailable(): void;
+    onRelayAvailable(): void;
+    authorityProofHeaders: ProofHeaders;
+    acquireGrantKeyLease(collectionId: string, keyHandle: string, signal?: AbortSignal): Promise<() => void>;
+}
+/**
+ * Owns every transport concern specific to files. ConnectionTransport only
+ * supplies authorization, routing, and proof-signing policy.
+ */
+export declare class ConnectionFileTransport {
+    private readonly options;
+    private readonly local;
+    constructor(options: ConnectionFileTransportOptions);
+    control<Result>(method: "GET" | "POST" | "DELETE", path?: string, input?: unknown, signal?: AbortSignal): Promise<Result>;
+    uploadChunk(session: FileTransferSession, chunkIndex: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>;
+    downloadChunk(session: FileTransferSession, chunkIndex: number, signal?: AbortSignal): Promise<Uint8Array>;
+    downloadHostedPart(session: FileTransferSession, partIndex: number, expectedLength: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    private requireFileToken;
+}
+export {};

package/dist/connection-file-transport.js

@@ -0,0 +1,85 @@
+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
+ * supplies authorization, routing, and proof-signing policy.
+ */
+export class ConnectionFileTransport {
+    options;
+    local;
+    constructor(options) {
+        this.options = options;
+        this.local = new LocalFileTransport(options);
+    }
+    async control(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();
+        }
+    }
+    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();
+        }
+    }
+    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 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();
+        }
+    }
+    async requireFileToken(signal) {
+        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;
+        }
+    }
+}

package/dist/connection-index.d.ts

@@ -0,0 +1,3 @@
+export declare function connectionIds(storage: Storage, storagePrefix: string): string[];
+export declare function addConnectionId(storage: Storage, storagePrefix: string, collectionId: string): void;
+export declare function removeConnectionId(storage: Storage, storagePrefix: string, collectionId: string): void;

package/dist/connection-index.js

@@ -0,0 +1,20 @@
+import { parseStored } from "./runtime-utils.js";
+export function connectionIds(storage, storagePrefix) {
+    const index = parseStored(storage.getItem(`${storagePrefix}:connections`));
+    return index?.version === 1 && Array.isArray(index.collectionIds)
+        && index.collectionIds.every((collectionId) => typeof collectionId === "string")
+        ? index.collectionIds
+        : [];
+}
+export function addConnectionId(storage, storagePrefix, collectionId) {
+    writeConnectionIds(storage, storagePrefix, [...connectionIds(storage, storagePrefix), collectionId]);
+}
+export function removeConnectionId(storage, storagePrefix, collectionId) {
+    writeConnectionIds(storage, storagePrefix, connectionIds(storage, storagePrefix).filter((id) => id !== collectionId));
+}
+function writeConnectionIds(storage, storagePrefix, ids) {
+    storage.setItem(`${storagePrefix}:connections`, JSON.stringify({
+        version: 1,
+        collectionIds: [...new Set(ids)]
+    }));
+}

package/dist/connection-notifications.d.ts

@@ -0,0 +1,31 @@
+import type { Application } from "./internal-types.js";
+import type { StoredToken } from "./internal-types.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
+import type { MdbaseNativeNotificationRegistration, MdbaseNativeNotificationRegistrationOptions, MdbaseNotificationRegistration, MdbaseNotificationRegistrationOptions } from "./notifications.js";
+export interface ConnectionNotificationContext {
+    serverUrl: string;
+    storage: Storage;
+    authorizedToken(signal?: AbortSignal): Promise<StoredToken | null>;
+    register(signal?: AbortSignal): Promise<Application>;
+    notificationKey(transport?: "web_push" | "fcm"): string;
+    requestTimeoutMs: number | null;
+}
+export declare class ConnectionNotifications {
+    private readonly context;
+    constructor(context: ConnectionNotificationContext);
+    registerNotifications(options: MdbaseNotificationRegistrationOptions): Promise<MdbaseNotificationRegistration>;
+    private registerNotificationsWithinBudget;
+    /**
+     * Register an iOS or Android installation for Connect-managed FCM.
+     *
+     * The application manifest selects the Firebase project. Re-register the
+     * same installation whenever Firebase refreshes its token.
+     */
+    registerNativeNotifications(options: MdbaseNativeNotificationRegistrationOptions): Promise<MdbaseNativeNotificationRegistration>;
+    private registerNativeNotificationsWithinBudget;
+    unregisterNativeNotifications(options?: ConnectRequestOptions): Promise<void>;
+    private unregisterNativeNotificationsWithinBudget;
+    unregisterNotifications(serviceWorker?: ServiceWorkerRegistration, options?: ConnectRequestOptions): Promise<void>;
+    private unregisterNotificationsWithinBudget;
+    private deleteNotificationChannel;
+}

package/dist/connection-notifications.js

@@ -0,0 +1,197 @@
+import { connectError } from "./errors.js";
+import { apiError, connectFetch, decodeJsonResponse, parseStored } from "./runtime-utils.js";
+import { base64UrlBytes, randomBase64Url } from "./base64.js";
+import { withRequestBudget } from "./request-budget.js";
+export class ConnectionNotifications {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async registerNotifications(options) {
+        return withRequestBudget(options, this.context.requestTimeoutMs, (budget) => this.registerNotificationsWithinBudget(options, budget.signal));
+    }
+    async registerNotificationsWithinBudget(options, signal) {
+        const token = await this.context.authorizedToken(signal);
+        if (!token) {
+            throw connectError("not_authorized", "Connect this application before enabling notifications.");
+        }
+        const application = await this.context.register(signal);
+        const declared = application.notifications?.criteria.map((criterion) => criterion.id) ?? [];
+        const criteria = [...new Set(options.criteria ?? declared)];
+        const undeclared = criteria.find((criterion) => !declared.includes(criterion));
+        if (undeclared) {
+            throw connectError("notification_criterion_not_declared", `The application manifest does not declare notification criterion ${undeclared}.`);
+        }
+        if (criteria.length === 0) {
+            throw connectError("notifications_not_declared", "This application manifest does not declare any notification criteria.");
+        }
+        const keyResponse = await connectFetch(`${this.context.serverUrl}/v1/notifications/vapid-public-key`, { signal }, "notifications_unavailable", "Push notifications are unavailable.");
+        const keyBody = await decodeJsonResponse(keyResponse, "invalid_operation_response", "Connect returned an invalid notification key response.");
+        if (!keyResponse.ok) {
+            throw apiError(keyBody, "notifications_unavailable", "Push notifications are unavailable.", keyResponse.status);
+        }
+        let pushSubscription = await options.serviceWorker.pushManager.getSubscription();
+        if (!pushSubscription) {
+            pushSubscription = await options.serviceWorker.pushManager.subscribe({
+                userVisibleOnly: true,
+                applicationServerKey: base64UrlBytes(keyBody.public_key)
+            });
+        }
+        const serialized = pushSubscription.toJSON();
+        if (!serialized.endpoint || !serialized.keys?.p256dh || !serialized.keys.auth) {
+            throw connectError("invalid_push_subscription", "The browser returned an incomplete push subscription.");
+        }
+        const previous = parseStored(this.context.storage.getItem(this.context.notificationKey()));
+        const installationId = options.installationId
+            ?? previous?.installationId
+            ?? randomBase64Url(24);
+        const channelResponse = await connectFetch(`${this.context.serverUrl}/v1/notifications/channels`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token.accessToken}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify({
+                installation_id: installationId,
+                criteria,
+                subscription: {
+                    endpoint: serialized.endpoint,
+                    expirationTime: serialized.expirationTime ?? null,
+                    keys: serialized.keys
+                }
+            }),
+            signal
+        }, "notification_registration_failed", "Could not register push notifications.");
+        const channelBody = await decodeJsonResponse(channelResponse, "invalid_operation_response", "Connect returned an invalid notification registration response.");
+        if (!channelResponse.ok) {
+            throw apiError(channelBody, "notification_registration_failed", "Could not register push notifications.", channelResponse.status);
+        }
+        if (previous?.channelId && previous.channelId !== channelBody.channel_id) {
+            void fetch(`${this.context.serverUrl}/v1/notifications/channels/${previous.channelId}`, {
+                method: "DELETE",
+                headers: { authorization: `Bearer ${token.accessToken}` },
+                signal
+            }).catch(() => undefined);
+        }
+        const registration = {
+            channelId: channelBody.channel_id,
+            installationId,
+            criteria
+        };
+        this.context.storage.setItem(this.context.notificationKey(), JSON.stringify(registration));
+        return registration;
+    }
+    /**
+     * Register an iOS or Android installation for Connect-managed FCM.
+     *
+     * The application manifest selects the Firebase project. Re-register the
+     * same installation whenever Firebase refreshes its token.
+     */
+    async registerNativeNotifications(options) {
+        return withRequestBudget(options, this.context.requestTimeoutMs, (budget) => this.registerNativeNotificationsWithinBudget(options, budget.signal));
+    }
+    async registerNativeNotificationsWithinBudget(options, signal) {
+        const token = await this.context.authorizedToken(signal);
+        if (!token) {
+            throw connectError("not_authorized", "Connect this application before enabling notifications.");
+        }
+        const application = await this.context.register(signal);
+        if (application.notifications?.native_delivery?.mode !== "managed_fcm") {
+            throw connectError("managed_fcm_not_declared", "This application does not declare Connect-managed native notifications.");
+        }
+        const declared = application.notifications.criteria.map((criterion) => criterion.id);
+        const criteria = [...new Set(options.criteria ?? declared)];
+        const undeclared = criteria.find((criterion) => !declared.includes(criterion));
+        if (undeclared) {
+            throw connectError("notification_criterion_not_declared", `The application manifest does not declare notification criterion ${undeclared}.`);
+        }
+        if (criteria.length === 0) {
+            throw connectError("notifications_not_declared", "This application manifest does not declare any notification criteria.");
+        }
+        const storageKey = this.context.notificationKey("fcm");
+        const previous = parseStored(this.context.storage.getItem(storageKey));
+        const installationId = options.installationId
+            ?? previous?.installationId
+            ?? randomBase64Url(24);
+        const response = await connectFetch(`${this.context.serverUrl}/v1/notifications/channels`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token.accessToken}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify({
+                installation_id: installationId,
+                criteria,
+                transport: "fcm",
+                token: options.token
+            }),
+            signal
+        }, "notification_registration_failed", "Could not register native notifications.");
+        const body = await decodeJsonResponse(response, "invalid_operation_response", "Connect returned an invalid native notification response.");
+        if (!response.ok) {
+            throw apiError(body, "notification_registration_failed", "Could not register native notifications.", response.status);
+        }
+        if (previous?.channelId && previous.channelId !== body.channel_id) {
+            void this.deleteNotificationChannel(previous.channelId, token.accessToken, signal)
+                .catch(() => undefined);
+        }
+        const registration = {
+            channelId: body.channel_id,
+            installationId,
+            transport: "fcm",
+            criteria
+        };
+        this.context.storage.setItem(storageKey, JSON.stringify(registration));
+        return registration;
+    }
+    async unregisterNativeNotifications(options = {}) {
+        return withRequestBudget(options, this.context.requestTimeoutMs, (budget) => this.unregisterNativeNotificationsWithinBudget(budget.signal));
+    }
+    async unregisterNativeNotificationsWithinBudget(signal) {
+        const storageKey = this.context.notificationKey("fcm");
+        const registration = parseStored(this.context.storage.getItem(storageKey));
+        const token = await this.context.authorizedToken(signal);
+        if (registration?.channelId && !token) {
+            throw connectError("not_authorized", "Reconnect this application before disabling native notifications.");
+        }
+        if (registration?.channelId && token) {
+            await this.deleteNotificationChannel(registration.channelId, token.accessToken, signal);
+        }
+        this.context.storage.removeItem(storageKey);
+    }
+    async unregisterNotifications(serviceWorker, options = {}) {
+        return withRequestBudget(options, this.context.requestTimeoutMs, (budget) => this.unregisterNotificationsWithinBudget(serviceWorker, budget.signal));
+    }
+    async unregisterNotificationsWithinBudget(serviceWorker, signal) {
+        const registration = parseStored(this.context.storage.getItem(this.context.notificationKey()));
+        const token = await this.context.authorizedToken(signal);
+        if (registration?.channelId && !token) {
+            throw connectError("not_authorized", "Reconnect this application before disabling push notifications.");
+        }
+        if (registration?.channelId && token) {
+            const response = await connectFetch(`${this.context.serverUrl}/v1/notifications/channels/${registration.channelId}`, {
+                method: "DELETE",
+                headers: { authorization: `Bearer ${token.accessToken}` },
+                signal
+            }, "notification_unregistration_failed", "Could not unregister push notifications.");
+            if (!response.ok && response.status !== 404) {
+                const body = await decodeJsonResponse(response, "invalid_operation_response", "Connect returned an invalid notification response.");
+                throw apiError(body, "notification_unregistration_failed", "Could not unregister push notifications.", response.status);
+            }
+        }
+        this.context.storage.removeItem(this.context.notificationKey());
+        const subscription = await serviceWorker?.pushManager.getSubscription();
+        await subscription?.unsubscribe();
+    }
+    async deleteNotificationChannel(channelId, accessToken, signal) {
+        const response = await connectFetch(`${this.context.serverUrl}/v1/notifications/channels/${channelId}`, {
+            method: "DELETE",
+            headers: { authorization: `Bearer ${accessToken}` },
+            signal
+        }, "notification_unregistration_failed", "Could not unregister push notifications.");
+        if (!response.ok && response.status !== 404) {
+            const body = await decodeJsonResponse(response, "invalid_operation_response", "Connect returned an invalid notification response.");
+            throw apiError(body, "notification_unregistration_failed", "Could not unregister push notifications.", response.status);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { GrantKeyStore } from "./crypto.js";
+import type { StoredToken } from "./internal-types.js";
+import type { ResolvedConnectTimeouts } from "./request-budget.js";
+export interface ConnectionTransportInternals {
+    readonly relayEncryption: "required" | "disabled";
+    removeToken(collectionId: string, keyHandle?: string, reason?: "not_authorized" | "authorization_lost" | "invalid_stored_grant" | "legacy_scope_reauthorization_required", 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;
+}
+export interface ConnectionTransportOptions {
+    serverUrl: string;
+    storage: Storage;
+    keyStore: GrantKeyStore;
+    directAccessMode: "auto" | "disabled";
+    loopbackUrl: string;
+    collectionId: string;
+    internals: ConnectionTransportInternals;
+    onChange(): void;
+    timeouts: ResolvedConnectTimeouts;
+}

package/dist/connection-transport-internals.js

@@ -0,0 +1 @@
+export {};

package/dist/connection-transport.d.ts

@@ -0,0 +1,64 @@
+import type { CollectionOperation } from "@mdbase-dev/connect-protocol";
+import type { StoredToken } from "./internal-types.js";
+import type { DirectAccessStatus, MdbaseConnectionRoute } from "./connection-types.js";
+import type { ConnectRequestOptions, PendingMutationSummary } from "./operation-types.js";
+import { ConnectionFileTransport } from "./connection-file-transport.js";
+import type { ConnectionTransportOptions } from "./connection-transport-internals.js";
+export type { ConnectionTransportInternals, ConnectionTransportOptions } from "./connection-transport-internals.js";
+export declare class ConnectionTransport {
+    private readonly serverUrl;
+    private readonly storage;
+    private readonly keyStore;
+    private readonly directAccessMode;
+    private readonly loopbackUrl;
+    private readonly collectionId;
+    private readonly internals;
+    private readonly onChange;
+    private readonly timeouts;
+    private readonly pendingMutationStore;
+    readonly files: ConnectionFileTransport;
+    private readonly refreshOperations;
+    private directStatus;
+    private currentRoute;
+    private directFailures;
+    private directRetryAt;
+    constructor(options: ConnectionTransportOptions);
+    get directAccess(): DirectAccessStatus;
+    get route(): MdbaseConnectionRoute;
+    notifyStorageChanged(): void;
+    checkDirectAccess(options?: ConnectRequestOptions): Promise<DirectAccessStatus>;
+    private checkDirectAccessWithinBudget;
+    /** Call from a user gesture to request browser permission for direct local access. */
+    requestDirectAccess(options?: ConnectRequestOptions): Promise<DirectAccessStatus>;
+    private requestDirectAccessWithinBudget;
+    disableDirectAccess(): void;
+    /** Return pending writes without exposing authority transport credentials. */
+    pendingMutations(): readonly PendingMutationSummary[];
+    pendingMutation(requestId: string): PendingMutationSummary | null;
+    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;
+    hasResumableMutationTransport(): boolean;
+    private directEligible;
+    private shouldAttemptDirect;
+    private probeDirectAccess;
+    private markDirectAvailable;
+    private markDirectUnavailable;
+    private setDirectStatus;
+    private setRoute;
+    private emitConnection;
+    private invalidateRejectedAuthorization;
+    currentToken(): StoredToken | null;
+    authorizedToken(options?: ConnectRequestOptions): Promise<StoredToken | null>;
+    private refreshAuthorization;
+    private performRefresh;
+    private storeTokenResponse;
+    private storedPendingMutations;
+    private storedPendingMutation;
+    private clearPendingMutation;
+    private grantKeyLeases;
+}