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

package/components/identity.tokens/source/decrypt.test.ts

@@ -7,6 +7,8 @@ let configuration: Configuration
 let context: Context
 let encrypt: Encrypt
 
+const authority = generate()
+
 beforeEach(() => {
   configuration = {
     key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog',
@@ -25,14 +27,14 @@ it('should decrypt', async () => {
   const identity: Identity = { id: generate() }
   const lifetime = 100
 
-  const reply = await encrypt.execute({ identity, lifetime })
+  const reply = await encrypt.execute({ authority, identity, lifetime })
 
   if (reply === undefined)
     throw new Error('?')
 
   const decrypted = await decrypt(reply, context)
 
-  expect(decrypted).toMatchObject({ identity, refresh: false })
+  expect(decrypted).toMatchObject({ authority, identity, refresh: false })
 })
 
 it('should decrypt with key1', async () => {
@@ -48,7 +50,7 @@ it('should decrypt with key1', async () => {
   const identity: Identity = { id: generate() }
   const lifetime = 100
 
-  const encrypted = await encrypt.execute({ identity, lifetime })
+  const encrypted = await encrypt.execute({ authority, identity, lifetime })
 
   if (encrypted === undefined)
     throw new Error('?')

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

@@ -2,8 +2,7 @@ import { V3 } from 'paseto'
 import { type Maybe } from '@toa.io/types'
 import { type Context, type Claim, type DecryptOutput } from './types'
 
-export async function computation (token: string, context: Context):
-Promise<Maybe<DecryptOutput>> {
+export async function computation (token: string, context: Context): Promise<Maybe<DecryptOutput>> {
   let refresh = false
   let claim = await decrypt(token, context.configuration.key0)
 
@@ -14,12 +13,14 @@ Promise<Maybe<DecryptOutput>> {
 
   if (claim === null)
     return ERR_INVALID_TOKEN
-  else return {
-    identity: claim.identity,
-    iat: claim.iat,
-    exp: claim.exp,
-    refresh
-  }
+  else
+    return {
+      authority: claim.aud,
+      identity: claim.identity,
+      iat: claim.iat,
+      exp: claim.exp,
+      refresh
+    }
 }
 
 async function decrypt (token: string, key: string): Promise<Claim | null> {

package/components/identity.tokens/source/encrypt.test.ts

@@ -1,3 +1,4 @@
+import assert from 'node:assert'
 import { generate } from 'randomstring'
 import { timeout } from '@toa.io/generic'
 import { Effect as Encrypt } from './encrypt'
@@ -7,6 +8,7 @@ import { type Context, type Identity } from './types'
 let encrypt: Encrypt
 
 const context: Context = {} as unknown as Context
+const authority = generate()
 
 beforeEach(() => {
   context.configuration = {
@@ -22,14 +24,36 @@ beforeEach(() => {
 it('should encrypt with given lifetime', async () => {
   const identity: Identity = { id: generate() }
   const lifetime = 0.1
-  const encrypted = await encrypt.execute({ identity, lifetime })
+
+  const encrypted = await encrypt.execute({
+    authority,
+    identity,
+    lifetime
+  })
 
   if (encrypted === undefined)
     throw new Error('?')
 
-  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ identity })
+  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ authority, identity })
 
   await timeout(lifetime * 1000)
 
   await expect(decrypt(encrypted, context)).resolves.toMatchObject({ message: 'INVALID_TOKEN' })
 })
+
+it('should encrypt without lifetime INSECURE', async () => {
+  const identity: Identity = { id: generate() }
+  const lifetime = 0
+
+  const encrypted = await encrypt.execute({
+    authority,
+    identity,
+    lifetime
+  })
+
+  const decrypted = await decrypt(encrypted, context)
+
+  assert.ok(!(decrypted instanceof Error))
+
+  expect(decrypted.identity).toMatchObject(identity)
+})

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

@@ -18,7 +18,11 @@ export class Effect implements Operation {
       ? undefined
       : new Date(Date.now() + lifetime).toISOString()
 
-    const payload: Partial<Claim> = { identity: input.identity, exp }
+    const payload: Partial<Claim> = {
+      identity: input.identity,
+      aud: input.authority,
+      exp
+    }
 
     return await V3.encrypt(payload, this.key)
   }

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

@@ -16,25 +16,31 @@ export interface Configuration {
 }
 
 export interface Entity {
-  identity: string
-  revokedAt: number
+  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
@@ -43,6 +49,7 @@ export interface DecryptOutput {
 
 export interface Claim {
   identity: Identity
+  aud: string
   iat: string
   exp?: string
 }

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

@@ -19,9 +19,3 @@ operations:
   get: *simple
   list: *simple
   delete: *simple
-  permute:
-    bindings: ~
-    input:
-      storage*: string
-      path*: string
-      list*: [string]

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

@@ -2,7 +2,7 @@
 
 function store (input, context) {
   const { storage, request, accept, meta } = input
-  const path = request.path
+  const path = request.url
   const claim = request.headers['content-type']
 
   return context.storages[storage].put(path, request, { claim, accept, meta })

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
@@ -142,7 +153,7 @@ using the `key0` configuration value as a secret.
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY
 ```
 
@@ -153,25 +164,22 @@ 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
 
 configuration:
-  identity.basic:
+  identity.tokens:
     lifetime: 2592000 # seconds, 30 days
     refresh: 600      # seconds, 10 minutes
 ```
@@ -199,7 +207,7 @@ the `key0` and `key1` values in order.
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY_2023Q3
     key1: $TOKEN_ENCRYPTION_KEY_2023Q2
 ```
@@ -231,7 +239,7 @@ The secret rotation is a 2-step process:
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY_2023Q3
     key1: $TOKEN_ENCRYPTION_KEY_2023Q4
 ```
@@ -244,18 +252,31 @@ configuration:
 # context.toa.yaml
 
 configuration:
-  identity.basic:
+  identity.tokens:
     key0: $TOKEN_ENCRYPTION_KEY_2023Q4
     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.