ldap-rest 2.0.0 → 2.0.1

package/README.md

@@ -81,7 +81,7 @@ See **[Configuration Guide](./docs/usage/configuration.md)** for all CLI options
 
 ## Documentation
 
-Documentation is organized into 3 categories:
+Documentation is organized into 4 categories:
 
 ### [Usage](./docs/usage/README.md)
 
@@ -110,6 +110,13 @@ Integrate LDAP-Rest into your web applications.
 - **[Examples](./docs/client-development/examples/README.md)** - React, Vue.js, Vanilla JS
 - **[Browser Demos](./examples/web/)** - Interactive demos (TOTP client, LDAP tree viewer)
 
+### [Architecture](./docs/architecture/README.md)
+
+How the server is put together and why.
+
+- **[Overview](./docs/architecture/README.md)** - Module map, life of a request, life of a write
+- **[Decision records](./docs/architecture/adr/)** - The decisions the code embodies
+
 ## Copyright and license
 
 [![Powered by LINAGORA](./docs/linagora.png)](https://linagora.com)

package/dist/bin/index.js

@@ -1 +1 @@
-import{fileURLToPath as e}from"url";import{join as t,dirname as i}from"path";import s from"express";import r from"body-parser";import{ConfigParser as o}from"../lib/parseConfig.js";import{unknownEnvironmentOptions as n}from"../config/options.js";import{keepRawBody as a}from"../lib/rawBody.js";import h from"../config/args.js";import l from"../lib/ldapActions.js";import{buildLogger as d}from"../logger/winston.js";import{setLogger as u,setDebug as c,errorResponse as g,messageOf as p}from"../lib/expressFormatedResponses.js";import{prefixCoversPath as f}from"../lib/auth/base.js";import{assertAuthzComposition as m,assertEnforceable as w,LDAP_JUDGING_HOOKS as b}from"../lib/authz/composition.js";import{registerAttributeTypes as v}from"../lib/utils.js";export{assertRfc4514Escapes,assertedRdnValue,asyncHandler,canonicalDn,escapeDnValue,escapeLdapFilter,escapeRegex,fillPattern,getCompiledRegex,getParentDn,getRdn,hasOnlyRfc4514Escapes,isChildOf,isDirectChildOf,isDnInBranch,isDnSyntax,isDummyMemberDn,knownAttributeName,movedToTrash,namesByDn,normalizeDn,organizationLink,parseDirectoryDate,parseDn,rdnTypes,rdnValue,substringSearchFilter,transformSchemas,unescapeDnValue,validateDnValue}from"../lib/utils.js";import{BadRequestError as y,errorChain as $}from"../lib/errors.js";export{AuthzRefusedError,BadGatewayError,ConflictError,ForbiddenError,GatewayTimeoutError,HttpError,NotFoundError,ServiceUnavailableError,TooManyRequestsError,UnauthorizedError,UriTooLongError}from"../lib/errors.js";import P,{recordHookOwner as j}from"../lib/hookBus.js";export{hookOwner,runAsHookOwner}from"../lib/hookBus.js";import{runWithLogContext as k,runForRequest as O}from"../lib/requestContext.js";import{requestId as S}from"../lib/changeContext.js";import{mountHealth as M,HEALTH_PATHS as x}from"../lib/health.js";import{httpRequestDuration as D,routeTemplate as C,secondsSince as E,unhandledRejections as _}from"../lib/metrics.js";import{registerProcessShutdown as A,shutdownTimeout as R}from"../lib/shutdown.js";import T from"../plugins/priority.json.js";const rejectEmptyMediaType=(e,t,i)=>{const s=e.headers["content-type"];(e=>void 0!==e.headers["transfer-encoding"]||!Number.isNaN(Number(e.headers["content-length"])))(e)&&"string"==typeof s&&""===s.split(";",1)[0].trim()?i(new y("Content-Type names no media type")):i()},stackChain=e=>{const t=$(e).map(e=>e.stack).filter(e=>Boolean(e));return t.length?t.join("\nCaused by: "):void 0},L=b.filter(e=>"ldapsearchfilter"!==e);class DM{app;config;ready;get server(){return this.life.server}set server(e){this.life.server=e}hooks={};hookBus=new P(this.hooks);loadedPlugins={};services=new Map;serviceOwners=new Map;ldap;operationSequence;logger;authenticators=[];_authState={dispatcherMounted:!1};_errorMiddlewareSetup=!1;bodyParsers=s.Router();_composed=!1;get composed(){return this._composed}life={unhandledRejections:0};inFlight=new Set;get stopping(){return void 0!==this.life.shutdown}get unhandledRejections(){return this.life.unhandledRejections}_errorMiddleware;pluginLoads=new Map;unknownCliOptions;deprecationWarnings;authzHooks=new WeakSet;constructor(){const e=new o(h);this.config=e.parse(),this.unknownCliOptions=e.unknownOptions,this.deprecationWarnings=e.deprecationWarnings,this.app=s(),this.app.disable("x-powered-by"),this.app.use((e,t,i)=>{const s=process.hrtime.bigint();t.setHeader("X-Content-Type-Options","nosniff"),this.stopping&&t.setHeader("Connection","close"),this.inFlight.add(t),t.once("finish",()=>{D.observe({method:e.method,route:C(e),status:String(t.statusCode)},E(s)),this.stopping&&this.server?.closeIdleConnections()}),t.once("close",()=>this.inFlight.delete(t)),i()}),this.app.use((e,t,i)=>{const s=S(e);t.setHeader("X-Request-Id",s),k({requestId:s},i)}),this.app.use(rejectEmptyMediaType),this.app.use(this.bodyParsers),this.app.use(r.json({verify:a})),this.app.use(r.urlencoded({extended:!0,verify:a})),M(this.app,this),this.logger=d(this.config);for(const e of this.deprecationWarnings)this.logger.warn(e);this.ldap=new l(this),u(this.logger),c(this.config.debug),this.operationSequence=0;const t=[];if(this.config.plugin){const e=this.config.plugin.find(e=>e.includes("configApi"));let i=this.config.plugin.filter(e=>!e.includes("configApi"));const s=this.logger,r=(async()=>{for(const e of T){const t=this.resolveModule(DM.moduleOf(e)),r=i.filter(e=>this.resolveModule(DM.moduleOf(e))===t);if(0!==r.length){i=i.filter(e=>!r.includes(e));for(const e of r)s.debug(`Loading ${e} in the priority pass`),await this.loadPlugin(e)}}})();t.push(r),t.push(r.then(async()=>{const e=i.map(e=>(s.debug(`Loading ${e} in the parallel batch`),this.loadPlugin(e)));await Promise.all(e)})),e&&t.push(Promise.all(t).then(()=>this.loadPlugin(e)))}this.ready=new Promise((e,i)=>{t.length>0?Promise.all(t).then(async()=>{this.setupErrorMiddleware(),this.warnUnauthenticatedRoutes(),await m(this),w(this),await this.learnAttributeTypes(),this._composed=!0,this.reportUnknownOptions(),this.afterLoad(),e()}).catch(e=>i(new Error("Error loading plugins: "+e))):(this.setupErrorMiddleware(),this._composed=!0,e())})}async learnAttributeTypes(){if(Object.values(this.loadedPlugins).some(e=>e.roles?.includes("authz")))try{v((await this.ldap.schemaIndex()).schema.attributeTypes)}catch(e){this.logger.warn(`Could not read the directory schema, DNs are compared with the usual attribute type names only: ${String(e)}`)}}routerStack(){const e=this.app;return(e.router??e._router)?.stack}withConfig(e){return Object.assign(Object.create(Object.getPrototypeOf(this)),this,{config:e})}reportUnknownOptions(){const e=Object.values(this.loadedPlugins).map(e=>e.constructor.optionDefinitions??{}),t=new Set(e.flatMap(e=>Object.entries(e).flatMap(([e,t])=>[e,...(t.aliases??[]).map(e=>e.replace(/^--?/,"").replace(/-/g,"_"))]))),i=[...this.unknownCliOptions.filter(e=>!t.has(e.replace(/^--?/,"").replace(/-/g,"_"))).map(e=>`option ${e}`),...n(h,process.env,e).map(e=>`environment variable ${e}`)];if(0===i.length)return;const s=`Unknown configuration: ${i.join(", ")} — no declared option reads it`;if(this.config.strict_options)throw new Error(s);this.logger.warn(s)}mountAuthDispatcher(e){const t=e.roles||[];t.includes("protect")||t.includes("logging")||this.mountAuthDispatcherNow()}mountAuthDispatcherNow(){this._authState.dispatcherMounted||(this._authState.dispatcherMounted=!0,this.app.use((e,t,i)=>{this.dispatchAuth(e,t,i)}))}registerAuthenticator(e){this.mountAuthDispatcherNow(),this.authenticators.includes(e)||this.authenticators.push(e)}registerBodyParser(e,t){this.bodyParsers.use(e,t)}dispatchAuth(e,t,i){let s=-1,r=[];for(const t of this.authenticators)for(const i of t.pathPrefixes)f(i,e.path)&&(i.length>s?(s=i.length,r=[t]):i.length!==s||r.includes(t)||r.push(t));if(s<0&&(r=this.authenticators.filter(e=>0===e.pathPrefixes.length)),0===r.length)return i();const finish=s=>{if(s>=r.length)return O(e,i);const o=r[s];if(!o.afterChain)return finish(s+1);o.afterChain(e,t,()=>finish(s+1))},o=[];e.authenticators=o;const run=i=>{if(i>=r.length)return finish(0);const s=r[i];s.authenticate(e,t,()=>{s.vouchedFor(e)&&o.push(s.name),run(i+1)})};run(0)}afterLoad(){for(const e of Object.values(this.loadedPlugins))try{e.afterLoad?.()}catch(t){this.logger.error(`Plugin ${e.name}: afterLoad failed: ${String(t)}`)}}warnUnauthenticatedRoutes(){const e=Object.values(this.loadedPlugins).filter(e=>e.roles?.includes("auth"));if(0===e.length)return[];const t=[];for(const i of e){if(!i.pathPrefixes||0===i.pathPrefixes.length)return[];t.push(...i.pathPrefixes)}const i=this.routerStack(),s=new Set;for(const e of i||[]){const t=e.route?.path;"string"==typeof t?s.add(t):Array.isArray(t)&&t.forEach(e=>"string"==typeof e&&s.add(e))}const r=[...s].filter(e=>!x.includes(e)&&!t.some(t=>e===t||e.startsWith(`${t}/`))),o=Object.values(this.loadedPlugins).some(e=>e.roles?.includes("authz"));return r.length>0&&this.logger.warn(`Authentication is restricted to ${t.join(", ")}, so these routes are served without authentication`+(o?" nor authorization":"")+`: ${r.sort().join(", ")}`),r.sort()}setupErrorMiddleware(){if(this._errorMiddlewareSetup&&this._errorMiddleware){const e=this.routerStack();if(e){const t=e.findIndex(e=>e.handle===this._errorMiddleware);-1!==t&&e.splice(t,1)}}this._errorMiddleware=(e,t,i,s)=>{const{status:r,body:o}=g(e,this.config.debug);if(r<500)return this.logger.warn(`Client error ${r} in request ${t.method} ${t.path}: ${o.error}`),void(i.headersSent||i.status(r).json(o));this.logger.error(`Server error ${r} in request ${t.method} ${t.path}: ${p(e)}`,{stack:stackChain(e),url:t.url,method:t.method}),i.headersSent||i.status(r).json(o)},this.app.use(this._errorMiddleware),this._errorMiddlewareSetup=!0}exitOnCrash(){process.on("uncaughtException",e=>{this.logger.error(`Uncaught exception: ${e.message}`,{stack:stackChain(e)}),setTimeout(()=>process.exit(1),this.config.shutdown_timeout),this.shutdown().finally(()=>process.exit(1))}),process.on("unhandledRejection",e=>{this.life.unhandledRejections++,_.inc(),this.logger.error(`Unhandled promise rejection: ${e instanceof Error?e.message:String(e)}`,{stack:stackChain(e)})})}run(){return new Promise((e,t)=>{this.server=this.app.listen(this.config.port,i=>{i?(this.logger.error(`Error starting server: ${i}`),t(i)):(this.logger.debug(`Server started on port ${this.config.port}`),e())})})}stop(){this.app.removeAllListeners(),this.server?.close(),this.logger.debug("Server stopped")}shutdown(){return this.life.shutdown??=this.letGo(),this.life.shutdown}async letGo(){const e=this.config.shutdown_timeout,t=Date.now(),i=Math.max(1e3,e-5e3);this.logger.notice(`Shutting down, ${i} ms for what is in flight`);const s=this.server;if(s){const e=new Promise(e=>s.close(()=>e()));s.closeIdleConnections();for(const e of this.inFlight)e.headersSent||e.setHeader("Connection","close");await DM.within(e,i),s.closeAllConnections()}const r=new Map;for(const[e,t]of Object.entries(this.loadedPlugins))r.set(e,Promise.resolve().then(()=>t.close?.()).catch(t=>{this.logger.warn(`${e}: close failed: ${t instanceof Error?t.message:String(t)}`)}).finally(()=>r.delete(e)));const o=Promise.all(r.values()).then(()=>this.ldap.close().catch(()=>{})),n=Math.max(1e3,e-(Date.now()-t)-1e3);await DM.within(o,n)||(this.logger.warn(`Shut down with a close still pending: ${[...r.keys()].join(", ")||"the directory connections"}`),this.ldap.close().catch(()=>{})),this.logger.notice("Shut down")}static async within(e,t){let i;const s=new Promise(e=>{i=setTimeout(()=>e(!1),t)});try{return await Promise.race([e.then(()=>!0),s])}finally{clearTimeout(i)}}shutdownOnSignals(){R.ms=this.config.shutdown_timeout,A(()=>this.shutdown())}static moduleOf(e){const t=e.indexOf(":");return-1===t?e:e.substring(0,t)}resolveModule(s){return s.startsWith("core/")?s.replace("core/",t(i(e(import.meta.url)),"..","plugins")+"/").replace(/$/,".js"):s.startsWith(".")?e(new URL(s,import.meta.url)):s}loadPlugin(e){let t,i;if(/:/.test(e)){let s=e.substring(e.indexOf(":")+1);if(e=e.substring(0,e.indexOf(":")),/:/.test(s)){t=s.substring(0,s.indexOf(":")),t||(t=void 0),s=s.substring(s.indexOf(":")+1);try{i=JSON.parse(s),"object"!=typeof i?(this.logger.error(`Overrides for plugin ${e} are not valid: ${s}`),i=void 0):this.logger.debug(`Overrides for plugin ${t||e}: ${s}`)}catch(t){this.logger.error(`Failed to parse overrides for plugin ${e}: ${t}, using ${s}`),i=void 0}}else t=s,t||(t=void 0)}else t=void 0;const s=i?void 0:`${this.resolveModule(e)}\0${t??""}`,r=void 0===s?void 0:this.pluginLoads.get(s);if(r)return this.logger.debug(`Plugin ${e} already loaded, skipping`),r;const o=this.importPlugin(e,t,i);if(void 0!==s){this.pluginLoads.set(s,o);const forget=()=>{this.pluginLoads.get(s)===o&&this.pluginLoads.delete(s)};o.then(e=>e||forget(),forget)}return o}importPlugin(e,t,i){return this.logger.debug(`Loading plugin ${e}`),e.startsWith("core/")&&(e=this.resolveModule(e)),new Promise((s,r)=>{import(e).then(async o=>{let n;if(o&&o.default&&(o=o.default),i){const e={...this.config,...i};n=new o(this.withConfig(e))}else n=new o(this);if(!n)return r(new Error(`Unable to load ${e}`));s(await this.registerPlugin(e,n,t)),this.logger.debug(`Plugin ${n.name} loaded`)}).catch(t=>r(new Error(`Failed to load plugin ${e}: ${t}`)))})}async admitToComposition(e){this.loadedPlugins[e.name]=e;try{await m(this,e)}finally{delete this.loadedPlugins[e.name]}}async registerPlugin(e,t,i){if(t.name||(t.name=e),i&&(t.name=i),this.loadedPlugins[t.name])return this.logger.warn(`Plugin ${e} not registered: the name "${t.name}" is already taken. This instance is dropped and its routes will not exist. To load the same plugin twice, give each one a name: --plugin '${e}:${t.name}2:{…}'`),!1;if(this.logger.debug(`Registering plugin ${e} as ${t.name}`),t.dependencies)for(const e in t.dependencies)this.loadedPlugins[e]||(this.logger.debug(`Plugin ${t.name} depends on ${e}, loading it first`),await this.loadPlugin(t.dependencies[e]));if(this._composed&&await this.admitToComposition(t),t.api&&(this.mountAuthDispatcher(t),this.logger.debug(`Plugin ${t.name} has API, registering it`),await t.api(this.app),this._errorMiddlewareSetup&&this.setupErrorMiddleware()),t.hooks)for(const e in t.hooks){this.logger.debug(`Plugin ${t.name} has hook ${e}, registering it`);const i=t.hooks[e];if(void 0===i)continue;if("function"!=typeof i)throw new Error(`Plugin ${t.name}: hook ${e} is invalid`);const s=e;if(j(i,t.name,e),t.roles?.includes("authz")&&L.includes(s)){const e=this.hookBus.subscribers(s),t=e.findIndex(e=>!this.authzHooks.has(e));this.hookBus.insert(s,i,t<0?e.length:t),this.authzHooks.add(i)}else this.hookBus.subscribe(s,i)}return this.loadedPlugins[t.name]=t,this.registerServices(t),!0}registerServices(e){for(const t of e.provides??[]){const i=this.serviceOwners.get(t.token);void 0===i?(this.services.set(t.token,t.service),this.serviceOwners.set(t.token,e.name)):this.logger.warn(`Plugin ${e.name}: service '${t.token.name}' is already provided by ${i}; this one is ignored`)}}}export{y as BadRequestError,DM,j as recordHookOwner,v as registerAttributeTypes};
+import{fileURLToPath as e}from"url";import{join as t,dirname as s}from"path";import i from"express";import o from"body-parser";import{ConfigParser as r}from"../lib/parseConfig.js";import{unknownEnvironmentOptions as n}from"../config/options.js";import{keepRawBody as a}from"../lib/rawBody.js";import h from"../config/args.js";import l from"../lib/ldapActions.js";import{buildLogger as c}from"../logger/winston.js";import{setLogger as u,setDebug as d,errorResponse as p,messageOf as g}from"../lib/expressFormatedResponses.js";import{prefixCoversPath as f}from"../lib/auth/base.js";import{assertAuthzComposition as m,assertEnforceable as w,LDAP_JUDGING_HOOKS as b}from"../lib/authz/composition.js";import{registerAttributeTypes as v}from"../lib/utils.js";export{assertRfc4514Escapes,assertedRdnValue,asyncHandler,canonicalDn,escapeDnValue,escapeLdapFilter,escapeRegex,fillPattern,getCompiledRegex,getParentDn,getRdn,hasOnlyRfc4514Escapes,isChildOf,isDirectChildOf,isDnInBranch,isDnSyntax,isDummyMemberDn,knownAttributeName,movedToTrash,namesByDn,normalizeDn,organizationLink,parseDirectoryDate,parseDn,rdnTypes,rdnValue,substringSearchFilter,transformSchemas,unescapeDnValue,validateDnValue}from"../lib/utils.js";import{BadRequestError as y,errorChain as $}from"../lib/errors.js";export{AuthzRefusedError,BadGatewayError,ConflictError,ForbiddenError,GatewayTimeoutError,HttpError,NotFoundError,ServiceUnavailableError,TooManyRequestsError,UnauthorizedError,UriTooLongError}from"../lib/errors.js";import P,{recordHookOwner as j}from"../lib/hookBus.js";export{hookOwner,runAsHookOwner}from"../lib/hookBus.js";import{runWithLogContext as k,runForRequest as S}from"../lib/requestContext.js";import{requestId as O}from"../lib/changeContext.js";import{mountHealth as x,HEALTH_PATHS as D}from"../lib/health.js";import{httpRequestDuration as C,routeTemplate as E,secondsSince as M,unhandledRejections as A}from"../lib/metrics.js";import{registerProcessShutdown as _,shutdownTimeout as R}from"../lib/shutdown.js";import T from"../plugins/priority.json.js";const rejectEmptyMediaType=(e,t,s)=>{const i=e.headers["content-type"];(e=>void 0!==e.headers["transfer-encoding"]||!Number.isNaN(Number(e.headers["content-length"])))(e)&&"string"==typeof i&&""===i.split(";",1)[0].trim()?s(new y("Content-Type names no media type")):s()},stackChain=e=>{const t=$(e).map(e=>e.stack).filter(e=>Boolean(e));return t.length?t.join("\nCaused by: "):void 0},L=b.filter(e=>"ldapsearchfilter"!==e);class DM{app;config;ready;get server(){return this.life.server}set server(e){this.life.server=e}hooks={};hookBus=new P(this.hooks);loadedPlugins={};services=new Map;serviceOwners=new Map;ldap;_operations={sequence:0};get operationSequence(){return this._operations.sequence}set operationSequence(e){this._operations.sequence=e}logger;authenticators=[];_authState={dispatcherMounted:!1};_errorState={};bodyParsers=i.Router();_compositionState={composed:!1};get composed(){return this._compositionState.composed}life={unhandledRejections:0};inFlight=new Set;get stopping(){return void 0!==this.life.shutdown}get unhandledRejections(){return this.life.unhandledRejections}pluginLoads=new Map;unknownCliOptions;deprecationWarnings;authzHooks=new WeakSet;constructor(){const e=new r(h);this.config=e.parse(),this.unknownCliOptions=e.unknownOptions,this.deprecationWarnings=e.deprecationWarnings,this.app=i(),this.app.disable("x-powered-by"),this.app.use((e,t,s)=>{const i=process.hrtime.bigint();t.setHeader("X-Content-Type-Options","nosniff"),this.stopping&&t.setHeader("Connection","close"),this.inFlight.add(t),t.once("finish",()=>{C.observe({method:e.method,route:E(e),status:String(t.statusCode)},M(i)),this.stopping&&this.server?.closeIdleConnections()}),t.once("close",()=>this.inFlight.delete(t)),s()}),this.app.use((e,t,s)=>{const i=O(e);t.setHeader("X-Request-Id",i),k({requestId:i},s)}),this.app.use(rejectEmptyMediaType),this.app.use(this.bodyParsers),this.app.use(o.json({verify:a})),this.app.use(o.urlencoded({extended:!0,verify:a})),x(this.app,this),this.logger=c(this.config);for(const e of this.deprecationWarnings)this.logger.warn(e);this.ldap=new l(this),u(this.logger),d(this.config.debug);const t=[];if(this.config.plugin){const e=this.config.plugin.find(e=>e.includes("configApi"));let s=this.config.plugin.filter(e=>!e.includes("configApi"));const i=this.logger,o=(async()=>{for(const e of T){const t=this.resolveModule(DM.moduleOf(e)),o=s.filter(e=>this.resolveModule(DM.moduleOf(e))===t);if(0!==o.length){s=s.filter(e=>!o.includes(e));for(const e of o)i.debug(`Loading ${e} in the priority pass`),await this.loadPlugin(e)}}})();t.push(o),t.push(o.then(async()=>{const e=s.map(e=>(i.debug(`Loading ${e} in the parallel batch`),this.loadPlugin(e)));await Promise.all(e)})),e&&t.push(Promise.all(t).then(()=>this.loadPlugin(e)))}this.ready=new Promise((e,s)=>{t.length>0?Promise.all(t).then(async()=>{this.setupErrorMiddleware(),this.warnUnauthenticatedRoutes(),await m(this),w(this),await this.learnAttributeTypes(),this._compositionState.composed=!0,this.reportUnknownOptions(),this.afterLoad(),e()}).catch(e=>s(new Error("Error loading plugins: "+e))):(this.setupErrorMiddleware(),this._compositionState.composed=!0,e())})}async learnAttributeTypes(){if(Object.values(this.loadedPlugins).some(e=>e.roles?.includes("authz")))try{v((await this.ldap.schemaIndex()).schema.attributeTypes)}catch(e){this.logger.warn(`Could not read the directory schema, DNs are compared with the usual attribute type names only: ${String(e)}`)}}routerStack(){const e=this.app;return(e.router??e._router)?.stack}withConfig(e){return Object.assign(Object.create(Object.getPrototypeOf(this)),this,{config:e})}reportUnknownOptions(){const e=Object.values(this.loadedPlugins).map(e=>e.constructor.optionDefinitions??{}),t=new Set(e.flatMap(e=>Object.entries(e).flatMap(([e,t])=>[e,...(t.aliases??[]).map(e=>e.replace(/^--?/,"").replace(/-/g,"_"))]))),s=[...this.unknownCliOptions.filter(e=>!t.has(e.replace(/^--?/,"").replace(/-/g,"_"))).map(e=>`option ${e}`),...n(h,process.env,e).map(e=>`environment variable ${e}`)];if(0===s.length)return;const i=`Unknown configuration: ${s.join(", ")} — no declared option reads it`;if(this.config.strict_options)throw new Error(i);this.logger.warn(i)}mountAuthDispatcher(e){const t=e.roles||[];t.includes("protect")||t.includes("logging")||this.mountAuthDispatcherNow()}mountAuthDispatcherNow(){this._authState.dispatcherMounted||(this._authState.dispatcherMounted=!0,this.app.use((e,t,s)=>{this.dispatchAuth(e,t,s)}))}registerAuthenticator(e){this.mountAuthDispatcherNow(),this.authenticators.includes(e)||this.authenticators.push(e)}registerBodyParser(e,t){this.bodyParsers.use(e,t)}dispatchAuth(e,t,s){let i=-1,o=[];for(const t of this.authenticators)for(const s of t.pathPrefixes)f(s,e.path)&&(s.length>i?(i=s.length,o=[t]):s.length!==i||o.includes(t)||o.push(t));if(i<0&&(o=this.authenticators.filter(e=>0===e.pathPrefixes.length)),0===o.length)return s();const finish=i=>{if(i>=o.length)return S(e,s);const r=o[i];if(!r.afterChain)return finish(i+1);r.afterChain(e,t,()=>finish(i+1))},r=[];e.authenticators=r;const run=s=>{if(s>=o.length)return finish(0);const i=o[s];i.authenticate(e,t,()=>{i.vouchedFor(e)&&r.push(i.name),run(s+1)})};run(0)}afterLoad(){for(const e of Object.values(this.loadedPlugins))try{e.afterLoad?.()}catch(t){this.logger.error(`Plugin ${e.name}: afterLoad failed: ${String(t)}`)}}warnUnauthenticatedRoutes(){const e=Object.values(this.loadedPlugins).filter(e=>e.roles?.includes("auth"));if(0===e.length)return[];const t=[];for(const s of e){if(!s.pathPrefixes||0===s.pathPrefixes.length)return[];t.push(...s.pathPrefixes)}const s=this.routerStack(),i=new Set;for(const e of s||[]){const t=e.route?.path;"string"==typeof t?i.add(t):Array.isArray(t)&&t.forEach(e=>"string"==typeof e&&i.add(e))}const o=[...i].filter(e=>!D.includes(e)&&!t.some(t=>e===t||e.startsWith(`${t}/`))),r=Object.values(this.loadedPlugins).some(e=>e.roles?.includes("authz"));return o.length>0&&this.logger.warn(`Authentication is restricted to ${t.join(", ")}, so these routes are served without authentication`+(r?" nor authorization":"")+`: ${o.sort().join(", ")}`),o.sort()}setupErrorMiddleware(){const e=this._errorState.handler;if(e){const t=this.routerStack();if(t){const s=t.findIndex(t=>t.handle===e);-1!==s&&t.splice(s,1)}}const handler=(e,t,s,i)=>{const{status:o,body:r}=p(e,this.config.debug);if(o<500)return this.logger.warn(`Client error ${o} in request ${t.method} ${t.path}: ${r.error}`),void(s.headersSent||s.status(o).json(r));this.logger.error(`Server error ${o} in request ${t.method} ${t.path}: ${g(e)}`,{stack:stackChain(e),url:t.url,method:t.method}),s.headersSent||s.status(o).json(r)};this._errorState.handler=handler,this.app.use(handler)}exitOnCrash(){process.on("uncaughtException",e=>{this.logger.error(`Uncaught exception: ${e.message}`,{stack:stackChain(e)}),setTimeout(()=>process.exit(1),this.config.shutdown_timeout),this.shutdown().finally(()=>process.exit(1))}),process.on("unhandledRejection",e=>{this.life.unhandledRejections++,A.inc(),this.logger.error(`Unhandled promise rejection: ${e instanceof Error?e.message:String(e)}`,{stack:stackChain(e)})})}run(){return new Promise((e,t)=>{this.server=this.app.listen(this.config.port,s=>{s?(this.logger.error(`Error starting server: ${s}`),t(s)):(this.logger.debug(`Server started on port ${this.config.port}`),e())})})}stop(){this.app.removeAllListeners(),this.server?.close(),this.logger.debug("Server stopped")}shutdown(){return this.life.shutdown??=this.letGo(),this.life.shutdown}async letGo(){const e=this.config.shutdown_timeout,t=Date.now(),s=Math.max(1e3,e-5e3);this.logger.notice(`Shutting down, ${s} ms for what is in flight`);const i=this.server;if(i){const e=new Promise(e=>i.close(()=>e()));i.closeIdleConnections();for(const e of this.inFlight)e.headersSent||e.setHeader("Connection","close");await DM.within(e,s),i.closeAllConnections()}const o=new Map;for(const[e,t]of Object.entries(this.loadedPlugins))o.set(e,Promise.resolve().then(()=>t.close?.()).catch(t=>{this.logger.warn(`${e}: close failed: ${t instanceof Error?t.message:String(t)}`)}).finally(()=>o.delete(e)));const r=Promise.all(o.values()).then(()=>this.ldap.close().catch(()=>{})),n=Math.max(1e3,e-(Date.now()-t)-1e3);await DM.within(r,n)||(this.logger.warn(`Shut down with a close still pending: ${[...o.keys()].join(", ")||"the directory connections"}`),this.ldap.close().catch(()=>{})),this.logger.notice("Shut down")}static async within(e,t){let s;const i=new Promise(e=>{s=setTimeout(()=>e(!1),t)});try{return await Promise.race([e.then(()=>!0),i])}finally{clearTimeout(s)}}shutdownOnSignals(){R.ms=this.config.shutdown_timeout,_(()=>this.shutdown())}static moduleOf(e){const t=e.indexOf(":");return-1===t?e:e.substring(0,t)}resolveModule(i){return i.startsWith("core/")?i.replace("core/",t(s(e(import.meta.url)),"..","plugins")+"/").replace(/$/,".js"):i.startsWith(".")?e(new URL(i,import.meta.url)):i}loadPlugin(e){let t,s;if(/:/.test(e)){let i=e.substring(e.indexOf(":")+1);if(e=e.substring(0,e.indexOf(":")),/:/.test(i)){t=i.substring(0,i.indexOf(":")),t||(t=void 0),i=i.substring(i.indexOf(":")+1);try{s=JSON.parse(i),"object"!=typeof s?(this.logger.error(`Overrides for plugin ${e} are not valid: ${i}`),s=void 0):this.logger.debug(`Overrides for plugin ${t||e}: ${i}`)}catch(t){this.logger.error(`Failed to parse overrides for plugin ${e}: ${t}, using ${i}`),s=void 0}}else t=i,t||(t=void 0)}else t=void 0;const i=s?void 0:`${this.resolveModule(e)}\0${t??""}`,o=void 0===i?void 0:this.pluginLoads.get(i);if(o)return this.logger.debug(`Plugin ${e} already loaded, skipping`),o;const r=this.importPlugin(e,t,s);if(void 0!==i){this.pluginLoads.set(i,r);const forget=()=>{this.pluginLoads.get(i)===r&&this.pluginLoads.delete(i)};r.then(e=>e||forget(),forget)}return r}importPlugin(e,t,s){return this.logger.debug(`Loading plugin ${e}`),e.startsWith("core/")&&(e=this.resolveModule(e)),new Promise((i,o)=>{import(e).then(async r=>{let n;if(r&&r.default&&(r=r.default),s){const e={...this.config,...s};n=new r(this.withConfig(e))}else n=new r(this);if(!n)return o(new Error(`Unable to load ${e}`));i(await this.registerPlugin(e,n,t)),this.logger.debug(`Plugin ${n.name} loaded`)}).catch(t=>o(new Error(`Failed to load plugin ${e}: ${t}`)))})}async admitToComposition(e){this.loadedPlugins[e.name]=e;try{await m(this,e)}finally{delete this.loadedPlugins[e.name]}}async registerPlugin(e,t,s){if(t.name||(t.name=e),s&&(t.name=s),this.loadedPlugins[t.name])return this.logger.warn(`Plugin ${e} not registered: the name "${t.name}" is already taken. This instance is dropped and its routes will not exist. To load the same plugin twice, give each one a name: --plugin '${e}:${t.name}2:{…}'`),!1;if(this.logger.debug(`Registering plugin ${e} as ${t.name}`),t.dependencies)for(const e in t.dependencies)this.loadedPlugins[e]||(this.logger.debug(`Plugin ${t.name} depends on ${e}, loading it first`),await this.loadPlugin(t.dependencies[e]));if(this._compositionState.composed&&await this.admitToComposition(t),t.api&&(this.mountAuthDispatcher(t),this.logger.debug(`Plugin ${t.name} has API, registering it`),await t.api(this.app),this._errorState.handler&&this.setupErrorMiddleware()),t.hooks)for(const e in t.hooks){this.logger.debug(`Plugin ${t.name} has hook ${e}, registering it`);const s=t.hooks[e];if(void 0===s)continue;if("function"!=typeof s)throw new Error(`Plugin ${t.name}: hook ${e} is invalid`);const i=e;if(j(s,t.name,e),t.roles?.includes("authz")&&L.includes(i)){const e=this.hookBus.subscribers(i),t=e.findIndex(e=>!this.authzHooks.has(e));this.hookBus.insert(i,s,t<0?e.length:t),this.authzHooks.add(s)}else this.hookBus.subscribe(i,s)}return this.loadedPlugins[t.name]=t,this.registerServices(t),!0}registerServices(e){for(const t of e.provides??[]){const s=this.serviceOwners.get(t.token);void 0===s?(this.services.set(t.token,t.service),this.serviceOwners.set(t.token,e.name)):this.logger.warn(`Plugin ${e.name}: service '${t.token.name}' is already provided by ${s}; this one is ignored`)}}}export{y as BadRequestError,DM,j as recordHookOwner,v as registerAttributeTypes};

package/dist/src/bin/index.d.ts

@@ -53,7 +53,14 @@ export declare class DM {
     /** The plugin that provided each service, for the duplicate warning. */
     private readonly serviceOwners;
     ldap: ldapActions;
-    operationSequence: number;
+    /**
+     * The next operation number, shared by the `withConfig` views. An accessor
+     * over an object because a field would be copied into each view — which
+     * would then count on its own — while an object is copied by reference.
+     */
+    private readonly _operations;
+    get operationSequence(): number;
+    set operationSequence(value: number);
     logger: winston.Logger;
     /** Authentication plugins, in registration order */
     authenticators: AuthBase[];
@@ -66,15 +73,25 @@ export declare class DM {
      * shared.
      */
     private _authState;
-    private _errorMiddlewareSetup;
+    /**
+     * The mounted error middleware, if any. In an object, as `_authState` is: a
+     * view made during loading would copy a bare `undefined` field, so a route
+     * it registers after `ready` would land behind the handler — the one place
+     * Express never routes an error to.
+     */
+    private readonly _errorState;
     /** The parsers plugins mount ahead of the global ones, see registerBodyParser */
     private readonly bodyParsers;
     /**
      * Whether the plugins of the configuration are loaded and their
      * composition checked. A plugin registered after that — a server
      * assembled by hand — is checked on its own as it arrives.
+     *
+     * In an object, as `_authState` is: a plain flag is copied into each
+     * `withConfig` view, and a view made during loading would keep `false` and
+     * let a plugin registered through it skip the composition check.
      */
-    private _composed;
+    private readonly _compositionState;
     /** Every plugin loaded and the composition checked */
     get composed(): boolean;
     /**
@@ -90,7 +107,6 @@ export declare class DM {
     get stopping(): boolean;
     /** Rejections nobody handled since the start, logged and counted */
     get unhandledRejections(): number;
-    private _errorMiddleware?;
     /**
      * The loads of `--plugin` entries without overrides, keyed by resolved
      * module and name. Regular plugins load in parallel and load their own

package/docs/README.md

@@ -34,12 +34,21 @@ 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
 
+### [Architecture](architecture/README.md)
+
+How the server is put together.
+
+- **[Overview](architecture/README.md)** - Module map, life of a request, life of a write
+- **[Decision records](architecture/adr/)** - Why the code is the way it is
+
 ### [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.
+- **[Modularization plan](development/modularization-plan.md)** - How the
+  `@ldap-rest/*` split and the remaining code-quality issues are sequenced.
 
 ## API stability
 

package/docs/architecture/README.md

@@ -0,0 +1,180 @@
+# Architecture
+
+How the server is put together, and the two paths that carry most of the
+work. Every design decision the code already embodies is recorded once, in
+[`adr/`](adr/); this page is the map and the tour.
+
+The plan that will split the repository into packages is
+[Modularization plan](../development/modularization-plan.md). That plan is a
+roadmap; this page describes the code as it is.
+
+## Module map
+
+| Path                   | Role                                                                                                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/bin/index.ts`     | `DM`: the Express app, plugin loading, the authentication dispatcher, `ready` and `stop`, `withConfig`                                                                                |
+| `src/config/`          | Command-line and environment parsing (`args.ts`), option specs (`options.ts`), the entity-schema model (`schema.ts`; the directory's own schema is `src/lib/ldap/schema.ts`)          |
+| `src/abstract/`        | `DmPlugin` base class; `LdapFlat`, the entity CRUD built on it; `TwakePlugin`                                                                                                         |
+| `src/hooks.ts`         | The hook type map: one entry per hook, with its arguments and its answer                                                                                                              |
+| `src/lib/`             | Core services: `ldapActions` and `lib/ldap/` (pool, search cache, schema), `lib/auth/`, `lib/authz/`, `lib/services/`, `lib/storage/`, `hookBus`, `requestContext`, errors, routes    |
+| `src/plugins/auth/`    | Authentication plugins, authorization plugins, and the guards that sit before them                                                                                                    |
+| `src/plugins/ldap/`    | Directory plugins: groups, organizations, entities, change detection, trash, password policy                                                                                          |
+| `src/plugins/scim/`    | The SCIM 2.0 API                                                                                                                                                                      |
+| `src/plugins/storage/` | Storage backends (`file`, `ldap`, `postgres`, `valkey`), each a `Store`                                                                                                               |
+| `src/plugins/twake/`   | Twake integrations: mail, calendar, spaces, drives, tombstones, lifecycle events                                                                                                      |
+| `src/plugins/*.ts`     | Standalone plugins: `storage` (`core/storage`, over the backends above), `static`, `weblogs`, `configApi`, `metrics`, `bcl`, and `rabbitmq` (a shared broker connection, not a store) |
+| `src/plugins/demo/`    | Example plugins                                                                                                                                                                       |
+| `src/browser/`         | Browser libraries shipped with the package                                                                                                                                            |
+| `src/logger/`          | Log formatting and levels                                                                                                                                                             |
+| `src/types/`           | Shared TypeScript declarations                                                                                                                                                        |
+
+The plugin families depend on `src/lib/` and on each other as documented in
+[dependencies](../plugin-development/dependencies.md). The dependency rules
+that the modularization will enforce are in the
+[plan](../development/modularization-plan.md#target-architecture).
+
+## Life of a request
+
+```mermaid
+flowchart TD
+    A[HTTP request] --> B[request id and log context]
+    B --> C[body parsers]
+    C --> D[protect plugins: rate limit, CrowdSec, trusted proxy]
+    D --> E[authentication dispatcher]
+    E --> F{most specific prefix}
+    F -->|one authenticator| G[vouched]
+    F -->|several on the same prefix| H[all of them, an AND]
+    H --> G
+    G --> I[runForRequest]
+    I --> J[route: checked params, query, body]
+    J --> K[ldap.forRequest or ldap.system]
+    K --> L[request hooks, authorization first]
+    L --> M[(directory)]
+    M --> N[done hooks of a write, then end hooks]
+    N --> O[onLdap* notifications]
+    J --> P[error middleware]
+```
+
+1. `DM` mounts, in this order: the request id and log context
+   (`runWithLogContext`), the media-type guard, the parsers a plugin
+   registered for its own prefix, the global JSON and form parsers (they keep
+   the raw bytes: HMAC authentication hashes them as the client signed them),
+   the health probes, the protect and logging plugins, the authentication
+   dispatcher, the plugin routes, and the error middleware, kept last.
+2. The dispatcher picks the authentication whose path prefix is the most
+   specific. Several plugins sharing that winning prefix all run, in
+   registration order, and every one must let the request through: two
+   credentials on one branch are an AND. A path nobody claims is guarded by
+   the unscoped authenticators (no prefix), if any are loaded; with none, the
+   request passes through unauthenticated, and `warnUnauthenticatedRoutes`
+   names those routes at startup.
+3. A plugin's `afterChain` runs after the whole selected chain and before any
+   route: it is the only place where a verdict can depend on several
+   authenticators without registration order deciding the answer.
+4. `runForRequest(req, next)` wraps everything downstream of a request an
+   authenticator let through — not the pass-through path, which has no
+   caller. A directory operation made there, by whatever plugin, is judged as
+   that caller even if the request object was not handed down. Hooks are the
+   exception: they run as the server (see below), and a hook acting as the
+   caller names the request it received. `ldap.system` is the explicit escape
+   anywhere else.
+5. A route declares its input schemas with `defineRoute`; the handler receives
+   checked `params`, `query` and `body`, and reaches the directory through
+   `ldap.forRequest(req)`. Work the server does for itself goes through
+   `ldap.system`.
+6. `ldapActions` raises the request hooks (authorization plugins first), makes
+   the operation, then raises the "done" and "end" hooks of a write. The next
+   section follows one.
+
+The decisions behind these steps: [authentication
+dispatch](adr/0002-authentication-dispatch.md), [authorization
+composition](adr/0003-authorization-composition.md), [fail-closed request
+context](adr/0004-fail-closed-request-context.md).
+
+## Life of a write
+
+```mermaid
+sequenceDiagram
+    participant R as route
+    participant L as ldapActions
+    participant H as plugins
+    participant D as directory
+
+    R->>L: add / modify / rename / delete
+    L->>H: request hook, chained (authorization first)
+    H-->>L: value, changed or refused
+    L->>L: drop cached reads the write changes
+    L->>D: LDAP add / modify / modifyDN / delete
+    D-->>L: result
+    L->>L: drop them again
+    L->>H: done hooks, notified
+    L->>H: end hooks, once the done hooks returned
+    H->>H: onLdapEntryChange, onLdapChange, onLdapMailChange…
+```
+
+- **Before the write.** A request hook is chained: each subscriber gets what
+  the previous one answered, and a refusal thrown by any of them stops the
+  operation. The request hooks of authorization plugins run before every
+  other subscriber's, so a caller who may not make the operation is refused
+  before a plugin judges its content.
+  [trash](adr/0007-trash-and-tombstone.md) and
+  [tombstone](adr/0007-trash-and-tombstone.md) use this point to replace a
+  delete.
+- **The write.** `ldapActions` drops the cached reads of what it is about to
+  change before the directory call and again once it returned, so a read
+  landing during the round trip cannot serve what the write replaced.
+  [Search cache](adr/0006-search-cache.md).
+- **After the write.** `ldapadddone`, `ldapmodifydone`, `ldapdeletedone` and
+  `ldaprenamedone` are notified, not awaited. `ldapaddafter` is awaited
+  within the request, for what must follow an add, such as provisioning the
+  account the entry describes. Once the done subscribers returned, the
+  matching `ldapmodifyend`, `ldapdeleteend` or `ldaprenameend` fires, whether
+  the write landed, was refused or was taken out of the request.
+- **Derived notifications.** `core/ldap/onChange` reads the entry before and
+  after the write and raises `onLdapEntryChange`, then the attribute-specific
+  ones (`onLdapMailChange`, `onLdapQuotaChange`, …). A delete fires
+  `onLdapEntryChange`, `onLdapChange` and `onLdapMailChange` only.
+- **Contract.** [Hook contract](adr/0005-hook-contract.md), and the reference
+  of every hook in [hooks](../plugin-development/hooks.md). Subscribers run as
+  the server, outside the request that raised the hook; one that acts as the
+  caller names the request in its arguments.
+
+## Startup
+
+The configuration is parsed from the command line and `DM_*` variables, then
+`DM` loads the plugins: `src/plugins/priority.json` first, one at a time in
+its order, then the rest in parallel. Once every load settled, the server
+checks the authorization composition, learns the directory's attribute types
+when an authorization plugin is loaded, reports unknown options and runs
+`afterLoad`. `DM.ready` resolves then, and rejects if a plugin failed to load;
+the CLI opens the port after it. An embedding host may register plugins after
+`ready`, and each registration is checked against the composition too.
+`warnUnauthenticatedRoutes` stays silent when no authentication plugin is
+loaded; the enforcement check says once whether that is an open server or a
+configuration to refuse.
+
+[Plugin load order](adr/0001-plugin-load-order.md),
+[server views](adr/0008-withconfig-views.md).
+
+## Decision records
+
+| Record                                          | Decision                                                                                |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [0001](adr/0001-plugin-load-order.md)           | Plugins load priority-first, then in parallel; dependencies load on demand              |
+| [0002](adr/0002-authentication-dispatch.md)     | The most specific authentication prefix wins; several on one prefix are an AND          |
+| [0003](adr/0003-authorization-composition.md)   | Two authorization models judging the same requests are refused unless made deliberate   |
+| [0004](adr/0004-fail-closed-request-context.md) | Directory operations inherit the request being served; `ldap.system` is the escape      |
+| [0005](adr/0005-hook-contract.md)               | Chained hooks transform and refuse; notified hooks observe, outside the request         |
+| [0006](adr/0006-search-cache.md)                | The search cache is off by default and only the process's own writes invalidate it      |
+| [0007](adr/0007-trash-and-tombstone.md)         | A delete becomes a move to trash or a tombstone, never a loss                           |
+| [0008](adr/0008-withconfig-views.md)            | A plugin with overrides sees a server view that shares everything but the configuration |
+
+## Checking the comments
+
+`npm run check:comments` (`scripts/check-comments.sh`) refuses new comments in
+`src/` that cite an issue number, narrate history ("used to", "since 1.2") or
+otherwise carry rationale. The rationale belongs in a decision record; the
+comment points at it. The accepted set is `scripts/comment-baseline.txt`, and
+it may only shrink: removing a comment is fine, adding one fails the check.
+`sh scripts/check-comments.sh --update` rewrites the baseline from the current
+tree when a change removes one.

package/docs/architecture/adr/0001-plugin-load-order.md

@@ -0,0 +1,50 @@
+# 0001 — Plugin load order
+
+## Context
+
+Plugins are listed with `--plugin`, in the order the administrator writes
+them, and a plugin may declare `dependencies` naming modules that must be
+registered before it. Some plugins cannot simply be imported in parallel with
+the rest: a guard whose Express middleware must sit ahead of the routes it
+protects, an access log that must see every request, an authenticator or URL
+gate other plugins must find registered when they register. Import order in
+the parallel batch is the order the imports happen to complete, which is not a
+configuration.
+
+## Decision
+
+`src/plugins/priority.json` lists the modules loaded first. That pass is
+sequential, in the file's order, and every instance of a priority module is
+loaded there, in configuration order — matching is on the module, not on the
+whole `--plugin` entry, so a named instance (`module:name:{…}`) keeps its
+rank. The remaining entries load in parallel. A declared dependency is loaded
+on demand when the plugin that needs it registers. A module requested twice
+under the same name without overrides is loaded once; a second instance needs
+its own name. Two plugins with the same instance name are refused, and the
+second is dropped with a warning. `configApi` loads last.
+
+The list holds four kinds of plugin: the guards whose middleware must run
+before the routes (`trustedProxy`, `crowdsec`, `rateLimit`), the access log
+that must see every request (`weblogs`), the authenticators the dispatcher and
+the authorization plugins naming them have to find registered (`token`,
+`fake`, `llng`, `openidconnect`), and the URL gate whose rules must exist
+before the routes they judge (`authzPerRoute`). `core/storage` is there
+because others must find it registered when they register.
+
+Hooks run in load order, except the request hooks of authorization plugins,
+which run before every other subscriber's.
+
+## Consequences
+
+- A plugin whose middleware must precede routes has to be in
+  `priority.json`; being written first in the configuration is not enough
+  once the parallel batch starts.
+- The relative order of two plugins that are neither priority nor linked by a
+  dependency is not defined, and no plugin may rely on it.
+- Adding a module to the priority list changes the order for every
+  deployment, so the list stays short.
+- An instance named with overrides loads at the rank of its module but keeps
+  its own configuration through a [server view](0008-withconfig-views.md).
+
+See [dependencies](../../plugin-development/dependencies.md) and
+`src/bin/index.ts`.

package/docs/architecture/adr/0002-authentication-dispatch.md

@@ -0,0 +1,43 @@
+# 0002 — Authentication dispatch
+
+## Context
+
+One server can host populations that authenticate differently: administrators
+behind a token, users behind OpenID Connect, machine clients behind HMAC. An
+authentication plugin declares the path prefixes it claims. A request must run
+the authentication that owns its path, and only that one: running two
+unrelated authenticators on one request composes as an AND that no credential
+can satisfy. A request no plugin claims must not silently become open without
+saying so.
+
+## Decision
+
+`DM` mounts one dispatcher layer, once, at the boundary between the protection
+plugins and the routes. For each request it selects the plugins whose prefix
+is the longest match. Several plugins sharing that winning prefix all run, in
+registration order, and every one must let the request through. When no
+plugin claims the path, the unscoped plugins (no prefix) run; when there is
+none, the request passes through unauthenticated, outside any request
+context. A plugin's `afterChain` runs after the whole chain and before the
+route. `runForRequest` then wraps everything downstream of a request an
+authenticator let through, and the dispatcher records which plugins vouched
+for the request in `req.authenticators`.
+
+`warnUnauthenticatedRoutes` lists, at startup, the routes that no
+authentication plugin covers. An unscoped authenticator guards everything and
+silences the warning.
+
+## Consequences
+
+- Two authenticators on one prefix require both credentials. That is
+  legitimate — a session and a token — but it fails closed when accidental.
+- Scoping authentication to a prefix opens every route outside it; the
+  startup warning is the only signal, and it names the routes.
+- `afterChain` is the only hook that sees all the selected authenticators'
+  verdicts, so an answer that depends on several of them belongs there, not
+  in a plugin's own middleware.
+- An authorization plugin can tell whose request it judges from
+  `req.authenticators`; see
+  [authorization composition](0003-authorization-composition.md).
+
+See `src/bin/index.ts` (`dispatchAuth`) and `src/lib/auth/base.ts`.

package/docs/architecture/adr/0003-authorization-composition.md

@@ -0,0 +1,59 @@
+# 0003 — Authorization composition
+
+## Context
+
+Every plugin that judges directory operations registers the same request
+hooks (`ldapsearchrequest`, `ldapaddrequest`, `ldapmodifyrequest`,
+`ldapdeleterequest`, `ldaprenamerequest`). Chained hooks run their
+subscribers in order and stop at the first refusal, so two loaded
+authorization plugins compose as an AND: the first to refuse answers. That
+rule is sound when it is meant. It is a refusal nobody can explain when it is
+not: `authzPerBranch` next to `authzDynamic` judges a machine token by a
+branch configuration written for administrators and refuses a write the
+token's ACLs grant.
+
+## Decision
+
+A plugin with the `authz` role that registers LDAP hooks is a _judge_. It
+judges the requests authenticated by the plugins named in `--authz-for`, or
+everyone by default. A plugin that authenticates as well judges only its own
+requests: its hooks read the credential it verified.
+
+`assertAuthzComposition` runs once every configured plugin is loaded, and
+again for each plugin registered later. It refuses:
+
+- an `authz_for` naming a plugin that is not a loaded authenticator — the
+  plugin would judge nobody. A server-wide `--authz-for` that no loaded plugin
+  reads only warns, as does an `authz_for` on a plugin that also
+  authenticates;
+- two judges whose populations overlap on an authenticator — the same one, or
+  one of them judging everyone — unless `--authz-combine` makes the AND
+  deliberate.
+
+Two judges whose authenticators can run on the same prefix, without sharing an
+authenticator name, are reported, not refused: asking for two credentials is
+already a decision, and a request carrying both is judged by both. A judge on
+`authzPerRoute` gates URLs and registers no LDAP hook, so it is not part of
+this AND — route plus branch is a documented combination.
+
+The request hooks of judges run before every other plugin's request hook and
+`ldapsearchfilter` keeps the load order. All the LDAP hooks compose as an
+AND, including the filters: two filters narrow the result twice.
+
+## Consequences
+
+- A deployment with two branch models on the same population no longer starts
+  unless it says `--authz-combine`; the error names both plugins.
+- Naming authenticators in `--authz-for` requires stable instance names, so
+  the configuration that scopes authentication and the one that scopes
+  authorization must agree.
+- A plugin registered by an embedding host is checked before its routes and
+  hooks exist, so a refused plugin leaves nothing behind.
+- Judges run first, in their load order. The chain stops at the first refusal,
+  so a judge after a refusing one does not run; the refusal is the answer.
+  No judge is skipped while the request is still allowed.
+- A judge that also authenticates judges only its own requests; a request it
+  did not vouch for passes its hooks untouched, because the absence of its
+  credential is not a refusal it makes.
+
+See `src/lib/authz/composition.ts` and `src/config/args.ts`.

package/docs/architecture/adr/0004-fail-closed-request-context.md

@@ -0,0 +1,45 @@
+# 0004 — Fail-closed request context
+
+## Context
+
+An authorization judge decides from the request (`req.user`, its
+authenticators, its path). But a directory operation is often made deep in a
+plugin that never received the request: a provisioning step incremented from a
+hook, a consistency repair, a route helper that searches before it writes.
+Passing the request down every call is easy to forget, and a forgotten request
+used to mean an operation nobody judged — a hole that is invisible until
+someone writes through it.
+
+## Decision
+
+The authentication dispatcher runs everything downstream of an authenticated
+request inside `runForRequest(req, next)`, an `AsyncLocalStorage`. Every
+directory operation defaults to `currentRequest()`, so a plugin that forgets
+the request still gets the caller's identity and is judged as them. Operations
+the server makes for itself run inside `outsideRequest()`, which `ldap.system`
+uses: it is the explicit escape from judgement, not a default.
+
+The log context is a second `AsyncLocalStorage`, kept apart: a line written as
+the server, outside the request, still names the request that made the server
+act. `outsideAnyRequest()` leaves both, for work that outlives a request (a
+pooled connection, a process-wide client).
+
+Hooks are the one place that deliberately leaves the context: the bus runs
+every subscriber inside `outsideRequest()`, so a hook's own writes are the
+server's and not the caller's. A hook that judges or acts for the caller has
+the request in its arguments and names it.
+
+## Consequences
+
+- A plugin that means to act as the server must say so with `ldap.system`;
+  forgetting the request fails closed instead of opening a hole.
+- A test that calls a plugin's directory operations directly must wrap them in
+  `runForRequest` to reproduce what the server does, or get the unjudged
+  behaviour of `ldap.system`.
+- Asynchronous work started inside the request inherits it, so a background
+  task that should not act as the caller has to leave the context first.
+- Errors and logging inherit the request id, which makes a write traceable to
+  the request that caused it.
+
+See `src/lib/requestContext.ts` and `src/lib/ldapActions.ts`
+(`forRequest`, `system`, `currentRequest`).

package/docs/architecture/adr/0005-hook-contract.md

@@ -0,0 +1,54 @@
+# 0005 — Hook contract
+
+## Context
+
+Plugins have to talk to each other without importing each other. A refusal
+has to be able to stop a write; a notification has to be able to run after the
+write, without holding the request open or turning a subscriber's failure into
+the caller's failure. One kind of hook cannot do both.
+
+## Decision
+
+There are two kinds, told apart by what a subscriber answers, and a third
+notification mode:
+
+- **Chained** (`chain(name, value)`). The value goes from one subscriber to
+  the next; the last answer is the result. A subscriber that throws stops the
+  chain and the error travels to the caller: a refusal is a refusal. Several
+  arguments are passed as one tuple.
+- **Notified** (`notify(name, ...args)`). Subscribers run one after the other,
+  outside the request that caused the write, and are not awaited. A failing
+  subscriber is logged with its plugin and hook, counted in the hook failure
+  metrics, and the next one still runs.
+- **Awaited notification** (`notifyAndWait`). As `notify`, but the caller waits
+  for the subscribers. A failure is still logged and swallowed.
+- **Strict notification** (`notifyStrict`) for the rare failure that is part
+  of the answer. Every subscriber runs; the first failure is raised once they
+  all returned.
+
+Every hook is declared in `src/hooks.ts` with its arguments and its answer. A
+plugin subscribing to an undeclared hook does not compile, and `npm run
+check:hooks` keeps the documentation in step. Notified hooks take their
+arguments one by one; chained hooks take one value, a tuple when there are
+several.
+
+The request hooks of authorization plugins run first, in load order. The
+other hooks run in plugin load order.
+
+## Consequences
+
+- A notified hook cannot refuse a write; a plugin that needs to refuse
+  subscribes to the request hook instead.
+- A chained subscriber must answer the value it was given, changed or not: an
+  `undefined` answer becomes the next subscriber's input.
+- A subscriber of a notified hook written `([dn, entry], ctx) => …` compiles
+  without annotation — its parameter takes the declared type, a `string`, and
+  a string can be destructured — and then reads the first character of the
+  DN. The documentation repeats the shape of each hook for this reason.
+- A "done" hook fires once the operation is over, including a modify that had
+  nothing to apply; a write refused by a request hook or by the directory
+  never reaches it. The "end" hook fires all the same, once the done
+  subscribers returned. Keying state by the operation number is what tells
+  two writes of one DN apart.
+
+See [hooks](../../plugin-development/hooks.md) and `src/lib/hookBus.ts`.

package/docs/architecture/adr/0006-search-cache.md

@@ -0,0 +1,49 @@
+# 0006 — Search cache
+
+## Context
+
+Reading one entry by DN is the most frequent operation a route makes: before a
+write, before an authorization decision, to render a page. A directory round
+trip per read is measurable, and a cache in front of it is easy to add and
+hard to keep honest. Serving a stale entry after a write is worse than the
+round trip.
+
+## Decision
+
+`SearchCache` caches non-paged, base-scope searches — single-entry lookups by
+DN, with whatever filter — keyed by base, scope, filter, attributes, options
+and values mode, in an LRU bounded by `--ldap-cache-max`. It is **off by
+default** (`--ldap-cache-ttl=0`): no deployment has run with it on, and
+turning it on for everyone would be a silent behaviour change.
+
+`ldapActions` drops, around every write it makes through this process:
+
+- the reads of the entry written and of its subtree (a rename or a move
+  re-parents a whole branch);
+- the `memberOf` of the members a group change adds or removes;
+- the reads of entries naming the entry renamed or deleted, because the
+  directory's `memberof` and `refint` overlays rewrite them.
+
+Entries are dropped before the directory call as well as after it, and a
+generation counter stops a read that started before the write from storing
+its stale answer afterwards. DNs are compared the way the directory does:
+case, spacing, escapes, aliases and multi-valued RDN order do not matter.
+
+Writes made elsewhere — another replica, an LSC synchronisation, a hand-run
+`ldapmodify` — do not invalidate anything. Each process caches on its own.
+
+## Consequences
+
+- Enable the cache only when this service is the only writer, or when serving
+  an entry up to `--ldap-cache-ttl` seconds old is acceptable.
+- A subtree or one-level read, or a paged search, is never cached; the cache
+  does not accelerate listings. A base-scope read with a filter is cached,
+  keyed by that filter.
+- The cache does not lift a miss: a read of an absent DN throws and caches
+  nothing.
+- The invalidation rules follow the overlays this project documents
+  (`memberof`, `refint`); a deployment with an overlay that rewrites other
+  entries must accept a miss or leave the cache off.
+
+See [configuration](../../usage/configuration.md#the-search-cache) and
+`src/lib/ldap/searchCache.ts`.

package/docs/architecture/adr/0007-trash-and-tombstone.md

@@ -0,0 +1,69 @@
+# 0007 — Trash and tombstone
+
+## Context
+
+Deleting an entry destroys the identifiers it held: a mail address, a login, a
+DN. An administrator who deletes the wrong account cannot undo it, and a
+deleted account's address can be taken by a new one immediately — which, for a
+mail system, means the new account receives the old one's mail. The directory
+has no undelete of its own.
+
+## Decision
+
+Two plugins answer a delete at the `ldapdeleterequest` hook, and a deployment
+picks one per branch:
+
+- **`core/ldap/trash`** moves the entry, by an atomic `modifyDN`, to a trash
+  branch under `--trash-base`, overwriting an earlier entry with the same RDN
+  there; unless `--trash-add-metadata=false`, it then replaces `description`
+  with the deletion date and the original DN, a failure there being logged
+  and not fatal. The native delete is cancelled. `--trash-watched-bases`
+  selects the branches; an empty list watches every branch.
+- **`core/twake/tombstone`** keeps the entry in place: one modify sets the
+  deleted attribute and the lock, the deletion date and the reason when their
+  attributes are configured, and removes the attributes the deployment names.
+  The identifier is reserved until an operator erases the tombstone, once the
+  deletion is old enough or immediately when forced. Erasing removes the entry
+  and its group memberships and announces nothing.
+
+The tombstone moves itself last in the `ldapdeleterequest` and
+`ldapaddrequest` chains (`hookBus.toLast`), so every plugin that may refuse
+has judged. The trash does not: it runs in load order, after the authorization
+judges but possibly before another plugin that can refuse a delete
+(`organizations`, `enterpriseRules`, `james`). A plugin that refuses a delete
+and loads after the trash refuses one that has already been moved. The
+tombstone is written by the server, not as the caller: the caller's delete
+right is what was judged.
+
+SCIM treats a tombstone as gone: its reads carry a not-deleted filter, so
+reads answer 404 and lists omit it; a create with the same identity erases
+the tombstone and creates a new entry. A non-SCIM delete of an existing
+tombstone writes nothing and fires `twakedeletionreplay`, so lifecycle events
+can replay a lost deletion. A SCIM DELETE never gets there: its existence
+check hides the tombstone and answers 404.
+
+The server refuses to start when the tombstone is loaded beside the trash and
+any watched branch overlaps a `--twake-tombstone-dn` pattern: the trash would
+move the entry before the tombstone saw the delete, and no tombstone would be
+written. An empty `--trash-watched-bases` watches every branch, so it overlaps
+any pattern and refuses too.
+
+## Consequences
+
+- A delete is no longer a delete. Code that lists a branch sees what the
+  trash or the tombstone left there, filtered by the plugin that owns the
+  branch.
+- Trash and tombstone cannot watch the same branch; the startup check names
+  the overlap.
+- A deployment that loads the trash must load it before the plugins that can
+  refuse a delete, or accept that a refusal can come after the entry moved.
+- A tombstone cannot be restored: clearing its deleted attribute by hand is
+  not a supported operation.
+- Trash moves the entry, so its DN changes and references to it are not
+  rewritten by the move beyond what the directory's `refint` overlay does.
+- Tombstones are erased by an explicit operator action, so a retention policy
+  has to run it.
+
+See [tombstone](../../usage/plugins/integrations/tombstone.md), the plugin
+list in [plugins](../../usage/plugins/README.md), and
+`src/plugins/ldap/trash.ts`, `src/plugins/twake/tombstone.ts`.

package/docs/architecture/adr/0008-withconfig-views.md

@@ -0,0 +1,58 @@
+# 0008 — Server views for plugins with overrides
+
+## Context
+
+The same plugin module can be loaded several times with different settings:
+`--plugin 'core/auth/token:admins:{…}'` and
+`--plugin 'core/auth/token:users:{…}'`. The plugin constructor receives the
+server, and reads its options from `this.server.config` and `this.config`.
+Those instances must see their own configuration while acting on the one
+server: the same Express app, the same hooks, the same LDAP connection and
+the same plugin registry. A second `DM` would be a second server.
+
+## Decision
+
+`DM.withConfig(config)` returns a view of the server built with
+`Object.create(Object.getPrototypeOf(this))` and `Object.assign(…, this,
+{ config })`. The own properties that hold objects — the app, the hooks, the
+LDAP actions, the plugin registry, the authenticators — are shared by
+reference. The configuration is `{ ...this.config, ...overrides }`, a shallow
+copy: overridden top-level keys are the plugin's alone, nested objects and
+arrays are still shared with the server. The loader constructs a plugin with
+overrides on such a view.
+
+A primitive field would be copied by value into every view, so state the views
+must share lives in an object: the operation counter (`_operations`, read
+through the `operationSequence` accessor) and the composition flag
+(`_compositionState`), as the dispatcher's own state does (`_authState`). A
+view created while the plugins load therefore sees the composition once the
+server has checked it.
+
+The copy is built on the prototype rather than by spreading `{...this}`,
+which copies own properties and leaves the methods behind: a plugin calling
+`this.server.anything()` would throw, and only when configured with
+overrides.
+
+## Consequences
+
+- A plugin loaded with overrides cannot change the server's configuration for
+  anyone else; mutating `this.config` affects its view alone, at the top
+  level.
+- Primitive fields are copied by value, not shared: what must be shared is
+  held in an object, as the operation counter and the composition flag are.
+  A plugin registered after `ready` through a view created while loading is
+  therefore checked against the composition like any other (before [#625] and
+  [#626], the counter and the flag were primitives, and neither held).
+- An own property added to the server after the view was created is not
+  visible to that view. State that must be shared has to live in an object
+  that already exists when the view is made.
+- A plugin that closes over `this.server` keeps the view for its lifetime,
+  which is the point: its options stay its own.
+- Tests may call `withConfig` to exercise option-dependent behaviour without
+  building a second server.
+
+See `src/bin/index.ts` (`withConfig`, `importPlugin`) and
+[plugin options](../../plugin-development/options.md).
+
+[#625]: https://github.com/linagora/ldap-rest/issues/625
+[#626]: https://github.com/linagora/ldap-rest/issues/626

package/docs/development/contracts.md

@@ -31,10 +31,15 @@ contract shows up as a diff instead of a surprise after the release:
 - `openapi.json` is the REST API document the published reference is built
   from. Regenerate it with `npm run generate:openapi`; `npm run check:openapi`
   fails when it is stale.
-
-The plugin types have no snapshot yet: one api-extractor report per sub-path
-export is a change of its own. Until it lands, a change to an exported type is
-reviewed by hand.
+- `etc/api/*.api.md` are the API Extractor reports of the five entry points
+  #595 covers first — `ldap-rest`, `./plugin`, `./hooks`, `./ldapactions` and
+  `./expressformatedresponses` — one file per sub-path. Regenerate them with
+  `npm run snapshot:api`; `npm run check:api`, part of `npm run check`, fails
+  when one is stale. A report lists what the entry exports and the shapes of
+  the types those exports reference, including the types the entry does not
+  export itself, so a change to `RouteDefinition` or `OptionSet` shows up even
+  though a plugin cannot name them. The 66 `./plugin-*` entries come with the
+  modularization, see [the plan](modularization-plan.md).
 
 The snapshot records what the parser reads. A narrowed `choices` list, a
 raised `min` or a lowered `max` is checked when a plugin reads its options,
@@ -59,8 +64,13 @@ that becomes required, a response that may now be null, changed security
 requirements, a removed union variant, a value an alternative of the type
 closes with an enum or a `const` where the type used to accept any, an
 untyped request value that becomes a union, an `allOf` that adds a
-constraint, or — once the plugin snapshot exists — a removed export or a
-narrowed signature. Renaming an option is a deprecation, not a removal, as
+constraint, or a removed declaration in `etc/api/` that a plugin can name —
+the exported one, or a member of an exported namespace. Renaming a type only
+reachable through a signature is not a break: nobody can write its name, and
+the declarations that use it are reported as changed. A changed declaration is
+printed for review and does not fail the job yet: telling an added optional
+member from a narrowed union needs more than a line diff, and comes with the
+`./plugin-*` reports. Renaming an option is a deprecation, not a removal, as
 long as the old CLI name and environment variable stay in its `aliases` and
 `envAliases`. Adding a union variant, a field or an optional parameter is
 additive, and so is a request union with an alternative that still accepts

package/docs/development/modularization-plan.md

@@ -0,0 +1,197 @@
+# Modularization plan
+
+How the remaining architecture work is sequenced: [#397] and the five
+`code-quality` issues that depend on it or prepare it. The plan is a roadmap,
+not a contract; update it as the work lands.
+
+## Open issues
+
+| Issue  | Subject                                                                             | Role                          | Size   |
+| ------ | ----------------------------------------------------------------------------------- | ----------------------------- | ------ |
+| [#397] | Split the repository into `@ldap-rest/*` modules                                    | Final step                    | Major  |
+| [#593] | Finish the plugin service migration: entity registry, call sites, family boundaries | Prerequisite of #397          | Large  |
+| [#594] | Finish the `ldapActions` split: operation pipeline and façade                       | Prerequisite of #397          | Medium |
+| [#595] | Snapshot the plugin API types and gate changes                                      | Safety net, start before #397 | Medium |
+| [#549] | Architecture pages, decision records, comment check                                 | Independent, start early      | Medium |
+| [#603] | Enable the type-checked ESLint rules the test block leaves out                      | Independent, quick win        | Small  |
+
+[#397] is still in the `2.0.0` milestone, which is released. Retarget it to a
+2.x epic or to 3.0.0 once the compatibility decision below is made. [#593] and
+[#594] are labelled `Minor`/`backlog` but are the real prerequisites of
+[#397]; promote them to the same milestone.
+
+## What blocks #397 today
+
+The core still imports plugin code:
+
+- `src/config/args.ts` imports the option sets of every plugin family.
+- `src/bin/index.ts` imports `src/plugins/priority.json`.
+- `src/hooks.ts` imports `ChangesToNotify` from
+  `src/plugins/ldap/onChange.ts` and the SCIM types from
+  `src/plugins/scim/types.ts`.
+- `src/abstract/ldapFlat.ts` reads `server.loadedPlugins` and uses
+  `requirePlugin`.
+- `src/lib/ldapActions.ts` is 1,375 lines; `src/lib/ldap/operations.ts` does
+  not exist.
+- The single package generates 66 `./plugin-*` exports from
+  `rollup.config.mjs`, with no npm workspaces.
+
+Between plugin families the coupling is smaller: only the Twake plugins import
+`ldap`/`scim` (15 imports), plus `TwakeGroups extends LdapGroups`.
+
+## Target architecture
+
+An npm workspaces monorepo with an umbrella package that preserves the public
+API:
+
+```text
+packages/
+  core/                 @ldap-rest/core
+  plugin-auth/          @ldap-rest/plugin-auth
+  plugin-ldap/          @ldap-rest/plugin-ldap
+  plugin-scim/          @ldap-rest/plugin-scim
+  plugin-storage/       @ldap-rest/plugin-storage
+  plugin-twake/         @ldap-rest/plugin-twake
+  plugin-misc/          @ldap-rest/plugin-misc
+  browser/              @ldap-rest/browser
+  schemas/              @ldap-rest/schemas
+  ldap-rest/            umbrella package (CLI and re-exports)
+```
+
+Rules:
+
+- `core` depends on no family; a family depends on no other family. Cross-family
+  needs go through services (`src/lib/services`) or hooks.
+- `TwakeGroups extends LdapGroups` is either the one documented exception or
+  the shared base moves to `core`.
+- `ldap-rest` stays the entry package: it depends on every package, keeps the
+  CLI and the `core/…` namespace, and re-exports the former sub-paths
+  (`ldap-rest/plugin-auth-authzlinid1`, …). The split is therefore not breaking
+  for users.
+- The core parser accepts an injected `OptionSet`; the umbrella composes the
+  option sets of every family. `Config` may stay a type-only aggregate in
+  `core`, but runtime option imports leave the core.
+- Each package builds on its own with a shared configuration; the umbrella
+  re-exports. The Twake-specific `bin/` scripts move to their package or to a
+  `@ldap-rest/cli` package.
+
+A package per plugin (`@ldap-rest/authz-linid1`, …) is possible, but start with
+families and extract optional plugins individually later. Otherwise the first
+day costs 66 packages and 66 release cycles.
+
+## Phases
+
+### Phase 0 — Guardrails and quick wins
+
+1. [#603]: enable the type-checked rules on `test/**/*.ts`, fix the 31
+   `no-floating-promises` and 24 `await-thenable` reports, add the block to CI.
+2. [#549], part 1: `docs/architecture/README.md` (module map, life of a
+   request, life of a write) and the decision records for the decisions already
+   in place. Add `scripts/check-comments.sh` with a baseline that may only
+   shrink. The GitHub ruleset change can land separately.
+3. [#595], part 1: `@microsoft/api-extractor` on the five main entry points
+   (`ldap-rest`, `./plugin`, `./hooks`, `./ldapactions`,
+   `./expressformatedresponses`), reports under `etc/api/`, wired into the
+   `contracts` job. The 66 `./plugin-*` entries wait for phase 3.
+
+Outcome: CI catches regressions, the current architecture is documented, and
+the public types have a baseline.
+
+### Phase 1 — Decouple the core
+
+1. [#593]:
+   - typed entity registry replacing the six hand-written loops;
+   - `GroupsApi`, `OrganizationsApi`, `TrashApi`, `PasswordPolicyApi`,
+     `TwakeGroupsApi`, `AuthenticatorsInfo` service interfaces;
+   - replace the 68 `loadedPlugins` reads and the 17 `requirePlugin` uses;
+   - move `ChangesToNotify` out of `plugins/ldap/onChange.ts` and the SCIM
+     types out of `plugins/scim/` into `src/lib/`;
+   - ESLint: forbid `loadedPlugins` under `src/plugins/**` and imports between
+     plugin families.
+2. [#594]: extract the operation pipeline into `src/lib/ldap/operations.ts`,
+   bring `ldapActions.ts` under 400 lines, add the file-size test, move the
+   ESLint exemption, add the type test on `ldap-rest/ldapactions`.
+3. Options refactor (needs its own issue): split `src/config/args.ts` into core
+   options and per-family option sets; let the parser/`DM` accept an
+   `OptionSet`; move `priority.json` into the core or make it a parameter.
+
+Outcome: `src/hooks.ts` imports no plugin, the core reads no `loadedPlugins`,
+families do not import each other, and `ldapActions` is a stable façade.
+
+### Phase 2 — Workspaces and extraction
+
+1. Set up npm workspaces, `packages/`, a shared `tsconfig` and per-package
+   builds.
+2. Extract `@ldap-rest/core` first, with the `ldap-rest` umbrella depending on
+   it and re-exporting the existing entry points.
+3. Extract the families in dependency order: storage → auth → ldap → scim →
+   twake → misc.
+4. Extract `browser` and `schemas`.
+5. After each step: `npm run test:dev`, `npm run check`,
+   `npm run check:openapi`, `npm run check:options`, and the `contracts` job.
+6. Update the Dockerfile, the `bin/` scripts, the examples and the docs.
+
+Outcome: a modular repository, with `ldap-rest` still installable and
+compatible.
+
+### Phase 3 — Contracts and finalization
+
+1. [#595], part 2: one api-extractor report per sub-path, including the
+   `./plugin-*` entries, and non-additive diffs refused by `contracts`.
+2. [#549], part 2: the modularization decision record, a shrinking comment
+   baseline, and the `require_code_owner_review` ruleset.
+3. Publish the scoped packages and document the deprecation policy for the
+   former sub-paths.
+4. Close [#397].
+
+## Branch strategy
+
+Phase 0 lands on `master`: it is non-breaking, and #603 fixes test bugs that
+matter to the default branch too. Merge `master` into `v3.0` before phase 1,
+so the 3.0 work starts from a green, guarded base. Phases 1 to 3 land on
+`v3.0`.
+
+## Order
+
+```text
+#603 ───────────────┐
+#549 (part 1) ──────┼──> Phase 0
+#595 (part 1) ──────┘
+                     │
+#593 ────────────────┼──> Phase 1 ──> #397 (Phase 2) ──> #595/#549 (part 2)
+#594 ────────────────┘
+```
+
+[#603] and [#549] part 1 can start in parallel. [#595] part 1 is a short
+spike. [#593] and [#594] can then run in parallel, but both touch the core:
+freeze new cross-family imports and new `loadedPlugins` reads from the start of
+phase 1.
+
+## Decisions to make
+
+1. **Granularity**: packages per family (recommended) or one package per plugin
+   from the start?
+2. **Versioning**: a non-breaking internal split in 2.x with the umbrella
+   (recommended), or 3.0.0 with the former sub-paths removed?
+3. **`TwakeGroups extends LdapGroups`**: documented exception, or move the
+   shared base into `core`?
+4. **`Config` type**: type-only aggregate in `core` (recommended to start), or
+   split per package with declaration merging?
+5. **Build**: Rollup per package (consistent with today) or `tsc` with
+   generated exports?
+
+## First actions
+
+1. Retarget [#397] and add the package map and the dependency rule to it.
+2. Open sub-issues for [#593] and [#594]; both are too large for one pull
+   request.
+3. Start [#603] and [#549] part 1 in parallel.
+4. Spike [#595] on the five main entry points.
+5. Then [#593]/[#594], then the package extraction.
+
+[#397]: https://github.com/linagora/ldap-rest/issues/397
+[#549]: https://github.com/linagora/ldap-rest/issues/549
+[#593]: https://github.com/linagora/ldap-rest/issues/593
+[#594]: https://github.com/linagora/ldap-rest/issues/594
+[#595]: https://github.com/linagora/ldap-rest/issues/595
+[#603]: https://github.com/linagora/ldap-rest/issues/603

package/docs/plugin-development/hooks.md

@@ -24,7 +24,8 @@ subscriber answers:
 A chained hook is handed its arguments as one value, a tuple when it has
 several. A notified hook is handed them one by one: its subscriber is
 `(dn, entry, context) => …`, never `([dn, entry], context) => …` — that form
-still compiles, the parameters being bivariant, but then reads the DN's first
+still compiles without annotation, since its parameter takes the declared
+`string` and a string can be destructured, but then reads the DN's first
 character as the DN.
 
 - **Chained.** The value goes from one subscriber to the next, each getting

package/docs/usage/operations.md

@@ -55,9 +55,12 @@ changes nothing.
 
 The image is built in two stages: a builder produces the package and installs
 its production dependencies, the runtime stage copies them and carries no
-compiler nor package manager cache. Its base image is pinned by digest in
-`scripts/buildDockerfile.ts`, so the image built is the one reviewed even if
-the tag moves; the digest follows the tag it names, taken from the
+compiler nor package manager cache. The runtime stage upgrades the Alpine
+packages of its base image with `apk upgrade --no-cache`, so a security fix
+published after the base image was built still reaches the image: two builds
+from the same digest may differ in those packages. Its base image is pinned by
+digest in `scripts/buildDockerfile.ts`, so the image built is the one reviewed
+even if the tag moves; the digest follows the tag it names, taken from the
 [Docker Hub tag page](https://hub.docker.com/_/node/tags?name=25-alpine) and
 updated by hand with it. Dependabot ignores the image: it would open a change
 to the generated `Dockerfile`, which the drift check refuses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -806,7 +806,9 @@
     "build:pages": "tsx scripts/build-pages.ts",
     "build:prod": "npm run clean && NODE_ENV=production rollup -c && npm run build:browser && node scripts/moveBrowserLibs.mjs && npm run build:dockerfile",
     "build:watch": "rollup -c --watch",
-    "check": "npm run check:ts && npm run lint && npm run format:check && npm run check:hooks && npm run check:no-client-values && npm run check:openapi && npm run check:options",
+    "check": "npm run check:ts && npm run lint && npm run format:check && npm run check:hooks && npm run check:comments && npm run check:no-client-values && npm run check:api && npm run check:openapi && npm run check:options",
+    "check:api": "tsx scripts/api-snapshot.ts --check",
+    "check:comments": "sh scripts/check-comments.sh",
     "check:hooks": "tsx scripts/hooks-doc.ts",
     "check:no-client-values": "sh scripts/check-no-client-values.sh",
     "check:openapi": "tsx scripts/check-openapi.ts",
@@ -825,6 +827,7 @@
     "generate:openapi": "tsx scripts/generate-openapi.ts",
     "lint": "eslint \"src/**/*.{ts,tsx,js,jsx}\" \"test/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.{ts,tsx,js,jsx}\" \"test/**/*.ts\" --fix",
+    "snapshot:api": "tsx scripts/api-snapshot.ts",
     "snapshot:options": "tsx scripts/options-snapshot.ts",
     "start:dev": "./.dev.mk start",
     "test": "npm run check:ts && mocha",
@@ -853,6 +856,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.60.1",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-terser": "^1.0.2",