@toa.io/extensions.exposition 1.0.0-alpha.4 → 1.0.0-alpha.41

package/documentation/access.md

@@ -14,8 +14,8 @@
 The Authorization is implemented as a set of [RTD Directives](tree.md#directives).
 
 Directives are executed in a predetermined order until one of them grants access to a resource.
-If none of the directives grants access, then the Authorization interrupts request processing and responds with an
-authorization error.
+If none of the directives grants access, then the Authorization interrupts request processing and
+responds with an authorization error.
 
 > The Authorization directive provider is named `authorization`,
 > so the full names of the directives are `authorization:{directive}`.
@@ -25,7 +25,7 @@ authorization error.
 Grants access if its value is `true` and no credentials were provided[^1].
 
 [^1]: Credentials in the request make the
-response [non-chachable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+response [non-cachable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
 
 ### `id`
 
@@ -56,8 +56,6 @@ is `87480f2bd88048518c529d7957475ecd`.
 
 Grants access if resolved Identity has a role matching the directive's value or one of its values.
 
-#### Example
-
 ```yaml
 # context.toa.yaml
 
@@ -70,11 +68,22 @@ Access will be granted if the resolved Identity has a role that matches `develop
 
 Read [Roles](#roles) section for more details.
 
+#### Dynamic roles
+
+The `role` directive can be used with a placeholder in the route.
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  /:org-id:
+    role: app:{org-id}:moderator
+```
+
 ### `rule`
 
 The Rule is a collection of authorization directives. It allows access only if all the specified
-directives grant
-access. The value of the `rule` directive can be a single Rule or a list of Rules.
+directives grant access. The value of the `rule` directive can be a single Rule or a list of Rules.
 
 #### Example
 
@@ -90,12 +99,22 @@ exposition:
 
 Access will be granted if an Identity matches a `user-id` placeholder and has a Role of `developer`.
 
+### `delegate`
+
+Embeds the value of the current Identity into the request body as a property named after the value
+of the directive value, and grants access.
+The request body must be an object.
+
+> :warning:<br/>
+> The intended use case for this directive is audit.
+> **Using it to pass Identity to the application logic is strongly discouraged.**
+
 ## Roles
 
 Role values are strings that can be assigned to an Identity and used for matching with values of
 the [`role` directive](#role).
 
-### Hierarchy
+### Hierarchies
 
 Role values are alphanumeric tokens separated by a colon (`:`).
 Each token defines a Role Scope, forming a hierarchy.
@@ -124,18 +143,10 @@ In other words, the Identity must have a specified or more general Role.
   </picture>
 </a>
 
-
 > The root-level Role Scope `system` is preserved and cannot be used with the `role` directives.
 
 See also [role management resources](components.md#roles).
 
-#### Authorization Directives
-
-```yaml
-/identity/roles/:id:
-  role: system:roles
-````
-
 ## Policies
 
 Component Resource branches cannot have authorization directives.

package/documentation/authorities.md

@@ -0,0 +1,53 @@
+# 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
+```
+
+## 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)
+can be used.
+
+```yaml
+# manifest.toa.yaml
+
+exposition:
+  /:
+    GET:
+      vary:embed:
+        app: authority
+      endpoint: observe
+```
+
+## 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/cache.md

@@ -17,7 +17,7 @@ to [safe HTTP methods](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HT
 
 ### Implicit modifications
 
-In terms of security, the following implicit modifications are made to the `Cache-Control` header:
+In terms of security, the following implicit modifications are made to the `cache-control` header:
 
 - If it contains the `public` directive without `no-cache` and the request is authenticated,
   the `no-cache` directive is added.
@@ -25,6 +25,13 @@ In terms of security, the following implicit modifications are made to the `Cach
 - If it does not contain the `private` directive and the request is authenticated, the `private`
   directive is added.
   This is to prevent the storage of private data in shared caches.
+- If it contains `private` directive and the request is authenticated, then `vary: authorization` is
+  added.
+  This is to prevent the reuse of private data when authenticated as another identity.[^1]
+
+[^1]: This also will invalidate the cache each time a new token is used for the same identity, thus
+limiting the `max-age` value to the token's `refresh` time.
+See [Issuing tokens](components.md#issuing-tokens).
 
 ## `cache:exact`
 

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
@@ -96,11 +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.
+Toa supports either asymmetric RS256 or symmetric HS256 / HS384 / HS512 tokens with pre-shared
+secrets.
 
 ```yaml
 # context.toa.yaml
@@ -108,8 +111,8 @@ Toa supports either asymmetric RS256 or symmetric HS256 / HS384 / HS512 tokens w
 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
 
@@ -132,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
@@ -153,19 +164,16 @@ 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
@@ -249,13 +257,26 @@ configuration:
     key1: $TOKEN_ENCRYPTION_KEY_2023Q3
 ```
 
-## Roles
+### Token resources
 
-The `identity.roles` component manages roles of an Identity used by [access authorization](access.md#role).
+`/identity/tokens/`
 
-### Role resources
+`POST` Issue a new token for the Identity. Request body is as follows:
 
-#### `/identity/roles/:id/`
+```yaml
+lifetime?: number # seconds
+```
+
+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).
+
+## Roles
+
+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.
 
@@ -267,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/
@@ -281,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

@@ -1,36 +1,30 @@
 # Identity
 
 Identity is the fundamental entity within an authentication system that represents the **unique
-identifier** of an
-individual, organization, application or device.
+identifier** of an individual, organization, application or device.
 
-In order to prove its Identity, the request originator must provide a valid _credentials_ that are
-associated with that
-Identity.
+To prove its Identity, the request originator must provide a valid _credentials_ that are associated
+with that Identity.
 
 Identity is intrinsically linked to credentials, as an Identity is established only when the first
-set of credentials
-for that Identity is created.
+set of credentials for that Identity is created.
 In other words, the creation of credentials marks the inception of an Identity.
 Once the last credentials are removed from the Identity, it ceases to exist.
 Without credentials, there is no basis for defining or asserting an Identity.
 
 ## Authentication
 
-The Authenticaiton system resolves provided credentials to an Identity using one of the supported
-authentication
-schemes.
+The Authentication system resolves provided credentials to an Identity using one of the supported
+authentication schemes.
 
 The Authentication is request-agnostic, meaning it does not depend on the specific URL being
-requested or the content of
-the request body.
+requested or the content of the request body.
 The only information it handles is the value of the `Authorization` header.
 
-> Except for its own [management resources](#persistent-credentials).
+> Except for its own [management resources](components.md).
 
 If the provided credentials are not valid or not associated with an Identity, then Authentication
-interrupts request
-processing and responds with an authentication error.
+interrupts request processing and responds with an authentication error.
 
 ### Basic scheme
 
@@ -52,8 +46,8 @@ Authrization: Token v4.local.eyJzdWIiOiJqb2hu...
 
 The `Token` is the **primary** authentication scheme.
 If request originators use an alternative authentication scheme, they will receive a response
-containing `Token`
-credentials and will be required to switch to the `Token` scheme for any subsequent requests.
+containing `Token`credentials and will be required to switch to the `Token` scheme for any
+subsequent requests.
 Continued use of other authentication schemes will result in temporary blocking of requests.
 
 See [`identity.tokens` component](components.md#stateless-tokens).
@@ -69,7 +63,8 @@ to [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.ht
 Authorization: Bearer eyJhbGciOiJIUzI1...
 ```
 
-Trusted providers are specified using the `identity.federation` property within the configuration annotation.
+Trusted providers are specified using the `identity.federation` property within the configuration
+annotation.
 
 ```yaml
 # context.toa.yaml
@@ -77,13 +72,13 @@ Trusted providers are specified using the `identity.federation` property within
 configuration:
   identity.federation:
     trust:
-      - issuer: https://accounts.google.com
-        audience:
+      - iss: https://accounts.google.com
+        aud:
           - <GOOGLE_CLIENT_ID>
 
-      - issuer: https://appleid.apple.com
+      - iss: https://appleid.apple.com
 
-      - issuer: private.entity
+      - iss: private.entity
         secrets:
           HS384:
             key0: <THE-SECRET-STRING-FOR-HS384>

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

@@ -7,16 +7,15 @@ operation call.
 
 ```yaml
 exposition:
-  realms:
-    toa: the.toa.io
-  /:
+  /:group:
     vary:languages: [en, fr]
     GET:
       vary:embed:
-        lang: language # predefined embeddings
-        realm: realm
+        app: authority # predefined embeddings
+        lang: language
         token: :x-access-token # raw header value
-      endpoint: dummies.get
+        group: /:group # route parameter
+      endpoint: observe
 ```
 
 ## Embeddings
@@ -30,13 +29,9 @@ If the value is an array, the first non-empty embedding function's result is use
 > If a property is already present in the input, the embedded value will overwrite its current
 > value.
 
-### Realm
+### Authority
 
-Realm is an identifier of a domain used to access the Exposition.
-The list of domains is defined by the `vary:realms` directive,
-which is a map of realm names to their domain names.
-
-The `realm` embedding substitutes the realm identified based on the `host` request header.
+The `authority` embedding substitutes request [authority identifier](authorities.md).
 
 ### Language
 
@@ -47,8 +42,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 +51,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.