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

package/dist/first-contact.js

@@ -0,0 +1,145 @@
+import { FIRST_CONTACT_PROTOCOL_VERSION } from "@mdbase-dev/connect-protocol";
+const TRANSCRIPT_DOMAIN = new TextEncoder().encode("mdbase-connect first-contact transcript\0");
+const SAS_INFO = new TextEncoder().encode("mdbase-connect first-contact sas v1");
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export class FirstContactCryptoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Derive the independently displayed first-contact authentication string.
+ * The private key must belong to the endpoint role named in the transcript.
+ */
+export async function deriveFirstContactSas(binding, role, identity) {
+    const keys = await validatedKeys(binding);
+    const own = role === "application"
+        ? binding.application_agreement_public_key
+        : binding.connector_agreement_public_key;
+    const peer = role === "application"
+        ? keys.connector
+        : keys.applicationAgreement;
+    if (identity.agreementPublicKey !== own) {
+        throw new FirstContactCryptoError("identity_mismatch", "The first-contact identity does not match the transcript.");
+    }
+    let peerKey;
+    try {
+        peerKey = await crypto.subtle.importKey("raw", peer, { name: "ECDH", namedCurve: "P-256" }, false, []);
+    }
+    catch {
+        throw new FirstContactCryptoError("invalid_public_key", "The first-contact public key is invalid.");
+    }
+    const shared = await crypto.subtle.deriveBits({ name: "ECDH", public: peerKey }, identity.agreementPrivateKey, 256);
+    const transcript = firstContactTranscript(binding, keys);
+    const salt = await crypto.subtle.digest("SHA-256", transcript);
+    const hkdfKey = await crypto.subtle.importKey("raw", shared, "HKDF", false, ["deriveBits"]);
+    const sas = new Uint8Array(await crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info: SAS_INFO }, hkdfKey, 40));
+    return formatSas(sas);
+}
+async function validatedKeys(binding) {
+    if (binding.protocol_version !== FIRST_CONTACT_PROTOCOL_VERSION) {
+        throw new FirstContactCryptoError("unsupported_version", "The first-contact protocol version is not supported.");
+    }
+    const applicationAgreement = canonicalPublicKey(binding.application_agreement_public_key);
+    const applicationSigning = canonicalPublicKey(binding.application_signing_public_key);
+    const connector = canonicalPublicKey(binding.connector_agreement_public_key);
+    if (equalBytes(applicationAgreement, applicationSigning)
+        || equalBytes(applicationAgreement, connector)
+        || equalBytes(applicationSigning, connector)) {
+        throw new FirstContactCryptoError("invalid_public_key", "First contact requires distinct endpoint agreement and signing keys.");
+    }
+    try {
+        await Promise.all([
+            applicationAgreement,
+            applicationSigning,
+            connector
+        ].map((key) => crypto.subtle.importKey("raw", key, { name: "ECDH", namedCurve: "P-256" }, false, [])));
+    }
+    catch {
+        throw new FirstContactCryptoError("invalid_public_key", "The first-contact public key is invalid.");
+    }
+    return { applicationAgreement, applicationSigning, connector };
+}
+function firstContactTranscript(binding, keys) {
+    const chunks = [
+        TRANSCRIPT_DOMAIN,
+        u32(binding.protocol_version),
+        field(uuidBytes(binding.application_id)),
+        field(uuidBytes(binding.application_installation_id)),
+        field(keys.applicationAgreement),
+        field(keys.applicationSigning),
+        field(uuidBytes(binding.connector_id)),
+        field(keys.connector)
+    ];
+    const length = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}
+function field(value) {
+    const output = new Uint8Array(4 + value.byteLength);
+    output.set(u32(value.byteLength));
+    output.set(value, 4);
+    return output;
+}
+function u32(value) {
+    const output = new Uint8Array(4);
+    new DataView(output.buffer).setUint32(0, value, false);
+    return output;
+}
+function uuidBytes(value) {
+    if (!UUID_PATTERN.test(value)) {
+        throw new FirstContactCryptoError("invalid_binding", "The first-contact transcript contains an invalid identifier.");
+    }
+    const compact = value.replaceAll("-", "");
+    return Uint8Array.from({ length: 16 }, (_, index) => Number.parseInt(compact.slice(index * 2, index * 2 + 2), 16));
+}
+function canonicalPublicKey(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw new FirstContactCryptoError("invalid_public_key", "The first-contact public key is invalid.");
+    }
+    const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    let bytes;
+    try {
+        bytes = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+    }
+    catch {
+        throw new FirstContactCryptoError("invalid_public_key", "The first-contact public key is invalid.");
+    }
+    if (bytes.byteLength !== 65
+        || bytes[0] !== 4
+        || base64Url(bytes) !== value) {
+        throw new FirstContactCryptoError("invalid_public_key", "The first-contact public key is invalid.");
+    }
+    return bytes;
+}
+function base64Url(value) {
+    return btoa(String.fromCharCode(...value))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/u, "");
+}
+function equalBytes(left, right) {
+    return left.byteLength === right.byteLength
+        && left.every((value, index) => value === right[index]);
+}
+function formatSas(value) {
+    let bits = 0n;
+    for (const byte of value)
+        bits = (bits << 8n) | BigInt(byte);
+    let output = "";
+    for (let index = 7; index >= 0; index -= 1) {
+        output += CROCKFORD_BASE32[Number((bits >> BigInt(index * 5)) & 31n)];
+        if (index === 4)
+            output += "-";
+    }
+    return output;
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export { decryptRelayResponse, encryptRelayRequest, IndexedDbGrantKeyStore, MemoryGrantKeyStore, RelayCryptoError, type RelayBinding, type GrantKeyRecord, type GrantKeyStore } from "./crypto.js";
 export { FileTransferCryptoError, GrantFileTransferCipher, type FileTransferBinding } from "./file-crypto.js";
+export { deriveFirstContactSas, FirstContactCryptoError, type FirstContactRole } from "./first-contact.js";
+export { applicationInstallationId, authorizationSigningMessage, signApplicationAuthorization } from "./application-identity.js";
 export * from "./authorization-types.js";
 export * from "./collection-client.js";
-export * from "./connect.js";
+export * from "./connect-options.js";
+export * from "./mdbase-connect.js";
 export * from "./connection.js";
 export * from "./connection-types.js";
 export * from "./errors.js";
@@ -13,4 +16,4 @@ export * from "./operation-types.js";
 export * from "./selection.js";
 export * from "./session.js";
 export { createPkce } from "./runtime-utils.js";
-export type { ApplicationProvisions, ApplicationRequirements, ApplicationNotifications, CollectionChange, CollectionChangesPage, CollectionContractDescriptor, CollectionDescription, CollectionFileMetadata, CollectionOperation as MdbaseOperation, CollectionTypeDescriptor, CollectionTypeDocument, ConnectOperationOutcome, ConnectProblem, ConnectProblemCategory, ConnectProblemCode, ConnectProblemDetailsByCode, ConnectRecoveryAction, ContractRequirement, DataContractViewIdentity, GrantScope, JsonObject, MdbaseAppManifest, NotificationCriterion, MdbaseDiagnostic, MdbaseOperationEnvelope, KnownConnectProblem, RecordDocument, QueryRecord, SavedNamedView, SavedViewDocument, SavedViewExecution, SavedViewList, SavedViewPresentation, SavedViewProperty, SavedViewSource, SavedViewSourceDocument, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, TypePackManifest, TypePackManifestResource, TypePackInstallResult, TypePackProvision, TypePackResourceDiff, TypePackSourceResource, UnknownConnectProblem } from "@mdbase-dev/connect-protocol";
+export type { ApplicationProvisions, ApplicationRequirements, ApplicationNotifications, ApplicationAuthorizationBinding, ApplicationAuthorizationProof, CollectionChange, CollectionChangesPage, CollectionContractDescriptor, CollectionDescription, CollectionFileMetadata, CollectionOperation as MdbaseOperation, CollectionTypeDescriptor, CollectionTypeDocument, ConnectOperationOutcome, ConnectProblem, ConnectProblemCategory, ConnectProblemCode, ConnectProblemDetailsByCode, ConnectRecoveryAction, ContractRequirement, DataContractViewIdentity, GrantScope, FirstContactBinding, JsonObject, MdbaseAppManifest, NotificationCriterion, MdbaseDiagnostic, MdbaseOperationEnvelope, KnownConnectProblem, RecordDocument, QueryRecord, SavedNamedView, SavedViewDocument, SavedViewExecution, SavedViewList, SavedViewPresentation, SavedViewProperty, SavedViewSource, SavedViewSourceDocument, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, TypePackManifest, TypePackManifestResource, TypePackInstallResult, TypePackProvision, TypePackResourceDiff, TypePackSourceResource, UnknownConnectProblem } from "@mdbase-dev/connect-protocol";

package/dist/index.js

@@ -1,8 +1,11 @@
 export { decryptRelayResponse, encryptRelayRequest, IndexedDbGrantKeyStore, MemoryGrantKeyStore, RelayCryptoError } from "./crypto.js";
 export { FileTransferCryptoError, GrantFileTransferCipher } from "./file-crypto.js";
+export { deriveFirstContactSas, FirstContactCryptoError } from "./first-contact.js";
+export { applicationInstallationId, authorizationSigningMessage, signApplicationAuthorization } from "./application-identity.js";
 export * from "./authorization-types.js";
 export * from "./collection-client.js";
-export * from "./connect.js";
+export * from "./connect-options.js";
+export * from "./mdbase-connect.js";
 export * from "./connection.js";
 export * from "./connection-types.js";
 export * from "./errors.js";

package/dist/internal-types.d.ts

@@ -1,12 +1,14 @@
-import type { ApplicationNotifications, CollectionOperation, EncryptedRelayOperationRequest, GrantEncryption, FileCapability, GrantScope } from "@mdbase-dev/connect-protocol";
+import type { ApplicationNotifications, ApplicationRequirements, CollectionOperation, EncryptedRelayOperationRequest, GrantEncryption, FileCapability, GrantScope } from "@mdbase-dev/connect-protocol";
 import { encryptRelayRequest } from "./crypto.js";
 export interface Application {
     id: string;
+    manifest_digest: string;
     name: string;
     distribution?: "web" | "portable";
     homepage?: string;
     project_url?: string;
     notifications?: ApplicationNotifications;
+    requirements: ApplicationRequirements;
 }
 export interface StoredAuthorization {
     version: 1;
@@ -18,6 +20,8 @@ export interface StoredAuthorization {
     collectionId?: string;
     returnTo?: string;
     keyHandle?: string;
+    installationKeyHandle?: string;
+    authorizationId?: string;
     applicationAgreementPublicKey?: string;
     applicationSigningPublicKey?: string;
 }

package/dist/mdbase-connect.d.ts

@@ -0,0 +1,21 @@
+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 { MdbaseSession, type MdbaseSessionOptions, type MdbaseUnavailableReason } from "./session.js";
+import type { Application } from "./internal-types.js";
+export declare class MdbaseConnect<Frontmatter extends JsonObject = JsonObject> {
+    private readonly internals;
+    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>>;
+    connections(): MdbaseConnectionInfo[];
+    connection(collectionId: string): MdbaseConnection<Frontmatter> | null;
+    unavailableReason(collectionId: string): MdbaseUnavailableReason | null;
+    onConnectionsChange(listener: (connections: MdbaseConnectionInfo[]) => void): () => void;
+    forgetAll(): void;
+}

package/dist/mdbase-connect.js

@@ -0,0 +1,42 @@
+import { MdbaseConnectInternals } from "./connect.js";
+import { defaultCallbackUrl } from "./runtime-utils.js";
+import { AUTHORIZATION_PROBLEM_CODES, REGISTRATION_PROBLEM_CODES, captureConnectOutcome } from "./outcomes.js";
+import { MdbaseSession } from "./session.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();
+        }
+    }
+}

package/dist/outcomes.d.ts

@@ -18,14 +18,14 @@ export declare const COMMON_OPERATION_PROBLEM_CODES: readonly ["access_denied",
 export declare const ALL_CONNECT_PROBLEM_CODES: ConnectProblemCode[];
 export type RegistrationProblemCode = "discovery_failed" | "invalid_application_manifest" | "invalid_request" | "manifest_load_failed" | "rate_limited" | "temporarily_unavailable" | "timeout";
 export declare const REGISTRATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout"];
-export type AuthorizationProblemCode = RegistrationProblemCode | "access_denied" | "approval_window_blocked" | "authorization_cancelled" | "browser_required" | "collection_access_denied" | "collection_configuration_invalid" | "collection_contracts_missing" | "collection_incompatible" | "collection_invalid" | "collection_kind_unsupported" | "collection_mismatch" | "collection_not_found" | "collection_type_registry_invalid" | "collection_version_unsupported" | "connector_identity_changed" | "connector_offline" | "connector_upgrade_required" | "device_authorization_failed" | "encryption_required" | "expired_token" | "invalid_callback" | "invalid_device_authorization_response" | "invalid_token_response" | "scope_denied" | "token_exchange_failed";
-export declare const AUTHORIZATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "approval_window_blocked", "authorization_cancelled", "browser_required", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "encryption_required", "expired_token", "invalid_callback", "invalid_device_authorization_response", "invalid_token_response", "scope_denied", "token_exchange_failed"];
+export type AuthorizationProblemCode = RegistrationProblemCode | "access_denied" | "approval_window_blocked" | "authorization_cancelled" | "browser_required" | "collection_access_denied" | "collection_configuration_invalid" | "collection_contracts_missing" | "collection_incompatible" | "collection_invalid" | "collection_kind_unsupported" | "collection_mismatch" | "collection_not_found" | "collection_type_registry_invalid" | "collection_version_unsupported" | "connector_identity_changed" | "connector_offline" | "connector_upgrade_required" | "device_authorization_failed" | "encryption_required" | "expired_token" | "first_contact_handler_required" | "invalid_callback" | "invalid_device_authorization_response" | "invalid_first_contact" | "invalid_token_response" | "scope_denied" | "token_exchange_failed";
+export declare const AUTHORIZATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "approval_window_blocked", "authorization_cancelled", "browser_required", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "encryption_required", "expired_token", "first_contact_handler_required", "invalid_callback", "invalid_device_authorization_response", "invalid_first_contact", "invalid_token_response", "scope_denied", "token_exchange_failed"];
 export type NotificationProblemCode = RegistrationProblemCode | "authorization_expired" | "invalid_push_subscription" | "managed_fcm_not_declared" | "not_authorized" | "notification_criterion_not_declared" | "notification_reauthorization_required" | "notification_registration_failed" | "notification_unregistration_failed" | "notifications_not_declared" | "notifications_unavailable";
 export declare const NOTIFICATION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "authorization_expired", "invalid_push_subscription", "managed_fcm_not_declared", "not_authorized", "notification_criterion_not_declared", "notification_reauthorization_required", "notification_registration_failed", "notification_unregistration_failed", "notifications_not_declared", "notifications_unavailable"];
 export type DirectAccessProblemCode = "connector_offline" | "connector_upgrade_required" | "invalid_operation_response" | "not_authorized" | "operation_failed" | "temporarily_unavailable" | "timeout";
 export declare const DIRECT_ACCESS_PROBLEM_CODES: readonly ["connector_offline", "connector_upgrade_required", "invalid_operation_response", "not_authorized", "operation_failed", "temporarily_unavailable", "timeout"];
 export type SessionProblemCode = AuthorizationProblemCode | "collection_not_ready" | "collection_not_selected" | "unknown_collection";
-export declare const SESSION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "approval_window_blocked", "authorization_cancelled", "browser_required", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "encryption_required", "expired_token", "invalid_callback", "invalid_device_authorization_response", "invalid_token_response", "scope_denied", "token_exchange_failed", "collection_not_ready", "collection_not_selected", "unknown_collection"];
+export declare const SESSION_PROBLEM_CODES: readonly ["discovery_failed", "invalid_application_manifest", "invalid_request", "manifest_load_failed", "rate_limited", "temporarily_unavailable", "timeout", "access_denied", "approval_window_blocked", "authorization_cancelled", "browser_required", "collection_access_denied", "collection_configuration_invalid", "collection_contracts_missing", "collection_incompatible", "collection_invalid", "collection_kind_unsupported", "collection_mismatch", "collection_not_found", "collection_type_registry_invalid", "collection_version_unsupported", "connector_identity_changed", "connector_offline", "connector_upgrade_required", "device_authorization_failed", "encryption_required", "expired_token", "first_contact_handler_required", "invalid_callback", "invalid_device_authorization_response", "invalid_first_contact", "invalid_token_response", "scope_denied", "token_exchange_failed", "collection_not_ready", "collection_not_selected", "unknown_collection"];
 export type CollectionSetupProblemCode = "collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported";
 export type CollectionDescriptionProblemCode = CommonOperationProblemCode | CollectionSetupProblemCode;
 export type CollectionReadProblemCode = CollectionDescriptionProblemCode | "invalid_path" | "operation_invalid";

package/dist/outcomes.js

@@ -60,8 +60,10 @@ export const AUTHORIZATION_PROBLEM_CODES = [
     "device_authorization_failed",
     "encryption_required",
     "expired_token",
+    "first_contact_handler_required",
     "invalid_callback",
     "invalid_device_authorization_response",
+    "invalid_first_contact",
     "invalid_token_response",
     "scope_denied",
     "token_exchange_failed"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect",
-  "version": "0.1.0-beta.23",
+  "version": "0.1.0-beta.24",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.23"
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.24"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",