samlify 2.12.0 → 2.13.0

package/types/src/utility.d.ts

@@ -1,125 +1,174 @@
 /**
- * @desc Mimic lodash.zipObject
- * @param arr1 {string[]}
- * @param arr2 {[]}
+ * Build an object by zipping two parallel arrays of keys and values.
+ * When `skipDuplicated` is false, colliding keys are aggregated into arrays
+ * so duplicate keys do not clobber earlier values.
+ *
+ * @param arr1 key array
+ * @param arr2 value array (same index as keys)
+ * @param skipDuplicated when true (default) later writes overwrite earlier ones
+ * @returns object composed from key/value pairs
  */
-export declare function zipObject(arr1: string[], arr2: any[], skipDuplicated?: boolean): {};
+export declare function zipObject<T>(arr1: string[], arr2: T[], skipDuplicated?: boolean): Record<string, T | T[]>;
 /**
- * @desc Alternative to lodash.flattenDeep
- * @reference https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_flattendeep
- * @param input {[]}
+ * Recursively flatten a nested array into a single-level array.
+ *
+ * @param input nested array input
+ * @returns flattened array
  */
-export declare function flattenDeep(input: any[]): any;
+export declare function flattenDeep<T>(input: T | T[]): T[];
 /**
- * @desc Alternative to lodash.last
- * @reference https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_last
- * @param input {[]}
+ * Return the last element of an array.
+ *
+ * @param input source array
+ * @returns the final element, or undefined when the array is empty
  */
-export declare function last(input: any[]): any;
+export declare function last<T>(input: T[]): T;
 /**
- * @desc Alternative to lodash.uniq
- * @reference https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_uniq
- * @param input {string[]}
+ * Return a copy of a string array with duplicates removed.
+ *
+ * @param input array with possible duplicates
+ * @returns array in original order without duplicates
  */
 export declare function uniq(input: string[]): string[];
 /**
- * @desc Alternative to lodash.get
- * @reference https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_get
- * @param obj
- * @param path
- * @param defaultValue
+ * Safely read a dotted path from an object, returning `defaultValue` when
+ * any segment is missing.
+ *
+ * @param obj source object
+ * @param path dotted path expression (e.g. "a.b.c")
+ * @param defaultValue fallback when the path does not resolve
+ * @returns resolved value or the default
  */
-export declare function get(obj: any, path: any, defaultValue: any): any;
+export declare function get<T = unknown>(obj: Record<string, unknown> | null | undefined, path: string, defaultValue?: T | null): T | null;
 /**
- * @desc Check if the input is string
- * @param {any} input
+ * Type guard for strings.
+ *
+ * @param input value to test
+ * @returns true when the input is a string primitive
  */
-export declare function isString(input: any): input is string;
+export declare function isString(input: unknown): input is string;
 /**
-* @desc Encode string with base64 format
-* @param  {string} message                       plain-text message
-* @return {string} base64 encoded string
-*/
+ * Encode a string or byte array as base64.
+ *
+ * @param message plain text or raw bytes
+ * @returns base64 encoded string
+ */
 declare function base64Encode(message: string | number[]): string;
 /**
-* @desc Decode string from base64 format
-* @param  {string} base64Message                 encoded string
-* @param  {boolean} isBytes                      determine the return value type (True: bytes False: string)
-* @return {bytes/string}  decoded bytes/string depends on isBytes, default is {string}
-*/
+ * Decode a base64 message. Returns either the decoded string or the raw
+ * Buffer depending on `isBytes`.
+ *
+ * @param base64Message base64 encoded payload
+ * @param isBytes when true, return a Buffer instead of a string
+ * @returns decoded string or Buffer
+ */
 export declare function base64Decode(base64Message: string, isBytes?: boolean): string | Buffer;
 /**
-* @desc Compress the string
-* @param  {string} message
-* @return {string} compressed string
-*/
+ * Raw-deflate a UTF-8 string and return the compressed bytes.
+ *
+ * @param message plain text
+ * @returns compressed bytes as a number array
+ */
 declare function deflateString(message: string): number[];
 /**
-* @desc Decompress the compressed string
-* @param  {string} compressedString
-* @return {string} decompressed string
-*/
+ * Raw-inflate a base64 string that was produced by {@link deflateString}.
+ *
+ * @param compressedString base64-encoded raw-deflate payload
+ * @returns decompressed UTF-8 string
+ */
 export declare function inflateString(compressedString: string): string;
 /**
-* @desc Parse the .cer to string format without line break, header and footer
-* @param  {string} certString     declares the certificate contents
-* @return {string} certificiate in string format
-*/
+ * Normalise a PEM certificate string to its base64 body.
+ *
+ * @param certString PEM-encoded X.509 certificate
+ * @returns certificate body without headers/whitespace
+ */
 declare function normalizeCerString(certString: string | Buffer): string;
 /**
-* @desc Normalize the string in .pem format without line break, header and footer
-* @param  {string} pemString
-* @return {string} private key in string format
-*/
+ * Normalise a PEM RSA private key string to its base64 body.
+ *
+ * @param pemString PEM-encoded RSA private key
+ * @returns key body without headers/whitespace
+ */
 declare function normalizePemString(pemString: string | Buffer): string;
 /**
-* @desc Return the complete URL
-* @param  {object} req                   HTTP request
-* @return {string} URL
-*/
-declare function getFullURL(req: any): string;
-/**
-* @desc Parse input string, return default value if it is undefined
-* @param  {string/boolean}
-* @return {boolean}
-*/
-declare function parseString(str: any, defaultValue?: string): any;
-/**
-* @desc Override the object by another object (rtl)
-* @param  {object} default object
-* @param  {object} object applied to the default object
-* @return {object} result object
-*/
-declare function applyDefault(obj1: any, obj2: any): any;
-/**
-* @desc Get public key in pem format from the certificate included in the metadata
-* @param {string} x509 certificate
-* @return {string} public key fetched from the certificate
-*/
-declare function getPublicKeyPemFromCertificate(x509Certificate: string): string;
-/**
-* @desc Read private key from pem-formatted string
-* @param {string | Buffer} keyString pem-formatted string
-* @param {string} protected passphrase of the key
-* @return {string} string in pem format
-* If passphrase is used to protect the .pem content (recommend)
-*/
-export declare function readPrivateKey(keyString: string | Buffer, passphrase: string | undefined, isOutputString?: boolean): any;
-/**
-* @desc Inline syntax sugar
-*/
-declare function convertToString(input: any, isOutputString: any): any;
-/**
- * @desc Check if the input is an array with non-zero size
- */
-export declare function isNonEmptyArray(a: any): boolean;
+ * Reconstruct the full URL (protocol + host + path) from an Express-style
+ * HTTP request.
+ *
+ * @param req Express-compatible request object
+ * @returns absolute URL string
+ */
+declare function getFullURL(req: {
+    protocol: string;
+    get: (name: string) => string | undefined;
+    originalUrl: string;
+}): string;
+/**
+ * Return `str` when it is truthy, otherwise the provided default.
+ */
+declare function parseString(str: string | undefined | null, defaultValue?: string): string;
+/**
+ * Shallow-merge `obj2` on top of `obj1`, returning a new object.
+ */
+declare function applyDefault<A extends object, B extends object>(obj1: A, obj2: B): A & B;
+/**
+ * Extract the SPKI PEM public key from a base64 X.509 certificate body.
+ *
+ * @param x509Certificate normalised certificate body (no PEM wrappers)
+ * @returns PEM-encoded public key
+ */
+declare function getPublicKeyPemFromCertificate(x509Certificate: string): string | Buffer;
+/**
+ * Read a PEM private key, optionally decrypting it with a passphrase.
+ *
+ * @param keyString PEM key contents
+ * @param passphrase optional passphrase protecting the key
+ * @param isOutputString when true, always return a string
+ * @returns PEM key as string or Buffer
+ */
+export declare function readPrivateKey(keyString: string | Buffer, passphrase: string | undefined, isOutputString?: boolean): string | Buffer;
+/**
+ * Coerce a value to a string when `isOutputString` is true, otherwise pass
+ * it through untouched.
+ */
+declare function convertToString(input: string | Buffer, isOutputString?: boolean): string | Buffer;
+/**
+ * Check that the input is an array with at least one element.
+ *
+ * @param a candidate value
+ * @returns true when the argument is a non-empty array
+ */
+export declare function isNonEmptyArray<T>(a: unknown): a is T[];
+/**
+ * Wrap a single value in an array, or return the array unchanged.
+ * An undefined input returns an empty array.
+ *
+ * @param a scalar, array, or undefined
+ * @returns array form of the input
+ */
 export declare function castArrayOpt<T>(a?: T | T[]): T[];
+/**
+ * Type guard removing `null` and `undefined` from a union.
+ *
+ * @param value value to narrow
+ * @returns true when the value is neither null nor undefined
+ */
 export declare function notEmpty<TValue>(value: TValue | null | undefined): value is TValue;
 /**
- * @desc Escape a string for safe use inside an XPath single-quoted string literal.
+ * Escape a string for safe use inside an XPath single-quoted string literal.
  * Prevents XPath injection by splitting on single quotes and using concat().
+ *
+ * @param value raw string that may contain quotes
+ * @returns XPath-safe string expression
  */
 export declare function escapeXPathValue(value: string): string;
+/**
+ * Convert a string to camelCase, splitting on whitespace, `-`, `_`, `.`,
+ * and inferred case boundaries.
+ *
+ * @param input source string
+ * @returns camelCased output
+ */
 export declare function camelCase(input: string): string;
 declare const utility: {
     isString: typeof isString;

package/types/src/validator.d.ts

@@ -1,3 +1,24 @@
+/**
+ * @file validator.ts
+ * @author tngan
+ * @desc Time-window validators for SAML `NotBefore` / `NotOnOrAfter` conditions.
+ */
+/** Signed clock-drift tolerance in milliseconds for the two boundaries. */
 type DriftTolerance = [number, number];
+/**
+ * Check whether the current clock falls within the provided SAML time
+ * window, applying a symmetric drift tolerance to both ends.
+ *
+ * Behaviour:
+ *   - Both bounds missing: logs a warning and returns `true`.
+ *   - Only `utcNotBefore` given: returns true when now is at or after it.
+ *   - Only `utcNotOnOrAfter` given: returns true when now is strictly before it.
+ *   - Both given: returns true only when both individual checks pass.
+ *
+ * @param utcNotBefore ISO-8601 lower bound (inclusive) or undefined
+ * @param utcNotOnOrAfter ISO-8601 upper bound (exclusive) or undefined
+ * @param drift tolerance applied to each bound, defaults to `[0, 0]`
+ * @returns whether the current time is within the configured window
+ */
 declare function verifyTime(utcNotBefore: string | undefined, utcNotOnOrAfter: string | undefined, drift?: DriftTolerance): boolean;
 export { verifyTime };

package/.circleci/config.yml

@@ -1,98 +0,0 @@
-version: 2.1
-
-jobs:
-  test-node-20:
-    docker:
-      - image: cimg/node:20.19
-    environment:
-      INSTALL_JDK: 1
-    steps:
-      - checkout
-      - run:
-          name: Install Java JDK 21
-          command: |
-            sudo apt-get update
-            sudo apt-get install -y wget lsb-release
-            sudo mkdir -p /etc/apt/keyrings
-            wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo tee /etc/apt/keyrings/adoptium.asc
-            echo "deb [signed-by=/etc/apt/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
-            sudo apt-get update
-            sudo apt-get install -y temurin-21-jdk
-            java -version
-            javac -version
-      - run:
-          name: Install dependencies
-          command: yarn install --production=true
-      - run:
-          name: Install test dependencies
-          command: yarn add @authenio/samlify-xsd-schema-validator
-      - run:
-          name: Run tests
-          command: yarn test 
-
-  test-node-22:
-    docker:
-      - image: cimg/node:22.12
-    environment:
-      INSTALL_JDK: 1
-    steps:
-      - checkout
-      - run:
-          name: Install Java JDK 21
-          command: |
-            sudo apt-get update
-            sudo apt-get install -y wget lsb-release
-            sudo mkdir -p /etc/apt/keyrings
-            wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo tee /etc/apt/keyrings/adoptium.asc
-            echo "deb [signed-by=/etc/apt/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
-            sudo apt-get update
-            sudo apt-get install -y temurin-21-jdk
-            java -version
-            javac -version
-      - run:
-          name: Install dependencies
-          command: yarn install --production=true
-      - run:
-          name: Install test dependencies
-          command: yarn add @authenio/samlify-xsd-schema-validator
-      - run:
-          name: Run tests
-          command: yarn test 
-
-  test-node-24:
-    docker:
-      - image: cimg/node:24.0
-    environment:
-      INSTALL_JDK: 1
-    steps:
-      - checkout
-      - run:
-          name: Install Java JDK 21
-          command: |
-            sudo apt-get update
-            sudo apt-get install -y wget lsb-release
-            sudo mkdir -p /etc/apt/keyrings
-            wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo tee /etc/apt/keyrings/adoptium.asc
-            echo "deb [signed-by=/etc/apt/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
-            sudo apt-get update
-            sudo apt-get install -y temurin-21-jdk
-            java -version
-            javac -version
-      - run:
-          name: Install dependencies
-          command: yarn install --production=true
-      - run:
-          name: Install test dependencies
-          command: yarn add @authenio/samlify-xsd-schema-validator
-      - run:
-          name: Run tests
-          command: yarn test 
-
-workflows:
-  version: 2
-  test:
-    jobs:
-      - test-node-20
-      - test-node-22
-      - test-node-24
-

package/.editorconfig

@@ -1,19 +0,0 @@
-root = true
-
-[*]
-indent_style = tab
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.{json,js,ts,jsx,html,css}]
-indent_style = space
-indent_size = 2
-
-[.eslintrc]
-indent_style = space
-indent_size = 2
-
-[*.md]
-trim_trailing_whitespace = false

package/.github/FUNDING.yml

@@ -1 +0,0 @@
-github: [tngan]

package/.github/workflows/deploy-docs.yml

@@ -1,56 +0,0 @@
-name: Deploy VitePress Docs
-
-on:
-  push:
-    branches:
-      - master
-    paths:
-      - 'docs/**'
-      - '.github/workflows/deploy-docs.yml'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 18
-          cache: 'yarn'
-
-      - name: Install dependencies
-        run: yarn install --frozen-lockfile
-
-      - name: Build VitePress
-        run: yarn docs:build
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/.vitepress/dist
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-

package/.pre-commit.sh

@@ -1,15 +0,0 @@
-echo "Linting"
-npm run lint
-LINTRESULT=$?
-
-echo "Compiling"
-$(npm bin)/tsc
-BUILDRESULT=$?
-
-if [[ $LINTRESULT -ne 0 || $BUILDRESULT -ne 0 ]]; then
-  echo "Fix errors before commit"
-  exit 1
-else
-  echo "Ok to commit"
-  exit 0
-fi

package/.snyk

@@ -1,4 +0,0 @@
-# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities.
-version: v1.25.0
-ignore: {}
-patch: {}

package/Makefile

@@ -1,25 +0,0 @@
-PROJECT = "samlify"
-
-install: ;@echo "install ${PROJECT}"; \
-				 npm install;
-
-clean:	;
-				rm -rf node_modules
-
-rebuild: ;
-	       rm -rf build; \
-				 tsc; \
-
-pretest:	;
-					mkdir -p build/test; \
-					cp -a test/key test/misc build/test;
-
-install_jdk:
-	sudo add-apt-repository ppa:openjdk-r/ppa -y
-	sudo apt-get -qq update
-	sudo apt-get install -y openjdk-9-jdk
-
-doc: ;@echo "prepare and serve the docs"; \
-	   docsify serve ./docs
-
-.PHONY: rebuild pretest doc install_jdk

package/index.ts

@@ -1,28 +0,0 @@
-// version <= 1.25
-import IdentityProvider, { IdentityProvider as IdentityProviderInstance } from './src/entity-idp';
-import ServiceProvider, { ServiceProvider as ServiceProviderInstance } from './src/entity-sp';
-
-export { default as IdPMetadata } from './src/metadata-idp';
-export { default as SPMetadata } from './src/metadata-sp';
-export { default as Utility } from './src/utility';
-export { default as SamlLib } from './src/libsaml';
-// roadmap
-// new name convention in version >= 3.0
-import * as Constants from './src/urn';
-import * as Extractor from './src/extractor';
-
-// exposed methods for customizing samlify
-import { setSchemaValidator, setDOMParserOptions } from './src/api';
-
-export {
-  Constants,
-  Extractor,
-  // temp: resolve the conflict after version >= 3.0
-  IdentityProvider,
-  IdentityProviderInstance,
-  ServiceProvider,
-  ServiceProviderInstance,
-  // set context
-  setSchemaValidator,
-  setDOMParserOptions
-};

package/src/api.ts

@@ -1,48 +0,0 @@
-import { DOMParser as dom, Options as DOMParserOptions } from '@xmldom/xmldom';
-
-// global module configuration
-interface Context extends ValidatorContext, DOMParserContext {}
-
-interface ValidatorContext {
-  validate?: (xml: string) => Promise<any>;
-}
-
-interface DOMParserContext {
-  dom: dom;
-}
-
-const XXE_SAFE_OPTIONS: DOMParserOptions = {
-  /**
-   * Treat XML parsing errors as fatal to prevent XXE attacks.
-   * Entity references (e.g. &xxe;) and malformed XML in SAML messages
-   * are not expected and may indicate an attack attempt.
-   */
-  errorHandler: {
-    error: (msg: string) => { throw new Error(`XML parsing error: ${msg}`); },
-    fatalError: (msg: string) => { throw new Error(`XML fatal error: ${msg}`); },
-  },
-};
-
-const context: Context = {
-  validate: undefined,
-  dom: new dom(XXE_SAFE_OPTIONS)
-};
-
-export function getContext() {
-  return context;
-}
-
-export function setSchemaValidator(params: ValidatorContext) {
-
-  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;
-
-}
-
-export function setDOMParserOptions(options: DOMParserOptions = {}) {
-  context.dom = new dom(options);
-}