jmap-kit 0.0.0 → 1.0.2

package/dist/src/capabilities/core-capability.d.ts

@@ -0,0 +1,307 @@
+import { z } from "zod/v4";
+import type { ValidationPlugin } from "../capability-registry/types.js";
+import { CORE_CAPABILITY_URI } from "../common/registry.js";
+import type { BaseFilterCondition, BaseGetRequestInvocationArgs, BaseInvocationArgs, BaseObject, BaseQueryRequestInvocationArgs, BaseSetRequestInvocationArgs } from "../invocation/types.js";
+import type { BlobCopyRequestInvocationArgs } from "./blob/types.js";
+/**
+ * Validates that `/get` method calls do not exceed the server's `maxObjectsInGet` limit.
+ *
+ * **Object Retrieval Limits (RFC 8620 Section 5.1):**
+ * - Enforces the `maxObjectsInGet` limit defined in the Core capability object
+ * - This limit applies to the `ids` array in any `/get` method call (`Mailbox/get`, `Email/get`, etc.)
+ * - Prevents requests that would be rejected by the server with a `requestTooLarge` error
+ * - The server defines this limit based on resource constraints and performance characteristics
+ *
+ * This validation catches oversized requests client-side before transmission, providing
+ * immediate feedback and avoiding unnecessary network traffic.
+ *
+ * **Example:**
+ * If a server sets `maxObjectsInGet: 500`, attempting to fetch 1000 email IDs in a single
+ * `Email/get` call would be caught and reported by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.1 | RFC 8620 Section 5.1: /get}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export declare const maxObjectsInGetPlugin: ValidationPlugin<"invocation", BaseGetRequestInvocationArgs<BaseInvocationArgs>>;
+/**
+ * Validates that `/set` method calls do not exceed the server's `maxObjectsInSet` limit.
+ *
+ * **Object Modification Limits (RFC 8620 Section 5.3):**
+ * - Enforces the `maxObjectsInSet` limit defined in the Core capability object
+ * - Counts the total number of operations across `create`, `update`, and `destroy` arguments
+ * - Applies to all `/set` method calls (`Mailbox/set`, `Email/set`, etc.)
+ * - Prevents requests that would be rejected with a `requestTooLarge` error
+ * - The server defines this limit to manage transaction size and resource usage
+ *
+ * This validation catches oversized batch operations client-side before transmission,
+ * allowing clients to split large operations into multiple requests if needed.
+ *
+ * **Example:**
+ * If a server sets `maxObjectsInSet: 100`, attempting to create 50 mailboxes, update 30,
+ * and delete 25 (total: 105 operations) in a single `Mailbox/set` call would be rejected.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3 | RFC 8620 Section 5.3: /set}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export declare const maxObjectsInSetPlugin: ValidationPlugin<"invocation", BaseSetRequestInvocationArgs<BaseInvocationArgs>>;
+/**
+ * Validates that `/query` method calls only use server-supported collation algorithms.
+ *
+ * **Collation Algorithm Support (RFC 8620 Section 5.5):**
+ * - Validates that any `collation` property in sort criteria is included in the server's
+ *   `collationAlgorithms` capability list
+ * - Collation algorithms control how strings are compared and sorted (case sensitivity,
+ *   locale-specific ordering, accent handling, etc.)
+ * - Common algorithms include "i;ascii-casemap" (case-insensitive ASCII) and "i;unicode-casemap"
+ * - Server support varies based on implementation and internationalisation capabilities
+ *
+ * This validation prevents query errors by catching unsupported collation algorithms before
+ * sending the request. Without this check, the server would reject the query with an
+ * `unsupportedSort` error.
+ *
+ * **Example:**
+ * If a server only supports "i;ascii-casemap" collation, attempting to sort with
+ * "i;unicode-casemap" would be caught and reported by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.5 | RFC 8620 Section 5.5: /query}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export declare const collationAlgorithmsPlugin: ValidationPlugin<"invocation", BaseQueryRequestInvocationArgs<BaseInvocationArgs, BaseFilterCondition>>;
+/**
+ * Prevents `/set` method calls on read-only accounts.
+ *
+ * **Read-Only Account Protection (RFC 8620 Section 1.6.2, Section 5.3):**
+ * - Validates that the target account's `isReadOnly` property is `false`
+ * - Read-only accounts cannot accept any data modification operations
+ * - All `/set` methods (create, update, destroy) require write access
+ * - Attempting modifications on read-only accounts would fail with an `accountReadOnly` error
+ *
+ * This validator catches the error client-side before making a server request, providing
+ * immediate feedback when attempting invalid operations on read-only accounts.
+ *
+ * **Common read-only scenarios:**
+ * - Shared resources with read-only permissions
+ * - Archive or backup accounts
+ * - Accounts in maintenance mode
+ * - Delegated access with restricted permissions
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3 | RFC 8620 Section 5.3: /set}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export declare const preventSetOnReadOnlyAccountPlugin: ValidationPlugin<"invocation", BaseSetRequestInvocationArgs<BaseObject>>;
+/**
+ * Validates that API requests do not exceed the server's `maxCallsInRequest` limit.
+ *
+ * **Request Batching Limits (RFC 8620 Section 3.2):**
+ * - Enforces the `maxCallsInRequest` limit defined in the Core capability object
+ * - This limit applies to the total number of method calls in the `methodCalls` array
+ * - JMAP allows batching multiple method calls in a single request for efficiency
+ * - Prevents requests that would be rejected with a `requestTooLarge` error
+ * - The server defines this limit to manage request processing complexity and resources
+ *
+ * This validation runs during the `pre-build` lifecycle hook, checking the request structure
+ * before serialisation. It catches oversized batches early, allowing clients to split large
+ * batches into multiple API requests.
+ *
+ * **Example:**
+ * If a server sets `maxCallsInRequest: 50`, attempting to batch 75 method calls
+ * (e.g., Email/get + 50 Email/set + 24 Mailbox/get) would be caught by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-3.2 | RFC 8620 Section 3.2: Making an API Request}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export declare const maxCallsInRequestPlugin: ValidationPlugin<"pre-build">;
+/**
+ * Validates that serialised API requests do not exceed the server's `maxSizeRequest` limit.
+ *
+ * **Request Size Limits (RFC 8620 Section 3.2):**
+ * - Enforces the `maxSizeRequest` limit defined in the Core capability object
+ * - Measures the total size of the serialised request body in bytes
+ * - This limit applies after the request has been serialised (JSON stringified and encoded)
+ * - Prevents requests that would be rejected with a `requestTooLarge` error
+ * - The server defines this limit based on available memory, bandwidth, and processing capacity
+ *
+ * This validation runs during the `post-serialization` lifecycle hook, checking the actual
+ * wire format size. It handles various body formats (string, Blob, ArrayBuffer) and provides
+ * human-readable error messages in megabytes.
+ *
+ * **Example:**
+ * If a server sets `maxSizeRequest: 10000000` (10 MB), attempting to send a request with
+ * a large Email/import containing 15 MB of email data would be caught and reported as
+ * "Request size (15.00 MB) exceeds server limit of 10.00 MB".
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-3.2 | RFC 8620 Section 3.2: Making an API Request}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export declare const maxSizeRequestPlugin: ValidationPlugin<"post-serialization">;
+/**
+ * Prevents Blob/copy operations on read-only target accounts.
+ *
+ * **Read-Only Account Protection for Blob/copy:**
+ * - Validates that the target account's (accountId) `isReadOnly` property is `false`
+ * - Blob/copy writes blobs to the target account, requiring write access
+ * - The source account (fromAccountId) only needs read access
+ * - Attempting to copy to a read-only account would fail with an `accountReadOnly` error
+ *
+ * This validator catches the error client-side before making a server request, providing
+ * immediate feedback when attempting to copy blobs to read-only accounts.
+ *
+ * **Common read-only scenarios:**
+ * - Shared accounts with read-only permissions
+ * - Archive or backup accounts
+ * - Accounts in maintenance mode
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-6.3 | RFC 8620 Section 6.3: Blob/copy}
+
+ */
+export declare const preventBlobCopyOnReadOnlyAccountPlugin: ValidationPlugin<"invocation", BlobCopyRequestInvocationArgs>;
+/**
+ * Defines the Core capability, including Core/echo and Blob/copy invocations
+ * and validation plugins.
+ */
+export declare const CoreCapability: {
+    uri: "urn:ietf:params:jmap:core";
+    invocations: {
+        Core: {
+            request: {
+                echo: import("../invocation/types.js").InvocationFactory<BaseInvocationArgs, import("./core/core.js").CoreInvocation<BaseInvocationArgs>>;
+            };
+            response: {
+                echo: import("../invocation/types.js").InvocationFactory<BaseInvocationArgs, import("./core/core.js").CoreInvocation<BaseInvocationArgs>>;
+            };
+        };
+        Blob: {
+            request: {
+                copy: import("../invocation/types.js").InvocationFactory<BlobCopyRequestInvocationArgs, import("./blob/blob.js").BlobInvocation<BlobCopyRequestInvocationArgs>>;
+            };
+            response: {
+                copy: import("../invocation/types.js").InvocationFactory<import("./blob/types.js").BlobCopyResponseInvocationArgs, import("./blob/blob.js").BlobInvocation<import("./blob/types.js").BlobCopyResponseInvocationArgs>>;
+            };
+        };
+    };
+    validators: ({
+        name: string;
+        hook: "pre-build";
+        trigger: import("../capability-registry/types.js").PluginTrigger;
+        validate(this: void, context: import("../capability-registry/types.js").PluginContext<"pre-build">): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "post-serialization";
+        trigger: import("../capability-registry/types.js").PluginTrigger;
+        validate(this: void, context: import("../capability-registry/types.js").PluginContext<"post-serialization">): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<BaseGetRequestInvocationArgs<BaseInvocationArgs>>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<BaseSetRequestInvocationArgs<BaseInvocationArgs>>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<BaseQueryRequestInvocationArgs<BaseInvocationArgs, BaseFilterCondition>>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<BlobCopyRequestInvocationArgs>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    })[];
+    schema: {
+        serverCapability: z.ZodObject<{
+            maxSizeUpload: z.ZodNumber;
+            maxConcurrentUpload: z.ZodNumber;
+            maxSizeRequest: z.ZodNumber;
+            maxConcurrentRequests: z.ZodNumber;
+            maxCallsInRequest: z.ZodNumber;
+            maxObjectsInGet: z.ZodNumber;
+            maxObjectsInSet: z.ZodNumber;
+            collationAlgorithms: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+};
+declare module "../common/types.js" {
+    interface ServerCapabilityRegistry {
+        [CORE_CAPABILITY_URI]: {
+            /**
+             * The maximum file size, in octets, that the server will accept for a single file upload
+             * (for any purpose). Suggested minimum: 50,000,000.
+             */
+            maxSizeUpload: UnsignedInt;
+            /**
+             * The maximum number of concurrent requests the server will accept to the upload endpoint.
+             * Suggested minimum: 4.
+             */
+            maxConcurrentUpload: UnsignedInt;
+            /**
+             * The maximum size, in octets, that the server will accept for a single request to the API
+             * endpoint. Suggested minimum: 10,000,000.
+             */
+            maxSizeRequest: UnsignedInt;
+            /**
+             * The maximum number of concurrent requests the server will accept to the API endpoint.
+             * Suggested minimum: 4.
+             */
+            maxConcurrentRequests: UnsignedInt;
+            /**
+             * The maximum number of method calls the server will accept in a single request to the API
+             * endpoint. Suggested minimum: 16.
+             */
+            maxCallsInRequest: UnsignedInt;
+            /**
+             * The maximum number of objects that the client may request in a single /get type method
+             * call. Suggested minimum: 500.
+             */
+            maxObjectsInGet: UnsignedInt;
+            /**
+             * The maximum number of objects the client may send to create, update, or destroy in a
+             * single /set type method call. This is the combined total, e.g., if the maximum is 10, you
+             * could not create 7 objects and destroy 6, as this would be 13 actions, which exceeds the
+             * limit. Suggested minimum: 500.
+             */
+            maxObjectsInSet: UnsignedInt;
+            /**
+             * A list of identifiers for algorithms registered in the collation registry, as defined in
+             * {@link https://www.rfc-editor.org/rfc/rfc4790.html RFC 4790}, that the server supports for
+             * sorting when querying records.
+             */
+            collationAlgorithms: string[];
+        };
+    }
+    interface AccountCapabilityRegistry {
+        "urn:ietf:params:jmap:core": EmptyObject;
+    }
+}

package/dist/src/capabilities/core-capability.js

@@ -0,0 +1,344 @@
+import { z } from "zod/v4";
+import { CORE_CAPABILITY_URI } from "../common/registry.js";
+import { Blob } from "./blob/blob.js";
+import { Core } from "./core/core.js";
+import { assertInvocationMethod } from "./utils/assert-invocation-method.js";
+import { createReadOnlyAccountValidator } from "./utils/create-readonly-account-validator.js";
+const MEGABYTE = 1_000_000; // 1 MB in bytes
+/**
+ * Validates that `/get` method calls do not exceed the server's `maxObjectsInGet` limit.
+ *
+ * **Object Retrieval Limits (RFC 8620 Section 5.1):**
+ * - Enforces the `maxObjectsInGet` limit defined in the Core capability object
+ * - This limit applies to the `ids` array in any `/get` method call (`Mailbox/get`, `Email/get`, etc.)
+ * - Prevents requests that would be rejected by the server with a `requestTooLarge` error
+ * - The server defines this limit based on resource constraints and performance characteristics
+ *
+ * This validation catches oversized requests client-side before transmission, providing
+ * immediate feedback and avoiding unnecessary network traffic.
+ *
+ * **Example:**
+ * If a server sets `maxObjectsInGet: 500`, attempting to fetch 1000 email IDs in a single
+ * `Email/get` call would be caught and reported by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.1 | RFC 8620 Section 5.1: /get}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export const maxObjectsInGetPlugin = {
+    name: "core-max-objects-in-get",
+    hook: "invocation",
+    trigger: {
+        method: "get",
+    },
+    validate(context) {
+        const { serverCapabilities, invocation } = context;
+        assertInvocationMethod(invocation, "get");
+        const coreCapability = serverCapabilities[CORE_CAPABILITY_URI];
+        const ids = invocation.getArgument("ids");
+        if (ids && ids.length > coreCapability.maxObjectsInGet) {
+            return {
+                valid: false,
+                errors: [
+                    new Error(`Request contains ${ids.length} objects, but server limit is ${coreCapability.maxObjectsInGet}`),
+                ],
+            };
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Validates that `/set` method calls do not exceed the server's `maxObjectsInSet` limit.
+ *
+ * **Object Modification Limits (RFC 8620 Section 5.3):**
+ * - Enforces the `maxObjectsInSet` limit defined in the Core capability object
+ * - Counts the total number of operations across `create`, `update`, and `destroy` arguments
+ * - Applies to all `/set` method calls (`Mailbox/set`, `Email/set`, etc.)
+ * - Prevents requests that would be rejected with a `requestTooLarge` error
+ * - The server defines this limit to manage transaction size and resource usage
+ *
+ * This validation catches oversized batch operations client-side before transmission,
+ * allowing clients to split large operations into multiple requests if needed.
+ *
+ * **Example:**
+ * If a server sets `maxObjectsInSet: 100`, attempting to create 50 mailboxes, update 30,
+ * and delete 25 (total: 105 operations) in a single `Mailbox/set` call would be rejected.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3 | RFC 8620 Section 5.3: /set}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export const maxObjectsInSetPlugin = {
+    name: "core-max-objects-in-set",
+    hook: "invocation",
+    trigger: {
+        method: "set",
+    },
+    validate(context) {
+        const { serverCapabilities, invocation } = context;
+        assertInvocationMethod(invocation, "set");
+        const coreCapability = serverCapabilities[CORE_CAPABILITY_URI];
+        const create = invocation.getArgument("create");
+        const update = invocation.getArgument("update");
+        const destroy = invocation.getArgument("destroy");
+        const totalObjects = (create ? Object.keys(create).length : 0) +
+            (update ? Object.keys(update).length : 0) +
+            (destroy ? destroy.length : 0);
+        if (totalObjects > coreCapability.maxObjectsInSet) {
+            return {
+                valid: false,
+                errors: [
+                    new Error(`Request contains ${totalObjects} operations, but server limit is ${coreCapability.maxObjectsInSet}`),
+                ],
+            };
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Validates that `/query` method calls only use server-supported collation algorithms.
+ *
+ * **Collation Algorithm Support (RFC 8620 Section 5.5):**
+ * - Validates that any `collation` property in sort criteria is included in the server's
+ *   `collationAlgorithms` capability list
+ * - Collation algorithms control how strings are compared and sorted (case sensitivity,
+ *   locale-specific ordering, accent handling, etc.)
+ * - Common algorithms include "i;ascii-casemap" (case-insensitive ASCII) and "i;unicode-casemap"
+ * - Server support varies based on implementation and internationalisation capabilities
+ *
+ * This validation prevents query errors by catching unsupported collation algorithms before
+ * sending the request. Without this check, the server would reject the query with an
+ * `unsupportedSort` error.
+ *
+ * **Example:**
+ * If a server only supports "i;ascii-casemap" collation, attempting to sort with
+ * "i;unicode-casemap" would be caught and reported by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.5 | RFC 8620 Section 5.5: /query}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export const collationAlgorithmsPlugin = {
+    name: "core-collation-algorithms",
+    hook: "invocation",
+    trigger: {
+        method: "query",
+    },
+    validate(context) {
+        const { serverCapabilities, invocation } = context;
+        assertInvocationMethod(invocation, "query");
+        const coreCapability = serverCapabilities[CORE_CAPABILITY_URI];
+        const sort = invocation.getArgument("sort");
+        if (sort) {
+            const errors = [];
+            for (const sortCriterion of sort) {
+                if (sortCriterion.collation && !coreCapability.collationAlgorithms.includes(sortCriterion.collation)) {
+                    errors.push(new Error(`Unsupported collation algorithm '${sortCriterion.collation}'. Supported algorithms: ${coreCapability.collationAlgorithms.join(", ")}`));
+                }
+            }
+            if (errors.length > 0) {
+                return {
+                    valid: false,
+                    errors,
+                };
+            }
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Prevents `/set` method calls on read-only accounts.
+ *
+ * **Read-Only Account Protection (RFC 8620 Section 1.6.2, Section 5.3):**
+ * - Validates that the target account's `isReadOnly` property is `false`
+ * - Read-only accounts cannot accept any data modification operations
+ * - All `/set` methods (create, update, destroy) require write access
+ * - Attempting modifications on read-only accounts would fail with an `accountReadOnly` error
+ *
+ * This validator catches the error client-side before making a server request, providing
+ * immediate feedback when attempting invalid operations on read-only accounts.
+ *
+ * **Common read-only scenarios:**
+ * - Shared resources with read-only permissions
+ * - Archive or backup accounts
+ * - Accounts in maintenance mode
+ * - Delegated access with restricted permissions
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3 | RFC 8620 Section 5.3: /set}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export const preventSetOnReadOnlyAccountPlugin = createReadOnlyAccountValidator({
+    name: "core-prevent-set-on-readonly-account",
+    trigger: {
+        method: "set",
+    },
+});
+/**
+ * Validates that API requests do not exceed the server's `maxCallsInRequest` limit.
+ *
+ * **Request Batching Limits (RFC 8620 Section 3.2):**
+ * - Enforces the `maxCallsInRequest` limit defined in the Core capability object
+ * - This limit applies to the total number of method calls in the `methodCalls` array
+ * - JMAP allows batching multiple method calls in a single request for efficiency
+ * - Prevents requests that would be rejected with a `requestTooLarge` error
+ * - The server defines this limit to manage request processing complexity and resources
+ *
+ * This validation runs during the `pre-build` lifecycle hook, checking the request structure
+ * before serialisation. It catches oversized batches early, allowing clients to split large
+ * batches into multiple API requests.
+ *
+ * **Example:**
+ * If a server sets `maxCallsInRequest: 50`, attempting to batch 75 method calls
+ * (e.g., Email/get + 50 Email/set + 24 Mailbox/get) would be caught by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-3.2 | RFC 8620 Section 3.2: Making an API Request}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export const maxCallsInRequestPlugin = {
+    name: "core-max-calls-in-request",
+    hook: "pre-build",
+    trigger: {},
+    validate(context) {
+        const { serverCapabilities, data: { methodCalls }, } = context;
+        const { maxCallsInRequest } = serverCapabilities[CORE_CAPABILITY_URI];
+        if (methodCalls.length > maxCallsInRequest) {
+            return {
+                valid: false,
+                errors: [
+                    new Error(`Request contains ${methodCalls.length} methods, but server limit is ${maxCallsInRequest}`),
+                ],
+            };
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Validates that serialised API requests do not exceed the server's `maxSizeRequest` limit.
+ *
+ * **Request Size Limits (RFC 8620 Section 3.2):**
+ * - Enforces the `maxSizeRequest` limit defined in the Core capability object
+ * - Measures the total size of the serialised request body in bytes
+ * - This limit applies after the request has been serialised (JSON stringified and encoded)
+ * - Prevents requests that would be rejected with a `requestTooLarge` error
+ * - The server defines this limit based on available memory, bandwidth, and processing capacity
+ *
+ * This validation runs during the `post-serialization` lifecycle hook, checking the actual
+ * wire format size. It handles various body formats (string, Blob, ArrayBuffer) and provides
+ * human-readable error messages in megabytes.
+ *
+ * **Example:**
+ * If a server sets `maxSizeRequest: 10000000` (10 MB), attempting to send a request with
+ * a large Email/import containing 15 MB of email data would be caught and reported as
+ * "Request size (15.00 MB) exceeds server limit of 10.00 MB".
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-3.2 | RFC 8620 Section 3.2: Making an API Request}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+
+ */
+export const maxSizeRequestPlugin = {
+    name: "core-max-size-request",
+    hook: "post-serialization",
+    trigger: {},
+    async validate(context) {
+        const { serverCapabilities, data: { body }, } = context;
+        const { maxSizeRequest } = serverCapabilities[CORE_CAPABILITY_URI];
+        // Forward-compatibility: serialize() always produces a string body; Blob and ArrayBuffer
+        // paths exist for custom post-serialization transformers.
+        let inputData;
+        if (typeof body === "string") {
+            const encoder = new TextEncoder();
+            inputData = encoder.encode(body);
+            /* v8 ignore start */
+            /* istanbul ignore else */
+        }
+        else if (body instanceof globalThis.Blob) {
+            /* istanbul ignore next */
+            inputData = new Uint8Array(await body.arrayBuffer());
+            /* istanbul ignore else */
+        }
+        else {
+            inputData = new Uint8Array(body);
+        }
+        /* v8 ignore stop */
+        const requestSize = inputData.length;
+        if (requestSize > maxSizeRequest) {
+            const sizeInMB = (requestSize / MEGABYTE).toFixed(2);
+            const maxSizeInMB = (maxSizeRequest / MEGABYTE).toFixed(2);
+            return {
+                valid: false,
+                errors: [new Error(`Request size (${sizeInMB} MB) exceeds server limit of ${maxSizeInMB} MB`)],
+            };
+        }
+        return {
+            valid: true,
+        };
+    },
+};
+/**
+ * Prevents Blob/copy operations on read-only target accounts.
+ *
+ * **Read-Only Account Protection for Blob/copy:**
+ * - Validates that the target account's (accountId) `isReadOnly` property is `false`
+ * - Blob/copy writes blobs to the target account, requiring write access
+ * - The source account (fromAccountId) only needs read access
+ * - Attempting to copy to a read-only account would fail with an `accountReadOnly` error
+ *
+ * This validator catches the error client-side before making a server request, providing
+ * immediate feedback when attempting to copy blobs to read-only accounts.
+ *
+ * **Common read-only scenarios:**
+ * - Shared accounts with read-only permissions
+ * - Archive or backup accounts
+ * - Accounts in maintenance mode
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-6.3 | RFC 8620 Section 6.3: Blob/copy}
+
+ */
+export const preventBlobCopyOnReadOnlyAccountPlugin = createReadOnlyAccountValidator({
+    name: "core-prevent-blob-copy-on-readonly-account",
+    trigger: {
+        dataType: "Blob",
+        method: "copy",
+    },
+});
+const coreServerCapabilitySchema = z.looseObject({
+    maxSizeUpload: z.number().int().min(0),
+    maxConcurrentUpload: z.number().int().min(1),
+    maxSizeRequest: z.number().int().min(0),
+    maxConcurrentRequests: z.number().int().min(0),
+    maxCallsInRequest: z.number().int().min(0),
+    maxObjectsInGet: z.number().int().min(0),
+    maxObjectsInSet: z.number().int().min(0),
+    collationAlgorithms: z.array(z.string()),
+});
+/**
+ * Defines the Core capability, including Core/echo and Blob/copy invocations
+ * and validation plugins.
+ */
+export const CoreCapability = {
+    uri: CORE_CAPABILITY_URI,
+    invocations: {
+        Core,
+        Blob: {
+            request: {
+                copy: Blob.request.copy,
+            },
+            response: {
+                copy: Blob.response.copy,
+            },
+        },
+    },
+    validators: [
+        maxObjectsInGetPlugin,
+        maxObjectsInSetPlugin,
+        collationAlgorithmsPlugin,
+        preventSetOnReadOnlyAccountPlugin,
+        preventBlobCopyOnReadOnlyAccountPlugin,
+        maxCallsInRequestPlugin,
+        maxSizeRequestPlugin,
+    ],
+    schema: { serverCapability: coreServerCapabilitySchema },
+};
+//# sourceMappingURL=core-capability.js.map

package/dist/src/capabilities/core-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-capability.js","sourceRoot":"","sources":["../../../src/capabilities/core-capability.ts"],"names":[],"mappings":"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"}