ldap-rest 1.2.0 → 1.3.0

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

@@ -1,13 +1,3 @@
-/**
- * @module plugins/twake/instances
- *
- * Gives every account this server creates its workplace instance, once its
- * entry is written, from the Cloudery or from the cozy-stack admin API. The
- * address is written once the instance exists, then `user.created` is
- * published and the entry marked. The event is sent at least once.
- *
- * See `docs/usage/plugins/integrations/instances.md`.
- */
 import type { Express, Request } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
@@ -23,12 +13,55 @@ export interface WorkplaceCreated {
 interface Account extends InstanceRequest {
     twakeId: string;
 }
+export declare const EnsureInstanceBody: import("@sinclair/typebox").TObject<{
+    dn: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    mail: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare const EnsureInstanceResponse: import("@sinclair/typebox").TObject<{
+    state: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"ready">, import("@sinclair/typebox").TLiteral<"pending">]>;
+}>;
 export default class TwakeInstances extends DmPlugin {
+    static optionDefinitions: {
+        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;
+    };
     name: string;
     roles: Role[];
     dependencies: {
         rabbitmq: string;
     };
+    private readonly settings;
     protected readonly patterns: RegExp[];
     protected readonly provider: InstanceProvider;
     protected readonly fqdnAttribute: string;

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
 {