@mdbase-dev/connect 0.1.0-beta.100

package/dist/crypto.js

@@ -0,0 +1,409 @@
+import { OPERATION_TRANSPORT_PROTOCOL_VERSION, GRANT_ENCRYPTION_PROTOCOL_VERSION, AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_HEADERS, AUTHORITY_PROOF_VERSION, RELAY_ENCRYPTION_SUITE, isConnectProblem } from "@mdbase-dev/connect-protocol";
+const DATABASE_NAME = "mdbase-connect-keys";
+const STORE_NAME = "grant-keys";
+const MAX_U64 = 18446744073709551615n;
+const REQUEST_INFO = "mdbase-connect relay request key v1";
+const RESPONSE_INFO = "mdbase-connect relay response key v1";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Origin-scoped storage for non-extractable grant keys and atomic counters. */
+export class IndexedDbGrantKeyStore {
+    database = null;
+    async create(handle) {
+        const record = await generateGrantKey(handle);
+        const database = await this.open();
+        await idbWrite(database, (store) => store.add({ ...record, counter: "0" }));
+        return record;
+    }
+    async get(handle) {
+        const database = await this.open();
+        const value = await idbRequest(database.transaction(STORE_NAME).objectStore(STORE_NAME).get(handle));
+        return value ? {
+            handle: value.handle,
+            agreementPrivateKey: value.agreementPrivateKey,
+            agreementPublicKey: value.agreementPublicKey,
+            signingPrivateKey: value.signingPrivateKey,
+            signingPublicKey: value.signingPublicKey
+        } : null;
+    }
+    async nextCounter(handle) {
+        const database = await this.open();
+        return new Promise((resolve, reject) => {
+            const transaction = database.transaction(STORE_NAME, "readwrite");
+            const store = transaction.objectStore(STORE_NAME);
+            const request = store.get(handle);
+            let next = null;
+            request.onerror = () => reject(request.error);
+            request.onsuccess = () => {
+                const record = request.result;
+                if (!record) {
+                    transaction.abort();
+                    reject(new RelayCryptoError("missing_grant_key", "The encrypted grant key is unavailable."));
+                    return;
+                }
+                const counter = BigInt(record.counter) + 1n;
+                if (counter > MAX_U64) {
+                    transaction.abort();
+                    reject(new RelayCryptoError("counter_exhausted", "The encrypted grant must be authorized again."));
+                    return;
+                }
+                next = counter.toString();
+                store.put({ ...record, counter: next });
+            };
+            transaction.onerror = () => reject(transaction.error);
+            transaction.onabort = () => reject(transaction.error ?? new Error("Key counter transaction aborted."));
+            transaction.oncomplete = () => {
+                if (next)
+                    resolve(next);
+            };
+        });
+    }
+    async delete(handle) {
+        const database = await this.open();
+        await idbWrite(database, (store) => store.delete(handle));
+    }
+    open() {
+        if (typeof indexedDB === "undefined") {
+            throw new RelayCryptoError("key_storage_unavailable", "Encrypted relay authorization requires browser IndexedDB or an injected grant key store.");
+        }
+        if (!this.database) {
+            this.database = new Promise((resolve, reject) => {
+                const request = indexedDB.open(DATABASE_NAME, 1);
+                request.onupgradeneeded = () => {
+                    if (!request.result.objectStoreNames.contains(STORE_NAME)) {
+                        request.result.createObjectStore(STORE_NAME, { keyPath: "handle" });
+                    }
+                };
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => resolve(request.result);
+            });
+        }
+        return this.database;
+    }
+}
+/** Deterministic process-local storage for tests, CLIs, and non-browser adapters. */
+export class MemoryGrantKeyStore {
+    records = new Map();
+    sequence = Promise.resolve();
+    async create(handle) {
+        if (this.records.has(handle))
+            throw new Error(`Grant key already exists: ${handle}`);
+        const record = await generateGrantKey(handle);
+        this.records.set(handle, { ...record, counter: "0" });
+        return record;
+    }
+    async get(handle) {
+        const value = this.records.get(handle);
+        return value ? {
+            handle: value.handle,
+            agreementPrivateKey: value.agreementPrivateKey,
+            agreementPublicKey: value.agreementPublicKey,
+            signingPrivateKey: value.signingPrivateKey,
+            signingPublicKey: value.signingPublicKey
+        } : null;
+    }
+    nextCounter(handle) {
+        let resolve;
+        let reject;
+        const result = new Promise((res, rej) => { resolve = res; reject = rej; });
+        this.sequence = this.sequence.then(() => {
+            const record = this.records.get(handle);
+            if (!record)
+                throw new RelayCryptoError("missing_grant_key", "The encrypted grant key is unavailable.");
+            const counter = BigInt(record.counter) + 1n;
+            if (counter > MAX_U64)
+                throw new RelayCryptoError("counter_exhausted", "The encrypted grant must be authorized again.");
+            record.counter = counter.toString();
+            resolve(record.counter);
+        }).catch((error) => {
+            reject(error);
+        });
+        return result;
+    }
+    async delete(handle) {
+        this.records.delete(handle);
+    }
+}
+/** Sign one remote-authority or token-refresh request with the approved grant key. */
+export async function signAuthorityRequest(store, handle, expectedPublicKey, input) {
+    const record = await requireSigningKey(store, handle, expectedPublicKey);
+    const timestamp = input.timestamp ?? Math.floor(Date.now() / 1_000);
+    const nonce = input.nonce ?? crypto.randomUUID();
+    const message = await authorityProofMessage({ ...input, timestamp, nonce });
+    const signature = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, record.signingPrivateKey, new TextEncoder().encode(message));
+    return {
+        [AUTHORITY_PROOF_HEADERS.version]: String(AUTHORITY_PROOF_VERSION),
+        [AUTHORITY_PROOF_HEADERS.timestamp]: String(timestamp),
+        [AUTHORITY_PROOF_HEADERS.nonce]: nonce,
+        [AUTHORITY_PROOF_HEADERS.signature]: bytesToBase64Url(new Uint8Array(signature))
+    };
+}
+export async function authorityProofMessage(input) {
+    const method = input.method.toUpperCase();
+    const bodyHash = await sha256Base64Url(input.body ?? "");
+    const credentialHash = await sha256Base64Url(input.credential);
+    for (const value of [method, input.target, String(input.timestamp), input.nonce]) {
+        if (!value || value.includes("\n") || value.includes("\r")) {
+            throw new RelayCryptoError("invalid_proof_input", "Authority request proof metadata is invalid.");
+        }
+    }
+    return [
+        AUTHORITY_PROOF_DOMAIN,
+        AUTHORITY_PROOF_VERSION,
+        method,
+        input.target,
+        bodyHash,
+        credentialHash,
+        input.timestamp,
+        input.nonce
+    ].join("\n");
+}
+export async function encryptRelayRequest(store, handle, binding, operation, input, requestId = crypto.randomUUID(), deadlineUnixMs) {
+    validateGrantEncryption(binding.encryption);
+    if (deadlineUnixMs !== undefined
+        && (!Number.isSafeInteger(deadlineUnixMs) || deadlineUnixMs <= 0)) {
+        throw new RelayCryptoError("invalid_deadline", "The operation deadline is invalid.");
+    }
+    const record = await requireAgreementKey(store, handle, binding.encryption.application_agreement_public_key);
+    const counter = await store.nextCounter(handle);
+    const metadata = {
+        binding,
+        protocolVersion: OPERATION_TRANSPORT_PROTOCOL_VERSION,
+        requestId,
+        operation,
+        counter
+    };
+    const key = await deriveDirectionalKey(record.agreementPrivateKey, binding, metadata.protocolVersion, "request");
+    const plaintext = new TextEncoder().encode(JSON.stringify(input ?? {}));
+    const ciphertext = await crypto.subtle.encrypt({
+        name: "AES-GCM",
+        iv: nonce(counter),
+        additionalData: new TextEncoder().encode(aad(metadata, "request")),
+        tagLength: 128
+    }, key, plaintext);
+    return {
+        type: "encrypted_operation_request",
+        ...envelopeMetadata(metadata),
+        ...(deadlineUnixMs === undefined ? {} : { deadline_unix_ms: deadlineUnixMs }),
+        ciphertext: bytesToBase64Url(new Uint8Array(ciphertext))
+    };
+}
+export async function decryptRelayResponse(store, handle, binding, request, response) {
+    if (!sameEnvelopeMetadata(request, response)) {
+        throw new RelayCryptoError("invalid_encrypted_response", "Encrypted response metadata does not match its request.");
+    }
+    const record = await requireAgreementKey(store, handle, binding.encryption.application_agreement_public_key);
+    const metadata = {
+        binding,
+        protocolVersion: request.protocol_version,
+        requestId: request.request_id,
+        operation: request.operation,
+        counter: request.counter
+    };
+    const key = await deriveDirectionalKey(record.agreementPrivateKey, binding, request.protocol_version, "response");
+    try {
+        const plaintext = await crypto.subtle.decrypt({
+            name: "AES-GCM",
+            iv: nonce(request.counter),
+            additionalData: new TextEncoder().encode(aad(metadata, "response")),
+            tagLength: 128
+        }, key, toArrayBuffer(base64UrlToBytes(response.ciphertext)));
+        const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(plaintext));
+        if (value?.ok === true && "result" in value)
+            return value;
+        if (value?.ok === false && isConnectProblem(value.problem))
+            return value;
+        throw new Error("invalid response body");
+    }
+    catch (error) {
+        if (error instanceof RelayCryptoError)
+            throw error;
+        throw new RelayCryptoError("encrypted_response_rejected", "The encrypted connector response could not be authenticated.");
+    }
+}
+export class RelayCryptoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+async function generateGrantKey(handle) {
+    const agreement = await crypto.subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
+    const agreementPublicKey = bytesToBase64Url(new Uint8Array(await crypto.subtle.exportKey("raw", agreement.publicKey)));
+    const agreementPkcs8 = await crypto.subtle.exportKey("pkcs8", agreement.privateKey);
+    const agreementPrivateKey = await crypto.subtle.importKey("pkcs8", agreementPkcs8, { name: "ECDH", namedCurve: "P-256" }, false, ["deriveBits"]);
+    const signing = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+    const signingPublicKey = bytesToBase64Url(new Uint8Array(await crypto.subtle.exportKey("raw", signing.publicKey)));
+    const signingPkcs8 = await crypto.subtle.exportKey("pkcs8", signing.privateKey);
+    const signingPrivateKey = await crypto.subtle.importKey("pkcs8", signingPkcs8, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+    return {
+        handle,
+        agreementPrivateKey,
+        agreementPublicKey,
+        signingPrivateKey,
+        signingPublicKey
+    };
+}
+async function requireAgreementKey(store, handle, expectedPublicKey) {
+    const record = await store.get(handle);
+    if (!record || record.agreementPublicKey !== expectedPublicKey) {
+        throw new RelayCryptoError("missing_grant_key", "The encrypted grant key is unavailable or does not match the grant.");
+    }
+    return record;
+}
+async function requireSigningKey(store, handle, expectedPublicKey) {
+    const record = await store.get(handle);
+    if (!record || record.signingPublicKey !== expectedPublicKey) {
+        throw new RelayCryptoError("missing_grant_key", "The remote authority signing key is unavailable or does not match the grant.");
+    }
+    return record;
+}
+async function deriveDirectionalKey(privateKey, binding, protocolVersion, direction) {
+    const shared = await deriveP256SharedSecret(privateKey, binding.encryption.connector_agreement_public_key);
+    const material = await crypto.subtle.importKey("raw", shared, "HKDF", false, ["deriveKey"]);
+    const contextBytes = new TextEncoder().encode(context(binding, protocolVersion));
+    const salt = await crypto.subtle.digest("SHA-256", contextBytes);
+    return crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt,
+        info: new TextEncoder().encode(direction === "request" ? REQUEST_INFO : RESPONSE_INFO)
+    }, material, { name: "AES-GCM", length: 256 }, false, direction === "request" ? ["encrypt"] : ["decrypt"]);
+}
+/** @internal Shared ECDH primitive used by the independently keyed file data plane. */
+export async function deriveP256SharedSecret(privateKey, peerPublicKey) {
+    try {
+        const peer = await crypto.subtle.importKey("raw", toArrayBuffer(p256PublicKey(peerPublicKey)), { name: "ECDH", namedCurve: "P-256" }, false, []);
+        return await crypto.subtle.deriveBits({ name: "ECDH", public: peer }, privateKey, 256);
+    }
+    catch {
+        throw new RelayCryptoError("invalid_public_key", "The connector relay public key is invalid.");
+    }
+}
+function context(binding, protocolVersion) {
+    const value = binding.encryption;
+    return [
+        "mdbase-connect",
+        protocolVersion,
+        value.suite,
+        binding.grantId,
+        binding.applicationId,
+        value.connector_id,
+        value.collection_id,
+        value.scope_epoch,
+        value.key_id
+    ].join("|");
+}
+function aad(metadata, direction) {
+    return [
+        context(metadata.binding, metadata.protocolVersion),
+        metadata.requestId,
+        direction,
+        metadata.operation,
+        metadata.counter
+    ].join("|");
+}
+function envelopeMetadata(metadata) {
+    const encryption = metadata.binding.encryption;
+    return {
+        protocol_version: metadata.protocolVersion,
+        suite: RELAY_ENCRYPTION_SUITE,
+        request_id: metadata.requestId,
+        grant_id: metadata.binding.grantId,
+        application_id: metadata.binding.applicationId,
+        connector_id: encryption.connector_id,
+        collection_id: encryption.collection_id,
+        operation: metadata.operation,
+        scope_epoch: encryption.scope_epoch,
+        key_id: encryption.key_id,
+        counter: metadata.counter
+    };
+}
+function sameEnvelopeMetadata(request, response) {
+    return response.type === "encrypted_operation_response"
+        && typeof response.ciphertext === "string"
+        && request.protocol_version === response.protocol_version
+        && request.suite === response.suite
+        && request.request_id === response.request_id
+        && request.grant_id === response.grant_id
+        && request.application_id === response.application_id
+        && request.connector_id === response.connector_id
+        && request.collection_id === response.collection_id
+        && request.operation === response.operation
+        && request.scope_epoch === response.scope_epoch
+        && request.key_id === response.key_id
+        && request.counter === response.counter;
+}
+export function validateGrantEncryption(encryption) {
+    if (encryption.protocol_version !== GRANT_ENCRYPTION_PROTOCOL_VERSION
+        || encryption.suite !== RELAY_ENCRYPTION_SUITE
+        || !Number.isSafeInteger(encryption.scope_epoch)
+        || encryption.scope_epoch <= 0
+        || typeof encryption.key_id !== "string"
+        || encryption.key_id.length === 0
+        || encryption.key_id.length > 200
+        || encryption.key_id.includes("|")) {
+        throw new RelayCryptoError("unsupported_encryption", "The grant uses an unsupported relay encryption profile.");
+    }
+    if (typeof encryption.connector_id !== "string"
+        || !UUID_PATTERN.test(encryption.connector_id)
+        || typeof encryption.collection_id !== "string"
+        || !UUID_PATTERN.test(encryption.collection_id)) {
+        throw new RelayCryptoError("unsupported_encryption", "The grant uses invalid encrypted relay identities.");
+    }
+    p256PublicKey(encryption.application_agreement_public_key);
+    p256PublicKey(encryption.connector_agreement_public_key);
+}
+function nonce(counter) {
+    const value = BigInt(counter);
+    if (value <= 0n || value > MAX_U64 || value.toString() !== counter) {
+        throw new RelayCryptoError("invalid_counter", "The encrypted relay counter is invalid.");
+    }
+    const result = new Uint8Array(new ArrayBuffer(12));
+    const view = new DataView(result.buffer);
+    view.setBigUint64(4, value, false);
+    return result;
+}
+function bytesToBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+async function sha256Base64Url(value) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return bytesToBase64Url(new Uint8Array(digest));
+}
+function base64UrlToBytes(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new RelayCryptoError("invalid_base64", "Encrypted relay data is malformed.");
+    const padding = "=".repeat((4 - value.length % 4) % 4);
+    const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/") + padding);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function p256PublicKey(value) {
+    const bytes = base64UrlToBytes(value);
+    if (bytes.length !== 65 || bytes[0] !== 4) {
+        throw new RelayCryptoError("invalid_public_key", "Encrypted relay public keys must be uncompressed P-256 points.");
+    }
+    return bytes;
+}
+function toArrayBuffer(value) {
+    return Uint8Array.from(value).buffer;
+}
+function idbRequest(request) {
+    return new Promise((resolve, reject) => {
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+    });
+}
+function idbWrite(database, operation) {
+    return new Promise((resolve, reject) => {
+        const transaction = database.transaction(STORE_NAME, "readwrite");
+        const request = operation(transaction.objectStore(STORE_NAME));
+        request.onerror = () => reject(request.error);
+        transaction.onerror = () => reject(transaction.error);
+        transaction.onabort = () => reject(transaction.error ?? new Error("Grant key transaction aborted."));
+        transaction.oncomplete = () => resolve();
+    });
+}

package/dist/direct-access.d.ts

@@ -0,0 +1,3 @@
+import type { StoredToken } from "./internal-types.js";
+export declare function tokenSupportsDirectAccess(token: StoredToken | null, mode: "auto" | "disabled"): boolean;
+export declare function probeLoopbackAccess(loopbackUrl: string, expectedOperationProtocol: number, signal?: AbortSignal): Promise<boolean>;

package/dist/direct-access.js

@@ -0,0 +1,29 @@
+import { loopbackRequest } from "./operation-helpers.js";
+import { decodeJsonResponse } from "./runtime-utils.js";
+export function tokenSupportsDirectAccess(token, mode) {
+    if (!token || token.authority || !token.encryption || !token.grantId || !token.keyHandle) {
+        return false;
+    }
+    if (mode === "disabled")
+        return false;
+    return typeof location === "undefined"
+        || !token.applicationOrigin
+        || token.applicationOrigin === location.origin;
+}
+export async function probeLoopbackAccess(loopbackUrl, expectedOperationProtocol, signal) {
+    try {
+        const response = await fetch(`${loopbackUrl}/v1/ready`, loopbackRequest({
+            method: "GET",
+            cache: "no-store",
+            signal
+        }));
+        const body = await decodeJsonResponse(response, "invalid_operation_response", "The connector returned an invalid readiness response.").catch(() => null);
+        return response.ok
+            && body?.service === "mdbase-connect"
+            && body?.loopback_protocol_version === 1
+            && body?.operation_transport_protocol_version === expectedOperationProtocol;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+import { type ConnectOperationOutcome, type ConnectProblem, type ConnectProblemCode, type ConnectProblemDetailsByCode, type KnownConnectProblem, type MdbaseOperationEnvelope } from "@mdbase-dev/connect-protocol";
+interface ProblemOptions {
+    operationOutcome?: ConnectOperationOutcome;
+    traceId?: string;
+    status?: number;
+    cause?: unknown;
+}
+type ProblemOptionsFor<Code extends ConnectProblemCode> = ConnectProblemDetailsByCode[Code] extends undefined ? ProblemOptions & {
+    details?: never;
+} : {} extends ConnectProblemDetailsByCode[Code] ? ProblemOptions & {
+    details?: ConnectProblemDetailsByCode[Code];
+} : ProblemOptions & {
+    details: ConnectProblemDetailsByCode[Code];
+};
+type ProblemArguments<Code extends ConnectProblemCode> = ConnectProblemDetailsByCode[Code] extends undefined ? [options?: ProblemOptionsFor<Code>] : {} extends ConnectProblemDetailsByCode[Code] ? [options?: ProblemOptionsFor<Code>] : [options: ProblemOptionsFor<Code>];
+export interface ConnectErrorContext {
+    status?: number;
+    cause?: unknown;
+}
+/** Internal carrier used while adapting throwing transports into public outcomes. */
+export declare class MdbaseConnectError extends Error {
+    readonly problem: ConnectProblem;
+    readonly code: ConnectProblem["code"];
+    readonly status?: number;
+    constructor(problem: ConnectProblem, context?: ConnectErrorContext);
+    get retryable(): boolean;
+    get requiresAuthorization(): boolean;
+    get outcomeUnknown(): boolean;
+    get recovery(): "choose_collection" | "contact_support" | "fix_request" | "none" | "reauthorize" | "refresh" | "repair_collection" | "resolve_conflict" | "resolve_outcome" | "resume_connector_access" | "retry" | "upgrade_application" | "upgrade_collection" | "upgrade_connector";
+    get details(): unknown;
+}
+export declare function connectProblem<Code extends ConnectProblemCode>(code: Code, message: string, ...[options]: ProblemArguments<Code>): KnownConnectProblem<Code>;
+export declare function unknownConnectProblem(serverCode: string, message: string, options?: ProblemOptions & {
+    details?: unknown;
+}): ConnectProblem;
+export declare function connectError<Code extends ConnectProblemCode>(code: Code, message: string, ...args: ProblemArguments<Code>): MdbaseConnectError;
+export declare function serverConnectError(serverCode: string, message: string, options?: ProblemOptions & {
+    details?: unknown;
+    status?: number;
+    cause?: unknown;
+}): MdbaseConnectError;
+export declare function operationProblem<Result>(envelope: MdbaseOperationEnvelope<Result>): KnownConnectProblem<"collection_configuration_invalid" | "collection_invalid" | "collection_type_registry_invalid" | "collection_version_unsupported" | "operation_invalid">;
+/** True only when repeating an operation is safe without asking the user. */
+export declare function isRetryableConnectError(error: unknown): boolean;
+export {};

package/dist/errors.js

@@ -0,0 +1,142 @@
+import { CONNECT_PROBLEM_CATALOG, CONNECT_PROBLEM_VERSION, normalizeConnectProblem } from "@mdbase-dev/connect-protocol";
+/** Internal carrier used while adapting throwing transports into public outcomes. */
+export class MdbaseConnectError extends Error {
+    problem;
+    code;
+    status;
+    constructor(problem, context = {}) {
+        super(problem.message, context.cause === undefined ? undefined : { cause: context.cause });
+        this.problem = problem;
+        this.name = "MdbaseConnectError";
+        this.code = problem.code;
+        this.status = context.status;
+    }
+    get retryable() {
+        return this.problem.recovery === "retry"
+            && this.problem.operation_outcome !== "unknown";
+    }
+    get requiresAuthorization() {
+        return this.problem.category === "authorization";
+    }
+    get outcomeUnknown() {
+        return this.problem.operation_outcome === "unknown";
+    }
+    get recovery() {
+        return this.problem.recovery;
+    }
+    get details() {
+        return this.problem.details;
+    }
+}
+export function connectProblem(code, message, ...[options = {}]) {
+    const definition = CONNECT_PROBLEM_CATALOG[code];
+    return {
+        problem_version: CONNECT_PROBLEM_VERSION,
+        code,
+        category: definition.category,
+        recovery: definition.recovery,
+        message,
+        ...(options.details === undefined ? {} : { details: options.details }),
+        ...(options.operationOutcome === undefined
+            ? {}
+            : { operation_outcome: options.operationOutcome }),
+        ...(options.traceId === undefined ? {} : { trace_id: options.traceId })
+    };
+}
+export function unknownConnectProblem(serverCode, message, options = {}) {
+    return normalizeConnectProblem(serverCode, message, {
+        details: options.details,
+        operation_outcome: options.operationOutcome,
+        trace_id: options.traceId
+    });
+}
+export function connectError(code, message, ...args) {
+    const options = args[0];
+    return new MdbaseConnectError(connectProblem(code, message, ...args), {
+        status: options?.status,
+        cause: options?.cause
+    });
+}
+export function serverConnectError(serverCode, message, options = {}) {
+    const { status, cause, ...problemOptions } = options;
+    return new MdbaseConnectError(normalizeConnectProblem(serverCode, message, {
+        details: problemOptions.details,
+        operation_outcome: problemOptions.operationOutcome,
+        trace_id: problemOptions.traceId
+    }), { status, cause });
+}
+export function operationProblem(envelope) {
+    const code = diagnosticProblemCode(envelope.diagnostics);
+    const message = diagnosticMessage(envelope.diagnostics);
+    if (code === "collection_version_unsupported") {
+        const versions = diagnosticVersions(envelope.diagnostics);
+        return connectProblem(code, message, {
+            operationOutcome: "rejected",
+            details: versions
+        });
+    }
+    if (code !== "operation_invalid") {
+        return connectProblem(code, message, {
+            operationOutcome: "rejected",
+            details: { diagnostics: envelope.diagnostics }
+        });
+    }
+    return connectProblem(code, message, {
+        operationOutcome: "rejected",
+        details: {
+            diagnostics: envelope.diagnostics,
+            partial_result: envelope.result
+        }
+    });
+}
+function diagnosticProblemCode(diagnostics) {
+    const codes = new Set(diagnostics
+        .filter((diagnostic) => diagnostic.severity === "error")
+        .map((diagnostic) => diagnostic.code));
+    if (["migration_required", "migration_lossy", "unsupported_version"]
+        .some((code) => codes.has(code)))
+        return "collection_version_unsupported";
+    if (["invalid_config", "invalid_configuration", "missing_config", "missing_spec_version"]
+        .some((code) => codes.has(code)))
+        return "collection_configuration_invalid";
+    if ([
+        "duplicate_type",
+        "invalid_contract_definition",
+        "invalid_data_contract",
+        "invalid_type_definition",
+        "invalid_type_path"
+    ].some((code) => codes.has(code)))
+        return "collection_type_registry_invalid";
+    if (["collection_invalid", "collection_open_failed"]
+        .some((code) => codes.has(code)))
+        return "collection_invalid";
+    return "operation_invalid";
+}
+function diagnosticVersions(diagnostics) {
+    const source = diagnostics
+        .map((diagnostic) => diagnostic.details)
+        .find((details) => isRecord(details));
+    return {
+        current_version: typeof source?.current_version === "string"
+            ? source.current_version
+            : "0.2.x",
+        required_version: typeof source?.required_version === "string"
+            ? source.required_version
+            : "0.3.0"
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** True only when repeating an operation is safe without asking the user. */
+export function isRetryableConnectError(error) {
+    return error instanceof MdbaseConnectError && error.retryable;
+}
+function diagnosticMessage(diagnostics) {
+    return diagnostics
+        .filter((item) => item.severity === "error")
+        .map((item) => item.message)
+        .join(" ")
+        || diagnostics.map((item) => item.message).join(" ")
+        || "The collection rejected this operation.";
+}

package/dist/external-store.d.ts

@@ -0,0 +1,10 @@
+/** Minimal framework-neutral shape consumed by React's useSyncExternalStore. */
+export interface MdbaseExternalStore<Snapshot> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): Snapshot;
+}
+/**
+ * Adapt an existing SDK session without introducing another cache or state
+ * owner. The stable object can be passed directly to useSyncExternalStore.
+ */
+export declare function externalStore<Snapshot>(source: MdbaseExternalStore<Snapshot>): MdbaseExternalStore<Snapshot>;

package/dist/external-store.js

@@ -0,0 +1,10 @@
+/**
+ * Adapt an existing SDK session without introducing another cache or state
+ * owner. The stable object can be passed directly to useSyncExternalStore.
+ */
+export function externalStore(source) {
+    return {
+        subscribe: (listener) => source.subscribe(listener),
+        getSnapshot: () => source.getSnapshot()
+    };
+}