@bostonuniversity/shibboleth-sp 1.0.2

package/dist/types/Config.d.ts

@@ -0,0 +1,28 @@
+import { KeyValuePair } from "./Http";
+import { SamlParms } from "./Saml";
+/**
+ * A type that accounts for ALL configurable values.
+ *
+ * @property domain - The domain for app requests (browser access domain)
+ * @property appLoginHeader - Header name for login redirects
+ * @property appLogoutHeader - Header name for logout redirects
+ * @property appAuthorization - True for standard mode, false for basic mode
+ * @property samlParms - SAML configuration parameters
+ * @property jwtPrivateKeyPEM - Optional private key for JWT generation
+ * @property jwtPublicKeyPEM - Optional public key for JWT generation
+ * @property customHeaders - Optional custom headers to append to requests
+ */
+export interface IConfig {
+    domain: string;
+    appLoginHeader: string;
+    appLogoutHeader: string;
+    appAuthorization: boolean;
+    samlParms: SamlParms;
+    jwtPrivateKeyPEM?: string;
+    jwtPublicKeyPEM?: string;
+    customHeaders?: KeyValuePair[];
+}
+/**
+ * @returns An instance of IConfig whose values are ALL obtained from the environment.
+ */
+export declare const getConfigFromEnvironment: () => IConfig;

package/dist/types/HandlerSp.d.ts

@@ -0,0 +1,20 @@
+import { IConfig } from './Config';
+import { IRequest, IResponse } from './Http';
+export declare enum AUTH_PATHS {
+    LOGIN = "/login",
+    LOGOUT = "/logout",
+    ASSERT = "/assert",
+    METADATA = "/metadata",
+    FAVICON = "/favicon.ico"
+}
+export declare const APP_AUTHORIZATION_HEADER_NAME = "app_authorization";
+/**
+ * This is the sp "switchboard operator" for origin request traffic. It will perform all saml SP operations for ensuring
+ * that the user bears JWT proof of saml authentication, else it drives the authentication flow with the IDP.
+ * @param event
+ * @returns Promise<IRequest|IResponse>
+ *    IRequest: Returning the original request (possibly with headers added) - indicates the request is to be
+ *      forwarded on to the target app.
+ *    IResponse: Returning an object that indicates an error or redirection - not passing through to the target app.
+ */
+export declare const handler: (originRequest: IRequest, config: IConfig) => Promise<IRequest | IResponse>;

package/dist/types/Http.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Interface for an incoming request.
+ *
+ * @remarks This was modelled after a Lambda@Edge request event, but that is arbitrary - this app is agnostic
+ * as to which environment it will be run in (such as cloudfront edge lambda), docker compose, etc.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-event-structure.html#lambda-event-structure-request
+ */
+export interface IRequest {
+    uri: string;
+    method: string;
+    querystring: string;
+    clientIp?: string;
+    status?: string;
+    body: RequestBody;
+    headers: RequestHeaders;
+    headerActivity: {
+        added: RequestHeaders;
+        removed: RequestHeaders;
+        modified: RequestHeaders;
+    };
+}
+/**
+ * Interface for an outgoing response.
+ *
+ * @remarks This was modelled after a Lambda@Edge response event, but that is arbitrary - this app is agnostic
+ * as to which environment it will be run in (such as cloudfront edge lambda), docker compose, etc.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-event-structure.html#lambda-event-structure-response
+ */
+export interface IResponse {
+    status: string;
+    statusDescription: string;
+    body?: string;
+    headers?: RequestHeaders;
+}
+export interface RequestBody {
+    data: string;
+}
+export type RequestHeaders = {
+    [headerName: string]: KeyValuePair[];
+};
+export interface KeyValuePair {
+    key: string;
+    value: string;
+}
+export type IHeaders = {
+    empty: boolean;
+    get: (key: string) => string | null;
+    join: (joiner: string, except?: string[]) => string;
+    isTruthy: (key: string) => boolean;
+};
+/**
+ * Header accessor wrapper.
+ * @param request
+ * @returns
+ */
+export declare const Headers: (request: IRequest | IResponse) => IHeaders;
+/**
+ * Utility function for adding headers to a request or response
+ * @param obj
+ * @param keyname
+ * @param value
+ * @returns
+ */
+export declare const addHeader: (obj: IRequest | IResponse, keyname: string, value: string) => void;
+/**
+ * Extracts the host header value from an HTTP request.
+ * @param request The HTTP request object
+ * @returns The host header value, or null if not found or invalid request
+ */
+export declare const getHost: (request: IRequest) => string | null;

package/dist/types/Jwt.d.ts

@@ -0,0 +1,59 @@
+import { IRequest } from './Http';
+/**
+ * Use the jsonwebtoken library to create and verify jwts.
+ *
+ * @see https://www.npmjs.com/package/jsonwebtoken
+ */
+export declare class JwtTools {
+    private publicKey;
+    private privateKey;
+    private expiresIn;
+    private clockTime;
+    static TOKEN_NAME: string;
+    static COOKIE_NAME: string;
+    resetPrivateKey(privateKey: string): void;
+    resetPublicKey(publicKey: string): void;
+    setExpiration(expiresIn: string): void;
+    setClockTime(clockTime: number): void;
+    /**
+     * The cookie header is a concatenation of name=value pairs delimited by a ";" character.
+     * Get the value of one of these pairs, specified by name.
+     * @param request The HTTP request containing cookies
+     * @param cookieName The name of the cookie to retrieve
+     * @returns The cookie value if found, undefined otherwise
+     */
+    parseCookieValue(request: IRequest, cookieName: string): string | null;
+    /**
+     * Any environment variable starting with "IMPERSONATE_" is treated as an attribute for building a jwt token.
+     * This provides an option for mocking a jwt while running locally for testing so as to "pretend" a valid jwt
+     * was provided with the http request.
+     * @example
+     * IMPERSONATE_buPrincipal=wrh
+     * IMPERSONATE_eduPersonPrincipalName=wrh@bu.edu
+     * IMPERSONATE_eduPersonAffiliation=employee|member|staff
+     * @returns JWT token object with impersonation attributes, or null if no IMPERSONATE_ environment variables are found
+     */
+    getImpersonationToken(): any;
+    /**
+     * Extract the decoded JWT from the larger cookie value.
+     * @param request
+     * @param verify
+     * @returns
+     */
+    getToken(request: IRequest, verify?: boolean): any;
+    /**
+     * Determine if a request carries a valid jwt in its cookie header.
+     * @param request
+     * @returns
+     */
+    hasValidToken(request: IRequest): any;
+    /**
+     * Place a jwt in a "set-cookie" response header.
+     * @param response
+     * @param payload
+     */
+    setCookieInResponse(response: any, payload: any): void;
+    setCookieInvalidationInResponse(response: any): void;
+    getCookieName(): string;
+    getTokenName(): string;
+}

package/dist/types/Keys.d.ts

@@ -0,0 +1,13 @@
+export declare class Keys {
+    private _keys;
+    private _certificate;
+    constructor();
+    private extractValueFromPEM;
+    get privateKey(): string;
+    get publicKey(): string;
+    get certificate(): string;
+    get privateKeyPEM(): string;
+    get publicKeyPEM(): string;
+    get certificatePEM(): string;
+    toString: () => string;
+}

package/dist/types/Saml.d.ts

@@ -0,0 +1,73 @@
+import { SAMLAssertResponse } from 'saml2-js';
+import { IRequest } from './Http';
+/**
+ * Parameters required to configure the SAML tools.
+ *
+ * @property entityId - The entity ID of your app known to shibboleth (e.g., 'https://*.myapp.bu.edu/shibboleth')
+ * @property entryPoint - The IDP address for SSO (e.g., 'https://shib-test.bu.edu/idp/profile/SAML2/Redirect/SSO')
+ * @property logoutUrl - The IDP logout URL (e.g., 'https://shib.bu.edu/idp/logout.jsp')
+ * @property idpCert - The public certificate from the IDP's X509Certificate element
+ * @property cert - Optional SAML certificate for your service provider metadata
+ * @property key - Optional private key for your service provider metadata
+ */
+export interface SamlParms {
+    entityId: string;
+    entryPoint: string;
+    logoutUrl: string;
+    idpCert: string;
+    cert?: string;
+    key?: string;
+}
+export type SamlResponseObject = {
+    samlResponseParm: string | undefined;
+    xmlData: string | undefined;
+    relayState: string | undefined;
+};
+export type SendAssertResult = {
+    samlAssertResponse: SAMLAssertResponse | null;
+    relayState: string | null;
+};
+export declare class SamlTools {
+    private sp_options;
+    private idp_options;
+    constructor(parms: SamlParms);
+    setSpCertificate(cert: string): void;
+    setPrivateKey(key: string): void;
+    setAssertUrl(assertEndpoint: string): void;
+    getMetaData(): string;
+    /**
+     * The request indicates the user is not authenticated, and so needs to be redirected to a url for signin with the IDP.
+     *
+     * @see https://www.npmjs.com/package/saml2-js#create_login_request_urlidp-options-cb
+     * @param relay_state
+     * @returns
+     */
+    createLoginRequestUrl(relay_state: string): Promise<string>;
+    /**
+     * @returns The url to the IDP to logout.
+     */
+    createLogoutRequestUrl(): Promise<string>;
+    /**
+     * The saml response could come from the IDP as either a querystring parameter (GET), or as a
+     * form data parameter (POST).
+     * @param request
+     * @returns
+     */
+    getSamlResponseParameter(request: IRequest): SamlResponseObject | null;
+    /**
+     * The request has a SAMLResponse parameter and so indicates authentication has completed and a followup
+     * assert against the SAMLResponse parameter is next.
+     *
+     * @see https://www.npmjs.com/package/saml2-js#create_login_request_urlidp-options-cb
+     * @param requestUrl
+     * @returns
+     */
+    sendAssert(request: IRequest): Promise<SendAssertResult>;
+}
+/**
+ * The saml assert response will have attributes that are missing the friendly names.
+ * These friendly names can still be found in the xml that was passed to the post_assert
+ * to get the response, and can be applied to that response to overwrite the "unfriendly" names.
+ * @param saml_assert_response
+ */
+export declare function getFriendlySamlResponse(xmlData: string | undefined, response: SAMLAssertResponse): SAMLAssertResponse | null;

package/dist/types/Utils.d.ts

@@ -0,0 +1,40 @@
+export declare const ParameterTester: {
+    isBlank: (s: string | null | undefined) => boolean;
+    isNotBlank: (s: string | null | undefined) => boolean;
+    anyBlank: (...a: any) => boolean;
+    anyNotBlank: (...a: any) => boolean;
+    allBlank: (...a: any) => boolean;
+    noneBlank: (...a: any) => boolean;
+    someBlankSomeNot: (...a: any) => boolean;
+};
+/**
+ * Prints debug information to console when DEBUG environment variable is set to 'true'.
+ * @param value The debug message to print
+ */
+export declare const debugPrint: (value: string) => void;
+/**
+ * Find the first field with a value in an object for the list of field names provided.
+ * The field is assumed to be an array, and the value is the first element of it.
+ * @param parentObj The object to search within
+ * @param names The field names to search for
+ * @returns The first non-empty field value found, or null if none found
+ */
+export declare const findFirstFieldValue: (parentObj: any, ...names: any) => string | null;
+/**
+ * Logs debug messages to console when DEBUG environment variable is set to 'true'.
+ * @param msg The message to log
+ */
+export declare const debugLog: (msg: string) => void;
+/**
+ * Type guard function to check if a value is of a specific type based on field presence.
+ * @param value The value to check
+ * @param fieldName The field name that should exist on the type
+ * @returns True if the field exists on the value, indicating it's of type T
+ */
+export declare const instanceOf: <T>(value: any, fieldName: string) => value is T;
+type ReplacerFunction = (key: string, value: any) => any;
+type ReplacerArray = (string | number)[];
+type Replacer = ReplacerFunction | ReplacerArray | null;
+type Space = string | number | null;
+export declare const safeStringify: (obj: any, replacer?: Replacer, space?: Space) => string | undefined;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export { SamlParms } from './Saml';
+export * from './HandlerSp';
+export * from './Http';
+export * from './Config';
+export * from './Jwt';
+export * from './Keys';
+export * from './Saml';
+export * from './Utils';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bostonuniversity/shibboleth-sp",
+  "version": "1.0.2",
+  "description": "A nodejs typescript library that provides all service provider functionality for authenticating with a shibboleth IDP",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bu-ist/shibboleth-sp.git"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && node src/build.js",
+    "build:tsc": "rm -rf dist/ && npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc",
+    "build:cjs": "tsc --module CommonJS --outdir dist/cjs",
+    "pack": "npm run build && npm pack --pack-destination .",
+    "publish": "npm run pack && npm publish ./@bostonuniversity-shibboleth-sp-1.0.2.tgz --access public",
+    "watch": "tsc -w",
+    "test": "jest --silent"
+  },
+  "module": "dist/esm/index.js",
+  "main": "dist/cjs/index.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@types/saml2-js": "^3.0.4",
+    "@xmldom/xmldom": "^0.8.10",
+    "js-yaml": "^3.14.2",
+    "jsonwebtoken": "^9.0.2",
+    "ms": "^3.0.0-canary.1",
+    "saml2-js": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/node": "20.6.3",
+    "@types/node-forge": "^1.3.8",
+    "esbuild": "^0.25.11",
+    "jest": "^29.7.0",
+    "node-forge": "^1.3.1",
+    "ts-jest": "^29.2.0",
+    "ts-node": "^10.9.1",
+    "tsx": "^4.21.0",
+    "typescript": "~5.2.2"
+  },
+  "overrides": {
+    "js-yaml": "^3.14.2"
+  }
+}