@mdbase-dev/connect-protocol 0.1.0-beta.31 → 0.1.0-beta.33

package/dist/application-authorization.d.ts

@@ -1,10 +1,12 @@
 import type { ApplicationFileRequirement } from "./files.js";
 import type { CollectionOperation } from "./operations.js";
+import type { ConnectContractRequirements } from "./compatibility.js";
 export type ApplicationAuthorizationFlow = "authorization_code" | "device_code";
 export interface ApplicationAuthorizationBinding {
-    protocol_version: 2;
+    protocol_version: 4;
     authorization_id: string;
     application_id: string;
+    application_declaration_id: string;
     application_manifest_digest: string;
     application_installation_id: string;
     installation_signing_public_key: string;
@@ -17,6 +19,7 @@ export interface ApplicationAuthorizationBinding {
     redirect_uri?: string;
     state?: string;
     code_challenge: string;
+    contracts: ConnectContractRequirements;
     requested_operations: CollectionOperation[];
     requested_files?: ApplicationFileRequirement;
     collection_id?: string;

package/dist/application-authorization.js

@@ -1,5 +1,5 @@
 const INSTALLATION_ID_DOMAIN = new TextEncoder().encode("mdbase-connect application installation id v2\0");
-const AUTHORIZATION_PROOF_DOMAIN = new TextEncoder().encode("mdbase-connect application authorization proof v2\0");
+const AUTHORIZATION_PROOF_DOMAIN = new TextEncoder().encode("mdbase-connect application authorization proof v4\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)])));
@@ -25,12 +25,20 @@ export function authorizationSigningMessage(binding) {
     }
     const nonce = canonicalBase64(binding.authorization_nonce);
     const challenge = canonicalBase64(binding.code_challenge);
-    if (binding.protocol_version !== 2
+    const contracts = binding.contracts;
+    if (binding.protocol_version !== 4
         || 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)
         || (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"))
@@ -48,6 +56,7 @@ export function authorizationSigningMessage(binding) {
         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),
@@ -58,12 +67,21 @@ export function authorizationSigningMessage(binding) {
         optionalString(binding.redirect_uri),
         optionalString(binding.state),
         field(new TextEncoder().encode(binding.code_challenge)),
+        u32(contracts.operation_transport),
+        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;
@@ -78,7 +96,7 @@ function validateRequestedFiles(files) {
 }
 function requestedFiles(files) {
     if (files === undefined)
-        return new Uint8Array([0]);
+        return new Uint8Array(1);
     const actions = files.actions.map((action) => field(new TextEncoder().encode(action)));
     return concat([
         new Uint8Array([1]),
@@ -95,12 +113,12 @@ function requestedFiles(files) {
 }
 function optionalString(value) {
     return value === undefined
-        ? new Uint8Array([0])
+        ? new Uint8Array(1)
         : concat([new Uint8Array([1]), field(new TextEncoder().encode(value))]);
 }
 function optionalUuid(value) {
     return value === undefined
-        ? new Uint8Array([0])
+        ? new Uint8Array(1)
         : concat([new Uint8Array([1]), field(uuidBytes(value))]);
 }
 function publicKey(value) {

package/dist/capabilities.d.ts

@@ -26,6 +26,7 @@ export declare const APPLICATION_CAPABILITY_DEFINITIONS: {
     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"];

package/dist/capabilities.js

@@ -25,6 +25,7 @@ export const APPLICATION_CAPABILITY_DEFINITIONS = {
     "definitions.update": ["update_type"],
     "definitions.type-pack.inspect": ["assess_type_pack"],
     "definitions.type-pack.apply": ["assess_type_pack", "apply_type_pack"],
+    "collection.setup.apply": ["assess_collection_setup", "apply_collection_setup"],
     "timers.list": ["list_timers"],
     "timers.put": ["put_timer"],
     "timers.cancel": ["cancel_timer"],

package/dist/collection-setup.d.ts

@@ -0,0 +1,83 @@
+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[];
+}
+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;
+    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,26 @@
+import type { ApplicationFileRequirement } from "./files.js";
+import { type CollectionOperation } from "./operations.js";
+export declare const OPERATION_TRANSPORT_PROTOCOL_VERSION: 2;
+export declare const AUTHORIZATION_BINDING_PROTOCOL_VERSION: 4;
+export declare const SEMANTIC_CAPABILITY_CONTRACT_VERSION: 1;
+export declare const DURABLE_MUTATION_CONTRACT_VERSION: 1;
+export interface ConnectContractRequirements {
+    operation_transport: 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?: ApplicationFileRequirement): ConnectContractRequirements;
+export declare function supportsContractRequirements(required: ConnectContractRequirements, supported: ConnectContractSupport, durableMutation: boolean): boolean;

package/dist/compatibility.js

@@ -0,0 +1,35 @@
+import { isMutatingOperation } from "./operations.js";
+export const OPERATION_TRANSPORT_PROTOCOL_VERSION = 2;
+export const AUTHORIZATION_BINDING_PROTOCOL_VERSION = 4;
+export const SEMANTIC_CAPABILITY_CONTRACT_VERSION = 1;
+export const DURABLE_MUTATION_CONTRACT_VERSION = 1;
+export const CONNECT_CONTRACT_SUPPORT = {
+    operation_transport: [OPERATION_TRANSPORT_PROTOCOL_VERSION],
+    authorization_binding: [AUTHORIZATION_BINDING_PROTOCOL_VERSION],
+    semantic_capabilities: [SEMANTIC_CAPABILITY_CONTRACT_VERSION],
+    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) {
+    const requirements = {
+        operation_transport: OPERATION_TRANSPORT_PROTOCOL_VERSION,
+        authorization_binding: AUTHORIZATION_BINDING_PROTOCOL_VERSION,
+        semantic_capabilities: 1
+    };
+    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)
+        && 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)));
+}

package/dist/connect-problems.generated.d.ts

@@ -20,6 +20,10 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "authorization";
         readonly recovery: "reauthorize";
     };
+    readonly authorization_binding_incompatible: {
+        readonly category: "compatibility";
+        readonly recovery: "upgrade_application";
+    };
     readonly authorization_cancelled: {
         readonly category: "cancellation";
         readonly recovery: "none";
@@ -40,6 +44,10 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "validation";
         readonly recovery: "fix_request";
     };
+    readonly capability_contract_incompatible: {
+        readonly category: "compatibility";
+        readonly recovery: "upgrade_application";
+    };
     readonly change_cursor_reset: {
         readonly category: "conflict";
         readonly recovery: "refresh";
@@ -120,6 +128,10 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "availability";
         readonly recovery: "retry";
     };
+    readonly durable_mutation_unsupported: {
+        readonly category: "compatibility";
+        readonly recovery: "upgrade_connector";
+    };
     readonly encrypted_relay_rejected: {
         readonly category: "authorization";
         readonly recovery: "reauthorize";
@@ -240,6 +252,14 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "authorization";
         readonly recovery: "reauthorize";
     };
+    readonly mutation_recovery_expired: {
+        readonly category: "compatibility";
+        readonly recovery: "none";
+    };
+    readonly mutation_request_conflict: {
+        readonly category: "conflict";
+        readonly recovery: "resolve_conflict";
+    };
     readonly no_pending_mutation: {
         readonly category: "conflict";
         readonly recovery: "refresh";
@@ -320,6 +340,26 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "compatibility";
         readonly recovery: "fix_request";
     };
+    readonly registry_backup_invalid: {
+        readonly category: "integrity";
+        readonly recovery: "contact_support";
+    };
+    readonly registry_busy: {
+        readonly category: "availability";
+        readonly recovery: "retry";
+    };
+    readonly registry_corrupt: {
+        readonly category: "integrity";
+        readonly recovery: "repair_collection";
+    };
+    readonly registry_migration_failed: {
+        readonly category: "internal";
+        readonly recovery: "contact_support";
+    };
+    readonly registry_schema_incompatible: {
+        readonly category: "compatibility";
+        readonly recovery: "upgrade_connector";
+    };
     readonly relay_authorization_expired: {
         readonly category: "authorization";
         readonly recovery: "reauthorize";
@@ -360,6 +400,10 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "availability";
         readonly recovery: "retry";
     };
+    readonly transport_protocol_incompatible: {
+        readonly category: "compatibility";
+        readonly recovery: "upgrade_connector";
+    };
     readonly type_pack_provision_failed: {
         readonly category: "validation";
         readonly recovery: "repair_collection";
@@ -405,11 +449,25 @@ export interface ConnectProblemDetailsByCode {
         "interval_seconds": number;
     };
     "authority_authorization_changed": undefined;
+    "authorization_binding_incompatible": {
+        "contract": string;
+        "required": Array<number>;
+        "supported": Array<number>;
+        "peer": string;
+        "operation"?: string;
+    };
     "authorization_cancelled": undefined;
     "authorization_expired": undefined;
     "authorization_replayed": undefined;
     "browser_required": undefined;
     "callback_url_required": undefined;
+    "capability_contract_incompatible": {
+        "contract": string;
+        "required": Array<number>;
+        "supported": Array<number>;
+        "peer": string;
+        "operation"?: string;
+    };
     "change_cursor_reset": undefined;
     "collection_access_denied": undefined;
     "collection_configuration_invalid": {
@@ -446,6 +504,13 @@ export interface ConnectProblemDetailsByCode {
     "device_authorization_failed": undefined;
     "direct_operation_rejected": undefined;
     "discovery_failed": undefined;
+    "durable_mutation_unsupported": {
+        "contract": string;
+        "required": Array<number>;
+        "supported": Array<number>;
+        "peer": string;
+        "operation"?: string;
+    };
     "encrypted_relay_rejected": undefined;
     "encryption_required": undefined;
     "expired_token": undefined;
@@ -487,6 +552,10 @@ export interface ConnectProblemDetailsByCode {
     "manifest_load_failed": undefined;
     "manifest_required": undefined;
     "missing_grant_key": undefined;
+    "mutation_recovery_expired": undefined;
+    "mutation_request_conflict": {
+        "request_id": string;
+    };
     "no_pending_mutation": undefined;
     "not_authorized": undefined;
     "not_remote_authority": undefined;
@@ -502,7 +571,9 @@ export interface ConnectProblemDetailsByCode {
         "diagnostics": Array<Record<string, unknown>>;
         "partial_result"?: unknown;
     };
-    "operation_outcome_unknown": undefined;
+    "operation_outcome_unknown": {
+        "request_id": string;
+    };
     "path_occupied": undefined;
     "pending_mutation_unresolved": undefined;
     "query_snapshot_changed": undefined;
@@ -512,6 +583,11 @@ export interface ConnectProblemDetailsByCode {
     "reconnect_required": undefined;
     "redirect_uri_required": undefined;
     "reference_updates_unsupported": undefined;
+    "registry_backup_invalid": undefined;
+    "registry_busy": undefined;
+    "registry_corrupt": undefined;
+    "registry_migration_failed": undefined;
+    "registry_schema_incompatible": undefined;
     "relay_authorization_expired": undefined;
     "relay_unavailable": undefined;
     "sandbox_unsupported": undefined;
@@ -522,6 +598,13 @@ export interface ConnectProblemDetailsByCode {
     "temporarily_unavailable": undefined;
     "timeout": undefined;
     "token_exchange_failed": undefined;
+    "transport_protocol_incompatible": {
+        "contract": string;
+        "required": Array<number>;
+        "supported": Array<number>;
+        "peer": string;
+        "operation"?: string;
+    };
     "type_pack_provision_failed": undefined;
     "unknown_collection": undefined;
     "unsafe_file_path": undefined;
@@ -559,6 +642,12 @@ export interface ConnectProblemByCode {
         recovery: "reauthorize";
         details?: never;
     };
+    "authorization_binding_incompatible": ConnectProblemBase & {
+        code: "authorization_binding_incompatible";
+        category: "compatibility";
+        recovery: "upgrade_application";
+        details: ConnectProblemDetailsByCode["authorization_binding_incompatible"];
+    };
     "authorization_cancelled": ConnectProblemBase & {
         code: "authorization_cancelled";
         category: "cancellation";
@@ -589,6 +678,12 @@ export interface ConnectProblemByCode {
         recovery: "fix_request";
         details?: never;
     };
+    "capability_contract_incompatible": ConnectProblemBase & {
+        code: "capability_contract_incompatible";
+        category: "compatibility";
+        recovery: "upgrade_application";
+        details: ConnectProblemDetailsByCode["capability_contract_incompatible"];
+    };
     "change_cursor_reset": ConnectProblemBase & {
         code: "change_cursor_reset";
         category: "conflict";
@@ -709,6 +804,12 @@ export interface ConnectProblemByCode {
         recovery: "retry";
         details?: never;
     };
+    "durable_mutation_unsupported": ConnectProblemBase & {
+        code: "durable_mutation_unsupported";
+        category: "compatibility";
+        recovery: "upgrade_connector";
+        details: ConnectProblemDetailsByCode["durable_mutation_unsupported"];
+    };
     "encrypted_relay_rejected": ConnectProblemBase & {
         code: "encrypted_relay_rejected";
         category: "authorization";
@@ -889,6 +990,18 @@ export interface ConnectProblemByCode {
         recovery: "reauthorize";
         details?: never;
     };
+    "mutation_recovery_expired": ConnectProblemBase & {
+        code: "mutation_recovery_expired";
+        category: "compatibility";
+        recovery: "none";
+        details?: never;
+    };
+    "mutation_request_conflict": ConnectProblemBase & {
+        code: "mutation_request_conflict";
+        category: "conflict";
+        recovery: "resolve_conflict";
+        details: ConnectProblemDetailsByCode["mutation_request_conflict"];
+    };
     "no_pending_mutation": ConnectProblemBase & {
         code: "no_pending_mutation";
         category: "conflict";
@@ -965,7 +1078,7 @@ export interface ConnectProblemByCode {
         code: "operation_outcome_unknown";
         category: "conflict";
         recovery: "resolve_outcome";
-        details?: never;
+        details: ConnectProblemDetailsByCode["operation_outcome_unknown"];
     };
     "path_occupied": ConnectProblemBase & {
         code: "path_occupied";
@@ -1009,6 +1122,36 @@ export interface ConnectProblemByCode {
         recovery: "fix_request";
         details?: never;
     };
+    "registry_backup_invalid": ConnectProblemBase & {
+        code: "registry_backup_invalid";
+        category: "integrity";
+        recovery: "contact_support";
+        details?: never;
+    };
+    "registry_busy": ConnectProblemBase & {
+        code: "registry_busy";
+        category: "availability";
+        recovery: "retry";
+        details?: never;
+    };
+    "registry_corrupt": ConnectProblemBase & {
+        code: "registry_corrupt";
+        category: "integrity";
+        recovery: "repair_collection";
+        details?: never;
+    };
+    "registry_migration_failed": ConnectProblemBase & {
+        code: "registry_migration_failed";
+        category: "internal";
+        recovery: "contact_support";
+        details?: never;
+    };
+    "registry_schema_incompatible": ConnectProblemBase & {
+        code: "registry_schema_incompatible";
+        category: "compatibility";
+        recovery: "upgrade_connector";
+        details?: never;
+    };
     "relay_authorization_expired": ConnectProblemBase & {
         code: "relay_authorization_expired";
         category: "authorization";
@@ -1069,6 +1212,12 @@ export interface ConnectProblemByCode {
         recovery: "retry";
         details?: never;
     };
+    "transport_protocol_incompatible": ConnectProblemBase & {
+        code: "transport_protocol_incompatible";
+        category: "compatibility";
+        recovery: "upgrade_connector";
+        details: ConnectProblemDetailsByCode["transport_protocol_incompatible"];
+    };
     "type_pack_provision_failed": ConnectProblemBase & {
         code: "type_pack_provision_failed";
         category: "validation";