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

package/documentation/query.md

@@ -77,8 +77,12 @@ query:
 
 ### Path variables
 
-Path variables are prepended to the `criteria` request query parameter using logical AND,
-except for the [`POST` method](#post-method).
+Path variables are prepended to the `criteria` request query parameter except for
+the [`POST` method](#post-method).
+
+If query criteria starts with logical operator (`,` or `;`), then path variables are prepended
+accordingly.
+`AND` logical operator is used by default.
 
 Given the following declaration:
 
@@ -92,7 +96,7 @@ exposition:
     GET:
       endpoint: observe
       query:
-        criteria: state==hot; # open criteria
+        criteria: ,state==hot; # open criteria
 ```
 
 and the following request:
@@ -104,7 +108,7 @@ GET /dummies/cool/?criteria=rank==5
 Operation call will have the following query criteria:
 
 ```yaml
-criteria: state==hot;type==cool;rank=5
+criteria: (type==cool,state==hot);(rank=5)
 ```
 
 #### POST method
@@ -173,6 +177,10 @@ Constant values can be declared using the shortcut:
 limit: 10
 ```
 
+```http
+GET /dummies/?omit=100&limit=10
+```
+
 ## Sort
 
 The `sort` query property defines the result order of Observations within an `objects` scope
@@ -209,6 +217,8 @@ GET /dummies/?sort=timestamp:asc
 
 ## Selectors
 
+![Not implemented](https://img.shields.io/badge/Not_implemented-red)
+
 The `selectors` query property contains a list of Entity properties allowed for a client to use in
 the `criteria` and `sort` query parameters.
 If no value is provided, then no selectors are allowed.
@@ -225,6 +235,21 @@ A list of Entity properties to be included in the Observation result.
 projection: [id, title, timestamp]
 ```
 
+## Parameters
+
+By default, the only query parameters allowed are described above. Arbitrary query parameters
+can be allowed by specifying them in the `parameters` property.
+
+```yaml
+parameters: [foo, bar]
+```
+
+These parameters are embedded in the operation call input, which must be an object.
+
+```http
+GET /dummies/?foo=0&bar=baz
+```
+
 ## Optimistic concurrency control
 
 If an operation returns an object with `_version` property,

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

@@ -56,6 +56,19 @@ as it provides a more specific match compared to the generic `/users/:id` route.
 
 The priority of Routes with the same specificity is determined by the order of declaration.
 
+## Route forwarding
+
+A Route can be forwarded to another Route by specifying the destination Route as the value of the
+Route.
+
+```yaml
+/destination/:var: ...
+/static: /destination/hello
+/variables/:bar: /destination/:bar
+```
+
+Forwarding Route variables are mapped to the forwarded Route variables if they have the same name.
+
 ## Methods
 
 Methods are mappings of the HTTP methods to the corresponding operations.

package/features/access.feature

@@ -5,9 +5,9 @@ Feature: Access authorization
     Given the `identity.basic` database contains:
       # developer:secret
       # user:12345
-      | _id                              | username  | password                                                     |
-      | efe3a65ebbee47ed95a73edd911ea328 | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-      | e8e4f9c2a68d419b861403d71fabc915 | user      | $2b$10$Frszmrmsz9iwSXzBbRRMKeDVKsNxozkrLNSsN.SnVC.KPxLtQr/bK |
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+      | e8e4f9c2a68d419b861403d71fabc915 | nex       | user      | $2b$10$Frszmrmsz9iwSXzBbRRMKeDVKsNxozkrLNSsN.SnVC.KPxLtQr/bK |
     And the `identity.bans` database is empty
 
   Scenario: Deny by default
@@ -21,6 +21,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       """
     Then the following reply is sent:
       """
@@ -40,6 +41,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       accept: application/yaml
       """
     Then the following reply is sent:
@@ -50,6 +52,56 @@ Feature: Access authorization
       access: granted!
       """
 
+  Scenario: Allow access to anyone
+    Given the annotation:
+      """yaml
+      /:
+        io:output: true
+        auth:anyone: true
+        GET:
+          dev:stub:
+            access: granted!
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: application/yaml
+
+      access: granted!
+      """
+
+    # request without credentials
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
+    # request with invalid credentials
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic bm9uOmV4aXN0ZW50
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      """
+
   Scenario: Deny access with credentials to a resource with anonymous access
     Given the annotation:
       """yaml
@@ -62,6 +114,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       """
     Then the following reply is sent:
@@ -83,6 +136,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -96,6 +150,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic dXNlcjoxMjM0NQ==
       accept: application/yaml
       """
@@ -122,6 +177,7 @@ Feature: Access authorization
       # identity with `developer` and `user` roles
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -136,6 +192,7 @@ Feature: Access authorization
       # identity with no roles
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic dXNlcjoxMjM0NQ==
       """
     Then the following reply is sent:
@@ -164,6 +221,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /nested/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: text/plain
       """
@@ -177,6 +235,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /javascript/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       """
     Then the following reply is sent:
@@ -203,6 +262,7 @@ Feature: Access authorization
       # identity with `developer` and `user` roles
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -240,6 +300,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /rust/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -253,6 +314,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /javascript/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       """
     Then the following reply is sent:
@@ -273,8 +335,37 @@ Feature: Access authorization
       """
     When the following request is received:
       """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.9oEtVJkfRw4cOJ8M4DxuVuAN29dGT26XMYyPAoXtwrkdkiJVSVj46sMNAOdlxwKGszJZV_ReOL26dxDVlsQ7QAIuRhRPlvsHYNOhcD-LApoAXV0S3IK16EMoEv7tE9z70FCLC3WoIW9RIQ8PR3uZhAdhSgBilsVOpWrk4XtnfCIlVwhYMKu79a66oZZhV2Q7Kl3nfYsf84-6rAL_1H0MsqCDUHVXuIg
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ developer.token }}
+
+      id: ${{ developer.id }}
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjoxMjM0NQ==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ user.token }}
+
+      id: ${{ user.id }}
+      """
+    When the following request is received:
+      """
+      GET /${{ developer.id }}/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ developer.token }}
       accept: application/yaml
       """
     Then the following reply is sent:
@@ -290,8 +381,9 @@ Feature: Access authorization
       """
     When the following request is received:
       """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.cjlxn4IJ9hI92KuksguzDx7_kYxgDFFGFnfNchf0cWnmos34dqX2XpTAUBd-LqgqfuH-lVGfNvjBUkw5JtHRBiIAVaPHF3Ncc0eafwgH2DPme9pndZL92fWryGnJ-sMHA28Q6UcXsIfhgd2JZ0n-585SBhwlosC3gKTcVHK7XNljeaTen4jZPw8uY-pdbsm6dDq3aKMzl8K78_BTTfiNPG2cI_aNuHw
+      GET /${{ user.id }}/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ developer.token }}
       accept: application/yaml
       """
     Then the following reply is sent:
@@ -315,6 +407,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -329,6 +422,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Token ${{ token }}
       accept: application/yaml
       """
@@ -355,6 +449,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -368,6 +463,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Token v3.local.9oEtVJkfRw4cOJ8M4DxuVuAN29dGT26XMYyPAoXtwrkdkiJVSVj46sMNAOdlxwKGszJZV_ReOL26dxDVlsQ7QAIuRhRPlvsHYNOhcD-LApoAXV0S3IK16EMoEv7tE9z70FCLC3WoIW9RIQ8PR3uZhAdhSgBilsVOpWrk4XtnfCIlVwhYMKu79a66oZZhV2Q7Kl3nfYsf84-6rAL_1H0MsqCDUHVXuIg
       accept: text/plain
       """
@@ -375,12 +471,12 @@ Feature: Access authorization
       """
       403 Forbidden
 
-      Basic authentication scheme is required to access this resource.
+      Basic authentication scheme is required to access this resource
       """
 
   Scenario: Adding a role without required permissions
 
-  Trunk directives should not be applied to the Identity management resources.
+  Trunk directives should not be applied to the Identity management resources
 
     Given the annotation:
       """yaml
@@ -390,6 +486,7 @@ Feature: Access authorization
     When the following request is received:
       """
       POST /identity/roles/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       content-type: application/yaml
 
       role: developer
@@ -414,15 +511,31 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /echo/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
     Then the following reply is sent:
       """
       200 OK
+      authorization: Token ${{ token }}
 
       identity:
         id: efe3a65ebbee47ed95a73edd911ea328
         roles:
           - developer
       """
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+    And the reply does not contain:
+      """
+      authorization: Token
+      """

package/features/annotation.feature

@@ -18,6 +18,7 @@ Feature: Annotation
     When the following request is received:
       """
       GET /foo/ HTTP/1.1
+      host: nex.toa.io
       accept: application/yaml
       """
     Then the following reply is sent:

package/features/auth.assert.feature

@@ -0,0 +1,57 @@
+Feature: Identity assertion
+
+  Scenario: Assert Identity
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     | _version |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+    And the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET:
+            auth:assert: true
+            anyone: true
+            io:output: true
+            endpoint: ping
+      """
+
+    # existent identity
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ developer.token }}
+      """
+
+    # new identity
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYSQkdzByZCE=
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ user.token }}
+      """
+
+    # invalid credentials
+    When the following request is received:
+      """
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYXNz
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      422 Unprocessable Entity
+
+      code: INVALID_PASSWORD
+      """

package/features/auth.claims.feature

@@ -0,0 +1,171 @@
+@security
+Feature: Federated identity authentication
+
+  Background:
+    Given the `identity.federation` database is empty
+    And local IDP is running
+    And the IDP token for Bob is issued
+    And the `identity.federation` configuration:
+      """yaml
+      trust:
+        - iss: http://localhost:44444
+      implicit: true
+      """
+
+  Scenario: Full claim
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            aud: test
+            sub: Bob
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: Only `sub`
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            sub: Bob
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: No `sub`
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            aud: test
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: `sub` mismatch
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            sub: Alice
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
+  Scenario: `aud` mismatch
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claims:
+            iss: http://localhost:44444
+            aud: goalkeepers
+          dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+      """
+
+  Scenario: Matching authority and Route parameter
+    Given the annotation:
+      """yaml
+      authorities:
+        test: the.test.local
+      /:
+        /:id:
+          GET:
+            auth:claims:
+              aud: :authority
+              sub: /:id
+            dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET /Bob/ HTTP/1.1
+      host: the.test.local
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
+  Scenario: `iss` matching authority common domain
+    Given the annotation:
+      """yaml
+      /:
+        /:id:
+          GET:
+            auth:claims:
+              iss: :domain
+              sub: /:id
+            dev:stub: ok
+      """
+
+    When the following request is received:
+      """
+      GET /Bob/ HTTP/1.1
+      host: localhost
+      authorization: Bearer ${{ Bob.id_token }}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """