@guardian/pan-domain-node 0.5.1 → 1.1.0

package/src/panda.ts

@@ -1,8 +1,11 @@
 import * as cookie from 'cookie';
 
 import {parseCookie, parseUser, sign, verifySignature} from './utils';
-import {AuthenticationStatus, User, AuthenticationResult, ValidateUserFn} from './api';
+import {User, AuthenticationResult, ValidateUserFn, gracePeriodInMillis} from './api';
 import { fetchPublicKey, PublicKeyHolder } from './fetch-public-key';
+import { S3 } from "@aws-sdk/client-s3";
+import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
+import { AwsCredentialIdentityProvider } from "@aws-sdk/types";
 
 export function createCookie(user: User, privateKey: string): string {
     let queryParams: string[] = [];
@@ -25,34 +28,71 @@ export function createCookie(user: User, privateKey: string): string {
 }
 
 export function verifyUser(pandaCookie: string | undefined, publicKey: string, currentTime: Date, validateUser: ValidateUserFn): AuthenticationResult {
-    if(!pandaCookie) {
-        return { status: AuthenticationStatus.INVALID_COOKIE };
+    if (!pandaCookie) {
+        return {
+            success: false,
+            reason: 'no-cookie'
+        };
     }
 
-    const { data, signature } = parseCookie(pandaCookie);
+    const parsedCookie = parseCookie(pandaCookie);
+    if (!parsedCookie) {
+        return {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+    }
+    const { data, signature } = parsedCookie;
 
-    if(!verifySignature(data, signature, publicKey)) {
-        return { status: AuthenticationStatus.INVALID_COOKIE };
+    if (!verifySignature(data, signature, publicKey)) {
+        return {
+            success: false,
+            reason: 'invalid-cookie'
+        };
     }
 
-    const currentTimestampInMilliseconds = currentTime.getTime();
+    const currentTimestampInMillis = currentTime.getTime();
 
     try {
         const user: User = parseUser(data);
-        const isExpired = user.expires < currentTimestampInMilliseconds;
-
-        if(isExpired) {
-            return { status: AuthenticationStatus.EXPIRED, user };
+        const isExpired = user.expires < currentTimestampInMillis;
+
+        if (isExpired) {
+            const gracePeriodEndsAtEpochTimeMillis = user.expires + gracePeriodInMillis;
+            if (gracePeriodEndsAtEpochTimeMillis < currentTimestampInMillis) {
+                return {
+                    success: false,
+                    reason: 'expired-cookie'
+                };
+            } else {
+                return {
+                    success: true,
+                    shouldRefreshCredentials: true,
+                    mustRefreshByEpochTimeMillis: gracePeriodEndsAtEpochTimeMillis,
+                    user
+                }
+            }
         }
 
-        if(!validateUser(user)) {
-            return { status: AuthenticationStatus.NOT_AUTHORISED, user };
+        if (!validateUser(user)) {
+            return {
+                success: false,
+                reason: 'invalid-user',
+                user
+            };
         }
 
-        return { status: AuthenticationStatus.AUTHORISED, user };
-    } catch(error) {
+        return {
+            success: true,
+            shouldRefreshCredentials: false,
+            user
+        };
+    } catch (error) {
         console.error(error);
-        return { status: AuthenticationStatus.INVALID_COOKIE };
+        return {
+            success: false,
+            reason: 'unknown'
+        };
     }
 }
 
@@ -64,19 +104,25 @@ export class PanDomainAuthentication {
     validateUser: ValidateUserFn;
 
     publicKey: Promise<PublicKeyHolder>;
-    keyCacheTime: number = 60 * 1000; // 1 minute
+    keyCacheTimeInMillis: number = 60 * 1000; // 1 minute
     keyUpdateTimer?: NodeJS.Timeout;
+    s3Client: S3;
 
-    constructor(cookieName: string, region: string, bucket: string, keyFile: string, validateUser: ValidateUserFn) {
+    constructor(cookieName: string, region: string, bucket: string, keyFile: string, validateUser: ValidateUserFn, credentialsProvider: AwsCredentialIdentityProvider = fromNodeProviderChain()) {
         this.cookieName = cookieName;
         this.region = region;
         this.bucket = bucket;
         this.keyFile = keyFile;
         this.validateUser = validateUser;
 
-        this.publicKey = fetchPublicKey(region, bucket, keyFile);
+        const standardAwsConfig = {
+            region: region,
+            credentials: credentialsProvider,
+        }; 
+        this.s3Client = new S3(standardAwsConfig);
+        this.publicKey = fetchPublicKey(this.s3Client, bucket, keyFile);
 
-        this.keyUpdateTimer = setInterval(() => this.getPublicKey(), this.keyCacheTime);
+        this.keyUpdateTimer = setInterval(() => this.getPublicKey(), this.keyCacheTimeInMillis);
     }
 
     stop(): void {
@@ -91,8 +137,8 @@ export class PanDomainAuthentication {
             const now = new Date();
             const diff = now.getTime() - lastUpdated.getTime();
 
-            if(diff > this.keyCacheTime) {
-                this.publicKey = fetchPublicKey(this.region, this.bucket, this.keyFile);
+            if(diff > this.keyCacheTimeInMillis) {
+                this.publicKey = fetchPublicKey(this.s3Client, this.bucket, this.keyFile);
                 return this.publicKey.then(({ key }) => key);
             } else {
                 return key;
@@ -104,7 +150,6 @@ export class PanDomainAuthentication {
         return this.getPublicKey().then(publicKey => {
             const cookies = cookie.parse(requestCookies);
             const pandaCookie = cookies[this.cookieName];
-
             return verifyUser(pandaCookie, publicKey, new Date(), this.validateUser);
         });
     }

package/src/utils.ts

@@ -8,14 +8,40 @@ export function decodeBase64(data: string): string {
     return Buffer.from(data, 'base64').toString('utf8');
 }
 
+export type ParsedCookie = { data: string, signature: string };
+
+/**
+ * Check if a string is valid base64
+ */
+function isBase64(str: string): boolean {
+    try {
+        return Buffer.from(str, 'base64').toString('base64') === str;
+    } catch (err) {
+        return false;
+    }
+}
+
 /**
  * Parse a pan-domain user cookie in to data and signature
+ * Validates that the cookie is properly formatted (two base64 strings separated by '.')
  */
-export function parseCookie(cookie: string): { data: string, signature: string} {
-    const splitCookie = cookie.split('\.');
+export function parseCookie(cookie: string): ParsedCookie | undefined {
+    const cookieRegex = /^([\w\W]*)\.([\w\W]*)$/;
+    const match = cookie.match(cookieRegex);
+    
+    if (!match) {
+        return undefined;
+    }
+
+    const [, data, signature] = match;
+    
+    if (!isBase64(data) || !isBase64(signature)) {
+        return undefined;
+    }
+
     return {
-        data: decodeBase64(splitCookie[0]),
-        signature: splitCookie[1]
+        data: decodeBase64(data),
+        signature: signature
     };
 }
 

package/test/panda.test.ts

@@ -1,4 +1,9 @@
-import {guardianValidation, AuthenticationStatus, User} from '../src/api';
+import {
+    CookieFailure, FreshSuccess,
+    gracePeriodInMillis,
+    guardianValidation, StaleSuccess,
+    User, UserValidationFailure
+} from '../src/api';
 import { verifyUser, createCookie, PanDomainAuthentication } from '../src/panda';
 import { fetchPublicKey } from '../src/fetch-public-key';
 
@@ -9,37 +14,132 @@ import {
     publicKey,
     privateKey
 } from './fixtures';
-import {decodeBase64} from "../src/utils";
+import {decodeBase64, parseCookie, ParsedCookie, parseUser} from "../src/utils";
 
 jest.mock('../src/fetch-public-key');
-jest.useFakeTimers('modern');
+jest.useFakeTimers();
+
+function userFromCookie(cookie: string): User {
+    // This function is only used to generate a `User` object from
+    // a well-formed text fixture cookie, in order to check that successful
+    // `AuthenticationResult`s have the right shape. As such we don't want
+    // to have to deal with the case of a bad cookie so we just cast to `ParsedCookie`.
+    const parsedCookie = parseCookie(cookie) as ParsedCookie;
+    return parseUser(parsedCookie.data);
+}
 
 describe('verifyUser', function () {
 
-    test("return invalid cookie if missing", () => {
-        expect(verifyUser(undefined, "", new Date(0), guardianValidation).status).toBe(AuthenticationStatus.INVALID_COOKIE);
+    test("fail to authenticate if cookie is missing", () => {
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'no-cookie'
+        };
+        expect(verifyUser(undefined, "", new Date(0), guardianValidation)).toStrictEqual(expected);
     });
 
-    test("return invalid cookie for a malformed signature", () => {
+    test("fail to authenticate if signature is malformed", () => {
         const [data, signature] = sampleCookie.split(".");
         const testCookie = data + ".1234";
 
-        expect(verifyUser(testCookie, publicKey, new Date(0), guardianValidation).status).toBe(AuthenticationStatus.INVALID_COOKIE);
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        expect(verifyUser(testCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
+    });
+
+    test("fail to authenticate if cookie expired and we're outside the grace period", () => {
+        // Cookie expires at epoch time 1234
+        const afterEndOfGracePeriod = new Date(1234 + gracePeriodInMillis + 1)
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'expired-cookie'
+        };
+        expect(verifyUser(sampleCookie, publicKey, afterEndOfGracePeriod, guardianValidation)).toStrictEqual(expected);
+    });
+
+    test("fail to authenticate if user fails validation function", () => {
+        expect(verifyUser(sampleCookieWithoutMultifactor, publicKey, new Date(0), guardianValidation)).toStrictEqual({
+            success: false,
+            reason: 'invalid-user',
+            user: userFromCookie(sampleCookieWithoutMultifactor)
+        });
+        expect(verifyUser(sampleNonGuardianCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual({
+            success: false,
+            reason: 'invalid-user',
+            user: userFromCookie(sampleNonGuardianCookie)
+        });
+    });
+
+    test("fail to authenticate with invalid-cookie reason if signature is not valid", () => {
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const slightlyBadCookie = sampleCookie.slice(0, -2);
+        expect(verifyUser(slightlyBadCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
+    });
+
+    test("fail to authenticate with invalid-cookie reason if data part is not base64", () => {
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const [_, signature] = sampleCookie.split(".");
+        const nonBase64Data = "not-base64-data";
+        const testCookie = `${nonBase64Data}.${signature}`;
+        expect(verifyUser(testCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
     });
 
-    test("return expired", () => {
-        const someTimeInTheFuture = new Date(5678);
-        expect(someTimeInTheFuture.getTime()).toBe(5678);
-        expect(verifyUser(sampleCookie, publicKey, someTimeInTheFuture, guardianValidation).status).toBe(AuthenticationStatus.EXPIRED);
+    test("fail to authenticate with invalid-cookie reason if signature part is not base64", () => {
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const [data, _] = sampleCookie.split(".");
+        const nonBase64Signature = "not-base64-signature";
+        const testCookie = `${data}.${nonBase64Signature}`;
+        expect(verifyUser(testCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
     });
 
-    test("return not authenticated if user fails validation function", () => {
-        expect(verifyUser(sampleCookieWithoutMultifactor, publicKey, new Date(0), guardianValidation).status).toBe(AuthenticationStatus.NOT_AUTHORISED);
-        expect(verifyUser(sampleNonGuardianCookie, publicKey, new Date(0), guardianValidation).status).toBe(AuthenticationStatus.NOT_AUTHORISED);
+    test("fail to authenticate with invalid-cookie reason if cookie has no dot separator", () => {
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const noDotCookie = sampleCookie.replace(".", "");
+        expect(verifyUser(noDotCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
     });
 
-    test("return authenticated", () => {
-        expect(verifyUser(sampleCookie, publicKey, new Date(0), guardianValidation).status).toBe(AuthenticationStatus.AUTHORISED);
+    test("fail to authenticate with invalid-cookie reason if cookie has multiple dot separators", () => {
+        const expected: CookieFailure = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const multipleDotsCookie = sampleCookie.replace(".", "..");
+        expect(verifyUser(multipleDotsCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
+    });
+
+    test("authenticate if the cookie and user are valid", () => {
+        const expected: FreshSuccess = {
+            success: true,
+            // Cookie is not expired so no need to refresh credentials
+            shouldRefreshCredentials: false,
+            user: userFromCookie(sampleCookie)
+        };
+        expect(verifyUser(sampleCookie, publicKey, new Date(0), guardianValidation)).toStrictEqual(expected);
+    });
+
+    test("authenticate with shouldRefreshCredentials if cookie expired but we're within the grace period", () => {
+        const beforeEndOfGracePeriod = new Date(1234 + gracePeriodInMillis - 1);
+        const expected: StaleSuccess = {
+            success: true,
+            user: userFromCookie(sampleCookie),
+            shouldRefreshCredentials: true,
+            mustRefreshByEpochTimeMillis: 1234 + gracePeriodInMillis
+        };
+        expect(verifyUser(sampleCookie, publicKey, beforeEndOfGracePeriod, guardianValidation)).toStrictEqual(expected);
     });
 });
 
@@ -122,32 +222,133 @@ describe('panda class', function () {
       (fetchPublicKey as jest.MockedFunction<typeof fetchPublicKey>).mockResolvedValue({ key: publicKey, lastUpdated: new Date() });
     });
 
-    it('should return authenticated if valid', async () => {
+    it('should authenticate if cookie and user are valid', async () => {
       jest.setSystemTime(100);
       const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u)=> true);
-      const { status } = await panda.verify(`cookiename=${sampleCookie}`);
+      const authenticationResult = await panda.verify(`cookiename=${sampleCookie}`);
+
+      const expected: FreshSuccess = {
+          success: true,
+          // Cookie is not expired
+          shouldRefreshCredentials: false,
+          user: userFromCookie(sampleCookie)
+      }
+      expect(authenticationResult).toStrictEqual(expected);
+    });
 
-      expect(status).toBe(AuthenticationStatus.AUTHORISED);
+    it('should authenticate if cookie and user are valid when multiple cookies are passed', async () => {
+      jest.setSystemTime(100);
+      const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u)=> true);
+      const authenticationResult = await panda.verify(`a=blah; b=stuff; cookiename=${sampleCookie}; c=4958345`);
+
+      const expected: FreshSuccess = {
+          success: true,
+          // Cookie is not expired
+          shouldRefreshCredentials: false,
+          user: userFromCookie(sampleCookie)
+      };
+      expect(authenticationResult).toStrictEqual(expected);
     });
 
-    it('should return expired if expired', async () => {
-      jest.setSystemTime(10_000);
+    it('should fail to authenticate if cookie expired and we\'re outside the grace period', async () => {
+      // Cookie expiry is 1234
+      const afterEndOfGracePeriodEpochMillis = 1234 + gracePeriodInMillis + 1
+      jest.setSystemTime(afterEndOfGracePeriodEpochMillis);
 
       const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u)=> true);
-      const { status } = await panda.verify(`cookiename=${sampleCookie}`);
+      const authenticationResult = await panda.verify(`cookiename=${sampleCookie}`);
 
-      expect(status).toBe(AuthenticationStatus.EXPIRED);
+      const expected: CookieFailure = {
+          success: false,
+          reason: 'expired-cookie'
+      };
+      expect(authenticationResult).toStrictEqual(expected);
     });
 
-    it('should return not authenticated if validation fails', async () => {
+    it('authenticate with shouldRefreshCredentials if cookie expired but we\'re within the grace period', async () => {
+      // Cookie expiry is 1234
+      const beforeEndOfGracePeriodEpochMillis = 1234 + gracePeriodInMillis - 1;
+      jest.setSystemTime(beforeEndOfGracePeriodEpochMillis);
+
+      const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u)=> true);
+      const authenticationResult = await panda.verify(`cookiename=${sampleCookie}`);
+
+      const expected: StaleSuccess = {
+          success: true,
+          shouldRefreshCredentials: true,
+          mustRefreshByEpochTimeMillis: 1234 + gracePeriodInMillis,
+          user: userFromCookie(sampleCookie)
+      };
+      expect(authenticationResult).toStrictEqual(expected);
+    });
+
+    it('should fail to authenticate if user is not valid', async () => {
       jest.setSystemTime(100);
 
       const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', guardianValidation);
-      const { status } = await panda.verify(`cookiename=${sampleNonGuardianCookie}`);
+      const authenticationResult = await panda.verify(`cookiename=${sampleNonGuardianCookie}`);
+
+      const expected: UserValidationFailure = {
+          success: false,
+          reason: 'invalid-user',
+          user: userFromCookie(sampleNonGuardianCookie)
+      };
+      expect(authenticationResult).toStrictEqual(expected);
+    });
 
-      expect(status).toBe(AuthenticationStatus.NOT_AUTHORISED);
+    it('should fail to authenticate if there is no cookie with the correct name', async () => {
+      jest.setSystemTime(100);
+
+      const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', guardianValidation);
+      const authenticationResult = await panda.verify(`wrongcookiename=${sampleNonGuardianCookie}`);
+
+      const expected: CookieFailure = {
+          success: false,
+          reason: "no-cookie"
+      };
+      expect(authenticationResult).toStrictEqual(expected);
     });
 
+    it('should fail to authenticate if the cookie request header is malformed', async () => {
+      jest.setSystemTime(100);
+
+      const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', guardianValidation);
+      // The cookie headers should be semicolon-separated name=valueg
+      const authenticationResult = await panda.verify(sampleNonGuardianCookie);
+
+      const expected: CookieFailure = {
+          success: false,
+          reason: "no-cookie"
+      };
+      expect(authenticationResult).toStrictEqual(expected);
+    });
+
+    it('should fail to authenticate if there is no cookie with the correct name out of multiple cookies', async () => {
+      jest.setSystemTime(100);
+
+      const panda = new PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', guardianValidation);
+      const authenticationResult = await panda.verify(`wrongcookiename=${sampleNonGuardianCookie}; anotherwrongcookiename=${sampleNonGuardianCookie}`);
+
+      const expected: CookieFailure = {
+          success: false,
+          reason: "no-cookie"
+      };
+      expect(authenticationResult).toStrictEqual(expected);
+    });
+
+    it('should fail to authenticate with invalid-cookie reason if cookie is malformed', async () => {
+      jest.setSystemTime(100);
+
+      const panda = new PanDomainAuthentication('rightcookiename', 'region', 'bucket', 'keyfile', guardianValidation);
+      // There is a valid Panda cookie in here, but it's under the wrong name
+      const authenticationResult = await panda.verify(`wrongcookiename=${sampleNonGuardianCookie}; rightcookiename=not-valid-panda-cookie`);
+
+      const expected: CookieFailure = {
+        success: false,
+        reason: "invalid-cookie"
+      };
+      expect(authenticationResult).toStrictEqual(expected);
+    });
   });
 
 });

package/test/utils.test.ts

@@ -3,11 +3,17 @@ import { sampleCookie } from './fixtures';
 import { URLSearchParams } from 'url';
 
 test("decode a cookie", () => {
-    const { data, signature } = parseCookie(sampleCookie);
-    expect(signature.length).toBe(684);
+    const parsedCookie = parseCookie(sampleCookie);
+    expect(parsedCookie).toBeDefined()
 
-    const params = new URLSearchParams(data);
-    
-    expect(params.get("firstName")).toBe("Test");
-    expect(params.get("lastName")).toBe("User");
+    // Unfortunately the above expect() doesn't narrow the type
+    if (parsedCookie) {
+        const { data, signature } = parsedCookie;
+        expect(signature.length).toBe(684);
+
+        const params = new URLSearchParams(data);
+
+        expect(params.get("firstName")).toBe("Test");
+        expect(params.get("lastName")).toBe("User");
+    }
 });

package/.github/workflows/snyk.yml

@@ -1,19 +0,0 @@
-name: Snyk
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-jobs:
-  security:
-    uses: guardian/.github/.github/workflows/sbt-node-snyk.yml@main
-    with:
-      DEBUG: true
-      ORG: guardian
-      SKIP_NODE: false
-      NODE_VERSION_FILE: .nvmrc
-
-    secrets:
-       SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}