samlify 2.11.0 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +1 -1
  2. package/build/src/api.js +52 -3
  3. package/build/src/api.js.map +1 -1
  4. package/build/src/binding-post.js +236 -182
  5. package/build/src/binding-post.js.map +1 -1
  6. package/build/src/binding-redirect.js +303 -215
  7. package/build/src/binding-redirect.js.map +1 -1
  8. package/build/src/binding-simplesign.js +285 -137
  9. package/build/src/binding-simplesign.js.map +1 -1
  10. package/build/src/entity-idp.js +130 -47
  11. package/build/src/entity-idp.js.map +1 -1
  12. package/build/src/entity-sp.js +81 -39
  13. package/build/src/entity-sp.js.map +1 -1
  14. package/build/src/entity.js +100 -62
  15. package/build/src/entity.js.map +1 -1
  16. package/build/src/extractor.js +119 -155
  17. package/build/src/extractor.js.map +1 -1
  18. package/build/src/flow.js +100 -96
  19. package/build/src/flow.js.map +1 -1
  20. package/build/src/libsaml.js +318 -261
  21. package/build/src/libsaml.js.map +1 -1
  22. package/build/src/metadata-idp.js +60 -30
  23. package/build/src/metadata-idp.js.map +1 -1
  24. package/build/src/metadata-sp.js +51 -41
  25. package/build/src/metadata-sp.js.map +1 -1
  26. package/build/src/metadata.js +47 -43
  27. package/build/src/metadata.js.map +1 -1
  28. package/build/src/options.js +73 -0
  29. package/build/src/options.js.map +1 -0
  30. package/build/src/urn.js +28 -1
  31. package/build/src/urn.js.map +1 -1
  32. package/build/src/utility.js +165 -83
  33. package/build/src/utility.js.map +1 -1
  34. package/build/src/validator.js +27 -10
  35. package/build/src/validator.js.map +1 -1
  36. package/package.json +17 -7
  37. package/types/src/api.d.ts +33 -3
  38. package/types/src/binding-post.d.ts +67 -34
  39. package/types/src/binding-redirect.d.ts +58 -31
  40. package/types/src/binding-simplesign.d.ts +77 -21
  41. package/types/src/entity-idp.d.ts +40 -31
  42. package/types/src/entity-sp.d.ts +37 -27
  43. package/types/src/entity.d.ts +71 -77
  44. package/types/src/extractor.d.ts +31 -22
  45. package/types/src/flow.d.ts +24 -2
  46. package/types/src/libsaml.d.ts +172 -118
  47. package/types/src/metadata-idp.d.ts +27 -11
  48. package/types/src/metadata-sp.d.ts +29 -19
  49. package/types/src/metadata.d.ts +59 -34
  50. package/types/src/options.d.ts +37 -0
  51. package/types/src/types.d.ts +250 -24
  52. package/types/src/urn.d.ts +7 -0
  53. package/types/src/utility.d.ts +144 -89
  54. package/types/src/validator.d.ts +21 -0
  55. package/.circleci/config.yml +0 -98
  56. package/.editorconfig +0 -19
  57. package/.github/FUNDING.yml +0 -1
  58. package/.github/workflows/deploy-docs.yml +0 -56
  59. package/.pre-commit.sh +0 -15
  60. package/.snyk +0 -4
  61. package/Makefile +0 -25
  62. package/index.ts +0 -28
  63. package/src/api.ts +0 -36
  64. package/src/binding-post.ts +0 -336
  65. package/src/binding-redirect.ts +0 -335
  66. package/src/binding-simplesign.ts +0 -231
  67. package/src/entity-idp.ts +0 -145
  68. package/src/entity-sp.ts +0 -114
  69. package/src/entity.ts +0 -243
  70. package/src/extractor.ts +0 -399
  71. package/src/flow.ts +0 -469
  72. package/src/libsaml.ts +0 -777
  73. package/src/metadata-idp.ts +0 -146
  74. package/src/metadata-sp.ts +0 -203
  75. package/src/metadata.ts +0 -166
  76. package/src/types.ts +0 -127
  77. package/src/urn.ts +0 -210
  78. package/src/utility.ts +0 -231
  79. package/src/validator.ts +0 -44
  80. package/tsconfig.json +0 -41
  81. package/tslint.json +0 -35
  82. package/types.d.ts +0 -2
  83. package/vitest.config.ts +0 -12
@@ -1,24 +1,40 @@
1
1
  /**
2
- * @file metadata-idp.ts
3
- * @author tngan
4
- * @desc Metadata of identity provider
5
- */
2
+ * @file metadata-idp.ts
3
+ * @author tngan
4
+ * @desc Metadata of an identity provider (IdP). Accepts either a raw XML
5
+ * document or a structured options object and presents a normalised API.
6
+ */
6
7
  import Metadata, { MetadataInterface } from './metadata';
7
8
  import { MetadataIdpConstructor } from './types';
9
+ /** Public interface exposed by IdP metadata instances. */
8
10
  export interface IdpMetadataInterface extends MetadataInterface {
9
11
  }
12
+ /**
13
+ * Factory returning a new {@link IdpMetadata} instance.
14
+ *
15
+ * @param meta XML metadata document or structured options
16
+ * @returns fresh IdpMetadata
17
+ */
10
18
  export default function (meta: MetadataIdpConstructor): IdpMetadata;
11
19
  export declare class IdpMetadata extends Metadata {
20
+ /**
21
+ * Build IdP metadata from XML or programmatic options.
22
+ *
23
+ * @param meta XML string/Buffer or {@link MetadataIdpOptions}
24
+ */
12
25
  constructor(meta: MetadataIdpConstructor);
13
26
  /**
14
- * @desc Get the preference whether it wants a signed request
15
- * @return {boolean} WantAuthnRequestsSigned
16
- */
27
+ * Return whether the IdP requires signed `AuthnRequest` messages.
28
+ *
29
+ * @returns true when the metadata advertises `WantAuthnRequestsSigned="true"`
30
+ */
17
31
  isWantAuthnRequestsSigned(): boolean;
18
32
  /**
19
- * @desc Get the entity endpoint for single sign on service
20
- * @param {string} binding protocol binding (e.g. redirect, post)
21
- * @return {string/object} location
22
- */
33
+ * Return the single sign-on endpoint URL for the given binding, or the
34
+ * full service map when the binding isn't a string.
35
+ *
36
+ * @param binding protocol binding key (`redirect`, `post`, etc.)
37
+ * @returns endpoint URL or raw service map
38
+ */
23
39
  getSingleSignOnService(binding: string): string | object;
24
40
  }
@@ -1,36 +1,46 @@
1
1
  /**
2
- * @file metadata-sp.ts
3
- * @author tngan
4
- * @desc Metadata of service provider
5
- */
2
+ * @file metadata-sp.ts
3
+ * @author tngan
4
+ * @desc Metadata of a service provider (SP). Accepts either a raw XML
5
+ * document or a structured options object and presents a normalised API.
6
+ */
6
7
  import Metadata, { MetadataInterface } from './metadata';
7
8
  import { MetadataSpConstructor } from './types';
9
+ /** Public interface exposed by SP metadata instances. */
8
10
  export interface SpMetadataInterface extends MetadataInterface {
9
11
  }
12
+ /**
13
+ * Factory returning a new {@link SpMetadata} instance.
14
+ *
15
+ * @param meta XML metadata document or structured options
16
+ * @returns fresh SpMetadata
17
+ */
10
18
  export default function (meta: MetadataSpConstructor): SpMetadata;
11
19
  /**
12
- * @desc SP Metadata is for creating Service Provider, provides a set of API to manage the actions in SP.
13
- */
20
+ * SP metadata abstraction constructs a valid EntityDescriptor/SPSSODescriptor
21
+ * from options, and exposes inspection helpers used by the flow layer.
22
+ */
14
23
  export declare class SpMetadata extends Metadata {
15
24
  /**
16
- * @param {object/string} meta (either xml string or configuration in object)
17
- * @return {object} prototypes including public functions
18
- */
25
+ * Build SP metadata from XML or programmatic options.
26
+ *
27
+ * @param meta XML string/Buffer or {@link MetadataSpOptions}
28
+ */
19
29
  constructor(meta: MetadataSpConstructor);
20
30
  /**
21
- * @desc Get the preference whether it wants a signed assertion response
22
- * @return {boolean} Wantassertionssigned
23
- */
31
+ * Return whether the SP requires signed assertions.
32
+ */
24
33
  isWantAssertionsSigned(): boolean;
25
34
  /**
26
- * @desc Get the preference whether it signs request
27
- * @return {boolean} Authnrequestssigned
28
- */
35
+ * Return whether the SP signs its `AuthnRequest` messages.
36
+ */
29
37
  isAuthnRequestSigned(): boolean;
30
38
  /**
31
- * @desc Get the entity endpoint for assertion consumer service
32
- * @param {string} binding protocol binding (e.g. redirect, post)
33
- * @return {string/[string]} URL of endpoint(s)
34
- */
39
+ * Return the AssertionConsumerService endpoint URL(s) for the requested
40
+ * binding.
41
+ *
42
+ * @param binding protocol binding key (`redirect`, `post`, etc.)
43
+ * @returns endpoint URL, list of URLs, or raw service list
44
+ */
35
45
  getAssertionConsumerService(binding: string): string | string[];
36
46
  }
@@ -1,57 +1,82 @@
1
+ import type { ExtractorFields } from './types';
2
+ /** Public interface exposed by every metadata instance. */
1
3
  export interface MetadataInterface {
2
4
  xmlString: string;
3
5
  getMetadata: () => string;
4
6
  exportMetadata: (exportFile: string) => void;
5
7
  getEntityID: () => string;
6
8
  getX509Certificate: (certType: string) => string | string[];
7
- getNameIDFormat: () => any[];
9
+ getNameIDFormat: () => string[];
8
10
  getSingleLogoutService: (binding: string | undefined) => string | object;
9
11
  getSupportBindings: (services: string[]) => string[];
10
12
  }
13
+ /** Parsed metadata bag exposed under `meta`. */
14
+ export interface MetadataBag {
15
+ [key: string]: unknown;
16
+ entityDescriptor?: string | string[];
17
+ entityID?: string;
18
+ sharedCertificate?: string;
19
+ certificate?: {
20
+ signing?: string | string[];
21
+ encryption?: string | string[];
22
+ } | Record<string, string | string[]>;
23
+ singleLogoutService?: Array<{
24
+ binding: string;
25
+ location: string;
26
+ }> | {
27
+ binding: string;
28
+ location: string;
29
+ };
30
+ nameIDFormat?: string | string[];
31
+ }
11
32
  export default class Metadata implements MetadataInterface {
12
33
  xmlString: string;
13
- meta: any;
34
+ meta: MetadataBag;
14
35
  /**
15
- * @param {string | Buffer} xml
16
- * @param {object} extraParse for custom metadata extractor
17
- */
18
- constructor(xml: string | Buffer, extraParse?: any);
36
+ * Parse a SAML metadata XML document and hydrate a typed `meta` bag.
37
+ *
38
+ * @param xml raw metadata XML (string or Buffer)
39
+ * @param extraParse additional extractor fields merged into the standard set
40
+ */
41
+ constructor(xml: string | Buffer, extraParse?: ExtractorFields);
19
42
  /**
20
- * @desc Get the metadata in xml format
21
- * @return {string} metadata in xml format
22
- */
43
+ * Return the underlying metadata XML.
44
+ */
23
45
  getMetadata(): string;
24
46
  /**
25
- * @desc Export the metadata to specific file
26
- * @param {string} exportFile is the output file path
27
- */
47
+ * Write the metadata XML to disk at the given path.
48
+ *
49
+ * @param exportFile absolute file path
50
+ */
28
51
  exportMetadata(exportFile: string): void;
29
52
  /**
30
- * @desc Get the entityID in metadata
31
- * @return {string} entityID
32
- */
53
+ * Return the metadata `entityID`.
54
+ */
33
55
  getEntityID(): string;
34
56
  /**
35
- * @desc Get the x509 certificate declared in entity metadata
36
- * @param {string} use declares the type of certificate
37
- * @return {string} certificate in string format
38
- */
39
- getX509Certificate(use: string): any;
40
- /**
41
- * @desc Get the support NameID format declared in entity metadata
42
- * @return {array} support NameID format
43
- */
44
- getNameIDFormat(): any;
45
- /**
46
- * @desc Get the entity endpoint for single logout service
47
- * @param {string} binding e.g. redirect, post
48
- * @return {string/object} location
49
- */
57
+ * Return the X.509 certificate(s) declared in metadata for a given use.
58
+ *
59
+ * @param use `signing` or `encryption`
60
+ * @returns certificate body or list, or `null` when missing
61
+ */
62
+ getX509Certificate(use: string): string | string[];
63
+ /**
64
+ * Return the supported NameID formats declared in metadata.
65
+ */
66
+ getNameIDFormat(): string[];
67
+ /**
68
+ * Return the single-logout service endpoint for the requested binding.
69
+ * When no binding is provided, returns the raw service list.
70
+ *
71
+ * @param binding `redirect`, `post`, etc.
72
+ * @returns endpoint URL or raw service list
73
+ */
50
74
  getSingleLogoutService(binding: string | undefined): string | object;
51
75
  /**
52
- * @desc Get the support bindings
53
- * @param {[string]} services
54
- * @return {[string]} support bindings
55
- */
76
+ * Reduce a service descriptor array to the list of bindings it declares.
77
+ *
78
+ * @param services list of service descriptor objects
79
+ * @returns supported binding keys
80
+ */
56
81
  getSupportBindings(services: string[]): string[];
57
82
  }
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @file options.ts
3
+ * @desc Backwards-compatible discriminators for the options-bag /
4
+ * legacy-positional shapes accepted by the create* methods on
5
+ * Entity / IdentityProvider / ServiceProvider.
6
+ *
7
+ * Per `saml-bindings §3.4.3, §3.5.3`, RelayState is request-scoped.
8
+ * These helpers let callers pass it as part of an options bag while
9
+ * preserving the legacy callback-only / string-only positional shapes.
10
+ */
11
+ import type { CreateLoginRequestOptions, CreateLoginResponseOptions, CreateLogoutRequestOptions, CreateLogoutResponseOptions, CustomTagReplacement } from './types';
12
+ /**
13
+ * Resolve the 3rd-position parameter of `ServiceProvider#createLoginRequest`.
14
+ * Accepts a callback (legacy), an options bag, or undefined.
15
+ */
16
+ export declare function normalizeCreateLoginRequestOptions(input: CreateLoginRequestOptions | CustomTagReplacement | undefined): CreateLoginRequestOptions;
17
+ /**
18
+ * Resolve the 5th-position parameter of `IdentityProvider#createLoginResponse`.
19
+ * Accepts a callback (legacy), an options bag, or undefined.
20
+ *
21
+ * Legacy positional `encryptThenSign` (6th) and `relayState` (7th) are
22
+ * folded into the bag when the 5th argument is the legacy callback form.
23
+ */
24
+ export declare function normalizeCreateLoginResponseOptions(optionsOrCallback: CreateLoginResponseOptions | CustomTagReplacement | undefined, legacyEncryptThenSign?: boolean, legacyRelayState?: string): CreateLoginResponseOptions;
25
+ /**
26
+ * Resolve the 4th-position parameter of `Entity#createLogoutRequest`.
27
+ * Accepts a string (legacy `relayState`), an options bag, or undefined.
28
+ *
29
+ * Legacy positional `customTagReplacement` (5th) is folded into the bag
30
+ * when the 4th argument is the legacy string form.
31
+ */
32
+ export declare function normalizeCreateLogoutRequestOptions(optionsOrRelayState: CreateLogoutRequestOptions | string | undefined, legacyCustomTagReplacement?: CustomTagReplacement): CreateLogoutRequestOptions;
33
+ /**
34
+ * Resolve the 4th-position parameter of `Entity#createLogoutResponse`.
35
+ * Same dispatch rules as {@link normalizeCreateLogoutRequestOptions}.
36
+ */
37
+ export declare function normalizeCreateLogoutResponseOptions(optionsOrRelayState: CreateLogoutResponseOptions | string | undefined, legacyCustomTagReplacement?: CustomTagReplacement): CreateLogoutResponseOptions;
@@ -3,12 +3,188 @@ export { IdentityProvider as IdentityProviderConstructor } from './entity-idp';
3
3
  export { IdpMetadata as IdentityProviderMetadata } from './metadata-idp';
4
4
  export { ServiceProvider as ServiceProviderConstructor } from './entity-sp';
5
5
  export { SpMetadata as ServiceProviderMetadata } from './metadata-sp';
6
+ /** Raw metadata payload: either the XML contents or a path. */
6
7
  export type MetadataFile = string | Buffer;
7
- type SSOService = {
8
+ /** SAML SSO service endpoint descriptor. */
9
+ export interface SSOService {
8
10
  isDefault?: boolean;
9
11
  Binding: string;
10
12
  Location: string;
11
- };
13
+ }
14
+ /** Primitive value types that appear inside XML attributes. */
15
+ export type XmlAttributeValue = string | number | boolean | undefined;
16
+ /** Attribute bag accepted by the `xml` module (element `_attr` slot). */
17
+ export type XmlAttributeMap = Record<string, XmlAttributeValue>;
18
+ /** An `{ _attr: {...} }` node accepted by the `xml` module. */
19
+ export interface XmlAttrNode {
20
+ _attr: XmlAttributeMap;
21
+ }
22
+ /** Recursive node shape accepted by the `xml` module. */
23
+ export type XmlNode = string | number | boolean | XmlAttrNode | {
24
+ [tagName: string]: unknown;
25
+ } | XmlNode[];
26
+ /** Element array for the `xml` module builder. */
27
+ export type XmlElementArray = XmlNode[];
28
+ /**
29
+ * Replacement map for template-tag interpolation.
30
+ * Values are stringified by the replacement routine.
31
+ */
32
+ export type TagReplacementMap = Record<string, string | number | boolean | null | undefined>;
33
+ /** Per-scalar value produced by the SAML XPath extractor. */
34
+ export type ExtractorValue = string | string[] | number | boolean | null | Record<string, string | string[]>;
35
+ /**
36
+ * Result object produced by `extract`. Keys depend on the fields requested;
37
+ * the documented members below cover the common SAML flows.
38
+ */
39
+ export interface ExtractorResult {
40
+ [key: string]: ExtractorValue | undefined;
41
+ signature?: string | string[];
42
+ issuer?: string | string[];
43
+ nameID?: string;
44
+ conditions?: Record<string, string | string[]>;
45
+ sessionIndex?: Record<string, string | string[]>;
46
+ attributes?: Record<string, string | string[]>;
47
+ response?: Record<string, string | string[]>;
48
+ request?: Record<string, string | string[]>;
49
+ audience?: string | string[];
50
+ authnContextClassRef?: string | string[];
51
+ nameIDPolicy?: Record<string, string | string[]>;
52
+ }
53
+ /** Field definition consumed by `extract`. */
54
+ export interface ExtractorField {
55
+ key: string;
56
+ localPath: string[] | string[][];
57
+ attributes: string[];
58
+ index?: string[];
59
+ attributePath?: string[];
60
+ context?: boolean;
61
+ shortcut?: string;
62
+ }
63
+ /** Array of extractor field definitions. */
64
+ export type ExtractorFields = ExtractorField[];
65
+ /**
66
+ * Minimal HTTP request shape the library consumes from the caller's web
67
+ * framework. Only the fields SAML needs are typed.
68
+ */
69
+ export interface ESamlHttpRequest {
70
+ query?: Record<string, string | undefined>;
71
+ body?: Record<string, string | undefined>;
72
+ octetString?: string;
73
+ }
74
+ /**
75
+ * Parsed request snapshot passed around when building response messages
76
+ * so the response can include matching `InResponseTo` references.
77
+ */
78
+ export interface RequestInfo {
79
+ extract: ExtractorResult;
80
+ [key: string]: unknown;
81
+ }
82
+ /**
83
+ * Authenticated user passed to the IdP when building a login/logout
84
+ * response. Additional custom claims are permitted via the index signature.
85
+ */
86
+ export interface SAMLUser {
87
+ email?: string;
88
+ logoutNameID?: string;
89
+ sessionIndex?: string;
90
+ [key: string]: unknown;
91
+ }
92
+ /**
93
+ * Caller-supplied template transformer used by the create* methods.
94
+ * Receives the raw template string and returns the substituted result
95
+ * along with the SAML message ID.
96
+ */
97
+ export type CustomTagReplacement = (template: string) => BindingContext;
98
+ /**
99
+ * Per-request options accepted by `ServiceProvider#createLoginRequest`.
100
+ *
101
+ * `relayState` here takes precedence over `entitySetting.relayState`,
102
+ * which is deprecated for v3 — see `saml-bindings §3.4.3` and §3.5.3
103
+ * (RelayState is request-scoped, not entity-scoped).
104
+ */
105
+ export interface CreateLoginRequestOptions {
106
+ relayState?: string;
107
+ customTagReplacement?: CustomTagReplacement;
108
+ /** saml-core §3.4.1 — when true, the IdP MUST re-authenticate the user. */
109
+ forceAuthn?: boolean;
110
+ /**
111
+ * saml-core §3.4.1 — `<samlp:AuthnRequest>` may identify the desired ACS
112
+ * endpoint either by URL+ProtocolBinding *or* by an index into the SP's
113
+ * metadata. The three attributes are mutually exclusive: "If the
114
+ * `<AssertionConsumerServiceIndex>` attribute is present, neither
115
+ * `<AssertionConsumerServiceURL>` nor `<ProtocolBinding>` may be set."
116
+ *
117
+ * When this option is set, samlify omits both `AssertionConsumerServiceURL`
118
+ * and `ProtocolBinding` from the rendered request — including any
119
+ * metadata-derived ACS URL the SP would otherwise inject. In other words,
120
+ * if the caller sets `assertionConsumerServiceIndex`, the index wins;
121
+ * mutual exclusion enforcement is the caller's responsibility.
122
+ *
123
+ * Useful for IdPs (legacy Shibboleth, certain ADFS configurations) that
124
+ * prefer the metadata-indexed form per saml-profiles §4.1.4.1.
125
+ */
126
+ assertionConsumerServiceIndex?: number;
127
+ }
128
+ /** Per-request options accepted by `IdentityProvider#createLoginResponse`. */
129
+ export interface CreateLoginResponseOptions {
130
+ relayState?: string;
131
+ customTagReplacement?: CustomTagReplacement;
132
+ /** When true, encrypt the assertion before signing the message. */
133
+ encryptThenSign?: boolean;
134
+ }
135
+ /** Per-request options accepted by `Entity#createLogoutRequest`. */
136
+ export interface CreateLogoutRequestOptions {
137
+ relayState?: string;
138
+ customTagReplacement?: CustomTagReplacement;
139
+ }
140
+ /** Per-request options accepted by `Entity#createLogoutResponse`. */
141
+ export interface CreateLogoutResponseOptions {
142
+ relayState?: string;
143
+ customTagReplacement?: CustomTagReplacement;
144
+ }
145
+ /** Output of an XML-signature binding step (base64 SAML + request id). */
146
+ export interface BindingContext {
147
+ context: string;
148
+ id: string;
149
+ }
150
+ /** Post-binding output extended with the endpoint, relay state, and kind. */
151
+ export interface PostBindingContext extends BindingContext {
152
+ relayState?: string;
153
+ entityEndpoint: string;
154
+ type: string;
155
+ }
156
+ /** Simple-sign binding output. */
157
+ export interface SimpleSignBindingContext extends PostBindingContext {
158
+ sigAlg?: string;
159
+ signature?: string;
160
+ keyInfo?: string;
161
+ }
162
+ /** Simple-sign computed output without the outer endpoint wrapper. */
163
+ export interface SimpleSignComputedContext extends BindingContext {
164
+ sigAlg?: string;
165
+ signature?: string;
166
+ }
167
+ /** Parsed result emitted by SAML binding parsers. */
168
+ export interface ParseResult {
169
+ samlContent: string;
170
+ extract: ExtractorResult;
171
+ sigAlg: string;
172
+ }
173
+ /** Options for `MetadataSpOptions#signatureConfig`. */
174
+ export interface SignatureConfig {
175
+ prefix?: string;
176
+ location?: {
177
+ reference?: string;
178
+ action?: 'append' | 'prepend' | 'before' | 'after';
179
+ };
180
+ attrs?: Record<string, string>;
181
+ existingPrefixes?: Record<string, string>;
182
+ }
183
+ /** SAML root-element wrapping template (request/response contexts). */
184
+ export interface SAMLDocumentTemplate {
185
+ context?: string;
186
+ }
187
+ /** Options accepted when constructing IdP metadata programmatically. */
12
188
  export interface MetadataIdpOptions {
13
189
  entityID?: string;
14
190
  signingCert?: string | Buffer | (string | Buffer)[];
@@ -18,8 +194,19 @@ export interface MetadataIdpOptions {
18
194
  singleSignOnService?: SSOService[];
19
195
  singleLogoutService?: SSOService[];
20
196
  requestSignatureAlgorithm?: string;
197
+ /**
198
+ * Override the order of child elements rendered inside
199
+ * `<IDPSSODescriptor>`. Each entry names a child element; the constructor
200
+ * emits the populated children in the order given. Mirrors the SP-side
201
+ * `MetadataSpOptions.elementsOrder`. Pre-baked variants are exposed via
202
+ * `Constants.elementsOrder.idp` (`default`, `onelogin`, `shibboleth`).
203
+ * See `saml-metadata §2.4.3` for the schema-declared sequence (#429).
204
+ */
205
+ elementsOrder?: string[];
21
206
  }
207
+ /** Constructor argument for IdP metadata: options or raw XML. */
22
208
  export type MetadataIdpConstructor = MetadataIdpOptions | MetadataFile;
209
+ /** Options accepted when constructing SP metadata programmatically. */
23
210
  export interface MetadataSpOptions {
24
211
  entityID?: string;
25
212
  signingCert?: string | Buffer | (string | Buffer)[];
@@ -27,28 +214,19 @@ export interface MetadataSpOptions {
27
214
  authnRequestsSigned?: boolean;
28
215
  wantAssertionsSigned?: boolean;
29
216
  wantMessageSigned?: boolean;
30
- signatureConfig?: {
31
- [key: string]: any;
32
- };
217
+ signatureConfig?: SignatureConfig;
33
218
  nameIDFormat?: string[];
34
219
  singleSignOnService?: SSOService[];
35
220
  singleLogoutService?: SSOService[];
36
221
  assertionConsumerService?: SSOService[];
37
222
  elementsOrder?: string[];
38
223
  }
224
+ /** Constructor argument for SP metadata: options or raw XML. */
39
225
  export type MetadataSpConstructor = MetadataSpOptions | MetadataFile;
226
+ /** Combined settings bag carried by an Entity. */
40
227
  export type EntitySetting = ServiceProviderSettings & IdentityProviderSettings;
41
- export interface SignatureConfig {
42
- prefix?: string;
43
- location?: {
44
- reference?: string;
45
- action?: 'append' | 'prepend' | 'before' | 'after';
46
- };
47
- }
48
- export interface SAMLDocumentTemplate {
49
- context?: string;
50
- }
51
- export type ServiceProviderSettings = {
228
+ /** Service-provider configuration accepted by the SP factory. */
229
+ export interface ServiceProviderSettings {
52
230
  metadata?: string | Buffer;
53
231
  entityID?: string;
54
232
  authnRequestsSigned?: boolean;
@@ -67,23 +245,36 @@ export type ServiceProviderSettings = {
67
245
  signatureConfig?: SignatureConfig;
68
246
  loginRequestTemplate?: SAMLDocumentTemplate;
69
247
  logoutRequestTemplate?: SAMLDocumentTemplate;
248
+ logoutResponseTemplate?: SAMLDocumentTemplate;
70
249
  signingCert?: string | Buffer | (string | Buffer)[];
71
250
  encryptCert?: string | Buffer | (string | Buffer)[];
72
251
  transformationAlgorithms?: string[];
73
252
  nameIDFormat?: string[];
74
253
  allowCreate?: boolean;
254
+ /**
255
+ * @deprecated Pass `relayState` per request via the options bag on
256
+ * `createLoginRequest` / `createLogoutRequest` / `createLogoutResponse`
257
+ * instead. RelayState is request-scoped per `saml-bindings §3.4.3, §3.5.3`;
258
+ * keeping it on the entity makes a single SP/IdP instance unsafe for
259
+ * concurrent requests with different relay state values. Will be removed
260
+ * in v3.
261
+ */
75
262
  relayState?: string;
263
+ /** Clock drift tolerance in ms for notBefore / notOnOrAfter checks. */
76
264
  clockDrifts?: [number, number];
77
- };
78
- export type IdentityProviderSettings = {
265
+ }
266
+ /** Identity-provider configuration accepted by the IdP factory. */
267
+ export interface IdentityProviderSettings {
79
268
  metadata?: string | Buffer;
80
- /** signature algorithm */
269
+ /** XML-DSig signature algorithm URI for requests. */
81
270
  requestSignatureAlgorithm?: string;
82
- /** template of login response */
271
+ /** Login response template with optional attribute statements. */
83
272
  loginResponseTemplate?: LoginResponseTemplate;
84
- /** template of logout request */
273
+ /** Logout request XML template. */
85
274
  logoutRequestTemplate?: SAMLDocumentTemplate;
86
- /** customized function used for generating request ID */
275
+ /** Logout response XML template. */
276
+ logoutResponseTemplate?: SAMLDocumentTemplate;
277
+ /** Callback used to generate a unique SAML message ID. */
87
278
  generateID?: () => string;
88
279
  entityID?: string;
89
280
  privateKey?: string | Buffer;
@@ -101,7 +292,42 @@ export type IdentityProviderSettings = {
101
292
  wantLogoutResponseSigned?: boolean;
102
293
  wantAuthnRequestsSigned?: boolean;
103
294
  wantLogoutRequestSignedResponseSigned?: boolean;
295
+ /**
296
+ * Override the XML namespace prefixes used when rendering the IdP's
297
+ * default request/response templates.
298
+ *
299
+ * - `protocol` rebinds the SAML protocol namespace
300
+ * (`urn:oasis:names:tc:SAML:2.0:protocol`, default prefix `samlp`).
301
+ * - `assertion` rebinds the SAML assertion namespace
302
+ * (`urn:oasis:names:tc:SAML:2.0:assertion`, default prefix `saml`).
303
+ * - `encryptedAssertion` is the prefix wrapped around
304
+ * `<EncryptedAssertion>` inside `libsaml.encryptAssertion`.
305
+ *
306
+ * Per saml-core §1.4 the prefix choice is not normative — only the
307
+ * namespace URI bindings are. Some peers (legacy ADFS quirks, custom
308
+ * integrations) require non-standard prefixes; this lets callers swap
309
+ * `samlp:` ↔ `samlp2:` and `saml:` ↔ `saml2:` without supplying a fully
310
+ * custom template (closes #388).
311
+ */
104
312
  tagPrefix?: {
105
- [key: string]: string;
313
+ /** Prefix bound to the SAML protocol namespace (default: 'samlp'). */
314
+ protocol?: string;
315
+ /** Prefix bound to the SAML assertion namespace (default: 'saml'). */
316
+ assertion?: string;
317
+ /** Prefix used when wrapping `<EncryptedAssertion>`. */
318
+ encryptedAssertion?: string;
319
+ [key: string]: string | undefined;
106
320
  };
107
- };
321
+ /**
322
+ * @internal Populated by the IdP constructor when `tagPrefix.protocol`
323
+ * or `tagPrefix.assertion` is overridden — pre-rewritten copies of the
324
+ * built-in default request/response templates that the bindings consume
325
+ * in place of the library-internal defaults. Not part of the public
326
+ * configuration surface.
327
+ */
328
+ tagPrefixedDefaults?: {
329
+ loginResponseTemplate?: SAMLDocumentTemplate;
330
+ logoutRequestTemplate?: SAMLDocumentTemplate;
331
+ logoutResponseTemplate?: SAMLDocumentTemplate;
332
+ };
333
+ }
@@ -135,6 +135,7 @@ declare const algorithms: {
135
135
  RSA_SHA1: string;
136
136
  RSA_SHA256: string;
137
137
  RSA_SHA512: string;
138
+ RSA_SHA256_MGF1: string;
138
139
  };
139
140
  encryption: {
140
141
  data: {
@@ -152,6 +153,7 @@ declare const algorithms: {
152
153
  'http://www.w3.org/2000/09/xmldsig#rsa-sha1': string;
153
154
  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256': string;
154
155
  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512': string;
156
+ 'http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1': string;
155
157
  };
156
158
  };
157
159
  export declare enum ParserType {
@@ -189,5 +191,10 @@ declare const elementsOrder: {
189
191
  default: string[];
190
192
  onelogin: string[];
191
193
  shibboleth: string[];
194
+ idp: {
195
+ default: string[];
196
+ onelogin: string[];
197
+ shibboleth: string[];
198
+ };
192
199
  };
193
200
  export { namespace, tags, algorithms, wording, elementsOrder, messageConfigurations };