@guardian/pan-domain-node 0.5.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @guardian/pan-domain-node
 
+## 1.0.0
+
+### Major Changes
+
+- f91598a: # Changes
+  Adds a 24-hour grace period after cookie expiry, during which requests will still be considered authenticated.
+
+  This is modelled by changing `AuthenticatedStatus` into a discriminated union with the following properties (among others):
+
+  ### `success`
+
+  Whether to treat request as authenticated or not. **This will remain true after cookie expiry for the length of the grace period.**
+
+  [Almost all consumers](https://docs.google.com/spreadsheets/d/19XABaP9ua935TYJARkL8tstnizL69gIJ9av8C3UQBYw/edit?gid=0#gid=0) of this library check **only** the `AUTHORISED` status right now. These should all be able to switch to checking just this single boolean, implicitly getting grace period functionality in the process.
+
+  ### `shouldRefreshCredentials`
+
+  Whether to try and get fresh credentials.
+
+  This allows page endpoints to redirect to auth, and API endpoints to tell the frontend to show a warning message to the user.
+
+  ### `mustRefreshByEpochTimeMillis`
+
+  The time at which the grace period ends and the request will be treated as unauthenticated. This allows library consumers to warn the user in the app UI when they are near the end of the grace period, as Composer does: https://github.com/guardian/flexible-content/pull/5210
+
+  ```
+  Panda cookie:               issued     expires                       `mustRefreshByEpochTimeMillis`
+                              |          |                             |
+                              |--1 hour--|                             |
+  Grace period:                          [------------- 24 hours ------]
+
+  `success`:         --false-][-true-----------------------------------][-false-------->
+  `shouldRefreshCredentials`  [-false---][-true------------------------]
+  ```
+
+  # Why have we made this change?
+
+  The Panda authentication cookie expires after 1 hour, and top-level navigation requests (page loads) trigger automatic re-authentication after this point.
+
+  Unfortunately API requests cannot trigger re-authentication on their own, and background refresh mechanisms (e.g. iframe-based method used by [Pandular](https://github.com/guardian/pandular)) are increasingly blocked by browsers due to third-party cookie restrictions.
+
+  We would like to enforce a 24-hour grace period
+
+  # How to update consuming code
+
+  At a minimum, switch from
+
+  ```typescript
+  const authResult = await panda.verify(cookieHeader);
+  if (
+    authResult.status === AuthenticationStatus.AUTHORISED &&
+    authResult.user
+  ) {
+    return authResult.user.email;
+  }
+  ```
+
+  to
+
+  ```typescript
+  const authResult = await panda.verify(cookieHeader);
+  if (authResult.success) {
+    return authResult.user.email;
+  }
+  ```
+
+  This will implicitly give you grace period functionality, because `success` will remain true during the grace period.
+
+  However, we **strongly** recommend all consumers to take account of `shouldRefreshCredentials`. What you do with the result should depend on whether your endpoint can trigger re-auth.
+
+  ## Endpoints that can refresh credentials
+
+  Endpoints that **can** refresh credentials, e.g. page endpoints that can redirect to an auth flow, should send the user to re-auth if `shouldRefreshCredentials` is `true`:
+
+  ```typescript
+  const authResult = await panda.verify(headers.cookie);
+  if (authResult.success) {
+    if (authResult.shouldRefreshCredentials) {
+      // Send for auth
+    } else {
+      // Can perform action with user
+      return authResult.user;
+    }
+  }
+  ```
+
+  ## Endpoints that cannot refresh credentials
+
+  Endpoints that **cannot** refresh credentials, e.g. API endpoints, should log appropriately and return something to the client that can be used to warn the user that they need to refresh their session.
+
+  ```typescript
+  const authResult = await panda.verify(headers.cookie);
+  if (authResult.success) {
+    const user = authResult.user;
+    // Handle request
+    // When returning response:
+    if (authResult.shouldRefreshCredentials) {
+      const mustRefreshByEpochTimeMillis =
+        authResult.mustRefreshByEpochTimeMillis;
+      const remainingTime = mustRefreshByEpochTimeMillis - Date.now();
+      console.warn(
+        `Stale Panda auth, will expire in ${remainingTime} milliseconds`
+      );
+      // Can still return 200, but depending on the type of API,
+      // we may want to return some extra information so the client
+      // can warn the user they need to refresh their session.
+    } else {
+      // It's a fresh session. Nothing to worry about!
+    }
+  }
+  ```
+
 ## 0.5.1
 
 ### Patch Changes

package/CODEOWNERS

@@ -1 +1 @@
-* @guardian/digital-cms
+* @guardian/workflow-and-collaboration

package/README.md

@@ -14,14 +14,33 @@ functionality for signing and verifying login cookies in Scala.
 
 The `pan-domain-node` library provides an implementation of *verification only* for node apps.
 
-## To verify login in NodeJS
+## Grace period
+We continue to consider the request authenticated for a period of time after the cookie expiry.
 
-[![npm version](https://badge.fury.io/js/%40guardian%2Fpan-domain-node.svg)](https://badge.fury.io/js/%40guardian%2Fpan-domain-node)
+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).
+
+When the cookie is expired but we're still within this grace period, `shouldRefreshCredentials` will be `true`, which means:
+- Endpoints that can refresh credentials (e.g. page endpoints that can redirect) should do so
+- Endpoints that cannot refresh credentials (e.g. API endpoints) should tell the user to take some action to refresh credentials
+
+```
+Panda cookie:               issued     expires                       `mustRefreshByEpochTimeMillis`
+                            |          |                             |
+                            |--1 hour--|                             |
+Grace period:                          [------------- 24 hours ------]
 
+`success`:         --false-][-true-----------------------------------][-false-------->
+`shouldRefreshCredentials`  [-false---][-true------------------------]
+```
+
+## Example usage
+### Installation
+[![npm version](https://badge.fury.io/js/%40guardian%2Fpan-domain-node.svg)](https://badge.fury.io/js/%40guardian%2Fpan-domain-node)
 ```
 npm install --save-dev @guardian/pan-domain-node
 ```
 
+### Initialisation
 ```typescript
 import { PanDomainAuthentication, AuthenticationStatus, User, guardianValidation } from '@guardian/pan-domain-node';
 
@@ -38,18 +57,39 @@ function customValidation(user: User): boolean {
   const isInCorrectDomain = user.email.indexOf('test.com') !== -1;
   return isInCorrectDomain && user.multifactor;
 }
+```
 
-// when handling a request
-function(request) {
-  // Pass the raw unparsed cookies
-  return panda.verify(request.headers['Cookie']).then(( { status, user }) => {
-    switch(status) {
-      case AuthenticationStatus.Authorised:
-        // Good user, handle the request!
-
-      default:
-        // Bad user. Return 4XX
+### Verification: page endpoints
+This is for endpoints that **can** refresh credentials, e.g. a page endpoint that can redirect to an auth flow:
+```typescript
+const authenticationResult = await panda.verify(headers.cookie);
+if (authenticationResult.success) {
+    if (authenticationResult.shouldRefreshCredentials) {
+        // Send for auth
+    } else {
+        // Can perform action with user
+        return authenticationResult.user;
     }
-  });
 }
 ```
+
+### Verification: API endpoints
+This is for endpoints that **cannot** refresh credentials, e.g. API endpoints:
+```typescript
+const authenticationResult = await panda.verify(headers.cookie);
+if (authenticationResult.success) {
+  const user = authenticationResult.user;
+  // Handle request
+  // When returning response:
+  if (authenticationResult.shouldRefreshCredentials) {
+    const mustRefreshByEpochTimeMillis = authenticationResult.mustRefreshByEpochTimeMillis;
+    const remainingTime = mustRefreshByEpochTimeMillis - Date.now();
+    console.warn(`Stale Panda auth, will expire in ${remainingTime} milliseconds`);
+    // Can still return 200, but depending on the type of API,
+    // we may want to return some extra information so the client
+    // can warn the user they need to refresh their session.
+   } else {
+    // It's a fresh session. Nothing to worry about!
+  }
+}
+```

package/dist/src/api.d.ts

@@ -1,10 +1,35 @@
 export { PanDomainAuthentication } from './panda';
-export declare enum AuthenticationStatus {
-    INVALID_COOKIE = "Invalid Cookie",
-    EXPIRED = "Expired",
-    NOT_AUTHORISED = "Not Authorised",
-    AUTHORISED = "Authorised"
+export declare const gracePeriodInMillis: number;
+interface Result {
+    success: boolean;
 }
+interface Success extends Result {
+    success: true;
+    shouldRefreshCredentials: boolean;
+    user: User;
+}
+interface Failure extends Result {
+    success: false;
+    reason: string;
+}
+export interface FreshSuccess extends Success {
+    shouldRefreshCredentials: false;
+}
+export interface StaleSuccess extends Success {
+    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 declare type AuthenticationResult = FreshSuccess | StaleSuccess | CookieFailure | UserValidationFailure | UnknownFailure;
 export interface User {
     firstName: string;
     lastName: string;
@@ -15,9 +40,5 @@ export interface User {
     expires: number;
     multifactor: boolean;
 }
-export interface AuthenticationResult {
-    status: AuthenticationStatus;
-    user?: User;
-}
 export declare type ValidateUserFn = (user: User) => boolean;
 export declare function guardianValidation(user: User): boolean;

package/dist/src/api.js

@@ -1,15 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.guardianValidation = exports.AuthenticationStatus = void 0;
+exports.guardianValidation = exports.gracePeriodInMillis = void 0;
 var panda_1 = require("./panda");
 Object.defineProperty(exports, "PanDomainAuthentication", { enumerable: true, get: function () { return panda_1.PanDomainAuthentication; } });
-var AuthenticationStatus;
-(function (AuthenticationStatus) {
-    AuthenticationStatus["INVALID_COOKIE"] = "Invalid Cookie";
-    AuthenticationStatus["EXPIRED"] = "Expired";
-    AuthenticationStatus["NOT_AUTHORISED"] = "Not Authorised";
-    AuthenticationStatus["AUTHORISED"] = "Authorised";
-})(AuthenticationStatus = exports.AuthenticationStatus || (exports.AuthenticationStatus = {}));
+// 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------------------------]
+exports.gracePeriodInMillis = 24 * 60 * 60 * 1000;
 function guardianValidation(user) {
     const isGuardianUser = user.email.indexOf('guardian.co.uk') !== -1;
     return isGuardianUser && user.multifactor;

package/dist/src/panda.d.ts

@@ -10,7 +10,7 @@ export declare class PanDomainAuthentication {
     keyFile: string;
     validateUser: ValidateUserFn;
     publicKey: Promise<PublicKeyHolder>;
-    keyCacheTime: number;
+    keyCacheTimeInMillis: number;
     keyUpdateTimer?: NodeJS.Timeout;
     constructor(cookieName: string, region: string, bucket: string, keyFile: string, validateUser: ValidateUserFn);
     stop(): void;

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;