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

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

@@ -0,0 +1,135 @@
+'use strict'
+
+const { Readable } = require('node:stream')
+const { posix } = require('node:path')
+const { Err } = require('error-value')
+const { match } = require('matchacho')
+
+async function put (input, context) {
+  const { storage, request, location, accept, limit, trust } = input
+  const url = request.url
+  const id = request.headers['content-id']
+  const claim = request.headers['content-type']
+  const attributes = parseAttributes(request.headers['content-attributes'])
+  const reference = request.headers['content-location']
+
+  /** @type {Readable} */
+  let body = request
+
+  const options = { claim, accept, attributes }
+
+  if (id !== undefined) {
+    if (!ID_RX.test(id))
+      return ERR_INVALID_ID
+
+    options.id = id
+  }
+
+  if (reference !== undefined) {
+    const length = Number.parseInt(request.headers['content-length'])
+
+    if (length !== 0)
+      return ERR_LENGTH
+
+    if (!trusted(reference, trust))
+      return ERR_UNTRUSTED
+
+    body = await download(reference)
+
+    if (body instanceof Error)
+      return body
+
+    options.origin = reference
+  }
+
+  if (limit !== undefined)
+    options.limit = limit
+
+  const path = posix.resolve(url, location ?? '.')
+
+  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 = new Err('LOCATION_UNTRUSTED', 'Location is not trusted')
+const ERR_LENGTH = new Err('LOCATION_LENGTH', 'Content-Length must be 0 when Content-Location is used')
+const ERR_UNAVAILABLE = new Err('LOCATION_UNAVAILABLE', 'Location is not available')
+const ERR_INVALID_ID = new Err('INVALID_ID', 'Invalid Content-ID')
+
+const ID_RX = /^[a-zA-Z0-9-_]{1,32}$/
+
+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,11 @@ 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-cacheable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
+
+### `anyone`
+
+Grants access if its value is `true` and valid credentials were provided.
 
 ### `id`
 
@@ -37,11 +41,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 +57,118 @@ 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
+```
+
+### `claims`
+
+Grants access if `Bearer` authentication scheme is used
+and the Token's claims matches the specified values.
+
+```yaml
+/:
+  auth:claims:
+    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 the request authority:
+
+```yaml
+/secrets/:org-id:
+  auth:claims:
+    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:claims:
+    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`.
 
+### `input`
+
+Restricts access based on the request body (which must be an object).
+
+```yaml
+/commits/:id:
+  PUT:
+    auth:role: [developer, reviewer]
+    auth:input:
+      - prop: approved
+        role: reviewer
+      - prop: message
+        role: developer
+```
+
+The example above restricts access to the `approved` property of the request body to the identity
+with the `reviewer` role, and the `message` property to the identity with the `developer` role.
+
+> `auth:input` directive does not grant access by itself.
+
+### `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 +178,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 +194,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,48 @@
+# 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
+```
+
+## Mappings
+
+To pass the requested authority to the operation call, [`map:authority` directive](map#embeddings)
+can be used.
+
+```yaml
+# manifest.toa.yaml
+
+exposition:
+  /:
+    GET:
+      map:authority: hostname
+      endpoint: observe
+```
+
+If the value of the `authority` pseudo-header is not present in the `authorities` definition,
+then the value 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`