@toa.io/extensions.exposition 1.0.0-alpha.31 → 1.0.0-alpha.310

package/documentation/components.md

@@ -1,331 +0,0 @@
-# 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
-    pepper: '' # 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,128}$
-    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.
-
-## Identity federation (OpenID connect)
-
-The `identity.federation` component manages OpenID Connect federated identities.
-
-Both implicit identities creation and forced [identity inception](./identity.md) are supported
-as in case with basic credentials. `principal` is also working in the same way.
-
-The configuration schema alongside default values is described in
-the [component manifest](../components/identity.federation/manifest.toa.yaml).
-
-No federated tokens are accepted by default until at least one entry is added to the `trust`
-configuration.
-
-Toa supports either asymmetric RS256 or symmetric HS256 / HS384 / HS512 tokens with pre-shared
-secrets.
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.federation:
-    trust:
-      - iss: https://token.actions.githubusercontent.com
-        aud:
-          - https://github.com/tinovyatkin
-          - https://github.com/temich
-
-      - issuer: some.private.issuer
-        secrets:
-          HS256:
-            k1: <secret-to-be-used-for-hs256>
-```
-
-## Stateless tokens
-
-The `identity.tokens` component manages stateless 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).
-
-When the token is issued it is sent in the `authorization` response header and the `cache-control`
-is set to `no-store`.
-
-```http
-authorization: Token ...
-cache-control: no-store
-```
-
-### 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.tokens:
-    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
-convenience.
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.tokens:
-    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.tokens:
-    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.tokens:
-    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.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q4
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q3
-```
-
-### Token resources
-
-`/identity/tokens/`
-
-`POST` Issue a new token for the Identity. Request body is as follows:
-
-```yaml
-lifetime?: number # seconds
-```
-
-Providing a value of `0` will result in the token being issued with no expiration.
-However, it will still become invalid once the encryption key used is out
-of [rotation](#secret-rotation).
-
-## Roles
-
-The `identity.roles` component manages roles of an Identity used
-by [access authorization](access.md#role).
-
-### `/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
-```
-
-To assign arbitrary roles, the `system:identity:roles` role is required.
-
-An Identity having `system:identity:roles:delegation` role can delegate roles within its own
-Role Scopes (see [Role Hierarchies](access.md#hierarchies)).
-
-## 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
-comment: Bye bye
-```
-
-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

@@ -1,158 +0,0 @@
-# Identity
-
-Identity is the fundamental entity within an authentication system that represents the **unique
-identifier** of an individual, organization, application or device.
-
-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 Authentication 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](components.md).
-
-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 `identity.federation` property within the configuration
-annotation.
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.federation:
-    trust:
-      - iss: https://accounts.google.com
-        aud:
-          - <GOOGLE_CLIENT_ID>
-
-      - iss: https://appleid.apple.com
-
-      - iss: private.entity
-        secrets:
-          HS384:
-            key0: <THE-SECRET-STRING-FOR-HS384>
-            key1: <THE-SECRET-STRING-FOR-HS384> # selected by `kid` in the JWT header
-```
-
-## 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>

package/documentation/io.md

@@ -1,56 +0,0 @@
-# I/O restrictions
-
-The Exposition comes with `io` directives to control access to the operation's input and output
-properties.
-
-## `io:input`
-
-The `io:input` optional directive contains a list of properties that are allowed to be specified in
-the request body.
-
-```yaml
-POST:
-  endpoint: create
-  io:input: [name, location]
-```
-
-The list must be a valid subset of the operation's input properties.
-
-If `io:input` is specified and the request body is not an object, or contains properties that are
-not in the list, the request will be rejected with a `400` status code.
-
-> Therefore, `io:input` is only applicable to operations which input is an object or an
-> array of objects.
-
-## `io:output`
-
-The `io:output` mandatory directive contains a list of properties that are allowed to be included in
-the response body.
-
-```yaml
-GET:
-  endpoint: observe
-  io:output: [name, location]
-```
-
-When an operation does not return an object (e.g., a primitive or a stream), or an object is dynamic
-and its properties are not known in advance, `io:output` may have a value of `true` to disable
-output restrictions.
-
-```yaml
-GET:
-  endpoint: proxy
-  io:output: true
-```
-
-If a method declaration lacks `io:output` directive, it will trigger a warning, and its
-response will consistently be empty.
-If this behavior is intended, a `false` value can be employed to suppress warnings.
-
-```yaml
-GET:
-  endpoint: conceal
-  io:output: false
-```
-
-Output restrictions are not applied to stream responses and errors.

package/documentation/notes/sse.md

@@ -1,71 +0,0 @@
-# Note: Server Sent Events
-
-## TL;DR
-
-1. Doesn't exist.
-2. Ridiculous.
-3. Redundant.
-
-## There is no SSE
-
-The initial premise of SSE is to deliver real-time events specifically targeted at a particular user. It's evident that
-to access these events, user authentication is essential, typically implemented through
-an [HTTP Authentication framework](https://datatracker.ietf.org/doc/html/rfc2617).
-
-However, despite this being the most straightforward
-scenario, [it does not work this way](https://github.com/whatwg/html/issues/2177). The only viable way to use SSE is
-to avoid the standard `EventSource` implementation.
-
-## Peculiar event format
-
-### SLAP
-
-[Event stream format](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format)
-defines four fields: `event`, `data`, `id`, `retry`.
-
-In practice, code capable of producing such an object is forced to break the Single Level of Abstraction Principle. This
-requires knowledge of both event structures and connection properties. In real-world systems, these may be handled by
-different processes, such as an Events microservice and an API Gateway.
-
-### Content negotiation
-
-The `data` property is expected to be an arbitrary string, although real-world event data is often structured as an
-object.
-
-Furthermore, since the Event stream format defines its own content type, there is no built-in way to negotiate the
-format of the events.
-
-Additionally, the `data` value is limited to a single line, which hinders the use of
-more [human-friendly formats](https://yaml.org) in a straightforward manner.
-
-## HTTP is enough
-
-Rather than resorting to a non-standard client and a predefined content format, a basic HTTP request can provide a
-solution:
-
-```http
-GET /events/ HTTP/1.1
-accept: application/yaml
-```
-
-```
-200 OK
-content-type: application/yaml
-transfer-encoding: chunked
-
-id: 1
-event: created
-data:
-  foo: bar
-
-id: 2
-event: deleted
-data:
-  bar: baz
-```
-
-Server-side implementation with flow control and stream termination handling is trivial:
-
-```javascript
-eventStream.pipe(response)
-```