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

package/source/directives/auth/Anyone.ts

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

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

@@ -0,0 +1,24 @@
+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,20 +1,31 @@
 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 { 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'
-import type { Parameter, DirectiveFamily } from '../../RTD'
+import type { Remotes } from '../../Remotes.js'
+import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
+import type { Host } from '../../Factory.js'
 import type {
   AuthenticationResult,
   Ban,
@@ -22,119 +33,277 @@ import type {
   Discovery,
   Extension,
   Identity,
-  Input,
+  Context,
   Remote,
-  Schemes
-} from './types'
+  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 schemes = {} as unknown as Schemes
+  private readonly components: Components = {}
   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.`)
+  /** 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)),
-      Incept, () => new Incept(value as string, this.discovery),
-      () => new Class(value))
+    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 async preflight (directives: Directive[],
-    input: Input,
-    parameters: Parameter[]): Promise<Output> {
-    const identity = await this.resolve(input.authority, input.request.headers.authorization)
+  public arrange(directives: Directive[]): void {
+    directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
+  }
 
-    input.identity = identity
+  /**
+   * 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(identity, input, parameters)
+      const allow = await directive.authorize(context.identity, context, parameters)
 
       if (allow)
-        return directive.reply?.(identity) ?? null
+        if (this.permitted(context)) return directive.reply?.(context) ?? null
+        else throw new http.Forbidden()
     }
 
-    if (identity === null)
-      throw new http.Unauthorized()
-    else
-      throw new http.Forbidden()
+    if (context.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)
+  /**
+   * 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
 
-    const identity = request.identity
+    for (const directive of directives) {
+      const admits = await directive.admits?.(context.identity, context)
 
-    if (identity === null)
-      return
+      if (admits === undefined) {
+        untold = true
 
-    if (identity.scheme === PRIMARY && !identity.refresh)
-      return
+        continue
+      }
+
+      if (admits) {
+        admitted = true
 
-    // Role directive may have already set the value
-    if (identity.roles === undefined)
-      await Role.set(identity, this.discovery.roles)
+        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: request.authority, identity }
+      input: { authority: context.authority, identity }
     })
 
     const authorization = `Token ${token}`
 
     response.headers ??= new Headers()
     response.headers.set('authorization', authorization)
-    response.headers.append('cache-control', 'no-store')
+    response.headers.set('cache-control', 'no-store')
   }
 
-  private async resolve (authority: string, authorization: string | undefined): Promise<Identity | null> {
-    if (authorization === undefined)
-      return null
+  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 provider = PROVIDERS[scheme]
+    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
 
-    if (!(provider in this.discovery))
-      throw new http.Unauthorized(`Unknown authentication scheme '${scheme}'.`)
+    // 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]
 
-    this.schemes[scheme] ??= await this.discovery[provider]
+      const answer = await this.components[candidate]!.invoke<AuthenticationResult>(
+        'authenticate',
+        {
+          input: {
+            scheme,
+            authority,
+            credentials
+          }
+        }
+      )
 
-    const result = await this.schemes[scheme].invoke<AuthenticationResult>('authenticate', {
-      input: {
-        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
       }
-    })
 
-    if (result instanceof Error) return null
+      this.meter?.use(context, null)
+
+      return null
+    }
 
     const identity = result.identity
 
-    if (scheme !== PRIMARY && (await this.banned(identity))) throw new http.Unauthorized()
+    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 async banned (identity: Identity): Promise<boolean> {
+  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 } })
@@ -143,15 +312,77 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   }
 }
 
+/** 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
+  delegate: Delegate,
+  claims: Federation,
+  input: Input
 }
 
-const REMOTES: Remote[] = ['basic', 'federation', 'tokens', 'roles', 'bans']
+const REMOTES: Remote[] = ['basic', 'federation', 'tokens', 'roles', 'bans', 'otp']

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

@@ -0,0 +1,36 @@
+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,35 +1,54 @@
-import { BadRequest } from '../../HTTP'
-import { type Directive, type Identity } from './types'
-import type { Input } from '../../io'
+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) {
+  public constructor(property: string, discovery: Promise<Component>) {
     this.property = property
+    this.discovery = discovery
   }
 
-  public authorize (identity: Identity | null, context: Input): boolean {
-    if (identity === null)
-      return false
+  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
   }
 
-  private embed (body: unknown, identity: Identity): Record<string, unknown> {
-    if (body === undefined)
-      body = {}
+  /** 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] = identity
+    body[this.property] = structuredClone(identity)
 
     return body
   }
 }
 
-function check (body: unknown): asserts body is Record<string, unknown> {
+function check(body: unknown): asserts body is Record<string, unknown> {
   if (typeof body !== 'object' || body === null)
     throw new BadRequest('Invalid request body')
 }