@mdbase-dev/connect-protocol 0.1.0-beta.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdbase connect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/application-authorization.d.ts

@@ -0,0 +1,32 @@
+import type { ApplicationFileRequest } from "./files.js";
+import { type CollectionOperation } from "./operations.js";
+import type { AuthorizationBindingProtocolVersion, ConnectContractRequirements } from "./compatibility.js";
+export type ApplicationAuthorizationFlow = "authorization_code" | "device_code";
+export interface ApplicationAuthorizationBinding {
+    protocol_version: AuthorizationBindingProtocolVersion;
+    authorization_id: string;
+    application_id: string;
+    application_declaration_id: string;
+    application_manifest_digest: string;
+    application_installation_id: string;
+    installation_signing_public_key: string;
+    grant_agreement_public_key: string;
+    grant_signing_public_key: string;
+    flow: ApplicationAuthorizationFlow;
+    authorization_nonce: string;
+    issued_at: string;
+    expires_at: string;
+    redirect_uri?: string;
+    state?: string;
+    code_challenge: string;
+    contracts: ConnectContractRequirements;
+    requested_operations: CollectionOperation[];
+    requested_files?: ApplicationFileRequest;
+    collection_id?: string;
+}
+export interface ApplicationAuthorizationProof {
+    binding: ApplicationAuthorizationBinding;
+    signature: string;
+}
+export declare function applicationInstallationIdFromPublicKey(signingPublicKey: string): Promise<string>;
+export declare function authorizationSigningMessage(binding: ApplicationAuthorizationBinding): Uint8Array;

package/dist/application-authorization.js

@@ -0,0 +1,207 @@
+import { isMutatingOperation } from "./operations.js";
+import { AUTHORIZATION_BINDING_PROTOCOL_VERSION, LEGACY_AUTHORIZATION_BINDING_PROTOCOL_VERSION, OPERATION_TRANSPORT_PROTOCOL_VERSION, isSupportedAuthorizationBinding, isSupportedOperationTransport } from "./compatibility.js";
+const INSTALLATION_ID_DOMAIN = new TextEncoder().encode("mdbase-connect application installation id v2\0");
+const AUTHORIZATION_PROOF_V4_DOMAIN = new TextEncoder().encode("mdbase-connect application authorization proof v4\0");
+const AUTHORIZATION_PROOF_V5_DOMAIN = new TextEncoder().encode("mdbase-connect application authorization proof v5\0");
+export async function applicationInstallationIdFromPublicKey(signingPublicKey) {
+    const signing = publicKey(signingPublicKey);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", concat([INSTALLATION_ID_DOMAIN, field(signing)])));
+    const id = digest.slice(0, 16);
+    id[6] = (id[6] & 0x0f) | 0x80;
+    id[8] = (id[8] & 0x3f) | 0x80;
+    return [
+        hex(id.slice(0, 4)),
+        hex(id.slice(4, 6)),
+        hex(id.slice(6, 8)),
+        hex(id.slice(8, 10)),
+        hex(id.slice(10, 16))
+    ].join("-");
+}
+export function authorizationSigningMessage(binding) {
+    const keys = [
+        publicKey(binding.installation_signing_public_key),
+        publicKey(binding.grant_agreement_public_key),
+        publicKey(binding.grant_signing_public_key)
+    ];
+    if (keys.some((key, index) => keys.slice(index + 1).some((other) => equalBytes(key, other)))) {
+        throw new Error("Application authorization keys must be distinct.");
+    }
+    const nonce = canonicalBase64(binding.authorization_nonce);
+    const challenge = canonicalBase64(binding.code_challenge);
+    const contracts = binding.contracts;
+    const recovery = contracts.operation_transport_recovery ?? [];
+    const requiresDurableMutation = binding.requested_operations.some((operation) => isMutatingOperation(operation, { action: "mutate" }))
+        || binding.requested_files?.actions.some((action) => !["list", "read"].includes(action)) === true;
+    if (!isSupportedAuthorizationBinding(binding.protocol_version)
+        || nonce.byteLength !== 32
+        || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/u.test(binding.application_declaration_id)
+        || !/^[0-9a-f]{64}$/u.test(binding.application_manifest_digest)
+        || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/u.test(binding.issued_at)
+        || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/u.test(binding.expires_at)
+        || challenge.byteLength !== 32
+        || ![
+            contracts.operation_transport,
+            contracts.authorization_binding,
+            contracts.semantic_capabilities,
+            contracts.durable_mutation ?? 1
+        ].every((version) => Number.isInteger(version) && version > 0)
+        || contracts.authorization_binding !== binding.protocol_version
+        || !isSupportedOperationTransport(contracts.operation_transport)
+        || (binding.protocol_version === AUTHORIZATION_BINDING_PROTOCOL_VERSION
+            && contracts.operation_transport !== OPERATION_TRANSPORT_PROTOCOL_VERSION)
+        || recovery.some((version) => !isSupportedOperationTransport(version)
+            || version === contracts.operation_transport)
+        || new Set(recovery).size !== recovery.length
+        || (binding.protocol_version === LEGACY_AUTHORIZATION_BINDING_PROTOCOL_VERSION
+            && recovery.length > 0)
+        || (recovery.length > 0 && !requiresDurableMutation)
+        || (requiresDurableMutation
+            ? contracts.durable_mutation !== 1
+            : contracts.durable_mutation !== undefined)
+        || (binding.requested_operations.length === 0 && binding.requested_files === undefined)
+        || new Set(binding.requested_operations).size !== binding.requested_operations.length
+        || binding.requested_operations.some((operation) => !operation || operation.includes("\0"))
+        || (binding.flow === "authorization_code"
+            ? binding.redirect_uri === undefined || binding.state === undefined
+            : binding.flow === "device_code"
+                ? binding.redirect_uri !== undefined || binding.state !== undefined
+                : true)) {
+        throw new Error("Application authorization binding is invalid.");
+    }
+    validateRequestedFiles(binding.requested_files);
+    const operationFields = binding.requested_operations.map((operation) => field(new TextEncoder().encode(operation)));
+    return concat([
+        binding.protocol_version === AUTHORIZATION_BINDING_PROTOCOL_VERSION
+            ? AUTHORIZATION_PROOF_V5_DOMAIN
+            : AUTHORIZATION_PROOF_V4_DOMAIN,
+        u32(binding.protocol_version),
+        field(uuidBytes(binding.application_id)),
+        field(uuidBytes(binding.authorization_id)),
+        field(new TextEncoder().encode(binding.application_declaration_id)),
+        field(hexBytes(binding.application_manifest_digest)),
+        field(uuidBytes(binding.application_installation_id)),
+        ...keys.map(field),
+        field(new TextEncoder().encode(binding.flow)),
+        field(nonce),
+        field(new TextEncoder().encode(binding.issued_at)),
+        field(new TextEncoder().encode(binding.expires_at)),
+        optionalString(binding.redirect_uri),
+        optionalString(binding.state),
+        field(new TextEncoder().encode(binding.code_challenge)),
+        u32(contracts.operation_transport),
+        ...(binding.protocol_version === AUTHORIZATION_BINDING_PROTOCOL_VERSION
+            ? [u32(recovery.length), ...recovery.map(u32)]
+            : []),
+        u32(contracts.authorization_binding),
+        u32(contracts.semantic_capabilities),
+        optionalU32(contracts.durable_mutation),
+        u32(operationFields.length),
+        ...operationFields,
+        requestedFiles(binding.requested_files),
+        optionalUuid(binding.collection_id)
+    ]);
+}
+function optionalU32(value) {
+    return value === undefined
+        ? new Uint8Array(1)
+        : concat([new Uint8Array([1]), u32(value)]);
+}
+function validateRequestedFiles(files) {
+    if (files === undefined)
+        return;
+    if (files.actions.length === 0
+        || new Set(files.actions).size !== files.actions.length
+        || (files.scope.kind === "selected_folders"
+            && (files.scope.folders.length === 0
+                || new Set(files.scope.folders).size !== files.scope.folders.length
+                || files.scope.folders.some((folder) => !folder || folder.includes("\0"))))) {
+        throw new Error("Application authorization file request is invalid.");
+    }
+}
+function requestedFiles(files) {
+    if (files === undefined)
+        return new Uint8Array(1);
+    const actions = files.actions.map((action) => field(new TextEncoder().encode(action)));
+    return concat([
+        new Uint8Array([1]),
+        u32(actions.length),
+        ...actions,
+        field(new TextEncoder().encode(files.scope.kind)),
+        ...(files.scope.kind === "selected_folders"
+            ? [
+                u32(files.scope.folders.length),
+                ...files.scope.folders.map((folder) => field(new TextEncoder().encode(folder)))
+            ]
+            : [])
+    ]);
+}
+function optionalString(value) {
+    return value === undefined
+        ? new Uint8Array(1)
+        : concat([new Uint8Array([1]), field(new TextEncoder().encode(value))]);
+}
+function optionalUuid(value) {
+    return value === undefined
+        ? new Uint8Array(1)
+        : concat([new Uint8Array([1]), field(uuidBytes(value))]);
+}
+function publicKey(value) {
+    const key = canonicalBase64(value);
+    if (key.byteLength !== 65 || key[0] !== 4) {
+        throw new Error("Application authorization public key is invalid.");
+    }
+    return key;
+}
+function canonicalBase64(value) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value))
+        throw new Error("Invalid base64url value.");
+    const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    const decoded = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+    if (base64Url(decoded) !== value)
+        throw new Error("Non-canonical base64url value.");
+    return decoded;
+}
+function uuidBytes(value) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value)) {
+        throw new Error("Invalid UUID value.");
+    }
+    const compact = value.replaceAll("-", "");
+    return hexBytes(compact);
+}
+function hexBytes(value) {
+    if (!/^[0-9a-f]+$/u.test(value) || value.length % 2 !== 0) {
+        throw new Error("Invalid hexadecimal value.");
+    }
+    return Uint8Array.from({ length: value.length / 2 }, (_, index) => Number.parseInt(value.slice(index * 2, index * 2 + 2), 16));
+}
+function field(value) {
+    return concat([u32(value.byteLength), value]);
+}
+function u32(value) {
+    const output = new Uint8Array(4);
+    new DataView(output.buffer).setUint32(0, value, false);
+    return output;
+}
+function concat(values) {
+    const output = new Uint8Array(values.reduce((length, value) => length + value.byteLength, 0));
+    let offset = 0;
+    for (const value of values) {
+        output.set(value, offset);
+        offset += value.byteLength;
+    }
+    return output;
+}
+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 hex(value) {
+    return [...value].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,73 @@
+import type { CollectionOperation } from "./operations.js";
+export declare const APPLICATION_CAPABILITY_CONTRACT_VERSION: 2;
+export declare const APPLICATION_CAPABILITY_DEFINITIONS: {
+    readonly "collection.read": readonly ["describe", "changes", "read", "query", "list_views", "execute_view", "read_view_source", "validate", "read_type"];
+    readonly "records.create": readonly ["create"];
+    readonly "records.edit": readonly ["update", "rename"];
+    readonly "records.delete": readonly ["delete"];
+    readonly "views.manage": readonly ["create_view_source", "update_view_source", "delete_view_source"];
+    readonly "definitions.manage": readonly ["create_type", "update_type", "assess_type_pack", "apply_type_pack"];
+    readonly "background.schedule": readonly ["list_timers", "put_timer", "cancel_timer", "reconcile_timers"];
+    readonly "offline.replica": readonly ["sync"];
+};
+export declare const APPLICATION_SETUP_OPERATIONS: readonly ["assess_collection_setup", "apply_collection_setup"];
+export type ApplicationCapabilityId = keyof typeof APPLICATION_CAPABILITY_DEFINITIONS;
+export interface ApplicationCapabilityRequirements {
+    contract_version: typeof APPLICATION_CAPABILITY_CONTRACT_VERSION;
+    required: ApplicationCapabilityId[];
+    optional?: ApplicationCapabilityId[];
+}
+export declare function operationsForApplicationCapabilities(requirements: ApplicationCapabilityRequirements, options?: {
+    includeOptional?: boolean;
+}): CollectionOperation[];
+export declare function capabilityOperations(capability: ApplicationCapabilityId): CollectionOperation[];
+export declare function applicationOperationSelectionIsAtomic(requirements: ApplicationCapabilityRequirements, operations: readonly string[]): boolean;
+export declare const APPLICATION_CAPABILITY_V1_CONTRACT_VERSION: 1;
+export declare const APPLICATION_CAPABILITY_V1_DEFINITIONS: Readonly<{
+    readonly "collection.inspect": readonly ["describe"];
+    readonly "records.watch": readonly ["changes"];
+    readonly "records.read": readonly ["read"];
+    readonly "records.query": readonly ["query"];
+    readonly "records.validate": readonly ["validate"];
+    readonly "records.create": readonly ["create"];
+    readonly "records.update": readonly ["update"];
+    readonly "records.delete": readonly ["delete"];
+    readonly "records.rename": readonly ["rename"];
+    readonly "views.list": readonly ["list_views"];
+    readonly "views.execute": readonly ["execute_view"];
+    readonly "views.source.read": readonly ["read_view_source"];
+    readonly "views.source.create": readonly ["create_view_source"];
+    readonly "views.source.update": readonly ["update_view_source"];
+    readonly "views.source.delete": readonly ["delete_view_source"];
+    readonly "definitions.contracts.current": readonly [];
+    readonly "definitions.read": readonly ["read_type"];
+    readonly "definitions.create": readonly ["create_type"];
+    readonly "definitions.update": readonly ["update_type"];
+    readonly "definitions.type-pack.inspect": readonly ["assess_type_pack"];
+    readonly "definitions.type-pack.apply": readonly ["assess_type_pack", "apply_type_pack"];
+    readonly "collection.setup.apply": readonly ["assess_collection_setup", "apply_collection_setup"];
+    readonly "timers.list": readonly ["list_timers"];
+    readonly "timers.put": readonly ["put_timer"];
+    readonly "timers.cancel": readonly ["cancel_timer"];
+    readonly "timers.reconcile": readonly ["reconcile_timers"];
+    readonly "sync.offline-replica": readonly ["sync"];
+    readonly "notifications.background-delivery": readonly [];
+    readonly "files.list": readonly [];
+    readonly "files.read": readonly [];
+    readonly "files.add": readonly [];
+    readonly "files.replace": readonly [];
+    readonly "files.move": readonly [];
+    readonly "files.delete": readonly [];
+}>;
+export type LegacyApplicationCapabilityId = keyof typeof APPLICATION_CAPABILITY_V1_DEFINITIONS;
+export interface LegacyApplicationCapabilityRequirements {
+    contract_version: typeof APPLICATION_CAPABILITY_V1_CONTRACT_VERSION;
+    required: LegacyApplicationCapabilityId[];
+    optional?: LegacyApplicationCapabilityId[];
+}
+export declare function capabilityOperationsForContractVersion(contractVersion: number, capability: string): CollectionOperation[] | undefined;
+/** Fresh issuance only; never use this ceiling to reject retained authority or terminal replay. */
+export declare const FRESH_APPLICATION_AUTHORIZATION_VERSIONS: readonly [1, 2];
+export declare const APPLICATION_AUTHORIZATION_V2_ISSUANCE_CAPABILITY: "application-authorization-v2-issuance";
+export declare const FRESH_APPLICATION_AUTHORIZATION_CAPABILITIES: readonly string[];
+export declare function permitsFreshApplicationAuthorization(version: number): boolean;

package/dist/capabilities.js

@@ -0,0 +1,92 @@
+// Generated by scripts/generate-application-capabilities.mjs. Do not edit directly.
+export const APPLICATION_CAPABILITY_CONTRACT_VERSION = 2;
+export const APPLICATION_CAPABILITY_DEFINITIONS = {
+    "collection.read": ["describe", "changes", "read", "query", "list_views", "execute_view", "read_view_source", "validate", "read_type"],
+    "records.create": ["create"],
+    "records.edit": ["update", "rename"],
+    "records.delete": ["delete"],
+    "views.manage": ["create_view_source", "update_view_source", "delete_view_source"],
+    "definitions.manage": ["create_type", "update_type", "assess_type_pack", "apply_type_pack"],
+    "background.schedule": ["list_timers", "put_timer", "cancel_timer", "reconcile_timers"],
+    "offline.replica": ["sync"]
+};
+export const APPLICATION_SETUP_OPERATIONS = [
+    "assess_collection_setup",
+    "apply_collection_setup"
+];
+export function operationsForApplicationCapabilities(requirements, options = {}) {
+    const capabilities = options.includeOptional === false
+        ? requirements.required
+        : [...requirements.required, ...(requirements.optional ?? [])];
+    return [...new Set(capabilities.flatMap((capability) => APPLICATION_CAPABILITY_DEFINITIONS[capability]))];
+}
+export function capabilityOperations(capability) {
+    return [...APPLICATION_CAPABILITY_DEFINITIONS[capability]];
+}
+export function applicationOperationSelectionIsAtomic(requirements, operations) {
+    const selected = new Set(operations);
+    const declared = [...requirements.required, ...(requirements.optional ?? [])];
+    const allowed = new Set(declared.flatMap((capability) => APPLICATION_CAPABILITY_DEFINITIONS[capability]));
+    if ([...selected].some((operation) => !allowed.has(operation))) {
+        return false;
+    }
+    return declared.every((capability) => {
+        const capabilityOperations = APPLICATION_CAPABILITY_DEFINITIONS[capability];
+        const count = capabilityOperations.filter((operation) => selected.has(operation)).length;
+        return requirements.required.includes(capability)
+            ? count === capabilityOperations.length
+            : count === 0 || count === capabilityOperations.length;
+    });
+}
+// Frozen predecessor catalog. Lookup availability does not imply declaration acceptance.
+export const APPLICATION_CAPABILITY_V1_CONTRACT_VERSION = 1;
+export const APPLICATION_CAPABILITY_V1_DEFINITIONS = Object.freeze({
+    "collection.inspect": Object.freeze(["describe"]),
+    "records.watch": Object.freeze(["changes"]),
+    "records.read": Object.freeze(["read"]),
+    "records.query": Object.freeze(["query"]),
+    "records.validate": Object.freeze(["validate"]),
+    "records.create": Object.freeze(["create"]),
+    "records.update": Object.freeze(["update"]),
+    "records.delete": Object.freeze(["delete"]),
+    "records.rename": Object.freeze(["rename"]),
+    "views.list": Object.freeze(["list_views"]),
+    "views.execute": Object.freeze(["execute_view"]),
+    "views.source.read": Object.freeze(["read_view_source"]),
+    "views.source.create": Object.freeze(["create_view_source"]),
+    "views.source.update": Object.freeze(["update_view_source"]),
+    "views.source.delete": Object.freeze(["delete_view_source"]),
+    "definitions.contracts.current": Object.freeze([]),
+    "definitions.read": Object.freeze(["read_type"]),
+    "definitions.create": Object.freeze(["create_type"]),
+    "definitions.update": Object.freeze(["update_type"]),
+    "definitions.type-pack.inspect": Object.freeze(["assess_type_pack"]),
+    "definitions.type-pack.apply": Object.freeze(["assess_type_pack", "apply_type_pack"]),
+    "collection.setup.apply": Object.freeze(["assess_collection_setup", "apply_collection_setup"]),
+    "timers.list": Object.freeze(["list_timers"]),
+    "timers.put": Object.freeze(["put_timer"]),
+    "timers.cancel": Object.freeze(["cancel_timer"]),
+    "timers.reconcile": Object.freeze(["reconcile_timers"]),
+    "sync.offline-replica": Object.freeze(["sync"]),
+    "notifications.background-delivery": Object.freeze([]),
+    "files.list": Object.freeze([]),
+    "files.read": Object.freeze([]),
+    "files.add": Object.freeze([]),
+    "files.replace": Object.freeze([]),
+    "files.move": Object.freeze([]),
+    "files.delete": Object.freeze([])
+});
+export function capabilityOperationsForContractVersion(contractVersion, capability) {
+    const definitions = contractVersion === 1 ? APPLICATION_CAPABILITY_V1_DEFINITIONS
+        : contractVersion === 2 ? APPLICATION_CAPABILITY_DEFINITIONS : undefined;
+    if (!definitions || !Object.hasOwn(definitions, capability))
+        return undefined;
+    return [...definitions[capability]];
+}
+/** Fresh issuance only; never use this ceiling to reject retained authority or terminal replay. */
+export const FRESH_APPLICATION_AUTHORIZATION_VERSIONS = Object.freeze([1, 2]);
+export const APPLICATION_AUTHORIZATION_V2_ISSUANCE_CAPABILITY = "application-authorization-v2-issuance";
+export const FRESH_APPLICATION_AUTHORIZATION_CAPABILITIES = Object.freeze(["application-authorization-v2-issuance"]);
+export function permitsFreshApplicationAuthorization(version) {
+    return FRESH_APPLICATION_AUTHORIZATION_VERSIONS.some((supported) => supported === version);
+}

package/dist/collection-setup.d.ts

@@ -0,0 +1,90 @@
+import type { ContractSetupChoice, TypePackAssessment, TypePackProvision, TypePackReceipt } from "./type-packs.js";
+export type ConfigurationContributionValue = string | number | boolean | null;
+export interface ConfigurationRequirement {
+    id: string;
+    path: string;
+    predicate: "contains";
+    value: ConfigurationContributionValue;
+}
+export interface ConfigurationProvision {
+    requirement: string;
+    operation: "set_add";
+    path: string;
+    value: ConfigurationContributionValue;
+}
+export interface ApplicationCollectionSetupRequirements {
+    configuration: ConfigurationRequirement[];
+}
+export interface ApplicationCollectionSetupProvisions {
+    configuration: ConfigurationProvision[];
+    type_packs: TypePackProvision[];
+}
+export interface AssessCollectionSetupInput {
+    /** Stable application declaration id, not the server's database id. */
+    application_id: string;
+    /** Exact canonical digest of the complete registered application declaration. */
+    declaration_digest: string;
+    requirements: ApplicationCollectionSetupRequirements;
+    provisions: ApplicationCollectionSetupProvisions;
+    /** Collection-owner choices for user-owned contract implementations. */
+    contract_setups?: ContractSetupChoice[];
+    /** Digest-pinned consent to adopt unmanaged managed resources, keyed by pack id and target. */
+    type_pack_adoptions?: Record<string, Record<string, string>>;
+}
+export interface ApplyCollectionSetupInput extends AssessCollectionSetupInput {
+    expected_assessment_digest: string;
+    expected_collection_revision: string;
+    expected_provision_digest: string;
+    allow_type_pack_downgrades?: string[];
+}
+export interface ConfigurationSetupConflict {
+    code: "configuration_path_conflict" | "configuration_type_conflict";
+    path: string;
+    expected: "mapping" | "sequence";
+    observed: "null" | "boolean" | "number" | "string" | "sequence" | "mapping" | "tagged";
+    message: string;
+}
+export interface ConfigurationSetupAssessment {
+    requirement: string;
+    path: string;
+    value: ConfigurationContributionValue;
+    action: "current" | "add" | "conflict";
+    conflict?: ConfigurationSetupConflict;
+}
+export interface CollectionSetupAssessment {
+    status: "current" | "provision" | "conflict";
+    applicable: boolean;
+    application_id: string;
+    declaration_digest: string;
+    provision_digest: string;
+    collection_revision: string;
+    final_collection_revision: string;
+    baseline_diagnostic_count: number;
+    final_diagnostic_count: number;
+    resolved_diagnostic_count: number;
+    introduced_diagnostic_count: number;
+    baseline_diagnostic_digest: string;
+    configuration: ConfigurationSetupAssessment[];
+    type_packs: TypePackAssessment[];
+    final_resource_revisions: Record<string, string>;
+    assessment_digest: string;
+}
+export interface ConfigurationContributionReceipt {
+    requirement: string;
+    path: string;
+    value: ConfigurationContributionValue;
+}
+export interface CollectionSetupReceipt {
+    application_id: string;
+    declaration_digest: string;
+    provision_digest: string;
+    assessment_digest: string;
+    collection_revision: string;
+    configuration: ConfigurationContributionReceipt[];
+    type_packs: TypePackReceipt[];
+    cleanup_deferred: boolean;
+}
+export interface CollectionSetupApplyResult {
+    assessment: CollectionSetupAssessment;
+    receipt: CollectionSetupReceipt;
+}

package/dist/collection-setup.js

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

package/dist/compatibility.d.ts

@@ -0,0 +1,37 @@
+import type { ApplicationFileRequest } from "./files.js";
+import { type CollectionOperation } from "./operations.js";
+export declare const OPERATION_TRANSPORT_PROTOCOL_VERSION: 3;
+export declare const LEGACY_OPERATION_TRANSPORT_PROTOCOL_VERSION: 2;
+export declare const SUPPORTED_OPERATION_TRANSPORT_PROTOCOL_VERSIONS: readonly [3, 2];
+export type OperationTransportProtocolVersion = typeof SUPPORTED_OPERATION_TRANSPORT_PROTOCOL_VERSIONS[number];
+export declare const AUTHORIZATION_BINDING_PROTOCOL_VERSION: 5;
+export declare const LEGACY_AUTHORIZATION_BINDING_PROTOCOL_VERSION: 4;
+export declare const SUPPORTED_AUTHORIZATION_BINDING_PROTOCOL_VERSIONS: readonly [5, 4];
+export type AuthorizationBindingProtocolVersion = typeof SUPPORTED_AUTHORIZATION_BINDING_PROTOCOL_VERSIONS[number];
+export declare const SEMANTIC_CAPABILITY_CONTRACT_VERSION: 2;
+export declare const DURABLE_MUTATION_CONTRACT_VERSION: 1;
+export interface ConnectContractRequirements {
+    operation_transport: number;
+    /** Signed, mutation-only transports retained solely for exact outcome recovery. */
+    operation_transport_recovery?: number[];
+    authorization_binding: number;
+    semantic_capabilities: number;
+    /** Required only by operations that can durably mutate authority state. */
+    durable_mutation?: number;
+}
+export interface ConnectContractSupport {
+    operation_transport: number[];
+    authorization_binding: number[];
+    semantic_capabilities: number[];
+    durable_mutation: number[];
+}
+export declare const CONNECT_CONTRACT_SUPPORT: ConnectContractSupport;
+/**
+ * Produce the exact contract ceiling signed during authorization. `sync` is
+ * conservatively mutation-capable because its action is selected per request.
+ */
+export declare function authorizationContractRequirements(operations: readonly CollectionOperation[], files?: ApplicationFileRequest, operationTransportRecovery?: readonly OperationTransportProtocolVersion[], semanticCapabilityContractVersion?: 1 | 2): ConnectContractRequirements;
+export declare function supportsContractRequirements(required: ConnectContractRequirements, supported: ConnectContractSupport, durableMutation: boolean): boolean;
+export declare function isSupportedOperationTransport(version: number): version is OperationTransportProtocolVersion;
+export declare function isSupportedAuthorizationBinding(version: number): version is AuthorizationBindingProtocolVersion;
+export declare function permitsOperationTransport(contracts: ConnectContractRequirements, version: number, recoveryOnly?: boolean): boolean;

package/dist/compatibility.js

@@ -0,0 +1,65 @@
+import { APPLICATION_CAPABILITY_CONTRACT_VERSION } from "./capabilities.js";
+import { isMutatingOperation } from "./operations.js";
+export const OPERATION_TRANSPORT_PROTOCOL_VERSION = 3;
+export const LEGACY_OPERATION_TRANSPORT_PROTOCOL_VERSION = 2;
+export const SUPPORTED_OPERATION_TRANSPORT_PROTOCOL_VERSIONS = [
+    OPERATION_TRANSPORT_PROTOCOL_VERSION,
+    LEGACY_OPERATION_TRANSPORT_PROTOCOL_VERSION
+];
+export const AUTHORIZATION_BINDING_PROTOCOL_VERSION = 5;
+export const LEGACY_AUTHORIZATION_BINDING_PROTOCOL_VERSION = 4;
+export const SUPPORTED_AUTHORIZATION_BINDING_PROTOCOL_VERSIONS = [
+    AUTHORIZATION_BINDING_PROTOCOL_VERSION,
+    LEGACY_AUTHORIZATION_BINDING_PROTOCOL_VERSION
+];
+export const SEMANTIC_CAPABILITY_CONTRACT_VERSION = APPLICATION_CAPABILITY_CONTRACT_VERSION;
+export const DURABLE_MUTATION_CONTRACT_VERSION = 1;
+export const CONNECT_CONTRACT_SUPPORT = {
+    operation_transport: [...SUPPORTED_OPERATION_TRANSPORT_PROTOCOL_VERSIONS],
+    authorization_binding: [...SUPPORTED_AUTHORIZATION_BINDING_PROTOCOL_VERSIONS],
+    semantic_capabilities: [SEMANTIC_CAPABILITY_CONTRACT_VERSION, 1],
+    durable_mutation: [DURABLE_MUTATION_CONTRACT_VERSION]
+};
+/**
+ * Produce the exact contract ceiling signed during authorization. `sync` is
+ * conservatively mutation-capable because its action is selected per request.
+ */
+export function authorizationContractRequirements(operations, files, operationTransportRecovery = [], semanticCapabilityContractVersion = APPLICATION_CAPABILITY_CONTRACT_VERSION) {
+    const requirements = {
+        operation_transport: OPERATION_TRANSPORT_PROTOCOL_VERSION,
+        authorization_binding: AUTHORIZATION_BINDING_PROTOCOL_VERSION,
+        semantic_capabilities: semanticCapabilityContractVersion
+    };
+    const recovery = [...new Set(operationTransportRecovery)]
+        .filter((version) => version !== OPERATION_TRANSPORT_PROTOCOL_VERSION)
+        .sort((left, right) => right - left);
+    if (recovery.length > 0)
+        requirements.operation_transport_recovery = recovery;
+    if (operations.some((operation) => isMutatingOperation(operation, { action: "mutate" }))
+        || files?.actions.some((action) => action !== "list" && action !== "read") === true) {
+        requirements.durable_mutation = 1;
+    }
+    return requirements;
+}
+export function supportsContractRequirements(required, supported, durableMutation) {
+    return supported.operation_transport.includes(required.operation_transport)
+        && (required.operation_transport_recovery ?? []).every((version) => supported.operation_transport.includes(version))
+        && supported.authorization_binding.includes(required.authorization_binding)
+        && supported.semantic_capabilities.includes(required.semantic_capabilities)
+        && (!durableMutation
+            || (required.durable_mutation !== undefined
+                && supported.durable_mutation.includes(required.durable_mutation)));
+}
+export function isSupportedOperationTransport(version) {
+    return SUPPORTED_OPERATION_TRANSPORT_PROTOCOL_VERSIONS
+        .includes(version);
+}
+export function isSupportedAuthorizationBinding(version) {
+    return SUPPORTED_AUTHORIZATION_BINDING_PROTOCOL_VERSIONS
+        .includes(version);
+}
+export function permitsOperationTransport(contracts, version, recoveryOnly = false) {
+    return contracts.operation_transport === version
+        || (recoveryOnly
+            && (contracts.operation_transport_recovery ?? []).includes(version));
+}