@guardian/pan-domain-node 0.5.0 → 1.0.0

package/dist/src/panda.js

@@ -42,40 +42,78 @@ function createCookie(user, privateKey) {
 exports.createCookie = createCookie;
 function verifyUser(pandaCookie, publicKey, currentTime, validateUser) {
     if (!pandaCookie) {
-        return { status: api_1.AuthenticationStatus.INVALID_COOKIE };
+        return {
+            success: false,
+            reason: 'no-cookie'
+        };
     }
-    const { data, signature } = utils_1.parseCookie(pandaCookie);
+    const parsedCookie = utils_1.parseCookie(pandaCookie);
+    if (!parsedCookie) {
+        return {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+    }
+    const { data, signature } = parsedCookie;
     if (!utils_1.verifySignature(data, signature, publicKey)) {
-        return { status: api_1.AuthenticationStatus.INVALID_COOKIE };
+        return {
+            success: false,
+            reason: 'invalid-cookie'
+        };
     }
-    const currentTimestampInMilliseconds = currentTime.getTime();
+    const currentTimestampInMillis = currentTime.getTime();
     try {
         const user = utils_1.parseUser(data);
-        const isExpired = user.expires < currentTimestampInMilliseconds;
+        const isExpired = user.expires < currentTimestampInMillis;
         if (isExpired) {
-            return { status: api_1.AuthenticationStatus.EXPIRED, user };
+            const gracePeriodEndsAtEpochTimeMillis = user.expires + api_1.gracePeriodInMillis;
+            if (gracePeriodEndsAtEpochTimeMillis < currentTimestampInMillis) {
+                return {
+                    success: false,
+                    reason: 'expired-cookie'
+                };
+            }
+            else {
+                return {
+                    success: true,
+                    shouldRefreshCredentials: true,
+                    mustRefreshByEpochTimeMillis: gracePeriodEndsAtEpochTimeMillis,
+                    user
+                };
+            }
         }
         if (!validateUser(user)) {
-            return { status: api_1.AuthenticationStatus.NOT_AUTHORISED, user };
+            return {
+                success: false,
+                reason: 'invalid-user',
+                user
+            };
         }
-        return { status: api_1.AuthenticationStatus.AUTHORISED, user };
+        return {
+            success: true,
+            shouldRefreshCredentials: false,
+            user
+        };
     }
     catch (error) {
         console.error(error);
-        return { status: api_1.AuthenticationStatus.INVALID_COOKIE };
+        return {
+            success: false,
+            reason: 'unknown'
+        };
     }
 }
 exports.verifyUser = verifyUser;
 class PanDomainAuthentication {
     constructor(cookieName, region, bucket, keyFile, validateUser) {
-        this.keyCacheTime = 60 * 1000; // 1 minute
+        this.keyCacheTimeInMillis = 60 * 1000; // 1 minute
         this.cookieName = cookieName;
         this.region = region;
         this.bucket = bucket;
         this.keyFile = keyFile;
         this.validateUser = validateUser;
         this.publicKey = fetch_public_key_1.fetchPublicKey(region, bucket, keyFile);
-        this.keyUpdateTimer = setInterval(() => this.getPublicKey(), this.keyCacheTime);
+        this.keyUpdateTimer = setInterval(() => this.getPublicKey(), this.keyCacheTimeInMillis);
     }
     stop() {
         if (this.keyUpdateTimer) {
@@ -87,7 +125,7 @@ class PanDomainAuthentication {
         return this.publicKey.then(({ key, lastUpdated }) => {
             const now = new Date();
             const diff = now.getTime() - lastUpdated.getTime();
-            if (diff > this.keyCacheTime) {
+            if (diff > this.keyCacheTimeInMillis) {
                 this.publicKey = fetch_public_key_1.fetchPublicKey(this.region, this.bucket, this.keyFile);
                 return this.publicKey.then(({ key }) => key);
             }

package/dist/src/utils.d.ts

@@ -1,12 +1,14 @@
 import { User } from './api';
 export declare function decodeBase64(data: string): string;
-/**
- * Parse a pan-domain user cookie in to data and signature
- */
-export declare function parseCookie(cookie: string): {
+export declare type ParsedCookie = {
     data: string;
     signature: string;
 };
+/**
+ * Parse a pan-domain user cookie in to data and signature
+ * Validates that the cookie is properly formatted (two base64 strings separated by '.')
+ */
+export declare function parseCookie(cookie: string): ParsedCookie | undefined;
 /**
  * Verify signed data using nodeJs crypto library
  */

package/dist/src/utils.js

@@ -27,14 +27,34 @@ function decodeBase64(data) {
     return Buffer.from(data, 'base64').toString('utf8');
 }
 exports.decodeBase64 = decodeBase64;
+/**
+ * Check if a string is valid base64
+ */
+function isBase64(str) {
+    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 '.')
  */
 function parseCookie(cookie) {
-    const splitCookie = cookie.split('\.');
+    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
     };
 }
 exports.parseCookie = parseCookie;

package/dist/test/panda.test.js

@@ -16,26 +16,114 @@ const fixtures_1 = require("./fixtures");
 const utils_1 = require("../src/utils");
 jest.mock('../src/fetch-public-key');
 jest.useFakeTimers('modern');
+function userFromCookie(cookie) {
+    // 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 = utils_1.parseCookie(cookie);
+    return utils_1.parseUser(parsedCookie.data);
+}
 describe('verifyUser', function () {
-    test("return invalid cookie if missing", () => {
-        expect(panda_1.verifyUser(undefined, "", new Date(0), api_1.guardianValidation).status).toBe(api_1.AuthenticationStatus.INVALID_COOKIE);
+    test("fail to authenticate if cookie is missing", () => {
+        const expected = {
+            success: false,
+            reason: 'no-cookie'
+        };
+        expect(panda_1.verifyUser(undefined, "", new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
     });
-    test("return invalid cookie for a malformed signature", () => {
+    test("fail to authenticate if signature is malformed", () => {
         const [data, signature] = fixtures_1.sampleCookie.split(".");
         const testCookie = data + ".1234";
-        expect(panda_1.verifyUser(testCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation).status).toBe(api_1.AuthenticationStatus.INVALID_COOKIE);
+        const expected = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        expect(panda_1.verifyUser(testCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
     });
-    test("return expired", () => {
-        const someTimeInTheFuture = new Date(5678);
-        expect(someTimeInTheFuture.getTime()).toBe(5678);
-        expect(panda_1.verifyUser(fixtures_1.sampleCookie, fixtures_1.publicKey, someTimeInTheFuture, api_1.guardianValidation).status).toBe(api_1.AuthenticationStatus.EXPIRED);
+    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 + api_1.gracePeriodInMillis + 1);
+        const expected = {
+            success: false,
+            reason: 'expired-cookie'
+        };
+        expect(panda_1.verifyUser(fixtures_1.sampleCookie, fixtures_1.publicKey, afterEndOfGracePeriod, api_1.guardianValidation)).toStrictEqual(expected);
     });
-    test("return not authenticated if user fails validation function", () => {
-        expect(panda_1.verifyUser(fixtures_1.sampleCookieWithoutMultifactor, fixtures_1.publicKey, new Date(0), api_1.guardianValidation).status).toBe(api_1.AuthenticationStatus.NOT_AUTHORISED);
-        expect(panda_1.verifyUser(fixtures_1.sampleNonGuardianCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation).status).toBe(api_1.AuthenticationStatus.NOT_AUTHORISED);
+    test("fail to authenticate if user fails validation function", () => {
+        expect(panda_1.verifyUser(fixtures_1.sampleCookieWithoutMultifactor, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual({
+            success: false,
+            reason: 'invalid-user',
+            user: userFromCookie(fixtures_1.sampleCookieWithoutMultifactor)
+        });
+        expect(panda_1.verifyUser(fixtures_1.sampleNonGuardianCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual({
+            success: false,
+            reason: 'invalid-user',
+            user: userFromCookie(fixtures_1.sampleNonGuardianCookie)
+        });
+    });
+    test("fail to authenticate with invalid-cookie reason if signature is not valid", () => {
+        const expected = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const slightlyBadCookie = fixtures_1.sampleCookie.slice(0, -2);
+        expect(panda_1.verifyUser(slightlyBadCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
+    });
+    test("fail to authenticate with invalid-cookie reason if data part is not base64", () => {
+        const expected = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const [_, signature] = fixtures_1.sampleCookie.split(".");
+        const nonBase64Data = "not-base64-data";
+        const testCookie = `${nonBase64Data}.${signature}`;
+        expect(panda_1.verifyUser(testCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
+    });
+    test("fail to authenticate with invalid-cookie reason if signature part is not base64", () => {
+        const expected = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const [data, _] = fixtures_1.sampleCookie.split(".");
+        const nonBase64Signature = "not-base64-signature";
+        const testCookie = `${data}.${nonBase64Signature}`;
+        expect(panda_1.verifyUser(testCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
+    });
+    test("fail to authenticate with invalid-cookie reason if cookie has no dot separator", () => {
+        const expected = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const noDotCookie = fixtures_1.sampleCookie.replace(".", "");
+        expect(panda_1.verifyUser(noDotCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
+    });
+    test("fail to authenticate with invalid-cookie reason if cookie has multiple dot separators", () => {
+        const expected = {
+            success: false,
+            reason: 'invalid-cookie'
+        };
+        const multipleDotsCookie = fixtures_1.sampleCookie.replace(".", "..");
+        expect(panda_1.verifyUser(multipleDotsCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
+    });
+    test("authenticate if the cookie and user are valid", () => {
+        const expected = {
+            success: true,
+            // Cookie is not expired so no need to refresh credentials
+            shouldRefreshCredentials: false,
+            user: userFromCookie(fixtures_1.sampleCookie)
+        };
+        expect(panda_1.verifyUser(fixtures_1.sampleCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation)).toStrictEqual(expected);
     });
-    test("return authenticated", () => {
-        expect(panda_1.verifyUser(fixtures_1.sampleCookie, fixtures_1.publicKey, new Date(0), api_1.guardianValidation).status).toBe(api_1.AuthenticationStatus.AUTHORISED);
+    test("authenticate with shouldRefreshCredentials if cookie expired but we're within the grace period", () => {
+        const beforeEndOfGracePeriod = new Date(1234 + api_1.gracePeriodInMillis - 1);
+        const expected = {
+            success: true,
+            user: userFromCookie(fixtures_1.sampleCookie),
+            shouldRefreshCredentials: true,
+            mustRefreshByEpochTimeMillis: 1234 + api_1.gracePeriodInMillis
+        };
+        expect(panda_1.verifyUser(fixtures_1.sampleCookie, fixtures_1.publicKey, beforeEndOfGracePeriod, api_1.guardianValidation)).toStrictEqual(expected);
     });
 });
 describe('createCookie', function () {
@@ -92,23 +180,108 @@ describe('panda class', function () {
         beforeEach(() => {
             fetch_public_key_1.fetchPublicKey.mockResolvedValue({ key: fixtures_1.publicKey, lastUpdated: new Date() });
         });
-        it('should return authenticated if valid', () => __awaiter(this, void 0, void 0, function* () {
+        it('should authenticate if cookie and user are valid', () => __awaiter(this, void 0, void 0, function* () {
             jest.setSystemTime(100);
             const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u) => true);
-            const { status } = yield panda.verify(`cookiename=${fixtures_1.sampleCookie}`);
-            expect(status).toBe(api_1.AuthenticationStatus.AUTHORISED);
+            const authenticationResult = yield panda.verify(`cookiename=${fixtures_1.sampleCookie}`);
+            const expected = {
+                success: true,
+                // Cookie is not expired
+                shouldRefreshCredentials: false,
+                user: userFromCookie(fixtures_1.sampleCookie)
+            };
+            expect(authenticationResult).toStrictEqual(expected);
         }));
-        it('should return expired if expired', () => __awaiter(this, void 0, void 0, function* () {
-            jest.setSystemTime(10000);
+        it('should authenticate if cookie and user are valid when multiple cookies are passed', () => __awaiter(this, void 0, void 0, function* () {
+            jest.setSystemTime(100);
             const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u) => true);
-            const { status } = yield panda.verify(`cookiename=${fixtures_1.sampleCookie}`);
-            expect(status).toBe(api_1.AuthenticationStatus.EXPIRED);
+            const authenticationResult = yield panda.verify(`a=blah; b=stuff; cookiename=${fixtures_1.sampleCookie}; c=4958345`);
+            const expected = {
+                success: true,
+                // Cookie is not expired
+                shouldRefreshCredentials: false,
+                user: userFromCookie(fixtures_1.sampleCookie)
+            };
+            expect(authenticationResult).toStrictEqual(expected);
+        }));
+        it('should fail to authenticate if cookie expired and we\'re outside the grace period', () => __awaiter(this, void 0, void 0, function* () {
+            // Cookie expiry is 1234
+            const afterEndOfGracePeriodEpochMillis = 1234 + api_1.gracePeriodInMillis + 1;
+            jest.setSystemTime(afterEndOfGracePeriodEpochMillis);
+            const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u) => true);
+            const authenticationResult = yield panda.verify(`cookiename=${fixtures_1.sampleCookie}`);
+            const expected = {
+                success: false,
+                reason: 'expired-cookie'
+            };
+            expect(authenticationResult).toStrictEqual(expected);
+        }));
+        it('authenticate with shouldRefreshCredentials if cookie expired but we\'re within the grace period', () => __awaiter(this, void 0, void 0, function* () {
+            // Cookie expiry is 1234
+            const beforeEndOfGracePeriodEpochMillis = 1234 + api_1.gracePeriodInMillis - 1;
+            jest.setSystemTime(beforeEndOfGracePeriodEpochMillis);
+            const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', (u) => true);
+            const authenticationResult = yield panda.verify(`cookiename=${fixtures_1.sampleCookie}`);
+            const expected = {
+                success: true,
+                shouldRefreshCredentials: true,
+                mustRefreshByEpochTimeMillis: 1234 + api_1.gracePeriodInMillis,
+                user: userFromCookie(fixtures_1.sampleCookie)
+            };
+            expect(authenticationResult).toStrictEqual(expected);
+        }));
+        it('should fail to authenticate if user is not valid', () => __awaiter(this, void 0, void 0, function* () {
+            jest.setSystemTime(100);
+            const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', api_1.guardianValidation);
+            const authenticationResult = yield panda.verify(`cookiename=${fixtures_1.sampleNonGuardianCookie}`);
+            const expected = {
+                success: false,
+                reason: 'invalid-user',
+                user: userFromCookie(fixtures_1.sampleNonGuardianCookie)
+            };
+            expect(authenticationResult).toStrictEqual(expected);
         }));
-        it('should return not authenticated if validation fails', () => __awaiter(this, void 0, void 0, function* () {
+        it('should fail to authenticate if there is no cookie with the correct name', () => __awaiter(this, void 0, void 0, function* () {
             jest.setSystemTime(100);
             const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', api_1.guardianValidation);
-            const { status } = yield panda.verify(`cookiename=${fixtures_1.sampleNonGuardianCookie}`);
-            expect(status).toBe(api_1.AuthenticationStatus.NOT_AUTHORISED);
+            const authenticationResult = yield panda.verify(`wrongcookiename=${fixtures_1.sampleNonGuardianCookie}`);
+            const expected = {
+                success: false,
+                reason: "no-cookie"
+            };
+            expect(authenticationResult).toStrictEqual(expected);
+        }));
+        it('should fail to authenticate if the cookie request header is malformed', () => __awaiter(this, void 0, void 0, function* () {
+            jest.setSystemTime(100);
+            const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', api_1.guardianValidation);
+            // The cookie headers should be semicolon-separated name=valueg
+            const authenticationResult = yield panda.verify(fixtures_1.sampleNonGuardianCookie);
+            const expected = {
+                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', () => __awaiter(this, void 0, void 0, function* () {
+            jest.setSystemTime(100);
+            const panda = new panda_1.PanDomainAuthentication('cookiename', 'region', 'bucket', 'keyfile', api_1.guardianValidation);
+            const authenticationResult = yield panda.verify(`wrongcookiename=${fixtures_1.sampleNonGuardianCookie}; anotherwrongcookiename=${fixtures_1.sampleNonGuardianCookie}`);
+            const expected = {
+                success: false,
+                reason: "no-cookie"
+            };
+            expect(authenticationResult).toStrictEqual(expected);
+        }));
+        it('should fail to authenticate with invalid-cookie reason if cookie is malformed', () => __awaiter(this, void 0, void 0, function* () {
+            jest.setSystemTime(100);
+            const panda = new panda_1.PanDomainAuthentication('rightcookiename', 'region', 'bucket', 'keyfile', api_1.guardianValidation);
+            // There is a valid Panda cookie in here, but it's under the wrong name
+            const authenticationResult = yield panda.verify(`wrongcookiename=${fixtures_1.sampleNonGuardianCookie}; rightcookiename=not-valid-panda-cookie`);
+            const expected = {
+                success: false,
+                reason: "invalid-cookie"
+            };
+            expect(authenticationResult).toStrictEqual(expected);
         }));
     });
 });

package/dist/test/utils.test.js

@@ -4,9 +4,14 @@ const utils_1 = require("../src/utils");
 const fixtures_1 = require("./fixtures");
 const url_1 = require("url");
 test("decode a cookie", () => {
-    const { data, signature } = utils_1.parseCookie(fixtures_1.sampleCookie);
-    expect(signature.length).toBe(684);
-    const params = new url_1.URLSearchParams(data);
-    expect(params.get("firstName")).toBe("Test");
-    expect(params.get("lastName")).toBe("User");
+    const parsedCookie = utils_1.parseCookie(fixtures_1.sampleCookie);
+    expect(parsedCookie).toBeDefined();
+    // Unfortunately the above expect() doesn't narrow the type
+    if (parsedCookie) {
+        const { data, signature } = parsedCookie;
+        expect(signature.length).toBe(684);
+        const params = new url_1.URLSearchParams(data);
+        expect(params.get("firstName")).toBe("Test");
+        expect(params.get("lastName")).toBe("User");
+    }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guardian/pan-domain-node",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "NodeJs implementation of Guardian pan-domain auth verification",
   "main": "dist/src/api.js",
   "types": "dist/src/api.d.ts",

package/src/api.ts

@@ -1,11 +1,69 @@
 export { PanDomainAuthentication } from './panda';
 
-export enum AuthenticationStatus {
-    INVALID_COOKIE = 'Invalid Cookie',
-    EXPIRED = 'Expired',
-    NOT_AUTHORISED = 'Not Authorised',
-    AUTHORISED = 'Authorised'
+// We continue to consider the request authenticated for
+// a period of time after the cookie expiry. This is to allow
+// API requests which cannot directly send the user for re-auth to
+// indicate to the user that they must take some action to refresh their
+// credentials (usually, refreshing the page).
+
+// Panda cookie:               issued     expires
+//                             |          |
+//                             |--1 hour--|
+// Grace period:                          [------------- 24 hours ------]
+// `success`:         --false-][-true-----------------------------------][-false-------->
+// `shouldRefreshCredentials`  [-false---][-true------------------------]
+export const gracePeriodInMillis = 24 * 60 * 60 * 1000;
+
+// These are used to enforce the structure of the
+// `AuthenticationResult` union types,
+// but are not exported because they are too general.
+interface Result {
+    success: boolean
+}
+interface Success extends Result {
+    // `success` is true when both these are true:
+    // 1. we've verified that the cookie is signed by the correct private key
+    //    and decoded a `User` from it
+    // 2. we've validated the `User` using `ValidateUserFn`
+    success: true,
+    shouldRefreshCredentials: boolean,
+    user: User
+}
+interface Failure extends Result {
+    success: false,
+    reason: string
+}
+
+// These are members of the `AuthenticationResult` union,
+// so they are exported for use by library consumers.
+export interface FreshSuccess extends Success {
+    // Cookie has not expired yet, so no need to refresh credentials.
+    shouldRefreshCredentials: false
+}
+export interface StaleSuccess extends Success {
+    // Cookie has expired: we're in the grace period.
+    // Endpoints that can refresh credentials should do so,
+    // and those that cannot should tell the user to do so.
+    shouldRefreshCredentials: true,
+    mustRefreshByEpochTimeMillis: number
 }
+export interface UserValidationFailure extends Failure {
+    reason: 'invalid-user',
+    user: User
+}
+export interface CookieFailure extends Failure {
+    reason: 'no-cookie' | 'invalid-cookie' | 'expired-cookie'
+}
+export interface UnknownFailure extends Failure {
+    reason: 'unknown'
+}
+
+export type AuthenticationResult = FreshSuccess
+    | StaleSuccess
+    | CookieFailure
+    | UserValidationFailure
+    | UnknownFailure
+
 
 export interface User {
     firstName: string,
@@ -18,11 +76,6 @@ export interface User {
     multifactor: boolean
 }
 
-export interface AuthenticationResult {
-    status: AuthenticationStatus,
-    user?: User 
-}
-
 export type ValidateUserFn = (user: User) => boolean;
 
 export function guardianValidation(user: User): boolean {

package/src/panda.ts

@@ -1,7 +1,7 @@
 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';
 
 export function createCookie(user: User, privateKey: string): string {
@@ -25,34 +25,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,7 +101,7 @@ export class PanDomainAuthentication {
     validateUser: ValidateUserFn;
 
     publicKey: Promise<PublicKeyHolder>;
-    keyCacheTime: number = 60 * 1000; // 1 minute
+    keyCacheTimeInMillis: number = 60 * 1000; // 1 minute
     keyUpdateTimer?: NodeJS.Timeout;
 
     constructor(cookieName: string, region: string, bucket: string, keyFile: string, validateUser: ValidateUserFn) {
@@ -76,7 +113,7 @@ export class PanDomainAuthentication {
 
         this.publicKey = fetchPublicKey(region, bucket, keyFile);
 
-        this.keyUpdateTimer = setInterval(() => this.getPublicKey(), this.keyCacheTime);
+        this.keyUpdateTimer = setInterval(() => this.getPublicKey(), this.keyCacheTimeInMillis);
     }
 
     stop(): void {
@@ -91,7 +128,7 @@ export class PanDomainAuthentication {
             const now = new Date();
             const diff = now.getTime() - lastUpdated.getTime();
 
-            if(diff > this.keyCacheTime) {
+            if(diff > this.keyCacheTimeInMillis) {
                 this.publicKey = fetchPublicKey(this.region, this.bucket, this.keyFile);
                 return this.publicKey.then(({ key }) => key);
             } else {