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

package/components/identity.tokens/operations/types.d.ts

@@ -0,0 +1,40 @@
+import { type Call, type Maybe, type Observation } from '@toa.io/types';
+export interface Context {
+    local: {
+        observe: Observation<Entity>;
+        decrypt: Call<Maybe<DecryptOutput>, string>;
+    };
+    configuration: Configuration;
+}
+export interface Configuration {
+    readonly key0: string;
+    readonly key1?: string;
+    readonly lifetime: number;
+    readonly refresh: number;
+}
+export interface Entity {
+    identity: string;
+    revokedAt: number;
+}
+export interface Identity extends Record<string, any> {
+    id: string;
+}
+export interface AuthenticateOutput {
+    identity: Identity;
+    refresh: boolean;
+}
+export interface EncryptInput {
+    identity: Identity;
+    lifetime?: number;
+}
+export interface DecryptOutput {
+    identity: Identity;
+    iat: string;
+    exp?: string;
+    refresh: boolean;
+}
+export interface Claim {
+    identity: Identity;
+    iat: string;
+    exp?: string;
+}

package/components/identity.tokens/operations/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/components/identity.tokens/operations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":""}

package/components/octets.storage/manifest.toa.yaml

@@ -10,6 +10,7 @@ operations:
       storage*: string
       request*: ~
       accept: string
+      meta: <string>
   fetch: &simple
     bindings: ~
     input:

package/components/octets.storage/operations/store.js

@@ -1,11 +1,11 @@
 'use strict'
 
 function store (input, context) {
-  const { storage, request } = input
+  const { storage, request, accept, meta } = input
   const path = request.path
   const claim = request.headers['content-type']
 
-  return context.storages[storage].put(path, request, { claim, accept: input.accept })
+  return context.storages[storage].put(path, request, { claim, accept, meta })
 }
 
 exports.effect = store

package/cucumber.js

@@ -1,6 +1,5 @@
 module.exports = {
   default: {
-    paths: ['features/**/*.feature'],
     requireModule: ['ts-node/register'],
     require: ['./features/**/*.ts'],
     failFast: true

package/documentation/components.md

@@ -34,7 +34,7 @@ them).
 configuration:
   identity.basic:
     username:
-      - ^\S{1,16}$
+      - ^\S{1,128}$
     password:
       - ^\S{8,32}$
 ```
@@ -89,9 +89,32 @@ password?: string
 
 Access requires basic credentials of the modified Identity or `system:identity:basic` role.
 
+## Identity federation (OpenID connect)
+
+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).
+
+No federated tokens are accepted by default until at least one entry is added to the `trust` configuration.
+
+```yaml
+# context.toa.yaml
+
+configuration:
+  identity.federation:
+    trust:
+      - issuer: https://token.actions.githubusercontent.com
+        audience:
+          - https://github.com/tinovyatkin
+          - https://github.com/temich
+```
+
 ## Stateless tokens
 
-The `identity.tokens` component manages statless authentication tokens.
+The `identity.tokens` component manages stateless authentication tokens.
 
 These tokens carry the information required to authenticate the Identity and authorize access.
 

package/documentation/identity.md

@@ -69,20 +69,20 @@ 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 `idenity.trust` property within the Exposition annotation.
+Trusted providers are specified using the `identity.federation` property within the configuration annotation.
 
 ```yaml
 # context.toa.yaml
 
-exposition:
-  identity:
+configuration:
+  identity.federation:
     trust:
-      - https://accounts.google.com
-      - https://appleid.apple.com
+      - issuer: https://accounts.google.com
+        audience:
+          - <GOOGLE_CLIENT_ID>
+      - issuer: https://appleid.apple.com
 ```
 
-The example above demonstrates the default list of trusted providers.
-
 ## Identity inception
 
 The simplest way to establish a relationship between an Identity and an entity representing a user

package/documentation/octets.md

@@ -23,7 +23,7 @@ If request's `content-type` is not acceptable, or if the request body does not p
 the [validation](/extensions/storages/readme.md#async-putpath-string-stream-readable-type-typecontrol-maybeentry),
 the request is rejected with a `415 Unsupported Media Type` response.
 
-The value of the directive is an object with the following properties:
+The value of the directive is `null` or an object with the following properties:
 
 - `accept`: a media type or an array of media types that are acceptable.
   If the `accept` property is not specified, any media type is acceptable (which is the default).
@@ -43,43 +43,27 @@ The value of the directive is an object with the following properties:
         analyze: images.analyze
 ```
 
-### Workflows
-
-A workflow is a list of endpoints to be called.
-The following input will be passed to each endpoint:
-
-```yaml
-storage: string
-path: string
-entry: Entry
-```
-
-See [Entry](/extensions/storages/readme.md#entry) and an
-example [workflow step processor](../features/steps/components/octets.tester).
+Non-standard `content-meta` header can be used
+to set initial [metadata](/extensions/storages/readme.md#entry) value for the Entry.
 
-A _workflow unit_ is an object with keys referencing the workflow step identifier, and an endpoint
-as value.
-Steps within a workflow unit are executed in parallel.
+The value of the `content-meta` header is a comma-separated list of key-value string pairs.
+If no value is provided for a key, the string `true` is used.
 
-```yaml
-octets:store:
-  workflow:
-    resize: images.resize
-    analyze: images.analyze
+```http
+POST /images/ HTTP/1.1
+content-type: image/jpeg
+content-meta: foo, bar=baz
+content-meta: baz=1
 ```
 
-A workflow can be a single unit, or an array of units.
-If it's an array, the workflow units are executed in sequence.
-
 ```yaml
-octets:store:
-  workflow:
-    - optimize: images.optimize   # executed first
-    - resize: images.resize       # executed second
-      analyze: images.analyze     # executed in parallel with `resize`
+meta:
+  foo: 'true'
+  bar: 'baz'
+  baz: '1'
 ```
 
-If one of the workflow units returns an error, the execution of the workflow is interrupted.
+If the Entry already exists, the `content-meta` header is ignored.
 
 ### Response
 
@@ -114,9 +98,9 @@ created: 1698004822358
 optimize: null
 --cut
 error:
-step: resize
-code: TOO_SMALL
-message: Image is too small
+  step: resize
+  code: TOO_SMALL
+  message: Image is too small
 --cut--
 ```
 
@@ -147,26 +131,42 @@ The value of the directive is an object with the following properties:
         meta: true  # allow access to an Entry
 ```
 
-To access an Entry, the request path must be suffixed with `:meta`:
+The `octets:fetch: ~` declaration is equivalent to defaults.
+
+To access an Entry, the `accept` request header must contain the `octets.entry` subtype
+in
+the `toa` [vendor tree](https://datatracker.ietf.org/doc/html/rfc6838#section-3.2):
 
 ```http
-GET /images/eecd837c:meta HTTP/1.1
+GET /images/eecd837c HTTP/1.1
+accept: application/vnd.toa.octets.entry+yaml
 ```
 
-The `octets:fetch: ~` declaration is equivalent to defaults.
-
 ## `octets:list`
 
 Lists the entries stored under the request path.
 
+The value of the directive is an object with the following properties:
+
+- `meta`: `boolean` indicating whether the list of Entries is accessible.
+  Defaults to `false`, which means that only entry identifiers are returned.
+
 ```yaml
 /images:
   octets:context: images
   GET:
-    octets:list: ~
+    octets:list:
+      meta: true
 ```
 
-Responds with a list of entry identifiers.
+The `octets:list: ~` declaration is equivalent to defaults.
+
+To access a list of Entries, the `accept` request header must contain the `octets.entries` subtype:
+
+```http
+GET /images/ HTTP/1.1
+accept: application/vnd.toa.octets.entries+yaml
+```
 
 ## `octets:delete`
 
@@ -179,6 +179,20 @@ Delete the entry corresponding to the request path.
     octets:delete: ~
 ```
 
+The value of the directive may contain a [workflow](#workflows) declaration, to be executed before
+the entry is deleted.
+
+```yaml
+/images:
+  octets:context: images
+  DELETE:
+    octets:delete:
+      workflow:
+        cleanup: images.cleanup
+```
+
+The error returned by the workflow prevents the deletion of the entry.
+
 ## `octets:permute`
 
 Performs
@@ -194,3 +208,42 @@ under the request path.
 ```
 
 The request body must be a list of entry identifiers.
+
+## Workflows
+
+A workflow is a list of endpoints to be called.
+The following input will be passed to each endpoint:
+
+```yaml
+storage: string
+path: string
+entry: Entry
+parameters: Record<string, string> # route parameters
+```
+
+See [Entry](/extensions/storages/readme.md#entry) and an
+example [workflow step processor](../features/steps/components/octets.tester).
+
+A _workflow unit_ is an object with keys referencing the workflow step identifier, and an endpoint
+as value.
+Steps within a workflow unit are executed in parallel.
+
+```yaml
+octets:store:
+  workflow:
+    resize: images.resize
+    analyze: images.analyze
+```
+
+A workflow can be a single unit, or an array of units.
+If it's an array, the workflow units are executed in sequence.
+
+```yaml
+octets:store:
+  workflow:
+    - optimize: images.optimize   # executed first
+    - resize: images.resize       # executed second
+      analyze: images.analyze     # executed in parallel with `resize`
+```
+
+If one of the workflow units returns an error, the execution of the workflow is interrupted.

package/documentation/protocol.md

@@ -27,7 +27,8 @@ foo: bar
 ### Multipart types
 
 Multipart responses are endoded using content negotiation,
-and the `content-type` of the response is set to one of the custom `multipart/` subtypes, corresponding to the type of
+and the `content-type` of the response is set to one of the custom `multipart/` subtypes,
+corresponding to the type of
 the parts:
 
 | Response type       | Part type             |
@@ -60,3 +61,22 @@ See also:
 - [Multipart Content-Type](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) at W3C
 - [Content-Type: multipart](https://learn.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/aa493937(v=exchg.140))
   at Microsoft
+
+## CORS
+
+[CORS](https://www.w3.org/TR/2020/SPSD-cors-20200602/) is supported,
+credentials, any `origin`, and any request header fields are allowed.
+
+The following request headers are allowed:
+
+- `accept`
+- `authorization`
+- `content-type`
+- headers used by the [`vary:embed` directive](vary.md#embeddings)
+
+The following response headers are exposed:
+
+- `authorization`
+- `content-type`
+- `content-length`
+- `etag`

package/documentation/query.md

@@ -107,7 +107,7 @@ Operation call will have the following query criteria:
 criteria: state==hot;type==cool;rank=5
 ```
 
-### POST method
+#### POST method
 
 `POST` method semantically used to create a new entity instance, that is, calling a Transition
 without Query.

package/documentation/vary.md

@@ -0,0 +1,69 @@
+# HTTP request details
+
+The `vary` directives family provides the capability to include HTTP request details as input for an
+operation call.
+
+## TL;DR
+
+```yaml
+exposition:
+  realms:
+    toa: the.toa.io
+  /:
+    vary:languages: [en, fr]
+    GET:
+      vary:embed:
+        lang: language # predefined embeddings
+        realm: realm
+        token: :x-access-token # raw header value
+      endpoint: dummies.get
+```
+
+## Embeddings
+
+Request parts are embedded into the operation call according to the mapping
+defined by the `vary:embed` directive.
+The keys in the embedding map are the names of the input properties details to be embedded to,
+and the values are the names of the embedding functions.
+If the value is an array, the first non-empty embedding function's result is used.
+
+> If a property is already present in the input, the embedded value will overwrite its current
+> value.
+
+### Realm
+
+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.
+
+### Language
+
+The `language` embedding substitutes the most matching language code based on the `accept-language`
+request header and a list of supported languages defined by the `vary:languages` directive, and also
+adds `accept-language` to the `vary` HTTP response header value.
+If neither of the supported languages matches, the first supported language is used.
+
+### 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.
+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).
+
+[Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are embedded
+as a comma-separated list.
+
+### Fallbacks
+
+If the embedding function is an array, the first non-empty resolved value is used.
+
+```yaml
+vary:embed:
+  ip: # fallbacks
+    - :CloudFront-Viewer-Address
+    - :CF-Connecting-IP
+    - :X-Appengine-User-IP
+```

package/features/cors.feature

@@ -0,0 +1,72 @@
+Feature: CORS Support
+
+  Scenario: Using CORS
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        /foo:
+          GET:
+            dev:stub: Hello
+      """
+    When the following request is received:
+      """
+      OPTIONS / HTTP/1.1
+      origin: https://hello.world
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      access-control-allow-origin: https://hello.world
+      access-control-allow-methods: GET, POST, PUT, PATCH, DELETE
+      access-control-allow-headers: accept, authorization, content-type
+      access-control-allow-credentials: true
+      access-control-max-age: 3600
+      cache-control: public, max-age=3600
+      vary: origin
+      """
+    When the following request is received:
+      """
+      GET /foo/ HTTP/1.1
+      origin: https://hello.world
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      access-control-allow-origin: https://hello.world
+      access-control-expose-headers: authorization, content-type, content-length, etag
+      vary: origin
+      """
+
+  Scenario: Errors contain CORS headers
+    Given the annotation:
+      """yaml
+      /:
+        /foo:
+          GET:
+            dev:stub: Hello
+      """
+    When the following request is received:
+      """
+      GET /bar/ HTTP/1.1
+      origin: https://hello.world
+      """
+    Then the following reply is sent:
+      """
+      404 Not Found
+      access-control-allow-origin: https://hello.world
+      access-control-expose-headers: authorization, content-type, content-length, etag
+      vary: origin
+      """
+    When the following request is received:
+      """
+      GET /foo/ HTTP/1.1
+      origin: https://hello.world
+      """
+    Then the following reply is sent:
+      """
+      401 Unauthorized
+      access-control-allow-origin: https://hello.world
+      access-control-expose-headers: authorization, content-type, content-length, etag
+      vary: origin
+      """

package/features/identity.feature

@@ -17,7 +17,7 @@ Feature: Identity resource
     Then the following reply is sent:
       """
       200 OK
-      authorization: Token ${{ token }}
+      authorization: Token ${{ User.token }}
 
       id: efe3a65ebbee47ed95a73edd911ea328
       roles:
@@ -27,14 +27,30 @@ Feature: Identity resource
     When the following request is received:
       """
       GET /identity/ HTTP/1.1
-      authorization: Token ${{ token }}
+      authorization: Token ${{ User.token }}
       accept: application/yaml
       """
     Then the following reply is sent:
       """
       200 OK
 
-      id: efe3a65ebbee47ed95a73edd911ea328
+      id: ${{ User.id }}
+      roles:
+        - developer
+        - system:identity
+      """
+    # checking that it returns the same id for given token
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      authorization: Token ${{ User.token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: ${{ User.id }}
       roles:
         - developer
         - system:identity