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

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 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 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", "assess_collection_setup", "apply_collection_setup", "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", "apply_collection_setup", "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",
@@ -24,16 +21,161 @@ export const COLLECTION_OPERATIONS = [
     "update_type",
     "assess_type_pack",
     "apply_type_pack",
+    "assess_collection_setup",
+    "apply_collection_setup",
     "list_timers",
     "put_timer",
     "cancel_timer",
     "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",
+    "assess_collection_setup": "never",
+    "apply_collection_setup": "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,
+    "assess_collection_setup": 1,
+    "apply_collection_setup": 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",
+    "apply_collection_setup",
+    "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.33",
   "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,8 @@
     "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",
+    "mdbase_query_v0_3": "./mdbase-query.v0.3.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"