@toa.io/extensions.exposition 1.0.0-alpha.2 → 1.0.0-alpha.21

package/documentation/components.md

@@ -96,9 +96,14 @@ 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).
+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.
+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
@@ -110,6 +115,11 @@ configuration:
         audience:
           - https://github.com/tinovyatkin
           - https://github.com/temich
+
+      - issuer: some.private.issuer
+        secrets:
+          HS256:
+            k1: <secret-to-be-used-for-hs256>
 ```
 
 ## Stateless tokens
@@ -125,6 +135,14 @@ 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
@@ -135,7 +153,7 @@ using the `key0` configuration value as a secret.
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY
 ```
 
@@ -146,25 +164,22 @@ The `key0` configuration value is required.
 ### 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
 
 configuration:
-  identity.basic:
+  identity.tokens:
     lifetime: 2592000 # seconds, 30 days
     refresh: 600      # seconds, 10 minutes
 ```
@@ -192,7 +207,7 @@ the `key0` and `key1` values in order.
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY_2023Q3
     key1: $TOKEN_ENCRYPTION_KEY_2023Q2
 ```
@@ -224,7 +239,7 @@ The secret rotation is a 2-step process:
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY_2023Q3
     key1: $TOKEN_ENCRYPTION_KEY_2023Q4
 ```
@@ -237,18 +252,31 @@ configuration:
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY_2023Q4
     key1: $TOKEN_ENCRYPTION_KEY_2023Q3
 ```
 
-## Roles
+### Token resources
+
+`/identity/tokens/`
+
+`POST` Issue a new token for the Identity. Request body is as follows:
+
+```yaml
+lifetime?: number # seconds
+```
 
-The `identity.roles` component manages roles of an Identity used by [access authorization](access.md#role).
+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).
 
-### Role resources
+## Roles
 
-#### `/identity/roles/:id/`
+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.
 
@@ -260,13 +288,16 @@ Access requires credentials of the Identity or `system:identity:roles` role.
 role: string
 ```
 
-Access requires `system:identity:roles` role.
+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).
+A banned identity will fail to authenticate with any associated credentials
+(except [tokens](#stateless-tokens) within the `refresh` period).
 
 ```http
 PUT /identity/bans/:id/
@@ -274,6 +305,7 @@ authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
 content-type: application/yaml
 
 banned: true
+comment: Bye bye
 ```
 
 Access requires `system:identity:bans` role.

package/documentation/identity.md

@@ -80,7 +80,14 @@ configuration:
       - issuer: https://accounts.google.com
         audience:
           - <GOOGLE_CLIENT_ID>
+
       - issuer: https://appleid.apple.com
+
+      - issuer: 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

package/documentation/io.md

@@ -0,0 +1,56 @@
+# 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/octets.md

@@ -209,6 +209,18 @@ under the request path.
 
 The request body must be a list of entry identifiers.
 
+## `octets:workflow`
+
+Execute a [workflow](#workflows) on the entry under the request path.
+
+```yaml
+/images:
+  /*:
+    DELETE:
+      octets:workflow:
+        archive: images.archive
+```
+
 ## Workflows
 
 A workflow is a list of endpoints to be called.

package/documentation/protocol.md

@@ -72,6 +72,9 @@ The following request headers are allowed:
 - `accept`
 - `authorization`
 - `content-type`
+- `etag`
+- `if-match`
+- `if-none-match`
 - headers used by the [`vary:embed` directive](vary.md#embeddings)
 
 The following response headers are exposed:

package/documentation/query.md

@@ -6,10 +6,10 @@
 id?: string
 criteria?: string
 sort?: string
-omit?: [integer]
-limit?: [integer]
+omit?: integer
+limit?: integer
 selectors?: string[]
-projection?: [string]
+projection?: string[]
 ```
 
 ```yaml
@@ -45,7 +45,7 @@ Undefined `query` denies any query arguments in requests.
 
 ## Criteria
 
-Search critaria in [RSQL](https://github.com/jirutka/rsql-parser) format.
+Search criteria in [RSQL](https://github.com/jirutka/rsql-parser) format.
 
 The `criteria` property is considered as *open* when it ends with a `;`, allowing the combination of
 request query criteria using `and` logic.
@@ -77,7 +77,7 @@ query:
 
 ### Path variables
 
-Path variables are prepended to the `criteria` request query parameter using logial AND,
+Path variables are prepended to the `criteria` request query parameter using logical AND,
 except for the [`POST` method](#post-method).
 
 Given the following declaration:
@@ -224,3 +224,48 @@ A list of Entity properties to be included in the Observation result.
 ```yaml
 projection: [id, title, timestamp]
 ```
+
+## Optimistic concurrency control
+
+If an operation returns an object with `_version` property,
+then its value is passed as the value of
+the [`etag` header](https://datatracker.ietf.org/doc/html/rfc7232#section-2.3) in the response
+(and removed from the object).
+
+Client can use the `if-match` request header to perform an operation only if the corresponding
+object has not been modified since the last retrieval.
+
+```http
+GET /dummies/5e82ed5e/ HTTP/1.1
+
+---
+
+HTTP/1.1 200 OK
+etag: "1"
+
+foo: bar
+```
+
+```http request
+PUT /dummies/5e82ed5e/ HTTP/1.1
+if-match: "1"
+
+foo: baz
+```
+
+```http
+200 OK
+```
+
+```http request
+PUT /dummies/5e82ed5e/ HTTP/1.1
+if-match: "never"
+
+foo: baz
+```
+
+```http
+412 Precondition Failed
+```
+
+The value within the quotes is mapped to the `version` property of operation call query.

package/documentation/require.md

@@ -0,0 +1,15 @@
+# Directive family Require
+
+The `require` directive family provides the ability to specify HTTP request requirements to be met.
+
+## Headers
+
+`require:header` requires a specific header to be present in the request, and `require:headers`
+requires a set of headers to be present.
+
+```yaml
+exposition:
+  /:id:
+    require:header: if-match # enforce concurrency control
+    PUT: transit
+```

package/documentation/tree.md

@@ -102,7 +102,7 @@ HTTP methods can only be mapped to operations of the corresponding types.
 | `GET`       | **Observation**<br/>**Computation**           |
 | `PATCH`     | **Assignment**<br/>**Effect**                 |
 
-As method mapping is unambiguous for Observation, Assignent, and Computation, a consice syntax is
+As method mapping is unambiguous for Observation, Assignment, and Computation, a concise syntax is
 available:
 
 ```yaml
@@ -110,7 +110,23 @@ available:
 /items/:id: [observe, assign]
 ```
 
-### Intermediate Nodes
+### Projections
+
+A Method can have a `projection` key that specifies the fields of the operation result to be
+included in the response.
+
+```yaml
+/teapots:
+  GET:
+    endpoint: select
+    projection:
+      - name
+      - state
+```
+
+> `id` is always included in the projection.
+
+## Intermediate Nodes
 
 An RTD Node that has a Route with a key `/` is an _intermediate_ Node.
 Intermediate Nodes must not have Methods as they are unreachable.
@@ -124,8 +140,10 @@ Intermediate Nodes must not have Methods as they are unreachable.
 
 ## Directives
 
-RTD Directives are declared using RTD node or Method keys following the `{family}:{directive}` pattern and can be used
-to add or modify the behavior of request processing. Directive declarations are applied to the RTD node where they are
+RTD Directives are declared using RTD node or Method keys following the `{family}:{directive}`
+pattern and can be used
+to add or modify the behavior of request processing. Directive declarations are applied to the RTD
+node where they are
 declared and to all nested nodes.
 
 ```yaml

package/documentation/vary.md

@@ -9,13 +9,14 @@ operation call.
 exposition:
   realms:
     toa: the.toa.io
-  /:
+  /:group:
     vary:languages: [en, fr]
     GET:
       vary:embed:
         lang: language # predefined embeddings
         realm: realm
         token: :x-access-token # raw header value
+        group: /:group # route parameter
       endpoint: dummies.get
 ```
 
@@ -47,8 +48,8 @@ If neither of the supported languages matches, the first supported language is u
 
 ### Raw header values
 
-Keys in the embedding map starting with a semicolon (:) are the names of HTTP request headers whose
-values to be embedded into an operation call.
+Values in the embedding map starting with a semicolon (:) are the names of HTTP request headers
+whose values to be embedded into an operation call.
 The names of these headers are then included in the `vary` HTTP response header
 and [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
 of the [CORS](protocol.md#cors).
@@ -56,6 +57,11 @@ of the [CORS](protocol.md#cors).
 [Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are embedded
 as a comma-separated list.
 
+### Route parameters
+
+Values in the embedding map starting with `/:` are the names of route parameters whose values
+to be embedded into an operation call.
+
 ### Fallbacks
 
 If the embedding function is an array, the first non-empty resolved value is used.

package/features/access.feature

@@ -1,3 +1,4 @@
+@security
 Feature: Access authorization
 
   Background:
@@ -30,6 +31,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:anonymous: true
         GET:
           dev:stub:
@@ -71,6 +73,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -109,6 +112,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -146,6 +150,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /:
           auth:role: developer:rust:junior  # role scope matches
           /nested:
@@ -190,6 +195,7 @@ Feature: Access authorization
           - developer
           - admin
         GET:
+          io:output: true
           dev:stub:
             access: granted!
       """
@@ -215,6 +221,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /rust/:id:
           auth:rule:
             id: id
@@ -257,6 +264,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -295,6 +303,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -335,6 +344,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:scheme: basic
           auth:id: id
@@ -374,7 +384,8 @@ Feature: Access authorization
 
     Given the annotation:
       """yaml
-      anonymous: true
+      /:
+        anonymous: true
       """
     When the following request is received:
       """
@@ -388,62 +399,30 @@ Feature: Access authorization
       401 Unauthorized
       """
 
-  Scenario: Banning an Identity
+  Scenario: Authorization delegation
     Given the `identity.roles` database contains:
-      | _id                              | identity                         | role   |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | system |
-    And the annotation:
-      """yaml
-      /:
-        /:id:
-          auth:id: id
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    And the `identity.tokens` configuration:
+      | _id                              | identity                         | role      |
+      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer |
+    And the `echo` is running with the following manifest:
       """yaml
-      refresh: 1
+      exposition:
+        /:
+          io:output: true
+          auth:delegate: identity
+          GET: identity
       """
     When the following request is received:
       """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
+      GET /echo/ HTTP/1.1
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
       """
     Then the following reply is sent:
       """
       200 OK
-      authorization: Token ${{ token }}
-      """
-    When the following request is received:
-      """
-      PUT /identity/bans/e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      content-type: application/yaml
 
-      banned: true
-      """
-    Then the following reply is sent:
-      """
-      204 No Content
-      """
-    # accessing a resource with a banned Identity
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
-      """
-    Then after 1 second
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Token ${{ token }}
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
+      identity:
+        id: efe3a65ebbee47ed95a73edd911ea328
+        roles:
+          - developer
       """

package/features/annotation.feature

@@ -4,6 +4,7 @@ Feature: Annotation
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         /foo:
           GET:

package/features/body.feature

@@ -5,7 +5,8 @@ Feature: Request body
       """yaml
       exposition:
         /:
-          POST: transit
+          io:output: true
+          POST: create
       """
     When the following request is received:
       """
@@ -25,6 +26,7 @@ Feature: Request body
       """yaml
       exposition:
         /:name:
+          io:output: true
           GET: <operation>
       """
     When the following request is received: