@guardian/pan-domain-node
Version:
NodeJs implementation of Guardian pan-domain auth verification
162 lines (106 loc) • 5.34 kB
Markdown
- a3a6b24: Fix fast-xml-parser vulnerabilities
- f72f1c3: Bump @aws-sdk to latest to remove vulnerable fast-xml-parser version
- 567436a: no-op release to test migration to NPM trusted publishing
- 502bbd5: no-op release to test migration to NPM trusted publishing
- 5c14027: Fix app crash with no cookie value
- b762261: Download public key from S3 with AWS credential
- f91598a:
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, 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, 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!
}
}
```
- bdd4adb: Testing changeset release and capitalising some text
- 01ddac5: Fix bug preventing cookie expiry from being correctly validated