@toa.io/extensions.exposition 1.0.0-alpha.14 → 1.0.0-alpha.142

package/documentation/access.md

@@ -15,8 +15,7 @@ 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.
+responds with an authorization error.
 
 > The Authorization directive provider is named `authorization`,
 > so the full names of the directives are `authorization:{directive}`.
@@ -26,7 +25,11 @@ authorization error.
 Grants access if its value is `true` and no credentials were provided[^1].
 
 [^1]: Credentials in the request make the
-response [non-cachable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+response [non-cacheable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+
+### `anyone`
+
+Grants access if its value is `true` and valid credentials were provided.
 
 ### `id`
 
@@ -38,11 +41,8 @@ the directive's value.
 Given the Route declaration and corresponding HTTP request:
 
 ```yaml
-# context.toa.yaml
-
-exposition:
-  /users/:user-id:
-    id: "user-id"
+/users/:user-id:
+  id: "user-id"
 ```
 
 ```http
@@ -58,11 +58,8 @@ is `87480f2bd88048518c529d7957475ecd`.
 Grants access if resolved Identity has a role matching the directive's value or one of its values.
 
 ```yaml
-# context.toa.yaml
-
-exposition:
-  /code:
-    role: [developer, reviewer]
+/code:
+  role: [developer, reviewer]
 ```
 
 Access will be granted if the resolved Identity has a role that matches `developer` or `reviewer`.
@@ -74,11 +71,50 @@ Read [Roles](#roles) section for more details.
 The `role` directive can be used with a placeholder in the route.
 
 ```yaml
-# context.toa.yaml
+/:org-id:
+  role: app:{org-id}:moderator
+```
 
-exposition:
-  /:org-id:
-    role: app:{org-id}:moderator
+### `claims`
+
+Grants access if `Bearer` authentication scheme is used
+and the Token's claims matches the specified values.
+
+```yaml
+/:
+  auth:claims:
+    iss: https://id.example.com
+    sub: someone
+    aud: stars
+```
+
+> If OIDC token claim contains `aud`
+> as [an array](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation), the
+> directive will match if at least one value.
+
+At least one property is required.
+
+Values may refer to the Route parameters or the request authority:
+
+```yaml
+/secrets/:org-id:
+  auth:claims:
+    iss: https://id.org.com
+    sub: /:org-id
+    aud: :authority
+```
+
+An expression `:domain` will match if the domain in the value of `iss` matches the request
+authority, excluding the most specific subdomain.
+
+Issuer `https://accounts.example.com` matches request authorities `images.example.com`
+and `sub.images.example.com`, but not `images.another.com`.
+
+```yaml
+/images/:user-id:
+  auth:claims:
+    iss: :domain
+    sub: /:org-id
 ```
 
 ### `rule`
@@ -89,23 +125,43 @@ directives grant access. The value of the `rule` directive can be a single Rule
 #### Example
 
 ```yaml
-# context.toa.yaml
-
-exposition:
-  /commits/:user-id:
-    rule:
-      id: user-id
-      role: developer
+/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`.
 
+### `input`
+
+Restricts access based on the request body (which must be an object).
+
+```yaml
+/commits/:id:
+  PUT:
+    auth:role: [developer, reviewer]
+    auth:input:
+      - prop: approved
+        role: reviewer
+      - prop: message
+        role: developer
+```
+
+The example above restricts access to the `approved` property of the request body to the identity
+with the `reviewer` role, and the `message` property to the identity with the `developer` role.
+
+> `auth:input` directive does not grant access by itself.
+
 ### `delegate`
 
 Embeds the value of the current Identity into the request body as a property named after the value
 of the directive value, and grants access.
+The request body must be an object.
 
-> The request body must be an object.
+> :warning:<br/>
+> The intended use case for this directive is audit.
+> **Using it to pass Identity to the application logic is strongly discouraged.**
 
 ## Roles
 
@@ -122,11 +178,8 @@ directive.
 #### Example
 
 ```yaml
-# context.toa.yaml
-
-/exposition:
-  /commits/:user-id:
-    role: developer:senior
+/commits/:user-id:
+  role: developer:senior
 ```
 
 The example above defines a `role` directive with the specified `developer:senior` Role Scope.
@@ -141,7 +194,6 @@ In other words, the Identity must have a specified or more general Role.
   </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).

package/documentation/authorities.md

@@ -0,0 +1,48 @@
+# Authorities
+
+Authorities are a mechanism that allows serving multiple domains from a single instance of the
+application.
+
+## Definition
+
+The `authorities` definition is a map of authority identifiers to the `:authority` pseudo-header
+values.
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  authorities:
+    one: the.one.com
+    two: the.two.com
+```
+
+## Mappings
+
+To pass the requested authority to the operation call, [`map:authority` directive](map#embeddings)
+can be used.
+
+```yaml
+# manifest.toa.yaml
+
+exposition:
+  /:
+    GET:
+      map:authority: hostname
+      endpoint: observe
+```
+
+If the value of the `authority` pseudo-header is not present in the `authorities` definition,
+then the value is embedded as is.
+
+## Identity
+
+Credentials stored or issued by the [authentication system](identity.md) are associated with an
+authority.
+Credentials in one authority are not valid in another,
+or may be associated with a different Identity; in other words, Identity exists in the context of an
+authority.
+
+> :warning:<br/>
+> Changing the authority identifier will break compatibility with existing stored or issued
+> credentials.

package/documentation/cache.md

@@ -17,7 +17,7 @@ to [safe HTTP methods](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HT
 
 ### Implicit modifications
 
-In terms of security, the following implicit modifications are made to the `Cache-Control` header:
+In terms of security, the following implicit modifications are made to the `cache-control` header:
 
 - If it contains the `public` directive without `no-cache` and the request is authenticated,
   the `no-cache` directive is added.
@@ -25,6 +25,13 @@ In terms of security, the following implicit modifications are made to the `Cach
 - If it does not contain the `private` directive and the request is authenticated, the `private`
   directive is added.
   This is to prevent the storage of private data in shared caches.
+- If it contains `private` directive and the request is authenticated, then `vary: authorization` is
+  added.
+  This is to prevent the reuse of private data when authenticated as another identity.[^1]
+
+[^1]: This also will invalidate the cache each time a new token is used for the same identity, thus
+limiting the `max-age` value to the token's `refresh` time.
+See [Issuing tokens](components.md#issuing-tokens).
 
 ## `cache:exact`
 

package/documentation/components.md

@@ -20,7 +20,7 @@ and pepper.
 configuration:
   identity.basic:
     rounds: 10 # salt rounds
-    peper: ''  # hashing pepper
+    pepper: '' # hashing pepper
 ```
 
 ### Credentials constraints
@@ -74,6 +74,12 @@ username: string
 password: string
 ```
 
+Returns `201 Created` if the Identity is created,
+or `422 Unprocessable Entity` with one of the error codes:
+
+- `INVALID_USERNAME` - `username` does not match constraints
+- `INVALID_PASSWORD` - `password` does not match constraints
+
 Access is [anonymous](access.md#anonymous).
 
 #### `/identity/basic/:id/`
@@ -89,6 +95,15 @@ password?: string
 
 Access requires basic credentials of the modified Identity or `system:identity:basic` role.
 
+#### `/identity/basic/usernames/:username/`
+
+<code>GET</code> Check if the username is available.
+
+`username` must be Base64 URL encoded.
+
+Returns empty response with status `204`
+if the username is already taken or `404` if it is available.
+
 ## Identity federation (OpenID connect)
 
 The `identity.federation` component manages OpenID Connect federated identities.
@@ -111,8 +126,8 @@ secrets.
 configuration:
   identity.federation:
     trust:
-      - issuer: https://token.actions.githubusercontent.com
-        audience:
+      - iss: https://token.actions.githubusercontent.com
+        aud:
           - https://github.com/tinovyatkin
           - https://github.com/temich
 
@@ -122,9 +137,9 @@ configuration:
             k1: <secret-to-be-used-for-hs256>
 ```
 
-## Stateless tokens
+## Local tokens
 
-The `identity.tokens` component manages stateless authentication tokens.
+The `identity.tokens` component manages local authentication tokens.
 
 These tokens carry the information required to authenticate the Identity and authorize access.
 
@@ -135,40 +150,108 @@ 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
+```
+
+### Custom tokens
+
+Custom tokens can be issued with a specific set of permissions and scopes for the own Identity or by
+an Identity with the `system:identity:tokens` role.
+
+Tokens are issued with custom secret keys and are not subject to [token rotation](#token-rotation).
+To invalidate a custom token, its secret key must be deleted.
+
+Custom tokens have no `refresh` period, that is, never become obsolete and never refreshed.
+
+```
+POST /identity/tokens/<identity>/
+host: nex.toa.io
+authorization: ...
+accept: application/yaml
+content-type: application/yaml
+
+lifetime: 3600
+scopes: [app:developer]
+permissions:
+  /users/fc8e66dd/: [GET, PUT]
+  /posts/fc8e66dd/**/comments/: [*]
+```
+
+```
+201 Created
+content-type: application/yaml
+
+token: <token>
+```
+
+- `lifetime`: Issued token will be valid for this period
+  (default is specified in [the configuration](#token-rotation)).
+  The value of `0` means the token will not expire, which is supported, but
+  **strongly not recommended** for production environments.
+- `scopes`: Issued token will assume only specified [role scopes](access.md#roles).
+- `permissions`: Issued token will have permissions to access only specified resources and methods.
+  Supports [glob patterns](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)
+  and a wildcard method.
+
+> `roles` and `permissions` are additional restrictions applied on top of the Identity’s inherent
+> privileges.
+
+### Custom token invalidation
+
+Custom tokens can be invalidated by deleting the secret key used to issue them.
+This can be done by the Identity that issued the token or by an Identity with
+the `system:identity:keys` role.
+
+```
+DELETE /identity/keys/<identity>/<key.id>/
+authorization: ...
+```
+
+Token secret key `id` can be obtained from the list of issued tokens (or from the footer of the
+token itself).
+
+```
+GET /identity/keys/<identity>/
+authorization: ...
+```
+
 ### 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.
+using the first key from the `keys` configuration value.
 
 ```yaml
 # context.toa.yaml
 
 configuration:
   identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY
+    keys:
+      2024q1: $TOKEN_SECRET_2024Q1
 ```
 
-The `key0` configuration value is required.
+At least one key in the `keys` 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).
+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.
+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.
+convenience.
 
 ```yaml
 # context.toa.yaml
@@ -192,43 +275,18 @@ Token revocation takes effect once the `refresh` period of the currently issued
 
 ### 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."
+Tokens are always encrypted using the first key from the `keys` configuration value,
+and decrypted by the key used to encrypt them.
 
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q2
-```
+To rotate the secret key, a new key must be added to the top of the `keys` configuration value, that
+is, it will be used to encrypt new tokens.
 
-Secret rotation is performed by adding a new key as the `key0` value and moving the existing `key0`
-to the `key1` value.
+Old keys must be removed only after the `refresh` period of the previously issued tokens has
+expired.
 
-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.
+> Let's say you are adding a new secret key each quarter: `2024Q1`, `2024Q2` and so on.
+> The old key `2024Q1` must be removed from the configuration only when the `refresh` period after
+> the new key `2024Q2` was added has expired.
 
 ```yaml
 # context.toa.yaml
@@ -324,3 +382,17 @@ roles:
   - developer
   - system:identity:roles
 ```
+
+When no credentials are provided, transient Identity is created.
+
+```http
+GET /identity/
+accept: application/yaml
+```
+
+```
+201 Created
+
+id: 332017649c814649b25ee466c1fe4534
+roles: []
+```

package/documentation/dev.md

@@ -0,0 +1,30 @@
+# Development tools
+
+## `dev:stub`
+
+Returns a successful response with the given body.
+
+```yaml
+/foo:
+  dev:sub: Hello!
+/bar:
+  dev:sub:
+    hello: world
+```
+
+## `dev:sleep`
+
+Enables delay before processing the request, up to given maximum time in milliseconds (unlimited by
+if value is
+`0`).
+Desired delay can be set in the `sleep` request header.
+
+```yaml
+/foo:
+  dev:sleep: 1000
+```
+
+```http
+GET /foo/ HTTP/1.1
+sleep: 500
+```

package/documentation/flow.md

@@ -0,0 +1,44 @@
+# Request flow
+
+## `flow:fetch`
+
+Fetches the content from the resource returned by the specified endpoint.
+
+The value of the directive is a `string` specifying endpoint to be called for the redirection
+request.
+
+Request `authority`, `path` and `parameters` are passed as input to the redirection endpoint,
+and it must return a URL `string`, an `Error` or an object with the following properties:
+
+```yaml
+url: string
+options?:
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+```
+
+If it returns a URL or Request, then the response to the specified request is returned as the
+response to the original request, along with the `content-type`, `content-length`, and `etag`
+headers.
+
+## `flow:compose`
+
+Compose an object from a response stream in object mode.
+
+The value of the directive is an object whose values are JavaScript expressions
+accessing the response stream objects composed into an array named `$`.
+
+```yaml
+flow:compose:
+  one: $[0].status
+  two: $[1].data.foo
+  three: $[2].amount
+```
+
+```yaml
+flow:compose:
+  sum: $[0].value + $[1].value
+```
+
+Be careful.