@toa.io/extensions.exposition 1.0.0-alpha.5 → 1.0.0-alpha.6

package/components/identity.basic/manifest.toa.yaml

@@ -42,9 +42,11 @@ configuration:
 exposition:
   isolated: true
   /:
+    io:output: [id]
     anonymous: true
     POST: incept
   /:id:
+    io:output: [id]
     auth:role: system:identity:basic
     auth:scheme: basic
     auth:id: id

package/components/identity.federation/manifest.toa.yaml

@@ -93,9 +93,3 @@ configuration:
           - sub
         additionalProperties: false
     additionalProperties: false
-
-exposition:
-  isolated: true
-  /:
-    anonymous: true
-    POST: incept

package/components/identity.roles/manifest.toa.yaml

@@ -28,5 +28,6 @@ exposition:
     auth:role: system:identity:roles
     POST: transit
     GET:
+      io:output: true
       auth:id: identity
       endpoint: list

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/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
@@ -251,9 +251,9 @@ PUT /dummies/5e82ed5e/ HTTP/1.1
 if-match: "1"
 
 foo: baz
+```
 
----
-
+```http
 200 OK
 ```
 
@@ -262,8 +262,10 @@ 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/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/features/access.feature

@@ -30,6 +30,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:anonymous: true
         GET:
           dev:stub:
@@ -71,6 +72,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -109,6 +111,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -146,6 +149,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /:
           auth:role: developer:rust:junior  # role scope matches
           /nested:
@@ -190,6 +194,7 @@ Feature: Access authorization
           - developer
           - admin
         GET:
+          io:output: true
           dev:stub:
             access: granted!
       """
@@ -215,6 +220,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /rust/:id:
           auth:rule:
             id: id
@@ -257,6 +263,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -295,6 +302,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -335,6 +343,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:scheme: basic
           auth:id: id
@@ -374,7 +383,8 @@ Feature: Access authorization
 
     Given the annotation:
       """yaml
-      anonymous: true
+      /:
+        anonymous: true
       """
     When the following request is received:
       """

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

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

package/features/cache.feature

@@ -14,6 +14,7 @@ Feature: Caching
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         GET:
           cache:control: max-age=60000
@@ -37,6 +38,7 @@ Feature: Caching
     Given the annotation:
       """yaml
       /:
+        io:output: true
         cache:control: max-age=30000
         GET:
           anonymous: true
@@ -120,6 +122,7 @@ Feature: Caching
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         cache:exact: max-age=60000, public
         GET:

package/features/directives.feature

@@ -4,6 +4,7 @@ Feature: Directives
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         GET:
           dev:stub:
@@ -26,6 +27,7 @@ Feature: Directives
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         dev:stub:
           hello: again

package/features/dynamic.feature

@@ -11,6 +11,7 @@ Feature: Dynamic tree updates
       """yaml
       exposition:
         /:
+          io:output: true
           isolated: true
           GET: enumerate
       """
@@ -27,6 +28,7 @@ Feature: Dynamic tree updates
       """yaml
       exposition:
         /:
+          io:output: true
           GET: enumerate
       """
     When the following request is received:
@@ -44,19 +46,22 @@ Feature: Dynamic tree updates
       """yaml
       exposition:
         /:id:
+          io:output: true
           GET: observe
       """
     Then the `pots` is stopped
     Then the `pots` is running with the following manifest:
       """yaml
       exposition:
-        /:id:
-          GET: observe
-        /big:
-          GET:
-            endpoint: enumerate
-            query:
-              criteria: volume>200
+        /:
+          io:output: true
+          /:id:
+            GET: observe
+          /big:
+            GET:
+              endpoint: enumerate
+              query:
+                criteria: volume>200
       """
     When the following request is received:
       """
@@ -73,6 +78,7 @@ Feature: Dynamic tree updates
       """yaml
       exposition:
         /big:
+          io:output: true
           GET:
             endpoint: enumerate
             query:
@@ -83,6 +89,7 @@ Feature: Dynamic tree updates
       """yaml
       exposition:
         /big:
+          io:output: true
           GET:
             endpoint: enumerate
             query:

package/features/errors.feature

@@ -46,7 +46,7 @@ Feature: Errors
       accept: application/yaml
       """
     Then the following reply is sent:
-      """http
+      """
       405 Method Not Allowed
       """
 
@@ -57,7 +57,7 @@ Feature: Errors
       accept: application/yaml
       """
     Then the following reply is sent:
-      """http
+      """
       501 Not Implemented
       """
 
@@ -197,6 +197,7 @@ Feature: Errors
       """yaml
       /:
         GET:
+          io:output: true
           anonymous: true
           dev:stub: hello
       """

package/features/etag.feature

@@ -5,6 +5,7 @@ Feature: Optimistic concurrency control
       """yaml
       exposition:
         /:
+          io:output: true
           POST: create
           /:id:
             GET: observe

package/features/identity.basic.feature

@@ -22,6 +22,7 @@ Feature: Basic authentication
       """yaml
       exposition:
         /:
+          io:output: true
           anonymous: true     # checking compatibility with anonymous access
           POST:
             incept: id
@@ -72,6 +73,7 @@ Feature: Basic authentication
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           id: id
           GET:
@@ -115,6 +117,25 @@ Feature: Basic authentication
       200 OK
       """
 
+  Scenario: Changing other identity the password
+    Given the `identity.basic` database contains:
+      | _id                              | username  | password                                                     | _version |
+      | efe3a65ebbee47ed95a73edd911ea328 | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+      | 6c0be50cbfb043acafe69cc7d3895f84 | attacker  | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+    When the following request is received:
+      """
+      PATCH /identity/basic/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      authorization: Basic YXR0YWNrZXI6c2VjcmV0
+      accept: application/yaml
+      content-type: application/yaml
+
+      password: new-secret
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
   Scenario Outline: <problem> not meeting the requirements
     When the following request is received:
       """
@@ -173,6 +194,7 @@ Feature: Basic authentication
     And the annotation:
       """yaml
       /:
+        io:output: true
         GET:
           auth:role: system:stub
           dev:stub:
@@ -244,6 +266,7 @@ Feature: Basic authentication
       """yaml
       exposition:
         /:
+          io:output: true
           anonymous: true
           POST:
             incept: id

package/features/identity.federation.feature

@@ -4,7 +4,6 @@ Feature: Identity Federation
     Given the `identity.federation` database is empty
     Given local IDP is running
 
-
   Scenario: Getting identity for a new user
     Given the `identity.federation` configuration:
       """yaml
@@ -27,9 +26,8 @@ Feature: Identity Federation
 
       id: ${{ User.id }}
       roles: []
-      scheme: bearer
       """
-    # validate token
+    # validate TOKEN
     When the following request is received:
       """
       GET /identity/ HTTP/1.1
@@ -41,7 +39,7 @@ Feature: Identity Federation
       200 OK
       id: ${{ User.id }}
       """
-    # ensuring identity idemptotency
+    # ensuring identity idempotency
     When the following request is received:
       """
       GET /identity/ HTTP/1.1
@@ -81,7 +79,6 @@ Feature: Identity Federation
       authorization: Token ${{ GoodUser.token }}
 
       id: ${{ GoodUser.id }}
-      scheme: bearer
       """
 
   Scenario: Creating an Identity using inception with existing credentials
@@ -96,6 +93,7 @@ Feature: Identity Federation
         /:
           anonymous: true
           POST:
+            io:output: true
             incept: id
             endpoint: create
       """

package/features/identity.roles.feature

@@ -11,6 +11,7 @@ Feature: Roles management
     And the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: test
         GET:
           dev:stub:

package/features/identity.tokens.feature

@@ -7,6 +7,7 @@ Feature: Tokens lifecycle
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /hello/:id:
           auth:id: id
           GET:
@@ -35,6 +36,7 @@ Feature: Tokens lifecycle
     And the annotation:
       """yaml
       /:
+        io:output: true
         /hello/:id:
           auth:id: id
           GET:
@@ -72,6 +74,7 @@ Feature: Tokens lifecycle
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           id: id
           GET: