@toa.io/extensions.exposition 0.9.0-canary.2 → 0.20.0-alpha.0

package/cucumber.js

@@ -0,0 +1,9 @@
+module.exports = {
+  default: {
+    paths: ['features/**/*.feature'],
+    requireModule: ['ts-node/register'],
+    require: ['./features/**/*.ts'],
+    publishQuiet: true,
+    failFast: true
+  }
+}

package/documentation/access.md

@@ -0,0 +1,256 @@
+# Access authorization
+
+> The Authorization is intrinsically linked with the [Authentication](./identity.md).
+
+<a href="">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.assets/ia3-dark.jpg">
+    <img alt="IA3" width="600" height="507" src="./.assets/ia3-light.jpg">
+  </picture>
+</a>
+
+## Directives
+
+The Authorization is implemented as a set of [RTD Directives](tree.md#directives).
+
+Directives are executed in a predetermined order until one of them grants access to a resource. If
+none of the
+directives grants access, then the Authorization interrupts request processing and responds with an
+authorization error.
+
+> The Authorization directive provider is named `authorization`,
+> so the full names of the directives are `authorization:{directive}`.
+
+### `anonymous`
+
+Grants access if its value is `true` and no credentials were provided[^1].
+
+[^1]: Credentials in the request make the
+response [non-chachable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+
+### `id`
+
+Grants access if resolved Identity matches the value of the URL path segment placeholder named after
+the directive's value.
+
+#### Example
+
+Given the Route declaration and corresponding HTTP request:
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /users/:user-id:
+    id: "user-id"
+```
+
+```http
+GET /users/87480f2bd88048518c529d7957475ecd/
+Authorization: ...
+```
+
+For this request access will be granted if the resolved Identity value
+is `87480f2bd88048518c529d7957475ecd`.
+
+### `role`
+
+Grants access if resolved Identity has a role matching the directive's value or one of its values.
+
+#### Example
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /code:
+    role: [developer, reviewer]
+```
+
+Access will be granted if the resolved Identity has a role that matches `developer` or `reviewer`.
+
+Read [Roles](#roles) section for more details.
+
+### `rule`
+
+The Rule is a collection of authorization directives. It allows access only if all the specified
+directives grant
+access. The value of the `rule` directive can be a single Rule or a list of Rules.
+
+#### Example
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /commits/:user-id:
+    rule:
+      id: user-id
+      role: developer
+```
+
+Access will be granted if an Identity matches a `user-id` placeholder and has a Role of `developer`.
+
+## Roles
+
+Role values are strings that can be assigned to an Identity and used for matching with values of
+the [`role` directive](#role).
+
+### Hierarchy
+
+Role values are alphanumeric tokens separated by a colon (`:`).
+Each token defines a Role Scope, forming a hierarchy.
+A Role matches the value of the `rule` directive if that Role has the specified Scope in a
+directive.
+
+#### Example
+
+```yaml
+# context.toa.yaml
+
+/exposition:
+  /commits/:user-id:
+    role: developer:senior
+```
+
+The example above defines a `role` directive with the specified `developer:senior` Role Scope.
+This directive matches the roles `developer:senior` and `developer`,
+but it **does not** match the Role `developer:senior:javascript`.
+In other words, the Identity must have a specified or more general Role.
+
+<a href="https://miro.com/app/board/uXjVOoy0ImU=/?moveToWidget=3458764556008550471&cot=14">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset=".assets/role-scopes-dark.jpg">
+    <img alt="IA3" width="600" height="425" src=".assets/role-scopes-light.jpg">
+  </picture>
+</a>
+
+
+> The root-level Role Scope `system` is preserved and cannot be used with the `role` directives.
+
+See also [role management resources](components.md#roles).
+
+#### Authorization Directives
+
+```yaml
+/identity/roles/:id:
+  role: system:roles
+````
+
+## Policies
+
+Component Resource branches cannot have authorization directives.
+Instead, they must declare Authorization Policies using `policy` directive to
+be attached in the Context to a Resource Tree as a set of Authorization Directives
+using `attachment` directive.
+
+This restriction provides a separation of concerns, allowing components to be reused in different
+Contexts with varying
+access rules.
+
+```yaml
+# manifest.toa.yaml
+
+name: posts
+
+exposition:
+  /:user-id:
+    GET:
+      endpoint: observe
+      policy: read:list
+    POST:
+      endpoint: transit
+      policy: post:submit
+    /:post-id:
+      GET:
+        endpoint: observe
+        policy: read:post
+      PUT:
+        endpoint: assign
+        policy: post:edit
+```
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /posts:
+    attachment:
+      read:
+        anonymous: true
+      post:
+        id: user-id
+      post:edit:
+        role: app:posts:editor
+```
+
+Policy values as well as [Role](#roles) values define hierarchical Policy Scopes.
+
+In the example above:
+
+- an Attachment `read` attaches Directive `anonymous: true` to both `read:list` and `read:post`
+  Policy Scopes.
+  This means that a list of posts and each post can be accessed without authorization.
+- an Attachment `post` attaches Directive `id: user-id` to both `post:submit` and `post:edit` Policy
+  Scopes.
+  This means that an Identity can submit and edit their own posts.
+- an Attachment `post:edit` attaches Directive `role: app:posts:editor` to `post:edit` Policy Scope.
+  This means that an identity with the role scope `app:posts:editor` can edit posts by any author,
+  in addition to the fact that the author themselves can do this thanks to the previous Attachment.
+
+### Nesting
+
+Policies are namespace-scoped, meaning they can be attached to any Route under the
+corresponding `/{namespace}` prefix.
+
+Attachment is applied to the node where it is declared, as well as its nested nodes.
+Directives of the Attachment are applied to the node where the attached Policies are declared, as
+well as their nested nodes.
+
+Here's an example of how this works:
+
+```yaml
+# manifest.toa.yaml
+
+name: posts
+
+exposition:
+  /:user-id:
+    GET:
+      endpoint: observe
+      policy: read
+  /:user-id/:post-id:
+    GET:
+      endpoint: observe
+      policy: read
+```
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /posts:
+    /:user-id:
+      attachment:
+        read:
+          anonymous: true
+    /:user-id/:post-id:
+      attachment:
+        read:
+          role: reader
+```
+
+In the example above, the same Policy `read` is attached to two Routes with different Directives.
+
+The following example demonstrates the attachment of the `read` Policy to both Routes with the same
+Directive:
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /posts:
+    attachment:
+      read:
+        anonymous: true
+```

package/documentation/components.md

@@ -0,0 +1,276 @@
+# Components and resources
+
+Exposition comes with a set of components that run within the same process. These components are
+configured in the same
+way as if they were a part of the Context. Resources exposed by the components
+are [isolated](tree.md#directives).
+
+## Basic credentials
+
+The `identity.basic` component stores basic credentials.
+
+### Password hashing
+
+Passwords are hashed using the [bcrypt](https://github.com/dcodeIO/bcrypt.js) algorithm with salt
+and pepper.
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    rounds: 10 # salt rounds
+    peper: ''  # hashing pepper
+```
+
+### Credentials constraints
+
+Credential constraints are defined using a set of regular expressions (values must match all of
+them).
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    username:
+      - ^\S{1,16}$
+    password:
+      - ^\S{8,32}$
+```
+
+> Values in the example above are the default values.
+
+### Principal
+
+When an application is deployed for the first time, there are no credentials, and therefore, there
+is no Identity that
+could have a Role to manage Roles of other Identities.
+
+This issue is addressed by using the `principal` key in the configuration:
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    principal: root
+```
+
+The value of the `principal` key corresponds to the `username` of the basic credentials. Once these
+credentials are
+created, the associated Identity will be assigned the `system` Role.
+
+Once created, the username of the principal cannot be modified.
+
+### Resources
+
+#### `/identity/basic/`
+
+<code>POST</code> Create new Identity with Basic credentials. Request body is as follows:
+
+```yaml
+username: string
+password: string
+```
+
+Access is [anonymous](access.md#anonymous).
+
+#### `/identity/basic/:id/`
+
+> `:id` placeholder refers to an Identity.
+
+<code>PUT</code> Update basic credentials. Request body is as follows:
+
+```yaml
+username?: string
+password?: string
+```
+
+Access requires basic credentials of the modified Identity or `system:identity:basic` role.
+
+## Stateless tokens
+
+The `identity.tokens` component manages statless authentication tokens.
+
+These tokens carry the information required to authenticate the Identity and authorize access.
+
+### Issuing tokens
+
+The new token is issued each time the request is made:
+
+1. Using authentication scheme other than `Token`.
+2. Using `Token` authentication scheme with an [obsolete token](#token-rotation).
+
+### Token encryption
+
+Issued tokens are encrypted
+with [PASETO V3 encryption](https://github.com/panva/paseto/blob/main/docs/README.md#v3encryptpayload-key-options)
+using the `key0` configuration value as a secret.
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    key0: $TOKEN_ENCRYPTION_KEY
+```
+
+The `key0` configuration value is required.
+
+> Valid secret key may be generated using the [`toa key` command](/runtime/cli/readme.md#key).
+
+### Token rotation
+
+Issued tokens are valid for a `lifetime` period defined in the configuration. After the `refresh`
+period, the token is
+considered obsolete (yet still valid), and a new token is [issued](#issuing-tokens) unless the
+provided one has
+been [revoked](#token-revocation).
+
+This essentially means that if the client uses the token at least once every `lifetime` period, it
+will always have a
+valid token to authenticate with. Also, token revocation or changing roles of an Identity will take
+effect once
+the `refresh` period of the currently issued tokens has expired.
+
+Adjusting these two values is a delicate trade-off between security, performance and client
+convinience.
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    lifetime: 2592000 # seconds, 30 days
+    refresh: 600      # seconds, 10 minutes
+```
+
+> Values in the example above are the default values.
+
+### Token revocation
+
+All currently issued tokens of an Identity are revoked when:
+
+1. Basic credentials associated with the Identity are [modified](#identitybasicid).
+2. Identity is [banned](#banned-identities).
+
+Token revocation takes effect once the `refresh` period of the currently issued tokens has expired.
+
+### Secret rotation
+
+Tokens are always encrypted using the `key0` configuration value, and they will be decrypted by
+attempting both
+the `key0` and `key1` values in order.
+
+`key0` is considered the "current key," and `key1` is considered the "previous key."
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
+    key1: $TOKEN_ENCRYPTION_KEY_2023Q2
+```
+
+Secret rotation is performed by adding a new key as the `key0` value and moving the existing `key0`
+to the `key1` value.
+
+When rolling out the new secret key, there will be a period of time when the new key is deployed to
+some Exposition
+instances. During this time, these instances will start using the new key to encrypt tokens, while
+other instances will
+continue using the current key and will not be able to decrypt tokens encrypted with the new key.
+
+To address this issue, the `key1` configuration value may be used as a "transient key."
+
+The secret rotation is a 2-step process:
+
+> The process **must not** be performed earlier than the `lifetime` period since the last rotation,
+> as it may invalidate
+> tokens before they expire. Therefore, it is guaranteed that there are no valid tokens issued with
+> the current `key1`
+> value.
+
+1. Deploy the new secret key to all Exposition instances as `key1`. This enables all instances to
+   decrypt tokens
+   encrypted with the new key while still using the current key for encryption.
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
+    key1: $TOKEN_ENCRYPTION_KEY_2023Q4
+```
+
+2. Move the new secret key from `key1` to `key0`, and move the current key from `key0` to `key1`.
+   During this rollout,
+   all instances can decrypt tokens encrypted with both the new key and the current key.
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.basic:
+    key0: $TOKEN_ENCRYPTION_KEY_2023Q4
+    key1: $TOKEN_ENCRYPTION_KEY_2023Q3
+```
+
+## Roles
+
+The `identity.roles` component manages roles of an Identity used by [access authorization](access.md#role).
+
+### Role resources
+
+#### `/identity/roles/:id/`
+
+`GET` Get roles of an Identity.
+
+Access requires credentials of the Identity or `system:identity:roles` role.
+
+`POST` Add a role to an Identity. Request body is as follows:
+
+```yaml
+role: string
+```
+
+Access requires `system:identity:roles` role.
+
+## Banned Identities
+
+The `identity.bans` component manages banned identities.
+A banned identity will fail to authenticate with any associated credentials (except [tokens](#stateless-tokens) within
+the `refresh` period).
+
+```http
+PUT /identity/bans/:id/
+authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
+content-type: application/yaml
+
+banned: true
+```
+
+Access requires `system:identity:bans` role.
+
+## Authentication echo
+
+Exposition implements a predefined resource `/identity/` with the `GET` method, which returns the
+Identity resolved by the provided credentials.
+
+```http
+GET /identity/
+authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
+accept: application/yaml
+```
+
+```
+200 OK
+
+id: fc8e66ddd51d45eea89602c9dd38a542
+roles:
+  - developer
+  - system:identity:roles
+```

package/documentation/identity.md

@@ -0,0 +1,156 @@
+# Identity
+
+Identity is the fundamental entity within an authentication system that represents the **unique
+identifier** of an
+individual, organization, application or device.
+
+In order to prove its Identity, the request originator must provide a valid _credentials_ that are
+associated with that
+Identity.
+
+Identity is intrinsically linked to credentials, as an Identity is established only when the first
+set of credentials
+for that Identity is created.
+In other words, the creation of credentials marks the inception of an Identity.
+Once the last credentials are removed from the Identity, it ceases to exist.
+Without credentials, there is no basis for defining or asserting an Identity.
+
+## Authentication
+
+The Authenticaiton system resolves provided credentials to an Identity using one of the supported
+authentication
+schemes.
+
+The Authentication is request-agnostic, meaning it does not depend on the specific URL being
+requested or the content of
+the request body.
+The only information it handles is the value of the `Authorization` header.
+
+> Except for its own [management resources](#persistent-credentials).
+
+If the provided credentials are not valid or not associated with an Identity, then Authentication
+interrupts request
+processing and responds with an authentication error.
+
+### Basic scheme
+
+Classic username/password pair. See [RFC7617](https://datatracker.ietf.org/doc/html/rfc7617).
+
+```http
+Authorization: Basic aGVsbG86d29ybGQK
+```
+
+See [`identity.basic` component](components.md#basic-credentials).
+
+### Token scheme
+
+Tokens issued by the Authentication system. These tokens are [PASETO](https://paseto.io).
+
+```http
+Authrization: Token v4.local.eyJzdWIiOiJqb2hu...
+```
+
+The `Token` is the **primary** authentication scheme.
+If request originators use an alternative authentication scheme, they will receive a response
+containing `Token`
+credentials and will be required to switch to the `Token` scheme for any subsequent requests.
+Continued use of other authentication schemes will result in temporary blocking of requests.
+
+See [`identity.tokens` component](components.md#stateless-tokens).
+
+### Bearer scheme
+
+OpenID tokens issued by trusted providers.
+For more information, refer
+to [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html),
+[RFC6750](https://datatracker.ietf.org/doc/html/rfc6750).
+
+```http
+Authorization: Bearer eyJhbGciOiJIUzI1...
+```
+
+Trusted providers are specified using the `idenity.trust` property within the Exposition annotation.
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  identity:
+    trust:
+      - https://accounts.google.com
+      - https://appleid.apple.com
+```
+
+The example above demonstrates the default list of trusted providers.
+
+## Identity inception
+
+The simplest way to establish a relationship between an Identity and an entity representing a user
+is to synchronize their identifiers.
+
+This can be achieved by using the `auth:incept` directive as follows:
+
+```yaml
+# manifest.toa.yaml
+name: users
+
+entity:
+  schema:
+    name: string
+
+exposition:
+  /:
+    POST:
+      incept: id
+      endpoint: transit
+```
+
+The value of the `auth:incept` directive refers to the name of the response property that will be
+returned by the `POST` operation, containing the created entity identifier.
+
+A request with Identity inception must contain (non-existent) credentials that will be associated
+with the created Identity.
+
+```http
+POST /users/
+authorization: Basic dXNlcjpwYXNz
+accept: application/yaml
+content-type: application/yaml
+
+name: John
+```
+
+```
+201 Created
+content-type: application/yaml
+
+id: 2428c31ecb6e4a51a24ef52f0c4181b9
+```
+
+As a result of processing the above request, the provided Basic credentials associated with the
+Identity `2428c31ecb6e4a51a24ef52f0c4181b9` are created.
+
+## FAQ
+
+<dl>
+<dt>How can I log in a user?</dt>
+<dd>
+Technically speaking, since the Authentication is request-agnostic, user credentials
+can be sent with any request.
+
+However, it is most likely that a request originator will need to obtain an Identity value for
+subsequent requests.
+For this reason, it is recommended to make a `GET /identity/` request.
+</dd>
+<dt>How can I log out a user?</dt>
+<dd>Delete <code>Token</code> credentials from the device.</dd>
+<dt>Where are the sessions?</dt>
+<dd>
+The Authentication is stateless, meaning it does not store any information between
+requests except for persistent credentials.</dd>
+<dt>How can I pass the Identity to an operation call?</dt>
+<dd>
+This is not possible. Refer to the Resource Design Guidelines for more information.
+<a href="https://github.com/toa-io/toa/issues/353">#353</a>
+</dd>
+</dl>