passport-entra 0.0.2 → 0.0.3

package/dist/passport-entra.d.ts

@@ -1,39 +1,57 @@
 import { Strategy } from 'passport';
 import { createRemoteJWKSet } from 'jose';
 import type { Request } from 'express';
-export interface OauthBearerOptions {
+/**
+ * Bearerstrategy options
+ */
+export interface BearerOptions {
+    /** If set, check aud claim against this audience */
     audience?: string | string[];
+    /** ClientID of app in Entra, check aud claim against clientID if audience options is not set */
     clientID: string;
+    /** clockSkew allowed when checking nbf and exp claims */
     clockSkew?: string | number;
+    /** well known oid-configuration endpoint, ie <issuer>/.well-known/openid-configuration */
     identityMetadata: string;
+    /** iss claim check, ie https://login.microsoftonline.com/<tenantID>/v2.0 - tenantID of app in Entra */
     issuer: string | string[];
+    /** scp claim check */
     scope?: string[];
 }
-type VerifyCallback = (token: object, done: AuthenticateCallback) => void;
-export type AuthenticateCallback = (err: unknown, user?: Express.User | false | null, info?: object, status?: number | number[]) => void;
+/**
+ * Called by this BearerStrategy when the token has been validated.
+ * Use the token (the bearer JWT payload) to find the user. Then call done.
+ */
+export type VerifyCallback = (token: object, done: VerifyCompleteCallback) => void;
+/**
+ * Call this in the VerifyCallback with either the found user or an error.
+ * The user ends up in req.user, the info in req.authInfo.
+ * An error results in an authentication failure. Status is ignored.
+ */
+export type VerifyCompleteCallback = (err: unknown, user?: Express.User | false | null, info?: object, status?: number | number[]) => void;
 /**
  * Bearerstrategy for password.js, used with Microsoft Entra as identity provider
  */
 export default class BearerStrategy extends Strategy {
-    /** aud claim check  */
     audience: string[];
-    /** clientID to check */
     clientID: string;
-    /** clockSkew allowed when checking nbf and exp */
     clockSkew: string | number;
-    /** well known oid-configuration endpoint */
     identityMetadata: string;
-    /** iss claim check */
     issuer: string | string[];
-    /** strategy name */
     name: string;
-    /** scp claim check */
     scope: string[];
-    /** call this function to get the user belonging to the token */
     verifyFn: VerifyCallback;
-    /** cached JWK set from well known oid-configuration endpoint */
     jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
-    constructor(options: OauthBearerOptions, verifyFn: VerifyCallback);
+    /**
+     * Creates a new BearerStrategy instance.
+     * @param options The validation options.
+     * @param verifyFn Called when a token is validated, needs to provide the User object.
+     */
+    constructor(options: BearerOptions, verifyFn: VerifyCallback);
+    /**
+     * Validates the Bearer token in a request.
+     * When validated, calls VerifyFn to retrieve the User belonging to the token.
+     * @param req The Express request
+     */
     authenticate(req: Request): Promise<void>;
 }
-export {};

package/dist/passport-entra.js

@@ -15,10 +15,14 @@ const jose_1 = require("jose");
  * Bearerstrategy for password.js, used with Microsoft Entra as identity provider
  */
 class BearerStrategy extends passport_1.Strategy {
+    /**
+     * Creates a new BearerStrategy instance.
+     * @param options The validation options.
+     * @param verifyFn Called when a token is validated, needs to provide the User object.
+     */
     constructor(options, verifyFn) {
         var _a, _b, _c;
         super();
-        /** strategy name */
         this.name = 'oauth-bearer';
         this.verifyFn = verifyFn;
         let audience = (_a = options.audience) !== null && _a !== void 0 ? _a : options.clientID;
@@ -32,6 +36,11 @@ class BearerStrategy extends passport_1.Strategy {
         this.issuer = options.issuer;
         this.scope = (_c = options.scope) !== null && _c !== void 0 ? _c : [];
     }
+    /**
+     * Validates the Bearer token in a request.
+     * When validated, calls VerifyFn to retrieve the User belonging to the token.
+     * @param req The Express request
+     */
     authenticate(req) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "passport-entra",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Microft Entra authentication strategy for passport",
   "main": "dist/passport-entra.js",
   "types": "dist/passport-entra.d.ts",
   "scripts": {
+    "build": "tsc",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "Jan Bakker",

package/passport-entra.ts

@@ -3,18 +3,36 @@ import { createRemoteJWKSet, jwtVerify } from 'jose';
 
 import type { Request } from 'express';
 
-export interface OauthBearerOptions {
+/**
+ * Bearerstrategy options
+ */
+export interface BearerOptions {
+  /** If set, check aud claim against this audience */
   audience?: string | string[];
+  /** ClientID of app in Entra, check aud claim against clientID if audience options is not set */
   clientID: string;
+  /** clockSkew allowed when checking nbf and exp claims */
   clockSkew?: string | number;
+  /** well known oid-configuration endpoint, ie <issuer>/.well-known/openid-configuration */
   identityMetadata: string;
+  /** iss claim check, ie https://login.microsoftonline.com/<tenantID>/v2.0 - tenantID of app in Entra */
   issuer: string | string[];
+  /** scp claim check */
   scope?: string[];
 }
 
-type VerifyCallback = (token: object, done: AuthenticateCallback) => void;
+/** 
+ * Called by this BearerStrategy when the token has been validated. 
+ * Use the token (the bearer JWT payload) to find the user. Then call done.
+ */
+export type VerifyCallback = (token: object, done: VerifyCompleteCallback) => void;
 
-export type AuthenticateCallback = (
+/** 
+ * Call this in the VerifyCallback with either the found user or an error.
+ * The user ends up in req.user, the info in req.authInfo.
+ * An error results in an authentication failure. Status is ignored.
+ */
+export type VerifyCompleteCallback = (
   err: unknown,
   user?: Express.User | false | null,
   info?: object,
@@ -25,34 +43,22 @@ export type AuthenticateCallback = (
  * Bearerstrategy for password.js, used with Microsoft Entra as identity provider
  */
 export default class BearerStrategy extends Strategy {
-  /** aud claim check  */
   audience;
-
-  /** clientID to check */
   clientID;
-
-  /** clockSkew allowed when checking nbf and exp */
   clockSkew;
-
-  /** well known oid-configuration endpoint */
-  identityMetadata: string;
-
-  /** iss claim check */
+  identityMetadata;
   issuer;
-
-  /** strategy name */
   name = 'oauth-bearer';
-
-  /** scp claim check */
   scope;
-
-  /** call this function to get the user belonging to the token */
   verifyFn;
-
-  /** cached JWK set from well known oid-configuration endpoint */
   jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
 
-  constructor(options: OauthBearerOptions, verifyFn: VerifyCallback) {
+  /**
+   * Creates a new BearerStrategy instance.
+   * @param options The validation options.
+   * @param verifyFn Called when a token is validated, needs to provide the User object.
+   */
+  constructor(options: BearerOptions, verifyFn: VerifyCallback) {
     super();
 
     this.verifyFn = verifyFn;
@@ -70,6 +76,11 @@ export default class BearerStrategy extends Strategy {
     this.scope = options.scope ?? [];
   }
 
+  /**
+   * Validates the Bearer token in a request.
+   * When validated, calls VerifyFn to retrieve the User belonging to the token.
+   * @param req The Express request
+   */
   async authenticate(req: Request) {
     try {
       if (!this.jwks) {
@@ -81,12 +92,14 @@ export default class BearerStrategy extends Strategy {
         const { jwks_uri } = await res.json() as { jwks_uri: string };
         this.jwks = createRemoteJWKSet(new URL(jwks_uri));
       }
+
       const header = req.get('authorization');
       const headerParts = header?.split(' ');
       const jwt = headerParts?.length === 2 && headerParts[0].toLowerCase() === 'bearer' && headerParts[1];
       if (!jwt) {
         throw new Error('Unable to extract Bearer token from Authorization header');
       }
+
       const { payload } = await jwtVerify(jwt, this.jwks, {
         audience: this.audience, // aud
         clockTolerance: this.clockSkew, // exp, nbf