ldap-rest 1.2.1 → 1.3.0

package/dist/src/plugins/twake/james.d.ts

@@ -16,7 +16,23 @@ type Identity = {
 };
 /** Signatures an identity carries over, see {@link Identity} */
 export type Signatures = Pick<Identity, 'htmlSignature' | 'textSignature'>;
+export declare const QuotaParams: import("@sinclair/typebox").TObject<{
+    user: import("@sinclair/typebox").TString;
+}>;
 export default class James extends TwakePlugin {
+    static optionDefinitions: {
+        james_webadmin_url: import("../../config/options").StringOption;
+        james_webadmin_token: import("../../config/options").StringOption;
+        james_signature_template: import("../../config/options").StringOption;
+        james_concurrency: import("../../config/options").NumberOption;
+        james_init_delay: import("../../config/options").NumberOption;
+        james_retry_attempts: import("../../config/options").NumberOption;
+        james_retry_delay: import("../../config/options").NumberOption;
+        james_mailing_list_branch: import("../../config/options").ArrayOption;
+        james_mailbox_type_attribute: import("../../config/options").StringOption;
+        james_sync_forwards: import("../../config/options").BooleanOption;
+        james_team_mailbox_any_domain: import("../../config/options").BooleanOption;
+    };
     name: string;
     roles: Role[];
     dependencies: {
@@ -30,6 +46,7 @@ export default class James extends TwakePlugin {
     private forwardAttr;
     private initDelay;
     constructor(server: DM);
+    private get settings();
     /**
      * Register API routes
      */

package/dist/src/plugins/twake/james.options.d.ts

@@ -0,0 +1,21 @@
+/**
+ * James plugin options, see `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const jamesOptions: {
+    james_webadmin_url: import("../../config/options").StringOption;
+    james_webadmin_token: import("../../config/options").StringOption;
+    james_signature_template: import("../../config/options").StringOption;
+    james_concurrency: import("../../config/options").NumberOption;
+    james_init_delay: import("../../config/options").NumberOption;
+    james_retry_attempts: import("../../config/options").NumberOption;
+    james_retry_delay: import("../../config/options").NumberOption;
+    james_mailing_list_branch: import("../../config/options").ArrayOption;
+    james_mailbox_type_attribute: import("../../config/options").StringOption;
+    james_sync_forwards: import("../../config/options").BooleanOption;
+    james_team_mailbox_any_domain: import("../../config/options").BooleanOption;
+};
+export type JamesOptions = OptionsOf<typeof jamesOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function jamesOptionsOf(config: Config): JamesOptions;

package/dist/src/plugins/twake/lifecycleEvents.d.ts

@@ -23,6 +23,18 @@ interface Rule {
 }
 export declare function parseRules(source: string): Rule[];
 export default class TwakeLifecycleEvents extends DmPlugin {
+    static optionDefinitions: {
+        twake_lifecycle_role_attribute: import("../../config/options").StringOption;
+        twake_lifecycle_lock_attribute: import("../../config/options").StringOption;
+        twake_lifecycle_lock_value: import("../../config/options").StringOption;
+        twake_lifecycle_deleted_attribute: import("../../config/options").StringOption;
+        twake_lifecycle_deleted_value: import("../../config/options").StringOption;
+        twake_lifecycle_deleted_at_attribute: import("../../config/options").StringOption;
+        twake_lifecycle_deleted_at_format: import("../../config/options").StringOption;
+        twake_lifecycle_reason_attribute: import("../../config/options").StringOption;
+        twake_lifecycle_rules: import("../../config/options").StringOption;
+        twake_lifecycle_member_attribute: import("../../config/options").StringOption;
+    };
     name: string;
     roles: Role[];
     dependencies: {

package/dist/src/plugins/twake/migrationProxy.d.ts

@@ -1,14 +1,3 @@
-/**
- * @module plugins/twake/migrationProxy
- *
- * Keeps the migrated-users list of the Twake Mail migration proxy in step
- * with the accounts of the directory: an account created during the
- * migration has no mailbox on the old system, so the proxy has to route it
- * to the new one from its first login, and the addresses of a migrated
- * account have to follow it.
- *
- * See `docs/usage/plugins/integrations/mail-migration.md`.
- */
 import type { Express } from 'express';
 import TwakePlugin from '../../abstract/twakePlugin';
 import { type Role } from '../../abstract/plugin';
@@ -27,7 +16,18 @@ import type { HealthStatus } from '../../lib/health';
  *           type: boolean
  *           description: Whether the proxy routes the user to the new backend
  */
+export declare const MailMigrationParams: import("@sinclair/typebox").TObject<{
+    user: import("@sinclair/typebox").TString;
+}>;
 export default class MigrationProxy extends TwakePlugin {
+    static optionDefinitions: {
+        migration_proxy_url: import("../../config/options").StringOption;
+        migration_proxy_token: import("../../config/options").StringOption;
+        migration_proxy_branch: import("../../config/options").ArrayOption;
+        migration_proxy_concurrency: import("../../config/options").NumberOption;
+        migration_proxy_retry_attempts: import("../../config/options").NumberOption;
+        migration_proxy_retry_delay: import("../../config/options").NumberOption;
+    };
     name: string;
     roles: Role[];
     dependencies: {

package/dist/src/plugins/twake/migrationProxy.options.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Twake Mail migration proxy options, see `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const migrationProxyOptions: {
+    migration_proxy_url: import("../../config/options").StringOption;
+    migration_proxy_token: import("../../config/options").StringOption;
+    migration_proxy_branch: import("../../config/options").ArrayOption;
+    migration_proxy_concurrency: import("../../config/options").NumberOption;
+    migration_proxy_retry_attempts: import("../../config/options").NumberOption;
+    migration_proxy_retry_delay: import("../../config/options").NumberOption;
+};
+export type MigrationProxyOptions = OptionsOf<typeof migrationProxyOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function migrationProxyOptionsOf(config: Config): MigrationProxyOptions;

package/dist/src/plugins/twake/spaces.d.ts

@@ -18,7 +18,35 @@ export type Space = {
         role: SpaceRole;
     }[];
 };
+export declare const SpaceOrganizationParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+}>;
+export declare const SpaceParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    spaceId: import("@sinclair/typebox").TString;
+}>;
+export declare const SpaceMemberParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    spaceId: import("@sinclair/typebox").TString;
+    userId: import("@sinclair/typebox").TString;
+}>;
+export declare const SpaceGroupParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    spaceId: import("@sinclair/typebox").TString;
+    groupId: import("@sinclair/typebox").TString;
+}>;
 export default class TwakeSpaces extends DmPlugin {
+    static optionDefinitions: {
+        twake_space_base: import("../../config/options").StringOption;
+        twake_space_class: import("../../config/options").ArrayOption;
+        twake_space_display_name_attribute: import("../../config/options").StringOption;
+        twake_space_admin_attribute: import("../../config/options").StringOption;
+        twake_space_editor_attribute: import("../../config/options").StringOption;
+        twake_space_viewer_attribute: import("../../config/options").StringOption;
+        twake_space_user_role_attribute: import("../../config/options").StringOption;
+        twake_space_exchange: import("../../config/options").StringOption;
+        twake_space_sync_queue: import("../../config/options").StringOption;
+    };
     name: string;
     roles: Role[];
     dependencies: Record<string, string>;
@@ -32,6 +60,8 @@ export default class TwakeSpaces extends DmPlugin {
     private readonly exchange;
     private readonly domainAttribute;
     private readonly orgPattern?;
+    private readonly groupSettings;
+    private readonly instanceSettings;
     private readonly domains;
     /**
      * Changes are followed one at a time, each from the directory as it is

package/dist/src/plugins/twake/tombstone.d.ts

@@ -1,22 +1,24 @@
-/**
- * @module plugins/twake/tombstone
- *
- * Turns the delete of an account into a tombstone: the entry stays, flagged
- * as deleted, dated, locked, with the reason and without the attributes the
- * deployment wants gone. The address it holds cannot be taken again until the
- * tombstone is erased.
- *
- * SCIM treats a tombstone as gone. Erasing removes the entry and its group
- * memberships, once the deletion is old enough or when forced, and announces
- * nothing: the deletion already did.
- *
- * See `docs/usage/plugins/integrations/tombstone.md`.
- */
 import type { Express, Request } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type { Hooks } from '../../hooks';
+export declare const EraseTombstoneBody: import("@sinclair/typebox").TObject<{
+    dn: import("@sinclair/typebox").TString;
+    force: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export declare const EraseTombstoneResponse: import("@sinclair/typebox").TObject<{
+    success: import("@sinclair/typebox").TBoolean;
+}>;
 export default class TwakeTombstone extends DmPlugin {
+    static optionDefinitions: {
+        twake_tombstone_dn: import("../../config/options").ArrayOption;
+        twake_tombstone_default_reason: import("../../config/options").StringOption;
+        twake_tombstone_reason_header: import("../../config/options").StringOption;
+        twake_tombstone_reasons: import("../../config/options").ArrayOption;
+        twake_tombstone_clear_attributes: import("../../config/options").ArrayOption;
+        twake_tombstone_erase_min_age: import("../../config/options").NumberOption;
+        twake_tombstone_group_bases: import("../../config/options").ArrayOption;
+    };
     name: string;
     roles: Role[];
     private readonly attrs;

package/dist/src/plugins/twake/twakeGroups.options.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Twake groups options, see `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const twakeGroupsOptions: {
+    twake_group_base: import("../../config/options").StringOption;
+    twake_group_user_base: import("../../config/options").StringOption;
+    twake_group_organization_dn: import("../../config/options").StringOption;
+    twake_group_organization_status_attribute: import("../../config/options").StringOption;
+    twake_group_organization_deleted_value: import("../../config/options").StringOption;
+    twake_group_display_name_attribute: import("../../config/options").StringOption;
+    twake_group_color_attribute: import("../../config/options").StringOption;
+    twake_group_created_at_attribute: import("../../config/options").StringOption;
+    twake_group_max_page_limit: import("../../config/options").NumberOption;
+    twake_group_member_fields: import("../../config/options").JsonOption<{}>;
+};
+export type TwakeGroupsOptions = OptionsOf<typeof twakeGroupsOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function twakeGroupsOptionsOf(config: Config): TwakeGroupsOptions;

package/dist/src/plugins/twake/twakeInstances.options.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Twake instances options, see `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const twakeInstancesOptions: {
+    twake_instance_dn: import("../../config/options").ArrayOption;
+    twake_instance_skip_attribute: import("../../config/options").StringOption;
+    twake_instance_skip_value: import("../../config/options").StringOption;
+    twake_instance_provider: import("../../config/options").StringOption;
+    twake_instance_id: import("../../config/options").StringOption;
+    twake_instance_fqdn_attribute: import("../../config/options").StringOption;
+    twake_instance_sent_attribute: import("../../config/options").StringOption;
+    twake_instance_locale: import("../../config/options").StringOption;
+    twake_instance_timeout: import("../../config/options").NumberOption;
+    twake_instance_cloudery_url: import("../../config/options").StringOption;
+    twake_instance_cloudery_token: import("../../config/options").StringOption;
+    twake_instance_cloudery_offer: import("../../config/options").StringOption;
+    twake_instance_cloudery_domain: import("../../config/options").StringOption;
+    twake_instance_cloudery_organization_offer: import("../../config/options").StringOption;
+    twake_instance_cozy_url: import("../../config/options").StringOption;
+    twake_instance_cozy_user: import("../../config/options").StringOption;
+    twake_instance_cozy_passphrase: import("../../config/options").StringOption;
+    twake_instance_cozy_domain: import("../../config/options").StringOption;
+    twake_instance_cozy_context: import("../../config/options").StringOption;
+    twake_instance_cozy_apps: import("../../config/options").StringOption;
+    twake_instance_cozy_org_id: import("../../config/options").StringOption;
+    twake_instance_cozy_org_domain: import("../../config/options").StringOption;
+    twake_instance_auth_exchange: import("../../config/options").StringOption;
+    twake_instance_b2b_exchange: import("../../config/options").StringOption;
+    twake_instance_user_created_key: import("../../config/options").StringOption;
+    twake_instance_organization_created_key: import("../../config/options").StringOption;
+    twake_instance_workplace_created_key: import("../../config/options").StringOption;
+    twake_instance_queue: import("../../config/options").StringOption;
+    twake_instance_organization_base: import("../../config/options").StringOption;
+    twake_instance_organization_id_attribute: import("../../config/options").StringOption;
+    twake_instance_organization_domain_attribute: import("../../config/options").StringOption;
+    twake_instance_organization_name_attribute: import("../../config/options").StringOption;
+    twake_instance_organization_fqdn_attribute: import("../../config/options").StringOption;
+};
+export type TwakeInstancesOptions = OptionsOf<typeof twakeInstancesOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function twakeInstancesOptionsOf(config: Config): TwakeInstancesOptions;

package/dist/src/plugins/twake/twakeLifecycle.options.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Account lifecycle options, shared by the Twake lifecycle plugins. See
+ * `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const twakeLifecycleOptions: {
+    twake_lifecycle_role_attribute: import("../../config/options").StringOption;
+    twake_lifecycle_lock_attribute: import("../../config/options").StringOption;
+    twake_lifecycle_lock_value: import("../../config/options").StringOption;
+    twake_lifecycle_deleted_attribute: import("../../config/options").StringOption;
+    twake_lifecycle_deleted_value: import("../../config/options").StringOption;
+    twake_lifecycle_deleted_at_attribute: import("../../config/options").StringOption;
+    twake_lifecycle_deleted_at_format: import("../../config/options").StringOption;
+    twake_lifecycle_reason_attribute: import("../../config/options").StringOption;
+    twake_lifecycle_rules: import("../../config/options").StringOption;
+    twake_lifecycle_member_attribute: import("../../config/options").StringOption;
+};
+export type TwakeLifecycleOptions = OptionsOf<typeof twakeLifecycleOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function twakeLifecycleOptionsOf(config: Config): TwakeLifecycleOptions;

package/dist/src/plugins/twake/twakeSpaces.options.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Twake spaces options, see `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const twakeSpacesOptions: {
+    twake_space_base: import("../../config/options").StringOption;
+    twake_space_class: import("../../config/options").ArrayOption;
+    twake_space_display_name_attribute: import("../../config/options").StringOption;
+    twake_space_admin_attribute: import("../../config/options").StringOption;
+    twake_space_editor_attribute: import("../../config/options").StringOption;
+    twake_space_viewer_attribute: import("../../config/options").StringOption;
+    twake_space_user_role_attribute: import("../../config/options").StringOption;
+    twake_space_exchange: import("../../config/options").StringOption;
+    twake_space_sync_queue: import("../../config/options").StringOption;
+};
+export type TwakeSpacesOptions = OptionsOf<typeof twakeSpacesOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function twakeSpacesOptionsOf(config: Config): TwakeSpacesOptions;

package/dist/src/plugins/twake/twakeTombstone.options.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Twake tombstone options, see `docs/plugin-development/options.md`.
+ */
+import type { Config } from '../../config/args';
+import { type OptionsOf } from '../../config/options';
+export declare const twakeTombstoneOptions: {
+    twake_tombstone_dn: import("../../config/options").ArrayOption;
+    twake_tombstone_default_reason: import("../../config/options").StringOption;
+    twake_tombstone_reason_header: import("../../config/options").StringOption;
+    twake_tombstone_reasons: import("../../config/options").ArrayOption;
+    twake_tombstone_clear_attributes: import("../../config/options").ArrayOption;
+    twake_tombstone_erase_min_age: import("../../config/options").NumberOption;
+    twake_tombstone_group_bases: import("../../config/options").ArrayOption;
+};
+export type TwakeTombstoneOptions = OptionsOf<typeof twakeTombstoneOptions>;
+/** The checked values for a caller that holds a Config instead of the plugin */
+export declare function twakeTombstoneOptionsOf(config: Config): TwakeTombstoneOptions;

package/docs/README.md

@@ -20,6 +20,7 @@ Create and extend LDAP-Rest with custom plugins.
 
 - **[Development Guide](plugin-development/README.md)** - Architecture and plugin creation
 - **[Hooks](plugin-development/hooks.md)** - LDAP hooks system
+- **[Routes](plugin-development/routes.md)** - Declaring routes and their input schemas
 - **[Testing](plugin-development/testing.md)** - Testing with embedded LDAP
 - **[Dependencies](plugin-development/dependencies.md)** - Plugin dependencies matrix
 

package/docs/client-development/api/rest-api.md

@@ -156,6 +156,7 @@ curl -H "Accept: application/json" \
 {
   "apiPrefix": "/api",
   "ldapBase": "dc=example,dc=com",
+  "version": "1.2.1",
   "features": {
     "flatResources": [
       {
@@ -242,6 +243,10 @@ curl -H "Accept: application/json" \
 
 - `apiPrefix`: API URL prefix (default: `/api`)
 - `ldapBase`: LDAP base DN
+- `version`: the server's version, as its `package.json` declares it. A client
+  compares it with the range it supports and tells an administrator when the
+  server is older. Optional: an installation that moved that file leaves it
+  out, and a client must then work without it
 - `features.ldapFlatGeneric.flatResources`: Array of flat LDAP resources (users, positions, etc.)
 - `features.ldapGroups`: Group management configuration (if enabled)
 - `features.ldapOrganizations`: Organization tree configuration (if enabled)
@@ -1078,7 +1083,7 @@ curl -X POST \
 ```
 
 A member that does not exist answers 400 naming it, and none of the members
-is added (unless `--group-allow-unexistent-members` is set). Group creation
+is added (unless `--groups-allow-unexistent-members` is set). Group creation
 checks its `member` list the same way:
 
 ```json
@@ -1335,8 +1340,9 @@ no `limit` was given —
 
 #### 500 Internal Server Error
 
-The failure is in the server's logs, not in the response; the message names
-it only when the server runs with `--debug`:
+Every 5xx answers this body, whether the route threw or reported the failure
+through the server's own helper. The failure is in the server's logs, not in
+the response; the message names it only when the server runs with `--debug`:
 
 ```json
 {

package/docs/client-development/schemas/README.md

@@ -66,7 +66,7 @@ A complete schema consists of two main sections: entity metadata and attribute d
     },
     "mail": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
       "required": false,
       "role": "primaryEmail"
     },
@@ -74,7 +74,7 @@ A complete schema consists of two main sections: entity metadata and attribute d
       "type": "array",
       "items": {
         "type": "string",
-        "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+        "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
       },
       "required": false,
       "role": "emailAliases"
@@ -197,7 +197,7 @@ Simple text values.
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
     "required": false,
     "role": "primaryEmail"
   },
@@ -237,7 +237,7 @@ Multi-valued attributes containing multiple items of the same type.
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
     },
     "required": false,
     "role": "emailAliases"
@@ -338,19 +338,20 @@ Complete reference for all attribute properties.
 
 ### Attribute Properties Table
 
-| Property   | Type            | Applies To          | Description                                                                           | Example                             |
-| ---------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
-| `type`     | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
-| `required` | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
-| `fixed`    | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
-| `role`     | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
-| `test`     | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
-| `branch`   | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
-| `ui`       | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
-| `hint`     | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
-| `group`    | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
-| `default`  | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
-| `items`    | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
+| Property    | Type            | Applies To          | Description                                                                           | Example                             |
+| ----------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
+| `type`      | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
+| `required`  | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
+| `fixed`     | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
+| `role`      | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
+| `test`      | string/regex    | String, Array items | Regular expression for validation                                                     | `"^[a-zA-Z0-9._-]{1,255}$"`         |
+| `maxLength` | number          | String, Array items | Longest value accepted, in characters; a longer one is refused before `test` (4096)   | `255`                               |
+| `branch`    | string[]        | Pointer             | LDAP branches where referenced entries exist                                          | `["ou=users,dc=example,dc=com"]`    |
+| `ui`        | object          | Pointer             | UI configuration for pointer selection (future feature)                               | `{}`                                |
+| `hint`      | text            | String, Array items | What a valid value looks like, shown under the field and quoted in refusals           | `"Expected pattern 999 9999"`       |
+| `group`     | text            | All                 | Form section the attribute is shown in                                                | `"Mailbox Settings"`                |
+| `default`   | any             | All                 | Default value for new entries                                                         | `["top", "person"]`                 |
+| `items`     | object          | Array               | Schema for array element validation                                                   | `{"type": "string", "test": "..."}` |
 
 A _text_ is a plain string or a map keyed by language tag,
 `{ "en": "Mailbox Settings", "fr": "Paramètres de messagerie" }`, picked as
@@ -378,16 +379,40 @@ answers, one value where the attribute holds one, can be sent back as is;
 two values or more for a single-valued attribute are refused. Each element
 of an `array` follows `items.type`, text without `items`. A `number` or
 `integer` is a JSON number or its text (`42`, `"42"`), a `boolean` a JSON
-boolean or the directory's `TRUE` / `FALSE`; anything else for them, and
+boolean or the directory's `TRUE` / `FALSE`. A JSON number is judged on the
+text written for it, what the directory is sent: `1e21` and `1e-7` are
+written `1e+21` and `1e-7`, so they are refused like that text, and a whole
+number beyond 2⁵³ is refused whatever the type, as the JSON parser has
+already lost its digits. Anything else for them, and
 anything but text for a `string`, `date` or `pointer`, is refused; an
 attribute with `normalize` takes any text, read after validation. In a
 `replace`, `null` or `[]` clears an attribute; in an `add` or on a creation
-they are refused as no value. A `delete` naming the attribute, or naming it
-with no value, removes it, unless it is `required`; naming values removes
-those, every value it holds included, as the server does not read what
-remains, and `''` names no value. An empty string sent as a value is
-checked against `test`, refused for a pointer, and missing for a `required`
-attribute. Every refusal answers 400 with the attribute's name.
+they are refused as no value when the schema declares the attribute. A
+`null` under a name the schema does not declare — and, for an entity without
+a schema, under any name — is dropped from a creation and from an `add`, as
+if the key were left out, and clears the attribute in a `replace`. A
+`delete` naming the attribute, or naming it with no value, removes it,
+unless it is `required`; naming values removes those, every value it holds
+included, as the server does not read what remains, and `''` names no
+value. An empty string sent as a value is checked against `test`, refused
+for a pointer, and missing for a `required` attribute. Every refusal answers
+400 with the attribute's name.
+
+#### What an attribute may be called
+
+A name is read as the directory reads it: case and the `;binary` option do
+not change the attribute it names, so `Cn`, `CN` and `cn;binary` all name
+`cn`. Each key the schema declares is written under the schema's spelling —
+`Cn` becomes `cn`, `L;binary` becomes `l;binary` — before any check, so that
+a `required` attribute counts as present wherever it was sent, and a `fixed`
+one is written once, at its default. The attribute's type is read the same
+way when a value is converted, so a boolean sent as `pwdReset;binary` is
+written `TRUE`.
+
+Two keys of an entry or of one part of a change naming one attribute are
+refused; the option does not make them two, so `l` and `l;binary` are
+refused together. A name the schema does not declare is left as sent, and a
+strict schema refuses it.
 
 Every entity route applies these rules; `test/lib/entitySchema.contract.test.ts`
 asserts them on a flat entity, a group and an organization alike. In the
@@ -451,7 +476,10 @@ Assigns semantic meaning to attributes for special handling by the application.
 
 #### `test` (Optional)
 
-Regular expression pattern for validating attribute values.
+Regular expression pattern for validating attribute values. The value is
+judged only up to its attribute's length: see
+[`maxLength`](#maxlength-optional) below, which a deployment writing its own
+pattern should read.
 
 ```json
 {
@@ -461,7 +489,7 @@ Regular expression pattern for validating attribute values.
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
   }
 }
 ```
@@ -474,7 +502,38 @@ Regular expression pattern for validating attribute values.
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
+    }
+  }
+}
+```
+
+#### `maxLength` (Optional)
+
+Longest value, in UTF-16 code units (what `.length` counts, so an emoji or an
+accented letter outside the basic plane counts as two), accepted before `test`
+runs on it. A value past
+it is refused with 400, and the pattern never reads it — whether or not it
+would have matched. On an array, `maxLength` on the attribute governs every
+item; one declared under `items` is read only when the attribute declares
+none. It is a positive whole number of characters: the server refuses to load
+a schema where it is not.
+
+A pattern is written for values of its attribute, not for a payload of any
+size: handed several kilobytes, a pattern whose parts overlap walks the value
+in quadratic time, on the event loop that answers every other request
+meanwhile. The limit keeps the pattern within what it was written for. It is
+**4096** unless the schema says otherwise; an attribute holding longer values
+— a description, a public key — declares its own.
+
+```json
+{
+  "sshPublicKey": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "maxLength": 16384,
+      "test": "^[^\\r\\n]*$"
     }
   }
 }
@@ -594,7 +653,7 @@ Email-related roles help applications handle email addresses consistently across
 {
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
     "required": false,
     "role": "primaryEmail"
   }
@@ -609,7 +668,7 @@ Email-related roles help applications handle email addresses consistently across
     "type": "array",
     "items": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
     },
     "required": false,
     "role": "emailAliases"
@@ -686,9 +745,14 @@ Common validation patterns:
 **Email:**
 
 ```regex
-^[^@\s]+@[^@\s]+\.[^@\s]+$
+^[^@\s]+@[^@\s.]+(\.[^@\s.]+)+$
 ```
 
+The domain part holds no dot of its own: where it did, the pattern tried every
+dot as the last separator and read the value again each time — seconds for a
+value of a few kilobytes. The result is that a trailing dot (`a@b.c.`) is
+refused, where the older form accepted it.
+
 **DN (Distinguished Name):**
 
 ```regex
@@ -1045,7 +1109,7 @@ Start with the schema that most closely matches your directory type:
   "attributes": {
     "mail": {
       "type": "string",
-      "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+      "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$",
       "required": false,
       "role": "primaryEmail"
     },
@@ -1238,7 +1302,7 @@ Use `test` patterns to enforce data quality:
   },
   "mail": {
     "type": "string",
-    "test": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
+    "test": "^[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+$"
   }
 }
 ```