ldap-rest 0.3.0 → 0.3.1

package/dist/src/plugins/ldap/passwordPolicy.d.ts

@@ -11,6 +11,184 @@
  */
 import type { Express } from 'express';
 import DmPlugin, { type Role } from '../../abstract/plugin';
+/**
+ * Shared OpenAPI schemas surfaced by this plugin. Picked up by
+ * scripts/generate-openapi.ts and merged into `components.schemas`.
+ *
+ * @openapi-component
+ * PasswordPolicy:
+ *   type: object
+ *   description: |
+ *     Active OpenLDAP ppolicy configuration. All duration fields are in
+ *     **seconds**. Absent fields mean the policy attribute is not set.
+ *   properties:
+ *     dn:
+ *       type: string
+ *       description: DN of the ppolicy entry.
+ *       example: cn=default,ou=policies,dc=example,dc=com
+ *     pwdMaxAge:
+ *       type: integer
+ *       description: Maximum password age in seconds (0 = never expires).
+ *       example: 7776000
+ *     pwdMinAge:
+ *       type: integer
+ *       description: Minimum password age in seconds before it may be changed.
+ *       example: 0
+ *     pwdInHistory:
+ *       type: integer
+ *       description: Number of previous passwords stored.
+ *       example: 5
+ *     pwdCheckQuality:
+ *       type: integer
+ *       description: Password quality enforcement level (0-2).
+ *       example: 1
+ *     pwdMinLength:
+ *       type: integer
+ *       description: Minimum password length.
+ *       example: 12
+ *     pwdMaxFailure:
+ *       type: integer
+ *       description: Maximum bind failures before lockout.
+ *       example: 5
+ *     pwdLockout:
+ *       type: boolean
+ *       description: Whether account lockout is enabled.
+ *       example: true
+ *     pwdLockoutDuration:
+ *       type: integer
+ *       description: Lockout duration in seconds (0 = permanent until admin reset).
+ *       example: 300
+ *     pwdGraceAuthNLimit:
+ *       type: integer
+ *       description: Number of grace logins allowed after password expires.
+ *       example: 0
+ *     pwdExpireWarning:
+ *       type: integer
+ *       description: Seconds before expiry at which a warning is issued.
+ *       example: 1209600
+ *     pwdMustChange:
+ *       type: boolean
+ *       description: If true, users must change their password after an admin reset.
+ *       example: true
+ *     pwdAllowUserChange:
+ *       type: boolean
+ *       description: Whether users are allowed to change their own password.
+ *       example: true
+ * PasswordStatus:
+ *   type: object
+ *   description: Current password status for a specific user account.
+ *   required: [dn, passwordSet, isExpired, isExpiringSoon, mustChange, isLocked, failureCount, graceLoginsUsed]
+ *   properties:
+ *     dn:
+ *       type: string
+ *       description: Fully-qualified DN of the user.
+ *       example: uid=alice,ou=users,dc=example,dc=com
+ *     passwordSet:
+ *       type: boolean
+ *       description: Whether a userPassword attribute is present.
+ *       example: true
+ *     lastChanged:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       description: ISO-8601 timestamp of last password change, or null if never set.
+ *       example: '2026-01-15T10:00:00.000Z'
+ *     expiresAt:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       description: ISO-8601 expiry timestamp, or null if no max age is configured.
+ *       example: '2026-04-15T10:00:00.000Z'
+ *     daysUntilExpiration:
+ *       type: integer
+ *       nullable: true
+ *       description: Remaining days until expiry (negative means already expired).
+ *       example: 80
+ *     isExpired:
+ *       type: boolean
+ *       example: false
+ *     isExpiringSoon:
+ *       type: boolean
+ *       description: True when expiry is within the configured warning window.
+ *       example: false
+ *     mustChange:
+ *       type: boolean
+ *       description: True when `pwdReset` is set (admin forced change).
+ *       example: false
+ *     isLocked:
+ *       type: boolean
+ *       description: True when the account is currently locked.
+ *       example: false
+ *     lockedAt:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       description: ISO-8601 timestamp of lockout, or null.
+ *       example: null
+ *     failureCount:
+ *       type: integer
+ *       description: Number of recorded bind failures still within the window.
+ *       example: 0
+ *     graceLoginsUsed:
+ *       type: integer
+ *       description: Number of grace logins already consumed.
+ *       example: 0
+ * ExpiringAccount:
+ *   type: object
+ *   description: User whose password is expiring within the warning window.
+ *   required: [dn, expiresAt, daysUntilExpiration]
+ *   properties:
+ *     dn: { type: string, example: uid=bob,ou=users,dc=example,dc=com }
+ *     uid: { type: string, example: bob }
+ *     displayName: { type: string, example: Bob Builder }
+ *     mail: { type: string, example: bob@example.com }
+ *     expiresAt:
+ *       type: string
+ *       format: date-time
+ *       example: '2026-05-01T08:00:00.000Z'
+ *     daysUntilExpiration: { type: integer, example: 6 }
+ * LockedAccount:
+ *   type: object
+ *   description: User account that is currently locked.
+ *   required: [dn, failureCount]
+ *   properties:
+ *     dn: { type: string, example: uid=charlie,ou=users,dc=example,dc=com }
+ *     uid: { type: string, example: charlie }
+ *     displayName: { type: string, example: Charlie Chaplin }
+ *     mail: { type: string, example: charlie@example.com }
+ *     lockedAt:
+ *       type: string
+ *       format: date-time
+ *       nullable: true
+ *       example: '2026-04-24T14:30:00.000Z'
+ *     failureCount: { type: integer, example: 5 }
+ * PasswordValidationRequest:
+ *   type: object
+ *   required: [password]
+ *   properties:
+ *     password:
+ *       type: string
+ *       format: password
+ *       description: The candidate password to validate.
+ *       example: 'S3cur3P@ss!'
+ *     dn:
+ *       type: string
+ *       description: Optional user DN for context (not used in local validation).
+ *       example: uid=alice,ou=users,dc=example,dc=com
+ * PasswordValidationResponse:
+ *   type: object
+ *   required: [valid, errors]
+ *   properties:
+ *     valid:
+ *       type: boolean
+ *       description: True when the password meets all complexity rules.
+ *       example: true
+ *     errors:
+ *       type: array
+ *       items: { type: string }
+ *       description: List of failed rule descriptions (empty when valid).
+ *       example: []
+ */
 export default class PasswordPolicy extends DmPlugin {
     name: string;
     roles: Role[];

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[];