@hitchy/plugin-auth 0.3.5 → 0.3.7

package/docs/api/routing.md

@@ -1,101 +0,0 @@
----
-prev: config.md
-next: false
----
-
-# Routing defaults
-
-Unless [disabled in runtime configuration](config.md#config-auth-prefix), this plugin is always setting up routes providing basic user authentication to a client.
-
-::: warning Customizable prefix  
-The following documentation relies on default prefix `/api/auth`. You may [change this default in runtime configuration](config.md#config-auth-prefix). Adopt URLs listed below according to your setup if required.  
-:::
-
-Some basic initialization is required in every request. This can't be disabled using runtime configuration.
-
-## `POST /api/auth/login/:strategy?`
-
-This route is authenticating some user by processing its credentials found in request body which is either JSON-formatted or some URL-encoded form data. 
-
-Actual format of provided credentials depend on passport strategy being used. The built-in local strategy used by default expects `username` and `password` being provided in properties named accordingly:
-
-```http request
-POST /api/auth/login HTTP/1.0
-Content-Type: application/x-www-form-urlencoded
-
-username=john.doe&password=my-secret-token
-```
-
-The result is always provided as JSON object.
-
-:::tip Background
-This routing combines policy [authentication.login](policy/authentication.md#login) with controller [user.authenticate](controller/user.md#authenticate).
-:::
-
-## `GET /api/auth/login/:strategy`
-
-This route is integrating authentication code for optionally picking up external authentication on returning from remote service. You need to provide a strategy here.
-
-## `GET /api/auth/logout`
-
-This route is triggering removal any server-side session data suitable for implicitly re-authenticating some current user. 
-
-The result is provided as JSON object.
-
-:::tip Background
-This routing combines policy [authentication.logout](policy/authentication.md#logout) with controller [user.unauthenticate](controller/user.md#unauthenticate).
-:::
-
-## `GET /api/auth/current`
-
-The route delivers information on some currently authenticated user as JSON object.
-
-If no user is authenticated, the result is:
-
-```json
-{
-	"success": true,
-    "authenticated": false
-}
-```
-
-Following a successful authentication, the result is similar to this one:
-
-```json
-{
-	"success": true,
-    "authenticated": {
-        "uuid": "12345678-1234-1234-1234-1234-123456789012",
-        "name": "john.doe",
-        "roles": ["users", "customers"]
-    }
-}
-```
-
-:::tip Background
-This routing targets controller [user.getCurrent](controller/user.md#getcurrent).
-:::
-
-## `POST /api/auth/password`
-
-This route is processing request for changing some previously authenticated user's token a.k.a. password. 
-
-All information is read from request body which is either JSON-formatted or some URL-encoded form data. It must contain properties `current` and `next` providing user's current password and the one to become user's next password.
-
-```http request
-POST /api/auth/passowrd HTTP/1.0
-Content-Type: application/x-www-form-urlencoded
-
-current=my-old-secret&next=my-new-secret
-```
-
-The result is provided as JSON object.
-
-::: warning Current user, only  
-By intention, this request handler is limited to changing current user's password, only. A custom request handler is required to change password of different users.
-:::
-
-:::tip Background
-This routing combines policy [user.changePassword](policy/user.md#changepassword) with controller [user.changePassword](controller/user.md#changepassword).
-:::
-

package/docs/api/service/auth-manager.md

@@ -1,86 +0,0 @@
----
-prev: authentication-strategies.md
-next: authorization-tree.md
----
-
-# AuthManager
-
-This service provides several helper functions commonly useful on managing authentication and authorization at runtime. 
-
-::: tip FYI  
-Due to supporting both parts, the name is reduced to common prefix _Auth_ by intention.  
-:::
-
-## Properties
-
-### adminRole
-
-This property commonly exposes name of role implicitly granting access to any resource without regards to existing authorization rules in runtime configuration or in local database. The resulting name depends on current runtime environment and runtime configuration.
-
-## Methods
-
-### asUser()
-
-**Signature:** `async asUser( user, [ createIfMissing ] ): User`
-
-This wrapper is meant to assure that provided user is actually an instance of model [User](../model/user.md) existing in local database. 
-
-It takes a user's name, ...
-
-```javascript
-const user = await AuthManager.asUser( "john.doe" );
-```
-
-... an object with property name selecting desired user (ignoring any other property in that object) ...
-
-```javascript
-const user = await AuthManager.asUser( { name: "john.doe", foo: "bar" } );
-```
-
-... or the user's existing instance as input.
-
-```javascript
-const user = await AuthManager.asUser( new User( uuid ) );
-```
-
-It retrieves instance of user selected either way. Due to accepting instances of [User](../model/user.md), it can be safely used multiple times.
-
-Optional boolean parameter `createIfMissing` must be set true to implicitly create selected user in local database if missing. Otherwise, the method throws an error causing promised result to be rejected.
-
-### asRole()
-
-**Signature:** `async asRole( role, [ createIfMissing ] ): Role`
-
-This is the counterpart to [asUser()](#asuser) for simplifying access on roles. The same semantics apply.
-
-### listRolesOfUser()
-
-**Signature:** `async listRolesOfUser( user, [ createIfMissing ], [ uuidsOnly ] ): Roles[]`
-
-The method takes a user and qualifies it via [asUser()](#asuser) before fetching list of user's associated roles. Argument for optional `createIfMissing` is forwarded to `asUser()` and `false` by default. Argument for optional `uuidsOnly` must be set explicitly to prevent listed instances of [Role](../model/role.md) to implicitly load their records from database.
-
-### listUsersOfRole()
-
-**Signature:** `async listUsersOfRole( role, [ createIfMissing ], [ uuidsOnly ] ): User[]`
-
-This method is the counterpart to [listRolesOfUser()](#listrolesofuser): it is querying local database for users associated with a given role. Provided role is qualified via [asRole()](#asrole) with argument `createIfMissing` being forwarded. 
-
-Optional boolean parameter `uuidsOnly` must be set to prevent implicit retrieval of either listed user's record from database.
-
-### grantRoleToUser()
-
-**Signature:** `async grantRoleToUser( role, user, [ createIfMissing] ): void`
-
-This helper is provided for conveniently [associating](../model/user-to-role.md) a [user](../model/user.md) with a [role](../model/role.md). Provided arguments for `role` and `user` are qualified with [asRole()](#asrole) and [asUser()](#asuser). Optional argument for `createIfMissing` is forwarded to either method internally.
-
-### revokeRoleFromUser()
-
-**Signature:** `async revokeRoleFromUser( role, user, [ createIfMissing] ): void`
-
-This helper is provided for conveniently removing any existing [association](../model/user-to-role.md) between a [user](../model/user.md) and a [role](../model/role.md). Provided arguments for `role` and `user` are qualified with [asRole()](#asrole) and [asUser()](#asuser). Optional argument for `createIfMissing` is forwarded to either method internally.
-
-### createAdminIfMissing()
-
-**Signature:** `async createAdminIfMissing(): void`
-
-This method is used during bootstrap to make sure there is always a user associated with configured [administrator role](#adminrole) preventing any authorization management from locking out all existing users.

package/docs/api/service/authentication-passport.md

@@ -1,21 +0,0 @@
----
-prev: /api/service/
-next: authentication-strategies.md
----
-
-# AuthenticationPassport
-
-This service integrates [Passport](https://www.passportjs.org/) with Hitchy's request routing. The service itself represents instance of Passport created for integration with Hitchy-based application.
-
-This service is primarily for internal use. You should use it in edge cases to additionally customize Passport, only.
-
-## Methods
-
-### integrateWithHitchy()
-
-**Signature:** `integrateWithHitchy(): void`
-
-This method has been implemented for internal use. It is executed on every incoming request
-
-* to set up handlers persisting authenticated user's information to server-side session and restoring it from there in follow-up requests and
-* to instruct passport to [use](https://www.passportjs.org/docs/configure/#strategies) every configured strategy.

package/docs/api/service/authentication-strategies.md

@@ -1,22 +0,0 @@
----
-prev: authentication-passport.md
-next: auth-manager.md
----
-
-# AuthenticationStrategies
-
-This service helps with picking a default strategy. In addition, it exposes a strategy for local authentication. The latter is used on integrating [Passport](https://www.passportjs.org/) while bootstrapping your application and this plugin.
-
-## Methods
-
-### defaultStrategy()
-
-**Signature:** `defaultStrategy(): string`
-
-Provides name of strategy to use by default depending on current application's configuration.
-
-### generateLocal()
-
-**Signature:** `generateLocal(): Strategy`
-
-Creates custom instance of Passport's LocalStrategy set up for integrating with Hitchy's request routing.

package/docs/api/service/authorization-node.md

@@ -1,102 +0,0 @@
----
-prev: authorization-tree.md
-next: authorization-policy-generator.md
----
-
-# AuthorizationNode
-
-This class is primarily used by [AuthorizationTree](authorization-tree.md) to describe a tree of nodes.
-
-## Properties
-
-### parent
-
-Refers to parent authorization node in a tree of nodes. It is nullish on top-most node of tree.
-
-### name
-
-Provides segment of resource name used to address this node in context of its parent node.
-
-## Methods
-
-### clear()
-
-**Signature:** `clear(): AuthorizationNode`
-
-Clears thread of current node by recursively invoking this very method on superordinated nodes before deleting any list of users and roles tracked in context of current node for being granted or revoked access on resource represented by current node.
-
-Returns this node for daisy-chaining calls.
-
-### addRole()
-
-**Signature:** `addRole( roleName, [ accept ] ): AuthorizationNode`
-
-Adds named role to current node for being granted or revoked access depending on optionally provided argument `accept`. On omitting or on providing `true`, access on resource represented by current node is granted to named role. Otherwise, access is revoked.
-
-Returns this node for daisy-chaining calls.
-
-### addUser()
-
-**Signature:** `addUser( userName, [ accept ] ): AuthorizationNode`
-
-Adds named user to current node for being granted or revoked access depending on optionally provided argument `accept`. On omitting or on providing `true`, access on resource represented by current node is granted to named user. Otherwise, access is revoked.
-
-Returns this node for daisy-chaining calls.
-
-### removeRole()
-
-**Signature:** `removeRole( roleName, [ accept ] ): AuthorizationNode`
-
-Revokes previously granted or revoked access on resource represented by current node to/from named role. Optionally provided argument `accept` must be equivalent to what was provided on adding role before.
-
-Returns this node for daisy-chaining calls.
-
-### removeUser()
-
-**Signature:** `removeUser( userName, [ accept ] ): AuthorizationNode`
-
-Revokes previously granted or revoked access on resource represented by current node to/from named user. Optionally provided argument `accept` must be equivalent to what was provided on adding role before.
-
-Returns this node for daisy-chaining calls.
-
-### getChild()
-
-**Signature:** `getChild( name, [ addIfMissing ] ): AuthorizationNode`
-
-Retrieves reference on node subordinated to current one representing immediate child of current resource in a hierarchy of resources.
-
-Provided `name` must be a single segment's name, only. Optional argument `addIfMissing` must be `true` to always return another node. Otherwise, undefined is returned if selected child node does not exist.
-
-### isAuthorized()
-
-**Signature:** `isAuthorized( userName, roleName ): number`
-
-Checks if current nodes' lists of grants and revokes for accessing represented resource are containing provided user name or role name. 
-
-The method returns
-
-* -1 if user/role is revoked access on represented resource,
-* 1 if user/role is granted access on represented resource and
-* 0 if current node doesn't affect provided user or role.
-
-If either provided name of a user or role is granted access while the other is rejected, the method throws exception.
-
-### isSpare()
-
-**Signature:** `isSpare(): boolean`
-
-Detects if current node and all of its child nodes are spare by means of not granting or revoking access on their represented resource to/from any user or role.
-
-This information is used on garbage collection to drop data in runtime memory which isn't actually required anymore.
-
-### gc()
-
-**Signature:** `gc(): AuthorizationNode`
-
-Runs garbage collection on thread of current node returning a reduced copy of current node's thread for replacement in scope of parent node. `undefined` is returned in case of current node being available for removal.
-
-### path()
-
-**Signature:** `path(): string`
-
-Recursively compiles qualified name of resource represented by current node.

package/docs/api/service/authorization-policy-generator.md

@@ -1,66 +0,0 @@
----
-prev: authorization-node.md
-next: ../config.md
----
-
-# AuthorizationPolicyGenerator
-
-This service is generating functions suitable for [policy-handling](https://core.hitchy.org/internals/routing-basics.html#policies) requests. Generated functions filter mismatching requests thus help with writing more self-explanatory request routing configurations.
-
-::: tip  
-Users with administrator role always pass any generated policy.  
-:::
-
-## Methods
-
-### hasRole()
-
-**Signature:** `hasRole( roles ): Hitchy.Core.RequestPolicyHandler`
-
-Generates request policy handler testing if a provided request's user is associated with one of the roles listed here. If request's user is associated with either role, the request processing is continued. Otherwise this policy responds with HTTP status code 403.
-
-Argument `roles` is
-
-* a string naming single role without any prefix or suffix or
-* an array of such strings.
-
-Returned function can be injected into runtime configuration for policies like this:
-
-```javascript
-module.exports = function() {
-    const { hasRole } = this.runtime.service.AuthorizationPolicyGenerator;
-    
-    return {
-        policies: {
-            "GET /api/premium": hasRole( "customer" ),
-            "GET /api/public": hasRole( [ "guest", "customer", "manager" ] ),
-        },
-    };
-};
-```
-
-### mayAccess( resource )
-
-**Signature:** `mayAccess( resource ): Hitchy.Core.RequestPolicyHandler`
-
-Generates request policy handler testing if a provided request's user is authorized to access any of the listed resources.
-
-Argument `resource` is
-
-* a string naming single resource or
-* an array of such resource names.
-
-Resulting handler can be injected into runtime configuration for policies like this:
-
-```javascript
-module.exports = function() {
-    const { mayAccess } = this.runtime.service.AuthorizationPolicyGenerator;
-    
-    return {
-        policies: {
-            "GET /api/premium": mayAccess( "plan.premium" ),
-            "GET /api/export": mayAccess( [ "plan.premium", "level.manager" ] ),
-        },
-    };
-};
-```

package/docs/api/service/authorization-tree.md

@@ -1,123 +0,0 @@
----
-prev: auth-manager.md
-next: authorization-node.md
----
-
-# AuthorizationTree
-
-This service implements class for tracking state of authorizations by means of granting or revoking access on named resources to/from users and role in a tree of [nodes](authorization-node.md). 
-
-In opposition to other services, this service is primarily a class which could be instantiated to describe a tree of authorization settings. It complies with existing services by [exposing a single instance as current tree of authorizations](#current), only.
-
-On starting application, this plugin is processing runtime configuration and local database for existing [authorization rules](../model/authorization-rule.md) building this tree in runtime memory for improved authorizations testing during request routing.
-
-## Properties
-
-### current
-
-This static property exposes single instance of current runtime representing the tree which has been set up by the plugin on starting application. This instance is implicitly updated by some actions affecting existing users, roles and authorization rules in local database.
-
-## Methods
-
-::: warning Instance methods  
-In opposition to other services, these methods are instance methods and thus are available e.g. on current tree, only.
-
-Instead of writing
-
-```javascript
-AuthorizationTree.addRule( rule )
-```
-
-you must write
-
-```javascript
-AuthorizationTree.current.addRule( rule )
-```
-:::
-
-### selectNode()
-
-**Signature:** `selectNode( selector, [ addIfMissing ], [ callback ] ): AuthorizationNode`
-
-This method descends into tree of nodes according to provided selector which is a resource's hierarchical name. If optional argument `addIfMissing` is `true`, any missing node is created on the fly assuring to always return a node representing selected resource.
-
-When providing callback in third argument, it is invoked on every existing (or implicitly created) node passed while descending into tree. The callback is invoked with 
-
-* current node, 
-* segment of selector a.k.a. resource name selecting this node in context of its parent, 
-* the segment's index in list of segments extracted from selector and
-* the full list of segments to be processed.
-
-The callback may return `false` to prematurely stop descending into tree.
-
-### clear()
-
-**Signature:** `clear(): AuthorizationTree`
-
-Clears tree by recursive deleting all its nodes. Returns tree itself for daisy-chaining calls.
-
-### addRule()
-
-**Signature:** `addRule( rule ): AuthorizationTree`
-
-Adjusts tree to represent provided [authorization rule](../model/authorization-rule.md). The provided rule may be instance of model [AuthorizationRule](../model/authorization-rule.md) or any other object resembling authorization rules by providing equivalent properties `selector`, `user`, `role` and `accept`.
-
-::: warning Note  
-Adding a rule doesn't imply to eventually grant access on some resource.  
-:::
-
-The method returns current tree for daisy-chaining calls.
-
-### removeRule()
-
-**Signature:** `removeRule( rule ): AuthorizationTree`
-
-This is the counterpart of [addRule()](#addrule). It adjusts tree to stop representing provided [authorization rule](../model/authorization-rule.md).
-
-::: warning Note  
-Removing a rule doesn't imply to eventually revoke access on some resource. It's reverting some previous change of tree, only.  
-:::
-
-::: warning Note  
-When adding a rule multiple times, it will be counted as such. You need to remove the rule as many times as it has been added before to actually remove it from tree.    
-:::
-
-The method returns current tree for daisy-chaining calls.
-
-### isAuthorized()
-
-**Signature:** `isAuthorized( selector, user, role, [ acceptByDefault ] ): boolean`
-
-This method checks, whether tree is currently granting or revoking access on a selected resource to/from user and/or role.
-
-::: warning Note  
-Access on a resource can be granted or revoked on particular resource. It might be granted/revoked on a superordinated resource, too.  
-:::
-
-The method takes a user or a role and checks if it is affected by any rule tracked for either node of tree which is passed on descending into tree according to provided selector. If there is no rule on any passed node affecting provided user or role, the default provided in optional fourth argument is used, which is false by default, thus preventing access by default.
-
-The method returns `true`, if access is granted, and `false` otherwise.
-
-### gc()
-
-**Signature:** `gc( [ force ] ): void`
-
-This method is meant to search tree for sparse threads and remove them if necessary. It is implicitly invoked each time a rule is removed with [removeRule()](#removerule), though garbage collection is triggered after seeing a certain number of calls, only. You can enforce a garbage collection by setting optional argument `force`.
-
-### loadFromDatabase()
-
-**Signature:** `async loadFromDatabase(): void`
-
-This method is reading all existing instances of [AuthorizationRule](../model/authorization-rule.md) from local database invoking [addRule()](#addrule) on every found rule.
-
-### loadFromConfiguration()
-
-**Signature:** `loadFromConfiguration( configuration ): void`
-
-The method searches provided configuration for describing rules in one of several supported formats and adds them to current tree. The provided configuration can be
-
-* an object mapping resource names into
-  * a string naming user or role granted or revoked access on named resource,
-  * a string naming multiple users and/or roles separated by comma with each granted or revoked access on resource,
-  * an array of either sort of string or
-  * an object providing `users` and `roles` or `grants` and `revokes` in separate properties each supporting a format similar to the one of strings described above and another map of relative resource names into rules for resources subordinated to current one.

package/docs/api/service/readme.md

@@ -1,15 +0,0 @@
----
-prev: ../
-next: false
----
-
-# Services
-
-Select one of the provided [services](https://core.hitchy.org/internals/components.html#services):
-
-* [AuthenticationPassport](authentication-passport.md)
-* [AuthenticationStrategies](authentication-strategies.md)
-* [AuthManager](auth-manager.md)
-* [AuthorizationTree](authorization-tree.md)
-* [AuthorizationNode](authorization-node.md)
-* [AuthorizationPolicyGenerator](authorization-policy-generator.md)

package/docs/guides/getting-started.md

@@ -1,69 +0,0 @@
----
-prev: ../guides/
-next: openid-connect.md
----
-
-# Quick Start
-
-This document is a step-by-step guide for basically setting up [Hitchy](https://core.hitchy.org/) with support for authentication and authorization using this plugin.
-
-## Setup Project
-
-Create a folder for your application and enter it:
-
-```bash
-mkdir my-new-app
-cd my-new-app
-```
-
-Initialize your application's package management so dependencies are tracked:
-
-```bash
-npm init -y
-```
-
-Install [@hitchy/core](https://www.npmjs.com/package/@hitchy/core) and [@hitchy/plugin-auth](https://www.npmjs.com/package/@hitchy/plugin-auth) as dependencies:
-
-```bash
-npm install @hitchy/core @hitchy/plugin-auth
-```
-
-:::tip
-Plugin [@hitchy/plugin-auth](https://www.npmjs.com/package/@hitchy/plugin-auth) is 
-implicitly fetching [@hitchy/plugin-odem](https://www.npmjs.com/package/@hitchy/plugin-odem), [@hitchy/plugin-session](https://www.npmjs.com/package/@hitchy/plugin-session) and [@hitchy/plugin-cookies](https://www.npmjs.com/package/@hitchy/plugin-cookies) as dependencies. 
-:::
-
-## Start Hitchy
-
-At this point Hitchy is ready. Thus, start it with:
-
-```bash
-hitchy start
-```
-
-:::warning Hitchy not found?
-If Hitchy isn't found this might be due to issues with your Node.js and npm setup. In most cases using **npx** solves this issue for now:
-
-```bash
-npx hitchy start
-```
-:::
-
-Keep it running while trying out next.
-
-:::tip
-Whenever you want to stop Hitchy press Ctrl+C to gracefully shut it down.
-:::
-
-## Try It Out
-
-The plugin [injects special endpoints for managing a user's authentication](../api/routing.md) by default. You should be able to authenticate with a request like this:
-
-```http request
-POST /api/auth/login HTTP/1.0
-Content-Type: application/x-www-form-urlencoded
-
-username=admin&password=nimda
-```
-
-This works due to the default [configuration](../api/config.md#config-auth-admin) for implicitly [setting up administrator account](/api/service/auth-manager.md#createadminifmissing) on application start.