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

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

@@ -1 +1 @@
-sha384-5i/BVtYUAqTluHzqWtHkb2tI4mKjuOsQMdAKhtXjddN95BAkTPOpub7++MQX+fU0
+sha384-Rejwyx0zN9iv54K0UaKMWs09sQLXcxnOBtKT574KVKlC7aR4FZ7CqpPRMd7mKlNl

package/dist/connect-options.d.ts

@@ -0,0 +1,22 @@
+import type { JsonObject, MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
+import type { GrantKeyStore } from "./crypto.js";
+export interface MdbaseConnectOptions {
+    serverUrl: string;
+    /**
+     * A bundled v1 application manifest or its app-local URL. String values
+     * are loaded by this SDK and posted inline; Connect never fetches them.
+     */
+    manifest?: MdbaseAppManifest | string;
+    redirectUri?: string;
+    storage?: Storage;
+    /** Encrypted relay is required by default for newly authorized grants. */
+    relayEncryption?: "required" | "disabled";
+    keyStore?: GrantKeyStore;
+    /** Prefer same-computer connector access when the browser permits it. */
+    directAccess?: "auto" | "disabled";
+    /** Loopback origin override for development and automated testing. */
+    loopbackUrl?: string;
+    /** Override browser navigation, for example to use a native system browser. */
+    navigate?: (url: string) => void | Promise<void>;
+}
+export type MdbaseFrontmatter = JsonObject;

package/dist/connect-options.js

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

package/dist/connect.d.ts

@@ -1,40 +1,51 @@
 import type { JsonObject, MdbaseAppManifest } from "@mdbase-dev/connect-protocol";
 import { MdbaseConnection, type MdbaseAuthorizationOutcome, type MdbaseAuthorizationResult, type MdbaseAuthorizeOptions, type MdbaseConnectEnvironment } from "./connection.js";
+import type { MdbaseConnectOptions } from "./connect-options.js";
 import type { MdbaseConnectionInfo } from "./connection-types.js";
 import { type GrantKeyStore } from "./crypto.js";
-import { type Application } from "./internal-types.js";
-import { type AuthorizationProblemCode, type ConnectOutcome, type RegistrationProblemCode } from "./outcomes.js";
-import { MdbaseSession, type MdbaseSessionOptions, type MdbaseUnavailableReason } from "./session.js";
-export interface MdbaseConnectOptions {
-    serverUrl: string;
-    /**
-     * A bundled v1 application manifest or its app-local URL. String values
-     * are loaded by this SDK and posted inline; Connect never fetches them.
-     */
-    manifest?: MdbaseAppManifest | string;
-    redirectUri?: string;
-    storage?: Storage;
-    /** Encrypted relay is required by default for newly authorized grants. */
-    relayEncryption?: "required" | "disabled";
-    keyStore?: GrantKeyStore;
-    /** Prefer same-computer connector access when the browser permits it. */
-    directAccess?: "auto" | "disabled";
-    /** Loopback origin override for development and automated testing. */
-    loopbackUrl?: string;
-    /** Override browser navigation, for example to use a native system browser. */
-    navigate?: (url: string) => void | Promise<void>;
-}
-export declare class MdbaseConnect<Frontmatter extends JsonObject = JsonObject> {
-    private readonly internals;
+import { type Application, type StoredToken } from "./internal-types.js";
+import type { MdbaseUnavailableReason } from "./session.js";
+export declare class MdbaseConnectInternals<Frontmatter extends JsonObject> {
+    readonly serverUrl: string;
+    readonly manifest: MdbaseAppManifest | string;
+    readonly manifestSource: string;
+    readonly redirectUri: string;
+    readonly storage: Storage;
+    readonly relayEncryption: "required" | "disabled";
+    readonly keyStore: GrantKeyStore;
+    readonly directAccessMode: "auto" | "disabled";
+    readonly loopbackUrl: string;
+    readonly navigate?: (url: string) => void | Promise<void>;
+    readonly credentialStorage: MdbaseConnectEnvironment["credentialStorage"];
+    private application;
+    private readonly completionPromises;
+    private readonly connectionCache;
+    private readonly listeners;
+    private readonly invalidatedConnections;
     constructor(options: MdbaseConnectOptions);
-    register(): Promise<ConnectOutcome<Application, RegistrationProblemCode>>;
-    authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
-    createSession(options: MdbaseSessionOptions): MdbaseSession<Frontmatter>;
     environment(): MdbaseConnectEnvironment;
-    completeAuthorization(callbackUrl?: string): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
+    register(): Promise<Application>;
+    private loadManifest;
+    authorize(options?: MdbaseAuthorizeOptions): Promise<MdbaseAuthorizationOutcome<Frontmatter>>;
+    private authorizeWeb;
+    private authorizePortable;
+    completeAuthorization(callbackUrl: string): Promise<MdbaseAuthorizationResult<Frontmatter>>;
+    private performAuthorizationCompletion;
     connections(): MdbaseConnectionInfo[];
     connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
     unavailableReason(collectionId: string): MdbaseUnavailableReason | null;
     onConnectionsChange(listener: (connections: MdbaseConnectionInfo[]) => void): () => void;
-    forgetAll(): void;
+    storeTokenResponse(body: any, clientId: string, keyHandle?: string): StoredToken;
+    removeToken(collectionId: string, keyHandle?: string, reason?: MdbaseUnavailableReason): void;
+    tokenKey(collectionId: string): string;
+    pendingMutationKey(collectionId: string): string;
+    notificationKey(collectionId: string, transport?: "web_push" | "fcm"): string;
+    directPreferenceKey(): string;
+    defaultApplicationOrigin(): string;
+    private pendingKey;
+    private storagePrefix;
+    private connectionsKey;
+    private connectionIds;
+    private addConnectionId;
+    private emitConnections;
 }

package/dist/connect.js

@@ -1,53 +1,15 @@
-import { DEFAULT_LOOPBACK_PORT, ENCRYPTED_RELAY_PROTOCOL_VERSION, RELAY_ENCRYPTION_SUITE } from "@mdbase-dev/connect-protocol";
+import { FIRST_CONTACT_PROTOCOL_VERSION, DEFAULT_LOOPBACK_PORT, ENCRYPTED_RELAY_PROTOCOL_VERSION, RELAY_ENCRYPTION_SUITE } from "@mdbase-dev/connect-protocol";
 import { abortableDelay } from "./async.js";
 import { randomBase64Url } from "./base64.js";
+import { applicationInstallationId, signApplicationAuthorization } from "./application-identity.js";
 import { MdbaseConnection } from "./connection.js";
 import { IndexedDbGrantKeyStore, MemoryGrantKeyStore, validateGrantEncryption } from "./crypto.js";
+import { applicationIdentity, presentFirstContact } from "./first-contact-presentation.js";
 import { connectError, serverConnectError } from "./errors.js";
 import { DEFAULT_OPERATIONS } from "./internal-types.js";
 import { uniqueOperations } from "./operation-helpers.js";
-import { AUTHORIZATION_PROBLEM_CODES, REGISTRATION_PROBLEM_CODES, captureConnectOutcome } from "./outcomes.js";
-import { MdbaseSession } from "./session.js";
-import { MemoryStorage, apiError, canonicalLoopbackUrl, connectFetch, createPkce, defaultCallbackUrl, defaultManifestSource, defaultRedirectUri, defaultStorage, isOpaquePortableManifest, manifestStorageFingerprint, oauthErrorCode, parseDeviceAuthorization, parseGrantScope, parseStored, stripTrailingSlash, validFileCapability, validAuthorityTokenResponse } from "./runtime-utils.js";
-export class MdbaseConnect {
-    internals;
-    constructor(options) {
-        this.internals = new MdbaseConnectInternals(options);
-    }
-    register() {
-        return captureConnectOutcome(() => this.internals.register(), REGISTRATION_PROBLEM_CODES);
-    }
-    authorize(options = {}) {
-        return captureConnectOutcome(() => this.internals.authorize(options), AUTHORIZATION_PROBLEM_CODES);
-    }
-    createSession(options) {
-        return new MdbaseSession(this, options);
-    }
-    environment() {
-        return this.internals.environment();
-    }
-    completeAuthorization(callbackUrl) {
-        return captureConnectOutcome(() => this.internals.completeAuthorization(callbackUrl ?? defaultCallbackUrl()), AUTHORIZATION_PROBLEM_CODES);
-    }
-    connections() {
-        return this.internals.connections();
-    }
-    connection(collectionId) {
-        return this.internals.connection(collectionId);
-    }
-    unavailableReason(collectionId) {
-        return this.internals.unavailableReason(collectionId);
-    }
-    onConnectionsChange(listener) {
-        return this.internals.onConnectionsChange(listener);
-    }
-    forgetAll() {
-        for (const connection of this.connections()) {
-            this.connection(connection.collectionId)?.forget();
-        }
-    }
-}
-class MdbaseConnectInternals {
+import { MemoryStorage, apiError, canonicalLoopbackUrl, connectFetch, createPkce, defaultManifestSource, defaultRedirectUri, defaultStorage, isOpaquePortableManifest, manifestStorageFingerprint, oauthErrorCode, parseDeviceAuthorization, parseGrantScope, parseStored, stripTrailingSlash, validFileCapability, validAuthorityTokenResponse } from "./runtime-utils.js";
+export class MdbaseConnectInternals {
     serverUrl;
     manifest;
     manifestSource;
@@ -150,10 +112,10 @@ class MdbaseConnectInternals {
         }
         const portableDeclared = typeof this.manifest !== "string"
             && this.manifest.distribution === "portable";
-        const popup = portableDeclared
-            && !options.openVerification
+        const popup = !(portableDeclared && options.openVerification)
+            && !this.navigate
             && typeof window !== "undefined"
-            ? window.open(`${this.serverUrl}/device`, "mdbase-connect-authorization", "popup,width=620,height=760")
+            ? window.open("", "mdbase-connect-authorization", "popup,width=620,height=760")
             : null;
         let application;
         try {
@@ -164,18 +126,47 @@ class MdbaseConnectInternals {
             throw error;
         }
         if (application.distribution === "portable") {
-            return this.authorizePortable(application, options, popup);
+            if (options.openVerification)
+                popup?.close();
+            return this.authorizePortable(application, options, options.openVerification ? null : popup);
         }
-        popup?.close();
+        return this.authorizeWeb(application, options, popup);
+    }
+    async authorizeWeb(application, options, popup) {
         const { verifier, challenge } = await createPkce();
         const state = randomBase64Url(24);
+        const authorizationId = crypto.randomUUID();
         const targetCollectionId = options.target?.kind === "collection"
             ? options.target.collectionId
             : undefined;
-        const keyHandle = this.relayEncryption === "required"
-            ? `grant:${application.id}:${state}`
-            : undefined;
-        const grantKey = keyHandle ? await this.keyStore.create(keyHandle) : undefined;
+        const keyHandle = `grant:${application.id}:${state}`;
+        const grantKey = await this.keyStore.create(keyHandle);
+        const installation = await applicationIdentity(this.keyStore, this.serverUrl, application);
+        const operations = uniqueOperations(options.operations ?? DEFAULT_OPERATIONS);
+        const issuedAt = new Date();
+        const proof = await signApplicationAuthorization({
+            protocol_version: FIRST_CONTACT_PROTOCOL_VERSION,
+            authorization_id: authorizationId,
+            application_id: application.id,
+            application_manifest_digest: application.manifest_digest,
+            application_installation_id: await applicationInstallationId(installation),
+            installation_agreement_public_key: installation.agreementPublicKey,
+            installation_signing_public_key: installation.signingPublicKey,
+            grant_agreement_public_key: grantKey.agreementPublicKey,
+            grant_signing_public_key: grantKey.signingPublicKey,
+            flow: "authorization_code",
+            authorization_nonce: randomBase64Url(32),
+            issued_at: issuedAt.toISOString(),
+            expires_at: new Date(issuedAt.getTime() + 10 * 60 * 1_000).toISOString(),
+            redirect_uri: this.redirectUri,
+            state,
+            code_challenge: challenge,
+            requested_operations: operations,
+            ...(application.requirements?.files
+                ? { requested_files: application.requirements.files }
+                : {}),
+            ...(targetCollectionId ? { collection_id: targetCollectionId } : {})
+        }, installation);
         const pending = {
             version: 1,
             verifier,
@@ -186,30 +177,107 @@ class MdbaseConnectInternals {
             collectionId: targetCollectionId,
             returnTo: options.returnTo,
             keyHandle,
-            applicationAgreementPublicKey: grantKey?.agreementPublicKey,
-            applicationSigningPublicKey: grantKey?.signingPublicKey
+            installationKeyHandle: installation.handle,
+            authorizationId,
+            applicationAgreementPublicKey: grantKey.agreementPublicKey,
+            applicationSigningPublicKey: grantKey.signingPublicKey
         };
         this.storage.setItem(this.pendingKey(state), JSON.stringify(pending));
-        const authorize = new URL(`${this.serverUrl}/oauth/authorize`);
-        authorize.searchParams.set("client_id", application.id);
-        authorize.searchParams.set("redirect_uri", this.redirectUri);
-        authorize.searchParams.set("code_challenge", challenge);
-        authorize.searchParams.set("code_challenge_method", "S256");
-        authorize.searchParams.set("state", state);
-        authorize.searchParams.set("operations", uniqueOperations(options.operations ?? DEFAULT_OPERATIONS).join(","));
-        if (targetCollectionId) {
-            authorize.searchParams.set("collection_id", targetCollectionId);
-        }
-        if (grantKey) {
-            authorize.searchParams.set("relay_protocol", "1");
-            authorize.searchParams.set("application_agreement_public_key", grantKey.agreementPublicKey);
-            authorize.searchParams.set("application_signing_public_key", grantKey.signingPublicKey);
-        }
-        if (this.navigate)
-            await this.navigate(authorize.href);
-        else
-            location.assign(authorize.href);
-        return { kind: "redirecting" };
+        try {
+            const response = await fetch(`${this.serverUrl}/oauth/authorization_request`, {
+                method: "POST",
+                headers: { "content-type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({
+                    client_id: application.id,
+                    redirect_uri: this.redirectUri,
+                    code_challenge: challenge,
+                    code_challenge_method: "S256",
+                    state,
+                    operations: operations.join(","),
+                    ...(targetCollectionId ? { collection_id: targetCollectionId } : {}),
+                    application_authorization: JSON.stringify(proof)
+                }),
+                signal: options.signal
+            });
+            const body = await response.json();
+            if (!response.ok) {
+                throw apiError(body, "device_authorization_failed", "Application authorization could not be started.", response.status);
+            }
+            if (typeof body.authorization_uri !== "string"
+                || body.authorization_id !== authorizationId
+                || !Number.isInteger(body.expires_in)
+                || !Number.isInteger(body.interval)
+                || body.expires_in <= 0
+                || body.interval <= 0) {
+                throw connectError("invalid_device_authorization_response", "The authorization service returned an invalid polling response.");
+            }
+            if (this.navigate)
+                await this.navigate(body.authorization_uri);
+            else if (popup)
+                popup.location.href = body.authorization_uri;
+            else {
+                throw connectError("browser_required", "The approval window was blocked. Allow popups for this application and try again.");
+            }
+            const expiresAt = Date.now() + body.expires_in * 1_000;
+            let intervalSeconds = body.interval;
+            let shownFirstContact = "";
+            while (Date.now() < expiresAt) {
+                await abortableDelay(intervalSeconds * 1_000, options.signal);
+                if (options.signal?.aborted) {
+                    throw connectError("authorization_cancelled", "Application authorization was cancelled.");
+                }
+                let statusResponse;
+                try {
+                    statusResponse = await fetch(`${this.serverUrl}/oauth/authorization_status`, {
+                        method: "POST",
+                        headers: { "content-type": "application/x-www-form-urlencoded" },
+                        body: new URLSearchParams({
+                            client_id: application.id,
+                            authorization_id: authorizationId,
+                            code_verifier: verifier
+                        }),
+                        signal: options.signal
+                    });
+                }
+                catch (cause) {
+                    if (options.signal?.aborted) {
+                        throw connectError("authorization_cancelled", "Application authorization was cancelled.", { cause });
+                    }
+                    continue;
+                }
+                const statusBody = await statusResponse.json();
+                if (!statusResponse.ok) {
+                    const code = oauthErrorCode(statusBody);
+                    if (code === "authorization_pending") {
+                        if (statusBody.first_contact) {
+                            shownFirstContact = await presentFirstContact(statusBody.first_contact, application, installation, options, shownFirstContact);
+                        }
+                        continue;
+                    }
+                    if (code === "slow_down") {
+                        intervalSeconds += 2;
+                        continue;
+                    }
+                    throw apiError(statusBody, "token_exchange_failed", "Application authorization could not be completed.", statusResponse.status);
+                }
+                if (typeof statusBody.authorization_redirect !== "string") {
+                    throw connectError("invalid_token_response", "The authorization service returned an invalid completion response.");
+                }
+                const result = await this.performAuthorizationCompletion(statusBody.authorization_redirect, state);
+                popup?.close();
+                return { kind: "connected", ...result };
+            }
+            throw connectError("expired_token", "The application authorization expired.");
+        }
+        catch (error) {
+            popup?.close();
+            this.storage.removeItem(this.pendingKey(state));
+            await this.keyStore.delete(keyHandle);
+            if (options.signal?.aborted) {
+                throw connectError("authorization_cancelled", "Application authorization was cancelled.", { cause: error });
+            }
+            throw error;
+        }
     }
     async authorizePortable(application, options, popup) {
         if (this.relayEncryption !== "required") {
@@ -219,6 +287,33 @@ class MdbaseConnectInternals {
         const { verifier, challenge } = await createPkce();
         const keyHandle = `grant:${application.id}:${randomBase64Url(24)}`;
         const grantKey = await this.keyStore.create(keyHandle);
+        const installation = await applicationIdentity(this.keyStore, this.serverUrl, application);
+        const operations = uniqueOperations(options.operations ?? DEFAULT_OPERATIONS);
+        const authorizationId = crypto.randomUUID();
+        const issuedAt = new Date();
+        const proof = await signApplicationAuthorization({
+            protocol_version: FIRST_CONTACT_PROTOCOL_VERSION,
+            authorization_id: authorizationId,
+            application_id: application.id,
+            application_manifest_digest: application.manifest_digest,
+            application_installation_id: await applicationInstallationId(installation),
+            installation_agreement_public_key: installation.agreementPublicKey,
+            installation_signing_public_key: installation.signingPublicKey,
+            grant_agreement_public_key: grantKey.agreementPublicKey,
+            grant_signing_public_key: grantKey.signingPublicKey,
+            flow: "device_code",
+            authorization_nonce: randomBase64Url(32),
+            issued_at: issuedAt.toISOString(),
+            expires_at: new Date(issuedAt.getTime() + 10 * 60 * 1_000).toISOString(),
+            code_challenge: challenge,
+            requested_operations: operations,
+            ...(application.requirements?.files
+                ? { requested_files: application.requirements.files }
+                : {}),
+            ...(options.target?.kind === "collection"
+                ? { collection_id: options.target.collectionId }
+                : {})
+        }, installation);
         let response;
         let body;
         try {
@@ -227,15 +322,13 @@ class MdbaseConnectInternals {
                 headers: { "content-type": "application/x-www-form-urlencoded" },
                 body: new URLSearchParams({
                     client_id: application.id,
-                    operations: uniqueOperations(options.operations ?? DEFAULT_OPERATIONS).join(","),
+                    operations: operations.join(","),
                     ...(options.target?.kind === "collection"
                         ? { collection_id: options.target.collectionId }
                         : {}),
                     code_challenge: challenge,
                     code_challenge_method: "S256",
-                    relay_protocol: "1",
-                    application_agreement_public_key: grantKey.agreementPublicKey,
-                    application_signing_public_key: grantKey.signingPublicKey
+                    application_authorization: JSON.stringify(proof)
                 })
             });
             body = await response.json();
@@ -257,6 +350,9 @@ class MdbaseConnectInternals {
         catch (error) {
             popup?.close();
             await this.keyStore.delete(keyHandle);
+            if (options.signal?.aborted) {
+                throw connectError("authorization_cancelled", "Downloaded application authorization was cancelled.", { cause: error });
+            }
             throw error;
         }
         options.onDeviceCode?.(authorization);
@@ -284,6 +380,7 @@ class MdbaseConnectInternals {
             });
         }
         let intervalSeconds = authorization.intervalSeconds;
+        let shownFirstContact = "";
         try {
             while (Date.now() < authorization.expiresAt) {
                 await abortableDelay(intervalSeconds * 1_000, options.signal);
@@ -313,8 +410,12 @@ class MdbaseConnectInternals {
                 const tokenBody = await tokenResponse.json();
                 if (!tokenResponse.ok) {
                     const code = oauthErrorCode(tokenBody);
-                    if (code === "authorization_pending")
+                    if (code === "authorization_pending") {
+                        if (tokenBody.first_contact) {
+                            shownFirstContact = await presentFirstContact(tokenBody.first_contact, application, installation, options, shownFirstContact);
+                        }
                         continue;
+                    }
                     if (code === "slow_down") {
                         intervalSeconds += 5;
                         continue;
@@ -357,6 +458,9 @@ class MdbaseConnectInternals {
         catch (error) {
             popup?.close();
             await this.keyStore.delete(keyHandle);
+            if (options.signal?.aborted) {
+                throw connectError("authorization_cancelled", "Downloaded application authorization was cancelled.", { cause: error });
+            }
             throw error;
         }
     }

package/dist/connection.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionChange, CollectionChangesPage, CollectionDescription, CollectionOperation, CollectionTypeDocument, CreateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, FileCapability, GrantScope, JsonObject, ReadViewSourceInput, RecordDocument, SavedViewExecution, SavedViewList, SavedViewSourceDocument, TypePackInstallResult, TypePackProvision, UpdateViewSourceInput } from "@mdbase-dev/connect-protocol";
+import type { CollectionChange, CollectionChangesPage, CollectionDescription, CollectionOperation, FirstContactBinding, CollectionTypeDocument, CreateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, FileCapability, GrantScope, JsonObject, ReadViewSourceInput, RecordDocument, SavedViewExecution, SavedViewList, SavedViewSourceDocument, TypePackInstallResult, TypePackProvision, UpdateViewSourceInput } from "@mdbase-dev/connect-protocol";
 import { type ConnectionTransportInternals } from "./connection-transport.js";
 import type { DirectAccessStatus, MdbaseAuthorizationCapabilities, MdbaseConnectionInfo, MdbaseConnectionRoute, MdbaseSyncConnection } from "./connection-types.js";
 import type { GrantKeyStore } from "./crypto.js";
@@ -22,6 +22,11 @@ export interface MdbaseAuthorizeOptions {
     returnTo?: string;
     /** Receives the short code even when the SDK also opens the approval page. */
     onDeviceCode?: (authorization: MdbaseDeviceAuthorization) => void;
+    /**
+     * Displays the independently derived first-contact code. Keep it visible
+     * while the user compares and accepts the same code on the connector.
+     */
+    onFirstContact?: (challenge: MdbaseFirstContactChallenge) => void | Promise<void>;
     /** Replace the default popup for a downloaded application's approval page. */
     openVerification?: (authorization: MdbaseDeviceAuthorization) => void | Promise<void>;
     /** Stop polling and discard the unapproved, in-memory key. */
@@ -31,9 +36,16 @@ export interface MdbaseConnectionAuthorizeOptions {
     operations?: CollectionOperation[];
     returnTo?: string;
     onDeviceCode?: (authorization: MdbaseDeviceAuthorization) => void;
+    onFirstContact?: (challenge: MdbaseFirstContactChallenge) => void | Promise<void>;
     openVerification?: (authorization: MdbaseDeviceAuthorization) => void | Promise<void>;
     signal?: AbortSignal;
 }
+export interface MdbaseFirstContactChallenge {
+    binding: FirstContactBinding;
+    authenticationString: string;
+    applicationId: string;
+    connectorId: string;
+}
 export interface MdbaseConnectEnvironment {
     distribution: "web" | "portable";
     applicationOrigin: string;
@@ -78,7 +90,7 @@ export declare class MdbaseConnection<Frontmatter extends JsonObject = JsonObjec
     authorizationCapabilities(requiredOperations?: CollectionOperation[]): MdbaseAuthorizationCapabilities;
     hasOperations(requiredOperations: CollectionOperation[]): boolean;
     authorize(options?: MdbaseConnectionAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
-    requestOperations(requiredOperations: CollectionOperation[], options?: Pick<MdbaseConnectionAuthorizeOptions, "returnTo">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
+    requestOperations(requiredOperations: CollectionOperation[], options?: Omit<MdbaseConnectionAuthorizeOptions, "operations">): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter> | {
         kind: "unchanged";
         connection: MdbaseConnection<Frontmatter>;
     }, AuthorizationProblemCode>>;

package/dist/first-contact-presentation.d.ts

@@ -0,0 +1,5 @@
+import type { MdbaseAuthorizeOptions } from "./connection.js";
+import type { GrantKeyRecord, GrantKeyStore } from "./crypto.js";
+import type { Application } from "./internal-types.js";
+export declare function presentFirstContact(value: unknown, application: Application, installation: GrantKeyRecord, options: MdbaseAuthorizeOptions, previousFingerprint: string): Promise<string>;
+export declare function applicationIdentity(keyStore: GrantKeyStore, serverUrl: string, application: Application): Promise<GrantKeyRecord>;

package/dist/first-contact-presentation.js

@@ -0,0 +1,51 @@
+import { applicationInstallationId } from "./application-identity.js";
+import { deriveFirstContactSas } from "./first-contact.js";
+import { connectError } from "./errors.js";
+export async function presentFirstContact(value, application, installation, options, previousFingerprint) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw connectError("invalid_first_contact", "The authorization service returned an invalid first-contact challenge.");
+    }
+    const binding = value;
+    const installationId = await applicationInstallationId(installation);
+    if (binding.application_id !== application.id
+        || binding.application_installation_id !== installationId
+        || binding.application_agreement_public_key !== installation.agreementPublicKey
+        || binding.application_signing_public_key !== installation.signingPublicKey) {
+        throw connectError("invalid_first_contact", "The first-contact challenge does not match this application installation.");
+    }
+    const fingerprint = JSON.stringify(binding);
+    if (fingerprint === previousFingerprint)
+        return previousFingerprint;
+    if (!options.onFirstContact) {
+        throw connectError("first_contact_handler_required", "Local access requires the application to display a first-contact comparison code.");
+    }
+    let authenticationString;
+    try {
+        authenticationString = await deriveFirstContactSas(binding, "application", installation);
+    }
+    catch (cause) {
+        throw connectError("invalid_first_contact", "The authorization service returned an invalid first-contact challenge.", { cause });
+    }
+    await options.onFirstContact({
+        binding,
+        authenticationString,
+        applicationId: binding.application_id,
+        connectorId: binding.connector_id
+    });
+    return fingerprint;
+}
+export async function applicationIdentity(keyStore, serverUrl, application) {
+    const handle = `application-installation:${serverUrl}:${application.id}`;
+    const existing = await keyStore.get(handle);
+    if (existing)
+        return existing;
+    try {
+        return await keyStore.create(handle);
+    }
+    catch (error) {
+        const raced = await keyStore.get(handle);
+        if (raced)
+            return raced;
+        throw error;
+    }
+}

package/dist/first-contact.d.ts

@@ -0,0 +1,14 @@
+import { type FirstContactBinding } from "@mdbase-dev/connect-protocol";
+export type FirstContactRole = "application" | "connector";
+export declare class FirstContactCryptoError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Derive the independently displayed first-contact authentication string.
+ * The private key must belong to the endpoint role named in the transcript.
+ */
+export declare function deriveFirstContactSas(binding: FirstContactBinding, role: FirstContactRole, identity: {
+    agreementPrivateKey: CryptoKey;
+    agreementPublicKey: string;
+}): Promise<string>;