NONE: Refactor authentication mechanism (#50)

Author: akostevich-atlassian

src/middlewares/auth-header-jwt-middleware.ts

@@ -1,5 +1,5 @@
 import { NextFunction, Request, Response } from "express";
-import { verifyAsymmetricJWTToken, verifySymmetricJWTToken } from "../utils/jwt";
+import { JwtVerificationError, verifyAsymmetricJWTToken, verifySymmetricJWTToken } from "../utils/jwt";
 import { fromExpressRequest } from "atlassian-jwt";
 
 
@@ -17,7 +17,8 @@ const validateAuthToken = (type: "symmetric" | "asymmetric") => async (req: Requ
 		}
 		next();
 	} catch (e) {
-		res.status(e.status).send(e.message);
+		const message = e instanceof JwtVerificationError ? e.message : "Unauthorized";
+		res.status(401).send(message);
 	}
 };
 /**

src/middlewares/querystring-jwt-middleware.ts

@@ -1,5 +1,5 @@
 import { NextFunction, Request, Response } from "express";
-import { verifySymmetricJWTToken } from "../utils/jwt";
+import { JwtVerificationError, verifySymmetricJWTToken } from "../utils/jwt";
 import { fromExpressRequest } from "atlassian-jwt";
 
 /**
@@ -11,6 +11,7 @@ export const querystringJwtMiddleware = async (req: Request, res: Response, next
 		res.locals.jiraTenant = await verifySymmetricJWTToken(fromExpressRequest(req), req.query.jwt as string);
 		next();
 	} catch (e) {
-		res.status(e.status).send(e.message);
+		const message = e instanceof JwtVerificationError ? e.message : "Unauthorized";
+		res.status(401).send(message);
 	}
 };

src/utils/jwt.ts

@@ -4,123 +4,150 @@ import { Request } from "atlassian-jwt/dist/lib/jwt";
 import { envVars } from "../env";
 
 /**
- * This decodes the JWT token from Jira, verifies it against the jira tenant's shared secret
- * And returns the verified Jira tenant if it passes
- * https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#decoding-and-verifying-a-jwt-token
+ * A Jira JWT token claims.
+ *
+ * @ses https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#manually-creating-a-jwt
+ */
+export type JiraJwtClaims = {
+	readonly iss: string;
+	readonly iat: number;
+	readonly exp: number;
+	readonly qsh: string;
+	readonly sub?: string;
+	readonly aud?: string[];
+}
+
+/**
+ * Verifies a Jira symmetric JWT token.
+ *
+ * This decodes the JWT token, verifies it against the jira tenant's shared secret
+ * and returns the verified Jira tenant if it passes.
+ *
+ * @see https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#types-of-jwt-token
+ * @see https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#decoding-and-verifying-a-jwt-token
+ *
+ * @throws {JwtVerificationError} The given token is invalid or cannot be verified.
  */
 export const verifySymmetricJWTToken = async (request: Request, token?: string): Promise<JiraTenant> => {
 	// if JWT is missing, return a 401
-	if (!token) {
-		return Promise.reject({
-			status: 401,
-			message: "Missing JWT token"
-		});
-	}
+	if (!token) throw new JwtVerificationError("Missing JWT token");
 
 	// Decode jwt token without verification
-	let data = decodeSymmetric(token, "", getAlgorithm(token), true);
-	// Get the jira tenant associated with this url
-	const jiraTenant = await database.findJiraTenant({ clientKey: data.iss });
-
-	// If tenant doesn't exist anymore, return a 404
-	if (!jiraTenant) {
-		return Promise.reject({
-			status: 404,
-			message: "Jira Tenant doesn't exist"
-		});
+	let unverifiedClaims: Record<string, unknown>;
+	try {
+		unverifiedClaims = decodeSymmetric(token, "", getAlgorithm(token), true) as Record<string, unknown>;
+	} catch (e) {
+		throw new JwtVerificationError("The JWT token is invalid.");
 	}
 
-	try {
-		// Try to verify the jwt token
-		data = decodeSymmetric(token, jiraTenant.sharedSecret, getAlgorithm(token));
-		await validateQsh(data.qsh, request);
+	validateIss(unverifiedClaims.iss);
 
-		// If all verifications pass, save the jiraTenant to local to be used later
-		return jiraTenant;
+	// Get the jira tenant associated with this url
+	const jiraTenant = await database.findJiraTenant({ clientKey: unverifiedClaims.iss as string });
+
+	if (!jiraTenant) throw new JwtVerificationError("The JWT token is invalid.");
+
+	// Decode a JWT token with verification.
+	let verifiedClaims: JiraJwtClaims;
+	try {
+		verifiedClaims = decodeSymmetric(token, jiraTenant.sharedSecret, getAlgorithm(token));
 	} catch (e) {
-		// If verification doesn't work, show a 401 error
-		return Promise.reject({
-			status: 401,
-			message: `JWT verification failed: ${e}`
-		});
+		throw new JwtVerificationError("The JWT token is not authentic.");
 	}
+
+	// Validate the standard claims.
+	validateQsh(verifiedClaims.qsh, request);
+	validateExp(verifiedClaims.exp);
+
+	// If all verifications pass, save the jiraTenant to local to be used later
+	return jiraTenant;
 };
 
 
 /**
- * This decodes the JWT token from Jira, verifies it based on the connect public key
- * This is used for installed and uninstalled lifecycle events
- * https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/#validating-installation-lifecycle-requests
+ * Verifies a Jira asymmetric JWT token, used for lifecycle event requests.
+ *
+ * This decodes the JWT token, verifies it based on the connect public key.
+ *
+ * @see https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#types-of-jwt-token
+ * @see https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#decoding-and-verifying-a-jwt-token
+ * @see https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/#validating-installation-lifecycle-requests
+ *
+ * @throws {JwtVerificationError} The given token is invalid or cannot be verified.
  */
 export const verifyAsymmetricJWTToken = async (request: Request, token?: string): Promise<void> => {
-	// if JWT is missing, return a 401
-	if (!token) {
-		return Promise.reject({
-			status: 401,
-			message: "Missing JWT token"
-		});
+	if (!token) throw new JwtVerificationError("Missing JWT token");
+
+	let unverifiedClaims: Record<string, unknown>;
+
+	// Decode a JWT token without verification.
+	try {
+		unverifiedClaims = decodeAsymmetric(token, "", getAlgorithm(token), true) as Record<string, unknown>;
+	} catch (e) {
+		throw new JwtVerificationError("The JWT token is invalid.");
 	}
 
+	validateIss(unverifiedClaims.iss);
+
 	const publicKey = await queryAtlassianConnectPublicKey(getKeyId(token));
-	const unverifiedClaims = decodeAsymmetric(token, publicKey, getAlgorithm(token), true);
 
-	if (!unverifiedClaims.iss) {
-		return Promise.reject({
-			status: 401,
-			message: "JWT claim did not contain the issuer (iss) claim"
-		});
+	// Decode a JWT token with verification.
+	let verifiedClaims: JiraJwtClaims;
+	try {
+		verifiedClaims = decodeAsymmetric(token, publicKey, getAlgorithm(token));
+	} catch (e) {
+		throw new JwtVerificationError("The JWT token is not authentic.");
 	}
 
+	// Validate the standard claims.
+	validateExp(verifiedClaims.exp);
+	validateQsh(verifiedClaims.qsh, request);
+
 	// Make sure the AUD claim has the correct URL
-	if (!unverifiedClaims?.aud?.[0]?.includes(envVars.APP_URL)) {
-		return Promise.reject({
-			status: 401,
-			message: "JWT claim did not contain the correct audience (aud) claim"
-		});
+	if (!verifiedClaims?.aud?.[0]?.includes(envVars.APP_URL)) {
+		throw new JwtVerificationError("The JWT token does not contain the correct audience (aud) claim");
 	}
+};
 
-	const verifiedClaims = decodeAsymmetric(token, publicKey, getAlgorithm(token));
-
-	// If claim doesn't have QSH, reject
-	if (!verifiedClaims.qsh) {
-		return Promise.reject({
-			status: 401,
-			message: "JWT validation Failed, no qsh"
-		});
-	}
+export class JwtVerificationError extends Error {
+}
 
-	// Check that claim is still within expiration, give 3 second leeway in case of time drift
-	if (verifiedClaims.exp && (Date.now() / 1000 - 3) >= verifiedClaims.exp) {
-		return Promise.reject({
-			status: 401,
-			message: "JWT validation failed, token is expired"
-		});
+const validateIss = (iss: unknown): void => {
+	if (typeof iss !== "string" || !iss) {
+		throw new JwtVerificationError("The JWT token does not contain or contains the unexpected issuer (iss) claim");
 	}
-
-	await validateQsh(verifiedClaims.qsh, request);
 };
 
-// Check to see if QSH from token is the same as the request
-const validateQsh = async (qsh: string, request: Request): Promise<void> => {
+/**
+ * Validates whether the fixed or URL-bound `qsh` claim.
+ */
+const validateQsh = (qsh: string, request: Request): void => {
 	if (qsh !== "context-qsh" && qsh !== createQueryStringHash(request, false)) {
-		return Promise.reject({
-			status: 401,
-			message: "JWT Verification Failed, wrong qsh"
-		});
+		throw new JwtVerificationError("JWT Verification Failed, wrong qsh");
 	}
 };
 
+/**
+ * Validates the `exp` claim. Gives a 3-second leeway in case of time drift.
+ */
+const validateExp = (exp: number): void => {
+	const leewayInSeconds = 3;
+	const nowInSeconds = Date.now() / 1000 - 3;
+
+	if (nowInSeconds >= exp + leewayInSeconds) {
+		throw new JwtVerificationError("The JWT validation failed, token is expired");
+	}
+};
 
 /**
- * Queries the public key for the specified keyId
+ * Queries the public key for the specified keyId.
+ *
+ * @see https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/#verifying-a-asymmetric-jwt-token-for-install-callbacks
  */
 const queryAtlassianConnectPublicKey = async (keyId: string): Promise<string> => {
 	const response = await fetch(`https://connect-install-keys.atlassian.com/${keyId}`);
 	if (response.status !== 200) {
-		return Promise.reject({
-			status: 401,
-			message: `Unable to get public key for keyId ${keyId}`
-		});
+		throw new JwtVerificationError(`Unable to get public key for keyId ${keyId}`);
 	}
 	return response.text();
 };