@toa.io/extensions.exposition 1.0.0-alpha.49 → 1.0.0-alpha.50

package/documentation/access.md

@@ -37,11 +37,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 +54,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 +67,49 @@ 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
+### `claim`
+
+Grants access if `Bearer` authentication scheme is used and the claim's property matches specified.
+
+```yaml
+/:
+  auth:claim:
+    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 a request authority:
+
+```yaml
+/secrets/:org-id:
+  auth:claim:
+    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:claim:
+    iss: :domain
+    sub: /:org-id
 ```
 
 ### `rule`
@@ -88,13 +120,10 @@ 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`.
@@ -124,11 +153,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

@@ -17,13 +17,6 @@ exposition:
     two: the.two.com
 ```
 
-## Ingress
-
-Each host in the authority definition is used to create a Kubernetes Ingress resource.
-
-> If the application is accessed with the `:authority` that does not match the authority definition,
-> the response with `404` status code is returned.
-
 ## Embedding
 
 To pass the requested authority to the operation call, [`vary:embed` directive](vary.md#embeddings)
@@ -40,6 +33,9 @@ exposition:
       endpoint: observe
 ```
 
+If the value of the `authority` pseudo-header is not present in the `authorities` definition,
+then the value of the `authority` pseudo-header is embedded as is.
+
 ## Identity
 
 Credentials stored or issued by the [authentication system](identity.md) are associated with an

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/auth.claim.feature

@@ -0,0 +1,170 @@
+@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
+      """
+
+  Scenario: Full claim
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          auth:claim:
+            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:claim:
+            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:claim:
+            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:claim:
+            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:claim:
+            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:claim:
+              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:claim:
+              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
+      """

package/features/authorities.feature

@@ -19,6 +19,8 @@ Feature: Authorities
       """
       200 OK
       """
+
+    # arbitrary authorities are also allowed
     When the following request is received:
       """
       GET / HTTP/1.1
@@ -26,7 +28,5 @@ Feature: Authorities
       """
     Then the following reply is sent:
       """
-      404 Not Found
-
-      Unknown authority
+      200 OK
       """

package/features/authorities.federation.feature

@@ -5,7 +5,6 @@ Feature: OIDC tokens with authorities
       """yaml
       authorities:
         one: the.one.com
-        two: the.two.com
       /:
         /:id:
           auth:id: id
@@ -65,6 +64,8 @@ Feature: OIDC tokens with authorities
       """
       200 OK
       """
+
+    # authorization will create new identity within `one` authority
     When the following request is received:
       """
       GET /${{ Two.id }}/ HTTP/1.1
@@ -73,7 +74,7 @@ Feature: OIDC tokens with authorities
       """
     Then the following reply is sent:
       """
-      401 Unauthorized
+      403 Forbidden
       """
 
     # access `two` authority
@@ -85,7 +86,7 @@ Feature: OIDC tokens with authorities
       """
     Then the following reply is sent:
       """
-      401 Unauthorized
+      403 Forbidden
       """
     When the following request is received:
       """

package/features/authorities.tokens.feature

@@ -5,7 +5,6 @@ Feature: Token credentials with authorities
       """yaml
       authorities:
         one: the.one.com
-        two: the.two.com
       /:
         /:id:
           auth:id: id
@@ -43,7 +42,7 @@ Feature: Token credentials with authorities
       id: ${{ one.id }}
       """
 
-    # create identity within the `two` authority
+    # create identity within the `the.two.com` authority
     When the following request is received:
       """
       POST /identity/basic/ HTTP/1.1

package/features/identity.federation.feature

@@ -3,7 +3,7 @@ Feature: Identity Federation
 
   Background:
     Given the `identity.federation` database is empty
-    Given local IDP is running
+    And local IDP is running
 
   Scenario: Getting identity for a new user
     Given the `identity.federation` configuration:
@@ -169,7 +169,7 @@ Feature: Identity Federation
         - iss: http://localhost:44444
       principal:
         iss: http://localhost:44444
-        sub: root-mock-id
+        sub: root
       """
     And the IDP token for root is issued
 

package/features/routes.feature

@@ -138,6 +138,32 @@ Feature: Routes
       201 Created
       """
 
+  Scenario: Routes with default namespace conflicts
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:foo:
+          io:output: true
+          PUT: compute
+      """
+    And the `echo.beacon` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          io:output: true
+          GET: hello
+      """
+    When the following request is received:
+      """
+      GET /echo/beacon/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      """
+
   Scenario: Routes with parameters
     Given the `echo` is running with the following manifest:
       """yaml
@@ -159,3 +185,40 @@ Feature: Routes
       a: foo
       b: bar
       """
+
+  Scenario: Route forwarding
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /show/:a/:b:
+          io:output: true
+          GET: parameters
+        /hello: /echo/show/foo/bar
+        /mirror/:a/:b: /echo/show/:a/:b
+      """
+    When the following request is received:
+      """
+      GET /echo/hello/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      a: foo
+      b: bar
+      """
+    When the following request is received:
+      """
+      GET /echo/mirror/bar/baz/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      a: bar
+      b: baz
+      """

package/features/steps/IdP.ts

@@ -109,7 +109,7 @@ export class IdP {
       },
       {
         iss: IdP.issuer,
-        sub: `${user}-mock-id`,
+        sub: user,
         aud: 'test',
         iat: Math.floor(Date.now() / 1000),
         exp: Math.floor((Date.now() + 1000 * 60 * 5) / 1000)
@@ -134,7 +134,7 @@ export class IdP {
       },
       {
         iss: IdP.issuer,
-        sub: `${user}-mock-id`,
+        sub: user,
         aud: 'test',
         iat: Math.floor(Date.now() / 1000),
         exp: Math.floor((Date.now() + 1000 * 60 * 5) / 1000)

package/features/steps/components/echo.beacon/manifest.toa.yaml

@@ -0,0 +1,2 @@
+namespace: echo
+name: beacon

package/features/steps/components/echo.beacon/operations/hello.js

@@ -0,0 +1,5 @@
+'use strict'
+
+exports.computation = () => {
+  return 'Hello!'
+}

package/features/vary.feature

@@ -214,7 +214,6 @@ Feature: The Vary directive family
       """yaml
       authorities:
         one: the.one.com
-        two: the.two.com
       """
     Given the `echo` is running with the following manifest:
       """yaml
@@ -248,5 +247,5 @@ Feature: The Vary directive family
       """
       200 OK
 
-      Hello two
+      Hello the.two.com
       """

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.49",
+  "version": "1.0.0-alpha.50",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -17,9 +17,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.49",
-    "@toa.io/generic": "1.0.0-alpha.49",
-    "@toa.io/schemas": "1.0.0-alpha.49",
+    "@toa.io/core": "1.0.0-alpha.50",
+    "@toa.io/generic": "1.0.0-alpha.50",
+    "@toa.io/schemas": "1.0.0-alpha.50",
     "bcryptjs": "2.4.3",
     "error-value": "0.3.0",
     "js-yaml": "4.1.0",
@@ -44,11 +44,11 @@
     "features:security": "cucumber-js --tags @security"
   },
   "devDependencies": {
-    "@toa.io/agent": "1.0.0-alpha.49",
-    "@toa.io/extensions.storages": "1.0.0-alpha.49",
+    "@toa.io/agent": "1.0.0-alpha.50",
+    "@toa.io/extensions.storages": "1.0.0-alpha.50",
     "@types/bcryptjs": "2.4.3",
     "@types/cors": "2.8.13",
     "@types/negotiator": "0.6.1"
   },
-  "gitHead": "fb382cfd086bf867209a95046e25b92e43e5b2bb"
+  "gitHead": "514269d4b481150c8cd0db2e5971da6e9fe80ad9"
 }

package/schemas/node.cos.yaml

@@ -1,5 +1,6 @@
 protected: boolean
 isolated: boolean
+forward: string
 routes: [ref:route]
 methods: [ref:method]
 directives: [ref:directive]

package/source/Gateway.ts

@@ -1,8 +1,9 @@
+import assert from 'node:assert'
 import { type bindings, Connector } from '@toa.io/core'
 import * as http from './HTTP'
 import { rethrow } from './exceptions'
 import type { Interception } from './Interception'
-import type { Node, Method, Parameter, Tree } from './RTD'
+import type { Node, Method, Parameter, Tree, Match } from './RTD'
 import type { Label } from './discovery'
 import type { Branch } from './Branch'
 
@@ -28,12 +29,7 @@ export class Gateway extends Connector {
     if (interception !== null)
       return interception
 
-    const match = this.tree.match(context.url.pathname)
-
-    if (match === null)
-      throw new http.NotFound('Route not found')
-
-    const { node, parameters } = match
+    const { node, parameters } = this.match(context)
 
     if (context.request.method === 'OPTIONS')
       return await this.explain(node)
@@ -65,6 +61,31 @@ export class Gateway extends Connector {
     console.info('Gateway is closed')
   }
 
+  private match (context: http.Context): Match {
+    const match = this.tree.match(context.url.pathname)
+
+    if (match === null)
+      throw new http.NotFound('Route not found')
+
+    if (match.node.forward === null)
+      return match
+
+    const destination = match.node.forward.replace(/\/:([^/]+)/g,
+      (_, name) => {
+        const value = match.parameters.find((parameter) => parameter.name === name)?.value
+
+        assert.ok(value !== undefined, `Forwarded parameter '${name}' not found`)
+
+        return `/${value}`
+      })
+
+    const forward = this.tree.match(destination)
+
+    assert.ok(forward !== null, 'Forwarded route not found')
+
+    return forward
+  }
+
   private async call (method: Method, context: http.Context, parameters: Parameter[]): Promise<http.OutgoingMessage> {
     if (context.url.pathname[context.url.pathname.length - 1] !== '/')
       throw new http.NotFound('Trailing slash is required')

package/source/HTTP/Server.ts

@@ -81,13 +81,8 @@ export class Server extends Connector {
       return
     }
 
-    if (request.headers.host === undefined || !(request.headers.host in this.authorities)) {
-      response.writeHead(404).end('Unknown authority')
-
-      return
-    }
-
-    const authority = this.authorities[request.headers.host]
+    const host = request.headers.host!
+    const authority = this.authorities[host] ?? host
     const context = new Context(authority, request as IncomingMessage, this.properties)
 
     this.process!(context)

package/source/RTD/Node.ts

@@ -4,6 +4,7 @@ import { type Match, type Parameter } from './Match'
 
 export class Node {
   public intermediate: boolean
+  public forward: string | null
   public methods: Methods
   private readonly protected: boolean
   private routes: Route[]
@@ -13,6 +14,7 @@ export class Node {
     this.routes = routes
     this.methods = methods
     this.protected = properties.protected
+    this.forward = properties.forward ?? null
     this.intermediate = this.routes.findIndex((route) => route.root) !== -1
 
     this.sort()
@@ -76,10 +78,15 @@ export class Node {
   }
 
   private sort (): void {
-    this.routes.sort((a, b) => a.variables - b.variables)
+    this.routes.sort((a, b) => {
+      return a.variables === b.variables
+        ? b.segments.length - a.segments.length // routes with more segments should be matched first
+        : a.variables - b.variables // routes with more variables should be matched last
+    })
   }
 }
 
 export interface Properties {
   protected: boolean
+  forward?: string
 }