Add some comments to explain logic

Author: mvantellingen

src/gateway.ts

@@ -17,6 +17,13 @@ type GatewayOptions = {
 	source: TokenSource;
 };
 
+/**
+ * This plugin is used to authenticate requests coming into the gateway. It
+ * reads the tokens from the request (using the token source provided),
+ * validates them. When sending back the response it will also set the tokens
+ * via the tokenSource on the response if the downstream services have
+ * created/modified them.
+ */
 export class GatewayAuthPlugin<TContext extends PublicFederatedTokenContext>
 	implements ApolloServerPlugin, GraphQLRequestListener<TContext>
 {
@@ -55,7 +62,8 @@ export class GatewayAuthPlugin<TContext extends PublicFederatedTokenContext>
 		const token = contextValue.federatedToken;
 
 		// Only load the access token if there is no refresh token. If a refresh
-		// token is present then we assume a refresh is happening
+		// token is present then we assume a refresh is happening and the
+		// accessToken is expired/invalid anyway
 		if (accessToken && !refreshToken) {
 			try {
 				await token.loadAccessJWT(this.signer, accessToken, fingerprint);
@@ -96,6 +104,10 @@ export class GatewayAuthPlugin<TContext extends PublicFederatedTokenContext>
 		const token = contextValue?.federatedToken;
 		const { req: request, res: response } = contextValue;
 
+		// Downstream services modified the tokens, so create a new JWT and set
+		// it on the response
+		// TODO: We should optimize this, if only the values are modified then
+		// we shouldn't have to create a new nested JWE
 		if (token?.isAccessTokenModified() || token?.isValueModified()) {
 			const { accessToken, fingerprint } = await token.createAccessJWT(
 				this.signer

src/jwt.ts

@@ -26,28 +26,32 @@ export class TokenExpiredError extends Error {}
 export class TokenInvalidError extends Error {}
 
 export class PublicFederatedToken extends FederatedToken {
-	async createAccessJWT(signer: TokenSigner) {
-		// Find the expire time of the first token that expires
-		const values = Object.values(this.tokens);
-		const sorted = values.sort((a, b) => a.exp - b.exp);
-		const exp = sorted[0].exp;
 
+	// Create the access JWT. This JWT is send to the client. It is send as
+	// signed token (not encrypted). The jwe attribute is encrypted however.
+	// This is all done when the GraphQL gateway sends the response back to the
+	// client.
+	async createAccessJWT(signer: TokenSigner) {
+		const exp = this.getExpireTime()
 		const fingerprint = generateFingerprint();
+		const subject = await signer.getSubject(this);
+
 		const payload: JWTPayload = {
-			exp: exp,
-			jwe: await signer.encryptObject(this.tokens),
 			...this.values,
+			exp,
+			sub: subject,
+			jwe: await signer.encryptObject(this.tokens),
 			_fingerprint: hashFingerprint(fingerprint),
 		};
 
-		const token = await signer.signJWT(payload, exp);
-
+		const token = await signer.signJWT(payload);
 		return {
 			accessToken: token,
 			fingerprint: fingerprint,
 		};
 	}
 
+
 	async loadAccessJWT(
 		signer: TokenSigner,
 		value: string,
@@ -78,7 +82,7 @@ export class PublicFederatedToken extends FederatedToken {
 		}
 
 		this.tokens = await signer.decryptObject(payload.jwe);
-		const knownKeys = ["jwe", "iat", "exp", "aud", "iss", "_fingerprint"];
+		const knownKeys = ["jwe", "iat", "exp", "aud", "sub", "jti", "iss", "_fingerprint"];
 		for (const k in payload) {
 			if (!knownKeys.includes(k)) {
 				this.values[k] = payload[k];

src/plugin.ts

@@ -5,6 +5,11 @@ import {
 } from "@apollo/server";
 import { FederatedToken, FederatedTokenContext } from "./token.js";
 
+
+// FederatedAuthPlugin is an Apollo plugin which should be used by all
+// downstream services. It reads the information from the request headers as
+// set by the GatewayAuthPlugin and sets the information on the response
+// headers for the GatewayAuthPlugin to be consumed.
 export class FederatedAuthPlugin<TContext extends FederatedTokenContext>
 	implements ApolloServerPlugin, GraphQLRequestListener<TContext>
 {