ldap-rest 0.3.0 → 0.3.2

package/dist/src/plugins/scim/scim.d.ts

@@ -3,6 +3,395 @@ import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type ldapActions from '../../lib/ldapActions';
 import { writeScimErrorFromException } from './errors';
+/**
+ * Reusable SCIM 2.0 schemas surfaced by this plugin.
+ * Picked up by scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * ScimUser:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 User resource (RFC 7643 §4.1).
+ *   required: [schemas, userName]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:User']
+ *     id:
+ *       type: string
+ *       description: Opaque server-assigned identifier.
+ *       example: 2819c223-7f76-453a-919d-413861904646
+ *     externalId:
+ *       type: string
+ *       description: Provisioner-assigned identifier.
+ *       example: 701984
+ *     userName:
+ *       type: string
+ *       description: Unique user identifier (login name).
+ *       example: bjensen
+ *     name:
+ *       type: object
+ *       properties:
+ *         formatted: { type: string, example: Ms. Barbara J Jensen III }
+ *         familyName: { type: string, example: Jensen }
+ *         givenName: { type: string, example: Barbara }
+ *         middleName: { type: string, example: Jane }
+ *         honorificPrefix: { type: string, example: Ms. }
+ *         honorificSuffix: { type: string, example: III }
+ *     displayName:
+ *       type: string
+ *       example: Babs Jensen
+ *     nickName:
+ *       type: string
+ *       example: Babs
+ *     profileUrl:
+ *       type: string
+ *       example: https://login.example.com/bjensen
+ *     title:
+ *       type: string
+ *       example: Tour Guide
+ *     userType:
+ *       type: string
+ *       example: Employee
+ *     preferredLanguage:
+ *       type: string
+ *       example: en-US
+ *     locale:
+ *       type: string
+ *       example: en-US
+ *     timezone:
+ *       type: string
+ *       example: America/Los_Angeles
+ *     active:
+ *       type: boolean
+ *       example: true
+ *     emails:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string }
+ *           display: { type: string }
+ *           type: { type: string }
+ *           primary: { type: boolean }
+ *       example:
+ *         - value: bjensen@example.com
+ *           type: work
+ *           primary: true
+ *     phoneNumbers:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string }
+ *           type: { type: string }
+ *           primary: { type: boolean }
+ *     addresses:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           streetAddress: { type: string }
+ *           locality: { type: string }
+ *           region: { type: string }
+ *           postalCode: { type: string }
+ *           country: { type: string }
+ *           type: { type: string }
+ *           primary: { type: boolean }
+ *     groups:
+ *       type: array
+ *       description: Groups the user belongs to (read-only).
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string }
+ *           $ref: { type: string }
+ *           display: { type: string }
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: User }
+ *         created: { type: string, format: date-time }
+ *         lastModified: { type: string, format: date-time }
+ *         location: { type: string }
+ *         version: { type: string }
+ * ScimGroup:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 Group resource (RFC 7643 §4.2).
+ *   required: [schemas, displayName]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:Group']
+ *     id:
+ *       type: string
+ *       description: Opaque server-assigned identifier.
+ *       example: e9e30dba-f08f-4109-8486-d5c6a331660a
+ *     externalId:
+ *       type: string
+ *       example: 00g1emaKYZTWRINFRGETl
+ *     displayName:
+ *       type: string
+ *       example: Tour Guides
+ *     members:
+ *       type: array
+ *       description: Members of the group.
+ *       items:
+ *         type: object
+ *         properties:
+ *           value: { type: string, description: User or Group id }
+ *           $ref: { type: string }
+ *           display: { type: string }
+ *       example:
+ *         - value: 2819c223-7f76-453a-919d-413861904646
+ *           display: Babs Jensen
+ *         - value: 902c246b-6245-4190-8e05-00816be7344a
+ *           display: Mandy Pepperidge
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: Group }
+ *         created: { type: string, format: date-time }
+ *         lastModified: { type: string, format: date-time }
+ *         location: { type: string }
+ *         version: { type: string }
+ * ScimListResponse:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 list query response (urn:ietf:params:scim:api:messages:2.0:ListResponse).
+ *   required: [schemas, totalResults, Resources]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:ListResponse']
+ *     totalResults:
+ *       type: integer
+ *       description: Total number of matching resources.
+ *       example: 2
+ *     startIndex:
+ *       type: integer
+ *       description: 1-based index of the first result returned.
+ *       example: 1
+ *     itemsPerPage:
+ *       type: integer
+ *       description: Number of resources returned in this page.
+ *       example: 2
+ *     Resources:
+ *       type: array
+ *       items: {}
+ *       description: The matching resources.
+ * ScimError:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 error response (urn:ietf:params:scim:api:messages:2.0:Error).
+ *   required: [schemas, status]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:Error']
+ *     status:
+ *       type: string
+ *       description: HTTP status code as a string.
+ *       example: '404'
+ *     scimType:
+ *       type: string
+ *       description: |
+ *         SCIM error type keyword (RFC 7644 §3.12). One of: invalidFilter,
+ *         tooMany, uniqueness, mutability, invalidSyntax, invalidPath,
+ *         noTarget, invalidValue, invalidVers, sensitive.
+ *       example: mutability
+ *     detail:
+ *       type: string
+ *       description: Human-readable error description.
+ *       example: Resource 2819c223-7f76-453a-919d-413861904646 not found.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:Error']
+ *     status: '404'
+ *     detail: Resource 2819c223-7f76-453a-919d-413861904646 not found.
+ * ScimPatchOp:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 patch request body (urn:ietf:params:scim:api:messages:2.0:PatchOp,
+ *     RFC 7644 §3.5.2).
+ *   required: [schemas, Operations]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:PatchOp']
+ *     Operations:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [op]
+ *         properties:
+ *           op:
+ *             type: string
+ *             enum: [add, remove, replace, Add, Remove, Replace]
+ *           path:
+ *             type: string
+ *             description: SCIM attribute path (e.g. "emails[type eq \"work\"].value").
+ *           value:
+ *             description: New value for the target attribute.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:PatchOp']
+ *     Operations:
+ *       - op: replace
+ *         path: active
+ *         value: false
+ *       - op: replace
+ *         path: emails[type eq "work"].value
+ *         value: bjensen@newdomain.example.com
+ * ScimBulkRequest:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 Bulk request (urn:ietf:params:scim:api:messages:2.0:BulkRequest,
+ *     RFC 7644 §3.7).
+ *   required: [schemas, Operations]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:BulkRequest']
+ *     failOnErrors:
+ *       type: integer
+ *       description: |
+ *         Stop processing after this many errors. Omit or set to 0 to
+ *         continue on errors and process all operations.
+ *       example: 1
+ *     Operations:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [method, path]
+ *         properties:
+ *           method:
+ *             type: string
+ *             enum: [POST, PUT, PATCH, DELETE]
+ *           bulkId:
+ *             type: string
+ *             description: |
+ *               Temporary client-assigned identifier for this operation.
+ *               Subsequent operations in the same request may reference the
+ *               created resource as "bulkId:<value>".
+ *           path:
+ *             type: string
+ *             description: Resource path relative to the SCIM prefix (e.g. /Users or /Groups/123).
+ *           data:
+ *             description: Request body for POST/PUT/PATCH operations.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:BulkRequest']
+ *     failOnErrors: 1
+ *     Operations:
+ *       - method: POST
+ *         bulkId: qwerty
+ *         path: /Users
+ *         data:
+ *           schemas: ['urn:ietf:params:scim:schemas:core:2.0:User']
+ *           userName: bjensen
+ *           name:
+ *             familyName: Jensen
+ *             givenName: Barbara
+ *       - method: DELETE
+ *         path: /Users/2819c223-7f76-453a-919d-413861904646
+ * ScimBulkResponse:
+ *   type: object
+ *   description: |
+ *     SCIM 2.0 Bulk response (urn:ietf:params:scim:api:messages:2.0:BulkResponse).
+ *   required: [schemas, Operations]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:api:messages:2.0:BulkResponse']
+ *     Operations:
+ *       type: array
+ *       items:
+ *         type: object
+ *         required: [method, status]
+ *         properties:
+ *           method:
+ *             type: string
+ *             enum: [POST, PUT, PATCH, DELETE]
+ *           bulkId:
+ *             type: string
+ *           location:
+ *             type: string
+ *             description: URL of the created/modified resource.
+ *           version:
+ *             type: string
+ *           status:
+ *             type: string
+ *             description: HTTP status code for this individual operation.
+ *           response:
+ *             $ref: '#/components/schemas/ScimError'
+ *             description: Present only when the operation failed.
+ *   example:
+ *     schemas: ['urn:ietf:params:scim:api:messages:2.0:BulkResponse']
+ *     Operations:
+ *       - method: POST
+ *         bulkId: qwerty
+ *         location: https://example.com/scim/v2/Users/2819c223-7f76-453a-919d-413861904646
+ *         status: '201'
+ *       - method: DELETE
+ *         status: '204'
+ * ScimResourceType:
+ *   type: object
+ *   description: SCIM 2.0 ResourceType definition (RFC 7643 §6).
+ *   required: [schemas, id, name, endpoint, schema]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:ResourceType']
+ *     id: { type: string, example: User }
+ *     name: { type: string, example: User }
+ *     endpoint: { type: string, example: /Users }
+ *     description: { type: string, example: User Account }
+ *     schema:
+ *       type: string
+ *       example: urn:ietf:params:scim:schemas:core:2.0:User
+ *     schemaExtensions:
+ *       type: array
+ *       items:
+ *         type: object
+ *         properties:
+ *           schema: { type: string }
+ *           required: { type: boolean }
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: ResourceType }
+ *         location: { type: string }
+ * ScimSchema:
+ *   type: object
+ *   description: SCIM 2.0 Schema definition (RFC 7643 §7).
+ *   required: [schemas, id, name, attributes]
+ *   properties:
+ *     schemas:
+ *       type: array
+ *       items: { type: string }
+ *       example: ['urn:ietf:params:scim:schemas:core:2.0:Schema']
+ *     id:
+ *       type: string
+ *       example: urn:ietf:params:scim:schemas:core:2.0:User
+ *     name: { type: string, example: User }
+ *     description: { type: string, example: User Account }
+ *     attributes:
+ *       type: array
+ *       items: {}
+ *       description: Schema attribute definitions.
+ *     meta:
+ *       type: object
+ *       properties:
+ *         resourceType: { type: string, example: Schema }
+ *         location: { type: string }
+ */
 export default class Scim extends DmPlugin {
     name: string;
     roles: Role[];

package/dist/src/plugins/static.d.ts

@@ -1,5 +1,38 @@
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../abstract/plugin';
+/**
+ * @openapi-component
+ * LdapSchema:
+ *   type: object
+ *   description: |
+ *     A JSON schema file served from the `schemas/` sub-directory of the
+ *     static path.  These schemas describe LDAP entity types (users, groups,
+ *     organizations, …) and are consumed by browser-embedded editors to
+ *     render attribute forms and validate input before submission.
+ *
+ *     The server replaces `__FOO_BAR__` placeholders on the fly with the
+ *     value of the corresponding `--foo-bar` CLI option so that a single
+ *     schema file can be shared between server-side validation and
+ *     client-side rendering.
+ *   additionalProperties: true
+ *   example:
+ *     entity:
+ *       name: standardUser
+ *       mainAttribute: uid
+ *       objectClass: [top, inetOrgPerson]
+ *       singularName: user
+ *       pluralName: users
+ *       base: ou=users,dc=example,dc=com
+ *     strict: true
+ *     attributes:
+ *       uid:
+ *         type: string
+ *         required: true
+ *         role: identifier
+ *       cn:
+ *         type: string
+ *         required: true
+ */
 export default class Static extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -1,6 +1,69 @@
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
+/**
+ * @openapi-component
+ * AppAccount:
+ *   type: object
+ *   description: |
+ *     An application-specific identity attached to a user.  App accounts
+ *     allow a single principal user to authenticate as different named
+ *     "devices" or "applications" each with its own credential, while
+ *     sharing the same mail address.
+ *   required: [uid]
+ *   properties:
+ *     uid:
+ *       type: string
+ *       description: |
+ *         Unique identifier of the app account.  Format:
+ *         `<username>_c<8-digits>` (e.g. `alice_c04729183`).
+ *       example: alice_c04729183
+ *     name:
+ *       type: string
+ *       description: Human-readable label (stored as LDAP `description`).
+ *       example: Work laptop
+ *   example:
+ *     uid: alice_c04729183
+ *     name: Work laptop
+ * AppAccountCreated:
+ *   type: object
+ *   description: |
+ *     Response returned when a new app account is successfully created.
+ *     The one-time cleartext password is included here and never returned
+ *     again — callers must store it immediately.
+ *   required: [uid, pwd, mail]
+ *   properties:
+ *     uid:
+ *       type: string
+ *       description: Identifier of the newly created app account.
+ *       example: alice_c04729183
+ *     pwd:
+ *       type: string
+ *       description: |
+ *         One-time cleartext password generated for this account.
+ *         Format: 6 blocks of 4 characters separated by `-`
+ *         (e.g. `Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@`).
+ *         OpenLDAP hashes it via ppolicy before storage.
+ *       example: Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@
+ *     mail:
+ *       type: string
+ *       description: Mail address of the principal account this app account belongs to.
+ *       example: alice@example.com
+ *   example:
+ *     uid: alice_c04729183
+ *     pwd: Ab3@-xYz!-9pQ#-Sv4$-mN8!-pQ5@
+ *     mail: alice@example.com
+ * AppAccountCreate:
+ *   type: object
+ *   description: Request body for creating a new app account.
+ *   properties:
+ *     name:
+ *       type: string
+ *       description: Optional human-readable label for the new account.
+ *       example: Work laptop
+ *   example:
+ *     name: Work laptop
+ */
 export default class AppAccountsApi extends DmPlugin {
     name: string;
     roles: Role[];

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

@@ -0,0 +1,54 @@
+import DmPlugin, { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import { Hooks } from '../../hooks';
+interface RabbitPublisher {
+    init(): Promise<void>;
+    publish(exchange: string, routingKey: string, message: Record<string, unknown>): Promise<void>;
+    close(clearSubscriptions?: boolean): Promise<void>;
+}
+export default class CozyProvision extends DmPlugin {
+    name: string;
+    roles: Role[];
+    private readonly cozyAdminUrl;
+    private readonly cozyAdminPassphrase;
+    private readonly cozyAdminUser;
+    private readonly cozyOrgId;
+    private readonly cozyOrgDomain;
+    private readonly cozyDefaultLocale;
+    private readonly rabbitmqUrl;
+    private readonly authExchange;
+    private readonly b2bExchange;
+    private publisher;
+    private publisherInit;
+    constructor(server: DM);
+    hooks: Hooks;
+    /**
+     * POST /instances on the cozy-stack admin API. Returns true on success
+     * (including 409 idempotent "already exists").
+     */
+    private createCozyInstance;
+    /**
+     * Publish user.created on the `auth` topic exchange. Payload mirrors what
+     * cozy-stack expects: a sub identifier, an optional email, and the
+     * organizationDomain so consumers can match the instance.
+     */
+    private publishUserCreated;
+    /**
+     * Publish domain.user.deleted on the `b2b` topic exchange so peer cozy
+     * instances can drop the deleted user's contact card.
+     */
+    private publishUserDeleted;
+    /**
+     * Lazy-init the AMQP publisher. The `@linagora/rabbitmq-client` dependency
+     * is optional — if the package or the broker is unreachable, return null
+     * so callers can no-op cleanly.
+     *
+     * Override this in tests to inject a stub publisher.
+     */
+    protected getPublisher(): Promise<RabbitPublisher | null>;
+    private extractId;
+    private extractPrimaryEmail;
+    private extractLocale;
+    private registerShutdown;
+}
+export {};

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

@@ -5,6 +5,53 @@ import type { DM } from '../../bin';
 import type { AttributeValue } from '../../lib/ldapActions';
 import { Hooks } from '../../hooks';
 import type { ChangesToNotify } from '../ldap/onChange';
+/**
+ * OpenAPI schemas specific to the James integration.
+ *
+ * @openapi-component
+ * JamesQuotaUsage:
+ *   type: object
+ *   description: |
+ *     Quota information for a mailbox user as returned by the James
+ *     WebAdmin API (`GET /quota/users/{mail}`). Contains separate
+ *     counters for message count and storage size.
+ *   properties:
+ *     count:
+ *       type: object
+ *       description: Message-count quota.
+ *       properties:
+ *         used:
+ *           type: integer
+ *           description: Number of messages currently stored.
+ *           example: 142
+ *         max:
+ *           type: integer
+ *           nullable: true
+ *           description: |
+ *             Maximum number of messages allowed. `null` means unlimited.
+ *           example: 10000
+ *     size:
+ *       type: object
+ *       description: Storage-size quota (bytes).
+ *       properties:
+ *         used:
+ *           type: integer
+ *           description: Bytes currently used.
+ *           example: 524288000
+ *         max:
+ *           type: integer
+ *           nullable: true
+ *           description: |
+ *             Maximum bytes allowed. `null` means unlimited.
+ *           example: 2147483648
+ *   example:
+ *     count:
+ *       used: 142
+ *       max: 10000
+ *     size:
+ *       used: 524288000
+ *       max: 2147483648
+ */
 export default class James extends TwakePlugin {
     name: string;
     roles: Role[];

package/docs/plugin-development/README.md

@@ -13,6 +13,7 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Configuration Best Practices](#configuration-best-practices)
 - [Complete Plugin Example](#complete-plugin-example)
 - [Testing Your Plugin](#testing-your-plugin)
+- [Documenting REST endpoints (OpenAPI)](./openapi.md)
 
 ---
 
@@ -1282,7 +1283,7 @@ source ~/.test-env && npm run test:dev
 ## Additional Resources
 
 - [Contributing Guide](../../CONTRIBUTING.md) - Git workflow and PR guidelines
-- [Hooks Reference](../../HOOKS.md) - Complete list of available hooks
+- [Hooks Reference](./hooks.md) - Complete list of available hooks
 - [Core Plugin Examples](../../src/plugins/) - Browse existing plugins
 - [Test Examples](../../test/plugins/) - See how core plugins are tested