@hitchy/plugin-auth 0.3.4 → 0.3.6

package/docs/.vuepress/config.js

@@ -1,55 +0,0 @@
-/**
- * (c) 2021 cepharum GmbH, Berlin, http://cepharum.de
- *
- * The MIT License (MIT)
- *
- * Copyright (c) 2021 cepharum GmbH
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- *
- * @author: cepharum
- */
-
-module.exports = {
-	evergreen: true,
-	base: "/",
-	dest: "public",
-	title: "Hitchy Auth Manual",
-	themeConfig: {
-		displayAllHeaders: true,
-		sidebar: "auto",
-		repo: "https://gitlab.com/hitchy/plugin-auth",
-		repoLabel: "Contribute!",
-		nav: [
-			{ text: "Home", link: "/" },
-			{ text: "Guides", link: "/guides/" },
-			{ text: "API", link: "/api/" },
-			{ text: "Hitchy", items: [
-					{ text: "Core", link: "https://core.hitchy.org/" },
-					{ text: "Plugins", items: [
-							{ text: "Odem", link: "https://odem.hitchy.org/" },
-							{ text: "Auth", link: "/" },
-						] },
-					{ text: "Tools", items: [
-							{ text: "SDT", link: "https://sdt.hitchy.org/" },
-						] }
-				] },
-		],
-	},
-};

package/docs/.vuepress/styles/palette.styl

@@ -1,4 +0,0 @@
-$accentColor = #c30045
-$textColor = #2c3e50
-$borderColor = #eaecef
-$codeBgColor = #282c34

package/docs/api/config.md

@@ -1,180 +0,0 @@
----
-prev: /api/service/
-next: routing.md
----
-
-# Runtime Configuration
-
-This plugin's runtime configuration is expected in section `auth` of your application's configuration. When complying with suggested filesystem layout for a Hitchy application, there should be a file **config/auth.js** in your application exposing this section similar to this:
-
-```javascript
-module.exports = {
-	auth: {
-		...
-	},
-};
-```
-
-The following parameters are supported there:
-
-## config.auth.prefix
-
-This optional string controls shared prefix of routes set up implicitly for providing basic authentication support. Its default is `/api/auth` resulting in routes `/api/auth/login`, `/api/auth/current` etc.
-
-Implicit routing setup can be disabled on providing boolean `false` as prefix here.
-
-## config.auth.admin
-
-Provides name and/or password of admin user to create initially when no user
-with administration privileges has been found in local database. This optional parameter
-is an object consisting of properties 
-
-* **role** selecting name of role granting full access to any associated user (default: `admin`),
-* **name** selecting name of user to create on start of application if there is no user associated with that role (default: `admin`) and
-* **password** providing password of that user to be created in clear text (default: `nimda`).
-
-```javascript
-module.exports = {
-	auth: {
-		admin: {
-			name: "jane.doe",
-			password: "my5ecr3t"
-		},
-	},
-};
-```
-
-:::tip  
-Environment variables **HITCHY_ADMIN_NAME**, **HITCHY_ADMIN_PASSWORD** and **HITCHY_ADMIN_ROLE** can be used to override any configuration provided here to e.g. support container-driven setups.   
-:::
-
-## config.auth.roles
-
-Lists role names to create on boot if missing in local database. This list is empty by default.
-
-```javascript
-module.exports = {
-	auth: {
-		roles: [ "guest", "customer", "manager" ],
-	},
-};
-```
-
-## config.auth.authorizations
-
-This section grants or revokes access on named resources to/from users and/or roles. These _authorizations_ are loaded on application start before reading custom rules from local database. 
-
-:::tip  
-Authorizations read from local database may replace authorizations given in runtime configuration.  
-:::
-
-It is an object-style hierarchy mapping resource names into names of users and/or roles access on selected resource is granted to or revoked from.
-
-```javascript
-module.exports = {
-    auth: {
-        authorizations: {
-            "backup": "@managers",
-            "backup.export": "-@noobs",
-            "backup.import": "+@admins, -john.doe"
-        },
-    },
-};
-```
-
-Lists of users and roles can be provided as strings using comma for separation as illustrated above. Actual array are supported, too:
-
-```javascript
-module.exports = {
-    auth: {
-        authorizations: {
-            "backup": [ "@managers" ],
-            "backup.export": [ "-@noobs" ],
-            "backup.import": [ "+@admins", "-john.doe" ],
-        },
-    },
-};
-```
-
-Names of resources can be grouped by shared prefixes:
-
-```javascript
-module.exports = {
-    auth: {
-        authorizations: {
-            backup: {
-                people: [ "@managers" ],
-                sub: {
-                    export: [ "-@noobs" ],
-                    import: [ "+@admins", "-john.doe" ],
-                },
-            }
-        },
-    },
-};
-```
-
-Resource names concatenate path segments separated by period from each other. Common prefixes can be stripped off when nesting authorizations as demonstrated before. Nesting requires provision of users and roles moved into separate property named `people`.
-
-For improved readability, `people` list may be replaced with separate lists for `users` and `roles` as well as with lists `grant` and `revoke` grouping authorizations accordingly:
-
-```javascript
-module.exports = {
-    auth: {
-        authorizations: {
-            backup: {
-                grant: [ "@managers" ],
-                sub: {
-                    export: {
-                        revoke: [ "@noobs" ]
-                    },
-                    import: {
-                        users: [ "-john.doe" ],
-                        roles: [ "+admins" ]
-                    },
-                },
-            }
-        },
-    },
-};
-```
-
-## config.auth.strategies
-
-This optional object maps unique names of supported authentication strategies into related implementations for use with [Passport](https://www.passportjs.org/).
-
-```javascript
-const { OAuthStrategy } = require( "passport-oauth" );
-
-module.export = {
-    auth: {
-        strategies: {
-            oauth: new OAuthStrategy( options, localUserSelectorFn ),
-        },
-    },
-};
-```
-
-Any strategy listed here will be picked up on [integrating Passport with Hitchy's request routing](service/authentication-passport.md#integratewithhitchy). When implementing [policy-based](policy/authentication.md#login) authenticating requests, name of either strategy must be picked in request's parameter `strategy`:
-
-```javascript
-module.exports = function() {
-    const { login } = this.runtime.policy.Authentication;
-    
-    return {
-        routes: {
-            "GET /login/:strategy": login()
-        }
-    };
-};
-```
-
-If request parameter is missing, [configured default strategy](#config-auth-defaultstrategy) is used.
-
-Provide a custom local strategy in property `local` here to prevent built-in [local strategy](service/authentication-strategies.md#generatelocal) from being used. Omit this configuration to rely on that built-in local strategy for authenticating users against local database, only.
-
-## config.auth.defaultStrategy
-
-This optional string names strategy to use by default. Defaults to `local` itself. 
-
-Any custom strategy named here must be [set up](#config-auth-strategies) properly.

package/docs/api/controller/readme.md

@@ -1,10 +0,0 @@
----
-prev: ../
-next: false
----
-
-# Controllers
-
-Select one of the provided [controllers](https://core.hitchy.org/internals/components.html#controllers):
-
-* [User](user.md)

package/docs/api/controller/user.md

@@ -1,44 +0,0 @@
----
-prev: ../controller/
-next: ../policy/
----
-
-# UserController
-
-This controller provides request handlers basically suitable for authenticating as a user. However, neither handler is actually triggering a user's authentication or its logout, but provides suitable responses following some [additionally required policies](../policy/user.md).
-
-Any of the following request handlers can be used as target in your application's routing declarations in [section `routes`](https://core.hitchy.org/api/hitchy.html#config-routes) of [runtime configuration](https://core.hitchy.org/api/hitchy.html#configuration):
-
-```json
-{
-    "routes": {
-        "/login": "user.authenticate",
-        "/logout": "user.unauthenticate"
-    }
-}
-```
-
-## authenticate()
-
-This handler is responding on successful authentication. 
-
-It relies on policy [authentication.login](../policy/authentication.md#login) being processed, first. 
-
-## unauthenticate()
-
-This handler is responding on successfully dropping any authentication. 
-
-It relies on policy  [authentication.logout](../policy/authentication.md#logout) being processed, first. 
-
-## changePassword()
-
-This handler is responding on successfully changing user's token. 
-
-It relies on policy [user.changePassword](../policy/user.md#changepassword) being processed, first. 
-
-## getCurrent()
-
-This handler is delivering additional information on recently authenticated user. See related [routing description for response examples](../routing.md#get-api-auth-current).
-
-It doesn't depend on any additional policy being processed first. 
-

package/docs/api/model/authorization-rule.md

@@ -1,38 +0,0 @@
----
-prev: user-to-role.md
-next: /api/service/
----
-
-# AuthorizationRule
-
-An AuthorizationRule is a rule granting access on a [named resource](../../introduction.md#resources) to a [user](user.md) or [role](role.md) or rejecting access on that resource from a user or role. It is an essential part of authorization management.
-
-## Properties
-
-### selector
-
-This mandatory [string](https://odem.hitchy.org/guides/defining-models.html#strings) property selects a [resource](../../introduction.md#resources) (see the [example](../../introduction.md#an-example)) by its name.
-
-### user
-
-This optional [UUID](https://odem.hitchy.org/guides/defining-models.html#uuids) selects a single user which is granted access to selected resource.
-
-::: warning  
-A rule must select at least a user or a role. It may select both.  
-:::
-
-### role
-
-This optional [UUID](https://odem.hitchy.org/guides/defining-models.html#uuids) selects a single user which is granted access to selected resource.
-
-::: warning  
-A rule must select at least a user or a role. It may select both. 
-:::
-
-### accept 
-
-This [boolean](https://odem.hitchy.org/guides/defining-models.html#booleans) property indicates, whether rule is granting access to selected resource (`true`) or revoking it (`false`). The default value is `true`.
-
-## Methods
-
-AuthenticationRules don't have custom methods apart from [basic ones](https://odem.hitchy.org/api/model.html).

package/docs/api/model/readme.md

@@ -1,13 +0,0 @@
----
-prev: ../
-next: false
----
-
-# Models
-
-Select one of the provided [models](https://core.hitchy.org/internals/components.html#models):
-
-* [User](user.md)
-* [Role](role.md)
-* [UserToRole](user-to-role.md)
-* [AuthorizationRule](authorization-rule.md)

package/docs/api/model/role.md

@@ -1,22 +0,0 @@
----
-prev: user.md
-next: user-to-role.md
----
-
-# Role
-
-This model represents a single _role_ in local database. A role can be applied to multiple users. Authorizations can be granted to or revoked from a role instead of a single user, thus affecting all users the role has been applied to.
-
-It is part of access control management at runtime.
-
-## Properties
-
-These are the properties provided per role:
-
-### name
-
-For every role, this [string](https://odem.hitchy.org/guides/defining-models.html#strings) property is representing the role's unique name. It is used in authorization rules to grant access on a resource to a set of users or revoke it from them explicitly.
-
-## Methods
-
-Roles don't have custom methods apart from [basic ones](https://odem.hitchy.org/api/model.html).

package/docs/api/model/user-to-role.md

@@ -1,26 +0,0 @@
----
-prev: role.md
-next: authorization-rule.md
----
-
-# UserToRole
-
-Every instance of this model links an instance of [User model](user.md) with a instance of [Role model](role.md).
-
-This model is part of access control management at runtime.
-
-## Properties
-
-These are the properties provided per role:
-
-### user
-
-Provides [UUID](https://odem.hitchy.org/guides/defining-models.html#uuids) of user associated with a role.
-
-### user
-
-Provides [UUID](https://odem.hitchy.org/guides/defining-models.html#uuids) of role associated with a user.
-
-## Methods
-
-There no custom methods apart from [basic ones](https://odem.hitchy.org/api/model.html).

package/docs/api/model/user.md

@@ -1,50 +0,0 @@
----
-prev: ../model/
-next: role.md
----
-
-# User
-
-This model represents a single user in local database. It is meant to support access control management at runtime e.g. to have a user-customizable access control.
-
-## Properties
-
-These are the properties provided per user:
-
-### name
-
-The user's name is a required [string](https://odem.hitchy.org/guides/defining-models.html#strings) which is meant to be unique. It is used to pick a user for local authentication. Authorization rules are capable of addressing a user by name, too.
-
-### password
-
-This [string](https://odem.hitchy.org/guides/defining-models.html#strings) provides a salted one-way hash of user's password for local authentication or some other kind of token for use with a non-local strategy.
-
-Passwords for use with local authentication are implicitly hashed with [SCRYPT](https://de.wikipedia.org/wiki/Scrypt).
-
-### strategy
-
-Every user can be associated with a particular passport strategy to use for authentication. This [string](https://odem.hitchy.org/guides/defining-models.html#strings) property is picking a strategy by its name. Default strategy as configured is used in case this property is empty or unset.
-
-### strategyData
-
-This [string](https://odem.hitchy.org/guides/defining-models.html#strings) property is meant to provide custom data specific to selected strategy. It's format is specific to that strategy. It might be used to pick a remote service confirming the user's authentication or represent additional meta data on it.
-
-## Methods
-
-### hashPassword()
-
-**Signature:** `async hashPassword( cleartext, [ previous ] ): string`
-
-This asynchronous method derives salted hash from provided clear-text password. The second argument is optional. When provided, the salt is extracted from it instead of generating a fresh random salt. This is required for comparing password hashes. And it shouldn't be used for anything else. Using fresh salts whenever possible is essential to password security. 
-
-### setPassword()
-
-**Signature:** `async setPassword( password )`
-
-Changes password of user as provided in clear text. This is a helper updating hashed password in local instance. You still need to [save the record](https://odem.hitchy.org/api/model.html#instance-save) to persist the change.
-
-### verifyPassword()
-
-**Signature:** `async verifyPassword( password ): boolean`
-
-Compares this user's hashed password with a provided clear-text password by hashing the latter with the same salt extracted from the former and compare the hashes. The method is implicitly loading the record from persistent storage if required. It promises `true` if both hashes are identical and `false` otherwise.

package/docs/api/policy/authentication.md

@@ -1,44 +0,0 @@
----
-prev: ../policy/
-next: authorization.md
----
-
-# AuthenticationPolicy
-
-This class implements policy handlers for transparently processing requests for logging in and out by means of authenticating as a user relying on a [configured](../config.md#config-auth-strategies) [passport](https://www.passportjs.org/) [strategy](https://www.passportjs.org/packages/).
-
-These are the provided handlers:
-
-## initialize()
-
-This policy handler is basically integrating passport with a request's handling. It is unconditionally injected into every incoming request by default.
-
-The handler is adopting [passport's instructions for setting it up as a middleware](https://www.passportjs.org/docs/downloads/html/#middleware) to work in context of Hitchy framework.
-
-## login()
-
-Handles request for authentication via integrated passport's strategy as configured. 
-
-This handler is essential for [default route supported to authenticate a user](../routing.md#post-api-auth-login-strategy).
-
-::: tip Example  
-There is an example for how to use this policy in [section on configuring custom strategies](../config.md#config-auth-strategies).
-:::
-
-## logout()
-
-This handler is dropping any user currently authenticated in context of this request. 
-
-It is essential for [default route supported to drop user authentication](../routing.md#get-api-auth-logout).
-
-## mustBeAuthenticated()
-
-This handler responds with HTTP status 403 in case there is no authenticated user in context of current request. Use this policy if you want to reject all requests to a URL prefix unless some user has authenticated. 
-
-```json
-{
-    "policies": {
-        "/api/protected": [ "authentication.mustBeAuthenticated" ]
-    }
-}
-```

package/docs/api/policy/authorization.md

@@ -1,27 +0,0 @@
----
-prev: authentication.md
-next: user.md
----
-
-# AuthorizationPolicy
-
-This class provides policy handlers helping with common authorization tasks.
-
-## mustBeAdmin()
-
-This handler responds with HTTP status 403 in case there is no current user or any authenticated user isn't associated with the role configured to provide administrative privileges by means of granting access on all resources.
-
-::: tip   
-This policy handler can be combined with [authentication.mustBeAuthenticated](authentication.md#mustbeauthenticated) to deliver more useful response messages on requests completely lacking authentication.
-
-```json
-{
-    "policies": {
-        "/api/protected": [ 
-            "authentication.mustBeAuthenticated", 
-            "authorization.mustBeAdmin" 
-        ]
-    }
-}
-```
-:::

package/docs/api/policy/readme.md

@@ -1,12 +0,0 @@
----
-prev: ../
-next: false
----
-
-# Policies
-
-Select one of the provided [policies](https://core.hitchy.org/internals/components.html#policies):
-
-* [Authentication](authentication.md)
-* [Authorization](authorization.md)
-* [User](user.md)

package/docs/api/policy/user.md

@@ -1,22 +0,0 @@
----
-prev: authorization.md
-next: ../model/
----
-
-# UserPolicy
-
-This class provides policy handlers helping with common tasks related to some authenticated user.
-
-## mustBeMe()
-
-This handler tests if current request URL contains parameter named `uuid` matching current user's UUID. The request is rejected with HTTP status 403 **on mismatch**.
-
-## mustNotBeMe()
-
-This handler tests if current request URL contains parameter named `uuid` matching current user's UUID. The request is rejected with HTTP status 403 **on match**.
-
-## changePassword()
-
-This request is transparently processing request for changing any currently authenticated user's password. It requires provision of authenticated user's current password and the desired new password in request body.
-
-This policy handler is essential to [default route supporting change of a user's password](../routing.md#post-api-auth-password).

package/docs/api/readme.md

@@ -1,52 +0,0 @@
----
-prev: ../guides/
-next: false
----
-
-# API Reference
-
-## Components
-
-This plugin exposes the following [components](https://core.hitchy.org/internals/components.html) in context of your application:
-
-### Controllers
-
-The following [controlllers](https://core.hitchy.org/internals/components.html#controllers) are provided for implementing some default endpoints:
-
-* [User](controller/user.md)
-
-### Policies
-
-Several [policies](https://core.hitchy.org/internals/components.html#policies) are available for customizing authentication and authorization support in your application:
-
-* [Authentication](policy/authentication.md)
-* [Authorization](policy/authorization.md)
-* [User](policy/user.md)
-
-### Models
-
-These [models](https://core.hitchy.org/internals/components.html#models) are provided to manage access control at runtime:
-
-* [User](model/user.md)
-* [Role](model/role.md)
-* [UserToRole](model/user-to-role.md)
-* [AuthorizationRule](model/authorization-rule.md)
-
-### Services
-
-Commonly useful [services](https://core.hitchy.org/internals/components.html#services) regarding authentication and authorization are:
-
-* [AuthenticationPassport](service/authentication-passport.md)
-* [AuthenticationStrategies](service/authentication-strategies.md)
-* [AuthManager](service/auth-manager.md)
-* [AuthorizationNode](service/authorization-node.md)
-* [AuthorizationTree](service/authorization-tree.md)
-* [AuthorizationPolicyGenerator](service/authorization-policy-generator.md)
-
-## Configuration
-
-In addition to components listed above the plugin is processing some optionally available [runtime configuration](config.md).
-
-## Routing defaults
-
-Unless [disabled in runtime configuration](config.md#config-auth-prefix), this plugin is always setting up [routes providing basic user authentication](routing.md) to a client.