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

package/source/directives/auth/Role.ts

@@ -36,6 +36,19 @@ export class Role implements Directive {
     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
 

package/source/directives/auth/Rule.ts

@@ -1,4 +1,5 @@
 import { type Parameter } from '../../RTD/index.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Context, Directive, Identity, Create } from './types.js'
 
 export class Rule implements Directive {
@@ -22,4 +23,32 @@ export class Rule implements Directive {
 
     return true
   }
+
+  /** Whatever each of them makes of it, in the order they were declared. */
+  public describe (introspection: Introspection): Introspection {
+    for (const directive of this.directives)
+      introspection = directive.describe?.(introspection) ?? introspection
+
+    return introspection
+  }
+
+  /** All of them, so one that refuses ends it and one that cannot tell leaves it untold. */
+  public async admits (identity: Identity | null, context: Context): Promise<boolean | undefined> {
+    let untold = false
+
+    for (const directive of this.directives) {
+      const admits = await directive.admits?.(identity, context)
+
+      if (admits === undefined) {
+        untold = true
+
+        continue
+      }
+
+      if (!admits)
+        return false
+    }
+
+    return untold ? undefined : true
+  }
 }

package/source/directives/auth/Scheme.ts

@@ -23,4 +23,9 @@ export class Scheme implements Directive {
 
     return false
   }
+
+  /** It admits nobody: it is there to refuse a scheme, not to authorize one. */
+  public admits (): boolean {
+    return false
+  }
 }

package/source/directives/auth/types.ts

@@ -1,6 +1,7 @@
 import { type Component } from '@toa.io/core'
 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>

package/source/directives/cache/Cache.ts

@@ -18,7 +18,7 @@ export class Cache implements DirectiveFamily<Directive> {
     return new Class(value)
   }
 
-  public preflight (): Output {
+  public precall (): Output {
     return null
   }
 

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/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,11 +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 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,3 +1,4 @@
+import { restrict } from '../../Introspection.js'
 import { Output } from './Output.js'
 import { Input } from './Input.js'
 import { Throttle } from './Throttle.js'
@@ -7,6 +8,7 @@ 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'
 
@@ -38,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)

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,7 +32,7 @@ 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))
   }
 

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

@@ -47,7 +47,7 @@ it('should have a reply it named the status of restricted, whatever that status
     const ctx = context()
     const output = new Output(['code', 'error'])
 
-    output.preflight(ctx, [])
+    output.precall(ctx, [])
 
     const response: OutgoingMessage = {
       body: { status: stated, code: 'SplxlO', error: 'invalid_grant', secret: 'x' }
@@ -67,7 +67,7 @@ it('should leave a failure the gateway built alone, on such a route too', () =>
   const ctx = context()
   const output = new Output(['code'])
 
-  output.preflight(ctx, [])
+  output.precall(ctx, [])
 
   // what `Server.fail` builds out of an exception, on a route that also declares `io:status`
   const response: OutgoingMessage = {

package/source/directives/io/Status.ts

@@ -23,7 +23,7 @@ export class Status implements Directive {
     assert.ok(typeof value === 'string', '`io:status` must be a string')
   }
 
-  public preflight (): void {
+  public precall (): void {
     // nothing to do until the operation has answered
   }
 

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

package/source/directives/mcp/Tool.test.ts

@@ -0,0 +1,66 @@
+import assert from 'node:assert'
+import { describe, it } from 'node:test'
+import { Tool } from './Tool.js'
+import { MCP } from './MCP.js'
+
+describe('mcp:tool', () => {
+  it('should take what the route states the tool is', () => {
+    assert.strictEqual(new Tool('The pots that are hot.', '/pots/hot').description,
+      'The pots that are hot.')
+  })
+
+  it('should not accept an empty description', () => {
+    assert.throws(() => new Tool('  ', '/pots'), /cannot be empty/)
+  })
+
+  it('should not accept a value that is not one', () => {
+    // `true` published a tool that stated nothing, back when an operation stated it instead
+    assert.throws(() => new Tool(true, '/pots'), /the value is what the tool is/)
+    assert.throws(() => new Tool(false, '/pots'), /the value is what the tool is/)
+    assert.throws(() => new Tool(1, '/pots'), /the value is what the tool is/)
+  })
+
+  it('should refuse a route no name can spell', () => {
+    assert.throws(() => new Tool('A pot.', '/pots/a.b'), /no tool name can spell/)
+    assert.throws(() => new Tool('A pot.', '/pots/:a.b'), /no tool name can spell/)
+
+    // an underscore is what the convention keeps for itself
+    assert.throws(() => new Tool('A pot.', '/pots/a_b'), /no tool name can spell/)
+  })
+
+  it('should name the route it refuses', () => {
+    assert.throws(() => new Tool('A pot.', '/pots/a.b'), /'\/pots\/a\.b'/)
+  })
+})
+
+describe('mcp:tool inheritance', () => {
+  const family = new MCP()
+
+  it('should take the nearest declaration', () => {
+    const own = new Tool('Nearest.', '/pots')
+    const inherited = new Tool('Furthest.', '/pots')
+
+    assert.strictEqual(MCP.published([own, inherited])?.description, 'Nearest.')
+  })
+
+  it('should publish nothing where nothing is declared', () => {
+    assert.strictEqual(MCP.published(undefined), null)
+    assert.strictEqual(MCP.published([]), null)
+  })
+
+  it('should describe a method with what the route states', () => {
+    const described = family.explain([new Tool('What the route is.', '/pots')], null as never,
+      { description: 'What the operation is.' })
+
+    assert.strictEqual(described.description, 'What the route is.')
+  })
+
+  it('should state nothing where nothing is declared', () => {
+    assert.strictEqual(family.explain([], null as never, {}).description, undefined)
+  })
+
+  it('should refuse a directive it does not know', () => {
+    assert.throws(() => family.create('resource', 'A pot.', null, '/pots'),
+      /Unknown directive: mcp:resource/)
+  })
+})

package/source/directives/mcp/Tool.ts

@@ -0,0 +1,28 @@
+import assert from 'node:assert'
+import { refusal } from '../../RPC/names.js'
+import { segment } from '../../RTD/segment.js'
+
+/**
+ * What one method is, published to a model. Declaring it is what publishes it, and what it
+ * says is what it says it is: a tool a model cannot read the purpose of is one it cannot
+ * choose, so there is no way to publish one that states nothing.
+ *
+ * The operation states what it is too, and that is not this. An operation is written without
+ * knowledge of any route, and a tool is an operation and a route together — the same
+ * operation mounted twice is two tools, and one sentence cannot be true of both.
+ */
+export class Tool {
+  public readonly description: string
+
+  public constructor (value: unknown, route: string) {
+    assert.ok(typeof value === 'string' && value.trim().length > 0,
+      'Directive mcp:tool: the value is what the tool is, which cannot be empty')
+
+    // a tool is called by name, so a route that cannot be named cannot be one — said where
+    // the mistake is, rather than as a tool that is quietly never listed
+    assert.ok(refusal(segment(route)) === null,
+      `Directive mcp:tool: '${route}' holds a segment no tool name can spell`)
+
+    this.description = value
+  }
+}

package/source/directives/mcp/index.ts

@@ -0,0 +1,6 @@
+import { MCP } from './MCP.js'
+
+export const mcp = new MCP()
+
+export { FAMILY, MCP } from './MCP.js'
+export type { Tool } from './Tool.js'

package/source/directives/oauth/Discovery.ts

@@ -26,8 +26,17 @@ export class Discovery implements Interceptor {
     if (options.oauth === undefined)
       return
 
+    /*
+     * `https` always: RFC 8414 has an issuer be one, and OAuth 2.1 has every endpoint of an
+     * authorization server be one — the loopback exception is a client's redirect URI, not
+     * a server's address. A gateway served without TLS has no authorization server a client
+     * may use, and naming it `http` would hide that behind documents none should accept.
+     *
+     * The host is the configured one, not the request's, which is the client's to write: a
+     * forged one would have these documents name someone else's token endpoint.
+     */
     for (const [authority, host] of Object.entries(options.authorities))
-      this.authorities.set(authority, documents(origin(host), options.oauth))
+      this.authorities.set(authority, documents(`https://${host}`, options.oauth))
   }
 
   public reset (): void {
@@ -58,19 +67,4 @@ export class Discovery implements Interceptor {
   }
 }
 
-/**
- * The absolute URL an authority is reached at. Loopback is served over http and everything
- * else over https: the gateway may sit behind a terminating proxy, so the connection does
- * not say which, and the configured host does. Taken from the configuration rather than
- * from the request's `host`, which is the client's to write.
- */
-function origin (host: string): string {
-  const name = host.split(':')[0]
-
-  const loopback = name === 'localhost' || name === '127.0.0.1' || name === '[::1]' ||
-    name.endsWith('.localhost')
-
-  return `${loopback ? 'http' : 'https'}://${host}`
-}
-
 const UNAUTHORIZED = 401

package/source/directives/octets/Octets.ts

@@ -28,7 +28,7 @@ export class Octets implements DirectiveFamily<Directive> {
     return new Class(value, this.discovery, remotes)
   }
 
-  public async preflight (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
+  public async precall (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
     let context: Context | null = null
     let action: Directive | null = null
 

package/source/directives/require/Directive.ts

@@ -1,5 +1,5 @@
 import type { Input } from '../../io.js'
 
 export interface Directive {
-  preflight: (context: Input) => void
+  precall: (context: Input) => void
 }

package/source/directives/require/Headers.ts

@@ -12,7 +12,7 @@ export class Headers implements Directive {
     this.headers = headers
   }
 
-  public preflight (context: Input): void {
+  public precall (context: Input): void {
     for (const header of this.headers)
       if (context.request.headers[header] === undefined)
         throw new BadRequest(`Header required: ${header}`)