@toa.io/extensions.exposition 1.0.0-alpha.31 → 1.0.0-alpha.310

package/components/identity.tokens/source/types.ts

@@ -1,55 +0,0 @@
-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 {
-  revokedAt?: number
-}
-
-export interface Identity extends Record<string, any> {
-  id: string
-}
-
-export interface AuthenticateInput {
-  authority: string
-  credentials: string
-}
-
-export interface AuthenticateOutput {
-  identity: Identity
-  refresh: boolean
-}
-
-export interface EncryptInput {
-  authority: string
-  identity: Identity
-  lifetime?: number
-}
-
-export interface DecryptOutput {
-  authority: string
-  identity: Identity
-  iat: string
-  exp?: string
-  refresh: boolean
-}
-
-export interface Claim {
-  identity: Identity
-  aud: string
-  iat: string
-  exp?: string
-}

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

@@ -1,21 +0,0 @@
-namespace: octets
-name: storage
-
-storages: ~
-
-operations:
-  store:
-    bindings: ~
-    input:
-      storage*: string
-      request*: ~
-      accept: string
-      meta: <string>
-  fetch: &simple
-    bindings: ~
-    input:
-      storage*: string
-      path*: string
-  get: *simple
-  list: *simple
-  delete: *simple

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

@@ -1,7 +0,0 @@
-'use strict'
-
-function del (input, context) {
-  return context.storages[input.storage].delete(input.path)
-}
-
-exports.effect = del

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

@@ -1,46 +0,0 @@
-'use strict'
-
-const { posix } = require('node:path')
-const { Err } = require('error-value')
-
-async function fetch (input, context) {
-  const storage = context.storages[input.storage]
-  const basename = posix.basename(input.path)
-  const path = posix.dirname(input.path)
-  const [id, suffix] = split(basename)
-  const entry = await storage.get(posix.join(path, id))
-
-  if (entry instanceof Error)
-    return entry
-
-  let variant
-
-  if (suffix !== undefined) {
-    variant = entry.variants.find((variant) => variant.name === suffix)
-
-    if (variant === undefined)
-      return NOT_FOUND
-  }
-
-  const stream = await storage.fetch(input.path)
-
-  if (stream instanceof Error)
-    return stream
-
-  const { type, size } = variant ?? entry
-
-  return { stream, checksum: entry.id, type, size }
-}
-
-function split (basename) {
-  const dot = basename.indexOf('.')
-
-  if (dot === -1)
-    return [basename, undefined]
-  else
-    return [basename.slice(0, dot), basename.slice(dot + 1)]
-}
-
-const NOT_FOUND = Err('NOT_FOUND')
-
-exports.effect = fetch

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

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

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

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

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

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

package/cucumber.js

@@ -1,7 +0,0 @@
-module.exports = {
-  default: {
-    requireModule: ['ts-node/register'],
-    require: ['./features/**/*.ts'],
-    failFast: true
-  }
-}

package/documentation/access.md

@@ -1,266 +0,0 @@
-# Access authorization
-
-> The Authorization is intrinsically linked with the [Authentication](./identity.md).
-
-<a href="">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="./.assets/ia3-dark.jpg">
-    <img alt="IA3" width="600" height="507" src="./.assets/ia3-light.jpg">
-  </picture>
-</a>
-
-## Directives
-
-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.
-
-> The Authorization directive provider is named `authorization`,
-> so the full names of the directives are `authorization:{directive}`.
-
-### `anonymous`
-
-Grants access if its value is `true` and no credentials were provided[^1].
-
-[^1]: Credentials in the request make the
-response [non-cachable](https://datatracker.ietf.org/doc/html/rfc7234#section-3).
-
-### `id`
-
-Grants access if resolved Identity matches the value of the URL path segment placeholder named after
-the directive's value.
-
-#### Example
-
-Given the Route declaration and corresponding HTTP request:
-
-```yaml
-# context.toa.yaml
-
-exposition:
-  /users/:user-id:
-    id: "user-id"
-```
-
-```http
-GET /users/87480f2bd88048518c529d7957475ecd/
-Authorization: ...
-```
-
-For this request access will be granted if the resolved Identity value
-is `87480f2bd88048518c529d7957475ecd`.
-
-### `role`
-
-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]
-```
-
-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
-# 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.
-
-#### Example
-
-```yaml
-# context.toa.yaml
-
-exposition:
-  /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).
-
-### Hierarchies
-
-Role values are alphanumeric tokens separated by a colon (`:`).
-Each token defines a Role Scope, forming a hierarchy.
-A Role matches the value of the `rule` directive if that Role has the specified Scope in a
-directive.
-
-#### Example
-
-```yaml
-# context.toa.yaml
-
-/exposition:
-  /commits/:user-id:
-    role: developer:senior
-```
-
-The example above defines a `role` directive with the specified `developer:senior` Role Scope.
-This directive matches the roles `developer:senior` and `developer`,
-but it **does not** match the Role `developer:senior:javascript`.
-In other words, the Identity must have a specified or more general Role.
-
-<a href="https://miro.com/app/board/uXjVOoy0ImU=/?moveToWidget=3458764556008550471&cot=14">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset=".assets/role-scopes-dark.jpg">
-    <img alt="IA3" width="600" height="425" src=".assets/role-scopes-light.jpg">
-  </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).
-
-## Policies
-
-Component Resource branches cannot have authorization directives.
-Instead, they must declare Authorization Policies using `policy` directive to
-be attached in the Context to a Resource Tree as a set of Authorization Directives
-using `attachment` directive.
-
-This restriction provides a separation of concerns, allowing components to be reused in different
-Contexts with varying
-access rules.
-
-```yaml
-# manifest.toa.yaml
-
-name: posts
-
-exposition:
-  /:user-id:
-    GET:
-      endpoint: observe
-      policy: read:list
-    POST:
-      endpoint: transit
-      policy: post:submit
-    /:post-id:
-      GET:
-        endpoint: observe
-        policy: read:post
-      PUT:
-        endpoint: assign
-        policy: post:edit
-```
-
-```yaml
-# context.toa.yaml
-
-exposition:
-  /posts:
-    attachment:
-      read:
-        anonymous: true
-      post:
-        id: user-id
-      post:edit:
-        role: app:posts:editor
-```
-
-Policy values as well as [Role](#roles) values define hierarchical Policy Scopes.
-
-In the example above:
-
-- an Attachment `read` attaches Directive `anonymous: true` to both `read:list` and `read:post`
-  Policy Scopes.
-  This means that a list of posts and each post can be accessed without authorization.
-- an Attachment `post` attaches Directive `id: user-id` to both `post:submit` and `post:edit` Policy
-  Scopes.
-  This means that an Identity can submit and edit their own posts.
-- an Attachment `post:edit` attaches Directive `role: app:posts:editor` to `post:edit` Policy Scope.
-  This means that an identity with the role scope `app:posts:editor` can edit posts by any author,
-  in addition to the fact that the author themselves can do this thanks to the previous Attachment.
-
-### Nesting
-
-Policies are namespace-scoped, meaning they can be attached to any Route under the
-corresponding `/{namespace}` prefix.
-
-Attachment is applied to the node where it is declared, as well as its nested nodes.
-Directives of the Attachment are applied to the node where the attached Policies are declared, as
-well as their nested nodes.
-
-Here's an example of how this works:
-
-```yaml
-# manifest.toa.yaml
-
-name: posts
-
-exposition:
-  /:user-id:
-    GET:
-      endpoint: observe
-      policy: read
-  /:user-id/:post-id:
-    GET:
-      endpoint: observe
-      policy: read
-```
-
-```yaml
-# context.toa.yaml
-
-exposition:
-  /posts:
-    /:user-id:
-      attachment:
-        read:
-          anonymous: true
-    /:user-id/:post-id:
-      attachment:
-        read:
-          role: reader
-```
-
-In the example above, the same Policy `read` is attached to two Routes with different Directives.
-
-The following example demonstrates the attachment of the `read` Policy to both Routes with the same
-Directive:
-
-```yaml
-# context.toa.yaml
-
-exposition:
-  /posts:
-    attachment:
-      read:
-        anonymous: true
-```

package/documentation/authorities.md

@@ -1,53 +0,0 @@
-# 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

@@ -1,49 +0,0 @@
-# Caching
-
-Directive family `cache` implements the
-HTTP [Cache-Control](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9).
-
-## `cache:control`
-
-Sets the value of the `Cache-Control` header
-for [successful responses](https://datatracker.ietf.org/doc/html/rfc2616#section-10.2)
-to [safe HTTP methods](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP).
-
-```yaml
-/:
-  GET:
-    cache:control: max-age=60000
-```
-
-### Implicit modifications
-
-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.
-  This is done to prevent the storage of authentication tokens in shared caches.
-- 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`
-
-Same as `cache:control` without implicit modifications.
-
-```yaml
-/:
-  GET:
-    cache:exact: public, max-age=60000
-```
-
-## References
-
-- HTTP 14.9.1 [What is cacheable](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9.1)
-- See also [features](/extensions/exposition/features/cache.feature)