@toa.io/extensions.exposition 1.0.0-alpha.282 → 1.0.0-alpha.284

package/source/directives/auth/schemes.ts

@@ -1,24 +1,37 @@
 import type { Remote, Scheme } from './types.js'
 
-export const PROVIDERS: Record<Scheme, Remote> = {
-  basic: 'basic',
-  token: 'tokens',
-  bearer: 'federation',
-  code: 'federation',
-  otp: 'otp'
+/**
+ * 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: Scheme = 'token'
+export const PRIMARY: Remote = 'tokens'
 
 /**
- * The provider of a scheme, or nothing for a scheme that is not one — including a name a
+ * 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 provider (scheme: string): Remote | undefined {
+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.

package/source/directives/auth/types.ts

@@ -1,6 +1,7 @@
 import { type Component } from '@toa.io/core'
-import { type Maybe } from '@toa.io/types'
+import { type Maybe } from '@toa.io/core'
 import { type Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 import type * as http from '../../HTTP/index.js'
 import type * as io from '../../io.js'
 
@@ -13,6 +14,26 @@ export interface Directive {
     parameters: Parameter[]
   ) => boolean | Promise<boolean>
 
+  /**
+   * Whether this admits the identity where that can be told without a request — which is
+   * what describing a method is. `undefined` says it cannot be told: a directive reading a
+   * route variable's value or the body has neither here, and one that is not implemented
+   * says the same by its absence. Nothing here may have an effect on the request.
+   */
+  admits?: (
+    identity: Identity | null,
+    context: Context
+  ) => boolean | undefined | Promise<boolean | undefined>
+
+  /**
+   * What this directive makes of what the method says about itself, which is the reverse of
+   * what it does to a request: a property it fills from the identity is taken out of the
+   * input, because it is not the caller's to send — and a description that offers one invites
+   * a caller to name an identity that is not theirs. Nothing here may have an effect on the
+   * request.
+   */
+  describe?: (introspection: Introspection) => Introspection
+
   reply?: (context: Context) => http.OutgoingMessage | null
 
   settle?: (context: Context, response: http.OutgoingMessage) => Promise<void>
@@ -23,6 +44,9 @@ export interface Identity {
   roles?: string[]
   permissions?: Record<string, string[]>
   scheme: string | null // null for transient identities
+
+  /** The component that verified the credentials; none for a transient identity. */
+  provider?: Remote
   refresh: boolean
 }
 
@@ -43,6 +67,6 @@ export type AuthenticationResult = Maybe<{ identity: Identity, refresh: boolean
 export type Scheme = 'basic' | 'token' | 'bearer' | 'code' | 'otp'
 export type Remote = 'basic' | 'federation' | 'tokens' | 'roles' | 'bans' | 'otp'
 export type Discovery = Record<Remote, Promise<Component>>
-export type Schemes = Record<Scheme, Component>
+export type Components = Partial<Record<Remote, Component>>
 
 export type Create = (name: string, value: any, ...args: any[]) => Directive

package/source/directives/cache/Cache.ts

@@ -18,19 +18,28 @@ export class Cache implements DirectiveFamily<Directive> {
     return new Class(value)
   }
 
-  public preflight (): Output {
+  public precall (): Output {
     return null
   }
 
   public async settle (directives: Directive[], context: AuthenticatedContext, response: http.OutgoingMessage): Promise<void> {
-    const method = context.request.method
+    const directive = directives[0]
+
+    response.headers ??= new Headers()
+
+    // `cache:exact` sets what it is given, whatever the method: whether a reply may be
+    // stored at all is not a question about the method's cacheability, and a token
+    // endpoint answers a POST it must not have kept
+    if (directive instanceof Exact) {
+      directive.set(context, response.headers)
 
-    if (method !== 'GET' && method !== 'HEAD')
       return
+    }
 
-    const directive = directives[0]
+    const method = context.request.method
 
-    response.headers ??= new Headers()
+    if (method !== 'GET' && method !== 'HEAD')
+      return
 
     if (directive === undefined) {
       if (context.identity !== null && !Control.disabled(response.headers)) {

package/source/directives/cache/Control.ts

@@ -22,9 +22,6 @@ export class Control implements Directive {
   }
 
   public set (context: AuthenticatedContext, headers: Headers): void {
-    if (!['GET', 'HEAD', 'OPTIONS'].includes(context.request.method))
-      return
-
     this.control ??= this.resolve(context)
 
     if (Control.disabled(headers))

package/source/directives/dev/Development.ts

@@ -19,7 +19,7 @@ export class Development implements DirectiveFamily<Directive> {
     return new Class(value)
   }
 
-  public async preflight (directives: Directive[], input: Input): Promise<Output> {
+  public async precall (directives: Directive[], input: Input): Promise<Output> {
     let output = null
 
     for (const directive of directives) {

package/source/directives/flow/Fetch.ts

@@ -5,7 +5,7 @@ import { NotFound } from '../../HTTP/index.js'
 import type { Directive } from './types.js'
 import type { ReadableStream } from 'node:stream/web'
 import type { Remotes } from '../../Remotes.js'
-import type { Maybe } from '@toa.io/types'
+import type { Maybe } from '@toa.io/core'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io.js'
 import type { Input } from '../octets/types.js'

package/source/directives/flow/Flow.ts

@@ -18,7 +18,7 @@ export class Flow implements DirectiveFamily<Directive> {
     return new Class(value, remotes)
   }
 
-  public async preflight (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
+  public async precall (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
     for (const directive of directives) {
       if (directive.attach !== undefined)
         directive.attach(input)

package/source/directives/index.ts

@@ -5,10 +5,13 @@ import { dev } from './dev/index.js'
 import { octets } from './octets/index.js'
 import { io } from './io/index.js'
 import { map } from './map/index.js'
+import { mcp } from './mcp/index.js'
 import { req } from './require/index.js'
 import { flow } from './flow/index.js'
+import { discovery } from './oauth/index.js'
 import type { DirectiveFamily } from '../RTD/index.js'
 import type { Interceptor } from '../Interception.js'
 
-export const families: DirectiveFamily[] = [authorization, io, cache, map, req, flow, octets, dev]
-export const interceptors: Interceptor[] = [cors]
+export const families: DirectiveFamily[] =
+  [authorization, io, cache, map, mcp, req, flow, octets, dev]
+export const interceptors: Interceptor[] = [cors, discovery]

package/source/directives/io/Directive.ts

@@ -4,7 +4,7 @@ import type { Input as Context } from '../../io.js'
 import type * as http from '../../HTTP/index.js'
 
 export interface Directive {
-  preflight: (context: Context, parameters: Parameter[]) => void
+  precall: (context: Context, parameters: Parameter[]) => void
 
   /** Synchronous by contract: settling holds the response, and none of it needs I/O. */
   settle?: (context: Context, response: http.OutgoingMessage) => void

package/source/directives/io/IO.ts

@@ -1,11 +1,14 @@
+import { restrict } from '../../Introspection.js'
 import { Output } from './Output.js'
 import { Input } from './Input.js'
 import { Throttle } from './Throttle.js'
+import { Status } from './Status.js'
 import { Sync } from './lib/throttle/index.js'
 import type * as http from '../../HTTP/index.js'
 import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
 import type { Remotes } from '../../Remotes.js'
 import type { Constructor, Directive } from './Directive.js'
+import type { Introspection } from '../../Introspection.js'
 import { ATOM_GROUP } from '../../const.js'
 import type { extensions } from '@toa.io/core'
 
@@ -37,22 +40,49 @@ export class IO implements DirectiveFamily<Directive> {
     return new Directive(value, this.sync!, route)
   }
 
-  public preflight (directives: Directive[], context: http.Context,
+  public precall (directives: Directive[], context: http.Context,
     parameters: Parameter[]): null {
     let restricted = false
 
     for (const directive of directives) {
       restricted ||= directive instanceof Output
 
-      directive.preflight(context, parameters)
+      directive.precall(context, parameters)
     }
 
     if (!restricted)
-      DENIAL.preflight(context, parameters)
+      DENIAL.precall(context, parameters)
 
     return null
   }
 
+  /**
+   * What a whitelist admits is what the schema states. Without an `io:output` the reply is
+   * dropped before it is sent, so there is no output to describe at all.
+   */
+  public explain (directives: Directive[], _: http.Context,
+    introspection: Introspection): Introspection {
+    let restricted = false
+
+    for (const directive of directives) {
+      if (directive instanceof Input)
+        introspection.input = restrict(introspection.input, directive.allowed)
+
+      if (!(directive instanceof Output))
+        continue
+
+      restricted = true
+
+      if (!directive.disabled)
+        introspection.output = restrict(introspection.output, directive.allowed)
+    }
+
+    if (!restricted)
+      delete introspection.output
+
+    return introspection
+  }
+
   public settle (directives: Directive[], context: http.Context,
     output: http.OutgoingMessage): void {
     for (const directive of directives)
@@ -72,6 +102,7 @@ export class IO implements DirectiveFamily<Directive> {
 const constructors: Record<string, Constructor> = {
   input: Input,
   output: Output,
+  status: Status,
   throttle: Throttle
 }
 

package/source/directives/io/Input.ts

@@ -5,7 +5,8 @@ import type { Directive } from './Directive.js'
 import type { Input as Context } from '../../io.js'
 
 export class Input implements Directive {
-  private readonly allowed: Set<string>
+  /** what a client may send, which is therefore what the input schema states */
+  public readonly allowed: Set<string>
 
   public constructor (permissions: Permissions) {
     this.allowed = new Set(permissions)
@@ -15,7 +16,7 @@ export class Input implements Directive {
     schemas.input.validate<Permissions>(permissions, 'Incorrect \'io:input\' format')
   }
 
-  public preflight (context: Context): void {
+  public precall (context: Context): void {
     // Restrictions are on what the client sent, so the check goes to the front of the
     // pipeline whatever order the families ran in: `auth:delegate` embeds the identity
     // and `map:*` assigns mapped properties, and those additions are the server's own,

package/source/directives/io/Output.ts

@@ -7,10 +7,13 @@ import type { Input as Context } from '../../io.js'
 import type { OutgoingMessage } from '../../HTTP/index.js'
 
 export class Output implements Directive {
-  private readonly disabled: boolean = false
+  /** whether the reply passes whole, which is when the schema is the operation's own */
+  public readonly disabled: boolean = false
+
+  /** what a reply may carry, which is therefore what the output schema states */
+  public readonly allowed: Set<string>
   private readonly omitted: boolean = true
   private readonly permissions: string[] = []
-  private readonly allowed: Set<string>
 
   public constructor (permissions: Permissions) {
     if (typeof permissions === 'boolean')
@@ -29,13 +32,16 @@ export class Output implements Directive {
     schemas.output.validate(permissions, 'Incorrect \'io:output\' format')
   }
 
-  public preflight (context: Context): void {
+  public precall (context: Context): void {
     context.pipelines.response.push(this.restriction(context))
   }
 
   private restriction (context: Context) {
     return (message: OutgoingMessage): void => {
-      const error = message.status !== undefined && message.status >= 300
+      // what the gateway built is its own — a code and a message — and a restriction has
+      // nothing to say about it; everything else is a reply the operation returned, and is
+      // restricted whatever status it carries
+      const error = message.authentic === true
       const stream = message.body instanceof Stream
       const none = message.body === undefined || message.body === null
 

package/source/directives/io/Status.test.ts

@@ -0,0 +1,84 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Status } from './Status.js'
+import { Output } from './Output.js'
+import type { Input as Context } from '../../io.js'
+import type { OutgoingMessage } from '../../HTTP/index.js'
+
+const status = new Status('status')
+
+function context (): Context {
+  return { pipelines: { body: [], response: [] }, url: { pathname: '/' } } as unknown as Context
+}
+
+it('should take the status from the property and remove it', () => {
+  const response: OutgoingMessage = { body: { status: 400, error: 'invalid_request' } }
+
+  status.settle(context(), response)
+
+  assert.equal(response.status, 400)
+  assert.deepEqual(response.body, { error: 'invalid_request' })
+})
+
+it('should leave a reply that states no status alone', () => {
+  const response: OutgoingMessage = { body: { id: 'x' } }
+
+  status.settle(context(), response)
+
+  assert.equal(response.status, undefined)
+  assert.deepEqual(response.body, { id: 'x' })
+})
+
+it('should refuse a status that is not one', () => {
+  for (const value of ['400', null, {}, true])
+    assert.throws(() => {
+      status.settle(context(), { body: { status: value } } as OutgoingMessage)
+    }, /`io:status` expects 'status' to be a number/)
+})
+
+it('should refuse a declaration that is not a property name', () => {
+  for (const value of [1, null, {}, ['status']])
+    assert.throws(() => Status.validate(value), /`io:status` must be a string/)
+})
+
+it('should have a reply it named the status of restricted, whatever that status is', () => {
+  for (const stated of [200, 400]) {
+    const ctx = context()
+    const output = new Output(['code', 'error'])
+
+    output.precall(ctx, [])
+
+    const response: OutgoingMessage = {
+      body: { status: stated, code: 'SplxlO', error: 'invalid_grant', secret: 'x' }
+    }
+
+    status.settle(ctx, response)
+
+    for (const transform of ctx.pipelines.response)
+      transform(response)
+
+    assert.equal(response.status, stated)
+    assert.deepEqual(response.body, { code: 'SplxlO', error: 'invalid_grant' })
+  }
+})
+
+it('should leave a failure the gateway built alone, on such a route too', () => {
+  const ctx = context()
+  const output = new Output(['code'])
+
+  output.precall(ctx, [])
+
+  // what `Server.fail` builds out of an exception, on a route that also declares `io:status`
+  const response: OutgoingMessage = {
+    status: 422,
+    authentic: true,
+    body: { code: 'NOT_FOUND', message: 'nope' }
+  }
+
+  for (const transform of ctx.pipelines.response)
+    transform(response)
+
+  assert.deepEqual(response.body, { code: 'NOT_FOUND', message: 'nope' },
+    'a code and a message are not what a restriction has anything to say about')
+})

package/source/directives/io/Status.ts

@@ -0,0 +1,46 @@
+import assert from 'node:assert'
+import type { Directive } from './Directive.js'
+import type * as http from '../../HTTP/index.js'
+
+/**
+ * The status of the reply, taken from a property of what the operation returned and removed
+ * from it — an outcome the operation knows and the transport does not, like a protocol that
+ * states its error as a body rather than as a status of its own.
+ *
+ * Settled rather than transformed, so the status is set before anything reads it. A reply of
+ * 300 or above is left as the operation built it, which `io:output` does not restrict: a
+ * failure and a success are different shapes, and one list of permitted properties does not
+ * describe both.
+ */
+export class Status implements Directive {
+  private readonly property: string
+
+  public constructor (property: unknown) {
+    this.property = property as string
+  }
+
+  public static validate (value: unknown): asserts value is string {
+    assert.ok(typeof value === 'string', '`io:status` must be a string')
+  }
+
+  public precall (): void {
+    // nothing to do until the operation has answered
+  }
+
+  public settle (_: unknown, response: http.OutgoingMessage): void {
+    const body: unknown = response.body
+
+    if (body === null || typeof body !== 'object' || !(this.property in body))
+      return
+
+    const value: unknown = (body as Record<string, unknown>)[this.property]
+
+    assert.ok(typeof value === 'number',
+      `\`io:status\` expects '${this.property}' to be a number`)
+
+    response.status = value
+
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    delete (body as Record<string, unknown>)[this.property]
+  }
+}

package/source/directives/io/Throttle.ts

@@ -18,7 +18,7 @@ export class Throttle implements Directive {
     schemas.throttle.validate(declaration, 'Incorrect \'io:throttle\' format')
   }
 
-  public preflight (context: http.Context, parameters: Parameter[]): void {
+  public precall (context: http.Context, parameters: Parameter[]): void {
     const retry = this.quotas.check(context, parameters)
 
     if (retry > 0)

package/source/directives/io/lib/throttle/Quotas.ts

@@ -34,7 +34,7 @@ export class Quotas {
   private readonly entries = new Map<string, Entry>()
 
   /**
-   * The key computed at preflight, for settle to charge against.
+   * The key computed at precall, for settle to charge against.
    *
    * `segment` reads the route parameters, which settle is not given, and `identity`
    * can be refreshed between the two — so recomputing there would key a request
@@ -97,7 +97,7 @@ export class Quotas {
     if (!this.conditional || !this.keys.matches(input, output))
       return
 
-    // preflight always runs first, and a request it refuses never reaches settle
+    // precall always runs first, and a request it refuses never reaches settle
     const key = this.keyed.get(input) ?? this.keys.get(input)
 
     if (key === undefined)

package/source/directives/map/Headers.ts

@@ -1,7 +1,9 @@
 import assert from 'node:assert'
 import { cors } from '../cors/index.js'
 import { Mapping } from './Mapping.js'
+import { take } from '../../Introspection.js'
 import type { Input } from '../../io.js'
+import type { Introspection } from '../../Introspection.js'
 
 /**
  * Forbidden request header names: the browser sets them itself and a script cannot
@@ -25,6 +27,15 @@ export class Headers extends Mapping<Record<string, string>> {
     this.headers.forEach((header) => cors.allow(header))
   }
 
+  public override explain (introspection: Introspection): void {
+    for (const [property, header] of Object.entries(this.value)) {
+      const schema = take(introspection, property)
+
+      introspection.headers ??= {}
+      introspection.headers[property] = { ...schema, header }
+    }
+  }
+
   public properties (context: Input): Record<string, string> {
     context.pipelines.response.push((response) => {
       response.headers ??= new global.Headers()

package/source/directives/map/Map.ts

@@ -12,6 +12,7 @@ import type { Directive } from './Directive.js'
 import type { Properties } from './Properties.js'
 import type { DirectiveFamily, Parameter } from '../../RTD/index.js'
 import type { Input, Output } from '../../io.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Remotes } from '../../Remotes.js'
 
 export class Map implements DirectiveFamily {
@@ -31,7 +32,15 @@ export class Map implements DirectiveFamily {
       })
   }
 
-  public async preflight (directives: Directive[], context: Input, parameters: Parameter[]): Promise<Output> {
+  public explain (directives: Directive[], _: Input, introspection: Introspection): Introspection {
+    for (const directive of directives)
+      if (directive instanceof Mapping)
+        directive.explain(introspection)
+
+    return introspection
+  }
+
+  public async precall (directives: Directive[], context: Input, parameters: Parameter[]): Promise<Output> {
     const properties = {}
 
     for (const directive of directives)

package/source/directives/map/Mapping.ts

@@ -1,7 +1,9 @@
+import { take } from '../../Introspection.js'
 import type { Remotes } from '../../Remotes.js'
 import type { Directive } from './Directive.js'
 import type { Input } from '../../io.js'
 import type { Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 
 export abstract class Mapping<T = unknown> {
   protected value: T
@@ -13,6 +15,27 @@ export abstract class Mapping<T = unknown> {
   }
 
   public abstract properties (context: Input, parameters: Parameter[], directives: Directive[]): Output
+
+  /**
+   * What this mapping does to what the method says about itself, which is the reverse of
+   * what it does to a request: a property the gateway fills is taken out of the input,
+   * because it is not the caller's to send.
+   *
+   * The default says nothing more than that. A claim, an authority and a language come
+   * from the request itself and there is nowhere for a caller to put one; a header and a
+   * segment are the caller's, and those say where.
+   */
+  public explain (introspection: Introspection): void {
+    for (const property of this.names())
+      take(introspection, property)
+  }
+
+  /** The input properties this mapping fills, however its value names them. */
+  protected names (): string[] {
+    return typeof this.value === 'string'
+      ? [this.value]
+      : Object.keys(this.value as object)
+  }
 }
 
 type Properties = Record<string, unknown> | null

package/source/directives/map/Segments.ts

@@ -1,6 +1,8 @@
 import assert from 'node:assert'
 import { Mapping } from './Mapping.js'
+import { take } from '../../Introspection.js'
 import type { Parameter } from '../../RTD/index.js'
+import type { Introspection, Schema } from '../../Introspection.js'
 
 export class Segments extends Mapping<Record<string, string>> {
   public constructor (map: Record<string, string>) {
@@ -12,6 +14,16 @@ export class Segments extends Mapping<Record<string, string>> {
     super(map)
   }
 
+  /** A segment is the caller's, so it moves to the route rather than out of sight. */
+  public override explain (introspection: Introspection): void {
+    for (const property of Object.keys(this.value)) {
+      const schema = take(introspection, property)
+
+      introspection.route ??= {}
+      introspection.route[property] = schema ?? ({ type: 'string' } as unknown as Schema)
+    }
+  }
+
   public override properties (_: unknown, parameters: Parameter[]): Record<string, string> {
     return Object.entries(this.value).reduce((properties: Record<string, string>, [property, parameter]) => {
       const cut = parameter[0] === '~'

package/source/directives/mcp/MCP.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert'
+import { Tool } from './Tool.js'
+import type { Context } from '../../HTTP/index.js'
+import type { Introspection } from '../../Introspection.js'
+import type { DirectiveFamily } from '../../RTD/index.js'
+
+/** The name the family is declared under, and what `MCP` asks a method for. */
+export const FAMILY = 'mcp'
+
+export class MCP implements DirectiveFamily<Tool> {
+  public readonly name = FAMILY
+  public readonly mandatory = false
+
+  /** What this method is published as, which is what the nearest declaration says. */
+  public static published (directives: Tool[] | undefined): Tool | null {
+    return directives?.[0] ?? null
+  }
+
+  // eslint-disable-next-line max-params
+  public create (name: string, value: unknown, _: unknown, route: string): Tool {
+    assert.ok(name === 'tool', `Unknown directive: mcp:${name}`)
+
+    return new Tool(value, route)
+  }
+
+  /** What the route states this method is, which is the only thing that states it. */
+  public explain (directives: Tool[], _: Context,
+    introspection: Introspection): Introspection {
+    const tool = MCP.published(directives)
+
+    return tool === null ? introspection : { ...introspection, description: tool.description }
+  }
+}