samlify 2.12.0 → 2.13.0

package/README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://img.shields.io/circleci/build/github/tngan/samlify?style=for-the-badge&logo=circleci)](https://app.circleci.com/pipelines/github/tngan/samlify)
 [![npm version](https://img.shields.io/npm/v/samlify.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/samlify)
 [![NPM](https://img.shields.io/npm/dm/samlify.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/samlify)
-[![Coverage Status](https://img.shields.io/coveralls/tngan/samlify/master.svg?style=for-the-badge&logo=coveralls)](https://coveralls.io/github/tngan/samlify?branch=master)
+[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A590%25-brightgreen?style=for-the-badge&logo=vitest)](./vitest.config.ts)
 
 Highly configuarable Node.js SAML 2.0 library for Single Sign On
 

package/build/src/api.js

@@ -1,8 +1,24 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getContext = getContext;
 exports.setSchemaValidator = setSchemaValidator;
 exports.setDOMParserOptions = setDOMParserOptions;
+/**
+ * @file api.ts
+ * @author tngan
+ * @desc Global module configuration: XML schema validator and DOM parser.
+ */
 var xmldom_1 = require("@xmldom/xmldom");
 var XXE_SAFE_OPTIONS = {
     /**
@@ -17,20 +33,42 @@ var XXE_SAFE_OPTIONS = {
 };
 var context = {
     validate: undefined,
-    dom: new xmldom_1.DOMParser(XXE_SAFE_OPTIONS)
+    dom: new xmldom_1.DOMParser(XXE_SAFE_OPTIONS),
 };
+/**
+ * Return the module-wide runtime context (DOM parser and validator).
+ *
+ * @returns shared context object
+ */
 function getContext() {
     return context;
 }
+/**
+ * Register the caller-supplied SAML schema validator. Throws when the
+ * supplied value does not expose a `validate` callback.
+ *
+ * @param params object with a `validate(xml)` callback
+ */
 function setSchemaValidator(params) {
     if (typeof params.validate !== 'function') {
         throw new Error('validate must be a callback function having one argument as xml input');
     }
-    // assign the validate function to the context
     context.validate = params.validate;
 }
+/**
+ * Replace the module-wide DOM parser with one configured by the caller.
+ *
+ * The XXE-safe error handlers are merged into the supplied options as a
+ * baseline so callers can override unrelated settings without
+ * accidentally disabling XXE protection (`saml-core §6.4`,
+ * `saml-sec-consider §6.3.1`). A caller can still opt out by passing
+ * its own `errorHandler`, but it must do so explicitly.
+ *
+ * @param options xmldom parser options
+ */
 function setDOMParserOptions(options) {
+    var _a;
     if (options === void 0) { options = {}; }
-    context.dom = new xmldom_1.DOMParser(options);
+    context.dom = new xmldom_1.DOMParser(__assign(__assign(__assign({}, XXE_SAFE_OPTIONS), options), { errorHandler: (_a = options.errorHandler) !== null && _a !== void 0 ? _a : XXE_SAFE_OPTIONS.errorHandler }));
 }
 //# sourceMappingURL=api.js.map

package/build/src/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":";;AA8BA,gCAEC;AAED,gDASC;AAED,kDAEC;AA/CD,yCAA+E;AAa/E,IAAM,gBAAgB,GAAqB;IACzC;;;;OAIG;IACH,YAAY,EAAE;QACZ,KAAK,EAAE,UAAC,GAAW,IAAO,MAAM,IAAI,KAAK,CAAC,6BAAsB,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC;QACzE,UAAU,EAAE,UAAC,GAAW,IAAO,MAAM,IAAI,KAAK,CAAC,2BAAoB,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC;KAC7E;CACF,CAAC;AAEF,IAAM,OAAO,GAAY;IACvB,QAAQ,EAAE,SAAS;IACnB,GAAG,EAAE,IAAI,kBAAG,CAAC,gBAAgB,CAAC;CAC/B,CAAC;AAEF,SAAgB,UAAU;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAgB,kBAAkB,CAAC,MAAwB;IAEzD,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IAED,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;AAErC,CAAC;AAED,SAAgB,mBAAmB,CAAC,OAA8B;IAA9B,wBAAA,EAAA,YAA8B;IAChE,OAAO,CAAC,GAAG,GAAG,IAAI,kBAAG,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":";;;;;;;;;;;;;AA0CA,gCAEC;AAQD,gDAKC;AAaD,kDAMC;AA5ED;;;;GAIG;AACH,yCAA+E;AAe/E,IAAM,gBAAgB,GAAqB;IACzC;;;;OAIG;IACH,YAAY,EAAE;QACZ,KAAK,EAAE,UAAC,GAAW,IAAO,MAAM,IAAI,KAAK,CAAC,6BAAsB,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC;QACzE,UAAU,EAAE,UAAC,GAAW,IAAO,MAAM,IAAI,KAAK,CAAC,2BAAoB,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC;KAC7E;CACF,CAAC;AAEF,IAAM,OAAO,GAAY;IACvB,QAAQ,EAAE,SAAS;IACnB,GAAG,EAAE,IAAI,kBAAG,CAAC,gBAAgB,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,SAAgB,UAAU;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,MAAwB;IACzD,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;AACrC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,OAA8B;;IAA9B,wBAAA,EAAA,YAA8B;IAChE,OAAO,CAAC,GAAG,GAAG,IAAI,kBAAG,gCAChB,gBAAgB,GAChB,OAAO,KACV,YAAY,EAAE,MAAA,OAAO,CAAC,YAAY,mCAAI,gBAAgB,CAAC,YAAY,IACnE,CAAC;AACL,CAAC"}

package/build/src/binding-post.js

@@ -1,9 +1,11 @@
 "use strict";
 /**
-* @file binding-post.ts
-* @author tngan
-* @desc Binding-level API, declare the functions using POST binding
-*/
+ * @file binding-post.ts
+ * @author tngan
+ * @desc Binding-level API for SAML HTTP-POST. Builds base64 login/logout
+ * request and response payloads that callers embed in an auto-submitting
+ * HTML form.
+ */
 var __assign = (this && this.__assign) || function () {
     __assign = Object.assign || function(t) {
         for (var s, i = 1, n = arguments.length; i < n; i++) {
@@ -93,81 +95,115 @@ var libsaml_1 = __importDefault(require("./libsaml"));
 var utility_1 = __importStar(require("./utility"));
 var binding = urn_1.wording.binding;
 /**
-* @desc Generate a base64 encoded login request
-* @param  {string} referenceTagXPath           reference uri
-* @param  {object} entity                      object includes both idp and sp
-* @param  {function} customTagReplacement     used when developers have their own login response template
-*/
-function base64LoginRequest(referenceTagXPath, entity, customTagReplacement) {
+ * Generate a base64-encoded AuthnRequest for the HTTP-POST binding.
+ *
+ * @param referenceTagXPath XPath used when signing the request
+ * @param entity `{ idp, sp }` handles
+ * @param customTagReplacement optional custom template transformer
+ * @param forceAuthn per-request `ForceAuthn` flag (saml-core §3.4.1)
+ * @param assertionConsumerServiceIndex per-request ACS index (saml-core §3.4.1).
+ *   Mutually exclusive with `AssertionConsumerServiceURL` / `ProtocolBinding`;
+ *   when supplied, both of those attributes are dropped from the rendered XML.
+ * @returns id / base64-XML pair
+ */
+function base64LoginRequest(referenceTagXPath, entity, customTagReplacement, forceAuthn, assertionConsumerServiceIndex) {
+    var _a, _b;
     var metadata = { idp: entity.idp.entityMeta, sp: entity.sp.entityMeta };
     var spSetting = entity.sp.entitySetting;
     var id = '';
-    if (metadata && metadata.idp && metadata.sp) {
-        var base = metadata.idp.getSingleSignOnService(binding.post);
-        var rawSamlRequest = void 0;
-        if (spSetting.loginRequestTemplate && customTagReplacement) {
-            var info = customTagReplacement(spSetting.loginRequestTemplate.context);
-            id = (0, utility_1.get)(info, 'id', null);
-            rawSamlRequest = (0, utility_1.get)(info, 'context', null);
-        }
-        else {
-            var nameIDFormat = spSetting.nameIDFormat;
-            var selectedNameIDFormat = Array.isArray(nameIDFormat) ? nameIDFormat[0] : nameIDFormat;
-            id = spSetting.generateID();
-            rawSamlRequest = libsaml_1.default.replaceTagsByValue(libsaml_1.default.defaultLoginRequestTemplate.context, {
-                ID: id,
-                Destination: base,
-                Issuer: metadata.sp.getEntityID(),
-                IssueInstant: new Date().toISOString(),
-                AssertionConsumerServiceURL: metadata.sp.getAssertionConsumerService(binding.post),
-                EntityID: metadata.sp.getEntityID(),
-                AllowCreate: spSetting.allowCreate,
-                NameIDFormat: selectedNameIDFormat
-            });
-        }
-        if (metadata.idp.isWantAuthnRequestsSigned()) {
-            var privateKey = spSetting.privateKey, privateKeyPass = spSetting.privateKeyPass, signatureAlgorithm = spSetting.requestSignatureAlgorithm, transformationAlgorithms = spSetting.transformationAlgorithms;
-            return {
-                id: id,
-                context: libsaml_1.default.constructSAMLSignature({
-                    referenceTagXPath: referenceTagXPath,
-                    privateKey: privateKey,
-                    privateKeyPass: privateKeyPass,
-                    signatureAlgorithm: signatureAlgorithm,
-                    transformationAlgorithms: transformationAlgorithms,
-                    rawSamlMessage: rawSamlRequest,
-                    signingCert: metadata.sp.getX509Certificate('signing'),
-                    signatureConfig: spSetting.signatureConfig || {
-                        prefix: 'ds',
-                        location: { reference: "/*[local-name(.)='AuthnRequest']/*[local-name(.)='Issuer']", action: 'after' },
-                    }
-                }),
-            };
-        }
-        // No need to embeded XML signature
+    /* v8 ignore start */
+    if (!metadata.idp || !metadata.sp) {
+        throw new Error('ERR_GENERATE_POST_LOGIN_REQUEST_MISSING_METADATA');
+    }
+    /* v8 ignore stop */
+    var base = metadata.idp.getSingleSignOnService(binding.post);
+    var rawSamlRequest;
+    if (customTagReplacement) {
+        // saml-bindings §3.5 — the AuthnRequest template is informative, not
+        // normative. Honour the callback regardless of whether the caller
+        // supplied a custom template (closes #549). Pass the user-supplied
+        // template when present; otherwise the library default.
+        var templateContext = (_b = (_a = spSetting.loginRequestTemplate) === null || _a === void 0 ? void 0 : _a.context) !== null && _b !== void 0 ? _b : libsaml_1.default.defaultLoginRequestTemplate.context;
+        var info = customTagReplacement(templateContext);
+        id = (0, utility_1.get)(info, 'id');
+        rawSamlRequest = (0, utility_1.get)(info, 'context');
+    }
+    else {
+        var nameIDFormat = spSetting.nameIDFormat;
+        var selectedNameIDFormat = Array.isArray(nameIDFormat) ? nameIDFormat[0] : nameIDFormat;
+        id = spSetting.generateID();
+        // saml-core §3.4.1 — `AssertionConsumerServiceIndex` is mutually
+        // exclusive with `AssertionConsumerServiceURL` / `ProtocolBinding`.
+        // When the caller supplies the index we set the URL+ProtocolBinding
+        // tags to undefined so `replaceTagsByValue` drops both attributes
+        // from the rendered XML (closes #437).
+        var useAcsIndex = assertionConsumerServiceIndex !== undefined;
+        var tags = {
+            ID: id,
+            Destination: base,
+            Issuer: metadata.sp.getEntityID(),
+            IssueInstant: new Date().toISOString(),
+            ProtocolBinding: useAcsIndex
+                ? undefined
+                : 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
+            AssertionConsumerServiceURL: useAcsIndex
+                ? undefined
+                : metadata.sp.getAssertionConsumerService(binding.post),
+            AssertionConsumerServiceIndex: assertionConsumerServiceIndex,
+            EntityID: metadata.sp.getEntityID(),
+            AllowCreate: spSetting.allowCreate,
+            NameIDFormat: selectedNameIDFormat,
+            // saml-core §3.4.1 — `replaceTagsByValue` drops the attribute when
+            // `forceAuthn` is undefined, matching `use="optional"`.
+            ForceAuthn: forceAuthn,
+        };
+        rawSamlRequest = libsaml_1.default.replaceTagsByValue(libsaml_1.default.defaultLoginRequestTemplate.context, tags);
+    }
+    if (metadata.idp.isWantAuthnRequestsSigned()) {
+        var privateKey = spSetting.privateKey, privateKeyPass = spSetting.privateKeyPass, signatureAlgorithm = spSetting.requestSignatureAlgorithm, transformationAlgorithms = spSetting.transformationAlgorithms;
         return {
             id: id,
-            context: utility_1.default.base64Encode(rawSamlRequest),
+            context: libsaml_1.default.constructSAMLSignature({
+                referenceTagXPath: referenceTagXPath,
+                privateKey: privateKey,
+                privateKeyPass: privateKeyPass,
+                signatureAlgorithm: signatureAlgorithm,
+                transformationAlgorithms: transformationAlgorithms,
+                rawSamlMessage: rawSamlRequest,
+                signingCert: metadata.sp.getX509Certificate('signing'),
+                signatureConfig: spSetting.signatureConfig || {
+                    prefix: 'ds',
+                    location: { reference: "/*[local-name(.)='AuthnRequest']/*[local-name(.)='Issuer']", action: 'after' },
+                },
+            }),
         };
     }
-    throw new Error('ERR_GENERATE_POST_LOGIN_REQUEST_MISSING_METADATA');
+    return {
+        id: id,
+        context: utility_1.default.base64Encode(rawSamlRequest),
+    };
 }
 /**
-* @desc Generate a base64 encoded login response
-* @param  {object} requestInfo                 corresponding request, used to obtain the id
-* @param  {object} entity                      object includes both idp and sp
-* @param  {object} user                        current logged user (e.g. req.user)
-* @param  {function} customTagReplacement     used when developers have their own login response template
-* @param  {boolean}  encryptThenSign           whether or not to encrypt then sign first (if signing). Defaults to sign-then-encrypt
-*/
+ * Generate a base64-encoded login response for the HTTP-POST binding.
+ * Supports the sign-then-encrypt and encrypt-then-sign pipelines based on
+ * `encryptThenSign`.
+ *
+ * @param requestInfo parsed login request used to link `InResponseTo`
+ * @param entity `{ idp, sp }` handles
+ * @param user authenticated user
+ * @param customTagReplacement optional custom template transformer
+ * @param encryptThenSign when true, encrypt the assertion first then sign
+ * @returns id / base64-XML pair
+ */
 function base64LoginResponse() {
     return __awaiter(this, arguments, void 0, function (requestInfo, entity, user, customTagReplacement, encryptThenSign) {
-        var idpSetting, spSetting, id, metadata, nameIDFormat, selectedNameIDFormat, base, rawSamlResponse, nowTime, spEntityID, fiveMinutesLaterTime, fiveMinutesLater, now, acl, tvalue, template, privateKey, privateKeyPass, signatureAlgorithm, config, context;
+        var idpSetting, spSetting, id, metadata, nameIDFormat, selectedNameIDFormat, base, rawSamlResponse, nowTime, spEntityID, fiveMinutesLaterTime, fiveMinutesLater, now, acl, tvalue, templateContext, template, baseTemplate, privateKey, privateKeyPass, signatureAlgorithm, config, context;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         if (requestInfo === void 0) { requestInfo = {}; }
         if (user === void 0) { user = {}; }
         if (encryptThenSign === void 0) { encryptThenSign = false; }
-        return __generator(this, function (_a) {
-            switch (_a.label) {
+        return __generator(this, function (_k) {
+            switch (_k.label) {
                 case 0:
                     idpSetting = entity.idp.entitySetting;
                     spSetting = entity.sp.entitySetting;
@@ -178,9 +214,11 @@ function base64LoginResponse() {
                     };
                     nameIDFormat = idpSetting.nameIDFormat;
                     selectedNameIDFormat = Array.isArray(nameIDFormat) ? nameIDFormat[0] : nameIDFormat;
-                    if (!(metadata && metadata.idp && metadata.sp)) return [3 /*break*/, 3];
+                    /* v8 ignore start */
+                    if (!metadata.idp || !metadata.sp) {
+                        throw new Error('ERR_GENERATE_POST_LOGIN_RESPONSE_MISSING_METADATA');
+                    }
                     base = metadata.sp.getAssertionConsumerService(binding.post);
-                    rawSamlResponse = void 0;
                     nowTime = new Date();
                     spEntityID = metadata.sp.getEntityID();
                     fiveMinutesLaterTime = new Date(nowTime.getTime());
@@ -199,7 +237,6 @@ function base64LoginResponse() {
                         IssueInstant: now,
                         AssertionConsumerServiceURL: acl,
                         StatusCode: urn_1.StatusCode.Success,
-                        // can be customized
                         ConditionsNotBefore: now,
                         ConditionsNotOnOrAfter: fiveMinutesLater,
                         SubjectConfirmationDataNotOnOrAfter: fiveMinutesLater,
@@ -209,15 +246,17 @@ function base64LoginResponse() {
                         AuthnStatement: '',
                         AttributeStatement: '',
                     };
-                    if (idpSetting.loginResponseTemplate && customTagReplacement) {
-                        template = customTagReplacement(idpSetting.loginResponseTemplate.context);
-                        rawSamlResponse = (0, utility_1.get)(template, 'context', null);
+                    if (customTagReplacement) {
+                        templateContext = (_e = (_b = (_a = idpSetting.loginResponseTemplate) === null || _a === void 0 ? void 0 : _a.context) !== null && _b !== void 0 ? _b : (_d = (_c = idpSetting.tagPrefixedDefaults) === null || _c === void 0 ? void 0 : _c.loginResponseTemplate) === null || _d === void 0 ? void 0 : _d.context) !== null && _e !== void 0 ? _e : libsaml_1.default.defaultLoginResponseTemplate.context;
+                        template = customTagReplacement(templateContext);
+                        rawSamlResponse = (0, utility_1.get)(template, 'context');
                     }
                     else {
-                        if (requestInfo !== null) {
+                        if (requestInfo !== null && ((_f = requestInfo.extract) === null || _f === void 0 ? void 0 : _f.request)) {
                             tvalue.InResponseTo = requestInfo.extract.request.id;
                         }
-                        rawSamlResponse = libsaml_1.default.replaceTagsByValue(libsaml_1.default.defaultLoginResponseTemplate.context, tvalue);
+                        baseTemplate = (_j = (_h = (_g = idpSetting.tagPrefixedDefaults) === null || _g === void 0 ? void 0 : _g.loginResponseTemplate) === null || _h === void 0 ? void 0 : _h.context) !== null && _j !== void 0 ? _j : libsaml_1.default.defaultLoginResponseTemplate.context;
+                        rawSamlResponse = libsaml_1.default.replaceTagsByValue(baseTemplate, tvalue);
                     }
                     privateKey = idpSetting.privateKey, privateKeyPass = idpSetting.privateKeyPass, signatureAlgorithm = idpSetting.requestSignatureAlgorithm;
                     config = {
@@ -227,18 +266,14 @@ function base64LoginResponse() {
                         signingCert: metadata.idp.getX509Certificate('signing'),
                         isBase64Output: false,
                     };
-                    // step: sign assertion ? -> encrypted ? -> sign message ?
+                    // Order: sign assertion (if SP wants) → encrypt (if IdP wants) → sign message (if needed).
                     if (metadata.sp.isWantAssertionsSigned()) {
-                        // console.debug('sp wants assertion signed');
                         rawSamlResponse = libsaml_1.default.constructSAMLSignature(__assign(__assign({}, config), { rawSamlMessage: rawSamlResponse, transformationAlgorithms: spSetting.transformationAlgorithms, referenceTagXPath: "/*[local-name(.)='Response']/*[local-name(.)='Assertion']", signatureConfig: {
                                 prefix: 'ds',
                                 location: { reference: "/*[local-name(.)='Response']/*[local-name(.)='Assertion']/*[local-name(.)='Issuer']", action: 'after' },
                             } }));
                     }
-                    // console.debug('after assertion signed', rawSamlResponse);
-                    // SAML response must be signed sign message first, then encrypt
                     if (!encryptThenSign && (spSetting.wantMessageSigned || !metadata.sp.isWantAssertionsSigned())) {
-                        // console.debug('sign then encrypt and sign entire message');
                         rawSamlResponse = libsaml_1.default.constructSAMLSignature(__assign(__assign({}, config), { rawSamlMessage: rawSamlResponse, isMessageSigned: true, transformationAlgorithms: spSetting.transformationAlgorithms, signatureConfig: spSetting.signatureConfig || {
                                 prefix: 'ds',
                                 location: { reference: "/*[local-name(.)='Response']/*[local-name(.)='Issuer']", action: 'after' },
@@ -247,17 +282,15 @@ function base64LoginResponse() {
                     if (!idpSetting.isAssertionEncrypted) return [3 /*break*/, 2];
                     return [4 /*yield*/, libsaml_1.default.encryptAssertion(entity.idp, entity.sp, rawSamlResponse)];
                 case 1:
-                    context = _a.sent();
+                    context = _k.sent();
                     if (encryptThenSign) {
-                        //need to decode it
                         rawSamlResponse = utility_1.default.base64Decode(context);
                     }
                     else {
                         return [2 /*return*/, Promise.resolve({ id: id, context: context })];
                     }
-                    _a.label = 2;
+                    _k.label = 2;
                 case 2:
-                    //sign after encrypting
                     if (encryptThenSign && (spSetting.wantMessageSigned || !metadata.sp.isWantAssertionsSigned())) {
                         rawSamlResponse = libsaml_1.default.constructSAMLSignature(__assign(__assign({}, config), { rawSamlMessage: rawSamlResponse, isMessageSigned: true, transformationAlgorithms: spSetting.transformationAlgorithms, signatureConfig: spSetting.signatureConfig || {
                                 prefix: 'ds',
@@ -268,134 +301,155 @@ function base64LoginResponse() {
                             id: id,
                             context: utility_1.default.base64Encode(rawSamlResponse),
                         })];
-                case 3: throw new Error('ERR_GENERATE_POST_LOGIN_RESPONSE_MISSING_METADATA');
             }
         });
     });
 }
 /**
-* @desc Generate a base64 encoded logout request
-* @param  {object} user                         current logged user (e.g. req.user)
-* @param  {string} referenceTagXPath            reference uri
-* @param  {object} entity                       object includes both idp and sp
-* @param  {function} customTagReplacement      used when developers have their own login response template
-* @return {string} base64 encoded request
-*/
+ * Generate a base64-encoded LogoutRequest for the HTTP-POST binding.
+ *
+ * @param user currently authenticated user
+ * @param referenceTagXPath XPath used when signing the request
+ * @param entity `{ init, target }` handles
+ * @param customTagReplacement optional custom template transformer
+ * @returns id / base64-XML pair
+ */
 function base64LogoutRequest(user, referenceTagXPath, entity, customTagReplacement) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     var metadata = { init: entity.init.entityMeta, target: entity.target.entityMeta };
     var initSetting = entity.init.entitySetting;
     var nameIDFormat = initSetting.nameIDFormat;
     var selectedNameIDFormat = Array.isArray(nameIDFormat) ? nameIDFormat[0] : nameIDFormat;
     var id = '';
-    if (metadata && metadata.init && metadata.target) {
-        var rawSamlRequest = void 0;
-        if (initSetting.logoutRequestTemplate && customTagReplacement) {
-            var template = customTagReplacement(initSetting.logoutRequestTemplate.context);
-            id = (0, utility_1.get)(template, 'id', null);
-            rawSamlRequest = (0, utility_1.get)(template, 'context', null);
-        }
-        else {
-            id = initSetting.generateID();
-            var tvalue = {
-                ID: id,
-                Destination: metadata.target.getSingleLogoutService(binding.post),
-                Issuer: metadata.init.getEntityID(),
-                IssueInstant: new Date().toISOString(),
-                EntityID: metadata.init.getEntityID(),
-                NameIDFormat: selectedNameIDFormat,
-                NameID: user.logoutNameID,
-            };
-            rawSamlRequest = libsaml_1.default.replaceTagsByValue(libsaml_1.default.defaultLogoutRequestTemplate.context, tvalue);
-        }
-        if (entity.target.entitySetting.wantLogoutRequestSigned) {
-            // Need to embeded XML signature
-            var privateKey = initSetting.privateKey, privateKeyPass = initSetting.privateKeyPass, signatureAlgorithm = initSetting.requestSignatureAlgorithm, transformationAlgorithms = initSetting.transformationAlgorithms;
-            return {
-                id: id,
-                context: libsaml_1.default.constructSAMLSignature({
-                    referenceTagXPath: referenceTagXPath,
-                    privateKey: privateKey,
-                    privateKeyPass: privateKeyPass,
-                    signatureAlgorithm: signatureAlgorithm,
-                    transformationAlgorithms: transformationAlgorithms,
-                    rawSamlMessage: rawSamlRequest,
-                    signingCert: metadata.init.getX509Certificate('signing'),
-                    signatureConfig: initSetting.signatureConfig || {
-                        prefix: 'ds',
-                        location: { reference: "/*[local-name(.)='LogoutRequest']/*[local-name(.)='Issuer']", action: 'after' },
-                    }
-                }),
-            };
-        }
+    /* v8 ignore start */
+    if (!metadata.init || !metadata.target) {
+        throw new Error('ERR_GENERATE_POST_LOGOUT_REQUEST_MISSING_METADATA');
+    }
+    /* v8 ignore stop */
+    var rawSamlRequest;
+    if (customTagReplacement) {
+        // saml-bindings §3.5 — honour the callback even when the caller did
+        // not override `logoutRequestTemplate` (closes #549). Prefer the
+        // user-supplied template, then the tag-prefixed default (closes #388),
+        // and finally the library default.
+        var templateContext = (_e = (_b = (_a = initSetting.logoutRequestTemplate) === null || _a === void 0 ? void 0 : _a.context) !== null && _b !== void 0 ? _b : (_d = (_c = initSetting.tagPrefixedDefaults) === null || _c === void 0 ? void 0 : _c.logoutRequestTemplate) === null || _d === void 0 ? void 0 : _d.context) !== null && _e !== void 0 ? _e : libsaml_1.default.defaultLogoutRequestTemplate.context;
+        var template = customTagReplacement(templateContext);
+        id = (0, utility_1.get)(template, 'id');
+        rawSamlRequest = (0, utility_1.get)(template, 'context');
+    }
+    else {
+        id = initSetting.generateID();
+        var tvalue = {
+            ID: id,
+            Destination: metadata.target.getSingleLogoutService(binding.post),
+            Issuer: metadata.init.getEntityID(),
+            IssueInstant: new Date().toISOString(),
+            EntityID: metadata.init.getEntityID(),
+            NameIDFormat: selectedNameIDFormat,
+            NameID: user.logoutNameID,
+            // saml-core §3.7.1 — SessionIndex is optional; replaceTagsByValue
+            // drops the element when undefined (closes #470).
+            SessionIndex: user.sessionIndex,
+        };
+        var baseTemplate = (_h = (_g = (_f = initSetting.tagPrefixedDefaults) === null || _f === void 0 ? void 0 : _f.logoutRequestTemplate) === null || _g === void 0 ? void 0 : _g.context) !== null && _h !== void 0 ? _h : libsaml_1.default.defaultLogoutRequestTemplate.context;
+        rawSamlRequest = libsaml_1.default.replaceTagsByValue(baseTemplate, tvalue);
+    }
+    if (entity.target.entitySetting.wantLogoutRequestSigned) {
+        var privateKey = initSetting.privateKey, privateKeyPass = initSetting.privateKeyPass, signatureAlgorithm = initSetting.requestSignatureAlgorithm, transformationAlgorithms = initSetting.transformationAlgorithms;
         return {
             id: id,
-            context: utility_1.default.base64Encode(rawSamlRequest),
+            context: libsaml_1.default.constructSAMLSignature({
+                referenceTagXPath: referenceTagXPath,
+                privateKey: privateKey,
+                privateKeyPass: privateKeyPass,
+                signatureAlgorithm: signatureAlgorithm,
+                transformationAlgorithms: transformationAlgorithms,
+                rawSamlMessage: rawSamlRequest,
+                signingCert: metadata.init.getX509Certificate('signing'),
+                signatureConfig: initSetting.signatureConfig || {
+                    prefix: 'ds',
+                    location: { reference: "/*[local-name(.)='LogoutRequest']/*[local-name(.)='Issuer']", action: 'after' },
+                },
+            }),
         };
     }
-    throw new Error('ERR_GENERATE_POST_LOGOUT_REQUEST_MISSING_METADATA');
+    return {
+        id: id,
+        context: utility_1.default.base64Encode(rawSamlRequest),
+    };
 }
 /**
-* @desc Generate a base64 encoded logout response
-* @param  {object} requestInfo                 corresponding request, used to obtain the id
-* @param  {string} referenceTagXPath           reference uri
-* @param  {object} entity                      object includes both idp and sp
-* @param  {function} customTagReplacement     used when developers have their own login response template
-*/
+ * Generate a base64-encoded LogoutResponse for the HTTP-POST binding.
+ *
+ * @param requestInfo parsed request used to link `InResponseTo`
+ * @param entity `{ init, target }` handles
+ * @param customTagReplacement optional custom template transformer
+ * @returns id / base64-XML pair
+ */
 function base64LogoutResponse(requestInfo, entity, customTagReplacement) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     var metadata = {
         init: entity.init.entityMeta,
         target: entity.target.entityMeta,
     };
     var id = '';
     var initSetting = entity.init.entitySetting;
-    if (metadata && metadata.init && metadata.target) {
-        var rawSamlResponse = void 0;
-        if (initSetting.logoutResponseTemplate) {
-            var template = customTagReplacement(initSetting.logoutResponseTemplate.context);
-            id = template.id;
-            rawSamlResponse = template.context;
-        }
-        else {
-            id = initSetting.generateID();
-            var tvalue = {
-                ID: id,
-                Destination: metadata.target.getSingleLogoutService(binding.post),
-                EntityID: metadata.init.getEntityID(),
-                Issuer: metadata.init.getEntityID(),
-                IssueInstant: new Date().toISOString(),
-                StatusCode: urn_1.StatusCode.Success,
-                InResponseTo: (0, utility_1.get)(requestInfo, 'extract.request.id', null)
-            };
-            rawSamlResponse = libsaml_1.default.replaceTagsByValue(libsaml_1.default.defaultLogoutResponseTemplate.context, tvalue);
-        }
-        if (entity.target.entitySetting.wantLogoutResponseSigned) {
-            var privateKey = initSetting.privateKey, privateKeyPass = initSetting.privateKeyPass, signatureAlgorithm = initSetting.requestSignatureAlgorithm, transformationAlgorithms = initSetting.transformationAlgorithms;
-            return {
-                id: id,
-                context: libsaml_1.default.constructSAMLSignature({
-                    isMessageSigned: true,
-                    transformationAlgorithms: transformationAlgorithms,
-                    privateKey: privateKey,
-                    privateKeyPass: privateKeyPass,
-                    signatureAlgorithm: signatureAlgorithm,
-                    rawSamlMessage: rawSamlResponse,
-                    signingCert: metadata.init.getX509Certificate('signing'),
-                    signatureConfig: {
-                        prefix: 'ds',
-                        location: {
-                            reference: "/*[local-name(.)='LogoutResponse']/*[local-name(.)='Issuer']",
-                            action: 'after'
-                        }
-                    }
-                }),
-            };
-        }
+    /* v8 ignore start */
+    if (!metadata.init || !metadata.target) {
+        throw new Error('ERR_GENERATE_POST_LOGOUT_RESPONSE_MISSING_METADATA');
+    }
+    /* v8 ignore stop */
+    var rawSamlResponse;
+    if (customTagReplacement) {
+        // saml-bindings §3.5 — honour the callback even when the caller did
+        // not override `logoutResponseTemplate` (closes #549). Prefer the
+        // user-supplied template, then the tag-prefixed default (closes #388),
+        // and finally the library default.
+        var templateContext = (_e = (_b = (_a = initSetting.logoutResponseTemplate) === null || _a === void 0 ? void 0 : _a.context) !== null && _b !== void 0 ? _b : (_d = (_c = initSetting.tagPrefixedDefaults) === null || _c === void 0 ? void 0 : _c.logoutResponseTemplate) === null || _d === void 0 ? void 0 : _d.context) !== null && _e !== void 0 ? _e : libsaml_1.default.defaultLogoutResponseTemplate.context;
+        var template = customTagReplacement(templateContext);
+        id = template.id;
+        rawSamlResponse = template.context;
+    }
+    else {
+        id = initSetting.generateID();
+        var tvalue = {
+            ID: id,
+            Destination: metadata.target.getSingleLogoutService(binding.post),
+            EntityID: metadata.init.getEntityID(),
+            Issuer: metadata.init.getEntityID(),
+            IssueInstant: new Date().toISOString(),
+            StatusCode: urn_1.StatusCode.Success,
+            InResponseTo: (0, utility_1.get)(requestInfo, 'extract.request.id'),
+        };
+        var baseTemplate = (_h = (_g = (_f = initSetting.tagPrefixedDefaults) === null || _f === void 0 ? void 0 : _f.logoutResponseTemplate) === null || _g === void 0 ? void 0 : _g.context) !== null && _h !== void 0 ? _h : libsaml_1.default.defaultLogoutResponseTemplate.context;
+        rawSamlResponse = libsaml_1.default.replaceTagsByValue(baseTemplate, tvalue);
+    }
+    if (entity.target.entitySetting.wantLogoutResponseSigned) {
+        var privateKey = initSetting.privateKey, privateKeyPass = initSetting.privateKeyPass, signatureAlgorithm = initSetting.requestSignatureAlgorithm, transformationAlgorithms = initSetting.transformationAlgorithms;
         return {
             id: id,
-            context: utility_1.default.base64Encode(rawSamlResponse),
+            context: libsaml_1.default.constructSAMLSignature({
+                isMessageSigned: true,
+                transformationAlgorithms: transformationAlgorithms,
+                privateKey: privateKey,
+                privateKeyPass: privateKeyPass,
+                signatureAlgorithm: signatureAlgorithm,
+                rawSamlMessage: rawSamlResponse,
+                signingCert: metadata.init.getX509Certificate('signing'),
+                signatureConfig: {
+                    prefix: 'ds',
+                    location: {
+                        reference: "/*[local-name(.)='LogoutResponse']/*[local-name(.)='Issuer']",
+                        action: 'after',
+                    },
+                },
+            }),
         };
     }
-    throw new Error('ERR_GENERATE_POST_LOGOUT_RESPONSE_MISSING_METADATA');
+    return {
+        id: id,
+        context: utility_1.default.base64Encode(rawSamlResponse),
+    };
 }
 var postBinding = {
     base64LoginRequest: base64LoginRequest,