ldap-rest 1.2.1 → 2.0.0

package/dist/plugins/twake/tombstone.js

@@ -1 +1 @@
-import e from"../../abstract/plugin.js";import{BadRequestError as t,NotFoundError as s,ConflictError as r}from"../../lib/errors.js";import{jsonBody as a}from"../../lib/expressFormatedResponses.js";import{changeContext as i}from"../../lib/changeContext.js";import{extractLdapCode as o}from"../../lib/ldapCodes.js";import{escapeLdapFilter as n,asyncHandler as h,isDnInBranch as l,launchHooks as d}from"../../lib/utils.js";import{isTombstone as c,lifecycleAttributes as f,first as m,valueOf as p,parseDeletedAt as u,formatDeletedAt as w}from"./lifecycleAttributes.js";const g=/^[A-Za-z0-9_.-]{1,64}$/;class TwakeTombstone extends e{constructor(e){super(e),this.name="twakeTombstone",this.roles=["consistency","api"],this.reasonFor=new Map,this.erasing=new Set,this.hooks={ldapdeleterequest:async([e,t])=>{const s=[];for(const r of Array.isArray(e)?e:[e]){if(this.keeps(r)){const e=await this.read(r);if(e){await this.writeTombstone(r,e,this.reasonOf(r,t),t);continue}}s.push(r)}return[s,t]},ldapaddrequest:async([e,t,s])=>{if(this.isScim(s)&&this.matches(e)){const t=await this.read(e);t&&c(t,this.attrs)&&await this.replace(e,t,s)}return[e,t,s]},ldapsearchrequest:([e,t,s])=>{if(!this.isScim(s))return[e,t,s];const r=t.filter||"(objectClass=*)",a=`(!(${this.attrs.deleted}=${n(this.attrs.deletedValue)}))`;return[e,{...t,filter:`(&${String(r).startsWith("(")?String(r):`(${String(r)})`}${a})`},s]}};const t=this.config;if(this.attrs=f(t),!this.attrs.deleted)throw new Error(`${this.name}: --twake-lifecycle-deleted-attribute is required`);this.patterns=(t.twake_tombstone_dn||[]).map(e=>new RegExp(e,"i")),this.reasons=t.twake_tombstone_reasons||[],this.defaultReason=this.checkReason(t.twake_tombstone_default_reason||"deleted"),this.reasonHeader=(t.twake_tombstone_reason_header||"x-deletion-reason").toLowerCase(),this.clearAttributes=t.twake_tombstone_clear_attributes||[],this.eraseMinAge=t.twake_tombstone_erase_min_age??2592e3,this.groupBases=t.twake_tombstone_group_bases?.length?t.twake_tombstone_group_bases:[t.ldap_group_base||t.ldap_base||""],this.scimPrefix=t.scim_prefix||"/scim/v2",0===this.patterns.length&&this.logger.warn(`${this.name}: --twake-tombstone-dn is empty, every delete stays a delete`)}afterLoad(){for(const e of["ldapdeleterequest","ldapaddrequest"]){const t=this.server.hooks[e],s=this.hooks[e],r=t&&s?t.indexOf(s):-1;r<0||(t.splice(r,1),t.push(s))}}api(e){e.post(`${this.config.api_prefix}/v1/twake/tombstones/erase`,h(async(e,s)=>{const r=a(e,s,"dn");if(r){if("string"!=typeof r.dn)throw new t("Field dn must be a string");await this.erase(r.dn,{force:!0===r.force,req:e}),s.json({success:!0})}}))}async tombstone(e,s,r){if(!this.matches(e))throw new t(`${e} is not an entry that becomes a tombstone`);this.reasonFor.set(e,this.checkReason(s));try{await this.server.ldap.delete(e,r)}finally{this.reasonFor.delete(e)}}async erase(e,{force:t=!1,req:a}={}){await this.server.ldap.authorize("ldapdeleterequest",[e,a]);const i=await this.read(e);if(!i||!c(i,this.attrs))throw new s(`No tombstone at ${e}`);if(!t){const t=m(p(i,this.attrs.deletedAt)),s=t&&u(t,this.attrs.deletedAtFormat);if(!s)throw new r(`${e} holds no readable deletion date (--twake-lifecycle-deleted-at-attribute); force it to erase now`);if(Date.now()-s.getTime()<1e3*this.eraseMinAge)throw new r(`${e} was deleted less than ${this.eraseMinAge} seconds ago; force it to erase now`)}this.erasing.add(e);try{await this.server.ldap.delete(e,a)}finally{this.erasing.delete(e)}await this.leaveGroups(e),this.logger.info({plugin:this.name,event:"erase",dn:e,force:t})}keeps(e){return!this.erasing.has(e)&&this.matches(e)}assertComposition(){if(!this.server.loadedPlugins.trash)return;const e=String(this.config.trash_watched_bases||"").split(";").map(e=>e.trim()).filter(Boolean),t=this.patterns.filter(t=>{const s=t.source.replace(/\$$/,"");return 0===e.length||e.some(e=>l(s,e)||l(e,s))});if(t.length)throw new Error(`${this.name}: core/ldap/trash watches the branch of ${t.map(e=>e.source).join(", ")}, and would move those entries instead of leaving a tombstone. Leave that branch out of --trash-watched-bases, or load one of the two plugins only`)}async replace(e,t,s){const r=await this.groupsOf(e),a=this.config.group_dummy_user,i=new Set(a?await this.groupsOf(a):[]);await this.erase(e,{force:!0,req:s});const o=s.res;if(!o)return;const n=o.end.bind(o);o.end=(...s)=>{o.end=n;const a=n(...s);return this.restore(e,t,r,i).catch(t=>this.logger.error({plugin:this.name,event:"restore",dn:e,error:String(t)})),a}}async restore(e,t,s,r){if(await this.read(e))return;const a=Object.fromEntries(Object.entries(t).filter(([e,t])=>"dn"!==e&&!(Array.isArray(t)&&0===t.length)));await this.server.ldap.system.add(e,a);const i=this.config.group_dummy_user;for(const t of s)await this.server.ldap.system.modify(t,{add:{member:e}}),i&&!r.has(t)&&await this.server.ldap.system.modify(t,{delete:{member:i}}).catch(e=>{if(16!==o(e))throw e});this.logger.warn({plugin:this.name,event:"restore",dn:e})}matches(e){return this.patterns.some(t=>t.test(e))}isScim(e){const t=e?.originalUrl??e?.url;return"string"==typeof t&&t.startsWith(this.scimPrefix)}checkReason(e){if(!(this.reasons.length?this.reasons.includes(e):g.test(e)))throw new t(`Unknown deletion reason "${e}"${this.reasons.length?`; known: ${this.reasons.join(", ")}`:""}`);return e}reasonOf(e,t){const s=this.reasonFor.get(e);if(s)return s;const r=t?.headers?.[this.reasonHeader],a=Array.isArray(r)?r[0]:r;return a?this.checkReason(a):this.defaultReason}async read(e){try{return(await this.server.ldap.system.search({paged:!1,scope:"base",attributes:["*",this.attrs.lock]},e)).searchEntries[0]}catch(e){if(32===o(e))return;throw e}}async writeTombstone(e,t,s,r){const{attrs:a}=this;if(c(t,a))return d(this.server.hooks.twakedeletionreplay,e,t,i(r)),void this.logger.info({plugin:this.name,event:"replay",dn:e});const o={[a.deleted]:a.deletedValue,[a.lock]:a.lockValue};a.deletedAt&&(o[a.deletedAt]=w(new Date,a.deletedAtFormat)),a.reason&&(o[a.reason]=s);const n=this.clearAttributes.filter(e=>void 0!==p(t,e));await this.server.ldap.modify(e,n.length?{replace:o,delete:n}:{replace:o},void 0,{context:i(r)}),this.logger.info({plugin:this.name,event:"tombstone",dn:e,reason:s})}async groupsOf(e){const t=[];for(const s of this.groupBases.filter(Boolean))try{const r=await this.server.ldap.system.search({paged:!1,scope:"sub",filter:`(member=${n(e)})`,attributes:["dn"]},s);t.push(...r.searchEntries.map(e=>e.dn))}catch(e){if(32!==o(e))throw e}return t}async leaveGroups(e){for(const t of await this.groupsOf(e))await this.leaveGroup(t,e)}async leaveGroup(e,t){const s=this.config.group_dummy_user;let r=!1;for(let a=0;;a++)try{return void await this.server.ldap.system.modify(e,r?{add:{member:s},delete:{member:t}}:{delete:{member:t}})}catch(e){const t=o(e);if(16===t)return;if(a>=2)throw e;if(65===t&&s)r=!0;else{if(20!==t)throw e;r=!1}}}}export{TwakeTombstone as default};
+import{Type as e}from"@sinclair/typebox";import t from"../../abstract/plugin.js";import{BadRequestError as s,NotFoundError as r,ConflictError as a}from"../../lib/errors.js";import{changeContext as o}from"../../lib/changeContext.js";import{extractLdapCode as i}from"../../lib/ldapCodes.js";import{escapeLdapFilter as n,isDnInBranch as h,normalizeDn as c}from"../../lib/utils.js";import{scimOptionsOf as l}from"../scim/scim.options.js";import{lifecycleAttributes as d,isTombstone as f,first as m,valueOf as p,parseDeletedAt as u,formatDeletedAt as w}from"./lifecycleAttributes.js";import{twakeTombstoneOptions as g,twakeTombstoneOptionsOf as b}from"./twakeTombstone.options.js";import{defineRoute as y}from"../../lib/route.js";const _=/^[A-Za-z0-9_.-]{1,64}$/,k=e.Object({dn:e.String(),force:e.Optional(e.Boolean())}),v=e.Object({success:e.Boolean()});class TwakeTombstone extends t{static optionDefinitions=g;name="twakeTombstone";roles=["consistency","api"];attrs;patterns;defaultReason;reasonHeader;reasons;clearAttributes;eraseMinAge;groupBases;scimPrefix;reasonFor=new Map;erasing=new Set;constructor(e){super(e);const t=b(e.config);if(this.attrs=d(e.config),!this.attrs.deleted)throw new Error(`${this.name}: --twake-lifecycle-deleted-attribute is required`);this.patterns=t.twake_tombstone_dn.map(e=>new RegExp(e,"i")),this.reasons=t.twake_tombstone_reasons,this.defaultReason=this.checkReason(t.twake_tombstone_default_reason),this.reasonHeader=t.twake_tombstone_reason_header.toLowerCase(),this.clearAttributes=t.twake_tombstone_clear_attributes,this.eraseMinAge=t.twake_tombstone_erase_min_age,this.groupBases=t.twake_tombstone_group_bases.length?t.twake_tombstone_group_bases:[e.config.ldap_group_base||e.config.ldap_base||""],this.scimPrefix=l(e.config).scim_prefix,0===this.patterns.length&&this.logger.warn(`${this.name}: --twake-tombstone-dn is empty, every delete stays a delete`)}afterLoad(){for(const e of["ldapdeleterequest","ldapaddrequest"]){const t=this.hooks?.[e];t&&this.hookBus.toLast(e,t)}}hooks={ldapdeleterequest:async([e,t])=>{const s=[];for(const r of Array.isArray(e)?e:[e]){if(!this.erasing.has(r)){const e=await this.read(r);if(e&&(this.matches(r)||this.matches(e.dn))){await this.writeTombstone(r,e,this.reasonOf(r,t),t);continue}}s.push(r)}return[s,t]},ldapaddrequest:async([e,t,s])=>{if(this.isScim(s)&&this.matches(e)){const t=await this.read(e);t&&f(t,this.attrs)&&await this.replace(e,t,s)}return[e,t,s]},ldapsearchrequest:([e,t,s])=>{if(!this.isScim(s))return[e,t,s];const r=t.filter||"(objectClass=*)",a=`(!(${this.attrs.deleted}=${n(this.attrs.deletedValue)}))`;return[e,{...t,filter:`(&${String(r).startsWith("(")?String(r):`(${String(r)})`}${a})`},s]}};api(e){y(e,{method:"post",path:`${this.config.api_prefix}/v1/twake/tombstones/erase`,body:k,responses:{200:v},handler:async({req:e,res:t,body:s})=>{await this.erase(s.dn,{force:!0===s.force,req:e}),t.json({success:!0})}})}async tombstone(e,t,r){if(!this.matches(e))throw new s(`${e} is not an entry that becomes a tombstone`);this.reasonFor.set(e,this.checkReason(t));try{await this.server.ldap.delete(e,r)}finally{this.reasonFor.delete(e)}}async erase(e,{force:t=!1,req:s}={}){await this.server.ldap.authorize("ldapdeleterequest",[e,s]);const o=await this.read(e);if(!o||!f(o,this.attrs))throw new r(`No tombstone at ${e}`);if(!t){const t=m(p(o,this.attrs.deletedAt)),s=t&&u(t);if(!s)throw new a(`${e} holds no readable deletion date (--twake-lifecycle-deleted-at-attribute); force it to erase now`);if(Date.now()-s.getTime()<1e3*this.eraseMinAge)throw new a(`${e} was deleted less than ${this.eraseMinAge} seconds ago; force it to erase now`)}this.erasing.add(e);try{await this.server.ldap.delete(e,s)}finally{this.erasing.delete(e)}await this.leaveGroups(e),this.logger.info({plugin:this.name,event:"erase",dn:e,force:t})}keeps(e){return!this.erasing.has(e)&&this.matches(e)}assertComposition(){if(!this.server.loadedPlugins.trash)return;const e=String(this.config.trash_watched_bases||"").split(";").map(e=>e.trim()).filter(Boolean),t=this.patterns.filter(t=>{const s=t.source.replace(/\$$/,"");return 0===e.length||e.some(e=>h(s,e)||h(e,s))});if(t.length)throw new Error(`${this.name}: core/ldap/trash watches the branch of ${t.map(e=>e.source).join(", ")}, and would move those entries instead of leaving a tombstone. Leave that branch out of --trash-watched-bases, or load one of the two plugins only`)}async replace(e,t,s){const r=await this.groupsOf(e),a=this.config.group_dummy_user,o=new Set(a?await this.groupsOf(a):[]);await this.erase(e,{force:!0,req:s});const i=s.res;if(!i)return;const n=i.end.bind(i);i.end=(...s)=>{i.end=n;const a=n(...s);return this.restore(e,t,r,o).catch(t=>this.logger.error({plugin:this.name,event:"restore",dn:e,error:String(t)})),a}}async restore(e,t,s,r){if(await this.read(e))return;const a=Object.fromEntries(Object.entries(t).filter(([e,t])=>"dn"!==e&&!(Array.isArray(t)&&0===t.length)));await this.server.ldap.system.add(e,a);const o=this.config.group_dummy_user;for(const t of s)await this.server.ldap.system.modify(t,{add:{member:e}}),o&&!r.has(t)&&await this.server.ldap.system.modify(t,{delete:{member:o}}).catch(e=>{if(16!==i(e))throw e});this.logger.warn({plugin:this.name,event:"restore",dn:e})}matches(e){if(this.patterns.some(t=>t.test(e)))return!0;let t;try{t=c(e)}catch{return!1}return this.patterns.some(e=>e.test(t))}isScim(e){const t=e?.originalUrl??e?.url;return"string"==typeof t&&t.startsWith(this.scimPrefix)}checkReason(e){if(!(this.reasons.length?this.reasons.includes(e):_.test(e)))throw new s(`Unknown deletion reason "${e}"${this.reasons.length?`; known: ${this.reasons.join(", ")}`:""}`);return e}reasonOf(e,t){const s=this.reasonFor.get(e);if(s)return s;const r=t?.headers?.[this.reasonHeader],a=Array.isArray(r)?r[0]:r;return a?this.checkReason(a):this.defaultReason}async read(e){try{return(await this.server.ldap.system.search({paged:!1,scope:"base",attributes:["*",this.attrs.lock]},e)).searchEntries[0]}catch(t){const r=i(t);if(32===r)return;if(34===r)throw new s(`Invalid DN: ${e}`);throw t}}async writeTombstone(e,t,s,r){const{attrs:a}=this;if(f(t,a))return this.hookBus.notify("twakedeletionreplay",e,t,o(r)),void this.logger.info({plugin:this.name,event:"replay",dn:e});const i={[a.deleted]:a.deletedValue,[a.lock]:a.lockValue};a.deletedAt&&(i[a.deletedAt]=w(new Date,a.deletedAtFormat)),a.reason&&(i[a.reason]=s);const n=this.clearAttributes.filter(e=>void 0!==p(t,e));await this.server.ldap.modify(e,n.length?{replace:i,delete:n}:{replace:i},void 0,{context:o(r)}),this.logger.info({plugin:this.name,event:"tombstone",dn:e,reason:s})}async groupsOf(e){const t=[];for(const s of this.groupBases.filter(Boolean))try{const r=await this.server.ldap.system.search({paged:!1,scope:"sub",filter:`(member=${n(e)})`,attributes:["dn"]},s);t.push(...r.searchEntries.map(e=>e.dn))}catch(e){if(32!==i(e))throw e}return t}async leaveGroups(e){for(const t of await this.groupsOf(e))await this.leaveGroup(t,e)}async leaveGroup(e,t){const s=this.config.group_dummy_user;let r=!1;for(let a=0;;a++)try{return void await this.server.ldap.system.modify(e,r?{add:{member:s},delete:{member:t}}:{delete:{member:t}})}catch(e){const t=i(e);if(16===t)return;if(a>=2)throw e;if(65===t&&s)r=!0;else{if(20!==t)throw e;r=!1}}}}export{k as EraseTombstoneBody,v as EraseTombstoneResponse,TwakeTombstone as default};

package/dist/plugins/twake/twakeGroups.options.js

@@ -0,0 +1 @@
+import{defineOptions as _,opt as t,readOptions as e}from"../../config/options.js";const a=_({twake_group_base:t.string({env:"DM_TWAKE_GROUP_BASE",default:""}),twake_group_user_base:t.string({env:"DM_TWAKE_GROUP_USER_BASE",default:""}),twake_group_organization_dn:t.string({env:"DM_TWAKE_GROUP_ORGANIZATION_DN",default:""}),twake_group_organization_status_attribute:t.string({env:"DM_TWAKE_GROUP_ORGANIZATION_STATUS_ATTRIBUTE",default:"twakeOrgStatus"}),twake_group_organization_deleted_value:t.string({env:"DM_TWAKE_GROUP_ORGANIZATION_DELETED_VALUE",default:"deleted"}),twake_group_display_name_attribute:t.string({env:"DM_TWAKE_GROUP_DISPLAY_NAME_ATTRIBUTE",default:"twakeDisplayName"}),twake_group_color_attribute:t.string({env:"DM_TWAKE_GROUP_COLOR_ATTRIBUTE",default:"twakeGroupColor"}),twake_group_created_at_attribute:t.string({env:"DM_TWAKE_GROUP_CREATED_AT_ATTRIBUTE",default:"twakeCreatedAt"}),twake_group_max_page_limit:t.number({env:"DM_TWAKE_GROUP_MAX_PAGE_LIMIT",default:1e3,min:1}),twake_group_member_fields:t.json({env:"DM_TWAKE_GROUP_MEMBER_FIELDS",default:{}})});function twakeGroupsOptionsOf(_){return e(a,_)}export{a as twakeGroupsOptions,twakeGroupsOptionsOf};

package/dist/plugins/twake/twakeInstances.options.js

@@ -0,0 +1 @@
+import{defineOptions as _,opt as e,readOptions as t}from"../../config/options.js";const n=_({twake_instance_dn:e.array({env:"DM_TWAKE_INSTANCE_DN",default:[],kind:"dns"}),twake_instance_skip_attribute:e.string({env:"DM_TWAKE_INSTANCE_SKIP_ATTRIBUTE",default:""}),twake_instance_skip_value:e.string({env:"DM_TWAKE_INSTANCE_SKIP_VALUE",default:""}),twake_instance_provider:e.string({env:"DM_TWAKE_INSTANCE_PROVIDER",default:"cloudery"}),twake_instance_id:e.string({env:"DM_TWAKE_INSTANCE_ID",default:"{uid}"}),twake_instance_fqdn_attribute:e.string({env:"DM_TWAKE_INSTANCE_FQDN_ATTRIBUTE",default:"twakeWorkspaceUrl"}),twake_instance_sent_attribute:e.string({env:"DM_TWAKE_INSTANCE_SENT_ATTRIBUTE",default:"twakeCreatedEventAt"}),twake_instance_locale:e.string({env:"DM_TWAKE_INSTANCE_LOCALE",default:""}),twake_instance_timeout:e.number({env:"DM_TWAKE_INSTANCE_TIMEOUT",default:3e4,min:1}),twake_instance_cloudery_url:e.string({env:"DM_TWAKE_INSTANCE_CLOUDERY_URL",default:""}),twake_instance_cloudery_token:e.string({env:"DM_TWAKE_INSTANCE_CLOUDERY_TOKEN",default:""}),twake_instance_cloudery_offer:e.string({env:"DM_TWAKE_INSTANCE_CLOUDERY_OFFER",default:"b2b_twake_default",emptyIsValue:!0}),twake_instance_cloudery_domain:e.string({env:"DM_TWAKE_INSTANCE_CLOUDERY_DOMAIN",default:""}),twake_instance_cloudery_organization_offer:e.string({env:"DM_TWAKE_INSTANCE_CLOUDERY_ORGANIZATION_OFFER",default:""}),twake_instance_cozy_url:e.string({env:"DM_TWAKE_INSTANCE_COZY_URL",default:""}),twake_instance_cozy_user:e.string({env:"DM_TWAKE_INSTANCE_COZY_USER",default:"admin"}),twake_instance_cozy_passphrase:e.string({env:"DM_TWAKE_INSTANCE_COZY_PASSPHRASE",default:""}),twake_instance_cozy_domain:e.string({env:"DM_TWAKE_INSTANCE_COZY_DOMAIN",default:""}),twake_instance_cozy_context:e.string({env:"DM_TWAKE_INSTANCE_COZY_CONTEXT",default:"default",emptyIsValue:!0}),twake_instance_cozy_apps:e.string({env:"DM_TWAKE_INSTANCE_COZY_APPS",default:"home,drive,settings,notes,dataproxy",emptyIsValue:!0}),twake_instance_cozy_org_id:e.string({env:"DM_TWAKE_INSTANCE_COZY_ORG_ID",default:""}),twake_instance_cozy_org_domain:e.string({env:"DM_TWAKE_INSTANCE_COZY_ORG_DOMAIN",default:""}),twake_instance_auth_exchange:e.string({env:"DM_TWAKE_INSTANCE_AUTH_EXCHANGE",default:"auth"}),twake_instance_b2b_exchange:e.string({env:"DM_TWAKE_INSTANCE_B2B_EXCHANGE",default:"b2b"}),twake_instance_user_created_key:e.string({env:"DM_TWAKE_INSTANCE_USER_CREATED_KEY",default:"user.created"}),twake_instance_organization_created_key:e.string({env:"DM_TWAKE_INSTANCE_ORGANIZATION_CREATED_KEY",default:"organization.created"}),twake_instance_workplace_created_key:e.string({env:"DM_TWAKE_INSTANCE_WORKPLACE_CREATED_KEY",default:"workplace.created"}),twake_instance_queue:e.string({env:"DM_TWAKE_INSTANCE_QUEUE",default:"workplace.created.ldap-rest"}),twake_instance_organization_base:e.string({env:"DM_TWAKE_INSTANCE_ORGANIZATION_BASE",default:""}),twake_instance_organization_id_attribute:e.string({env:"DM_TWAKE_INSTANCE_ORGANIZATION_ID_ATTRIBUTE",default:"ou"}),twake_instance_organization_domain_attribute:e.string({env:"DM_TWAKE_INSTANCE_ORGANIZATION_DOMAIN_ATTRIBUTE",default:"twakeDomain"}),twake_instance_organization_name_attribute:e.string({env:"DM_TWAKE_INSTANCE_ORGANIZATION_NAME_ATTRIBUTE",default:"description"}),twake_instance_organization_fqdn_attribute:e.string({env:"DM_TWAKE_INSTANCE_ORGANIZATION_FQDN_ATTRIBUTE",default:""})});function twakeInstancesOptionsOf(_){return t(n,_)}export{n as twakeInstancesOptions,twakeInstancesOptionsOf};

package/dist/plugins/twake/twakeLifecycle.options.js

@@ -0,0 +1 @@
+import{defineOptions as e,opt as _,readOptions as t}from"../../config/options.js";const E=e({twake_lifecycle_role_attribute:_.string({env:"DM_TWAKE_LIFECYCLE_ROLE_ATTRIBUTE",default:""}),twake_lifecycle_lock_attribute:_.string({env:"DM_TWAKE_LIFECYCLE_LOCK_ATTRIBUTE",default:""}),twake_lifecycle_lock_value:_.string({env:"DM_TWAKE_LIFECYCLE_LOCK_VALUE",default:""}),twake_lifecycle_deleted_attribute:_.string({env:"DM_TWAKE_LIFECYCLE_DELETED_ATTRIBUTE",default:""}),twake_lifecycle_deleted_value:_.string({env:"DM_TWAKE_LIFECYCLE_DELETED_VALUE",default:"TRUE"}),twake_lifecycle_deleted_at_attribute:_.string({env:"DM_TWAKE_LIFECYCLE_DELETED_AT_ATTRIBUTE",default:""}),twake_lifecycle_deleted_at_format:_.string({env:"DM_TWAKE_LIFECYCLE_DELETED_AT_FORMAT",default:"iso8601"}),twake_lifecycle_reason_attribute:_.string({env:"DM_TWAKE_LIFECYCLE_REASON_ATTRIBUTE",default:""}),twake_lifecycle_rules:_.string({env:"DM_TWAKE_LIFECYCLE_RULES",default:""}),twake_lifecycle_member_attribute:_.string({env:"DM_TWAKE_LIFECYCLE_MEMBER_ATTRIBUTE",default:"member"})});function twakeLifecycleOptionsOf(e){return t(E,e)}export{E as twakeLifecycleOptions,twakeLifecycleOptionsOf};

package/dist/plugins/twake/twakeSpaces.options.js

@@ -0,0 +1 @@
+import{defineOptions as e,opt as t,readOptions as _}from"../../config/options.js";const a=e({twake_space_base:t.string({env:"DM_TWAKE_SPACE_BASE",default:""}),twake_space_class:t.array({env:"DM_TWAKE_SPACE_CLASS",default:["top","twakeSpace"],kind:"identifiers"}),twake_space_display_name_attribute:t.string({env:"DM_TWAKE_SPACE_DISPLAY_NAME_ATTRIBUTE",default:"twakeDisplayName"}),twake_space_admin_attribute:t.string({env:"DM_TWAKE_SPACE_ADMIN_ATTRIBUTE",default:"twakeSpaceAdmin"}),twake_space_editor_attribute:t.string({env:"DM_TWAKE_SPACE_EDITOR_ATTRIBUTE",default:"twakeSpaceEditor"}),twake_space_viewer_attribute:t.string({env:"DM_TWAKE_SPACE_VIEWER_ATTRIBUTE",default:"twakeSpaceViewer"}),twake_space_user_role_attribute:t.string({env:"DM_TWAKE_SPACE_USER_ROLE_ATTRIBUTE",default:""}),twake_space_exchange:t.string({env:"DM_TWAKE_SPACE_EXCHANGE",default:"space"}),twake_space_sync_queue:t.string({env:"DM_TWAKE_SPACE_SYNC_QUEUE",default:"twake.space.sync.requested.ldap-rest"})});function twakeSpacesOptionsOf(e){return _(a,e)}export{a as twakeSpacesOptions,twakeSpacesOptionsOf};

package/dist/plugins/twake/twakeTombstone.options.js

@@ -0,0 +1 @@
+import{defineOptions as e,opt as t,readOptions as _}from"../../config/options.js";const n=e({twake_tombstone_dn:t.array({env:"DM_TWAKE_TOMBSTONE_DN",default:[],kind:"dns"}),twake_tombstone_default_reason:t.string({env:"DM_TWAKE_TOMBSTONE_DEFAULT_REASON",default:"deleted"}),twake_tombstone_reason_header:t.string({env:"DM_TWAKE_TOMBSTONE_REASON_HEADER",default:"x-deletion-reason"}),twake_tombstone_reasons:t.array({env:"DM_TWAKE_TOMBSTONE_REASONS",default:[],kind:"identifiers"}),twake_tombstone_clear_attributes:t.array({env:"DM_TWAKE_TOMBSTONE_CLEAR_ATTRIBUTES",default:[],kind:"identifiers"}),twake_tombstone_erase_min_age:t.number({env:"DM_TWAKE_TOMBSTONE_ERASE_MIN_AGE",default:2592e3}),twake_tombstone_group_bases:t.array({env:"DM_TWAKE_TOMBSTONE_GROUP_BASES",default:[],kind:"dns"})});function twakeTombstoneOptionsOf(e){return _(n,e)}export{n as twakeTombstoneOptions,twakeTombstoneOptionsOf};

package/dist/plugins/weblogs.js

@@ -1 +1 @@
-import e from"../abstract/plugin.js";import{requestId as r}from"../lib/changeContext.js";import{runWithLogContext as o}from"../lib/requestContext.js";class WebLogs extends e{constructor(){super(...arguments),this.name="weblogs",this.roles=["logging"]}api(e){e.use((e,r,o)=>{let t=!0;this.logger.debug(`Incoming request: ${e.method} ${e.originalUrl}`);const s=Date.now();r.on("finish",()=>{const o={};e.proxyAuthUser?o.user=e.proxyAuthUser:e.user&&(o.user=e.user),t&&this.log(e,r,s,o),t=!1}),r.on("error",o=>{t&&this.log(e,r,s,{error:o.message}),t=!1}),r.on("close",()=>{r.writableEnded||(t&&this.log(e,r,s,{error:`Connection closed before response was sent for ${e.method} ${e.originalUrl}`}),t=!1)}),o()})}log(e,t,s,n){const i=Date.now()-s,l={...e.logDetails||{},requestId:r(e),method:e.method,url:e.originalUrl,status:t.statusCode,duration:i,ip:this.getClientIp(e),...n};o({requestId:l.requestId},()=>this.logger.notice(l))}getClientIp(e){const r=e.headers["x-forwarded-for"];if(r){return(Array.isArray(r)?r[0]:r).split(",")[0].trim()}return e.socket.remoteAddress||"unknown"}}export{WebLogs as default};
+import e from"../abstract/plugin.js";import{requestId as r}from"../lib/changeContext.js";import{runWithLogContext as o}from"../lib/requestContext.js";class WebLogs extends e{name="weblogs";roles=["logging"];api(e){e.use((e,r,o)=>{let t=!0;this.logger.debug(`Incoming request: ${e.method} ${e.originalUrl}`);const s=Date.now();r.on("finish",()=>{const o={};e.proxyAuthUser?o.user=e.proxyAuthUser:e.user&&(o.user=e.user),t&&this.log(e,r,s,o),t=!1}),r.on("error",o=>{t&&this.log(e,r,s,{error:o.message}),t=!1}),r.on("close",()=>{r.writableEnded||(t&&this.log(e,r,s,{error:`Connection closed before response was sent for ${e.method} ${e.originalUrl}`}),t=!1)}),o()})}log(e,t,s,n){const i=Date.now()-s,l={...e.logDetails||{},requestId:r(e),method:e.method,url:e.originalUrl,status:t.statusCode,duration:i,ip:this.getClientIp(e),...n};o({requestId:l.requestId},()=>this.logger.notice(l))}getClientIp(e){const r=e.headers["x-forwarded-for"];if(r){return(Array.isArray(r)?r[0]:r).split(",")[0].trim()}return e.socket.remoteAddress||"unknown"}}export{WebLogs as default};

package/dist/src/abstract/ldapFlat.d.ts

@@ -1,12 +1,3 @@
-/**
- * @module abstract/ldapFlat
- * @author Xavier Guimard <xguimard@linagora.com>
- *
- * Abstract class to manage LDAP entries in a flat branch
- * - add/delete entries
- * - modify entries
- * - validate with schema
- */
 import type { Express, Request, Response } from 'express';
 import type { DM } from '../bin';
 import type ldapActions from '../lib/ldapActions';
@@ -210,6 +201,26 @@ export interface LdapFlatConfig {
  *     dn: uid=bob,ou=users,dc=example,dc=com
  *     referencesUpdated: 3
  */
+export declare const FlatListQuery: import("@sinclair/typebox").TObject<{
+    match: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    attribute: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    attributes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export declare const FlatEntryParams: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+}>;
+export declare const FlatMoveBody: import("@sinclair/typebox").TObject<{
+    targetOrgDn: import("@sinclair/typebox").TString;
+}>;
+export declare const FlatMoveResponse: import("@sinclair/typebox").TObject<{
+    success: import("@sinclair/typebox").TBoolean;
+    departmentPath: import("@sinclair/typebox").TString;
+    departmentLink: import("@sinclair/typebox").TString;
+}>;
+export declare const FlatRenameBody: import("@sinclair/typebox").TObject<{
+    newId: import("@sinclair/typebox").TString;
+}>;
 export default abstract class LdapFlat extends DmPlugin {
     base: string;
     ldap: ldapActions;
@@ -220,6 +231,12 @@ export default abstract class LdapFlat extends DmPlugin {
     singularName: string;
     pluralName: string;
     hookPrefix: string;
+    /** `hookBus`, raising this entity's own hooks */
+    private readonly ownHooks;
+    /**
+     * @param server the server
+     * @param config the entity, its hook prefix included
+     */
     constructor(server: DM, config: LdapFlatConfig);
     /**
      * Attributes never sent back over the API. A manager may reset a password
@@ -365,6 +382,19 @@ export default abstract class LdapFlat extends DmPlugin {
      * @throws BadRequestError if the provided DN is not a direct child of this.base
      */
     protected resolveDn(id: string): string;
+    /**
+     * The name and the DN a creation of `id` gives: `id` is the naming value,
+     * or a DN whose first RDN names the entry, folded as the directory folds
+     * it and written back in this branch.
+     *
+     * Both the write and the answer it gets after it read the DN here, so a
+     * spelling the directory folds differently cannot leave the entry created
+     * under one DN and read back at another.
+     */
+    protected creationOf(id: string): {
+        name: string;
+        dn: string;
+    };
     addEntry(id: string, additional?: AttributesList, req?: Request): Promise<boolean>;
     modifyEntry(id: string, changes: ModifyRequest, req?: Request): Promise<boolean>;
     /**
@@ -421,6 +451,7 @@ export default abstract class LdapFlat extends DmPlugin {
         truncated: boolean;
     }>;
     searchEntriesByName(name: string, partial?: boolean, attrs?: string[]): Promise<LdapList>;
-    validateNewEntry(dn: string, entry: AttributesList): Promise<boolean>;
+    /** @returns the entry to write, under the schema's spellings */
+    validateNewEntry(dn: string, entry: AttributesList): Promise<AttributesList>;
     validateChanges(dn: string, changes: ModifyRequest): Promise<boolean>;
 }

package/dist/src/abstract/plugin.d.ts

@@ -3,30 +3,42 @@
  * @author Xavier Guimard <xguimard@linagora.com>
  */
 import type { Express } from 'express';
-import fetch, { type RequestInit, type Response } from 'node-fetch';
 import type winston from 'winston';
 import type { Config, DM } from '../bin';
 import type { Hooks, MaybePromise } from '../hooks';
+import type HookBus from '../lib/hookBus';
 import type { HealthStatus } from '../lib/health';
+import { type ServiceProvider, type ServiceToken } from '../lib/services';
+import { type OptionsOf, type OptionSet } from '../config/options';
 export { asyncHandler, escapeDnValue, unescapeDnValue, escapeLdapFilter, validateDnValue, } from '../lib/utils';
+export { defineRoute, registeredRoutes } from '../lib/route';
+export { serviceToken } from '../lib/services';
+export type { ServiceProvider, ServiceToken } from '../lib/services';
 export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UriTooLongError, TooManyRequestsError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, } from '../lib/errors';
 export type { HealthStatus };
 export type Role = 'auth' | 'authz' | 'protect' | 'api' | 'logging' | 'demo' | 'consistency' | 'configurable';
 export default abstract class DmPlugin {
+    /** Options this plugin declares, see `docs/plugin-development/options.md` */
+    static optionDefinitions: OptionSet;
     /**
      * Properties inherited from parent (DM)
      */
     server: DM;
     config: Config;
+    hookBus: HookBus;
     logger: winston.Logger;
-    registeredHooks: {
-        [K in keyof Hooks]?: Function[];
-    };
+    registeredHooks: Hooks;
     /**
      * Interfaces
      */
     hooks?: Hooks;
     dependencies?: Record<string, string>;
+    /**
+     * Services this plugin provides, each bound to its token. A consumer
+     * reaches them with `service(token)`, see
+     * `docs/plugin-development/services.md`.
+     */
+    provides?: ServiceProvider<unknown>[];
     roles?: Role[] | undefined;
     /**
      * Operational attributes this plugin follows through `onLdapEntryChange`,
@@ -76,12 +88,14 @@ export default abstract class DmPlugin {
      * Call another service: `fetch`, timed into the outbound metrics under
      * this plugin's name, see `docs/usage/operations.md#metrics`.
      */
-    protected fetch(url: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response>;
+    protected fetch(url: Parameters<typeof globalThis.fetch>[0], init?: RequestInit): Promise<Response>;
     /**
      * Constructor
      * @param server DM object
      */
     constructor(server: DM);
+    /** Values of the options this plugin declares, read and checked */
+    options<T extends OptionSet>(definitions: T): OptionsOf<T>;
     /**
      * Uniq ID, to be used when calling hooks
      *
@@ -106,6 +120,18 @@ export default abstract class DmPlugin {
     protected hideNeverReturn<T>(data: T): T;
     /** Names already warned about by requirePlugin, so each warns at most once. */
     private missingPluginsWarned?;
+    /** Services already warned about by service(), so each warns at most once. */
+    private missingServicesWarned?;
+    /**
+     * Reach a service another plugin provides. Declare the providing plugin in
+     * `dependencies` so it registers first. Returns null and logs a single
+     * warning when nothing provides it, so the consumer skips its feature
+     * rather than throwing.
+     *
+     * @param token the service wanted
+     * @returns the provided instance, or null
+     */
+    protected service<T>(token: ServiceToken<T>): T | null;
     /**
      * Resolve a sibling plugin by its registry name (the value of its `name`
      * property). Declare it in `dependencies` so it loads first. Returns null and

package/dist/src/abstract/twakePlugin.d.ts

@@ -9,6 +9,18 @@ import type { DM } from '../bin';
 import { type HealthStatus } from '../lib/health';
 import type { AttributesList } from '../lib/ldapActions';
 import DmPlugin, { type Role } from './plugin';
+/** What a Twake plugin needs to reach its WebAdmin API */
+export interface TwakeConnection {
+    url: string;
+    token: string;
+    concurrency: number;
+    /** Option holding the URL, named in the startup error when it is empty */
+    urlOption: string;
+    /** Option holding the token, named in the warning when it is empty */
+    tokenOption: string;
+    /** Option holding the concurrency, named when it is not a positive integer */
+    concurrencyOption: string;
+}
 /**
  * Abstract base class for all Twake-related plugins (James, Calendar, Matrix, etc.)
  * Consolidates common patterns for HTTP communication with Twake WebAdmin APIs
@@ -26,11 +38,9 @@ export declare abstract class TwakePlugin extends DmPlugin {
     /**
      * Constructor - initializes common Twake plugin configuration
      * @param server DM server instance
-     * @param urlConfig Configuration key for WebAdmin URL
-     * @param tokenConfig Configuration key for WebAdmin token
-     * @param concurrencyConfig Configuration key for concurrency limit
+     * @param connection WebAdmin URL, token and concurrency
      */
-    constructor(server: DM, urlConfig: string, tokenConfig: string, concurrencyConfig: string);
+    constructor(server: DM, connection: TwakeConnection);
     /**
      * Create HTTP headers with optional Authorization token
      * @param contentType Optional Content-Type header value

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

@@ -19,10 +19,12 @@ import type { Hooks } from '../hooks';
 import ldapActions from '../lib/ldapActions';
 import type DmPlugin from '../abstract/plugin';
 import AuthBase from '../lib/auth/base';
+import { type ServiceMap } from '../lib/services';
+import HookBus from '../lib/hookBus';
 export type { Config };
 export * from '../lib/utils';
 export { asyncHandler } from '../lib/utils';
-export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UriTooLongError, TooManyRequestsError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, } from '../lib/errors';
+export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, AuthzRefusedError, NotFoundError, ConflictError, UriTooLongError, TooManyRequestsError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, } from '../lib/errors';
 /**
  * @class DM
  */
@@ -33,12 +35,23 @@ export declare class DM {
     /** The listener, once `run()` opened it; shared by the `withConfig` views */
     get server(): import('http').Server | undefined;
     set server(server: import('http').Server | undefined);
-    hooks: {
-        [K in keyof Hooks]?: Function[];
-    };
+    /**
+     * What each hook's subscribers do, as a plugin declares them. The type
+     * names every hook: raising or subscribing to one goes through `hookBus`,
+     * which checks the arguments.
+     */
+    hooks: Hooks;
+    readonly hookBus: HookBus;
     loadedPlugins: {
         [key: string]: DmPlugin;
     };
+    /**
+     * The services plugins provide, keyed by their token. Shared by `withConfig`
+     * views as the plugin registry is; `registerPlugin` fills it.
+     */
+    readonly services: ServiceMap;
+    /** The plugin that provided each service, for the duplicate warning. */
+    private readonly serviceOwners;
     ldap: ldapActions;
     operationSequence: number;
     logger: winston.Logger;
@@ -87,6 +100,10 @@ export declare class DM {
      * whose name is taken. A Map, so that `withConfig` views share it.
      */
     private readonly pluginLoads;
+    /** CLI arguments no declared option matched, reported after the logger exists */
+    private readonly unknownCliOptions;
+    /** Configuration read through a deprecated name, reported once the logger exists */
+    private readonly deprecationWarnings;
     /**
      * The request hooks of the authorization plugins, which `registerPlugin`
      * keeps ahead of every other plugin's. See {@link AUTHZ_FIRST_HOOKS}.
@@ -123,6 +140,12 @@ export declare class DM {
      * @returns a server view backed by this instance
      */
     withConfig(config: Config): DM;
+    /**
+     * Name the CLI arguments and `DM_*` variables nothing declares, among the
+     * plugins `--plugins` loaded and their `optionDefinitions`. A host that
+     * registers its own plugins after `ready` is not covered.
+     */
+    private reportUnknownOptions;
     /**
      * Mount the authentication dispatcher, once, before the first plugin that
      * can register a route.
@@ -283,4 +306,12 @@ export declare class DM {
      */
     private admitToComposition;
     registerPlugin(pluginName: string, obj: DmPlugin, name?: string): Promise<boolean>;
+    /**
+     * Record the services a plugin provides. The first provider of a token
+     * wins: a second one would answer for the same interface and leave the
+     * choice to the load order, so it is ignored and named in a warning.
+     *
+     * @param obj the plugin just registered
+     */
+    private registerServices;
 }

package/dist/src/config/args.d.ts

@@ -1,8 +1,6 @@
 import type { AttributesList } from '../lib/ldapActions';
 import type { ConfigTemplate } from '../lib/parseConfig';
-/** The headers `core/static` sends unless told otherwise: no framing by another site */
-export declare const STATIC_CSP = "frame-ancestors 'self'";
-export declare const STATIC_FRAME_OPTIONS = "SAMEORIGIN";
+export { STATIC_CSP, STATIC_FRAME_OPTIONS } from '../plugins/static.options';
 export interface BranchPermissions {
     read?: boolean;
     write?: boolean;
@@ -34,6 +32,7 @@ export interface Config {
     log_level: 'error' | 'warn' | 'notice' | 'info' | 'debug';
     shutdown_timeout?: number;
     debug: boolean;
+    strict_options?: boolean;
     logger: 'console' | 'file';
     log_file?: string;
     api_prefix: string;
@@ -364,7 +363,6 @@ export interface Config {
     scim_bulk_max_payload_size?: number;
     scim_etag?: boolean;
     scim_base_url?: string;
-    [key: string]: string | string[] | boolean | number | AttributesList | AuthConfig | undefined;
 }
 /**
  * Config arguments

package/dist/src/config/options.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Configuration options declared by the code that reads them.
+ *
+ * A plugin describes its options next to its implementation with
+ * {@link defineOptions}; `src/config/args.ts` concatenates the declarations so
+ * the parser sees the same entries it always did. {@link readOptions} gives a
+ * plugin typed values, with the defaults applied and the value checked once.
+ *
+ * See `docs/plugin-development/options.md`.
+ */
+import { type ArrayKind, type ConfigEntry, type ConfigTemplate } from '../lib/parseConfig';
+import type { Config } from './args';
+export type OptionType = 'string' | 'number' | 'boolean' | 'array' | 'json';
+export interface OptionSpec<T> {
+    readonly type: OptionType;
+    /** Environment variable the option reads when the CLI does not set it */
+    readonly env?: string;
+    /** Value kept when neither the CLI nor the environment sets the option */
+    readonly default?: T;
+    /** Refuse an empty value rather than read it as unset */
+    readonly required?: boolean;
+    /**
+     * A string option whose empty value means something: keep it instead of
+     * reading the declared default, as an empty environment or CLI value does.
+     */
+    readonly emptyIsValue?: boolean;
+    /**
+     * Former CLI names still accepted, without the leading `--`: the parser
+     * reads them as the canonical name and warns at startup. An alias takes one
+     * value per occurrence, as the singular form does.
+     */
+    readonly aliases?: readonly string[];
+    /**
+     * Former environment variables still accepted, read when `env` is unset or
+     * holds an empty value the type reads as nothing
+     */
+    readonly envAliases?: readonly string[];
+}
+export interface StringOption extends OptionSpec<string> {
+    readonly type: 'string';
+    /** Values the option accepts, when it is a closed set */
+    readonly choices?: readonly string[];
+}
+export interface StringOrFalseOption extends OptionSpec<string | false> {
+    readonly type: 'string';
+    readonly allowFalse: true;
+}
+export interface NumberOption extends OptionSpec<number> {
+    readonly type: 'number';
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface BooleanOption extends OptionSpec<boolean> {
+    readonly type: 'boolean';
+}
+export interface ArrayOption extends OptionSpec<string[]> {
+    readonly type: 'array';
+    /** CLI name of the plural form, without the leading `--` */
+    readonly plural?: string;
+    /** How a comma, space or semicolon separated value splits, see ArrayKind */
+    readonly kind?: ArrayKind;
+}
+export interface JsonOption<T> extends OptionSpec<T> {
+    readonly type: 'json';
+}
+export type OptionSet = Record<string, OptionSpec<unknown>>;
+/** The typed values {@link readOptions} returns for a set of declarations */
+export type OptionsOf<T extends OptionSet> = {
+    [K in keyof T]: T[K] extends OptionSpec<infer V> ? V : never;
+};
+/**
+ * A set of options, keyed by their `Config` name (`scim_max_results` for
+ * `--scim-max-results`). Identity function: its only job is to keep the
+ * literal types of the declarations.
+ */
+export declare function defineOptions<T extends OptionSet>(options: T): T;
+export declare const opt: {
+    string: (options?: Omit<StringOption, "type">) => StringOption;
+    number: (options?: Omit<NumberOption, "type">) => NumberOption;
+    boolean: (options?: Omit<BooleanOption, "type">) => BooleanOption;
+    array: (options?: Omit<ArrayOption, "type">) => ArrayOption;
+    stringOrFalse: (options?: Omit<StringOrFalseOption, "type" | "allowFalse">) => StringOrFalseOption;
+    json: <T = Record<string, unknown>>(options?: Omit<JsonOption<T>, "type">) => JsonOption<T>;
+};
+/**
+ * The parser entries a set of declarations amounts to. `args.ts` concatenates
+ * them with the global options and the other plugins' declarations.
+ */
+export declare function toConfigEntries(options: OptionSet): ConfigEntry[];
+/**
+ * `DM_*` variables no declared option reads. Test-only variables are left
+ * out: a suite sets its own infrastructure through the same prefix.
+ */
+export declare function unknownEnvironmentOptions(entries: ConfigTemplate, env?: Record<string, string | undefined>, extra?: OptionSet[]): string[];
+/**
+ * Read a plugin's options from a parsed configuration, applying the declared
+ * defaults and checking the values. Called once per instance by
+ * `DmPlugin.options()`.
+ *
+ * `parsedKeys` names the options the parser knew. An option declared outside
+ * `src/config/args.ts` reaches the parser as an unknown `--name value` pair,
+ * so its aliases are read here, under the key the unknown name produces.
+ */
+export declare function readOptions<T extends OptionSet>(options: T, config: Config | Record<string, unknown>, parsedKeys?: ReadonlySet<string>, warn?: (message: string) => void): OptionsOf<T>;

package/dist/src/config/schema.d.ts

@@ -75,6 +75,16 @@ export declare function localizedText(text: LocalizedText | undefined, language?
  * @returns the message
  */
 export declare function invalidValueMessage(name: string, attr: SchemaAttribute | undefined): string;
+/**
+ * Refusal of a value longer than its attribute accepts, for a
+ * `BadRequestError`. Said apart from {@link invalidValueMessage}: the value
+ * is not malformed, it is longer than the attribute may hold.
+ *
+ * @param name attribute name
+ * @param maxLength the length it may not exceed
+ * @returns the message
+ */
+export declare function tooLongMessage(name: string, maxLength: number): string;
 /** Roles the core itself looks for. See {@link SchemaRole}. */
 export declare const CORE_ROLES: readonly ["identifier", "displayName", "primaryEmail", "emailAliases", "emailQuota", "organizationLink", "organizationPath", "members", "owners", "accountStatus", "password", "passwordReset", "accountExpiry", "domainLink", "domainName"];
 /**
@@ -142,10 +152,19 @@ export interface SchemaAttribute {
         test?: string | RegExp;
         hint?: LocalizedText;
         branch?: string[];
+        /** Longest value, in UTF-16 code units, before `test` runs on it */
+        maxLength?: number;
     };
     default?: AttributeValue;
     required?: boolean;
     test?: string | RegExp;
+    /**
+     * Longest value, in UTF-16 code units, `test` is asked to judge: a longer one is
+     * refused before the pattern reads it. Without it, the length is
+     * {@link DEFAULT_MAX_LENGTH}; an attribute holding longer values declares
+     * it here, the reason being in `docs/client-development/schemas/README.md`.
+     */
+    maxLength?: number;
     /**
      * Plain-language description of `test`, shown to the user *before* they get
      * a value wrong — "Expected pattern 999 9999". It travels with the
@@ -334,6 +353,10 @@ export declare function modifiedAttributeNames(body: {
  * written as text where the schema declares one, a boolean as LDAP's
  * `TRUE` / `FALSE`, and anything else is refused.
  *
+ * The attribute is read as a request names it, under any case and with or
+ * without a `;binary` option: the value is converted by its type, as the
+ * validator accepted it.
+ *
  * @param schema schema of the entry, if any
  * @param field attribute name
  * @param value value as the client sent it
@@ -391,15 +414,41 @@ export declare function withoutAttributes<T extends object>(entry: T, hidden: Se
  * @throws BadRequestError naming the first DN that breaks a rule
  */
 export declare function checkDnValues(field: string, attr: SchemaAttribute, value: AttributeValue, entryExists: (dn: string) => Promise<boolean>): Promise<void>;
+/**
+ * Longest value a pattern is asked to judge when the schema declares no
+ * `maxLength`. See `docs/client-development/schemas/README.md`.
+ */
+export declare const DEFAULT_MAX_LENGTH = 4096;
+/**
+ * The length a value is judged against: `maxLength` on the attribute, else
+ * the one on its `items`, else {@link DEFAULT_MAX_LENGTH}.
+ */
+export declare function maxLengthOf(attr: SchemaAttribute | undefined): number;
 /**
  * Tell whether every value of an attribute matches its pattern: `test`, or
  * `items.test` for the elements of an array.
  *
+ * A value longer than {@link maxLengthOf} is refused without running the
+ * pattern: see {@link SchemaAttribute.maxLength}.
+ *
  * @param attr schema definition
  * @param value value submitted
- * @returns false when one value does not match
+ * @returns false when one value does not match, or is too long
  */
 export declare function matchesPattern(attr: SchemaAttribute, value: AttributeValue): boolean;
+/**
+ * The value past the length its attribute accepts, if one is: what a refusal
+ * says, where the pattern would only have said the value is wrong.
+ *
+ * The default length applies to an attribute carrying a pattern, which it
+ * keeps within what the pattern was written for; an attribute without one is
+ * bounded only by the `maxLength` its schema declares.
+ *
+ * @param attr schema definition
+ * @param value value submitted
+ * @returns the too long value, or undefined when none is
+ */
+export declare function tooLongValue(attr: SchemaAttribute, value: AttributeValue): AttributeValue | undefined;
 /**
  * Refuse a payload naming an attribute the server owns.
  *