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

package/source/RTD/walk.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Tree } from './Tree.js'
+import { address, name } from '../RPC/names.js'
+import type { EndpointsFactory } from '../Endpoint.js'
+import type { DirectiveFactory } from './Directives.js'
+import type * as syntax from './syntax/index.js'
+
+const endpoints = {} as unknown as EndpointsFactory
+
+const directives = {
+  create: () => ({
+    precall: async () => null,
+    settle: async () => undefined,
+    dispose: () => undefined
+  }),
+  dispose: mock.fn()
+} as unknown as DirectiveFactory
+
+const node = (path: string, verbs: string[] = [], routes: syntax.Route[] = []): syntax.Route => ({
+  path,
+  node: {
+    routes,
+    methods: verbs.map((verb) => ({ verb, directives: [] })),
+    directives: []
+  }
+})
+
+const trunk = (routes: syntax.Route[], verbs: string[] = []): syntax.Node => ({
+  routes,
+  methods: verbs.map((verb) => ({ verb, directives: [] })),
+  directives: []
+})
+
+/** What a walk names, which is what a caller of `/.rpc` would write. */
+function names (tree: Tree): string[] {
+  return [...tree.walk()].map(({ segments, verb }) => name(segments, verb))
+    .filter((named): named is string => named !== null)
+}
+
+describe('walk', () => {
+  it('should name the trunk by its verb alone', () => {
+    const tree = new Tree(trunk([], ['GET']), endpoints, directives)
+
+    assert.deepEqual(names(tree), ['GET'])
+  })
+
+  it('should name every method of every route', () => {
+    const tree = new Tree(trunk([
+      node('/pots', ['GET', 'POST'], [node('/:id', ['GET', 'DELETE'])])
+    ]), endpoints, directives)
+
+    assert.deepEqual(names(tree).sort(), [
+      'pots/GET', 'pots/POST', 'pots/_id/DELETE', 'pots/_id/GET'
+    ])
+  })
+
+  it('should walk a branch that was merged', () => {
+    const tree = new Tree(trunk([]), endpoints, directives)
+
+    tree.merge(trunk([node('/pots', ['GET'])]), { namespace: 'default', component: 'pots' })
+
+    assert.deepEqual(names(tree), ['pots/GET'])
+  })
+
+  it('should name a tail', () => {
+    const tree = new Tree(trunk([node('/files', [], [node('/**', ['GET'])])]),
+      endpoints, directives)
+
+    assert.deepEqual(names(tree), ['files/__/GET'])
+  })
+
+  it('should skip an intermediate node, whose route answers in its place', () => {
+    const tree = new Tree(trunk([
+      // `/posts` is intermediate: `/posts/` is answered by its `/` route, not by itself
+      node('/posts', ['PATCH'], [node('/', ['PUT'])])
+    ]), endpoints, directives)
+
+    assert.deepEqual(names(tree), ['posts/PUT'])
+  })
+
+  it('should name nothing where a segment cannot be spelled', () => {
+    const tree = new Tree(trunk([node('/v1.0', ['GET']), node('/pots', ['GET'])]),
+      endpoints, directives)
+
+    assert.deepEqual(names(tree), ['pots/GET'])
+  })
+
+  it('should name what the tree then matches', () => {
+    const tree = new Tree(trunk([
+      node('/pots', ['GET'], [node('/:id', ['GET']), node('/hot', ['GET'])]),
+      node('/files', [], [node('/**', ['GET'])])
+    ], ['GET']), endpoints, directives)
+
+    const params = { id: 'a1b2', '**': 'a/b/c' }
+
+    for (const { segments, verb } of tree.walk()) {
+      const named = name(segments, verb)
+
+      assert.notStrictEqual(named, null, 'every walked method has a name')
+
+      const { path } = address(named!, params)
+      const match = tree.match(path)
+
+      assert.notStrictEqual(match, null, `'${named!}' resolves to '${path}', which matches`)
+      assert.ok(verb in match!.node.methods, `'${named!}' matches a node that answers ${verb}`)
+    }
+  })
+})

package/source/const.ts

@@ -2,3 +2,18 @@ export const BRANCH_TTL = 1_800_000
 
 /** The replicas of the gateway decide together, whatever context they serve. */
 export const ATOM_GROUP = 'exposition'
+
+/**
+ * Where JSON-RPC is served, for every procedure at once. Pinned rather than configured: a
+ * path an application could choose is a path it could collide with a route of its own.
+ */
+export const RPC = '/.rpc'
+
+/** Calls one request may carry where the annotation does not say. */
+export const BATCH = 32
+
+/**
+ * Where the Model Context Protocol is served. Pinned for the reason `/.rpc` is: a path an
+ * application could choose is a path it could collide with a route of its own.
+ */
+export const MCP = '/.mcp'

package/source/deployment.ts

@@ -67,6 +67,15 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   if (annotation.bouncer !== undefined)
     properties.bouncer = annotation.bouncer
 
+  if (annotation.oauth !== undefined)
+    properties.oauth = annotation.oauth
+
+  if (annotation.rpc !== undefined)
+    properties.rpc = annotation.rpc
+
+  if (annotation.mcp !== undefined)
+    properties.mcp = annotation.mcp
+
   service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
     value: JSON.stringify(properties)
@@ -83,4 +92,5 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   return { services: [service] }
 }
 
-type Properties = Pick<Annotation, 'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip'>
+type Properties = Pick<Annotation,
+'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip' | 'oauth' | 'rpc' | 'mcp'>

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

@@ -0,0 +1,38 @@
+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>, procedural = false): Context =>
+  ({ request: { headers }, procedural }) 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' }, true)
+
+    assert.equal(new Anonymous(true).authorize(null, procedural), 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({}, 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' }, true)), true)
+  })
+})

package/source/directives/auth/Anonymous.ts

@@ -7,9 +7,21 @@ export class Anonymous implements Directive {
     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: what a procedure answers is a value
+   * in an envelope, and the envelope is the one thing that is cached or not.
+   */
   public authorize (_: any, context: Context): boolean {
+    if (context.procedural)
+      return this.allow
+
     return 'authorization' in context.request.headers
       ? false
       : this.allow
   }
+
+  public admits (_: any, context: Context): boolean {
+    return this.authorize(_, context)
+  }
 }

package/source/directives/auth/Anyone.ts

@@ -10,4 +10,8 @@ export class Anyone implements Directive {
   public authorize (_: any, context: Context): boolean {
     return context.identity !== null && this.allow
   }
+
+  public admits (_: any, context: Context): boolean {
+    return this.authorize(_, context)
+  }
 }

package/source/directives/auth/Authorization.ts

@@ -16,11 +16,12 @@ import { Federation } from './Federation.js'
 import { Anyone } from './Anyone.js'
 import { Input, type Declaration } from './Input.js'
 import { split } from './split.js'
-import { PRIMARY, provider as providerOf } from './schemes.js'
+import { PRIMARY, UNRECOGNIZED, providers as providersOf } from './schemes.js'
 import { ATOM_GROUP } from '../../const.js'
 import { Quotas, Sync } from '../io/lib/throttle/index.js'
 import { Keys } from '../io/lib/throttle/Keys.js'
 import type { Output } from '../../io.js'
+import type { Introspection } from '../../Introspection.js'
 import type { Component } from '@toa.io/core'
 import type { Remotes } from '../../Remotes.js'
 import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
@@ -34,7 +35,7 @@ import type {
   Identity,
   Context,
   Remote,
-  Schemes
+  Components
 } from './types.js'
 
 export class Authorization implements DirectiveFamily<Directive, Extension> {
@@ -42,7 +43,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   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
@@ -100,11 +101,18 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
   }
 
-  public async preflight (directives: Directive[],
-    context: Context,
-    parameters: Parameter[]): Promise<Output> {
+  /**
+   * 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)
 
@@ -121,18 +129,69 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
       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.scheme === PRIMARY && !identity.refresh)
+    if (identity.provider === PRIMARY && !identity.refresh)
       return
 
     if (await this.banned(identity))
@@ -140,7 +199,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
 
     // 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.scheme === PRIMARY)
+    if (identity.provider === PRIMARY)
       identity.roles = await Role.get(identity, this.discovery.roles)
     else
       identity.roles ??= await Role.get(identity, this.discovery.roles)
@@ -170,25 +229,40 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
       throw new http.TooManyRequests(retry)
 
     const [scheme, credentials] = split(authorization)
-    const provider = providerOf(scheme)
+    const candidates = providersOf(scheme)
 
-    if (provider === undefined)
+    if (candidates === undefined)
       throw new http.Unauthorized(`Unknown authentication scheme '${scheme}'`)
 
-    this.schemes[scheme] ??= await this.discovery[provider]
+    let provider: Remote | null = null
+    let result: AuthenticationResult | null = null
 
-    const result = await this.schemes[scheme].invoke<AuthenticationResult>('authenticate', {
-      input: {
-        scheme,
-        authority,
-        credentials
-      }
-    })
+    // 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
 
-    if (result instanceof Error) {
-      const code: string | unknown = (result as unknown as { code: string }).code
+      provider = candidate
+      result = answer
 
-      if (typeof code === 'string') {
+      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
@@ -201,9 +275,10 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
 
     const identity = result.identity
 
-    if (scheme !== PRIMARY && (await this.banned(identity))) throw new http.Unauthorized()
+    if (provider !== PRIMARY && (await this.banned(identity))) throw new http.Unauthorized()
 
     identity.scheme = scheme
+    identity.provider = provider!
     identity.refresh = result.refresh
 
     return identity
@@ -228,6 +303,17 @@ 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]) =>

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,5 +1,7 @@
 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'
 
@@ -22,6 +24,18 @@ export class Delegate implements Directive {
     return true
   }
 
+  /** It admits whoever there is, and embedding the identity is the request's business. */
+  public admits (identity: Identity | null): boolean {
+    return identity !== null
+  }
+
+  /** The property it embeds is the identity's, so a caller has nothing to put there. */
+  public describe (introspection: Introspection): Introspection {
+    take(introspection, this.property)
+
+    return introspection
+  }
+
   private embed (body: unknown, identity: Identity): Record<string, unknown> {
     if (body === undefined)
       body = {}

package/source/directives/auth/Echo.ts

@@ -12,6 +12,11 @@ export class Echo implements Directive {
     return true
   }
 
+  /** What `authorize` answers, without inventing the identity it would go on to invent. */
+  public admits (identity: Identity | null, context: Context): boolean {
+    return !(identity === null && 'authorization' in context.request.headers)
+  }
+
   public reply (context: Context): OutgoingMessage {
     const body = context.identity!
 

package/source/directives/auth/Incept.ts

@@ -3,14 +3,14 @@ import { console } from 'openspan'
 import * as http from '../../HTTP/index.js'
 import { split } from './split.js'
 import { create } from './create.js'
-import { INCEPTION, UNKNOWN, provider as providerOf } from './schemes.js'
+import { INCEPTION, UNKNOWN, providers as providersOf } from './schemes.js'
 import { Role } from './Role.js'
 import type { Component } from '@toa.io/core'
-import type { Maybe } from '@toa.io/types'
-import type { Directive, Discovery, Identity, Context, Schemes, Ban } from './types.js'
+import type { Maybe } from '@toa.io/core'
+import type { Directive, Discovery, Identity, Context, Components, Ban } from './types.js'
 
 export class Incept implements Directive {
-  private static readonly schemes: Schemes = {} as unknown as Schemes
+  private static readonly components: Components = {}
   private static discovery: Discovery
   private static bans: Component | null = null
 
@@ -26,12 +26,17 @@ export class Incept implements Directive {
 
   public static async incept (context: Context, id: string): Promise<Identity> {
     const [scheme, credentials] = split(context.request.headers.authorization!)
-    const provider = providerOf(scheme)
+    const candidates = providersOf(scheme)
 
-    if (provider === undefined)
+    if (candidates === undefined)
       throw new http.BadRequest('Authentication scheme is not supported')
 
-    if (!INCEPTION.includes(provider))
+    // a scheme several providers claim is incepted by the one that incepts; `Bearer`
+    // carries an access token this gateway issued, and an identity cannot be incepted
+    // from a credential it would itself have to exist to hold
+    const provider = candidates.find((candidate) => INCEPTION.includes(candidate))
+
+    if (provider === undefined)
       throw new http.Unauthorized()
 
     Incept.bans ??= await Incept.discovery.bans
@@ -41,9 +46,9 @@ export class Incept implements Directive {
     if (ban.banned)
       throw new http.Unauthorized()
 
-    Incept.schemes[scheme] ??= await Incept.discovery[provider]
+    Incept.components[provider] ??= await Incept.discovery[provider]
 
-    const identity = await Incept.schemes[scheme].invoke<Maybe<Identity>>('incept', {
+    const identity = await Incept.components[provider]!.invoke<Maybe<Identity>>('incept', {
       input: {
         scheme,
         authority: context.authority,
@@ -56,8 +61,9 @@ export class Incept implements Directive {
       throw new http.UnprocessableEntity(identity)
 
     identity.scheme = scheme
-    identity.roles = []
 
+    // the roles are read where the token is minted: an Identity incepted as the principal
+    // has one already
     return identity
   }
 

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/schemes.test.ts

@@ -1,14 +1,18 @@
 import { it } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { provider } from './schemes.js'
+import { providers } from './schemes.js'
 
 it('should resolve a known scheme', () => {
-  assert.equal(provider('basic'), 'basic')
-  assert.equal(provider('bearer'), 'federation')
+  assert.deepEqual(providers('basic'), ['basic'])
+  assert.deepEqual(providers('code'), ['federation'])
+})
+
+it('should resolve every provider claiming a scheme, in order', () => {
+  assert.deepEqual(providers('bearer'), ['tokens', 'federation'])
 })
 
 it('should not resolve a property of Object.prototype', () => {
   for (const name of ['constructor', '__proto__', 'toString', 'hasOwnProperty'])
-    assert.equal(provider(name), undefined)
+    assert.equal(providers(name), undefined)
 })