ldap-rest 0.6.2 → 0.7.0

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

@@ -16,11 +16,10 @@
  * `tooMany` RFC 7644 §3.12 provides for a filter yielding "many more results
  * than the server is willing to calculate or process".
  */
-import type ldapActions from '../../lib/ldapActions';
-import type { AttributesList } from '../../lib/ldapActions';
-import type { DmRequest } from '../../lib/auth/base';
+import type { AttributesList, RequestBoundLdap } from '../../lib/ldapActions';
 export interface PagedSearch {
-    ldap: ldapActions;
+    /** The directory bound to the request, so authorization always applies. */
+    directory: RequestBoundLdap;
     base: string;
     filter: string;
     attributes: string[];
@@ -30,7 +29,6 @@ export interface PagedSearch {
     count: number;
     /** Upper bound on entries walked before answering `tooMany`. */
     maxScanned: number;
-    req?: DmRequest;
 }
 export interface PagedResult {
     entries: AttributesList[];

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

@@ -1,7 +1,22 @@
 import type { AttributesList } from '../../lib/ldapActions';
 import { type ScimUser, type ScimGroup, type ResourceMapping, type MultiValued } from './types';
 export declare const DEFAULT_USER_MAPPING: ResourceMapping;
+/**
+ * Group mapping.
+ *
+ * `externalId` is deliberately absent: RFC 7643 section 3.1 defines it as the
+ * *provisioning client's* identifier, so it cannot be served from a
+ * server-assigned value. groupOfNames has no attribute meant to hold one
+ * either, so the deployment names one with
+ * `--scim-group-external-id-attribute` and the entry is added at runtime by
+ * `withExternalId()`.
+ */
 export declare const DEFAULT_GROUP_MAPPING: ResourceMapping;
+/**
+ * Add the `externalId` entry when the deployment named an attribute to store
+ * it in. An entry already present — from a mapping override — wins.
+ */
+export declare function withExternalId(mapping: ResourceMapping, ldapAttribute: string): ResourceMapping;
 /**
  * LDAP GeneralizedTime (RFC 4517 §3.3.13) → SCIM DateTime (RFC 7643 §2.3.5,
  * an `xsd:dateTime`).
@@ -31,7 +46,81 @@ export interface MappingContext {
     resourceType: 'User' | 'Group';
     baseUrl?: string;
     scimPrefix: string;
+    /**
+     * LDAP attribute whose *presence* marks the account as locked, and the
+     * value written to lock it. Both come from `resolveLockConfig()`, which is
+     * the only place the defaults live: re-defaulting here would let a context
+     * built outside the plugin reach the directory with a pair the startup
+     * guard never saw. Groups have no `active`, so they pass empty strings.
+     */
+    lockAttribute: string;
+    lockValue: string;
 }
+/**
+ * SCIM `active` (RFC 7643 section 4.1.1) has no direct LDAP equivalent. We
+ * model it on the presence of one attribute: present means locked, absent
+ * means active.
+ *
+ * The default is the ppolicy overlay's `pwdAccountLockedTime`, whose
+ * conventional "locked forever" value is a GeneralizedTime in the distant
+ * past. A directory without that overlay points
+ * `--scim-user-lock-attribute` / `--scim-user-lock-value` somewhere else
+ * (`nsAccountLock` / `TRUE`, for instance).
+ */
+export declare const DEFAULT_LOCK_ATTRIBUTE = "pwdAccountLockedTime";
+export declare const DEFAULT_LOCK_VALUE = "000001010000Z";
+/**
+ * Where the configuration warnings go. A seam rather than a direct
+ * `console.warn` so the unit tests can read what was said instead of
+ * asserting on stderr.
+ */
+export declare let warn: (message: string) => void;
+/** Testing seam: replace the warning sink, and get the previous one back. */
+export declare function setLockConfigWarn(sink: (message: string) => void): (message: string) => void;
+/**
+ * Settle the lock configuration, or refuse to start.
+ *
+ * Ways to get a deployment that answers 200 to every deactivation while the
+ * directory locks nothing:
+ *
+ * - naming an attribute without its value. `000001010000Z` is the ppolicy
+ *   convention and means nothing to `nsAccountLock`, which 389-ds reads as
+ *   locked only when it says `true` — so every deactivation would be
+ *   written, read back as `active: false`, and the account would keep
+ *   binding.
+ * - naming an attribute and pinning that same ppolicy value on it, which a
+ *   deployment template that always sets both flags does by default. The
+ *   guard above sees a value and passes; the outcome is identical.
+ * - the mirror: a value the default attribute cannot hold.
+ *   `pwdAccountLockedTime` is a GeneralizedTime, so `TRUE` is refused by the
+ *   directory's schema — or, where the attribute was redefined locally,
+ *   stored and ignored.
+ * - a name that is not an attribute description. It is interpolated into the
+ *   emitted LDAP filter for `active eq …`, where a metacharacter makes
+ *   every list either malformed or quietly wrong.
+ *
+ * All are operator mistakes rather than attacks, and all are silent. The
+ * first and the last are refused outright. The two in the middle cannot be
+ * told apart from a deliberate local schema, so they are warned about: what
+ * the directory does with a value is beyond anything this can check.
+ */
+export declare function resolveLockConfig(attribute: string, value: string): {
+    attribute: string;
+    value: string;
+};
+/**
+ * Read a SCIM `active` value, wherever it came from.
+ *
+ * `undefined` means the body did not mention it — which is not the same as
+ * `true`. Only a boolean, or the two canonical strings some providers send
+ * instead, are accepted: guessing at `"0"`, `null` or `1` would let a
+ * deprovisioning request be executed as a re-activation, and answer 200
+ * doing it. The one rule lives here so POST, PUT, PATCH and the filter
+ * translator cannot drift apart.
+ */
+export declare function readActive(value: unknown): boolean | undefined;
+/** Is this entry locked, per the configured lock attribute? */
+export declare function isLocked(entry: AttributesList, ctx: MappingContext): boolean;
 /** Resolve the SCIM id for an LDAP entry, per configuration. */
 export declare function resolveScimId(entry: AttributesList, ctx: MappingContext): string | undefined;
 export declare function buildLocation(id: string, ctx: MappingContext): string | undefined;
@@ -44,6 +133,7 @@ export declare function ldapToScimUser(entry: AttributesList, mapping: ResourceM
 export declare function scimUserToLdap(user: ScimUser, mapping: ResourceMapping, ctx: MappingContext, objectClass: string[]): {
     rdn: string;
     attributes: AttributesList;
+    active?: boolean;
 };
 export declare function ldapToScimGroup(entry: AttributesList, mapping: ResourceMapping, ctx: MappingContext, memberResolver?: (dn: string) => MultiValued | undefined): ScimGroup;
 /**
@@ -58,15 +148,6 @@ export declare function scimGroupToLdap(group: ScimGroup, mapping: ResourceMappi
  * List of LDAP attributes to request from the directory so all
  * mapped SCIM attributes can be populated.
  */
-/**
- * The ppolicy overlay's lock marker, whose presence means `active: false`.
- *
- * Operational, so a search that does not name it never answers it: the read
- * path has to ask for it explicitly.
- */
-export declare const LOCK_ATTRIBUTE = "pwdAccountLockedTime";
-/** Is this entry locked, per the ppolicy lock marker? */
-export declare function isLocked(entry: AttributesList): boolean;
 export declare function requiredLdapAttributes(mapping: ResourceMapping, extra?: string[]): string[];
 /**
  * Given a SCIM attribute path like "emails.value" or "name.familyName",

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

@@ -19,7 +19,7 @@
  * member operations for Groups are handled via the caller-provided
  * `resolveMemberRef` hook (SCIM id → LDAP DN lookup).
  */
-import type { ModifyRequest } from '../../lib/ldapActions';
+import type { AttributesList, ModifyRequest } from '../../lib/ldapActions';
 import { type ResourceMapping, type PatchRequest } from './types';
 export interface PatchContext {
     mapping: ResourceMapping;
@@ -27,6 +27,21 @@ export interface PatchContext {
     resolveMemberRef?: (value: string) => Promise<string | undefined>;
     /** The LDAP attribute holding members, default 'member'. */
     memberAttribute?: string;
+    /**
+     * For Users: the attribute whose presence marks the account as locked, and
+     * the value to write when SCIM `active` is set to false.
+     */
+    lockAttribute?: string;
+    lockValue?: string;
+    /** True when this resource type carries SCIM `active` (Users only). */
+    supportsActive?: boolean;
+    /**
+     * The entry as it stands. RFC 7644 section 3.5.2 applies operations in
+     * order, so they are played against this and only the resulting difference
+     * is sent — without it, two operations touching one attribute would
+     * collapse into whichever the emitter happened to keep.
+     */
+    current: AttributesList;
 }
 export declare function patchToModifyRequest(patch: PatchRequest, ctx: PatchContext): Promise<ModifyRequest>;
 /**

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

@@ -0,0 +1,15 @@
+export interface ProjectionQuery {
+    attributes?: string[];
+    excludedAttributes?: string[];
+}
+/**
+ * Raise when both parameters are given: RFC 7644 §3.9 makes them mutually
+ * exclusive, and honouring one silently would hide the mistake.
+ */
+export declare function assertProjection(query: ProjectionQuery): void;
+/** Apply `attributes` / `excludedAttributes` to one resource. */
+export declare function projectResource<T extends Record<string, unknown>>(resource: T, query: ProjectionQuery): T;
+/** Apply the projection to every resource of a ListResponse. */
+export declare function projectList<T extends Record<string, unknown>, L extends {
+    Resources: T[];
+}>(list: L, query: ProjectionQuery): L;

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

@@ -419,6 +419,11 @@ export default class Scim extends DmPlugin {
      * `--scim-base-url` to make it absolute and trustworthy too.
      */
     private scimResource;
+    /**
+     * `attributes` / `excludedAttributes` (RFC 7644 section 3.9). Accepted on
+     * every route that answers a resource, not only the list ones.
+     */
+    private parseProjection;
     private readScimBody;
     api(app: Express): void;
     private parseListQuery;

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

@@ -41,14 +41,35 @@ export declare class ScimUsers {
     private readonly maxResults;
     private readonly maxScanned;
     private readonly scimPrefix;
+    private readonly lockAttribute;
+    private readonly lockValue;
     constructor(opts: ScimUsersOptions);
     private ctx;
+    /**
+     * LDAP attributes to fetch. The lock attribute backing SCIM `active` is
+     * operational on most directories, so it is never returned unless asked
+     * for by name.
+     */
+    private ldapAttributes;
     private dnForId;
     get(req: DmRequest, id: string): Promise<ScimUser>;
     list(req: DmRequest, query: ListQuery): Promise<ListResponse<ScimUser>>;
     create(req: DmRequest, resource: ScimUser): Promise<ScimUser>;
     replace(req: DmRequest, id: string, resource: ScimUser): Promise<ScimUser>;
     patch(req: DmRequest, id: string, patch: PatchRequest): Promise<ScimUser>;
+    /**
+     * Re-raise a directory refusal that names the schema, pointing at the flag
+     * that caused it.
+     *
+     * The generic translation in `errors` cannot do this: it sees the error,
+     * not the configuration. Only this class knows which attribute was
+     * configured to back `active`, and the shipped default —
+     * `pwdAccountLockedTime` — exists only where slapd loads the ppolicy
+     * overlay, which is the common way to meet this.
+     */
+    private lockSchemaError;
+    /** Fetch the raw LDAP entry backing a SCIM id, or raise 404. */
+    private currentEntry;
     delete(req: DmRequest, id: string): Promise<void>;
     /**
      * Given a SCIM member value (typically an id), return the LDAP DN.

package/docs/README.md

@@ -10,6 +10,7 @@ Installation, configuration and plugin usage.
 
 - **[Getting Started](usage/README.md)** - Quick start guide
 - **[Configuration](usage/configuration.md)** - CLI options and environment variables
+- **[Upgrading](usage/upgrading.md)** - What to check before deploying a new version
 - **[Plugins](usage/plugins/README.md)** - Documentation for all available plugins
 
 ### [Plugin Development](plugin-development/README.md)

package/docs/plugin-development/README.md

@@ -455,6 +455,28 @@ export default class MyPlugin extends DmPlugin {
 
 The `this.server.ldap` object provides access to all LDAP operations:
 
+> **Serving an HTTP request? Bind it first.**
+>
+> The authorization plugins (`core/auth/authzPerBranch`,
+> `core/auth/authzDynamic`, …) hook `ldapsearchrequest`, `ldapaddrequest`,
+> `ldapmodifyrequest`, `ldaprenamerequest` and `ldapdeleterequest`, and they
+> **skip every check when the request is missing**. The methods below take it as a trailing
+> optional argument, so forgetting it does not fail — it silently authorizes
+> the operation. Three such bugs shipped in the SCIM plugin.
+>
+> In a request handler, bind once and use the result:
+>
+> ```typescript
+> const directory = this.server.ldap.forRequest(req);
+> await directory.search({ scope: 'base' }, dn);
+> await directory.modify(dn, changes);
+> ```
+>
+> `forRequest()` returns a `RequestBoundLdap`, whose methods have no request
+> parameter at all — the omission stops being expressible. Use the unbound
+> methods only for work that genuinely belongs to no request, such as startup
+> or scheduled tasks, where passing nothing is the deliberate answer.
+
 #### Search
 
 ```typescript

package/docs/usage/README.md

@@ -86,4 +86,5 @@ The system will:
 
 - **[Configuration](configuration.md)** - CLI options and environment variables
 - **[Plugins](plugins/README.md)** - Choose and configure plugins
+- **[Upgrading](upgrading.md)** - What to check before deploying a new version
 - **[Troubleshooting](troubleshooting.md)** - Problem resolution

package/docs/usage/plugins/integrations/scim.md

@@ -41,27 +41,30 @@ All SCIM endpoints sit behind the auth middleware registered before the plugin
 
 ### CLI / environment
 
-| Argument                       | Environment                     | Default                                            | Description                                                            |
-| ------------------------------ | ------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
-| `--scim-prefix`                | `DM_SCIM_PREFIX`                | `/scim/v2`                                         | Base URL path for all SCIM endpoints                                   |
-| `--scim-user-base`             | `DM_SCIM_USER_BASE`             | `{ldap_base}`                                      | LDAP branch containing users                                           |
-| `--scim-group-base`            | `DM_SCIM_GROUP_BASE`            | `{ldap_base}`                                      | LDAP branch containing groups                                          |
-| `--scim-user-base-template`    | `DM_SCIM_USER_BASE_TEMPLATE`    | —                                                  | DN template with `{user}` placeholder (see _multi-tenant_)             |
-| `--scim-group-base-template`   | `DM_SCIM_GROUP_BASE_TEMPLATE`   | —                                                  | Same for groups                                                        |
-| `--scim-base-map`              | `DM_SCIM_BASE_MAP`              | —                                                  | Path to JSON file mapping authenticated user → `{userBase, groupBase}` |
-| `--scim-user-object-class`     | `DM_SCIM_USER_OBJECT_CLASSES`   | `top, inetOrgPerson, organizationalPerson, person` | Object classes for created Users                                       |
-| `--scim-user-rdn-attribute`    | `DM_SCIM_USER_RDN_ATTRIBUTE`    | `uid`                                              | RDN attribute for Users                                                |
-| `--scim-group-object-class`    | `DM_SCIM_GROUP_OBJECT_CLASSES`  | `top, groupOfNames`                                | Object classes for created Groups                                      |
-| `--scim-group-rdn-attribute`   | `DM_SCIM_GROUP_RDN_ATTRIBUTE`   | `cn`                                               | RDN attribute for Groups                                               |
-| `--scim-id-attribute`          | `DM_SCIM_ID_ATTRIBUTE`          | `rdn`                                              | `rdn` (default) or `entryUUID` for SCIM `id`                           |
-| `--scim-user-mapping`          | `DM_SCIM_USER_MAPPING`          | —                                                  | Path to JSON mapping override                                          |
-| `--scim-group-mapping`         | `DM_SCIM_GROUP_MAPPING`         | —                                                  | Same for Groups                                                        |
-| `--scim-max-results`           | `DM_SCIM_MAX_RESULTS`           | `200`                                              | Maximum page size (caps `count`)                                       |
-| `--scim-max-scanned`           | `DM_SCIM_MAX_SCANNED`           | `10000`                                            | Entries a list may walk before answering `400 tooMany`                 |
-| `--scim-bulk-max-operations`   | `DM_SCIM_BULK_MAX_OPERATIONS`   | `100`                                              | Max `/Bulk` operations per request                                     |
-| `--scim-bulk-max-payload-size` | `DM_SCIM_BULK_MAX_PAYLOAD_SIZE` | `1048576`                                          | Max `/Bulk` payload size in bytes                                      |
-| `--scim-etag`                  | `DM_SCIM_ETAG`                  | `false`                                            | Advertise ETag support in discovery (not yet implemented)              |
-| `--scim-base-url`              | `DM_SCIM_BASE_URL`              | auto from request                                  | Override external base URL for `meta.location` values                  |
+| Argument                             | Environment                           | Default                                            | Description                                                                                      |
+| ------------------------------------ | ------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `--scim-prefix`                      | `DM_SCIM_PREFIX`                      | `/scim/v2`                                         | Base URL path for all SCIM endpoints                                                             |
+| `--scim-user-base`                   | `DM_SCIM_USER_BASE`                   | `{ldap_base}`                                      | LDAP branch containing users                                                                     |
+| `--scim-group-base`                  | `DM_SCIM_GROUP_BASE`                  | `{ldap_base}`                                      | LDAP branch containing groups                                                                    |
+| `--scim-user-base-template`          | `DM_SCIM_USER_BASE_TEMPLATE`          | —                                                  | DN template with `{user}` placeholder (see _multi-tenant_)                                       |
+| `--scim-group-base-template`         | `DM_SCIM_GROUP_BASE_TEMPLATE`         | —                                                  | Same for groups                                                                                  |
+| `--scim-base-map`                    | `DM_SCIM_BASE_MAP`                    | —                                                  | Path to JSON file mapping authenticated user → `{userBase, groupBase}`                           |
+| `--scim-user-object-class`           | `DM_SCIM_USER_OBJECT_CLASSES`         | `top, inetOrgPerson, organizationalPerson, person` | Object classes for created Users                                                                 |
+| `--scim-user-rdn-attribute`          | `DM_SCIM_USER_RDN_ATTRIBUTE`          | `uid`                                              | RDN attribute for Users                                                                          |
+| `--scim-user-lock-attribute`         | `DM_SCIM_USER_LOCK_ATTRIBUTE`         | `pwdAccountLockedTime`                             | LDAP attribute whose presence marks a User as `active: false`                                    |
+| `--scim-user-lock-value`             | `DM_SCIM_USER_LOCK_VALUE`             | —                                                  | Value written to that attribute when deactivating (required unless the attribute is the default) |
+| `--scim-group-object-class`          | `DM_SCIM_GROUP_OBJECT_CLASSES`        | `top, groupOfNames`                                | Object classes for created Groups                                                                |
+| `--scim-group-rdn-attribute`         | `DM_SCIM_GROUP_RDN_ATTRIBUTE`         | `cn`                                               | RDN attribute for Groups                                                                         |
+| `--scim-group-external-id-attribute` | `DM_SCIM_GROUP_EXTERNAL_ID_ATTRIBUTE` | —                                                  | LDAP attribute storing a Group's `externalId` (unset: not supported)                             |
+| `--scim-id-attribute`                | `DM_SCIM_ID_ATTRIBUTE`                | `rdn`                                              | `rdn` (default) or `entryUUID` for SCIM `id`                                                     |
+| `--scim-user-mapping`                | `DM_SCIM_USER_MAPPING`                | —                                                  | Path to JSON mapping override                                                                    |
+| `--scim-group-mapping`               | `DM_SCIM_GROUP_MAPPING`               | —                                                  | Same for Groups                                                                                  |
+| `--scim-max-results`                 | `DM_SCIM_MAX_RESULTS`                 | `200`                                              | Maximum page size (caps `count`)                                                                 |
+| `--scim-max-scanned`                 | `DM_SCIM_MAX_SCANNED`                 | `10000`                                            | Entries a list may walk before answering `400 tooMany`                                           |
+| `--scim-bulk-max-operations`         | `DM_SCIM_BULK_MAX_OPERATIONS`         | `100`                                              | Max `/Bulk` operations per request                                                               |
+| `--scim-bulk-max-payload-size`       | `DM_SCIM_BULK_MAX_PAYLOAD_SIZE`       | `1048576`                                          | Max `/Bulk` payload size in bytes                                                                |
+| `--scim-etag`                        | `DM_SCIM_ETAG`                        | `false`                                            | Advertise ETag support in discovery (not yet implemented)                                        |
+| `--scim-base-url`                    | `DM_SCIM_BASE_URL`                    | auto from request                                  | Override external base URL for `meta.location` values                                            |
 
 ### Authorization
 
@@ -110,27 +113,91 @@ All responses have `Content-Type: application/scim+json`.
 
 ### Default mapping (LDAP ⇄ SCIM User)
 
-| SCIM                                 | LDAP                                            |
-| ------------------------------------ | ----------------------------------------------- |
-| `id`                                 | `uid` (or `entryUUID`)                          |
-| `userName`                           | `uid`                                           |
-| `externalId`                         | `employeeNumber`                                |
-| `name.familyName`                    | `sn`                                            |
-| `name.givenName`                     | `givenName`                                     |
-| `name.formatted`                     | `cn`                                            |
-| `displayName`                        | `displayName`                                   |
-| `title`                              | `title`                                         |
-| `preferredLanguage`                  | `preferredLanguage`                             |
-| `emails[primary=true].value`         | `mail`                                          |
-| `emails[primary=false].value`        | `mailAlternateAddress`                          |
-| `phoneNumbers[primary=true].value`   | `telephoneNumber`                               |
-| `phoneNumbers[primary=false].value`  | `mobile`                                        |
-| `active`                             | pseudo (false if `pwdAccountLockedTime` is set) |
-| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`           |
+| SCIM                                 | LDAP                                        |
+| ------------------------------------ | ------------------------------------------- |
+| `id`                                 | `uid` (or `entryUUID`)                      |
+| `userName`                           | `uid`                                       |
+| `externalId`                         | `employeeNumber`                            |
+| `name.familyName`                    | `sn`                                        |
+| `name.givenName`                     | `givenName`                                 |
+| `name.formatted`                     | `cn`                                        |
+| `displayName`                        | `displayName`                               |
+| `title`                              | `title`                                     |
+| `preferredLanguage`                  | `preferredLanguage`                         |
+| `emails[primary=true].value`         | `mail`                                      |
+| `emails[primary=false].value`        | `mailAlternateAddress`                      |
+| `phoneNumbers[primary=true].value`   | `telephoneNumber`                           |
+| `phoneNumbers[primary=false].value`  | `mobile`                                    |
+| `active`                             | pseudo (false if the lock attribute is set) |
+| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`       |
 
 Override with `--scim-user-mapping /path/to/user-mapping.json` (same schema as
 `static/schemas/scim/default-mapping.json`).
 
+## Deactivating an account (`active`)
+
+SCIM models account status with the boolean `active` (RFC 7643 §4.1.1), and it
+is how Okta, Entra ID and JumpCloud disable a user — they PATCH `active` to
+`false` rather than DELETE the resource.
+
+LDAP has no single equivalent, so the plugin models it on the **presence of one
+attribute**: present means locked, absent means active.
+
+| SCIM              | LDAP                                            |
+| ----------------- | ----------------------------------------------- |
+| `"active": false` | write `--scim-user-lock-value` to the attribute |
+| `"active": true`  | remove the attribute                            |
+| attribute absent  | `"active": true`                                |
+
+The default targets the ppolicy overlay:
+
+```bash
+--scim-user-lock-attribute pwdAccountLockedTime
+--scim-user-lock-value     000001010000Z          # "locked forever"
+```
+
+`pwdAccountLockedTime` only exists when slapd loads the ppolicy overlay. On a
+directory without it — plain OpenLDAP, 389-ds, AD — the directory refuses the
+write against its schema, and the plugin answers `400 invalidValue` naming
+the attribute and the flags to change, on `/Bulk` as on the single-resource
+routes. Point the two flags elsewhere:
+
+```bash
+--scim-user-lock-attribute nsAccountLock
+--scim-user-lock-value     TRUE
+```
+
+**Name the value whenever you name the attribute.** `000001010000Z` is the
+ppolicy convention and means nothing to any other attribute: 389-ds reads
+`nsAccountLock` as locked only when it says `true`. Setting the attribute
+alone would write a value the directory ignores — every deactivation answers
+200 and reads back `active: false` while the account keeps binding. The
+plugin refuses to start instead.
+
+Two more pairings get a warning at startup rather than a refusal, because
+neither can be told apart from a deliberate local schema:
+
+- the ppolicy value `000001010000Z` pinned on some other attribute, which is
+  what a deployment template that always sets both flags produces by default
+- a value `pwdAccountLockedTime` cannot hold, `TRUE` for instance: it holds a
+  GeneralizedTime
+
+**None of this can tell whether your directory honours the value you chose.**
+The checks are on the shape of the configuration. `active` is read back from
+the mere presence of the attribute, so a value the directory stores and
+ignores still reads as `false`. Verify once, by hand, that a deactivation
+actually prevents a bind.
+
+`active` is not a mapping entry and must not be added to a mapping file: it is
+handled by these two flags on every path — create, PUT, PATCH and the
+`active eq true|false` filter alike.
+
+PUT is a full replacement (RFC 7644 §3.5.1) for every attribute except this
+one: a body that omits `active` leaves the lock as it stands. Clearing it
+would release locks SCIM never set — a ppolicy auto-lockout, or one an
+administrator placed — so a routine profile sync would defeat the
+brute-force control. Send `"active": true` to reactivate deliberately.
+
 ## Writing a custom mapping schema
 
 The mapping file is a plain JSON document describing how each SCIM attribute is
@@ -247,6 +314,23 @@ adjust the loader). Exposing a schema there is **independent** from the
 LDAP↔SCIM projection: the schema file describes the public SCIM contract, the
 mapping file describes the internal translation.
 
+### Group `externalId`
+
+RFC 7643 §3.1 defines `externalId` as the **provisioning client's** identifier —
+the id Okta or Entra ID keeps for its own copy of the resource, which it later
+uses to find the group again (`filter=externalId eq "…"`).
+
+For Users it lands in `employeeNumber`. groupOfNames has no attribute meant to
+hold one, so nothing is stored unless the deployment names an attribute:
+
+```bash
+--scim-group-external-id-attribute description
+```
+
+Without it, `externalId` sent on a Group is ignored and a filter on it answers
+`400 invalidFilter` — which is at least honest. Any free attribute of your
+group entries works; use a mapping override if you would rather name it there.
+
 ## Filter syntax
 
 SCIM filters are translated to LDAP filters (RFC 4515). Values are always escaped
@@ -259,6 +343,7 @@ via `escapeLdapFilter()` — no LDAP injection is possible.
 | `emails.value co "@example.com"` | `(mail=*@example.com*)`       |
 | `displayName pr`                 | `(displayName=*)`             |
 | `active eq true`                 | `(!(pwdAccountLockedTime=*))` |
+| `active pr`                      | `(objectClass=*)`             |
 | `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`               |
 | `not (a eq "x")`                 | `(!(a=x))`                    |
 
@@ -297,6 +382,30 @@ willing to calculate or process". Raise the flag, or narrow the query.
 If the directory's own size limit is lower than the collection, it refuses the
 search first and the answer is the same `tooMany` — raise `sizelimit` in slapd.
 
+## Partial representations (`attributes` / `excludedAttributes`)
+
+Any route that answers a resource accepts the two RFC 7644 §3.9 parameters —
+the lists, the single-resource GETs, and the POST/PUT/PATCH answers alike.
+
+```bash
+curl '.../Users/alice?attributes=userName,name.familyName'
+curl '.../Users?excludedAttributes=emails'
+```
+
+- `attributes` replaces the default set: only what you name comes back.
+- `excludedAttributes` keeps the default set minus what you name.
+- Both accept standard attribute notation, so `name.familyName` and
+  `emails.value` narrow a complex or multi-valued attribute rather than
+  dropping it whole, and a core schema URN prefix is accepted and stripped.
+- `id` and `schemas` are `returned: always` (RFC 7643 §7): they survive an
+  exclusion and are added back to an `attributes` list.
+- `meta` is `returned: default`, so an `attributes` list that does not name it
+  does not get it. Ask for `meta` explicitly if you need `meta.location`.
+- The two are mutually exclusive; sending both answers `400 invalidValue`.
+
+The projection applies to the response only — the LDAP search still reads the
+attributes the mapping needs.
+
 ## Multi-tenant: per-user LDAP bases
 
 SCIM does not expose any tenant concept to clients — resource `id`s are opaque

package/docs/usage/upgrading.md

@@ -0,0 +1,122 @@
+# Upgrading
+
+What to check before deploying, newest first. Only releases that need a
+decision or a configuration change appear here; see the
+[CHANGELOG](../../CHANGELOG.md) for everything else.
+
+## To 0.7.0
+
+### `externalId` on Groups is no longer served
+
+**Who is affected:** anyone provisioning Groups from an identity provider and
+reading `externalId` back, or filtering on it.
+
+A Group's `externalId` used to answer its `entryUUID`. RFC 7643 section 3.1
+makes `externalId` the _provisioning client's_ identifier, so the id Okta or
+Entra ID sent was discarded on write, and `filter=externalId eq "<their id>"`
+searched `entryUUID` and matched nothing.
+
+Name an attribute to store it in:
+
+```bash
+--scim-group-external-id-attribute description
+```
+
+Left unset, `externalId` is simply not supported on Groups — absent from
+answers, and refused in filters. That is the honest behaviour; the previous
+one looked like support and was not.
+
+Users are unaffected: theirs was already stored in `employeeNumber`.
+
+**Migrating existing Groups.** Values sent before this release were never
+stored, so there is nothing to convert — re-send them from the provisioning
+side once the flag is set.
+
+### `active` is now writable, and needs an attribute your directory holds
+
+**Who is affected:** every SCIM deployment. Deactivations that used to be
+silently dropped now reach the directory.
+
+`active` is modelled on the presence of one LDAP attribute:
+
+```bash
+--scim-user-lock-attribute pwdAccountLockedTime   # default
+--scim-user-lock-value     000001010000Z          # default, "locked forever"
+```
+
+The default is the ppolicy overlay's convention, and **`pwdAccountLockedTime`
+only exists where slapd loads that overlay**. On a directory without it —
+plain OpenLDAP, 389-ds, AD — a deactivation is refused by the schema and
+answers `400 invalidValue` naming the flags. Point them elsewhere:
+
+```bash
+--scim-user-lock-attribute nsAccountLock
+--scim-user-lock-value     TRUE
+```
+
+Two configuration mistakes are now refused at startup rather than accepted
+and silently ineffective: naming an attribute without a value, and a name
+that is not an LDAP attribute description. Two more are warned about. See
+[the SCIM plugin documentation](plugins/integrations/scim.md#deactivating-an-account-active) for the
+detail.
+
+**Verify once, by hand, that a deactivation actually prevents a bind.**
+Nothing here can check that your directory honours the value you chose:
+`active` is read back from the mere presence of the attribute, so a value the
+directory stores and ignores still reads as `false`.
+
+**One deliberate deviation from RFC 7644 section 3.5.1:** a `PUT` that omits
+`active` leaves the lock as it stands rather than clearing it. Clearing it
+would release locks SCIM never set — a ppolicy auto-lockout after failed
+binds, or one an administrator placed — so a routine profile sync would
+defeat the brute-force control. Send `"active": true` to reactivate
+deliberately.
+
+### `forRequest()` for plugin authors
+
+No action needed to upgrade. If you maintain a plugin that serves HTTP
+requests, `this.server.ldap.forRequest(req)` returns a directory whose methods
+carry the request, so the authorization hooks always see it. The unbound
+methods take the request as a trailing optional argument, and omitting it
+skips every authorization check silently. See the
+[plugin development guide](../plugin-development/README.md#using-ldap-operations).
+
+## To 0.6.2
+
+### Writes that a bypass was letting through are now refused
+
+**Who is affected:** deployments using `core/auth/authzPerBranch` or
+`core/auth/authzLinid1` together with `plugins/ldap/onChange` or
+`plugins/ldap/organizations`.
+
+Both plugins rebuilt the hook tuple without the request, which made every
+authorization plugin registered after them skip its check. Every `modify`,
+and every `rename` for the second, went through unchecked.
+
+**Check your grants before rolling this out widely.** An identity whose
+grants were never quite right may start seeing `403` where it saw `200`. That
+is the fix, not a regression.
+
+Whether a given deployment was exposed was decided by plugin load order,
+which is a race — it could differ from one restart to the next.
+`core/auth/authzDynamic` was never affected: it reads its token from an
+`AsyncLocalStorage` rather than from the request.
+
+## To 0.6.1
+
+### SCIM reads are authorized
+
+**Who is affected:** any SCIM identity granted `write` without `read` on the
+same branch.
+
+Every search the SCIM plugin issued omitted the request, so
+`ldapsearchrequest` — the hook the authorization plugins use — skipped its
+check, and any authenticated identity could read any branch the plugin was
+pointed at.
+
+**An identity that writes now needs `read` on the same branch.** A SCIM write
+answers with the resource it just changed, so it reads the entry back; a
+grant of `write` without `read` no longer serves a write.
+
+`GET /Users`, `GET /Users/{id}` and their Group counterparts answer `403`
+where read is denied.