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

package/source/Tenant.ts

@@ -1,73 +0,0 @@
-import { setTimeout } from 'node:timers/promises'
-import { Connector } from '@toa.io/core'
-import { BRANCH_TTL } from '@toa.io/definitions/extensions.exposition'
-import type { bindings } from '@toa.io/core/types'
-import type { Label } from './discovery.js'
-import type { Branch } from './Branch.js'
-
-export class Tenant extends Connector {
-  private readonly broadcast: Broadcast
-  private readonly branch: Omit<Branch, 'timestamp'>
-  private started = 0
-  private stopped = false
-
-  public constructor(broadcast: Broadcast, branch: Omit<Branch, 'timestamp'>) {
-    super()
-
-    this.broadcast = broadcast
-    this.branch = branch
-
-    this.depends(broadcast)
-  }
-
-  public override async open(): Promise<void> {
-    this.started = Date.now()
-
-    await this.expose()
-    await this.broadcast.receive('ping', this.expose.bind(this))
-
-    void this.announce()
-  }
-
-  /**
-   * Announcing is stopped where the teardown begins, not in `dispose`, which a connector
-   * runs after every one of its dependencies has gone. A component on its way out that
-   * announces itself once more has its routes held open by whoever is listening, and the
-   * requests that follow reach nothing.
-   */
-  protected override async close(): Promise<void> {
-    this.stopped = true
-  }
-
-  private async announce(): Promise<void> {
-    while (!this.stopped) {
-      const delay = exposeInterval(Date.now() - this.started)
-
-      await setTimeout(delay, undefined, { ref: false })
-
-      if (this.stopped) break
-
-      await this.expose()
-    }
-  }
-
-  private async expose(): Promise<void> {
-    // the ping subscription outlives the announcing loop, and answering one on the way out
-    // is the same announcement by another route
-    if (this.stopped) return
-
-    await this.broadcast.transmit('expose', { ...this.branch, timestamp: this.started })
-  }
-}
-
-function exposeInterval(uptime: number): number {
-  return Math.round(
-    EXPOSE_MAX - (EXPOSE_MAX - EXPOSE_MIN) * Math.exp(-uptime / EXPOSE_TAU)
-  )
-}
-
-const EXPOSE_MIN = 5_000
-const EXPOSE_MAX = Math.round(BRANCH_TTL / 2.1)
-const EXPOSE_TAU = 900_000
-
-type Broadcast = bindings.Broadcast<Label>

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

@@ -1,70 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Anonymous } from './Anonymous.js'
-import type { Context } from './types.js'
-
-const context = (
-  headers: Record<string, string>,
-  flags: { procedural?: boolean; exploratory?: boolean } = {}
-): Context =>
-  ({
-    request: { headers },
-    procedural: false,
-    exploratory: false,
-    ...flags
-  }) as unknown as Context
-
-describe('anonymous', () => {
-  it('should admit a request that presents nothing', () => {
-    assert.equal(new Anonymous(true).authorize(null, context({})), true)
-  })
-
-  it('should refuse a request that presents a credential', () => {
-    // it would make the reply uncacheable, which is the whole of the rule
-    assert.equal(
-      new Anonymous(true).authorize(null, context({ authorization: 'Token x' })),
-      false
-    )
-  })
-
-  it('should admit a procedure whatever the request presented', () => {
-    // what a procedure answers is a value in an envelope, and the envelope is `no-store`
-    const procedural = context({ authorization: 'Token x' }, { procedural: true })
-
-    assert.equal(new Anonymous(true).authorize(null, procedural), true)
-  })
-
-  it('should admit a description whatever the request presented', () => {
-    // a description is not the reply a cache would hold, and varies by who asked in any case
-    const exploratory = context({ authorization: 'Token x' }, { exploratory: true })
-
-    assert.equal(new Anonymous(true).authorize(null, exploratory), true)
-  })
-
-  it('should refuse where it admits nobody', () => {
-    assert.equal(new Anonymous(false).authorize(null, context({})), false)
-    assert.equal(
-      new Anonymous(false).authorize(null, context({}, { procedural: true })),
-      false
-    )
-    assert.equal(
-      new Anonymous(false).authorize(null, context({}, { exploratory: true })),
-      false
-    )
-  })
-
-  it('should describe a method as it authorizes one', () => {
-    const directive = new Anonymous(true)
-
-    assert.equal(directive.admits(null, context({ authorization: 'Token x' })), false)
-    assert.equal(
-      directive.admits(null, context({ authorization: 'Token x' }, { procedural: true })),
-      true
-    )
-    assert.equal(
-      directive.admits(null, context({ authorization: 'Token x' }, { exploratory: true })),
-      true
-    )
-  })
-})

package/source/directives/auth/Anonymous.ts

@@ -1,36 +0,0 @@
-import { type Directive, type Context } from './types.js'
-import type { Introspection } from '../../Introspection.js'
-
-export class Anonymous implements Directive {
-  private readonly allow: boolean
-
-  public constructor(allow: boolean) {
-    this.allow = allow
-  }
-
-  /**
-   * A credential refuses, because it would make the reply uncacheable — which is the whole
-   * of the rule, and none of it applies to a procedure, nor to a description. What a
-   * procedure answers is a value in an envelope, and the envelope is the one thing that is
-   * cached or not; what a description answers is what the resource is, which is not the
-   * reply a cache would hold and varies by who asked in any case.
-   */
-  public authorize(_: any, context: Context): boolean {
-    if (context.procedural || context.exploratory) return this.allow
-
-    return 'authorization' in context.request.headers ? false : this.allow
-  }
-
-  public admits(_: any, context: Context): boolean {
-    return this.authorize(_, context)
-  }
-
-  /**
-   * That nothing guards it is something said rather than something left unsaid: it is also
-   * what refuses a caller presenting a credential, and a client with one has to know which
-   * methods not to present it to.
-   */
-  public describe(introspection: Introspection): Introspection {
-    return this.allow ? { ...introspection, anonymous: true } : introspection
-  }
-}

package/source/directives/auth/Anyone.ts

@@ -1,23 +0,0 @@
-import { type Directive, type Context } from './types.js'
-import type { Introspection } from '../../Introspection.js'
-
-export class Anyone implements Directive {
-  private readonly allow: boolean
-
-  public constructor(allow: boolean) {
-    this.allow = allow
-  }
-
-  public authorize(_: any, context: Context): boolean {
-    return context.identity !== null && this.allow
-  }
-
-  public admits(_: any, context: Context): boolean {
-    return this.authorize(_, context)
-  }
-
-  /** Whoever asks, as long as they are somebody. */
-  public describe(introspection: Introspection): Introspection {
-    return this.allow ? { ...introspection, authenticated: true } : introspection
-  }
-}

package/source/directives/auth/Assert.ts

@@ -1,43 +0,0 @@
-import assert from 'node:assert'
-import { newid } from '@toa.io/generic'
-import * as http from '../../HTTP/index.js'
-import { Incept } from './Incept.js'
-import type { Context, Directive, Identity } from './types.js'
-
-export class Assert implements Directive {
-  private readonly disabled: boolean
-
-  public constructor(enabled: boolean) {
-    assert.ok(
-      typeof enabled === 'boolean',
-      '`auth:assert` directive value must be a boolean'
-    )
-
-    this.disabled = !enabled
-  }
-
-  /** It admits nobody: it is there to require a credential, not to authorize one. */
-  public admits(): boolean {
-    return false
-  }
-
-  public async authorize(identity: Identity | null, context: Context): Promise<boolean> {
-    if (!this.disabled) await this.incept(context, identity)
-
-    return false
-  }
-
-  private async incept(context: Context, identity: Identity | null): Promise<void> {
-    if (context.request.headers.authorization === undefined) throw new http.Unauthorized()
-
-    if (identity === null) {
-      if (!Incept.acceptable(context)) throw new http.Unauthorized()
-
-      context.identity = await Incept.incept(context, newid())
-
-      context.pipelines.response.push((response) => {
-        response.status = 201
-      })
-    }
-  }
-}

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

@@ -1,24 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { permits } from './Authorization.js'
-
-const permissions = { '/users/me/**': ['GET'], '/notes/': ['*'] }
-
-it('should permit a matching method and path', () => {
-  assert.equal(permits(permissions, 'GET', '/users/me/posts/'), true)
-  assert.equal(permits(permissions, 'DELETE', '/notes/'), true)
-})
-
-it('should refuse another method or path', () => {
-  assert.equal(permits(permissions, 'POST', '/users/me/posts/'), false)
-  assert.equal(permits(permissions, 'GET', '/admin/'), false)
-})
-
-it('should be matched on the routed path, not on the request URL', () => {
-  const raw = '/users/me/%2e%2e/admin/'
-  const routed = new URL(raw, 'https://example.com').pathname
-
-  assert.equal(routed, '/users/admin/')
-  assert.equal(permits(permissions, 'GET', routed), false)
-})

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 '@toa.io/definitions/extensions.exposition'
-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'])
-  })
-})