ldap-rest 0.23.0 → 0.25.0

package/dist/plugins/ldap/passwordPolicy.js

@@ -1 +1 @@
-import{isDeepStrictEqual as e}from"node:util";import i from"../../abstract/plugin.js";import{asyncHandler as t,normalizeDn as s,escapeLdapFilter as a,validateDnValue as o,escapeDnValue as r}from"../../lib/utils.js";import{jsonBody as n}from"../../lib/expressFormatedResponses.js";import{extractLdapCode as c}from"../../lib/ldapCodes.js";import{NotFoundError as l,ConflictError as d,BadRequestError as p}from"../../lib/errors.js";const u=["pwdChangedTime","pwdAccountLockedTime","pwdFailureTime","pwdGraceUseTime","pwdReset","pwdPolicySubentry"],w={pwdMinAge:"integer",pwdMaxAge:"integer",pwdInHistory:"integer",pwdCheckQuality:"integer",pwdMinLength:"integer",pwdMaxLength:"integer",pwdExpireWarning:"integer",pwdGraceAuthNLimit:"integer",pwdGraceExpiry:"integer",pwdLockout:"boolean",pwdLockoutDuration:"integer",pwdMaxFailure:"integer",pwdFailureCountInterval:"integer",pwdMustChange:"boolean",pwdAllowUserChange:"boolean",pwdSafeModify:"boolean",pwdMinDelay:"integer",pwdMaxDelay:"integer",pwdMaxIdle:"integer",pwdMaxRecordedFailure:"integer",pwdCheckModuleArg:"text",pwdUseCheckModule:"boolean"},h=["pwdCheckModuleArg","pwdUseCheckModule"],y=[...Object.keys(w),"pwdAttribute","pwdCheckModule"],isWritablePolicyAttribute=e=>Object.prototype.hasOwnProperty.call(w,e),values=e=>(Array.isArray(e)?e:void 0===e?[]:[e]).map(e=>Buffer.isBuffer(e)?e.toString():String(e)).filter(e=>""!==e),first=e=>values(e)[0],userEntry=e=>({dn:e.dn,userPassword:first(e.userPassword),uid:first(e.uid),cn:first(e.cn),displayName:first(e.displayName),mail:first(e.mail),pwdChangedTime:first(e.pwdChangedTime),pwdAccountLockedTime:first(e.pwdAccountLockedTime),pwdFailureTime:values(e.pwdFailureTime),pwdGraceUseTime:values(e.pwdGraceUseTime),pwdReset:first(e.pwdReset),pwdPolicySubentry:first(e.pwdPolicySubentry)}),typedPolicy=e=>{const i={};for(const t of y){const s=values(e[t]);if(0!==s.length)switch(w[t]){case"integer":{const e=parseInt(s[0],10);isNaN(e)||(i[t]=e);break}case"boolean":i[t]="TRUE"===s[0];break;default:i[t]=1===s.length?s[0]:s}}return i},g=/[!@#$%^&*()_+\-=[\]{}|;:'",.<>?/]/;class PasswordPolicy extends i{constructor(){super(...arguments),this.name="ldapPasswordPolicy",this.roles=["api","configurable"],this.policyCache=new Map,this.discoveredDefault=null,this.warnedAmbiguousDefault=!1,this.warnedMissingBase=!1,this.POLICY_CACHE_TTL=6e4}api(e){const i=`${this.config.api_prefix}/v1`;e.get(`${i}/password-policy`,t(async(e,i)=>{const t=await this.readPolicyConfig();if(t.dn)try{await this.server.ldap.search({filter:"(objectClass=*)",scope:"base",attributes:["1.1"],paged:!1},t.dn,e)}catch(e){if(32!==c(e))throw e;return this.forgetPolicies(),void i.json({})}i.json(t)})),e.get(`${i}/users/:id/password-status`,t(async(e,i)=>{const t=this.param(e,"id"),s=await this.getPasswordStatus(t,e);i.json(s)})),e.post(`${i}/users/:id/unlock`,t(async(e,i)=>{const t=this.param(e,"id");await this.unlockAccount(t,e),i.json({success:!0,message:"Account unlocked"})})),e.get(`${i}/password-policy/expiring-soon`,t(async(e,i)=>{const t=parseInt(e.query.days)||this.config.ppolicy_warn_days||14,s=await this.findExpiringPasswords(t,e);i.json({warningDays:t,users:s})})),e.get(`${i}/password-policy/locked-accounts`,t(async(e,i)=>{const t=await this.findLockedAccounts(e);i.json({accounts:t})})),e.get(`${i}/password-policies`,t(async(e,i)=>{i.json({policies:await this.listPolicies(e)})})),e.post(`${i}/password-policies`,t(async(e,i)=>{const t=n(e,i);if(!t)return;const s=await this.createPolicy(t,e);i.status(201).json(s)})),e.get(`${i}/password-policies/:cn`,t(async(e,i)=>{const t=await this.findPolicy(this.param(e,"cn"),e);i.json(await this.toPolicyRecord(t))})),e.patch(`${i}/password-policies/:cn`,t(async(e,i)=>{const t=n(e,i);if(!t)return;const s=await this.updatePolicy(this.param(e,"cn"),t,e);i.json(s)})),e.delete(`${i}/password-policies/:cn`,t(async(e,i)=>{await this.deletePolicy(this.param(e,"cn"),e),i.json({success:!0})})),e.put(`${i}/users/:id/password-policy`,t(async(e,i)=>{const t=n(e,i);if(!t)return;const{policy:s}=t;if(null!==s&&("string"!=typeof s||!s))throw new p("policy must be a policy name or null");i.json(await this.assignPolicy(this.param(e,"id"),s,e))})),this.config.ppolicy_validate_complexity&&e.post(`${i}/password/validate`,t(async(e,i)=>{const t=n(e,i);if(!t)return;const{password:s}=t;if(!s)throw new p("password required");const a=this.validateComplexity(s);i.json(a)}))}async getPasswordStatus(e,i){const t=this.resolveUserDn(e),s=await this.readUser(t,e,["*",...u],i),a=await this.policyFor(s);return this.calculateStatus(t,s,a)}async readUser(e,i,t,s){try{const a=await this.server.ldap.search({filter:"(objectClass=*)",scope:"base",attributes:t,paged:!1},e,s);if(!a.searchEntries||0===a.searchEntries.length)throw new l(`User not found: ${i}`);return userEntry(a.searchEntries[0])}catch(e){if(e instanceof Error&&("NoSuchObjectError"===e.name||e.message.includes("0x20")||e.message.includes("Code: 32")))throw new l(`User not found: ${i}`);throw e}}calculateStatus(e,i,t){const s=Date.now(),a=this.parseGeneralizedTime(i.pwdChangedTime);let o=null,r=!1,n=null;t.pwdMaxAge&&a&&(o=new Date(a.getTime()+1e3*t.pwdMaxAge),r=s>o.getTime(),n=Math.ceil((o.getTime()-s)/864e5));let c=!1;const l=this.config.ppolicy_warn_days||14;null!==n&&n>0&&(c=n<=l);const d=i.pwdAccountLockedTime;let p=!!d;if(p&&!("000001010000Z"===d)&&t.pwdLockoutDuration){const e=this.parseGeneralizedTime(d);if(e){s>new Date(e.getTime()+1e3*t.pwdLockoutDuration).getTime()&&(p=!1)}}const u=i.pwdFailureTime,w=Array.isArray(u)?u.length:0,h=i.pwdGraceUseTime,y=Array.isArray(h)?h.length:0,g="TRUE"===i.pwdReset;return{dn:e,passwordSet:!!i.userPassword,lastChanged:a?.toISOString()||null,expiresAt:o?.toISOString()||null,daysUntilExpiration:n,isExpired:r,isExpiringSoon:c,mustChange:g,isLocked:p,lockedAt:d&&this.parseGeneralizedTime(d)?.toISOString()||null,failureCount:w,graceLoginsUsed:y,policy:t.dn??null}}async unlockAccount(e,i){const t=this.resolveUserDn(e),s=await this.server.ldap.search({filter:"(objectClass=*)",scope:"base",attributes:["pwdAccountLockedTime","pwdFailureTime"],paged:!1},t,i);if(!s.searchEntries||0===s.searchEntries.length)throw new l(`User not found: ${e}`);const a=userEntry(s.searchEntries[0]),o={};a.pwdAccountLockedTime&&(o.pwdAccountLockedTime=[]),a.pwdFailureTime?.length&&(o.pwdFailureTime=[]),Object.keys(o).length>0?(await this.server.ldap.modify(t,{delete:o},i),this.logger.info(`Account unlocked: ${t}`)):this.logger.info(`Account was not locked: ${t}`)}async findExpiringPasswords(e,i){const t=this.config.ldap_users_base||this.config.ldap_base,s=await this.server.ldap.search({filter:"(pwdChangedTime=*)",scope:"sub",attributes:["uid","cn","displayName","mail","pwdChangedTime","pwdPolicySubentry"],paged:!1},t,i),a=Date.now(),o=24*e*60*60*1e3,r=[];for(const e of s.searchEntries){const i=userEntry(e),t=this.parseGeneralizedTime(i.pwdChangedTime);if(!t)continue;const s=await this.policyFor(i);if(!s.pwdMaxAge)continue;const n=new Date(t.getTime()+1e3*s.pwdMaxAge),c=n.getTime()-a;c>0&&c<o&&r.push({dn:i.dn,uid:i.uid,displayName:i.displayName||i.cn,mail:i.mail,expiresAt:n.toISOString(),daysUntilExpiration:Math.ceil(c/864e5)})}return r.sort((e,i)=>e.daysUntilExpiration-i.daysUntilExpiration)}async findLockedAccounts(e){const i=this.config.ldap_users_base||this.config.ldap_base;return(await this.server.ldap.search({filter:"(pwdAccountLockedTime=*)",scope:"sub",attributes:["uid","cn","displayName","mail","pwdAccountLockedTime","pwdFailureTime"],paged:!1},i,e)).searchEntries.map(e=>{const i=userEntry(e);return{dn:i.dn,uid:i.uid,displayName:i.displayName||i.cn,mail:i.mail,lockedAt:this.parseGeneralizedTime(i.pwdAccountLockedTime)?.toISOString(),failureCount:Array.isArray(i.pwdFailureTime)?i.pwdFailureTime.length:0}})}async policyFor(e){if(e.pwdPolicySubentry){const i=await this.readPolicyAt(e.pwdPolicySubentry);if(i)return i}return this.readPolicyConfig()}async readPolicyConfig(){const e=this.config.ppolicy_default_dn||await this.discoverDefaultDn();return(e?await this.readPolicyAt(e):null)??{}}async discoverDefaultDn(){if(this.discoveredDefault&&Date.now()-this.discoveredDefault.time<this.POLICY_CACHE_TTL)return this.discoveredDefault.dn;let e=null;try{const i=(await this.server.ldap.search({filter:"(objectClass=pwdPolicy)",scope:"sub",attributes:["1.1"],paged:!1},this.policyBase())).searchEntries.map(e=>e.dn);1===i.length?e=i[0]:i.length>1&&!this.warnedAmbiguousDefault&&(this.warnedAmbiguousDefault=!0,this.logger.warn(`${i.length} password policies found and no --ppolicy-default-dn: accounts without pwdPolicySubentry are reported without a policy`))}catch(e){this.logger.debug(`No ppolicy found: ${e}`)}return this.discoveredDefault={dn:e,time:Date.now()},e}async readPolicyAt(e){const i=s(e),t=this.policyCache.get(i);if(t&&Date.now()-t.time<this.POLICY_CACHE_TTL)return t.policy;let a,o=null;try{const i=await this.server.ldap.search({filter:"(objectClass=pwdPolicy)",scope:"base",attributes:y,paged:!1},e);i.searchEntries.length>0&&(o=((e,i)=>{const t=typedPolicy(e);return{dn:i,pwdMaxAge:t.pwdMaxAge,pwdMinAge:t.pwdMinAge,pwdInHistory:t.pwdInHistory,pwdCheckQuality:t.pwdCheckQuality,pwdMinLength:t.pwdMinLength,pwdMaxFailure:t.pwdMaxFailure,pwdLockout:!0===t.pwdLockout,pwdLockoutDuration:t.pwdLockoutDuration,pwdGraceAuthNLimit:t.pwdGraceAuthNLimit,pwdExpireWarning:t.pwdExpireWarning,pwdMustChange:!0===t.pwdMustChange,pwdAllowUserChange:!1!==t.pwdAllowUserChange}})(i.searchEntries[0],e))}catch(e){a=String(e)}const r=this.config.ppolicy_default_dn;return!o&&r&&s(r)===i?this.logger.warn(`--ppolicy-default-dn ${e} holds no password policy${a?`: ${a}`:""}`):a&&this.logger.debug(`Failed to read ppolicy from ${e}: ${a}`),this.policyCache.set(i,{policy:o,time:Date.now()}),o}forgetPolicies(){this.policyCache.clear(),this.discoveredDefault=null}policyBase(){return this.config.ppolicy_base||this.config.ldap_base}async searchPolicies(e,i){try{return(await this.server.ldap.search({filter:`(&(objectClass=pwdPolicy)${e})`,scope:"sub",attributes:["objectClass","cn",...y],paged:!1},this.policyBase(),i)).searchEntries}catch(e){if(32!==c(e))throw e;return this.warnedMissingBase||(this.warnedMissingBase=!0,this.logger.warn(`${this.policyBase()} does not exist: no password policy is found there, check --ppolicy-base`)),[]}}async findPolicy(e,i){const t=await this.searchPolicies(`(cn=${a(e)})`,i);if(0===t.length)throw new l(`No password policy named ${e}`);if(t.length>1)throw new d(`Several password policies are named ${e}`);return t[0]}async listPolicies(e){const i=[];for(const t of await this.searchPolicies("",e))i.push(await this.toPolicyRecord(t));return i.sort((e,i)=>e.cn.localeCompare(i.cn))}async toPolicyRecord(e){const i=(await this.readPolicyConfig()).dn;return{...{dn:e.dn,cn:values(e.cn)[0]??"",isDefault:!!i&&s(i)===s(e.dn)},...typedPolicy(e)}}policyValue(e,i){switch(w[e]){case"integer":if("number"!=typeof i||!Number.isInteger(i)||i<0||"pwdCheckQuality"===e&&i>2)throw new p("pwdCheckQuality"===e?"pwdCheckQuality must be 0, 1 or 2":`${e} must be a non-negative integer`);return String(i);case"boolean":if("boolean"!=typeof i)throw new p(`${e} must be a boolean`);return i?"TRUE":"FALSE";default:if("string"!=typeof i||""===i)throw new p(`${e} must be a non-empty string`);return i}}async createPolicy(e,i){const{cn:t,...s}=e;if("string"!=typeof t)throw new p("cn required");try{o(t,"cn")}catch(e){throw new p(e.message)}const a=await this.findPolicy(t,i).catch(e=>{if(e instanceof l)return null;throw e});if(a)throw new d(`A password policy is named ${t}: ${a.dn}`);const n=["top","person","pwdPolicy"],u={objectClass:n,cn:t,sn:t,pwdAttribute:"userPassword"};for(const[e,i]of Object.entries(s)){if(!isWritablePolicyAttribute(e))throw new p(`${e} cannot be written`);null!==i&&(u[e]=this.policyValue(e,i))}h.some(e=>e in u)&&n.push("pwdPolicyChecker");try{await this.server.ldap.add(`cn=${r(t)},${this.policyBase()}`,u,i)}catch(e){if(32!==c(e))throw e;throw new l(`${this.policyBase()} does not exist: create it or change --ppolicy-base`)}return this.forgetPolicies(),this.toPolicyRecord(await this.findPolicy(t,i))}async updatePolicy(i,t,a){const o=await this.findPolicy(i,a),r=await this.toPolicyRecord(o),n={},c=[];for(const[i,a]of Object.entries(t)){if(!isWritablePolicyAttribute(i)){if("dn"===i?"string"==typeof a&&s(a)===s(r.dn):Object.prototype.hasOwnProperty.call(r,i)&&e(r[i],a))continue;throw new p(`${i} cannot be written`)}null!==a?n[i]=this.policyValue(i,a):void 0!==r[i]&&c.push(i)}const l={};if(Object.keys(n).length>0&&(l.replace=n),c.length>0&&(l.delete=c),!l.replace&&!l.delete)return r;const d=values(o.objectClass).map(e=>e.toLowerCase());return h.some(e=>e in n)&&!d.includes("pwdpolicychecker")&&(l.add={objectClass:"pwdPolicyChecker"}),await this.server.ldap.modify(o.dn,l,a),this.forgetPolicies(),this.toPolicyRecord(await this.findPolicy(i,a))}async deletePolicy(e,i){const t=await this.findPolicy(e,i),o=(await this.readPolicyConfig()).dn;if(o&&s(o)===s(t.dn))throw new d(`${t.dn} is the default password policy`);if((await this.server.ldap.search({filter:`(pwdPolicySubentry=${a(t.dn)})`,scope:"sub",attributes:["1.1"],sizeLimit:1,paged:!1},this.config.ldap_base)).searchEntries.length>0)throw new d(`${t.dn} is still applied to at least one entry`);await this.server.ldap.delete(t.dn,i),this.forgetPolicies()}async assignPolicy(e,i,t){const s=this.resolveUserDn(e);if(null===i){try{await this.server.ldap.modify(s,{delete:["pwdPolicySubentry"]},t)}catch(e){if(16!==c(e))throw e}return{dn:s,policy:null}}const a=await this.findPolicy(i,t);return await this.server.ldap.modify(s,{replace:{pwdPolicySubentry:a.dn}},t),{dn:s,policy:a.dn}}param(e,i){const t=e.params[i];return Array.isArray(t)?t[0]:t}parseGeneralizedTime(e){if(!e)return null;const i=e.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/);if(!i)return null;const[,t,s,a,o,r,n]=i;return new Date(Date.UTC(+t,+s-1,+a,+o,+r,+n))}validateComplexity(e){const i=[],t=this.config,s=t.ppolicy_min_length||12;return e.length<s&&i.push(`Minimum ${s} characters required`),t.ppolicy_require_uppercase&&!/[A-Z]/.test(e)&&i.push("At least one uppercase letter required"),t.ppolicy_require_lowercase&&!/[a-z]/.test(e)&&i.push("At least one lowercase letter required"),t.ppolicy_require_digit&&!/\d/.test(e)&&i.push("At least one digit required"),t.ppolicy_require_special&&!g.test(e)&&i.push("At least one special character required"),{valid:0===i.length,errors:i}}resolveUserDn(e){if(e.includes("="))return e;const i=this.config.ldap_users_base||this.config.ldap_base;return`${this.config.ldap_user_main_attribute||"uid"}=${r(e)},${i}`}getConfigApiData(){const e=this.config.api_prefix||"/api",i=!!this.config.ppolicy_validate_complexity;return{name:this.name,enabled:!0,endpoints:{getPolicy:`${e}/v1/password-policy`,getUserStatus:`${e}/v1/users/:id/password-status`,unlockUser:`${e}/v1/users/:id/unlock`,getExpiringSoon:`${e}/v1/password-policy/expiring-soon`,getLockedAccounts:`${e}/v1/password-policy/locked-accounts`,listPolicies:`${e}/v1/password-policies`,policy:`${e}/v1/password-policies/:cn`,assignPolicy:`${e}/v1/users/:id/password-policy`,validatePassword:i?`${e}/v1/password/validate`:void 0},config:{warnDays:this.config.ppolicy_warn_days||14,validateComplexity:i,...i&&{complexityRules:{minLength:this.config.ppolicy_min_length||12,requireUppercase:this.config.ppolicy_require_uppercase??!0,requireLowercase:this.config.ppolicy_require_lowercase??!0,requireDigit:this.config.ppolicy_require_digit??!0,requireSpecial:this.config.ppolicy_require_special??!0}}}}}}export{PasswordPolicy as default};
+import{isDeepStrictEqual as e}from"node:util";import t from"../../abstract/plugin.js";import{asyncHandler as i,normalizeDn as s,escapeLdapFilter as a,validateDnValue as r,escapeDnValue as o}from"../../lib/utils.js";import{jsonBody as n}from"../../lib/expressFormatedResponses.js";import{extractLdapCode as c}from"../../lib/ldapCodes.js";import{NotFoundError as l,ConflictError as d,BadRequestError as p}from"../../lib/errors.js";const u=["pwdChangedTime","pwdAccountLockedTime","pwdFailureTime","pwdGraceUseTime","pwdReset","pwdPolicySubentry"],h={pwdMinAge:"integer",pwdMaxAge:"integer",pwdInHistory:"integer",pwdCheckQuality:"integer",pwdMinLength:"integer",pwdMaxLength:"integer",pwdExpireWarning:"integer",pwdGraceAuthNLimit:"integer",pwdGraceExpiry:"integer",pwdLockout:"boolean",pwdLockoutDuration:"integer",pwdMaxFailure:"integer",pwdFailureCountInterval:"integer",pwdMustChange:"boolean",pwdAllowUserChange:"boolean",pwdSafeModify:"boolean",pwdMinDelay:"integer",pwdMaxDelay:"integer",pwdMaxIdle:"integer",pwdMaxRecordedFailure:"integer",pwdCheckModuleArg:"text",pwdUseCheckModule:"boolean"},w=["pwdCheckModuleArg","pwdUseCheckModule"],y=[...Object.keys(h),"pwdAttribute","pwdCheckModule"],isWritablePolicyAttribute=e=>Object.prototype.hasOwnProperty.call(h,e),values=e=>(Array.isArray(e)?e:void 0===e?[]:[e]).map(e=>Buffer.isBuffer(e)?e.toString():String(e)).filter(e=>""!==e),first=e=>values(e)[0],userEntry=e=>({dn:e.dn,userPassword:first(e.userPassword),uid:first(e.uid),cn:first(e.cn),displayName:first(e.displayName),mail:first(e.mail),pwdChangedTime:first(e.pwdChangedTime),pwdAccountLockedTime:first(e.pwdAccountLockedTime),pwdFailureTime:values(e.pwdFailureTime),pwdGraceUseTime:values(e.pwdGraceUseTime),pwdReset:first(e.pwdReset),pwdPolicySubentry:first(e.pwdPolicySubentry)}),typedPolicy=e=>{const t={};for(const i of y){const s=values(e[i]);if(0!==s.length)switch(h[i]){case"integer":{const e=parseInt(s[0],10);isNaN(e)||(t[i]=e);break}case"boolean":t[i]="TRUE"===s[0];break;default:t[i]=1===s.length?s[0]:s}}return t},g=/[!@#$%^&*()_+\-=[\]{}|;:'",.<>?/]/;class PasswordPolicy extends t{constructor(){super(...arguments),this.name="ldapPasswordPolicy",this.roles=["api","configurable"],this.policyCache=new Map,this.discoveredDefault=null,this.warnedAmbiguousDefault=!1,this.warnedMissingBase=!1,this.warnedUnreadableSchema=!1,this.POLICY_CACHE_TTL=6e4}api(e){const t=`${this.config.api_prefix}/v1`;e.get(`${t}/password-policy`,i(async(e,t)=>{const i=await this.readPolicyConfig();if(i.dn)try{await this.server.ldap.search({filter:"(objectClass=*)",scope:"base",attributes:["1.1"],paged:!1},i.dn,e)}catch(e){if(32!==c(e))throw e;return this.forgetPolicies(),void t.json({})}t.json(i)})),e.get(`${t}/users/:id/password-status`,i(async(e,t)=>{const i=this.param(e,"id"),s=await this.getPasswordStatus(i,e);t.json(s)})),e.post(`${t}/users/:id/unlock`,i(async(e,t)=>{const i=this.param(e,"id");await this.unlockAccount(i,e),t.json({success:!0,message:"Account unlocked"})})),e.get(`${t}/password-policy/expiring-soon`,i(async(e,t)=>{const i=parseInt(e.query.days)||this.config.ppolicy_warn_days||14,s=await this.findExpiringPasswords(i,e);t.json({warningDays:i,users:s})})),e.get(`${t}/password-policy/locked-accounts`,i(async(e,t)=>{const i=await this.findLockedAccounts(e);t.json({accounts:i})})),e.get(`${t}/password-policies`,i(async(e,t)=>{t.json({policies:await this.listPolicies(e),attributes:await this.definedAttributes()})})),e.post(`${t}/password-policies`,i(async(e,t)=>{const i=n(e,t);if(!i)return;const s=await this.createPolicy(i,e);t.status(201).json(s)})),e.get(`${t}/password-policies/:cn`,i(async(e,t)=>{const i=await this.findPolicy(this.param(e,"cn"),e);t.json(await this.toPolicyRecord(i))})),e.patch(`${t}/password-policies/:cn`,i(async(e,t)=>{const i=n(e,t);if(!i)return;const s=await this.updatePolicy(this.param(e,"cn"),i,e);t.json(s)})),e.delete(`${t}/password-policies/:cn`,i(async(e,t)=>{await this.deletePolicy(this.param(e,"cn"),e),t.json({success:!0})})),e.put(`${t}/users/:id/password-policy`,i(async(e,t)=>{const i=n(e,t);if(!i)return;const{policy:s}=i;if(null!==s&&("string"!=typeof s||!s))throw new p("policy must be a policy name or null");t.json(await this.assignPolicy(this.param(e,"id"),s,e))})),this.config.ppolicy_validate_complexity&&e.post(`${t}/password/validate`,i(async(e,t)=>{const i=n(e,t);if(!i)return;const{password:s}=i;if(!s)throw new p("password required");const a=this.validateComplexity(s);t.json(a)}))}async getPasswordStatus(e,t){const i=this.resolveUserDn(e),s=await this.readUser(i,e,["*",...u],t),a=await this.policyFor(s);return this.calculateStatus(i,s,a)}async readUser(e,t,i,s){try{const a=await this.server.ldap.search({filter:"(objectClass=*)",scope:"base",attributes:i,paged:!1},e,s);if(!a.searchEntries||0===a.searchEntries.length)throw new l(`User not found: ${t}`);return userEntry(a.searchEntries[0])}catch(e){if(e instanceof Error&&("NoSuchObjectError"===e.name||e.message.includes("0x20")||e.message.includes("Code: 32")))throw new l(`User not found: ${t}`);throw e}}calculateStatus(e,t,i){const s=Date.now(),a=this.parseGeneralizedTime(t.pwdChangedTime);let r=null,o=!1,n=null;i.pwdMaxAge&&a&&(r=new Date(a.getTime()+1e3*i.pwdMaxAge),o=s>r.getTime(),n=Math.ceil((r.getTime()-s)/864e5));let c=!1;const l=this.config.ppolicy_warn_days||14;null!==n&&n>0&&(c=n<=l);const d=t.pwdAccountLockedTime;let p=!!d;if(p&&!("000001010000Z"===d)&&i.pwdLockoutDuration){const e=this.parseGeneralizedTime(d);if(e){s>new Date(e.getTime()+1e3*i.pwdLockoutDuration).getTime()&&(p=!1)}}const u=t.pwdFailureTime,h=Array.isArray(u)?u.length:0,w=t.pwdGraceUseTime,y=Array.isArray(w)?w.length:0,g="TRUE"===t.pwdReset;return{dn:e,passwordSet:!!t.userPassword,lastChanged:a?.toISOString()||null,expiresAt:r?.toISOString()||null,daysUntilExpiration:n,isExpired:o,isExpiringSoon:c,mustChange:g,isLocked:p,lockedAt:d&&this.parseGeneralizedTime(d)?.toISOString()||null,failureCount:h,graceLoginsUsed:y,policy:i.dn??null}}async unlockAccount(e,t){const i=this.resolveUserDn(e),s=await this.server.ldap.search({filter:"(objectClass=*)",scope:"base",attributes:["pwdAccountLockedTime","pwdFailureTime"],paged:!1},i,t);if(!s.searchEntries||0===s.searchEntries.length)throw new l(`User not found: ${e}`);const a=userEntry(s.searchEntries[0]),r={};a.pwdAccountLockedTime&&(r.pwdAccountLockedTime=[]),a.pwdFailureTime?.length&&(r.pwdFailureTime=[]),Object.keys(r).length>0?(await this.server.ldap.modify(i,{delete:r},t),this.logger.info(`Account unlocked: ${i}`)):this.logger.info(`Account was not locked: ${i}`)}async findExpiringPasswords(e,t){const i=this.config.ldap_users_base||this.config.ldap_base,s=await this.server.ldap.search({filter:"(pwdChangedTime=*)",scope:"sub",attributes:["uid","cn","displayName","mail","pwdChangedTime","pwdPolicySubentry"],paged:!1},i,t),a=Date.now(),r=24*e*60*60*1e3,o=[];for(const e of s.searchEntries){const t=userEntry(e),i=this.parseGeneralizedTime(t.pwdChangedTime);if(!i)continue;const s=await this.policyFor(t);if(!s.pwdMaxAge)continue;const n=new Date(i.getTime()+1e3*s.pwdMaxAge),c=n.getTime()-a;c>0&&c<r&&o.push({dn:t.dn,uid:t.uid,displayName:t.displayName||t.cn,mail:t.mail,expiresAt:n.toISOString(),daysUntilExpiration:Math.ceil(c/864e5)})}return o.sort((e,t)=>e.daysUntilExpiration-t.daysUntilExpiration)}async findLockedAccounts(e){const t=this.config.ldap_users_base||this.config.ldap_base;return(await this.server.ldap.search({filter:"(pwdAccountLockedTime=*)",scope:"sub",attributes:["uid","cn","displayName","mail","pwdAccountLockedTime","pwdFailureTime"],paged:!1},t,e)).searchEntries.map(e=>{const t=userEntry(e);return{dn:t.dn,uid:t.uid,displayName:t.displayName||t.cn,mail:t.mail,lockedAt:this.parseGeneralizedTime(t.pwdAccountLockedTime)?.toISOString(),failureCount:Array.isArray(t.pwdFailureTime)?t.pwdFailureTime.length:0}})}async policyFor(e){if(e.pwdPolicySubentry){const t=await this.readPolicyAt(e.pwdPolicySubentry);if(t)return t}return this.readPolicyConfig()}async readPolicyConfig(){const e=this.config.ppolicy_default_dn||await this.discoverDefaultDn();return(e?await this.readPolicyAt(e):null)??{}}async discoverDefaultDn(){if(this.discoveredDefault&&Date.now()-this.discoveredDefault.time<this.POLICY_CACHE_TTL)return this.discoveredDefault.dn;let e=null;try{const t=(await this.server.ldap.search({filter:"(objectClass=pwdPolicy)",scope:"sub",attributes:["1.1"],paged:!1},this.policyBase())).searchEntries.map(e=>e.dn);1===t.length?e=t[0]:t.length>1&&!this.warnedAmbiguousDefault&&(this.warnedAmbiguousDefault=!0,this.logger.warn(`${t.length} password policies found and no --ppolicy-default-dn: accounts without pwdPolicySubentry are reported without a policy`))}catch(e){this.logger.debug(`No ppolicy found: ${e}`)}return this.discoveredDefault={dn:e,time:Date.now()},e}async readPolicyAt(e){const t=s(e),i=this.policyCache.get(t);if(i&&Date.now()-i.time<this.POLICY_CACHE_TTL)return i.policy;let a,r=null;try{const t=await this.server.ldap.search({filter:"(objectClass=pwdPolicy)",scope:"base",attributes:y,paged:!1},e);t.searchEntries.length>0&&(r=((e,t)=>{const i=typedPolicy(e);return{dn:t,pwdMaxAge:i.pwdMaxAge,pwdMinAge:i.pwdMinAge,pwdInHistory:i.pwdInHistory,pwdCheckQuality:i.pwdCheckQuality,pwdMinLength:i.pwdMinLength,pwdMaxFailure:i.pwdMaxFailure,pwdLockout:!0===i.pwdLockout,pwdLockoutDuration:i.pwdLockoutDuration,pwdGraceAuthNLimit:i.pwdGraceAuthNLimit,pwdExpireWarning:i.pwdExpireWarning,pwdMustChange:!0===i.pwdMustChange,pwdAllowUserChange:!1!==i.pwdAllowUserChange}})(t.searchEntries[0],e))}catch(e){a=String(e)}const o=this.config.ppolicy_default_dn;return!r&&o&&s(o)===t?this.logger.warn(`--ppolicy-default-dn ${e} holds no password policy${a?`: ${a}`:""}`):a&&this.logger.debug(`Failed to read ppolicy from ${e}: ${a}`),this.policyCache.set(t,{policy:r,time:Date.now()}),r}forgetPolicies(){this.policyCache.clear(),this.discoveredDefault=null}policyBase(){return this.config.ppolicy_base||this.config.ldap_base}async searchPolicies(e,t){try{return(await this.server.ldap.search({filter:`(&(objectClass=pwdPolicy)${e})`,scope:"sub",attributes:["objectClass","cn",...y],paged:!1},this.policyBase(),t)).searchEntries}catch(e){if(32!==c(e))throw e;return this.warnedMissingBase||(this.warnedMissingBase=!0,this.logger.warn(`${this.policyBase()} does not exist: no password policy is found there, check --ppolicy-base`)),[]}}async findPolicy(e,t){const i=await this.searchPolicies(`(cn=${a(e)})`,t);if(0===i.length)throw new l(`No password policy named ${e}`);if(i.length>1)throw new d(`Several password policies are named ${e}`);return i[0]}async listPolicies(e){const t=[];for(const i of await this.searchPolicies("",e))t.push(await this.toPolicyRecord(i));return t.sort((e,t)=>e.cn.localeCompare(t.cn))}async definedAttributes(){const e=Object.keys(h);try{const t=await this.server.ldap.schemaIndex();return e.filter(e=>t.getAttributeType(e))}catch(t){return this.warnedUnreadableSchema||(this.warnedUnreadableSchema=!0,this.logger.warn(`Unable to read the schema, every policy attribute is listed: ${String(t)}`)),e}}async toPolicyRecord(e){const t=(await this.readPolicyConfig()).dn;return{...{dn:e.dn,cn:values(e.cn)[0]??"",isDefault:!!t&&s(t)===s(e.dn)},...typedPolicy(e)}}policyValue(e,t){switch(h[e]){case"integer":if("number"!=typeof t||!Number.isInteger(t)||t<0||"pwdCheckQuality"===e&&t>2)throw new p("pwdCheckQuality"===e?"pwdCheckQuality must be 0, 1 or 2":`${e} must be a non-negative integer`);return String(t);case"boolean":if("boolean"!=typeof t)throw new p(`${e} must be a boolean`);return t?"TRUE":"FALSE";default:if("string"!=typeof t||""===t)throw new p(`${e} must be a non-empty string`);return t}}async createPolicy(e,t){const{cn:i,...s}=e;if("string"!=typeof i)throw new p("cn required");try{r(i,"cn")}catch(e){throw new p(e.message)}const a=await this.findPolicy(i,t).catch(e=>{if(e instanceof l)return null;throw e});if(a)throw new d(`A password policy is named ${i}: ${a.dn}`);const n=["top","person","pwdPolicy"],u={objectClass:n,cn:i,sn:i,pwdAttribute:"userPassword"};for(const[e,t]of Object.entries(s)){if(!isWritablePolicyAttribute(e))throw new p(`${e} cannot be written`);null!==t&&(u[e]=this.policyValue(e,t))}w.some(e=>e in u)&&n.push("pwdPolicyChecker");try{await this.server.ldap.add(`cn=${o(i)},${this.policyBase()}`,u,t)}catch(e){if(32!==c(e))throw e;throw new l(`${this.policyBase()} does not exist: create it or change --ppolicy-base`)}return this.forgetPolicies(),this.toPolicyRecord(await this.findPolicy(i,t))}async updatePolicy(t,i,a){const r=await this.findPolicy(t,a),o=await this.toPolicyRecord(r),n={},c=[];for(const[t,a]of Object.entries(i)){if(!isWritablePolicyAttribute(t)){if("dn"===t?"string"==typeof a&&s(a)===s(o.dn):Object.prototype.hasOwnProperty.call(o,t)&&e(o[t],a))continue;throw new p(`${t} cannot be written`)}null!==a?n[t]=this.policyValue(t,a):void 0!==o[t]&&c.push(t)}const l={};if(Object.keys(n).length>0&&(l.replace=n),c.length>0&&(l.delete=c),!l.replace&&!l.delete)return o;const d=values(r.objectClass).map(e=>e.toLowerCase());return w.some(e=>e in n)&&!d.includes("pwdpolicychecker")&&(l.add={objectClass:"pwdPolicyChecker"}),await this.server.ldap.modify(r.dn,l,a),this.forgetPolicies(),this.toPolicyRecord(await this.findPolicy(t,a))}async deletePolicy(e,t){const i=await this.findPolicy(e,t),r=(await this.readPolicyConfig()).dn;if(r&&s(r)===s(i.dn))throw new d(`${i.dn} is the default password policy`);if((await this.server.ldap.search({filter:`(pwdPolicySubentry=${a(i.dn)})`,scope:"sub",attributes:["1.1"],sizeLimit:1,paged:!1},this.config.ldap_base)).searchEntries.length>0)throw new d(`${i.dn} is still applied to at least one entry`);await this.server.ldap.delete(i.dn,t),this.forgetPolicies()}async assignPolicy(e,t,i){const s=this.resolveUserDn(e);if(null===t){try{await this.server.ldap.modify(s,{delete:["pwdPolicySubentry"]},i)}catch(e){if(16!==c(e))throw e}return{dn:s,policy:null}}const a=await this.findPolicy(t,i);return await this.server.ldap.modify(s,{replace:{pwdPolicySubentry:a.dn}},i),{dn:s,policy:a.dn}}param(e,t){const i=e.params[t];return Array.isArray(i)?i[0]:i}parseGeneralizedTime(e){if(!e)return null;const t=e.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/);if(!t)return null;const[,i,s,a,r,o,n]=t;return new Date(Date.UTC(+i,+s-1,+a,+r,+o,+n))}validateComplexity(e){const t=[],i=this.config,s=i.ppolicy_min_length||12;return e.length<s&&t.push(`Minimum ${s} characters required`),i.ppolicy_require_uppercase&&!/[A-Z]/.test(e)&&t.push("At least one uppercase letter required"),i.ppolicy_require_lowercase&&!/[a-z]/.test(e)&&t.push("At least one lowercase letter required"),i.ppolicy_require_digit&&!/\d/.test(e)&&t.push("At least one digit required"),i.ppolicy_require_special&&!g.test(e)&&t.push("At least one special character required"),{valid:0===t.length,errors:t}}resolveUserDn(e){if(e.includes("="))return e;const t=this.config.ldap_users_base||this.config.ldap_base;return`${this.config.ldap_user_main_attribute||"uid"}=${o(e)},${t}`}getConfigApiData(){const e=this.config.api_prefix||"/api",t=!!this.config.ppolicy_validate_complexity;return{name:this.name,enabled:!0,endpoints:{getPolicy:`${e}/v1/password-policy`,getUserStatus:`${e}/v1/users/:id/password-status`,unlockUser:`${e}/v1/users/:id/unlock`,getExpiringSoon:`${e}/v1/password-policy/expiring-soon`,getLockedAccounts:`${e}/v1/password-policy/locked-accounts`,listPolicies:`${e}/v1/password-policies`,policy:`${e}/v1/password-policies/:cn`,assignPolicy:`${e}/v1/users/:id/password-policy`,validatePassword:t?`${e}/v1/password/validate`:void 0},config:{warnDays:this.config.ppolicy_warn_days||14,validateComplexity:t,...t&&{complexityRules:{minLength:this.config.ppolicy_min_length||12,requireUppercase:this.config.ppolicy_require_uppercase??!0,requireLowercase:this.config.ppolicy_require_lowercase??!0,requireDigit:this.config.ppolicy_require_digit??!0,requireSpecial:this.config.ppolicy_require_special??!0}}}}}}export{PasswordPolicy as default};

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

@@ -125,6 +125,12 @@ export interface Config {
      * organization is in transit too, with or without this option.
      */
     authz_transit_branch?: string;
+    /**
+     * The attribute an entry put in transit keeps the organization it leaves
+     * in, removed when it is claimed: who claims it can tell where it comes
+     * from. Empty records nothing. It must exist in the directory's schema.
+     */
+    authz_transit_origin_attribute?: string;
     authz_unresolved_user?: string;
     authz_identity?: string;
     /**

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

@@ -217,10 +217,12 @@ export interface SchemaAttribute {
      */
     states?: Record<string, AttributeValue>;
     /**
-     * For a `pointer`: refuse to delete the entry it points at while any entry
-     * still references it. `ignore` (the default) leaves the reference dangling.
+     * For a `pointer`, or a list of them: what deleting the entry it points at
+     * does to the reference. `restrict` refuses the deletion while any entry
+     * still references it; `remove` takes the deleted DN out of the attribute;
+     * `ignore` (the default) leaves the reference dangling.
      */
-    referentialIntegrity?: 'restrict' | 'ignore';
+    referentialIntegrity?: 'restrict' | 'remove' | 'ignore';
     /**
      * For a `members`-role attribute: refuse to delete the entry while it still
      * has members. The placeholder member some directories need to keep a

package/dist/src/lib/authz/base.d.ts

@@ -63,6 +63,24 @@ export default abstract class AuthzBase extends DmPlugin {
      * only a caller holding the branch reads. None unless a plugin names some.
      */
     protected globalBranches(): string[];
+    /**
+     * Why `user` may not search under `base`, or `undefined` when they may:
+     * the judgement of `ldapsearchrequest`, for `authzScope` to ask it of a
+     * branch without searching it.
+     *
+     * Filtering, an administrator reads the directory whole — the
+     * organization tree, the groups, the nomenclatures — and what is held to
+     * a branch is the accounts, recognised one entry at a time by
+     * `ldapsearchfilter`; only a global branch asks for the branch itself.
+     * Otherwise the branch decides. Where a branch is a tenant rather than a
+     * department, letting a listing cross it is letting a customer read
+     * another.
+     *
+     * @param user the caller's DN
+     * @param base the base of the search
+     * @returns the end of the refusal's message, after the caller's name
+     */
+    searchRefusal(user: string, base: string): Promise<string | undefined>;
     /**
      * What taking an entry out of a branch, by a move or a rename, asks of
      * the caller there: read, by default, the destination being judged on
@@ -100,6 +118,27 @@ export default abstract class AuthzBase extends DmPlugin {
      * @param key the transit branch as {@link transitKey} gives it
      */
     protected inTransit(link: string | undefined, key?: string | undefined): boolean;
+    /**
+     * The attribute an entry in transit keeps the organization it was handed
+     * over from in: `--authz-transit-origin-attribute`, with a transit branch
+     * to hand it over through. `undefined` records nothing.
+     */
+    protected transitOriginAttribute(): string | undefined;
+    /**
+     * A modify that changes an entry's organization link, with the origin of
+     * a hand-over recorded: put in transit, the entry keeps the organization
+     * it leaves in {@link transitOriginAttribute}; claimed out of it, it loses
+     * it. The administrator who claims it can then tell where it comes from.
+     *
+     * The changes are left alone when they already name the attribute, and
+     * when the stored entry cannot be read: a failed read must not cost the
+     * move itself, which is judged elsewhere.
+     *
+     * @param dn the entry modified
+     * @param changes the modify as it stands
+     * @returns the modify, with the origin set or removed
+     */
+    protected recordTransitOrigin(dn: string, changes: ModifyRequest): Promise<ModifyRequest>;
     /**
      * The transit branch in the form DNs are compared in. A listing asks once
      * and hands it to {@link inTransit} for every entry, rather than parsing

package/dist/src/lib/errors.d.ts

@@ -7,7 +7,27 @@
  */
 export declare class HttpError extends Error {
     statusCode: number;
-    constructor(message: string, statusCode?: number);
+    refusal?: Refusal | undefined;
+    constructor(message: string, statusCode?: number, refusal?: Refusal | undefined);
+}
+/**
+ * What a client is told of a refusal besides its sentence: enough to say it
+ * in its own language and next to the field at fault, without reading the
+ * sentence back. Added to the `error` field of the answer, never in place
+ * of it.
+ */
+export interface Refusal {
+    /**
+     * `unique` (a value already used), `mailDomain` (an address outside the
+     * authorised domains) or `forbidden` (an authorization plugin refused)
+     */
+    code: 'unique' | 'mailDomain' | 'forbidden';
+    /** The attribute refused */
+    attribute?: string;
+    /** The value refused */
+    value?: string;
+    /** The authorised mail domains, for `mailDomain` */
+    domains?: string[];
 }
 /**
  * Client errors (4xx)
@@ -23,6 +43,19 @@ export declare class UnauthorizedError extends HttpError {
  * threw names the branch, which the caller may not know of.
  */
 export declare const AUTHZ_REFUSED = "Token does not have permission on this branch";
+/**
+ * The JSON answer of a client error: its sentence, and the refusal it
+ * carries. An authorization plugin's refusal carries none — its message names
+ * the branch, which is why the client is told `AUTHZ_REFUSED` — so the code
+ * is given here, from the sentence the caller settled on.
+ *
+ * @param err the error thrown
+ * @param message the sentence the client is told
+ * @returns the body to answer
+ */
+export declare const errorBody: (err: unknown, message: string) => {
+    error: string;
+} & Partial<Refusal>;
 export declare class ForbiddenError extends HttpError {
     constructor(message?: string);
 }
@@ -45,7 +78,7 @@ export declare class NotFoundError extends HttpError {
     constructor(message?: string);
 }
 export declare class ConflictError extends HttpError {
-    constructor(message?: string);
+    constructor(message?: string, refusal?: Refusal);
 }
 export declare class UriTooLongError extends HttpError {
     constructor(message?: string);

package/dist/src/lib/utils.d.ts

@@ -313,6 +313,18 @@ export declare function organizationLink(value: AttributeValue | undefined): str
  * ```
  */
 export declare function isDnInBranch(dn: string, base: string): boolean;
+/**
+ * Tell whether a rename moved an entry into the trash branch.
+ *
+ * `core/ldap/trash` turns a deletion into such a move, so the DN it frees is
+ * as free as a deleted one, without any `ldapdeletedone`.
+ *
+ * @param trashBase the `--trash-base`, if any
+ * @param oldDn DN before the rename
+ * @param newDn DN after it
+ * @returns true when the entry entered the trash branch
+ */
+export declare function movedToTrash(trashBase: string | undefined, oldDn: string, newDn: string): boolean;
 /**
  * Wrapper for async Express route handlers to catch errors and pass them to error middleware
  * This ensures that errors in async routes are properly handled and don't crash the server

package/dist/src/plugins/auth/authzScope.d.ts

@@ -83,6 +83,25 @@ export default class AuthzScope extends DmPlugin {
      * @param res Express response
      */
     private scope;
+    /** The password policy plugin, when loaded. */
+    private policyPlugin;
+    /**
+     * The `passwordPolicies` field: nothing when no plugin serves the policies,
+     * so that "not served" is not read as "not yours".
+     *
+     * @param may whether the caller may list them
+     */
+    private passwordPolicies;
+    /**
+     * Whether the describing plugin lets the caller list the password
+     * policies: the judgement its search hook makes of the listing, asked
+     * without the listing. A plugin that cannot say does not offer them, as
+     * `linksAnyDomain` does not.
+     *
+     * @param authz the describing plugin
+     * @param user the caller's DN
+     */
+    private readsPolicies;
     /**
      * Read the display name and path of a branch, so a client can show the
      * scope in the words the directory uses rather than as a raw DN.

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

@@ -54,6 +54,16 @@ import type { DM } from '../../bin';
  *           error:
  *             type: string
  *             description: Error message.
+ *           code:
+ *             type: string
+ *             description: |
+ *               `unique` or `mailDomain`, with `attribute`, `value` and
+ *               `domains`, as in the `Error` answer of a single write.
+ *           attribute: { type: string }
+ *           value: { type: string }
+ *           domains:
+ *             type: array
+ *             items: { type: string }
  *       example:
  *         - line: 5
  *           identifier: bob

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

@@ -5,7 +5,7 @@
  * Business rules an enterprise directory needs on top of declarative schema
  * validation: uniqueness across a shared namespace, mail addresses confined to
  * the domains an organization owns, computed organization paths, normalised
- * quotas, and referential-integrity guards on deletion.
+ * quotas, and referential integrity on deletion.
  *
  * Nothing here knows a concrete attribute name, a domain, or a nomenclature
  * value. Every rule is driven by the loaded entity schemas — their semantic
@@ -23,8 +23,9 @@
  *
  * ## What "a reference" is, and the one case this cannot see
  *
- * Two rules — the delete guard and the rename cascade — have to find every
- * entry naming another one by its DN. They look in two places, both declared
+ * Three rules — the delete guard, the removal of a deleted DN and the rename
+ * cascade — have to find every entry naming another one by its DN. They look
+ * in two places, both declared
  * by the schemas: every `pointer` (single, or under `items`) whose `branch`
  * admits the target, and every attribute carrying the `members` or `owners`
  * role. The second is not redundant: a group's member list cannot be a
@@ -33,8 +34,8 @@
  *
  * A deployment whose schema stores a DN in an attribute that is neither of
  * those — a plain `string` carrying no role — is therefore not covered: its
- * value is left naming the old DN after a rename, and does not hold a
- * deletion back. Declare such an attribute as a `pointer`, or give it the
+ * value is left naming the old DN after a rename, does not hold a deletion
+ * back, and is not removed when that DN is deleted. Declare such an attribute as a `pointer`, or give it the
  * role it plays. No marker is invented here to cover the gap: a marker
  * meaning "this happens to contain a DN" would be a third way of saying what
  * `pointer` and the roles already say.
@@ -225,7 +226,8 @@ export default class LdapEnterpriseRules extends DmPlugin {
      * Refuse a mail address outside the domains its organization may use.
      *
      * @param entity entity the entry belongs to
-     * @param attr schema definition of the mail attribute
+     * @param name the mail attribute
+     * @param attr its schema definition
      * @param values addresses submitted
      * @param submitted attributes as submitted, read for the organization link
      * @param current entry as stored, when the link is not being changed
@@ -295,10 +297,26 @@ export default class LdapEnterpriseRules extends DmPlugin {
      * @throws ConflictError naming the first referencing entry
      */
     private guardReferences;
+    /**
+     * Take a deleted DN out of every `referentialIntegrity: remove` pointer
+     * still naming it.
+     *
+     * Written with the server's own rights, not the caller's: the deletion was
+     * authorized, and the entries naming it are often outside what the caller
+     * may write — the organization a deleted account administered. A link left
+     * behind is a right waiting for the next entry given the same DN.
+     *
+     * A failure is logged, not thrown: the entry is already gone.
+     *
+     * @param dn entry just deleted
+     * @param context change context of the deletion, to attribute these writes
+     */
+    private removeReferences;
     /**
      * Every attribute of every loaded entity that could hold this DN.
      *
-     * This is the traversal the delete guard and the rename cascade share: it
+     * This is the traversal the delete guard, the removal and the rename
+     * cascade share: it
      * knows no attribute name, only what the schemas declare — a `pointer`
      * (single or under `items`) whose `branch` admits the DN's parent, or an
      * attribute carrying the `members` or `owners` role. The module header says

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

@@ -80,12 +80,35 @@ export type postModify = ModifyRequest;
  *     description: Updated description
  * Error:
  *   type: object
+ *   required: [error]
  *   properties:
- *     error: { type: string }
- *     code: { type: integer }
+ *     error:
+ *       type: string
+ *       description: What was refused, in English.
+ *     code:
+ *       type: string
+ *       description: |
+ *         For a client to explain the refusal in its own words, when there
+ *         is one: `unique` (a value already used), `mailDomain` (an address
+ *         outside the authorised mail domains), `forbidden` (the caller may
+ *         not act on this branch). Absent for any other refusal, which only
+ *         `error` describes. The Twake groups API answers its own codes
+ *         (`INVALID_INPUT`, `REFUSED`…).
+ *     attribute:
+ *       type: string
+ *       description: The attribute refused, for `unique` and `mailDomain`.
+ *     value:
+ *       type: string
+ *       description: The value refused, for `unique` and `mailDomain`.
+ *     domains:
+ *       type: array
+ *       items: { type: string }
+ *       description: The authorised mail domains, for `mailDomain`.
  *   example:
- *     error: Group not found
- *     code: 404
+ *     error: 'entity: "value" is already used (attribute must be unique)'
+ *     code: unique
+ *     attribute: attribute
+ *     value: value
  */
 export default class LdapGroups extends DmPlugin {
     name: string;
@@ -103,7 +126,8 @@ export default class LdapGroups extends DmPlugin {
     /**
      * Remove deleted entries from groups once the delete has landed: a delete
      * refused, failed or turned into something else by another plugin leaves
-     * the memberships alone.
+     * the memberships alone — except a move into the trash, which frees the DN
+     * all the same.
      */
     hooks: Hooks;
     /**

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

@@ -239,6 +239,7 @@ export default class PasswordPolicy extends DmPlugin {
     private discoveredDefault;
     private warnedAmbiguousDefault;
     private warnedMissingBase;
+    private warnedUnreadableSchema;
     private readonly POLICY_CACHE_TTL;
     api(app: Express): void;
     /**
@@ -288,7 +289,11 @@ export default class PasswordPolicy extends DmPlugin {
      */
     private readPolicyAt;
     private forgetPolicies;
-    private policyBase;
+    /**
+     * Where the policies are listed from: `--ppolicy-base`, else
+     * `--ldap-base`. `authzScope` asks whether a caller may search it.
+     */
+    policyBase(): string;
     /**
      * The policy entries under the policy base matching `filter`, none when
      * the base itself is missing
@@ -299,6 +304,13 @@ export default class PasswordPolicy extends DmPlugin {
      */
     private findPolicy;
     private listPolicies;
+    /**
+     * The writable policy attributes the directory's schema defines: OpenLDAP
+     * 2.4 lacks pwdMaxLength, pwdMaxIdle, pwdMinDelay and pwdMaxDelay, and
+     * only 2.6 has the checker's. All of them when the schema cannot be read:
+     * the directory still refuses what it lacks.
+     */
+    private definedAttributes;
     private toPolicyRecord;
     /**
      * The directory form of a value a client sent for policy attribute `name`

package/docs/client-development/api/rest-api.md

@@ -1142,6 +1142,20 @@ All errors return a JSON object with an error message:
 }
 ```
 
+The message is English, for a log or a developer. The refusals a client is
+expected to explain to its users carry a `code` too, and what was refused,
+for the client to say it in its own words and next to the field at fault.
+`error` is always there; read the other fields only when `code` is:
+
+| `code`       | Status | Refusal                                                      | Other fields                    |
+| ------------ | ------ | ------------------------------------------------------------ | ------------------------------- |
+| `unique`     | 409    | A value another entry already holds                          | `attribute`, `value`            |
+| `mailDomain` | 409    | An address outside the mail domains its organization may use | `attribute`, `value`, `domains` |
+| `forbidden`  | 403    | The caller may not act on this branch                        | none: the branch is not named   |
+
+Any other refusal has no `code`, and only its message says what it is. The
+bulk import reports the same fields on each refused row.
+
 ### Common Errors
 
 #### 400 Bad Request
@@ -1210,6 +1224,18 @@ not a DN (LDAP result code 34):
 }
 ```
 
+#### 403 Forbidden
+
+**Refused by authorization** — the caller may not read, write or delete in
+this branch. The branch is not named, the caller may not know of it:
+
+```json
+{
+  "error": "Token does not have permission on this branch",
+  "code": "forbidden"
+}
+```
+
 #### 404 Not Found
 
 **User Not Found:**
@@ -1259,6 +1285,32 @@ result codes 32 and 16). Removing a group member that is not one names both:
 A rename or a move onto a DN already taken answers the same way, naming that
 DN (LDAP result code 68).
 
+**Value already used** — a value the schema says is unique
+([`unique`](../../usage/plugins/ldap/enterprise-rules.md)), held by another
+entry, which is not named:
+
+```json
+{
+  "error": "user: \"alice@example.com\" is already used (mail must be unique)",
+  "code": "unique",
+  "attribute": "mail",
+  "value": "alice@example.com"
+}
+```
+
+**Mail domain not authorised** — an address outside the domains the entry's
+organization, or one of its ancestors, links to:
+
+```json
+{
+  "error": "The mail domain of \"x.user@other.org\" is not one of the authorised domains (example.com)",
+  "code": "mailDomain",
+  "attribute": "mail",
+  "value": "x.user@other.org",
+  "domains": ["example.com"]
+}
+```
+
 **Entry that cannot hold a change** — a modify adding an attribute the
 classes of the entry do not allow, or a value it already holds (LDAP result
 codes 65 and 20 on a modify):

package/docs/usage/configuration.md

@@ -417,12 +417,13 @@ whichever of the two names it selects. A value other than `req.user` or
 
 #### `core/auth/authzPerBranch`
 
-| CLI                               | Env                                | Default                                          | Description                                                                                                                                                                                                                                                                                                                                     |
-| --------------------------------- | ---------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--authz-per-branch-config`       | `DM_AUTHZ_PER_BRANCH_CONFIG`       | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                                                                                                                                                                                     |
-| `--authz-per-branch-cache-ttl`    | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`    | `60`                                             | Cache TTL (seconds)                                                                                                                                                                                                                                                                                                                             |
-| `--authz-filter-attached-entries` | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES` | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch`; always on under `authzLinid1`; does nothing under `authzDynamic`.                                                                                                                                                      |
-| `--authz-transit-branch`          | `DM_AUTHZ_TRANSIT_BRANCH`          |                                                  | Organization entries are handed over through when they are judged by attachment: every administrator sees and may claim what is there, and puts an entry there with write on the organization it leaves. An entry attached to no organization is in transit too. See [authzLinid1](plugins/auth/authz-linid1.md#transit-handing-an-entry-over). |
+| CLI                                | Env                                 | Default                                          | Description                                                                                                                                                                                                                                                                                                                                     |
+| ---------------------------------- | ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-per-branch-config`        | `DM_AUTHZ_PER_BRANCH_CONFIG`        | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                                                                                                                                                                                     |
+| `--authz-per-branch-cache-ttl`     | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`     | `60`                                             | Cache TTL (seconds)                                                                                                                                                                                                                                                                                                                             |
+| `--authz-filter-attached-entries`  | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES`  | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch`; always on under `authzLinid1`; does nothing under `authzDynamic`.                                                                                                                                                      |
+| `--authz-transit-branch`           | `DM_AUTHZ_TRANSIT_BRANCH`           |                                                  | Organization entries are handed over through when they are judged by attachment: every administrator sees and may claim what is there, and puts an entry there with write on the organization it leaves. An entry attached to no organization is in transit too. See [authzLinid1](plugins/auth/authz-linid1.md#transit-handing-an-entry-over). |
+| `--authz-transit-origin-attribute` | `DM_AUTHZ_TRANSIT_ORIGIN_ATTRIBUTE` |                                                  | Attribute an entry put in transit keeps the organization it leaves in, removed when it is claimed. Empty records nothing; it must exist in the directory's schema. See [authzLinid1](plugins/auth/authz-linid1.md#where-an-entry-comes-from).                                                                                                   |
 
 #### `core/auth/authzScope`
 

package/docs/usage/plugins/auth/authz-linid1.md

@@ -96,6 +96,40 @@ to the transit branch follows the same rules through
 `POST /api/v1/ldap/groups/:cn/move`; that endpoint does not move a group
 attached to no organization.
 
+#### Where an entry comes from
+
+Once in transit, an entry no longer says which organization it left, and the
+administrator who would claim it cannot tell whether it is theirs. Name an
+attribute to keep it in; `twakeTransitOrigin` below is an example, which
+the directory's schema must define (see the rules after it):
+
+```bash
+--authz-transit-origin-attribute twakeTransitOrigin
+```
+
+Putting an entry in transit, by `move` or by any modify of its
+`twakeDepartmentLink`, then sets that attribute to the DN of the organization
+it leaves; claiming it removes the attribute. A move from transit to transit
+keeps it, and an entry that was attached to no organization gets none. A
+modify that sets or removes the attribute itself is left as it is. The name
+is compared as LDAP does, whatever its case. Without a transit branch, the
+option does nothing.
+
+The attribute is the directory's to allow, and its rules apply to the whole
+move: what it refuses, it refuses the move with.
+
+- **A dedicated attribute.** The origin is written with a `replace`: every
+  value the attribute held is overwritten. A business attribute such as
+  `departmentNumber`, which may hold several real values, would lose them.
+  The Twake schema has no attribute for this: add one to the directory's
+  schema.
+- **Optional.** Claiming the entry removes the attribute, so it must be
+  among the `MAY` of its object classes, never a `MUST`. It must be allowed
+  on every entry that can be handed over, accounts and groups alike.
+- **Writable.** The directory's ACLs must let ldap-rest's bind write it.
+
+Without the option, nothing is recorded.
+
 ### Mail domains
 
 The mail domains an organization's entries may use are those it links in
@@ -145,7 +179,8 @@ a search started above the branch leaves its entries out. That is how only
 the administrators of the whole directory manage the
 [password policies](../ldap/password-policy.md#managing-policies). A global
 branch is no branch of theirs in `GET /authz/scope`, so it adds nothing to
-the organizations they are offered.
+the organizations they are offered; `passwordPolicies` there says whether
+they may list the policies.
 
 `--authz-global-write-branches` names branches whose writes and deletes are
 held the same way, while reading them stays as for the rest of the reference

package/docs/usage/plugins/ldap/bulk-import.md

@@ -495,11 +495,26 @@ newuser,New User,User,new2@example.com
       "line": 10,
       "identifier": "user009",
       "error": "Invalid DN format"
+    },
+    {
+      "line": 11,
+      "identifier": "user010",
+      "error": "user: \"jane@example.com\" is already used (mail must be unique)",
+      "code": "unique",
+      "attribute": "mail",
+      "value": "jane@example.com"
     }
   ]
 }
 ```
 
+A row refused by a rule a client is expected to explain — a value already
+used, a mail domain outside the authorised ones, with
+[enterprise rules](enterprise-rules.md) loaded — carries the same `code`,
+`attribute`, `value` and `domains` as the answer of a single write: see
+[the error format](../../../client-development/api/rest-api.md#error-response-format).
+Other rows only have `error`.
+
 ## Best Practices
 
 ### Handling Partial Failures