@toa.io/extensions.exposition 1.0.0-alpha.107 → 1.0.0-alpha.109

package/documentation/access.md

@@ -133,6 +133,26 @@ directives grant access. The value of the `rule` directive can be a single Rule
 
 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

package/documentation/identity.md

@@ -141,6 +141,9 @@ id: 2428c31ecb6e4a51a24ef52f0c4181b9
 As a result of processing the above request, the provided Basic credentials associated with the
 Identity `2428c31ecb6e4a51a24ef52f0c4181b9` are created.
 
+> `auth:incept` directive may have a `null` value, which means that the Identity will be created
+> without any associated entity.
+
 ## FAQ
 
 <dl>

package/features/auth.incept.feature

@@ -1,5 +1,37 @@
 Feature: Identity inception
 
+  Scenario: Non-associated Identity inception
+    Given the `identity.basic` database is empty
+    When the following request is received:
+      """
+      POST /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYXNzMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ token }}
+
+      id: ${{ id }}
+      roles: []
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjpwYXNzMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: ${{ id }}
+      roles: []
+      """
+
   Scenario: Creating new Identity using inception with Basic scheme
     Given the `users` is running with the following manifest:
       """yaml

package/features/auth.input.feature

@@ -0,0 +1,59 @@
+Feature: Input properties authorization
+
+  Background:
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username | password                                                     |
+      | 72cf9b0ab0ac4ab2b8036e4e940ddcae | nex       | root     | $2b$10$Qq/qnyyU5wjrbDXyWok14OnqAZv/z.pLhz.UddatjI6eHU/rFof4i |
+    And the `identity.roles` database contains:
+      | _id                              | identity                         | role  |
+      | 9c4702490ff84f2a9e1b1da2ab64bdd4 | 72cf9b0ab0ac4ab2b8036e4e940ddcae | app:b |
+
+  Scenario: Input properties authorization
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          io:input: [a, b]
+          io:output: [a, b]
+          anonymous: true
+          auth:role: app:b
+          auth:input:
+            - prop: b
+              role: app:b
+          PUT: parameters
+      """
+
+    When the following request is received:
+      """
+      PUT /echo/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/yaml
+
+      a: foo
+      b: bar
+      """
+    Then the following reply is sent:
+      """
+      403 Forbidden
+
+      Input property is not authorized
+      """
+    When the following request is received:
+      """
+      PUT /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic cm9vdDpzZWNyZXQ=
+      accept: application/yaml
+      content-type: application/yaml
+
+      a: foo
+      b: bar
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      a: foo
+      b: bar
+      """

package/features/cache.feature

@@ -42,7 +42,7 @@ Feature: Caching
       """
       200 OK
 
-      cache-control: private
+      cache-control: no-store
       """
 
   Scenario: Caching successful response
@@ -99,7 +99,7 @@ Feature: Caching
       """
       200 OK
       authorization: Token ${{ token }}
-      cache-control: private
+      cache-control: no-store
       """
     When the following request is received:
       """
@@ -190,7 +190,7 @@ Feature: Caching
       """
       200 OK
       authorization: Token ${{ token }}
-      cache-control: private
+      cache-control: no-store
       """
     When the following request is received:
       """
@@ -251,7 +251,7 @@ Feature: Caching
       """
       200 OK
       authorization: Token ${{ token }}
-      cache-control: private
+      cache-control: no-store
       """
     When the following request is received:
       """

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.107",
+  "version": "1.0.0-alpha.109",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -61,5 +61,5 @@
     "@types/negotiator": "0.6.1",
     "jest-esbuild": "0.3.0"
   },
-  "gitHead": "0c69afa09e2515ed76f88eaa9c9f5e5c97d8c5db"
+  "gitHead": "64010813141330312d1ae7ae4424b172bca3e451"
 }

package/source/HTTP/Context.ts

@@ -54,11 +54,12 @@ export class Context {
   }
 
   public async body<T> (): Promise<T> {
-    const value = await read(this)
+    let value = await read(this)
 
-    return this.pipelines.body.length === 0
-      ? value
-      : this.pipelines.body.reduce((value, transform) => transform(value), value)
+    for (const transform of this.pipelines.body)
+      value = await transform(value)
+
+    return value
   }
 
   private log (request: IncomingMessage): void {

package/source/directives/auth/Anonymous.ts

@@ -1,4 +1,4 @@
-import { type Directive, type Input } from './types'
+import { type Directive, type Context } from './types'
 
 export class Anonymous implements Directive {
   private readonly allow: boolean
@@ -7,8 +7,8 @@ export class Anonymous implements Directive {
     this.allow = allow
   }
 
-  public authorize (_: any, input: Input): boolean {
-    return 'authorization' in input.request.headers
+  public authorize (_: any, context: Context): boolean {
+    return 'authorization' in context.request.headers
       ? false
       : this.allow
   }

package/source/directives/auth/Anyone.ts

@@ -1,4 +1,4 @@
-import { type Directive, type Input } from './types'
+import { type Directive, type Context } from './types'
 
 export class Anyone implements Directive {
   private readonly allow: boolean
@@ -7,7 +7,7 @@ export class Anyone implements Directive {
     this.allow = allow
   }
 
-  public authorize (_: any, input: Input): boolean {
-    return input.identity !== null && this.allow
+  public authorize (_: any, context: Context): boolean {
+    return context.identity !== null && this.allow
   }
 }

package/source/directives/auth/Authorization.ts

@@ -12,9 +12,10 @@ import { Echo } from './Echo'
 import { Scheme } from './Scheme'
 import { Delegate } from './Delegate'
 import { Federation } from './Federation'
+import { Anyone } from './Anyone'
+import { Input } from './Input'
 import { split } from './split'
 import { PRIMARY, PROVIDERS } from './schemes'
-import { Anyone } from './Anyone'
 import type { Output } from '../../io'
 import type { Component } from '@toa.io/core'
 import type { Remotes } from '../../Remotes'
@@ -26,7 +27,7 @@ import type {
   Discovery,
   Extension,
   Identity,
-  Input,
+  Context,
   Remote,
   Schemes
 } from './types'
@@ -53,22 +54,24 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     return match(Class,
       Role, () => new Role(value as string | string[], this.discovery.roles),
       Rule, () => new Rule(value as Record<string, string>, this.create.bind(this)),
+      Input, () => new Input(value, this.create.bind(this)),
       Incept, () => new Incept(value as string, this.discovery),
       Delegate, () => new Delegate(value as string, this.discovery.roles),
       () => new Class(value))
   }
 
   public async preflight (directives: Directive[],
-    context: Input,
+    context: Context,
     parameters: Parameter[]): Promise<Output> {
     context.identity = await this.resolve(context.authority, context.request.headers.authorization)
+    directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
 
     for (const directive of directives) {
       const allow = await directive.authorize(context.identity, context, parameters)
 
       if (allow)
         if (this.permitted(context))
-          return directive.reply?.(context.identity) ?? null
+          return directive.reply?.(context) ?? null
         else
           throw new http.Forbidden()
     }
@@ -80,12 +83,12 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   }
 
   public async settle (directives: Directive[],
-    input: Input,
+    context: Context,
     response: http.OutgoingMessage): Promise<void> {
     await Promise.all(directives.map(async (directive) =>
-      directive.settle?.(input, response)))
+      directive.settle?.(context, response)))
 
-    const identity = input.identity
+    const identity = context.identity
 
     if (identity === null)
       return
@@ -98,7 +101,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     this.tokens ??= await this.discovery.tokens
 
     const token = await this.tokens.invoke<string>('encrypt', {
-      input: { authority: input.authority, identity }
+      input: { authority: context.authority, identity }
     })
 
     const authorization = `Token ${token}`
@@ -146,7 +149,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     return identity
   }
 
-  private permitted (context: Input): boolean {
+  private permitted (context: Context): boolean {
     const permissions = context.identity?.permissions
 
     if (permissions === undefined)
@@ -177,7 +180,8 @@ const constructors: Record<string, new (value: any, argument?: any) => Directive
   scheme: Scheme,
   echo: Echo,
   delegate: Delegate,
-  claims: Federation
+  claims: Federation,
+  input: Input
 }
 
 const REMOTES: Remote[] = ['basic', 'federation', 'tokens', 'roles', 'bans']

package/source/directives/auth/Delegate.ts

@@ -1,8 +1,7 @@
 import { BadRequest } from '../../HTTP'
-import { type Directive, type Identity } from './types'
 import { Role } from './Role'
+import type { Context, Directive, Identity } from './types'
 import type { Component } from '@toa.io/core'
-import type { Input } from '../../io'
 
 export class Delegate implements Directive {
   private readonly property: string
@@ -13,7 +12,7 @@ export class Delegate implements Directive {
     this.discovery = discovery
   }
 
-  public async authorize (identity: Identity | null, context: Input): Promise<boolean> {
+  public async authorize (identity: Identity | null, context: Context): Promise<boolean> {
     if (identity === null)
       return false
 

package/source/directives/auth/Echo.ts

@@ -1,26 +1,22 @@
-import { newid } from '@toa.io/generic'
+import { create } from './create'
 import type { OutgoingMessage } from '../../HTTP'
-import type { Directive, Identity, Input } from './types'
+import type { Directive, Identity, Context } from './types'
 
 export class Echo implements Directive {
-  public authorize (identity: Identity | null, input: Input): boolean {
-    if (identity === null && 'authorization' in input.request.headers)
+  public authorize (identity: Identity | null, context: Context): boolean {
+    if (identity === null && 'authorization' in context.request.headers)
       return false
 
-    input.identity ??= this.create()
+    context.identity ??= create()
 
     return true
   }
 
-  public reply (identity: Identity | null): OutgoingMessage {
-    const body = identity!
+  public reply (context: Context): OutgoingMessage {
+    const body = context.identity!
 
     return body.scheme === null
       ? { status: 201, body }
       : { body }
   }
-
-  private create (): Identity {
-    return { id: newid(), scheme: null, refresh: false, roles: [] }
-  }
 }

package/source/directives/auth/Federation.ts

@@ -1,5 +1,5 @@
 import assert from 'node:assert'
-import type { Directive, Identity, Input } from './types'
+import type { Directive, Identity, Context } from './types'
 import type { Parameter } from '../../RTD'
 
 export class Federation implements Directive {
@@ -12,7 +12,7 @@ export class Federation implements Directive {
     assert.ok(this.matchers.length > 0, '`auth:claims` requires at least one property defined')
   }
 
-  public authorize (identity: Identity | null, context: Input, parameters: Parameter[]): boolean {
+  public authorize (identity: Identity | null, context: Context, parameters: Parameter[]): boolean {
     if (identity === null || !('claims' in identity))
       return false
 
@@ -59,7 +59,7 @@ function matches (value: string | string[], reference: string): boolean {
     : value === reference
 }
 
-function codomain (iss: string, context: Input): boolean {
+function codomain (iss: string, context: Context): boolean {
   const hostname = new URL(iss).hostname
   const dot = hostname.indexOf('.')
   const basename = dot === -1 ? hostname : hostname.slice(dot)
@@ -67,7 +67,7 @@ function codomain (iss: string, context: Input): boolean {
   return context.authority.slice(-basename.length) === basename
 }
 
-type Matcher = (value: string | string[], context: Input, parameters: Parameter[]) => boolean
+type Matcher = (value: string | string[], context: Context, parameters: Parameter[]) => boolean
 
 interface Claims {
   iss: string

package/source/directives/auth/Id.ts

@@ -8,7 +8,7 @@ export class Id implements Directive {
     this.parameter = parameter
   }
 
-  public authorize (identity: Identity | null, _: any, parameters: Parameter[]): boolean {
+  public authorize (identity: Identity | null, _: unknown, parameters: Parameter[]): boolean {
     if (identity === null)
       return false
 

package/source/directives/auth/Incept.ts

@@ -1,31 +1,45 @@
+import assert from 'node:assert'
 import { type Maybe } from '@toa.io/types'
 import * as http from '../../HTTP'
-import { type Directive, type Discovery, type Identity, type Input, type Schemes } from './types'
+import { type Directive, type Discovery, type Identity, type Context, type Schemes } from './types'
 import { split } from './split'
+import { create } from './create'
 import { PROVIDERS } from './schemes'
 
 export class Incept implements Directive {
-  private readonly property: string
+  private readonly property: string | null
   private readonly discovery: Discovery
   private readonly schemes: Schemes = {} as unknown as Schemes
 
   public constructor (property: string, discovery: Discovery) {
+    assert.ok(property === null || typeof property === 'string',
+      '`auth:incept` value must be a string or null')
+
     this.property = property
     this.discovery = discovery
   }
 
-  public authorize (identity: Identity | null, input: Input): boolean {
-    return identity === null && 'authorization' in input.request.headers
+  public authorize (identity: Identity | null, context: Context): boolean {
+    return identity === null && 'authorization' in context.request.headers
+  }
+
+  public reply (context: Context): http.OutgoingMessage | null {
+    if (this.property !== null)
+      return null
+
+    const body = create(context.request.headers.authorization)
+
+    return { body }
   }
 
-  public async settle (input: Input, response: http.OutgoingMessage): Promise<void> {
-    const id = response.body?.[this.property]
+  public async settle (context: Context, response: http.OutgoingMessage): Promise<void> {
+    const id = response.body?.[this.property ?? 'id']
 
     if (id === undefined)
       throw new http.Conflict('Identity inception has failed as the response body ' +
         `does not contain the '${this.property}' property`)
 
-    const [scheme, credentials] = split(input.request.headers.authorization!)
+    const [scheme, credentials] = split(context.request.headers.authorization!)
     const provider = PROVIDERS[scheme]
 
     this.schemes[scheme] ??= await this.discovery[provider]
@@ -33,7 +47,7 @@ export class Incept implements Directive {
     const identity = await this.schemes[scheme]
       .invoke<Maybe<Identity>>('incept', {
       input: {
-        authority: input.authority,
+        authority: context.authority,
         id,
         credentials
       }
@@ -42,7 +56,7 @@ export class Incept implements Directive {
     if (identity instanceof Error)
       throw new http.UnprocessableEntity(identity)
 
-    input.identity = identity
-    input.identity.scheme = scheme
+    context.identity = identity
+    context.identity.scheme = scheme
   }
 }

package/source/directives/auth/Input.ts

@@ -0,0 +1,72 @@
+import { Forbidden } from '../../HTTP'
+import type { Parameter } from '../../RTD'
+import type { Context, Directive, Identity, Create } from './types'
+
+export class Input implements Directive {
+  public priority = 0
+  private readonly statements: Statement[] = []
+
+  public constructor (declarations: Declaration[], create: Create) {
+    this.statements = declarations.map((declaration) => new Statement(declaration, create))
+  }
+
+  public async authorize
+  (identity: Identity | null, context: Context, parameters: Parameter[]): Promise<boolean> {
+    context.pipelines.body.push(async (body) => this.check(identity, context, parameters, body))
+
+    return false
+  }
+
+  // eslint-disable-next-line max-params
+  private async check (identity: Identity | null, context: Context, parameters: Parameter[], body: unknown): Promise<unknown> {
+    if (body === undefined || body === null || body.constructor !== Object)
+      return body
+
+    const settled = await Promise.allSettled(this.statements.map(async (statement) =>
+      statement.check(identity, context, parameters, body as Body)))
+
+    for (const result of settled)
+      if (result.status === 'rejected')
+        throw result.reason
+
+    return body
+  }
+}
+
+class Statement {
+  private readonly properties: string[]
+  private readonly directives: Directive[] = []
+
+  public constructor ({ prop, ...directives }: Declaration, create: Create) {
+    this.properties = typeof prop === 'string' ? [prop] : prop
+
+    for (const [name, value] of Object.entries(directives)) {
+      const directive = create(name, value)
+
+      this.directives.push(directive)
+    }
+  }
+
+  // eslint-disable-next-line max-params
+  public async check (identity: Identity | null, context: Context, parameters: Parameter[], body: Body): Promise<void> {
+    const match = this.properties.some((property) => property in body)
+
+    if (!match)
+      return
+
+    for (const directive of this.directives) {
+      const authorized = await directive.authorize(identity, context, parameters)
+
+      if (!authorized)
+        throw new Forbidden('Input property is not authorized')
+    }
+  }
+}
+
+interface Declaration {
+  [key: Exclude<string, 'prop'>]: unknown
+
+  prop: string | string[]
+}
+
+type Body = Record<string, unknown>

package/source/directives/auth/Rule.ts

@@ -1,5 +1,5 @@
 import { type Parameter } from '../../RTD'
-import type { Input, Directive, Identity } from './types'
+import type { Context, Directive, Identity, Create } from './types'
 
 export class Rule implements Directive {
   private readonly directives: Directive[] = []
@@ -13,9 +13,9 @@ export class Rule implements Directive {
   }
 
   public async authorize
-  (identity: Identity | null, input: Input, parameters: Parameter[]): Promise<boolean> {
+  (identity: Identity | null, context: Context, parameters: Parameter[]): Promise<boolean> {
     for (const directive of this.directives) {
-      const authorized = await directive.authorize(identity, input, parameters)
+      const authorized = await directive.authorize(identity, context, parameters)
 
       if (!authorized)
         return false
@@ -24,5 +24,3 @@ export class Rule implements Directive {
     return true
   }
 }
-
-type Create = (name: string, value: any, ...args: any[]) => Directive

package/source/directives/auth/Scheme.ts

@@ -1,5 +1,5 @@
 import * as http from '../../HTTP'
-import { type Directive, type Identity, type Input } from './types'
+import { type Directive, type Identity, type Context } from './types'
 import { split } from './split'
 
 export class Scheme implements Directive {
@@ -11,11 +11,11 @@ export class Scheme implements Directive {
     this.Scheme = scheme[0].toUpperCase() + scheme.substring(1)
   }
 
-  public authorize (_: Identity | null, input: Input): boolean {
-    if (input.request.headers.authorization === undefined)
+  public authorize (_: Identity | null, context: Context): boolean {
+    if (context.request.headers.authorization === undefined)
       return false
 
-    const [scheme] = split(input.request.headers.authorization)
+    const [scheme] = split(context.request.headers.authorization)
 
     if (scheme !== this.scheme)
       throw new http.Forbidden(this.Scheme +

package/source/directives/auth/create.ts

@@ -0,0 +1,10 @@
+import { newid } from '@toa.io/generic'
+import type { Identity } from './types'
+
+export function create (credentials?: string): Identity {
+  const scheme = credentials === undefined
+    ? null
+    : credentials.split(' ')[0]
+
+  return { id: newid(), scheme, refresh: false, roles: [] }
+}

package/source/directives/auth/types.ts

@@ -5,15 +5,17 @@ import type * as http from '../../HTTP'
 import type * as io from '../../io'
 
 export interface Directive {
+  priority?: number
+
   authorize: (
     identity: Identity | null,
-    input: Input,
+    context: Context,
     parameters: Parameter[]
   ) => boolean | Promise<boolean>
 
-  reply?: (identity: Identity | null) => http.OutgoingMessage
+  reply?: (context: Context) => http.OutgoingMessage | null
 
-  settle?: (request: Input, response: http.OutgoingMessage) => Promise<void>
+  settle?: (context: Context, response: http.OutgoingMessage) => Promise<void>
 }
 
 export interface Identity {
@@ -32,10 +34,12 @@ export interface Ban {
   banned: boolean
 }
 
-export type Input = io.Input & Extension
+export type Context = io.Input & Extension
 export type AuthenticationResult = Maybe<{ identity: Identity, refresh: boolean }>
 
 export type Scheme = 'basic' | 'token' | 'bearer'
 export type Remote = 'basic' | 'federation' | 'tokens' | 'roles' | 'bans'
 export type Discovery = Record<Remote, Promise<Component>>
 export type Schemes = Record<Scheme, Component>
+
+export type Create = (name: string, value: any, ...args: any[]) => Directive