@toa.io/extensions.exposition 1.0.0-alpha.9 → 1.0.0-alpha.91

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

@@ -4,24 +4,22 @@ name: storage
 storages: ~
 
 operations:
-  store:
+  put:
     bindings: ~
     input:
       storage*: string
       request*: ~
       accept: string
-      meta: <string>
-  fetch: &simple
+      limit: number
+      trust: ~ # array of strings or regular expressions
+    errors:
+      - LOCATION_UNTRUSTED
+      - LOCATION_LENGTH
+      - LOCATION_UNAVAILABLE
+  get: &simple
     bindings: ~
     input:
       storage*: string
       path*: string
-  get: *simple
-  list: *simple
+  head: *simple
   delete: *simple
-  permute:
-    bindings: ~
-    input:
-      storage*: string
-      path*: string
-      list*: [string]

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

@@ -1,7 +1,7 @@
 'use strict'
 
-function get (input, context) {
-  return context.storages[input.storage].get(input.path)
+async function get (input, context) {
+  return await context.storages[input.storage].get(input.path)
 }
 
-exports.computation = get
+exports.effect = get

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

@@ -0,0 +1,7 @@
+'use strict'
+
+async function head (input, context) {
+  return await context.storages[input.storage].head(input.path)
+}
+
+exports.computation = head

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

@@ -0,0 +1,121 @@
+'use strict'
+
+const { Readable } = require('node:stream')
+const { Err } = require('error-value')
+const { match } = require('matchacho')
+
+async function put (input, context) {
+  const { storage, request, accept, limit, trust } = input
+  const path = request.url
+  const claim = request.headers['content-type']
+  const attributes = parseAttributes(request.headers['content-attributes'])
+  const location = request.headers['content-location']
+
+  /** @type {Readable} */
+  let body = request
+
+  const options = { claim, accept, attributes }
+
+  if (location !== undefined) {
+    const length = Number.parseInt(request.headers['content-length'])
+
+    if (length !== 0)
+      return ERR_LENGTH
+
+    if (!trusted(location, trust))
+      return ERR_UNTRUSTED
+
+    body = await download(location)
+
+    if (body instanceof Error)
+      return body
+
+    options.origin = location
+  }
+
+  if (limit !== undefined)
+    options.limit = limit
+
+  return context.storages[storage].put(path, body, options)
+}
+
+/**
+ * @param {string | string[] | undefined} values
+ * @returns {Record<string, string>}
+ */
+function parseAttributes (values) {
+  const attributes = {}
+
+  if (values === undefined)
+    return attributes
+
+  if (typeof values === 'string')
+    values = values.split(',')
+
+  for (const pair of values) {
+    const eq = pair.indexOf('=')
+    const key = (eq === -1 ? pair : pair.slice(0, eq)).trim()
+
+    attributes[key] = eq === -1 ? 'true' : pair.slice(eq + 1).trim()
+  }
+
+  return attributes
+}
+
+/**
+ * @param {string} location
+ * @return {Readable | Error}
+ */
+async function download (location) {
+  const response = await fetch(location)
+
+  if (!response.ok)
+    return ERR_UNAVAILABLE
+
+  return response.body === null ? ERR_UNAVAILABLE : Readable.fromWeb(
+    /** @type {import('node:stream/web').ReadableStream} **/ response.body)
+
+}
+
+/**
+ * @param {string} location
+ * @param {Trust | undefined} trust
+ * @return {boolean}
+ */
+function trusted (location, trust) {
+  if (trust === undefined)
+    return false
+
+  const url = toURL(location)
+
+  if (url === null)
+    return false
+
+  for (const permission of trust) {
+    const ok = match(permission,
+      String, (origin) => url.origin === origin,
+      RegExp, (pattern) => pattern.test(url.origin))
+
+    if (ok)
+      return true
+  }
+
+  return false
+}
+
+function toURL (location) {
+  try {
+    return new URL(location)
+  } catch (error) {
+    return null
+  }
+}
+
+const ERR_UNTRUSTED = Err('LOCATION_UNTRUSTED', 'Location is not trusted')
+const ERR_LENGTH = Err('LOCATION_LENGTH', 'Content-Length must be 0 when Content-Location is used')
+const ERR_UNAVAILABLE = Err('LOCATION_UNAVAILABLE', 'Location is not available')
+
+exports.effect = put
+
+/** @typedef {Array<string | RegExp>} Trust */
+/** @typedef {import('node:stream').Readable} Readable */

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`
 
@@ -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
@@ -56,46 +53,97 @@ 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
-
-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`.
 
 Read [Roles](#roles) section for more details.
 
+#### Dynamic roles
+
+The `role` directive can be used with a placeholder in the route.
+
+```yaml
+/: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`
 
 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
 
 ```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`.
 
+### `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.
@@ -105,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.
@@ -124,18 +169,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,49 @@
+# 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
+```
+
+## 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
+```
+
+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
+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
+
+`/identity/tokens/`
 
-The `identity.roles` component manages roles of an Identity used by [access authorization](access.md#role).
+`POST` Issue a new token for the Identity. Request body is as follows:
+
+```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
 
-### Role resources
+The `identity.roles` component manages roles of an Identity used
+by [access authorization](access.md#role).
 
-#### `/identity/roles/:id/`
+### `/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.
@@ -304,3 +329,17 @@ roles:
   - developer
   - system:identity:roles
 ```
+
+When no credentials are provided, transient Identity is created.
+
+```http
+GET /identity/
+accept: application/yaml
+```
+
+```
+201 Created
+
+id: 332017649c814649b25ee466c1fe4534
+roles: []
+```

package/documentation/flow.md

@@ -0,0 +1,44 @@
+# Request flow
+
+## `flow:fetch`
+
+Fetches the content from the resource returned by the specified endpoint.
+
+The value of the directive is a `string` specifying endpoint to be called for the redirection
+request.
+
+Request `authority`, `path` and `parameters` are passed as input to the redirection endpoint,
+and it must return a URL `string`, an `Error` or an object with the following properties:
+
+```yaml
+url: string
+options?:
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+```
+
+If it returns a URL or Request, then the response to the specified request is returned as the
+response to the original request, along with the `content-type`, `content-length`, and `etag`
+headers.
+
+## `flow:compose`
+
+Compose an object from a response stream in object mode.
+
+The value of the directive is an object whose values are JavaScript expressions
+accessing the response stream objects composed into an array named `$`.
+
+```yaml
+flow:compose:
+  one: $[0].status
+  two: $[1].data.foo
+  three: $[2].amount
+```
+
+```yaml
+flow:compose:
+  sum: $[0].value + $[1].value
+```
+
+Be careful.