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

package/source/directives/auth/Authorization.ts

@@ -1,157 +0,0 @@
-import assert from 'node:assert'
-import { match } from 'matchacho'
-import * as http from '../../HTTP'
-import { Anonymous } from './Anonymous'
-import { Id } from './Id'
-import { Role } from './Role'
-import { Rule } from './Rule'
-import { Incept } from './Incept'
-import { Echo } from './Echo'
-import { Scheme } from './Scheme'
-import { Delegate } from './Delegate'
-import { split } from './split'
-import { PRIMARY, PROVIDERS } from './schemes'
-import type { Output } from '../../io'
-import type { Component } from '@toa.io/core'
-import type { Remotes } from '../../Remotes'
-import type { Parameter, DirectiveFamily } from '../../RTD'
-import type {
-  AuthenticationResult,
-  Ban,
-  Directive,
-  Discovery,
-  Extension,
-  Identity,
-  Input,
-  Remote,
-  Schemes
-} from './types'
-
-export class Authorization implements DirectiveFamily<Directive, Extension> {
-  public readonly depends: string[] = ['Vary']
-  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 {
-    assert.ok(name in constructors,
-      `Directive 'auth:${name}' is not implemented.`)
-
-    const Class = constructors[name]
-
-    for (const name of REMOTES)
-      this.discovery[name] ??= remotes.discover('identity', name)
-
-    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)),
-      Incept, () => new Incept(value as string, this.discovery),
-      () => new Class(value))
-  }
-
-  public async preflight (directives: Directive[],
-    input: Input,
-    parameters: Parameter[]): Promise<Output> {
-    const identity = await this.resolve(input.authority, input.request.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: { authority: request.authority, identity }
-    })
-
-    const authorization = `Token ${token}`
-
-    response.headers ??= new Headers()
-    response.headers.set('authorization', authorization)
-    response.headers.append('cache-control', 'no-store')
-  }
-
-  private async resolve (authority: string, 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: {
-        authority,
-        credentials
-      }
-    })
-
-    if (result instanceof Error) 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 constructors: Record<string, new (value: any, argument?: any) => Directive> = {
-  anonymous: Anonymous,
-  id: Id,
-  role: Role,
-  rule: Rule,
-  incept: Incept,
-  scheme: Scheme,
-  echo: Echo,
-  delegate: Delegate
-}
-
-const REMOTES: Remote[] = ['basic', 'federation', 'tokens', 'roles', 'bans']

package/source/directives/auth/Delegate.ts

@@ -1,35 +0,0 @@
-import { BadRequest } from '../../HTTP'
-import { type Directive, type Identity } from './types'
-import type { Input } from '../../io'
-
-export class Delegate implements Directive {
-  private readonly property: string
-
-  public constructor (property: string) {
-    this.property = property
-  }
-
-  public authorize (identity: Identity | null, context: Input): boolean {
-    if (identity === null)
-      return false
-
-    context.pipelines.body.push((body) => this.embed(body, identity))
-
-    return true
-  }
-
-  private embed (body: unknown, identity: Identity): Record<string, unknown> {
-    if (body === undefined)
-      body = {}
-
-    check(body)
-    body[this.property] = identity
-
-    return body
-  }
-}
-
-function check (body: unknown): asserts body is Record<string, unknown> {
-  if (typeof body !== 'object' || body === null)
-    throw new BadRequest('Invalid request body')
-}

package/source/directives/auth/Echo.ts

@@ -1,12 +0,0 @@
-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/Id.ts

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

@@ -1,48 +0,0 @@
-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 { 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.request.headers
-  }
-
-  public async settle (input: 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(input.request.headers.authorization!)
-    const provider = PROVIDERS[scheme]
-
-    this.schemes[scheme] ??= await this.discovery[provider]
-
-    const identity = await this.schemes[scheme]
-      .invoke<Maybe<Identity>>('incept', {
-      input: {
-        authority: input.authority,
-        id,
-        credentials
-      }
-    })
-
-    if (identity instanceof Error)
-      throw new http.UnprocessableEntity(identity)
-
-    input.identity = identity
-    input.identity.scheme = scheme
-  }
-}

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

@@ -1,109 +0,0 @@
-import { type Component } from '@toa.io/core'
-import { generate } from 'randomstring'
-import { Role } from './Role'
-import { type Identity } from './types'
-import type { Parameter } from '../../RTD'
-
-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, undefined, [])
-
-  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)
-})
-
-it('should return true on match with parameters', async () => {
-  const result = await match(['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'], [{
-      name: 'org',
-      value: '29e54ae1'
-    }])
-
-  expect(result).toBe(true)
-})
-
-it('should return true on match with parameters', async () => {
-  const result = await match(['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'], [{
-      name: 'org',
-      value: '29e54ae1'
-    }])
-
-  expect(result).toBe(true)
-})
-
-it('should return false on mismatch with parameters', async () => {
-  const result = await match(['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'], [{
-      name: 'org',
-      value: '88584c9b'
-    }])
-
-  expect(result).toBe(false)
-})
-
-async function match
-(expected: string[], actual: string[], parameters: Parameter[] = []): 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, undefined, parameters)
-}

package/source/directives/auth/Role.ts

@@ -1,66 +0,0 @@
-import assert from 'node:assert'
-import { type Component, type Query } from '@toa.io/core'
-import { type Directive, type Identity } from './types'
-import type { Parameter } from '../../RTD'
-
-export class Role implements Directive {
-  public static remote: Component | null = null
-  private readonly roles: string[]
-  private readonly discovery: Promise<Component>
-  private readonly dynamic: boolean
-
-  public constructor (roles: string | string[], discovery: Promise<Component>) {
-    this.roles = typeof roles === 'string' ? [roles] : roles
-    this.discovery = discovery
-    this.dynamic = this.roles.some((role) => role.includes('{'))
-  }
-
-  public static async set (identity: Identity, discovery: Promise<Component>): Promise<void> {
-    this.remote ??= await discovery
-
-    const query: Query = {
-      criteria: `identity==${identity.id}`,
-      limit: 1024
-    }
-
-    identity.roles = await this.remote.invoke('list', { query })
-  }
-
-  public async authorize
-  (identity: Identity | null, _: unknown, parameters: Parameter[]): Promise<boolean> {
-    if (identity === null)
-      return false
-
-    await Role.set(identity, this.discovery)
-
-    if (identity.roles!.length === 0) // Role.set()
-
-      return false
-
-    return this.match(identity.roles!, parameters)
-  }
-
-  private match (roles: string[], parameters: Parameter[]): boolean {
-    const required = this.dynamic ? this.substitute(parameters) : this.roles
-
-    for (const role of roles) {
-      const ok = required.some((expected) => expected === role || expected.startsWith(role + ':'))
-
-      if (ok)
-        return true
-    }
-
-    return false
-  }
-
-  private substitute (parameters: Parameter[]): string[] {
-    return this.roles.map((role) => role.replaceAll(/{(\w+)}/g, (_, key) => {
-      const value = parameters.find((parameter) => parameter.name === key)?.value
-
-      assert.ok(value !== undefined,
-        `Role '${role}' requires '${key}' route parameter.`)
-
-      return value
-    }))
-  }
-}

package/source/directives/auth/Rule.ts

@@ -1,28 +0,0 @@
-import { type Parameter } from '../../RTD'
-import type { Input, Directive, 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: Input, 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, ...args: any[]) => Directive

package/source/directives/auth/Scheme.ts

@@ -1,26 +0,0 @@
-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.request.headers.authorization === undefined)
-      return false
-
-    const [scheme] = split(input.request.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

@@ -1,3 +0,0 @@
-import { Authorization } from './Authorization'
-
-export const authorization = new Authorization()

package/source/directives/auth/schemes.ts

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

package/source/directives/auth/split.ts

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

@@ -1,40 +0,0 @@
-import { type Component } from '@toa.io/core'
-import { type Maybe } from '@toa.io/types'
-import { type Parameter } from '../../RTD'
-import type * as http from '../../HTTP'
-import type * as io from '../../io'
-
-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 = 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>

package/source/directives/cache/Cache.ts

@@ -1,35 +0,0 @@
-import { Control } from './Control'
-import { Exact } from './Exact'
-import type { Input, Output } from '../../io'
-import type { Directive } from './types'
-import type { DirectiveFamily } from '../../RTD'
-import type * as http from '../../HTTP'
-
-export class Cache implements DirectiveFamily<Directive> {
-  public readonly name: string = 'cache'
-  public readonly mandatory: boolean = false
-
-  public create (name: string, value: any): Directive {
-    const Class = constructors[name]
-
-    if (Class === undefined)
-      throw new Error(`Directive 'cache:${name}' is not implemented.`)
-
-    return new Class(value)
-  }
-
-  public preflight (): Output {
-    return null
-  }
-
-  public async settle
-  (directives: Directive[], input: Input, response: http.OutgoingMessage): Promise<void> {
-    response.headers ??= new Headers()
-    directives[0]?.set(input, response.headers)
-  }
-}
-
-const constructors: Record<string, new (value: any) => Directive> = {
-  control: Control,
-  exact: Exact
-}