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

package/dist/index.d.ts

@@ -7,20 +7,25 @@ import type { ApplicationAuthorizationProof } from "./application-authorization.
 export * from "./connect-problems.generated.js";
 export * from "./files.js";
 export * from "./operations.js";
+export * from "./mutation-fingerprint.js";
+export * from "./compatibility.js";
 export * from "./capabilities.js";
 export * from "./application-authorization.js";
 export * from "./type-packs.js";
 export declare const CONTROL_PROTOCOL_VERSION: 1;
-export declare const ENCRYPTED_RELAY_PROTOCOL_VERSION: 1;
-export declare const APPLICATION_AUTHORIZATION_PROTOCOL_VERSION: 2;
+export { AUTHORIZATION_BINDING_PROTOCOL_VERSION as APPLICATION_AUTHORIZATION_PROTOCOL_VERSION } from "./compatibility.js";
 export declare const LOOPBACK_PROTOCOL_VERSION: 1;
 export declare const DEFAULT_LOOPBACK_PORT: 28485;
 export declare const RELAY_ENCRYPTION_SUITE: "P256-HKDF-SHA256-AES256GCM";
+export declare const GRANT_ENCRYPTION_PROTOCOL_VERSION: 1;
 export declare const SYNC_PROTOCOL_VERSION: 1;
 export declare const CONTRACT_SETUP_CAPABILITY: "contract-setup-v1";
 export declare const FILE_RELAY_CAPABILITY: "file-relay-v1";
-export declare const RELAY_REQUIRED_CAPABILITIES: readonly ["application-authorization-v2", "authorization-activation", "encrypted-relay", "policy-ack"];
-export declare const RELAY_CAPABILITIES: readonly ["application-authorization-v2", "authorization-activation", "encrypted-relay", "policy-ack", "contract-setup-v1", "file-relay-v1"];
+export declare const RELAY_REQUIRED_CAPABILITIES: readonly ["application-authorization-v3", "authorization-activation", "encrypted-relay", "policy-ack"];
+export declare const MINIMUM_CONNECTOR_VERSION: "0.1.0-beta.32";
+export declare const HOSTED_PROVIDER_REQUIRED_CAPABILITIES: readonly ["durable-mutation-journal-v1", "durable-file-lifecycle-v1"];
+export declare const HOSTED_PROVIDER_CAPABILITIES: readonly ["durable-mutation-journal-v1", "durable-file-lifecycle-v1", "mutation-replay-after-credential-retirement-v1"];
+export declare const RELAY_CAPABILITIES: readonly ["application-authorization-v3", "authorization-activation", "encrypted-relay", "policy-ack", "contract-setup-v1", "file-relay-v1"];
 export declare const AUTHORITY_PROOF_VERSION: 1;
 export declare const AUTHORITY_PROOF_ALGORITHM: "P256-SHA256";
 export declare const AUTHORITY_PROOF_DOMAIN: "mdbase-authority-request-proof-v1";
@@ -42,7 +47,7 @@ export declare const CONNECT_SCHEMA_IDS: {
     readonly dataContract: "https://mdbase.dev/schemas/v0.3/data-contract.schema.json";
     readonly eventActionInterop: "https://mdbase.dev/schemas/interop/v0.1/profile.schema.json";
     readonly protocol: "https://mdbase.dev/connect/schemas/connect-protocol.v1.json";
-    readonly encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v1.json";
+    readonly encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v2.json";
     readonly files: "https://mdbase.dev/connect/schemas/files.v1.json";
     readonly sync: "https://mdbase.dev/connect/schemas/sync.v1.json";
 };
@@ -171,7 +176,7 @@ export interface GrantScope {
 }
 export interface RelayOperationRequest {
     type: "operation_request";
-    protocol_version: 1;
+    protocol_version: 2;
     request_id: string;
     grant_id: string;
     collection_id: string;
@@ -181,29 +186,29 @@ export interface RelayOperationRequest {
 }
 export type RelayOperationResponse = {
     type: "operation_response";
-    protocol_version: 1;
+    protocol_version: 2;
     request_id: string;
     ok: true;
     result: unknown;
 } | {
     type: "operation_response";
-    protocol_version: 1;
+    protocol_version: 2;
     request_id: string;
     ok: false;
     problem: ConnectProblem;
 };
 export interface MdbaseOperationRequest<Input = unknown> {
-    protocol_version: 1;
+    protocol_version: 2;
     request_id: string;
     input: Input;
 }
 export type MdbaseOperationResponse<Result = unknown> = {
-    protocol_version: 1;
+    protocol_version: 2;
     request_id: string;
     ok: true;
     result: Result;
 } | {
-    protocol_version: 1;
+    protocol_version: 2;
     request_id: string;
     ok: false;
     problem: ConnectProblem;
@@ -232,7 +237,9 @@ export interface GrantPolicy {
     application_authorization: ApplicationAuthorizationProof;
 }
 /** Presentation-only grant shape used outside a local authorization boundary. */
-export type GrantSummary = Omit<GrantPolicy, "application_authorization">;
+export type GrantSummary = Omit<GrantPolicy, "application_authorization"> & {
+    contracts: import("./compatibility.js").ConnectContractRequirements;
+};
 export interface GrantEncryption {
     protocol_version: 1;
     suite: typeof RELAY_ENCRYPTION_SUITE;
@@ -244,7 +251,7 @@ export interface GrantEncryption {
     connector_agreement_public_key: string;
 }
 export interface EncryptedRelayEnvelope {
-    protocol_version: 1;
+    protocol_version: 2;
     suite: typeof RELAY_ENCRYPTION_SUITE;
     request_id: string;
     grant_id: string;
@@ -490,18 +497,22 @@ export interface RelayHello {
     protocol_version: 1;
     connector_version: string;
     capabilities: string[];
+    contract_support: import("./compatibility.js").ConnectContractSupport;
 }
 export interface RelayWelcome {
     type: "relay_welcome";
     protocol_version: 1;
     session_id: string;
     capabilities: string[];
+    contract_support: import("./compatibility.js").ConnectContractSupport;
 }
 export interface RelayIncompatible {
     type: "relay_incompatible";
     protocol_version: 1;
-    code: "connector_upgrade_required";
+    code: "connector_upgrade_required" | "transport_protocol_incompatible" | "authorization_binding_incompatible" | "capability_contract_incompatible" | "durable_mutation_unsupported";
     message: string;
+    details?: import("./connect-problems.generated.js").ConnectProblemDetailsByCode["transport_protocol_incompatible" | "authorization_binding_incompatible" | "capability_contract_incompatible" | "durable_mutation_unsupported"];
+    minimum_connector_version: string;
     update_url: string;
 }
 export interface RelayPolicyApplied {

package/dist/index.js

@@ -1,24 +1,35 @@
 export * from "./connect-problems.generated.js";
 export * from "./files.js";
 export * from "./operations.js";
+export * from "./mutation-fingerprint.js";
+export * from "./compatibility.js";
 export * from "./capabilities.js";
 export * from "./application-authorization.js";
 export * from "./type-packs.js";
 export const CONTROL_PROTOCOL_VERSION = 1;
-export const ENCRYPTED_RELAY_PROTOCOL_VERSION = 1;
-export const APPLICATION_AUTHORIZATION_PROTOCOL_VERSION = 2;
+export { AUTHORIZATION_BINDING_PROTOCOL_VERSION as APPLICATION_AUTHORIZATION_PROTOCOL_VERSION } from "./compatibility.js";
 export const LOOPBACK_PROTOCOL_VERSION = 1;
 export const DEFAULT_LOOPBACK_PORT = 28_485;
 export const RELAY_ENCRYPTION_SUITE = "P256-HKDF-SHA256-AES256GCM";
+export const GRANT_ENCRYPTION_PROTOCOL_VERSION = 1;
 export const SYNC_PROTOCOL_VERSION = 1;
 export const CONTRACT_SETUP_CAPABILITY = "contract-setup-v1";
 export const FILE_RELAY_CAPABILITY = "file-relay-v1";
 export const RELAY_REQUIRED_CAPABILITIES = [
-    "application-authorization-v2",
+    "application-authorization-v3",
     "authorization-activation",
     "encrypted-relay",
     "policy-ack"
 ];
+export const MINIMUM_CONNECTOR_VERSION = "0.1.0-beta.32";
+export const HOSTED_PROVIDER_REQUIRED_CAPABILITIES = [
+    "durable-mutation-journal-v1",
+    "durable-file-lifecycle-v1"
+];
+export const HOSTED_PROVIDER_CAPABILITIES = [
+    ...HOSTED_PROVIDER_REQUIRED_CAPABILITIES,
+    "mutation-replay-after-credential-retirement-v1"
+];
 export const RELAY_CAPABILITIES = [
     ...RELAY_REQUIRED_CAPABILITIES,
     CONTRACT_SETUP_CAPABILITY,
@@ -62,7 +73,7 @@ export const CONNECT_SCHEMA_IDS = {
     dataContract: "https://mdbase.dev/schemas/v0.3/data-contract.schema.json",
     eventActionInterop: "https://mdbase.dev/schemas/interop/v0.1/profile.schema.json",
     protocol: "https://mdbase.dev/connect/schemas/connect-protocol.v1.json",
-    encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v1.json",
+    encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v2.json",
     files: "https://mdbase.dev/connect/schemas/files.v1.json",
     sync: "https://mdbase.dev/connect/schemas/sync.v1.json"
 };

package/dist/mutation-fingerprint.d.ts

@@ -0,0 +1,6 @@
+import { type EncryptedOperation } from "./operations.js";
+export declare const MUTATION_FINGERPRINT_SCHEMA_VERSION: 1;
+export declare const MUTATION_FINGERPRINT_DOMAIN: "mdbase-connect mutation fingerprint v1\0";
+export declare function canonicalMutationInput(input: unknown): string;
+export declare function mutationFingerprintTranscript(operation: EncryptedOperation, input: unknown): Uint8Array<ArrayBuffer>;
+export declare function mutationFingerprint(operation: EncryptedOperation, input: unknown): Promise<string>;

package/dist/mutation-fingerprint.js

@@ -0,0 +1,116 @@
+import { mutationOperationIdentifier, operationInputSchemaVersion } from "./operations.js";
+export const MUTATION_FINGERPRINT_SCHEMA_VERSION = 1;
+export const MUTATION_FINGERPRINT_DOMAIN = "mdbase-connect mutation fingerprint v1\0";
+const encoder = new TextEncoder();
+export function canonicalMutationInput(input) {
+    return canonicalize(input, new Set());
+}
+export function mutationFingerprintTranscript(operation, input) {
+    const identifier = mutationOperationIdentifier(operation, input);
+    if (identifier === null)
+        throw new TypeError("The operation is not a canonical mutation.");
+    const identifierBytes = encoder.encode(identifier);
+    const inputBytes = encoder.encode(canonicalMutationInput(input));
+    const domainBytes = encoder.encode(MUTATION_FINGERPRINT_DOMAIN);
+    const transcript = new Uint8Array(domainBytes.length + 4 + 8 + identifierBytes.length + 4 + 8 + inputBytes.length);
+    const view = new DataView(transcript.buffer);
+    let offset = 0;
+    transcript.set(domainBytes, offset);
+    offset += domainBytes.length;
+    view.setUint32(offset, MUTATION_FINGERPRINT_SCHEMA_VERSION, false);
+    offset += 4;
+    offset = writeField(transcript, view, offset, identifierBytes);
+    view.setUint32(offset, operationInputSchemaVersion(operation, input), false);
+    offset += 4;
+    writeField(transcript, view, offset, inputBytes);
+    return transcript;
+}
+export async function mutationFingerprint(operation, input) {
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", mutationFingerprintTranscript(operation, input).buffer));
+    return base64Url(digest);
+}
+function canonicalize(value, ancestors) {
+    if (value === null)
+        return "null";
+    if (value === true)
+        return "true";
+    if (value === false)
+        return "false";
+    if (typeof value === "string") {
+        assertUnicodeScalarString(value);
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Mutation input numbers must be finite.");
+        return JSON.stringify(value);
+    }
+    if (typeof value !== "object") {
+        throw new TypeError(`Mutation input contains unsupported ${typeof value}.`);
+    }
+    if (ancestors.has(value))
+        throw new TypeError("Mutation input must not contain cycles.");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.getOwnPropertySymbols(value).length > 0) {
+                throw new TypeError("Mutation input must not contain symbol properties.");
+            }
+            const children = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.hasOwn(value, index))
+                    throw new TypeError("Mutation input arrays must not be sparse.");
+                children.push(canonicalize(value[index], ancestors));
+            }
+            return `[${children.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Mutation input objects must be plain JSON objects.");
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError("Mutation input must not contain symbol properties.");
+        }
+        const entries = Object.entries(value);
+        for (const [key] of entries)
+            assertUnicodeScalarString(key);
+        entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        return `{${entries.map(([key, child]) => {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || descriptor.get || descriptor.set) {
+                throw new TypeError("Mutation input must not contain accessor properties.");
+            }
+            return `${JSON.stringify(key)}:${canonicalize(child, ancestors)}`;
+        }).join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function assertUnicodeScalarString(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff)) {
+                throw new TypeError("Mutation input strings must not contain lone surrogates.");
+            }
+            index += 1;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            throw new TypeError("Mutation input strings must not contain lone surrogates.");
+        }
+    }
+}
+function writeField(transcript, view, offset, value) {
+    view.setBigUint64(offset, BigInt(value.length), false);
+    offset += 8;
+    transcript.set(value, offset);
+    return offset + value.length;
+}
+function base64Url(value) {
+    return btoa(String.fromCharCode(...value))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/u, "");
+}

package/dist/operations.d.ts

@@ -1,9 +1,14 @@
-/**
- * The executable collection-operation contract. Runtime parsers, capability
- * compilation, and public types must all consume this value; do not maintain a
- * second operation allow-list at an SDK or service boundary.
- */
+export declare const OPERATION_CATALOG_VERSION: 1;
 export declare const COLLECTION_OPERATIONS: readonly ["describe", "changes", "read", "query", "list_views", "execute_view", "read_view_source", "create_view_source", "update_view_source", "delete_view_source", "validate", "create", "update", "delete", "rename", "read_type", "create_type", "update_type", "assess_type_pack", "apply_type_pack", "list_timers", "put_timer", "cancel_timer", "reconcile_timers", "sync"];
 export type CollectionOperation = typeof COLLECTION_OPERATIONS[number];
+export declare const FILE_CONTROL_MESSAGE_TYPES: readonly ["list_files", "open_file_upload", "open_file_download", "move_file", "delete_file", "get_file_transfer_status", "commit_file_upload", "abort_file_transfer"];
+export type FileControlMessageType = typeof FILE_CONTROL_MESSAGE_TYPES[number];
+export type EncryptedOperation = CollectionOperation | "file_control";
+export declare const MUTATING_OPERATION_IDENTIFIERS: readonly ["create_view_source", "update_view_source", "delete_view_source", "create", "update", "delete", "rename", "create_type", "update_type", "apply_type_pack", "put_timer", "cancel_timer", "reconcile_timers", "sync:mutate", "file_control:open_file_upload", "file_control:move_file", "file_control:delete_file", "file_control:commit_file_upload", "file_control:abort_file_transfer"];
+export type MutationOperationIdentifier = typeof MUTATING_OPERATION_IDENTIFIERS[number];
 export declare function isCollectionOperation(value: string): value is CollectionOperation;
 export declare function areCollectionOperations(values: readonly string[]): values is readonly CollectionOperation[];
+export declare function isFileControlMessageType(value: string): value is FileControlMessageType;
+export declare function operationInputSchemaVersion(operation: EncryptedOperation, input: unknown): number;
+export declare function mutationOperationIdentifier(operation: EncryptedOperation, input: unknown): MutationOperationIdentifier | null;
+export declare function isMutatingOperation(operation: EncryptedOperation, input: unknown): boolean;

package/dist/operations.js

@@ -1,8 +1,5 @@
-/**
- * The executable collection-operation contract. Runtime parsers, capability
- * compilation, and public types must all consume this value; do not maintain a
- * second operation allow-list at an SDK or service boundary.
- */
+// Generated by scripts/generate-operation-catalog.mjs. Do not edit directly.
+export const OPERATION_CATALOG_VERSION = 1;
 export const COLLECTION_OPERATIONS = [
     "describe",
     "changes",
@@ -30,10 +27,148 @@ export const COLLECTION_OPERATIONS = [
     "reconcile_timers",
     "sync"
 ];
+export const FILE_CONTROL_MESSAGE_TYPES = [
+    "list_files",
+    "open_file_upload",
+    "open_file_download",
+    "move_file",
+    "delete_file",
+    "get_file_transfer_status",
+    "commit_file_upload",
+    "abort_file_transfer"
+];
+const COLLECTION_MUTATION_RULES = {
+    "describe": "never",
+    "changes": "never",
+    "read": "never",
+    "query": "never",
+    "list_views": "never",
+    "execute_view": "never",
+    "read_view_source": "never",
+    "create_view_source": "always",
+    "update_view_source": "always",
+    "delete_view_source": "always",
+    "validate": "never",
+    "create": "always",
+    "update": "always",
+    "delete": "always",
+    "rename": "always",
+    "read_type": "never",
+    "create_type": "always",
+    "update_type": "always",
+    "assess_type_pack": "never",
+    "apply_type_pack": "always",
+    "list_timers": "never",
+    "put_timer": "always",
+    "cancel_timer": "always",
+    "reconcile_timers": "always",
+    "sync": "sync_action"
+};
+const COLLECTION_INPUT_SCHEMA_VERSIONS = {
+    "describe": 1,
+    "changes": 1,
+    "read": 1,
+    "query": 1,
+    "list_views": 1,
+    "execute_view": 1,
+    "read_view_source": 1,
+    "create_view_source": 1,
+    "update_view_source": 1,
+    "delete_view_source": 1,
+    "validate": 1,
+    "create": 1,
+    "update": 1,
+    "delete": 1,
+    "rename": 1,
+    "read_type": 1,
+    "create_type": 1,
+    "update_type": 1,
+    "assess_type_pack": 1,
+    "apply_type_pack": 1,
+    "list_timers": 1,
+    "put_timer": 1,
+    "cancel_timer": 1,
+    "reconcile_timers": 1,
+    "sync": 1
+};
+const FILE_CONTROL_INPUT_SCHEMA_VERSIONS = {
+    "list_files": 1,
+    "open_file_upload": 1,
+    "open_file_download": 1,
+    "move_file": 1,
+    "delete_file": 1,
+    "get_file_transfer_status": 1,
+    "commit_file_upload": 1,
+    "abort_file_transfer": 1
+};
+const MUTATING_FILE_CONTROL_MESSAGE_TYPES = new Set([
+    "open_file_upload",
+    "move_file",
+    "delete_file",
+    "commit_file_upload",
+    "abort_file_transfer"
+]);
+export const MUTATING_OPERATION_IDENTIFIERS = [
+    "create_view_source",
+    "update_view_source",
+    "delete_view_source",
+    "create",
+    "update",
+    "delete",
+    "rename",
+    "create_type",
+    "update_type",
+    "apply_type_pack",
+    "put_timer",
+    "cancel_timer",
+    "reconcile_timers",
+    "sync:mutate",
+    "file_control:open_file_upload",
+    "file_control:move_file",
+    "file_control:delete_file",
+    "file_control:commit_file_upload",
+    "file_control:abort_file_transfer"
+];
 const COLLECTION_OPERATION_SET = new Set(COLLECTION_OPERATIONS);
+const FILE_CONTROL_MESSAGE_TYPE_SET = new Set(FILE_CONTROL_MESSAGE_TYPES);
 export function isCollectionOperation(value) {
     return COLLECTION_OPERATION_SET.has(value);
 }
 export function areCollectionOperations(values) {
     return values.every(isCollectionOperation);
 }
+export function isFileControlMessageType(value) {
+    return FILE_CONTROL_MESSAGE_TYPE_SET.has(value);
+}
+export function operationInputSchemaVersion(operation, input) {
+    if (operation === "file_control") {
+        const type = isObject(input) && typeof input.type === "string" ? input.type : "";
+        if (!isFileControlMessageType(type))
+            throw new Error(`Unknown file-control message: ${type}`);
+        return FILE_CONTROL_INPUT_SCHEMA_VERSIONS[type];
+    }
+    return COLLECTION_INPUT_SCHEMA_VERSIONS[operation];
+}
+export function mutationOperationIdentifier(operation, input) {
+    const object = isObject(input) ? input : {};
+    if (object.dry_run === true)
+        return null;
+    if (operation === "file_control") {
+        const type = typeof object.type === "string" ? object.type : "";
+        return MUTATING_FILE_CONTROL_MESSAGE_TYPES.has(type)
+            ? `file_control:${type}`
+            : null;
+    }
+    const rule = COLLECTION_MUTATION_RULES[operation];
+    if (rule === "always")
+        return operation;
+    if (rule === "sync_action" && object.action === "mutate")
+        return "sync:mutate";
+    return null;
+}
+export function isMutatingOperation(operation, input) {
+    return mutationOperationIdentifier(operation, input) !== null;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-protocol",
-  "version": "0.1.0-beta.31",
+  "version": "0.1.0-beta.32",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
-    "test": "node --test test/*.test.mjs && node ../../scripts/generate-connect-problems.mjs --check",
+    "test": "node --test test/*.test.mjs && node ../../scripts/generate-connect-problems.mjs --check && node ../../scripts/generate-operation-catalog.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/schemas/catalog.json

@@ -7,7 +7,7 @@
     "connect_protocol": "./connect-protocol.v1.schema.json",
     "connect_problem": "./connect-problem.v1.schema.json",
     "connect_problem_catalog": "./connect-problems.v1.catalog.json",
-    "encrypted_relay": "./encrypted-relay.v1.schema.json",
+    "encrypted_relay": "./encrypted-relay.v2.schema.json",
     "files": "./files.v1.schema.json",
     "notification_webhook": "./notification-webhook.v1.schema.json",
     "sync": "./sync.v1.schema.json"