@toa.io/extensions.exposition 1.0.0-alpha.17 → 1.0.0-alpha.170

package/documentation/access.md

@@ -25,7 +25,11 @@ responds with an 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`
 
@@ -37,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
@@ -57,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`.
@@ -73,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`
@@ -88,17 +125,34 @@ 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
@@ -124,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.

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/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.
 
@@ -143,21 +158,84 @@ 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).
 
@@ -197,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."
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q2
-```
+Tokens are always encrypted using the first key from the `keys` configuration value,
+and decrypted by the key used to encrypt them.
 
-Secret rotation is performed by adding a new key as the `key0` value and moving the existing `key0`
-to the `key1` value.
+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.
 
-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.
+Old keys must be removed only after the `refresh` period of the previously issued tokens has
+expired.
 
-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
@@ -329,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.