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

package/source/directives/auth/Delegate.ts

@@ -1,54 +0,0 @@
-import { BadRequest } from '../../HTTP/index.js'
-import { take } from '../../Introspection.js'
-import { Role } from './Role.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Context, Directive, Identity } from './types.js'
-import type { Component } from '@toa.io/core'
-
-export class Delegate implements Directive {
-  private readonly property: string
-  private readonly discovery: Promise<Component>
-
-  public constructor(property: string, discovery: Promise<Component>) {
-    this.property = property
-    this.discovery = discovery
-  }
-
-  public async authorize(identity: Identity | null, context: Context): Promise<boolean> {
-    if (identity === null) return false
-
-    identity.roles ??= await Role.get(identity, this.discovery)
-    context.pipelines.body.push((body) => this.embed(body, identity))
-
-    return true
-  }
-
-  /** It admits whoever there is, and embedding the identity is the request's business. */
-  public admits(identity: Identity | null): boolean {
-    return identity !== null
-  }
-
-  /**
-   * It takes an identity, and the property it embeds is that identity's — so a caller has
-   * nothing to put there.
-   */
-  public describe(introspection: Introspection): Introspection {
-    take(introspection, this.property)
-
-    return { ...introspection, authenticated: true }
-  }
-
-  private embed(body: unknown, identity: Identity): Record<string, unknown> {
-    if (body === undefined) body = {}
-
-    check(body)
-    body[this.property] = structuredClone(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,24 +0,0 @@
-import { create } from './create.js'
-import type { OutgoingMessage } from '../../HTTP/index.js'
-import type { Directive, Identity, Context } from './types.js'
-
-export class Echo implements Directive {
-  public authorize(identity: Identity | null, context: Context): boolean {
-    if (identity === null && 'authorization' in context.request.headers) return false
-
-    context.identity ??= create()
-
-    return true
-  }
-
-  /** What `authorize` answers, without inventing the identity it would go on to invent. */
-  public admits(identity: Identity | null, context: Context): boolean {
-    return !(identity === null && 'authorization' in context.request.headers)
-  }
-
-  public reply(context: Context): OutgoingMessage {
-    const body = context.identity!
-
-    return body.scheme === null ? { status: 201, body } : { body }
-  }
-}

package/source/directives/auth/Federation.ts

@@ -1,104 +0,0 @@
-import assert from 'node:assert'
-import type { Directive, Identity, Context } from './types.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Parameter } from '../../RTD/index.js'
-
-export class Federation implements Directive {
-  private readonly matchers: Array<[keyof Claims, Matcher]>
-
-  public constructor(options: Options) {
-    this.matchers = (Object.entries(options) as Array<[keyof Claims, string]>).map(
-      ([key, value]) => [key, toMatcher(value)]
-    )
-
-    assert.ok(
-      this.matchers.length > 0,
-      '`auth:claims` requires at least one property defined'
-    )
-  }
-
-  /** Which claims it takes needs the request; that it takes an identity does not. */
-  public admits(identity: Identity | null): boolean | undefined {
-    return identity === null ? false : undefined
-  }
-
-  /** Which claims is the application's business; that it takes an identity is the caller's. */
-  public describe(introspection: Introspection): Introspection {
-    return { ...introspection, authenticated: true }
-  }
-
-  public authorize(
-    identity: Identity | null,
-    context: Context,
-    parameters: Parameter[]
-  ): boolean {
-    if (identity === null || !('claims' in identity)) return false
-
-    const claims = (identity as FederatedIdentity).claims
-
-    for (const [key, match] of this.matchers)
-      if (!match(claims[key], context, parameters)) return false
-
-    return true
-  }
-}
-
-function toMatcher(expression: string): Matcher {
-  if (expression.startsWith(':')) {
-    const key = expression.slice(1) as 'authority'
-
-    if (key === 'authority') return (value, context) => matches(value, context[key])
-
-    if (key === 'domain')
-      return (value, context) => {
-        return Array.isArray(value)
-          ? value.some((iss) => codomain(iss, context))
-          : codomain(value, context)
-      }
-
-    throw new Error('Unknown `auth:claims` syntax: ' + expression)
-  }
-
-  if (expression.startsWith('/:')) {
-    const name = expression.slice(2)
-
-    return (value, _, parameters) =>
-      parameters.some(
-        (parameter) => parameter.name === name && matches(value, parameter.value)
-      )
-  }
-
-  return (value) => matches(value, expression)
-}
-
-function matches(value: string | string[], reference: string): boolean {
-  return Array.isArray(value) ? value.includes(reference) : value === reference
-}
-
-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)
-
-  return context.authority.slice(-basename.length) === basename
-}
-
-type Matcher = (
-  value: string | string[],
-  context: Context,
-  parameters: Parameter[]
-) => boolean
-
-interface Claims {
-  iss: string
-  sub: string
-  aud: string | string[]
-}
-
-interface Options extends Partial<Claims> {
-  iss: string
-}
-
-interface FederatedIdentity extends Identity {
-  claims: Claims
-}

package/source/directives/auth/Id.ts

@@ -1,37 +0,0 @@
-import { type Parameter } from '../../RTD/index.js'
-import { type Directive, type Identity } from './types.js'
-import type { Introspection } from '../../Introspection.js'
-
-export class Id implements Directive {
-  private readonly parameter: string
-
-  public constructor(parameter: string) {
-    this.parameter = parameter
-  }
-
-  /**
-   * Whether it is *this* identity's cannot be told from a description, which has no route
-   * variable to read — but that there must be an identity at all can, and a caller with
-   * none is refused whatever the value would have been.
-   */
-  public admits(identity: Identity | null): boolean | undefined {
-    return identity === null ? false : undefined
-  }
-
-  /** Reaching it is being the identity it is about, which is what `private` says. */
-  public describe(introspection: Introspection): Introspection {
-    return { ...introspection, private: true }
-  }
-
-  public authorize(
-    identity: Identity | null,
-    _: unknown,
-    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,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'