Merge pull request #177 from StatelessStudio/v2.0.0

[2.0.0] Jun-06-2019

Author: DrewImm

CHANGELOG.md

@@ -1,5 +1,30 @@
 # PointyApi Changelog
 
+## [2.0.0] Jun-06-2019
+
+### Breaking Changes (See migration.md)
+
+- [Issue #167] Auth token should remain stateless
+- [Issue #170] Guards should use forbiddenResponder instead of unauthorizedResponder
+- [Issue #174] Don't use auto-increment id
+- [Issue #175] Issue refresh tokens
+
+### Additions
+
+- [Issue #93] Add security checks to test-suite
+- [Issue #168] Add pointy.ready hook to fire when server is listening
+- [Issue #169] CORS function should utilize process.env.CLIENT_URL
+- [Issue #173] Package.json should include repository info
+
+### Fixes
+
+- npm update
+- Removed typedoc from dependencies
+- [Issue #165] loadUser() should use uniform Could not/Couldn't
+- [Issue #166] validationResponder() "Not null violation" should specify field name
+- [Issue #171] Http expect should accept success codes
+- [Issue #172] [README] Misidentifies Authentication/Authorization
+
 ## [1.2.4] May-29-2019
 
 ### Fixes

README.md

@@ -14,8 +14,8 @@ PointyAPI is a library for quickly creating robust API servers.
 
 - **ORM** *(TypeORM)* Create models which automatically create and maintain your database
 - **Validation** *(Class Validator)* Use Typescript decorators to automatically validate fields
-- **Authorization** *(JWT)* JWT and `request.user` make authorization a breeze
-- **Authentication** Use `CanRead()` and `CanWrite()` fields to ensure the user can read/write specific fields
+- **Authentication** *(JWT)* JWT and `request.user` make authorization a breeze
+- **Authorization** Use Guards, `CanRead()`, and `CanWrite()` fields to ensure the user can read/write specific fields
 
 ### Models
 
@@ -28,16 +28,16 @@ class User extends BaseUser
 	// User ID
 	@PrimaryGeneratedColumn() // Primary column
 	@IsInt() // Validation - Value must be integer
-	@BodyguardKey() // Authorization - User must match this to be considered "self"
-	@AnyoneCanRead() // Authentication - Anyone is allowed to read this field
+	@BodyguardKey() // Authentication - User must match this to be considered "self"
+	@AnyoneCanRead() // Authorization - Anyone is allowed to read this field
 	public id: number = undefined;
 
 	// Username
 	@Column({ unique: true }) // Database column - Usernames are unique
 	@IsAlphanumeric() // Validation - must be alphanumeric
 	@Length(4, 16) // Validation - must be between 4-16 characters
 	@AnyoneCanRead() // Authentication - Anyone has read privelege to this member
-	@OnlySelfCanWrite() // Authentication - Only self can write this member
+	@OnlySelfCanWrite() // Authorization - Only self can write this member
 	public username: string = undefined;
 
 	// Password
@@ -366,15 +366,45 @@ npm i pointyapi
 
 	Notice that now we get a `204 No Content` (which means deleted successfully!).
 
+	**What about the refreshToken?**
+	You may notice you got two tokens back: `token` and `refreshToken`.
+
+	The `token` is short-lived - it only lasts 15 minutes or so.
+	The `refreshToken` is long-living - it lasts about a week.
+
+	You can use the `refreshToken` to issue a new `accessToken` when it expires.
+
 9. **Production**
 
 To launch in production mode, please make sure the following variables are set (environment variables/.env)
 
 - **SITE_TITLE** - Set the site title
 - **CLIENT_URL** - Set your client URL to add the client to the CORS policy
 - **JWT_KEY** - Set your token key to make JWT cryptographically secure
-- **JWT_TTL** - Set your token time-to-live. Default is 4 hours
+- **JWT_TTL** - Set your token time-to-live (seconds). Default is 15 minutes
+- **JWT_REFRESH_TTL** - Set your refresh token time-to-live (seconds). Default is 7 days.
+
+#### UUID vs Auto-Incremented IDs
+
+It is a security risk to use auto-incremented IDs, and you should instead use UUID for all ID columns.
 
+To switch to using UUIDs:
+
+- Install the `pgcrypto` extension
+- Tell TypeORM to use pgcrypto by placing the line `uuidExtension: 'pgcrypto'` in `orm-cli.js`
+- Change all `PrimaryGeneratedColumn()` to `PrimaryGeneratedColumn('uuid')`
+- Change all `public id: number` members to `public id: string`
+- Make sure you remove `IsInt()` from all ID fields, if it exists
+- Ensure your front-end and anywhere you may access the ID is expecting a string
+
+Example:
+```typescript
+	// User ID
+	@PrimaryGeneratedColumn('uuid') // Primary column
+	@BodyguardKey() // Authentication - User must match this to be considered "self"
+	@AnyoneCanRead() // Authorization - Anyone is allowed to read this field
+	public id: string = undefined;
+```
 
 ### Continued Reading
 

migration.md

@@ -103,4 +103,18 @@
 17. Remove empty searches.
 	Get queries no longer require a `search` key to access other query keys
 18. All mdoel members must be initialized to undefined, including relational arrays
-19. Queries may no longer pass special keys with `__` or `___`.  You should now put these queries in the `additionalParameters` query object
+19. Queries may no longer pass special keys with `__` or `___`.  You should now put these queries in the `additionalParameters` query object
+
+## Version 1.x.x -> 2.x.x
+
+1. Auth tokens are now completely stateless. Remove the `token` field from your User entity.
+2. Login now issues a refresh token.
+   1. Make a POST endpoint in your auth router:
+		`router.post('/refresh', refreshTokenEndpoint);` 
+   2. Update your front-end auth service to save the `refreshToken` and `refreshExpiration` from the `loginEndpoint`
+   3. Set a timeout to call the `refreshTokenEndpoint` route when the access token expires. `refreshTokenEndpoint` will return an updated user object, including a new access token & expiration time.
+3. **(Optional)** PointyAPI now supports `UUID`. Follow the steps in the Readme to enable UUID (strongly recommended for production).
+
+   **NOTE** If you are already in production and decide to migrate to UUID, you must make sure to update relations etc
+
+4. **(Optional)** Guards will now issue a `401` only if a token is not present/valid, otherwise will issue a `403`. This may help determine if the user is authenticated/authorized on the front-end.

orm-cli.js

@@ -8,5 +8,6 @@ module.exports = {
 	user: dbSettings.user,
 	password: dbSettings.password,
 	database: dbSettings.database,
-	entities: [ 'lib/src/models/base-user.ts' ]
+	entities: [ 'lib/src/models/base-user.ts' ],
+	uuidExtension: 'pgcrypto'
 };

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "pointyapi",
-	"version": "1.2.4",
+	"version": "2.0.0",
 	"author": "stateless-studio",
 	"license": "MIT",
 	"scripts": {
@@ -57,5 +57,18 @@
 		"nyc": "^14.1.1",
 		"source-map-support": "^0.5.12",
 		"ts-node": "^7.0.1"
-	}
+	},
+	"description": "*\"Stop writing endpoints\"*",
+	"directories": {
+		"lib": "lib",
+		"test": "test"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/statelessstudio/pointyapi.git"
+	},
+	"bugs": {
+		"url": "https://github.com/statelessstudio/pointyapi/issues"
+	},
+	"homepage": "https://github.com/statelessstudio/pointyapi#readme"
 }

package.json

@@ -91,7 +91,10 @@ export class PointyPostgres extends BaseDb {
 			password: pgOptions.password,
 			database: pgOptions.database,
 			entities: this.entities,
-			synchronize: this.shouldSync
+			synchronize: this.shouldSync,
+			uuidExtension: pgOptions.uuidExtension
+				? pgOptions.uuidExtension
+				: 'pgcrypto'
 		}).catch((error) => this.errorHandler(error));
 	}
 }

src/database/postgres.ts

@@ -66,3 +66,4 @@ export { postEndpoint } from './endpoints/post-endpoint';
 export { patchEndpoint } from './endpoints/patch-endpoint';
 export { loginEndpoint } from './endpoints/login-endpoint';
 export { logoutEndpoint } from './endpoints/logout-endpoint';
+export { refreshTokenEndpoint } from './endpoints/refresh-token-endpoint';

src/endpoints.ts

@@ -78,7 +78,10 @@ export async function loginEndpoint(
 		const expiration = jwtBearer.getExpiration();
 		const token = jwtBearer.sign(match);
 
-		if (token) {
+		const refreshExpiration = jwtBearer.getExpiration(true);
+		const refreshToken = jwtBearer.sign(match, true);
+
+		if (token && refreshToken) {
 			// Set request user
 			request.user = match;
 
@@ -92,6 +95,8 @@ export async function loginEndpoint(
 
 			match['expiration'] = expiration;
 			match['token'] = token;
+			match['refreshExpiration'] = refreshExpiration;
+			match['refreshToken'] = refreshToken;
 
 			// Send response
 			if (!await runHook('afterLogin', request.user, request, response)) {

src/endpoints/login-endpoint.ts

@@ -0,0 +1,76 @@
+import { Request, Response } from 'express';
+
+import { jwtBearer } from '../jwt-bearer';
+import { runHook } from '../utils/run-hook';
+import { readFilter } from '../bodyguard/read-filter';
+import { BaseUser } from '../models';
+
+/**
+ * Refresh the user's token
+ * @param request Request object to query by
+ * @param response Response object to call responder with
+ */
+export async function refreshTokenEndpoint(
+	request: Request,
+	response: Response
+): Promise<void> {
+	// Check request body
+	if ('refreshToken' in request.body) {
+		// Check refresh token
+		const token = jwtBearer.dryVerify(request.body.refreshToken);
+
+		if (token && 'isRefresh' in token && token.isRefresh) {
+			// Load user
+			let match = await request.repository
+				.findOne({ id: token.id })
+				.catch((error) => response.error(error));
+
+			// Check matching user
+			if (match && match instanceof BaseUser) {
+				// Create token
+				const expiration = jwtBearer.getExpiration();
+				const token = jwtBearer.sign(match);
+
+				// Set request user
+				request.user = match;
+
+				// Create response
+				match = readFilter(
+					match,
+					request.user,
+					request.payloadType,
+					request.userType
+				);
+
+				match['expiration'] = expiration;
+				match['token'] = token;
+
+				// Send response
+				if (
+					!await runHook(
+						'tokenRefresh',
+						request.user,
+						request,
+						response
+					)
+				) {
+					return;
+				}
+
+				response.json(match);
+			}
+			else {
+				// No match found
+				response.unauthorizedResponder('Could not authenticate user');
+			}
+		}
+		else {
+			// No match found
+			response.unauthorizedResponder('Could not authenticate user');
+		}
+	}
+	else {
+		// Respond with 400
+		response.validationResponder('No refresh token sent');
+	}
+}