@toa.io/extensions.exposition 1.0.0-alpha.291 → 1.0.0-alpha.293

package/source/directives/auth/Incept.ts

@@ -1,117 +0,0 @@
-import assert from 'node:assert'
-import { console } from 'openspan'
-import * as http from '../../HTTP/index.js'
-import { split } from './split.js'
-import { create } from './create.js'
-import { INCEPTION, UNKNOWN, providers as providersOf } from './schemes.js'
-import { Role } from './Role.js'
-import type { Component } from '@toa.io/core'
-import type { Maybe } from '@toa.io/core/types'
-import type { Directive, Discovery, Identity, Context, Components, Ban } from './types.js'
-
-export class Incept implements Directive {
-  private static readonly components: Components = {}
-  private static discovery: Discovery
-  private static bans: Component | null = null
-
-  private readonly property: string | null
-
-  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
-    Incept.discovery ??= discovery
-  }
-
-  public static async incept(context: Context, id: string): Promise<Identity> {
-    const [scheme, credentials] = split(context.request.headers.authorization!)
-    const candidates = providersOf(scheme)
-
-    if (candidates === undefined)
-      throw new http.BadRequest('Authentication scheme is not supported')
-
-    // a scheme several providers claim is incepted by the one that incepts; `Bearer`
-    // carries an access token this gateway issued, and an identity cannot be incepted
-    // from a credential it would itself have to exist to hold
-    const provider = candidates.find((candidate) => INCEPTION.includes(candidate))
-
-    if (provider === undefined) throw new http.Unauthorized()
-
-    Incept.bans ??= await Incept.discovery.bans
-
-    const ban = await Incept.bans.invoke<Ban>('observe', { query: { id } })
-
-    if (ban.banned) throw new http.Unauthorized()
-
-    Incept.components[provider] ??= await Incept.discovery[provider]
-
-    const identity = await Incept.components[provider]!.invoke<Maybe<Identity>>(
-      'incept',
-      {
-        input: {
-          scheme,
-          authority: context.authority,
-          id,
-          credentials
-        }
-      }
-    )
-
-    if (identity instanceof Error) throw new http.UnprocessableEntity(identity)
-
-    identity.scheme = scheme
-
-    // the roles are read where the token is minted: an Identity incepted as the principal
-    // has one already
-    return identity
-  }
-
-  /** Credentials that were rejected for any reason but being unknown are not incepted. */
-  public static acceptable(context: Context): boolean {
-    return (
-      context.request.headers.authorization === undefined || context.rejection === UNKNOWN
-    )
-  }
-
-  public authorize(identity: Identity | null, context: Context): boolean {
-    return identity === null && Incept.acceptable(context)
-  }
-
-  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(context: Context, response: http.OutgoingMessage): Promise<void> {
-    const id = response.body?.[this.property ?? 'id']
-
-    if (id === undefined) {
-      console.debug('Inception skipped: response does not contain expected property', {
-        property: this.property,
-        response
-      })
-
-      return
-    }
-
-    assert(
-      typeof id === 'string',
-      `Response body property "${this.property}" expected to be a string`
-    )
-
-    if (context.request.headers.authorization !== undefined)
-      context.identity = await Incept.incept(context, id)
-    else {
-      const identity = { id, scheme: null, refresh: true }
-      const roles = await Role.get(identity, Incept.discovery.roles)
-
-      context.identity = { ...identity, roles }
-    }
-  }
-}

package/source/directives/auth/Input.ts

@@ -1,92 +0,0 @@
-import { Forbidden } from '../../HTTP/index.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Context, Directive, Identity, Create } from './types.js'
-
-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)
-    )
-  }
-
-  /** It admits nobody: it says what a body may carry, not who may send one. */
-  public admits(): boolean {
-    return false
-  }
-
-  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')
-    }
-  }
-}
-
-export interface Declaration {
-  [key: Exclude<string, 'prop'>]: unknown
-
-  prop: string | string[]
-}
-
-type Body = Record<string, unknown>

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

@@ -1,147 +0,0 @@
-import { it, beforeEach, mock } from 'node:test'
-import assert from 'node:assert/strict'
-import { isDeepStrictEqual } from 'node:util'
-
-import { type Component } from '@toa.io/core'
-import { generate } from 'randomstring'
-import { Role } from './Role.js'
-import { type Identity } from './types.js'
-import type { Parameter } from '../../RTD/index.js'
-
-const remote = {
-  invoke: mock.fn()
-} as unknown as Component
-
-const discovery = Promise.resolve(remote)
-
-beforeEach(() => {
-  resetCalls()
-})
-
-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.mock.mockImplementationOnce(async () => ['guest'])
-
-  const result = await directive.authorize(identity, undefined, [])
-
-  assert.strictEqual(result, false)
-
-  assert.ok(
-    remote.invoke.mock.calls.some(
-      (call: any) =>
-        call.arguments.length === 2 &&
-        isDeepStrictEqual(call.arguments[0], 'list') &&
-        isDeepStrictEqual(call.arguments[1], {
-          query: {
-            criteria: `identity=="${identity.id}"`,
-            limit: 1024
-          }
-        })
-    )
-  )
-})
-
-it('should return true on exact match', async () => {
-  const result = await match(['admin', 'user'], ['user'])
-
-  assert.strictEqual(result, true)
-})
-
-it('should return true on scope match', async () => {
-  const result = await match(['system:identity:roles'], ['system'])
-
-  assert.strictEqual(result, true)
-})
-
-it('should return false on scope mismatch', async () => {
-  const result = await match(['system:identity'], ['system:identity:roles'])
-
-  assert.strictEqual(result, false)
-})
-
-it('should return false on non-scope substring match', async () => {
-  const result = await match(['system:identity'], ['system:iden'])
-
-  assert.strictEqual(result, false)
-})
-
-it('should return true on match with parameters', async () => {
-  const result = await match(
-    ['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'],
-    [
-      {
-        name: 'org',
-        value: '29e54ae1'
-      }
-    ]
-  )
-
-  assert.strictEqual(result, true)
-})
-
-it('should return true on match with parameters', async () => {
-  const result = await match(
-    ['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'],
-    [
-      {
-        name: 'org',
-        value: '29e54ae1'
-      }
-    ]
-  )
-
-  assert.strictEqual(result, true)
-})
-
-it('should return false on mismatch with parameters', async () => {
-  const result = await match(
-    ['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'],
-    [
-      {
-        name: 'org',
-        value: '88584c9b'
-      }
-    ]
-  )
-
-  assert.strictEqual(result, 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.mock.mockImplementationOnce(async () => actual)
-
-  return await directive.authorize(identity, undefined, parameters)
-}
-
-function resetCalls(target = [remote, discovery], seen = new Set()) {
-  if (target === null || typeof target !== 'object' || seen.has(target)) return
-
-  seen.add(target)
-
-  for (const value of Object.values(target))
-    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
-    else resetCalls(value, seen)
-}

package/source/directives/auth/Role.ts

@@ -1,99 +0,0 @@
-import assert from 'node:assert'
-import { quote } from '@toa.io/generic'
-import { type Component } from '@toa.io/core'
-import type { Query } from '@toa.io/core/types'
-import { type Directive, type Identity } from './types.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-
-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 get(
-    identity: Identity,
-    discovery: Promise<Component>
-  ): Promise<string[]> {
-    this.remote ??= await discovery
-
-    const query: Query = {
-      criteria: `identity==${quote(identity.id)}`,
-      limit: 1024
-    }
-
-    return await this.remote.invoke('list', { query })
-  }
-
-  /**
-   * Reaching it takes a role, which is what `protected` says. A role of the `system` scope
-   * says so besides: what it guards is the machinery an application runs on rather than
-   * anything it serves, and a reader has no business being offered it as one.
-   */
-  public describe(introspection: Introspection): Introspection {
-    const system = this.roles.some(
-      (role) => role === SYSTEM || role.startsWith(SYSTEM + ':')
-    )
-
-    return { ...introspection, protected: true, ...(system ? { system: true } : {}) }
-  }
-
-  public async authorize(
-    identity: Identity | null,
-    _: unknown,
-    parameters: Parameter[]
-  ): Promise<boolean> {
-    if (identity === null) return false
-
-    identity.roles ??= await Role.get(identity, this.discovery)
-
-    return this.match(identity.roles, parameters)
-  }
-
-  /** A role naming a route variable cannot be told from a description, which has no values. */
-  public async admits(identity: Identity | null): Promise<boolean | undefined> {
-    if (this.dynamic) return undefined
-
-    if (identity === null) return false
-
-    identity.roles ??= await Role.get(identity, this.discovery)
-
-    return this.match(identity.roles, [])
-  }
-
-  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
-      })
-    )
-  }
-}
-
-/** The scope of what an application runs on, as opposed to what it serves. */
-const SYSTEM = 'system'

package/source/directives/auth/Rule.ts

@@ -1,59 +0,0 @@
-import { type Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Context, Directive, Identity, Create } from './types.js'
-
-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,
-    context: Context,
-    parameters: Parameter[]
-  ): Promise<boolean> {
-    for (const directive of this.directives) {
-      const authorized = await directive.authorize(identity, context, parameters)
-
-      if (!authorized) return false
-    }
-
-    return true
-  }
-
-  /** Whatever each of them makes of it, in the order they were declared. */
-  public describe(introspection: Introspection): Introspection {
-    for (const directive of this.directives)
-      introspection = directive.describe?.(introspection) ?? introspection
-
-    return introspection
-  }
-
-  /** All of them, so one that refuses ends it and one that cannot tell leaves it untold. */
-  public async admits(
-    identity: Identity | null,
-    context: Context
-  ): Promise<boolean | undefined> {
-    let untold = false
-
-    for (const directive of this.directives) {
-      const admits = await directive.admits?.(identity, context)
-
-      if (admits === undefined) {
-        untold = true
-
-        continue
-      }
-
-      if (!admits) return false
-    }
-
-    return untold ? undefined : true
-  }
-}

package/source/directives/auth/Scheme.ts

@@ -1,31 +0,0 @@
-import * as http from '../../HTTP/index.js'
-import { type Directive, type Identity, type Context } from './types.js'
-import { split } from './split.js'
-
-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, context: Context): boolean {
-    if (context.request.headers.authorization === undefined) return false
-
-    const [scheme] = split(context.request.headers.authorization)
-
-    if (scheme !== this.scheme)
-      throw new http.Forbidden(
-        this.Scheme + ' authentication scheme is required to access this resource'
-      )
-
-    return false
-  }
-
-  /** It admits nobody: it is there to refuse a scheme, not to authorize one. */
-  public admits(): boolean {
-    return false
-  }
-}

package/source/directives/auth/create.ts

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

package/source/directives/auth/index.ts

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

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

@@ -1,18 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { providers } from './schemes.js'
-
-it('should resolve a known scheme', () => {
-  assert.deepEqual(providers('basic'), ['basic'])
-  assert.deepEqual(providers('code'), ['federation'])
-})
-
-it('should resolve every provider claiming a scheme, in order', () => {
-  assert.deepEqual(providers('bearer'), ['tokens', 'federation'])
-})
-
-it('should not resolve a property of Object.prototype', () => {
-  for (const name of ['constructor', '__proto__', 'toString', 'hasOwnProperty'])
-    assert.equal(providers(name), undefined)
-})

package/source/directives/auth/schemes.ts

@@ -1,39 +0,0 @@
-import type { Remote, Scheme } from './types.js'
-
-/**
- * The providers of a scheme, in the order they are asked. More than one claims `Bearer`:
- * an OpenID `id_token` is federated, and a token this gateway issued is presented that way
- * by an OAuth client. Which of them a credential belongs to is each provider's own to say,
- * so the order here is only which is asked first.
- */
-export const PROVIDERS: Record<Scheme, Remote[]> = {
-  basic: ['basic'],
-  token: ['tokens'],
-  bearer: ['tokens', 'federation'],
-  code: ['federation'],
-  otp: ['otp']
-}
-
-export const INCEPTION: Remote[] = ['basic', 'federation']
-export const PRIMARY: Remote = 'tokens'
-
-/**
- * The providers of a scheme, or nothing for a scheme that is not one — including a name a
- * plain object answers on its own, like `constructor`.
- */
-export function providers(scheme: string): Remote[] | undefined {
-  return Object.hasOwn(PROVIDERS, scheme) ? PROVIDERS[scheme as Scheme] : undefined
-}
-
-/**
- * What a provider answers when the credentials are not of its kind. The next provider of
- * the scheme is asked; a provider that declines has done nothing, so asking is free of
- * effect — which asking one that rejects would not be.
- */
-export const UNRECOGNIZED = 'UNRECOGNIZED'
-
-/**
- * The rejection of credentials that are verifiable and owned by no identity: the one
- * inception goes ahead with.
- */
-export const UNKNOWN = 'NOT_FOUND'

package/source/directives/auth/split.ts

@@ -1,14 +0,0 @@
-import * as http from '../../HTTP/index.js'
-import { type Scheme } from './types.js'
-
-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]
-}