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

package/source/directives/auth/Authorization.ts

@@ -1,388 +0,0 @@
-import assert from 'node:assert'
-import { match } from 'matchacho'
-import { console } from 'openspan'
-import { Minimatch } from 'minimatch'
-import * as http from '../../HTTP/index.js'
-import { Anonymous } from './Anonymous.js'
-import { Id } from './Id.js'
-import { Role } from './Role.js'
-import { Rule } from './Rule.js'
-import { Incept } from './Incept.js'
-import { Assert } from './Assert.js'
-import { Echo } from './Echo.js'
-import { Scheme } from './Scheme.js'
-import { Delegate } from './Delegate.js'
-import { Federation } from './Federation.js'
-import { Anyone } from './Anyone.js'
-import { Input, type Declaration } from './Input.js'
-import { split } from './split.js'
-import { PRIMARY, UNRECOGNIZED, providers as providersOf } from './schemes.js'
-import { ATOM_GROUP } from '../../const.js'
-import { Quotas, Sync } from '../io/lib/throttle/index.js'
-import { Keys } from '../io/lib/throttle/Keys.js'
-import type { Output } from '../../io.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Component } from '@toa.io/core'
-import type { Remotes } from '../../Remotes.js'
-import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
-import type { Host } from '../../Factory.js'
-import type {
-  AuthenticationResult,
-  Ban,
-  Directive,
-  Discovery,
-  Extension,
-  Identity,
-  Context,
-  Remote,
-  Components
-} from './types.js'
-
-export class Authorization implements DirectiveFamily<Directive, Extension> {
-  public readonly depends: string[] = ['Vary']
-  public readonly name: string = 'auth'
-  public readonly mandatory: boolean = true
-
-  private readonly components: Components = {}
-  private readonly discovery = {} as unknown as Discovery
-  private tokens: Component | null = null
-  private bans: Component | null = null
-
-  /** Failed authentications per address, reconciled with the other gateways. */
-  private meter: Quotas | null = null
-  private sync: Sync | null = null
-
-  public mount(host: Host, options: http.Options): void {
-    this.sync?.dispose()
-    this.sync = null
-    this.meter = null
-
-    const bouncer = options.bouncer
-
-    // keyed by address, which is the deployment's to name, so off until it is set
-    if (bouncer === undefined) return
-
-    this.meter = new Quotas({
-      keys: Keys.create([{ method: 'ip', options: BOUNCER }]),
-      requests: bouncer.attempts ?? ATTEMPTS,
-      interval: (bouncer.interval ?? INTERVAL) * 1000,
-      conditional: true, // charged on a rejection, not on a check
-      name: METER
-    })
-
-    this.sync = new Sync(host.atom(ATOM_GROUP))
-    this.sync.register(this.meter)
-  }
-
-  public dispose(): void {
-    this.sync?.dispose()
-  }
-
-  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)),
-      Input,
-      () => new Input(value as Declaration[], 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 arrange(directives: Directive[]): void {
-    directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
-  }
-
-  /**
-   * Authentication: who the credential names, if one is presented. A credential belongs to
-   * the request, so it is read once however many calls the request carries.
-   */
-  public async preflight(context: Context): Promise<void> {
-    context.identity = await this.resolve(context)
-  }
-
-  /** Authorization: whether that identity may make this call, which every call asks anew. */
-  public async precall(
-    directives: Directive[],
-    context: Context,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    for (const directive of directives) {
-      const allow = await directive.authorize(context.identity, context, parameters)
-
-      if (allow)
-        if (this.permitted(context)) return directive.reply?.(context) ?? null
-        else throw new http.Forbidden()
-    }
-
-    if (context.identity === null) throw new http.Unauthorized()
-    else throw new http.Forbidden()
-  }
-
-  /**
-   * The same disjunction as `precall`, over what can be told without a request. A method no
-   * directive admits, and none is undecided about, is not this caller's to be told about —
-   * `null` takes it out of the answer.
-   *
-   * A permission is matched against a path, and a description is not a request to one, so
-   * `permits` has no say here. The call it describes is still checked, which is where a
-   * token's permissions belong.
-   *
-   * A method that is described is then described by each of them, which is a separate pass:
-   * admission is a disjunction and stops at the first that admits, while what the directives
-   * fill is not any one of them's to state alone.
-   */
-  public async explain(
-    directives: Directive[],
-    context: Context,
-    introspection: Introspection
-  ): Promise<Introspection | null> {
-    let untold = false
-    let admitted = false
-
-    for (const directive of directives) {
-      const admits = await directive.admits?.(context.identity, context)
-
-      if (admits === undefined) {
-        untold = true
-
-        continue
-      }
-
-      if (admits) {
-        admitted = true
-
-        break
-      }
-    }
-
-    if (!admitted && !untold) return null
-
-    // whichever of them admitted, a property any of them fills from the identity is filled
-    // from the identity: what a caller sent there would be overwritten or forged
-    for (const directive of directives)
-      introspection = directive.describe?.(introspection) ?? introspection
-
-    return introspection
-  }
-
-  public async settle(
-    directives: Directive[],
-    context: Context,
-    response: http.OutgoingMessage
-  ): Promise<void> {
-    await Promise.all(
-      directives.map(async (directive) => directive.settle?.(context, response))
-    )
-  }
-
-  /**
-   * Re-issuing a credential, and refusing a ban, are the request's business: the header
-   * carries one token however many calls were made, and a ban refuses all of them.
-   */
-  public async depart(context: Context, response: http.OutgoingMessage): Promise<void> {
-    const identity = context.identity
-
-    if (identity === null) return
-
-    if (identity.provider === PRIMARY && !identity.refresh) return
-
-    // resolving already asked, for any provider but the primary
-    if (context.vetted !== true && (await this.banned(identity)))
-      throw new http.Unauthorized()
-
-    // a token carries the roles it was issued with, and the refresh is where they are read again;
-    // any other scheme has just read them, unless a Role directive already did
-    if (identity.provider === PRIMARY)
-      identity.roles = await Role.get(identity, this.discovery.roles)
-    else identity.roles ??= await Role.get(identity, this.discovery.roles)
-    this.tokens ??= await this.discovery.tokens
-
-    const token = await this.tokens.invoke<string>('encrypt', {
-      input: { authority: context.authority, identity }
-    })
-
-    const authorization = `Token ${token}`
-
-    response.headers ??= new Headers()
-    response.headers.set('authorization', authorization)
-    response.headers.set('cache-control', 'no-store')
-  }
-
-  private async resolve(context: Context): Promise<Identity | null> {
-    const { authority } = context
-    const { authorization } = context.request.headers
-
-    if (authorization === undefined) return null
-
-    const retry = this.meter?.check(context, NONE) ?? 0
-
-    if (retry > 0) throw new http.TooManyRequests(retry)
-
-    const [scheme, credentials] = split(authorization)
-    const candidates = providersOf(scheme)
-
-    if (candidates === undefined)
-      throw new http.Unauthorized(`Unknown authentication scheme '${scheme}'`)
-
-    let provider: Remote | null = null
-    let result: AuthenticationResult | null = null
-
-    // the first provider that does not decline has claimed the credentials, and answers
-    // for them: a rejection from one that never recognized them is not the rejection
-    for (const candidate of candidates) {
-      this.components[candidate] ??= await this.discovery[candidate]
-
-      const answer = await this.components[candidate]!.invoke<AuthenticationResult>(
-        'authenticate',
-        {
-          input: {
-            scheme,
-            authority,
-            credentials
-          }
-        }
-      )
-
-      if (declined(answer)) continue
-
-      provider = candidate
-      result = answer
-
-      break
-    }
-
-    if (result === null || result instanceof Error) {
-      const code = result === null ? UNRECOGNIZED : codeOf(result)
-
-      if (code !== undefined) {
-        console.info('Authentication failed', { code })
-
-        context.rejection = code
-      }
-
-      this.meter?.use(context, null)
-
-      return null
-    }
-
-    const identity = result.identity
-
-    if (provider !== PRIMARY) {
-      if (await this.banned(identity)) throw new http.Unauthorized()
-
-      context.vetted = true
-    }
-
-    identity.scheme = scheme
-    identity.provider = provider!
-    identity.refresh = result.refresh
-
-    return identity
-  }
-
-  private permitted(context: Context): boolean {
-    const permissions = context.identity?.permissions
-
-    if (permissions === undefined) return true
-
-    // the route is matched on the normalized path, so the permission is too
-    return permits(permissions, context.request.method, context.url.pathname)
-  }
-
-  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
-  }
-}
-
-/** Whether a provider says the credentials are not of its kind, so the next is asked. */
-function declined(result: AuthenticationResult): boolean {
-  return result instanceof Error && codeOf(result) === UNRECOGNIZED
-}
-
-function codeOf(result: Error): string | undefined {
-  const code: string | unknown = (result as unknown as { code: string }).code
-
-  return typeof code === 'string' ? code : undefined
-}
-
-/** Whether the permissions admit the method on the path the request is routed by. */
-export function permits(
-  permissions: Record<string, string[]>,
-  method: string,
-  pathname: string
-): boolean {
-  return Object.entries(permissions).some(
-    ([pattern, methods]) =>
-      methods.some((allowed) => allowed === '*' || allowed === method) &&
-      glob(pattern).match(pathname)
-  )
-}
-
-/**
- * `minimatch(str, pattern)` compiles the pattern on every call, and a permission is
- * matched on every request the identity makes. Patterns arrive with an identity, hence
- * the bound.
- */
-function glob(pattern: string): Minimatch {
-  let compiled = GLOBS.get(pattern)
-
-  if (compiled === undefined) {
-    if (GLOBS.size >= GLOBS_LIMIT) GLOBS.clear()
-
-    compiled = new Minimatch(pattern)
-
-    GLOBS.set(pattern, compiled)
-  }
-
-  return compiled
-}
-
-/** What an address may fail at once, and the seconds it takes to earn them back. */
-const ATTEMPTS = 20
-const INTERVAL = 60
-
-/** Who is speaking when a request cannot be keyed. */
-const BOUNCER = 'Authentication bouncer'
-
-/** The meter's name in the atom: `atom:exposition:meter:credentials:<address>`. */
-const METER = 'credentials'
-
-const NONE: Parameter[] = []
-
-const GLOBS = new Map<string, Minimatch>()
-const GLOBS_LIMIT = 1024
-
-const constructors: Record<string, new (value: any, argument?: any) => Directive> = {
-  anonymous: Anonymous,
-  anyone: Anyone,
-  id: Id,
-  role: Role,
-  rule: Rule,
-  incept: Incept,
-  assert: Assert,
-  scheme: Scheme,
-  echo: Echo,
-  delegate: Delegate,
-  claims: Federation,
-  input: Input
-}
-
-const REMOTES: Remote[] = ['basic', 'federation', 'tokens', 'roles', 'bans', 'otp']

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

@@ -1,36 +0,0 @@
-import assert from 'node:assert'
-import { describe, it } from 'node:test'
-import { Delegate } from './Delegate.js'
-import type { Introspection } from '../../Introspection.js'
-
-describe('auth:delegate', () => {
-  function explanation(): Introspection {
-    return {
-      input: {
-        type: 'object',
-        properties: {
-          identity: { type: 'object' },
-          title: { type: 'string' }
-        },
-        required: ['identity', 'title']
-      }
-    } as unknown as Introspection
-  }
-
-  it('should take the property it embeds out of the input', () => {
-    const delegate = new Delegate('identity', null as never)
-    const described = delegate.describe(explanation())
-    const input = described.input as { properties: object; required: string[] }
-
-    assert.deepStrictEqual(Object.keys(input.properties), ['title'])
-    assert.deepStrictEqual(input.required, ['title'])
-  })
-
-  it('should leave an input that does not declare it alone', () => {
-    const delegate = new Delegate('originator', null as never)
-    const described = delegate.describe(explanation())
-    const input = described.input as { properties: object }
-
-    assert.deepStrictEqual(Object.keys(input.properties), ['identity', 'title'])
-  })
-})

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
-  }
-}