full documentation

README.md

@@ -2,6 +2,8 @@
 
 version: 2.0.0
 
+customizable and simple authentication
+
 ## Installation
 
 npm:
@@ -14,7 +16,93 @@ yarn:
 
 ## Usage
 
-TODO: Add usage
+### 1. put a gateway in front of the routes you want to secure
+
+```js
+const {create_gateway} = require('@sapphirecode/auth-server-helper');
+
+const gateway = create_gateway({
+  redirect_url: '/auth',
+  cookie_name: 'auth_cookie', // if defined, access tokens will be read from this cookie
+});
+
+// express
+app.use(gateway);
+
+// node http
+http.createServer((main_req, main_res) =>
+  gateway(main_req, main_res, (req, res) => {
+    // your request handler
+  });
+);
+```
+
+the gateway will forward any authorized requests to the next handler and
+redirect all others to the specified url
+
+### 2. creating the auth endpoint
+
+```js
+const {create_auth_handler} = require('@sapphirecode/auth-server-helper');
+
+const handler = create_auth_handler(
+  (req) => {
+    if (req.user === 'foo' && req.password === 'bar')
+      const {access_token_id, refresh_token_id} = req.allow_access({
+        access_token_expires_in: 600, // seconds until access tokens expire
+        include_refresh_token: true, // should the answer include a refresh token? default: false
+        refresh_token_expires_in: 3600, // seconds until refresh tokens expire (required if refresh tokens are generated)
+        data: {user: 'foo'}, // additional custom data to include in the token
+      });
+
+    if (req.user === 'part' && req.password === 'baz')
+      const part_id = req.allow_part(
+        60, // seconds until part_token expires
+        'some_module', // next module handler (defined below)
+        {foo: 'bar'} // custom data to attach to the token
+      );
+
+    // all allow_ functions return a token id, which can later be used to invalidate specific tokens from the server side
+
+    req.deny();
+  },
+  {
+    refresh: {
+      /*...same options as allow_access */
+    }, // define the behaviour of refresh tokens. Refresh tokens will not be accepted if this option is undefined
+    modules: {
+      some_module(req) {
+        // request handlers for part_tokens
+
+        // access custom data:
+        const auth_data = req.request.connection.auth;
+        auth_data.token_id; // token id
+        auth_data.token_data; // custom data
+        // the same works in handlers after the gateway, information is always stored in request.connection.auth
+      },
+    },
+    cookie_name: 'auth_cookie', // if defined, access tokens will be stored in this cookie
+  }
+);
+
+// express
+app.use(handler);
+
+// node http
+// ... create server, on path /auth run the handler
+handler(req, res);
+```
+
+after the auth handler, the request will be completed, no additional content
+should be served here.
+
+### Invalidating tokens after they are delivered to the client
+
+```js
+const {blacklist} = require('@sapphirecode/auth-server-helper');
+
+blacklist.add_signature(token_id); // the token id is returned from any function that creates tokens
+```
 
 ## License
 

lib/index.ts

@@ -0,0 +1,7 @@
+import create_gateway from './Gateway';
+import create_auth_handler from './AuthHandler';
+
+import blacklist from './Blacklist';
+import authority from './Authority';
+
+export default { create_gateway, create_auth_handler, blacklist, authority };