readme with correct instructions

Author: iamjono

README.md

@@ -1,4 +1,4 @@
-# Perfect-Authentication
+# Perfect Local Authentication (PostgreSQL)
 
 [![Perfect logo](http://www.perfect.org/github/Perfect_GH_header_854.jpg)](http://perfect.org/get-involved.html)
 
@@ -15,119 +15,139 @@
 [![Join the chat at https://gitter.im/PerfectlySoft/Perfect](https://img.shields.io/badge/Gitter-Join%20Chat-brightgreen.svg)](https://gitter.im/PerfectlySoft/Perfect?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Slack Status](http://perfect.ly/badge.svg)](http://perfect.ly) [![GitHub version](https://badge.fury.io/gh/PerfectlySoft%2FPerfect-CURL.svg)](https://badge.fury.io/gh/PerfectlySoft%2FPerfect-CURL)
 
-## OAuth2 Library for Perfect
+## Perfect Local Authentication (PostgreSQL) Library
 
 
-This project provides [OAuth2](https://oauth.net/2/) libraries and select OAuth2 provider drivers - Facebook, Google, GitHub.
+This package provides Local Authentication libraries for projects that require locally stored and handled authentication.
 
-Full documentation can be found at [http://www.perfect.org/docs/OAuth2.html](http://www.perfect.org/docs/OAuth2.html)
+Full documentation can be found at [http://www.perfect.org/docs/authentication.html](http://www.perfect.org/docs/authentication.html.html)
 
-A demo application can be found at [https://github.com/PerfectExamples/Perfect-Authentication-Demo](https://github.com/PerfectExamples/Perfect-Authentication-Demo) that shows the usage of the system.
+A template application can be found at [https://github.com/PerfectlySoft/Perfect-Local-Auth-PostgreSQL-Template](https://github.com/PerfectlySoft/Perfect-Local-Auth-PostgreSQL-Template), providing a fully functional starting point, as well as demonstrating the usage of the system.
 
 This package builds with Swift Package Manager and is part of the [Perfect](https://github.com/PerfectlySoft/Perfect) project. It was written to be stand-alone and so does not require PerfectLib or any other components.
 
-Ensure you have installed and activated the latest Swift 3.0 tool chain.
+Ensure you have installed and activated the latest Swift 3.x tool chain.
 
 ## Adding to your project
 
 Add this project as a dependency in your Package.swift file.
 
 ``` swift
-.Package(url: "https://github.com/PerfectlySoft/Perfect-Authentication.git", majorVersion: 1)
+.Package(url: "https://github.com/PerfectlySoft/Perfect-LocalAuthentication-PostgreSQL.git", majorVersion: 1)
 ```
 
-To then use the OAuth2 module in your code:
+To then use the LocalAuthentication module in your code:
 
 ``` swift
-import OAuth2
+import LocalAuthentication
 ```
 
 ## Configuration
 
-Each provider needs an "appid", also known as a "key", and a "secret". These are usually generated by the OAuth Host, such as Facebook, GitHub and Google developer consoles. These values, as well as an "endpointAfterAuth" and "redirectAfterAuth" value must be set for each provider you wish to use. 
+It is important to configure the following in main.swift to set up database and session configuration:
 
-To configure Facebook as a provider:
+Import the required modules:
 
 ``` swift
-FacebookConfig.appid = "yourAppID"
-FacebookConfig.secret = "yourSecret"
-FacebookConfig.endpointAfterAuth = "http://localhost:8181/auth/response/facebook"
-FacebookConfig.redirectAfterAuth = "http://localhost:8181/"
+import PerfectSession
+import PerfectSessionPostgreSQL
+import PerfectCrypto
+import LocalAuthentication
 ```
 
-To configure Google as a provider:
+Initialize PerfectCrypto:
 
 ``` swift
-GoogleConfig.appid = "yourAppID"
-GoogleConfig.secret = "yourSecret"
-GoogleConfig.endpointAfterAuth = "http://localhost:8181/auth/response/google"
-GoogleConfig.redirectAfterAuth = "http://localhost:8181/"
+let _ = PerfectCrypto.isInitialized
 ```
 
-To configure GitHub as a provider:
+Now set some defaults:
 
 ``` swift
-GitHubConfig.appid = "yourAppID"
-GitHubConfig.secret = "yourSecret"
-GitHubConfig.endpointAfterAuth = "http://localhost:8181/auth/response/github"
-GitHubConfig.redirectAfterAuth = "http://localhost:8181/"
+// Used in email communications
+// The Base link to your system, such as http://www.example.com/
+var baseURL = ""
+
+// Configuration of Session
+SessionConfig.name = "perfectSession" // <-- change
+SessionConfig.idle = 86400
+SessionConfig.cookieDomain = "localhost" //<-- change
+SessionConfig.IPAddressLock = false
+SessionConfig.userAgentLock = false
+SessionConfig.CSRF.checkState = true
+SessionConfig.CORS.enabled = true
+SessionConfig.cookieSameSite = .lax
 ```
 
-## Adding Routes
+Detailed Session configuration documentation can be dound at [https://www.perfect.org/docs/sessions.html](https://www.perfect.org/docs/sessions.html)
 
-The OAuth2 system relies on an authentication / exchange system, which requires a URL to be specially assembled that the user is redirected to, and a URL that the user is returned to after the user has committed the authorization action.
-
-The first set of routes below are the action URL's that will redirect to the OAuth2 provider's system. They can be anything you wish them to be. The user will never see anything on them as they will be immediately redirected to the correct place.
-
-The second set of routes below are where the OAuth2 provider should return the user to. Note that this is the same as the "endpointAfterAuth" configuration option. Once the "authResponse" function has been completed the user is automatically forwarded to the URL in the "redirectAfterAuth" option.
+The database and email configurations should be set as follows (if using JSON file config):
 
 ``` swift
-var routes: [[String: Any]] = [[String: Any]]()
+let opts = initializeSchema("./config/ApplicationConfiguration.json") // <-- loads base config like db and email configuration
+httpPort = opts["httpPort"] as? Int ?? httpPort
+baseURL = opts["baseURL"] as? String ?? baseURL
+```
 
-routes.append(["method":"get", "uri":"/to/facebook", "handler":Facebook.sendToProvider])
-routes.append(["method":"get", "uri":"/to/github", "handler":GitHub.sendToProvider])
-routes.append(["method":"get", "uri":"/to/google", "handler":Google.sendToProvider])
+Otherwise, these will need to be set equivalent to this function [https://github.com/PerfectlySoft/Perfect-LocalAuthentication-PostgreSQL/blob/master/Sources/LocalAuthentication/Schema/InitializeSchema.swift](https://github.com/PerfectlySoft/Perfect-LocalAuthentication-PostgreSQL/blob/master/Sources/LocalAuthentication/Schema/InitializeSchema.swift).
 
-routes.append(["method":"get", "uri":"/auth/response/facebook", "handler":Facebook.authResponse])
-routes.append(["method":"get", "uri":"/auth/response/github", "handler":GitHub.authResponse])
-routes.append(["method":"get", "uri":"/auth/response/google", "handler":Google.authResponse])
-```
+Set the session driver:
 
-## Information returned and made available
+``` swift
+let sessionDriver = SessionPostgresDriver()
+```
 
-After the user has been authenticated, certain information is gleaned from the OAuth2 provider.
+### Request & Response Filters
 
-Note that the session ID can be retrieved using:
+The following two session filters need to be added to your server config:
 
 ``` swift
-request.session?.token
+// (where filter is a [[String: Any]] object)
+filters.append(["type":"request","priority":"high","name":SessionPostgresFilter.filterAPIRequest])
+filters.append(["type":"response","priority":"high","name":SessionPostgresFilter.filterAPIResponse])
 ```
 
-The user-specific information can be accessed as part of the session info:
+For example, see [https://github.com/PerfectlySoft/Perfect-Local-Auth-PostgreSQL-Template/blob/master/Sources/PerfectLocalAuthPostgreSQLTemplate/configuration/Filters.swift](https://github.com/PerfectlySoft/Perfect-Local-Auth-PostgreSQL-Template/blob/master/Sources/PerfectLocalAuthPostgreSQLTemplate/configuration/Filters.swift)
 
-``` swift
-// The UserID as defined by the provider
-request.session?.userid
+### Add routes for login, register etc
 
-// designates the OAuth2 source - useful if you are allowing multiple OAuth providers
-request.session?.data["loginType"]
+The following routes can be added as needed or customized to add login, logout, register:
 
-// The access token obtained in the process
-request.session?.data["accessToken"]
+``` swift
+// Login
+routes.append(["method":"get", "uri":"/login", "handler":Handlers.login]) // simply a serving of the login GET
+routes.append(["method":"post", "uri":"/login", "handler":LocalAuthWebHandlers.login])
+routes.append(["method":"get", "uri":"/logout", "handler":LocalAuthWebHandlers.logout])
+
+// Register
+routes.append(["method":"get", "uri":"/register", "handler":LocalAuthWebHandlers.register])
+routes.append(["method":"post", "uri":"/register", "handler":LocalAuthWebHandlers.registerPost])
+routes.append(["method":"get", "uri":"/verifyAccount/{passvalidation}", "handler":LocalAuthWebHandlers.registerVerify])
+routes.append(["method":"post", "uri":"/registrationCompletion", "handler":LocalAuthWebHandlers.registerCompletion])
+
+// JSON
+routes.append(["method":"get", "uri":"/api/v1/session", "handler":LocalAuthJSONHandlers.session])
+routes.append(["method":"get", "uri":"/api/v1/logout", "handler":LocalAuthJSONHandlers.logout])
+routes.append(["method":"post", "uri":"/api/v1/register", "handler":LocalAuthJSONHandlers.register])
+routes.append(["method":"login", "uri":"/api/v1/login", "handler":LocalAuthJSONHandlers.login])
+```
 
-// The user's first name as supplied by the provider
-request.session?.data["firstName"]
+An example can be found at [https://github.com/PerfectlySoft/Perfect-Local-Auth-PostgreSQL-Template/blob/master/Sources/PerfectLocalAuthPostgreSQLTemplate/configuration/Routes.swift](https://github.com/PerfectlySoft/Perfect-Local-Auth-PostgreSQL-Template/blob/master/Sources/PerfectLocalAuthPostgreSQLTemplate/configuration/Routes.swift)
 
-// The user's last name as supplied by the provider
-request.session?.data["lastName"]
+## Testing for authentication:
 
-// The user's profile picture as supplied by the provider
-request.session?.data["picture"]
+The user id can be accessed as follows:
 
+``` swift
+request.session?.userid ?? ""
 ```
 
-With access to this information, you can now save to the database of your choice.
+If a user id (i.e. logged in state) is required to access a page, code such as this could be used to detect and redirect:
 
+``` swift
+let contextAuthenticated = !(request.session?.userid ?? "").isEmpty
+if !contextAuthenticated { response.redirect(path: "/login") }
+```
 
 ## Issues