@toa.io/extensions.exposition 0.20.0-dev.9 → 0.21.0-alpha.0

package/source/deployment.ts

@@ -0,0 +1,49 @@
+import { type Dependency, type Service } from '@toa.io/operations'
+import { encode } from '@toa.io/generic'
+import { type Annotation } from './Annotation'
+import * as schemas from './schemas'
+import { shortcuts } from './Directive'
+import { components } from './Composition'
+import { parse } from './RTD/syntax'
+
+export function deployment (_: unknown, annotation: Annotation | undefined): Dependency {
+  const labels = components().labels
+
+  const service: Service = {
+    group: 'exposition',
+    name: 'gateway',
+    port: 8000,
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    version: require('../package.json').version,
+    variables: [],
+    components: labels
+  }
+
+  if (annotation?.host !== undefined)
+    service.ingress = {
+      host: annotation.host,
+      class: annotation.class,
+      annotations: annotation.annotations
+    }
+
+  if (annotation?.['/'] !== undefined) {
+    const node = { '/': annotation['/'] }
+    const tree = parse(node, shortcuts)
+
+    service.variables.push({
+      name: 'TOA_EXPOSITION',
+      value: encode(tree)
+    })
+  }
+
+  if (annotation?.debug === true)
+    service.variables.push({
+      name: 'TOA_EXPOSITION_DEBUG',
+      value: '1'
+    })
+
+  if (annotation !== undefined)
+    schemas.annotaion.validate(annotation)
+
+  return { services: [service] }
+}

package/source/directives/auth/Anonymous.ts

@@ -0,0 +1,14 @@
+import { type Directive, type Input } from './types'
+
+export class Anonymous implements Directive {
+  private readonly allow: boolean
+
+  public constructor (allow: boolean) {
+    this.allow = allow
+  }
+
+  public authorize (_: any, input: Input): boolean {
+    if ('authorization' in input.headers) return false
+    else return this.allow
+  }
+}

package/source/directives/auth/Echo.ts

@@ -0,0 +1,12 @@
+import { type OutgoingMessage } from '../../HTTP'
+import { type Directive, type Identity } from './types'
+
+export class Echo implements Directive {
+  public authorize (identity: Identity | null): boolean {
+    return identity !== null
+  }
+
+  public reply (identity: Identity | null): OutgoingMessage {
+    return { body: identity }
+  }
+}

package/source/directives/auth/Family.ts

@@ -0,0 +1,145 @@
+import { type Component } from '@toa.io/core'
+import { Nope } from 'nopeable'
+import { type Parameter } from '../../RTD'
+import { type Family, type Output } from '../../Directive'
+import { type Remotes } from '../../Remotes'
+import * as http from '../../HTTP'
+import {
+  type AuthenticationResult,
+  type Ban,
+  type Directive,
+  type Discovery,
+  type Extension,
+  type Identity,
+  type Input, type Remote,
+  type Schemes
+} from './types'
+import { Anonymous } from './Anonymous'
+import { Id } from './Id'
+import { Role } from './Role'
+import { Rule } from './Rule'
+import { Incept } from './Incept'
+import { split } from './split'
+import { PRIMARY, PROVIDERS } from './schemes'
+import { Scheme } from './Scheme'
+import { Echo } from './Echo'
+
+class Authorization implements Family<Directive, Extension> {
+  public readonly name: string = 'auth'
+  public readonly mandatory: boolean = true
+  private readonly schemes = {} as unknown as Schemes
+  private readonly discovery = {} as unknown as Discovery
+  private tokens: Component | null = null
+  private bans: Component | null = null
+
+  public create (name: string, value: any, remotes: Remotes): Directive {
+    const Class = CLASSES[name]
+
+    if (Class === undefined)
+      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+
+    for (const name of REMOTES)
+      this.discovery[name] ??= remotes.discover('identity', name)
+
+    if (Class === Role) return new Class(value, this.discovery.roles)
+    else if (Class === Rule) return new Class(value, this.create.bind(this))
+    else if (Class === Incept) return new Class(value, this.discovery)
+    else return new Class(value)
+  }
+
+  public async preflight
+  (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
+    const identity = await this.resolve(input.headers.authorization)
+
+    input.identity = identity
+
+    for (const directive of directives) {
+      const allow = await directive.authorize(identity, input, parameters)
+
+      if (allow)
+        return directive.reply?.(identity) ?? null
+    }
+
+    if (identity === null) throw new http.Unauthorized()
+    else throw new http.Forbidden()
+  }
+
+  public async settle
+  (directives: Directive[], request: Input, response: http.OutgoingMessage): Promise<void> {
+    for (const directive of directives)
+      await directive.settle?.(request, response)
+
+    const identity = request.identity
+
+    if (identity === null)
+      return
+
+    if (identity.scheme === PRIMARY && !identity.refresh)
+      return
+
+    // Role directive may have already set the value
+    if (identity.roles === undefined)
+      await Role.set(identity, this.discovery.roles)
+
+    this.tokens ??= await this.discovery.tokens
+
+    const token = await this.tokens.invoke<string>('encrypt', { input: { identity } })
+    const authorization = `Token ${token}`
+
+    if (response.headers === undefined)
+      response.headers = {}
+
+    response.headers.authorization = authorization
+  }
+
+  private async resolve (authorization: string | undefined): Promise<Identity | null> {
+    if (authorization === undefined)
+      return null
+
+    const [scheme, credentials] = split(authorization)
+    const provider = PROVIDERS[scheme]
+
+    if (!(provider in this.discovery))
+      throw new http.Unauthorized(`Unknown authentication scheme '${scheme}'.`)
+
+    this.schemes[scheme] ??= await this.discovery[provider]
+
+    const result = await this.schemes[scheme]
+      .invoke<AuthenticationResult>('authenticate', { input: credentials })
+
+    if (result instanceof Nope)
+      return null
+
+    const identity = result.identity
+
+    if (scheme !== PRIMARY && await this.banned(identity))
+      throw new http.Unauthorized()
+
+    identity.scheme = scheme
+    identity.refresh = result.refresh
+
+    return identity
+  }
+
+  private async banned (identity: Identity): Promise<boolean> {
+    this.bans ??= await this.discovery.bans
+
+    const ban = await this.bans.invoke<Ban>('observe', { query: { id: identity.id } })
+
+    return ban.banned
+  }
+}
+
+const CLASSES: Record<string, new (value: any, argument?: any) => Directive> = {
+  anonymous: Anonymous,
+  id: Id,
+  role: Role,
+  rule: Rule,
+  incept: Incept,
+  scheme: Scheme,
+  echo: Echo
+}
+
+const REMOTES: Remote[] = ['basic', 'tokens', 'roles', 'bans']
+
+export = new Authorization()

package/source/directives/auth/Id.ts

@@ -0,0 +1,19 @@
+import { type Parameter } from '../../RTD'
+import { type Directive, type Identity } from './types'
+
+export class Id implements Directive {
+  private readonly parameter: string
+
+  public constructor (parameter: string) {
+    this.parameter = parameter
+  }
+
+  public authorize (identity: Identity | null, _: any, parameters: Parameter[]): boolean {
+    if (identity === null)
+      return false
+
+    const parameter = parameters.find((parameter) => parameter.name === this.parameter)
+
+    return parameter?.value === identity.id
+  }
+}

package/source/directives/auth/Incept.ts

@@ -0,0 +1,42 @@
+import { Nope, type Nopeable } from 'nopeable'
+import * as http from '../../HTTP'
+import { type Directive, type Discovery, type Identity, type Input, type Schemes } from './types'
+import { split } from './split'
+import { PROVIDERS } from './schemes'
+
+export class Incept implements Directive {
+  private readonly property: string
+  private readonly discovery: Discovery
+  private readonly schemes: Schemes = {} as unknown as Schemes
+
+  public constructor (property: string, discovery: Discovery) {
+    this.property = property
+    this.discovery = discovery
+  }
+
+  public authorize (identity: Identity | null, input: Input): boolean {
+    return identity === null && 'authorization' in input.headers
+  }
+
+  public async settle (request: Input, response: http.OutgoingMessage): Promise<void> {
+    const id = response.body?.[this.property]
+
+    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(request.headers.authorization as string)
+    const provider = PROVIDERS[scheme]
+
+    this.schemes[scheme] ??= await this.discovery[provider]
+
+    const identity = await this.schemes[scheme]
+      .invoke<Nopeable<Identity>>('create', { input: { id, credentials } })
+
+    if (identity instanceof Nope)
+      throw new http.Conflict(identity)
+
+    request.identity = identity
+    request.identity.scheme = scheme
+  }
+}

package/source/directives/auth/Role.test.ts

@@ -0,0 +1,62 @@
+import { type Component } from '@toa.io/core'
+import { generate } from 'randomstring'
+import { Role } from './Role'
+import { type Identity } from './types'
+
+const remote = {
+  invoke: jest.fn()
+} as unknown as jest.MockedObject<Component>
+
+const discovery = Promise.resolve(remote)
+
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+it('should return false if not matched', async () => {
+  const roles = ['admin', 'user']
+  const directive = new Role(roles, discovery)
+  const identity: Identity = { id: generate(), scheme: '', refresh: false }
+
+  remote.invoke.mockResolvedValueOnce(['guest'])
+
+  const result = await directive.authorize(identity)
+
+  expect(result).toBe(false)
+
+  expect(remote.invoke)
+    .toBeCalledWith('list', { query: { criteria: `identity==${identity.id}`, limit: 1024 } })
+})
+
+it('should return true on exact match', async () => {
+  const result = await match(['admin', 'user'], ['user'])
+
+  expect(result).toBe(true)
+})
+
+it('should return true on scope match', async () => {
+  const result = await match(['system:identity:roles'], ['system'])
+
+  expect(result).toBe(true)
+})
+
+it('should return false on scope mismatch', async () => {
+  const result = await match(['system:identity'], ['system:identity:roles'])
+
+  expect(result).toBe(false)
+})
+
+it('should return false on non-scope substring match', async () => {
+  const result = await match(['system:identity'], ['system:iden'])
+
+  expect(result).toBe(false)
+})
+
+async function match (expected: string[], actual: string[]): Promise<boolean> {
+  const directive = new Role(expected, discovery)
+  const identity: Identity = { id: generate(), scheme: '', refresh: false }
+
+  remote.invoke.mockResolvedValueOnce(actual)
+
+  return await directive.authorize(identity)
+}

package/source/directives/auth/Role.ts

@@ -0,0 +1,56 @@
+import { type Component, type Query } from '@toa.io/core'
+import { type Directive, type Identity } from './types'
+
+export class Role implements Directive {
+  public static remote: Component | null = null
+  private readonly roles: string[]
+  private readonly discovery: Promise<Component>
+
+  public constructor (roles: string | string[], discovery: Promise<Component>) {
+    this.roles = typeof roles === 'string' ? [roles] : roles
+    this.discovery = discovery
+  }
+
+  public static async set (identity: Identity, discovery: Promise<Component>): Promise<void> {
+    this.remote ??= await discovery
+
+    const query: Query = { criteria: `identity==${identity.id}`, limit: 1024 }
+    const roles: string[] = await this.remote.invoke('list', { query })
+
+    identity.roles = roles
+  }
+
+  public async authorize (identity: Identity | null): Promise<boolean> {
+    if (identity === null)
+      return false
+
+    await Role.set(identity, this.discovery)
+
+    if (identity.roles === undefined)
+      return false
+
+    return this.match(identity.roles)
+  }
+
+  private match (roles: string[]): boolean {
+    for (const role of roles) {
+      const index = this.roles.findIndex((expected) => compare(expected, role))
+
+      if (index !== -1)
+        return true
+    }
+
+    return false
+  }
+}
+
+function compare (expected: string, actual: string): boolean {
+  const exp = expected.split(':')
+  const act = actual.split(':')
+
+  for (let i = 0; i < act.length; i++)
+    if (exp[i] !== act[i])
+      return false
+
+  return true
+}

package/source/directives/auth/Rule.ts

@@ -0,0 +1,28 @@
+import { type Parameter } from '../../RTD'
+import { type Directive, type Identity } from './types'
+
+export class Rule implements Directive {
+  private readonly directives: Directive[] = []
+
+  public constructor (directives: Record<string, any>, create: Create) {
+    for (const [name, value] of Object.entries(directives)) {
+      const directive = create(name, value)
+
+      this.directives.push(directive)
+    }
+  }
+
+  public async authorize
+  (identity: Identity | null, input: any, parameters: Parameter[]): Promise<boolean> {
+    for (const directive of this.directives) {
+      const authorized = await directive.authorize(identity, input, parameters)
+
+      if (!authorized)
+        return false
+    }
+
+    return true
+  }
+}
+
+type Create = (name: string, value: any) => Directive

package/source/directives/auth/Scheme.ts

@@ -0,0 +1,26 @@
+import * as http from '../../HTTP'
+import { type Directive, type Identity, type Input } from './types'
+import { split } from './split'
+
+export class Scheme implements Directive {
+  private readonly scheme: string
+  private readonly Scheme: string
+
+  public constructor (scheme: string) {
+    this.scheme = scheme.toLowerCase()
+    this.Scheme = scheme[0].toUpperCase() + scheme.substring(1)
+  }
+
+  public authorize (_: Identity | null, input: Input): boolean {
+    if (input.headers.authorization === undefined)
+      return false
+
+    const [scheme] = split(input.headers.authorization)
+
+    if (scheme !== this.scheme)
+      throw new http.Forbidden(this.Scheme +
+        ' authentication scheme is required to access this resource.')
+
+    return false
+  }
+}

package/source/directives/auth/index.ts

@@ -0,0 +1,3 @@
+import Family from './Family'
+
+export = Family

package/source/directives/auth/schemes.ts

@@ -0,0 +1,8 @@
+import { type Remote, type Scheme } from './types'
+
+export const PROVIDERS: Record<Scheme, Remote> = {
+  basic: 'basic',
+  token: 'tokens'
+}
+
+export const PRIMARY: Scheme = 'token'

package/source/directives/auth/split.ts

@@ -0,0 +1,15 @@
+import * as http from '../../HTTP'
+import { type Scheme } from './types'
+
+export function split (authorization: string): [Scheme, string] {
+  const space = authorization.indexOf(' ')
+
+  if (space === -1)
+    throw new http.Unauthorized('Malformed authorization header.')
+
+  const Scheme = authorization.slice(0, space)
+  const scheme = Scheme.toLowerCase() as Scheme
+  const value = authorization.slice(space + 1)
+
+  return [scheme, value]
+}

package/source/directives/auth/types.ts

@@ -0,0 +1,37 @@
+import { type Component } from '@toa.io/core'
+import { type Nopeable } from 'nopeable'
+import { type Parameter } from '../../RTD'
+import type * as http from '../../HTTP'
+import type * as directive from '../../Directive'
+
+export interface Directive {
+  authorize: (identity: Identity | null, input: Input, parameters: Parameter[]) =>
+  boolean | Promise<boolean>
+
+  reply?: (identity: Identity | null) => http.OutgoingMessage
+
+  settle?: (request: Input, response: http.OutgoingMessage) => Promise<void>
+}
+
+export interface Identity {
+  readonly id: string
+  scheme: string
+  roles?: string[]
+  refresh: boolean
+}
+
+export interface Extension {
+  identity: Identity | null
+}
+
+export interface Ban {
+  banned: boolean
+}
+
+export type Input = directive.Input & Extension
+export type AuthenticationResult = Nopeable<{ identity: Identity, refresh: boolean }>
+
+export type Scheme = 'basic' | 'token'
+export type Remote = 'basic' | 'tokens' | 'roles' | 'bans'
+export type Discovery = Record<Remote, Promise<Component>>
+export type Schemes = Record<Scheme, Component>

package/source/directives/dev/Family.ts

@@ -0,0 +1,36 @@
+import { type Input, type Output, type Family } from '../../Directive'
+import { Stub } from './Stub'
+import { Throw } from './Throw'
+import { type Directive } from './types'
+
+class Development implements Family<Directive> {
+  public readonly name: string = 'dev'
+  public readonly mandatory: boolean = false
+
+  public create (name: string, value: any): Directive {
+    const Class = constructors[name]
+
+    if (Class === undefined)
+      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+
+    return new Class(value)
+  }
+
+  public preflight (directives: Directive[], input: Input): Output {
+    for (const directive of directives) {
+      const output = directive.apply(input)
+
+      if (output !== null)
+        return output
+    }
+
+    return null
+  }
+}
+
+const constructors: Record<string, new (value: any) => Directive> = {
+  stub: Stub,
+  throw: Throw
+}
+
+export = new Development()

package/source/directives/dev/Stub.ts

@@ -0,0 +1,14 @@
+import { type Output } from '../../Directive'
+import { type Directive } from './types'
+
+export class Stub implements Directive {
+  private readonly value: any
+
+  public constructor (value: any) {
+    this.value = value
+  }
+
+  public apply (): Output {
+    return { body: this.value }
+  }
+}

package/source/directives/dev/Throw.ts

@@ -0,0 +1,14 @@
+import { type Output } from '../../Directive'
+import { type Directive } from './types'
+
+export class Throw implements Directive {
+  private readonly message: any
+
+  public constructor (message: any) {
+    this.message = message
+  }
+
+  public apply (): Output {
+    throw new Error(this.message)
+  }
+}

package/source/directives/dev/index.ts

@@ -0,0 +1,3 @@
+import Family from './Family'
+
+export = Family

package/source/directives/dev/types.ts

@@ -0,0 +1,5 @@
+import { type Input, type Output } from '../../Directive'
+
+export interface Directive {
+  apply: (input: Input) => Output
+}

package/source/directives/index.ts

@@ -0,0 +1,5 @@
+import { type Family } from '../Directive'
+import Dev from './dev'
+import Auth from './auth'
+
+export const families: Family[] = [Dev, Auth]

package/source/discovery.ts

@@ -0,0 +1 @@
+export type Label = 'ping' | 'expose'

package/source/exceptions.ts

@@ -0,0 +1,17 @@
+import { type Exception } from '@toa.io/core'
+import * as http from './HTTP'
+
+export function rethrow (exception: Exception): void {
+  // see /runtime/core/src/exceptions.js
+
+  if ((exception.code >= 200 && exception.code < 210) || exception.code === 221)
+    throw new http.BadRequest(exception.message)
+
+  if (exception.code === 302)
+    throw new http.NotFound()
+
+  if (exception.code === 303)
+    throw new http.PreconditionFailed()
+
+  throw exception as unknown as Error
+}

package/source/index.test.ts

@@ -0,0 +1,9 @@
+/**
+ * WebStorm can't find jest types if they are in the root of the project,
+ * while a current project has its own node_modules.
+ *
+ * Importing jest here fixes the issue.
+ */
+import 'jest'
+
+it.skip('', () => undefined) // prevent jest from complaining about missing tests

package/source/index.ts

@@ -0,0 +1,6 @@
+export { manifest } from './manifest'
+export { deployment } from './deployment'
+export { components } from './Composition'
+export { Factory } from './Factory'
+
+export type { Remotes } from './Remotes'