ldap-rest 1.2.1 → 2.0.0

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

@@ -39,7 +39,11 @@ export declare function dnKey(dn: string): string;
 export declare function parentOf(dn: string): string;
 /**
  * The entries one level under a DN pattern holding `{org}`, the organization
- * captured as one RDN value: `(?:\\.|[^,])+` keeps an escaped comma inside it.
+ * captured as one RDN value: an escaped comma stays inside it.
+ *
+ * A backslash and the character it escapes are read as one, and a comma ends
+ * the value, so each character of the value is followed one way whatever
+ * the DN holds.
  */
 export declare function branchPattern(base: string): RegExp;
 /**
@@ -49,7 +53,31 @@ export declare function branchPattern(base: string): RegExp;
 export declare function movedInto(pattern: RegExp, dn: string, newDn: string): string | undefined;
 /** The organization of an entry one level under a branch pattern. */
 export declare function organizationIn(pattern: RegExp, dn: string): string | undefined;
+export declare const TwakeOrganizationParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+}>;
+export declare const OrganizationGroupParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    groupId: import("@sinclair/typebox").TString;
+}>;
+export declare const OrganizationGroupMemberParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    groupId: import("@sinclair/typebox").TString;
+    userId: import("@sinclair/typebox").TString;
+}>;
 export default class TwakeGroups extends LdapGroups {
+    static optionDefinitions: {
+        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<{}>;
+    };
     name: string;
     protected readonly groupBase: string;
     protected readonly userBase: string;

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';
@@ -22,13 +12,58 @@ export interface WorkplaceCreated {
 /** An account's instance request, and the id `user.created` names it by. */
 interface Account extends InstanceRequest {
     twakeId: string;
+    /** The organization id came from the DN, not from the provider settings */
+    fromDn?: boolean;
 }
+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;
@@ -95,12 +130,41 @@ export default class TwakeInstances extends DmPlugin {
     private get organizationFqdn();
     private organizationMail;
     private isOrganization;
+    /**
+     * The id the organization's own entry spells, for an id captured from a
+     * client's DN: the caller may write the branch in another case, and the
+     * Cloudery branch and the slug should not follow it. The captured value
+     * stands when there is no entry or no organization base.
+     */
+    private storedOrganizationId;
+    /** `account()`, with a captured organization id read from its entry. */
+    private storedAccount;
     private findOrganization;
     private read;
     protected announce(exchange: string, key: string, message: Record<string, unknown>): Promise<void>;
     /** What to ask for this account, when it gets an instance at all. */
     protected account(dn: string, entry: AttributesList): Account | undefined;
+    /**
+     * The expression that takes this DN for an account's, and where it sits.
+     *
+     * Each expression reads the canonical DN first: a client may spell the
+     * branch differently, and a space or an escape inside a captured value
+     * would otherwise be captured as written. The canonical form keeps the
+     * caller's case, which an organization id is sent as. An expression written
+     * with the directory's own spelling — `\2C`, a doubled space — does not
+     * match that form, so the DN as sent is tried next.
+     */
     private match;
+    /**
+     * The DN with a comma inside a value written `\2C`, as the directory writes
+     * it: an expression's `[^,]` cannot then read that comma as an RDN
+     * separator and name the branch of an entry beside it.
+     */
+    private separators;
+    /** The uid of an account's DN, under any name or alias of the type. */
+    private uid;
+    /** One queue per entry, whatever spelling its DN came in. */
+    private key;
     private id;
     protected value(entry: AttributesList, attribute: string): unknown;
     protected findByMail(email: string, req?: Request): Promise<AttributesList | undefined>;

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/lifecycleAttributes.d.ts

@@ -25,5 +25,16 @@ export declare function first(value: AttributeValue | null | undefined): string
 export declare const isTombstone: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
 export declare const isLocked: (entry: AttributesList, attrs: LifecycleAttributes) => boolean;
 export declare function formatDeletedAt(date: Date, format: DeletedAtFormat): string;
-/** A deletion date as the directory holds it, or undefined if unreadable. */
-export declare function parseDeletedAt(value: string, format: DeletedAtFormat): Date | undefined;
+/**
+ * A deletion date as the directory holds it, or undefined if unreadable.
+ *
+ * Read by the same reader as every other directory time: the format only says
+ * how this deployment writes the date, not how it is read.
+ *
+ * A value of another shape is refused here rather than handed to that
+ * reader, whose fallback to `new Date()` reads `1` or `Jan 1` as a date: the
+ * erase guard takes an unreadable date for a refusal. The same fallback rolls
+ * `2025-02-31` over to March, where the shared reader refuses that day
+ * spelled as a GeneralizedTime.
+ */
+export declare function parseDeletedAt(value: string): Date | undefined;

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;
@@ -46,8 +48,8 @@ export default class TwakeTombstone extends DmPlugin {
      */
     tombstone(dn: string, reason: string, req?: Request): Promise<void>;
     /**
-     * Remove a tombstone and its group memberships. Refused while the deletion
-     * is younger than the configured age, unless forced.
+     * Remove a tombstone and its group memberships. Refused when its deletion
+     * date is unreadable or younger than the configured age, unless forced.
      */
     erase(dn: string, { force, req }?: {
         force?: boolean;
@@ -75,6 +77,13 @@ export default class TwakeTombstone extends DmPlugin {
      * group the erase left holding only the placeholder loses it again.
      */
     private restore;
+    /**
+     * Whether this DN names an entry the expressions keep. A client may spell
+     * the DN differently from the expression; the directory stores the entry
+     * at its canonical DN, so the expressions read that too. The DN as sent is
+     * still tried: an expression written with the directory's own spelling
+     * (`\2C`, a doubled space) matches only that form.
+     */
     private matches;
     private isScim;
     private checkReason;

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,8 @@ 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
+- **[Services](plugin-development/services.md)** - Typed interfaces between plugins
+- **[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
 
@@ -32,6 +34,13 @@ Integrate LDAP-Rest into your web applications.
 - **[JSON Schemas](client-development/schemas/README.md)** - Schema structure and validation
 - **[Examples](client-development/examples/README.md)** - React, Vue.js, Vanilla JS integration
 
+### [Development](development/contracts.md)
+
+Work on ldap-rest itself.
+
+- **[Published contracts](development/contracts.md)** - What breaks a
+  contract, the snapshots that detect it and the deprecation window.
+
 ## API stability
 
 From 1.0.0, ldap-rest follows semantic versioning. These are its public
@@ -43,8 +52,9 @@ API, which a minor or a patch release does not break:
   [REST API](client-development/api/rest-api.md) and the plugin pages,
   their statuses and their error `code`s.
 - **Plugin API**: what `ldap-rest/plugin` exports — `DmPlugin` and its
-  roles (`auth`, `authz`, …), `asyncHandler`, the DN and filter escaping
-  helpers and the error classes —, the `DM` type of `ldap-rest` and the
+  roles (`auth`, `authz`, …), `serviceToken`, `ServiceToken` and
+  `ServiceProvider`, `asyncHandler`, the DN and filter escaping helpers and
+  the error classes —, the `DM` type of `ldap-rest` and the
   `Hooks` of `ldap-rest/hooks`, whose arguments are those typed in
   `src/hooks.ts` ([hooks](plugin-development/hooks.md)), and the directory
   operations of [the development guide](plugin-development/README.md):
@@ -57,6 +67,11 @@ API, which a minor or a patch release does not break:
 Everything else — other exports, internal helpers, log messages — may
 change in any release.
 
+The options and the REST API are checked mechanically: committed snapshots
+are compared with the base branch of each pull request, and a non-additive
+change needs the `breaking` label. The plugin types are still reviewed by
+hand. See [Published contracts](development/contracts.md).
+
 ## Presentations
 
 Interactive presentations (using [presenterm](https://github.com/mfontanini/presenterm)):

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
 {
@@ -1359,6 +1365,10 @@ const encoded = encodeURIComponent(dn);
 // Result: uid%3Djohn.doe%2Cou%3Dusers%2Cdc%3Dexample%2Cdc%3Dcom
 ```
 
+A path parameter is percent-decoded once, as RFC 3986 spells it: an
+identifier holding `%` is sent as `%25`, so `100%` is addressed as
+`/api/v1/ldap/users/100%25`.
+
 ### LDAP Attributes are Arrays
 
 LDAP attributes are always returned as arrays, even for single-valued attributes: