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

package/features/steps/components/octets.tester/operations/redirect.js

@@ -1,7 +1,12 @@
 function redirect (input) {
-  return input.parameters.type in urls ? { url: urls[input.parameters.type] } : new Error()
+  return input.parameters.type in urls ? { url: urls[input.parameters.type] } : ERR_UNKNOWN
 }
 
+// an error a caller is meant to see carries a code, always
+const ERR_UNKNOWN = new (class UnknownError extends Error {
+  code = 'ERROR'
+})()
+
 const urls = {
   'rfc': 'https://www.rfc-editor.org/rfc/rfc9564.txt',
   'img': 'https://www.w3.org/assets/logos/w3c/w3c-no-bars.svg'

package/features/steps/components/users/manifest.toa.yaml

@@ -21,6 +21,7 @@ operations:
   create:
     concurrency: retry
     query: false
+    errors: [0]
     input:
       properties:
         name:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.283",
   "type": "module",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -19,9 +19,9 @@
   },
   "dependencies": {
     "@simplewebauthn/server": "14.0.0",
-    "@toa.io/core": "1.0.0-alpha.282",
-    "@toa.io/generic": "1.0.0-alpha.282",
-    "@toa.io/schemas": "1.0.0-alpha.282",
+    "@toa.io/core": "1.0.0-alpha.283",
+    "@toa.io/generic": "1.0.0-alpha.283",
+    "@toa.io/schemas": "1.0.0-alpha.283",
     "bcryptjs": "3.0.3",
     "content-type": "3.0.0",
     "jose": "6.2.10",
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1",
-    "transpile": "tsc && npm run transpile:bans && npm run transpile:basic && npm run transpile:tokens && npm run transpile:roles && npm run transpile:federation && npm run transpile:credentials && npm run transpile:keys && npm run transpile:passkeys && npm run transpile:otp",
+    "transpile": "tsc && npm run transpile:bans && npm run transpile:basic && npm run transpile:tokens && npm run transpile:roles && npm run transpile:federation && npm run transpile:credentials && npm run transpile:keys && npm run transpile:passkeys && npm run transpile:otp && npm run transpile:clients && npm run transpile:grants",
     "transpile:bans": "tsc -p ./components/identity.bans",
     "transpile:basic": "tsc -p ./components/identity.basic",
     "transpile:tokens": "tsc -p ./components/identity.tokens",
@@ -46,6 +46,8 @@
     "transpile:keys": "tsc -p ./components/identity.keys",
     "transpile:passkeys": "tsc -p ./components/identity.passkeys",
     "transpile:otp": "tsc -p ./components/identity.otp",
+    "transpile:clients": "tsc -p ./components/identity.clients",
+    "transpile:grants": "tsc -p ./components/identity.grants",
     "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js",
     "features:h2c": "TOA_EXPOSITION_PROTOCOL=h2c TOA_AGENT_PROTOCOL=h2c TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js",
     "features:security": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags @security",
@@ -56,5 +58,5 @@
     "@types/cors": "2.8.19",
     "@types/negotiator": "0.6.5"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
+  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
 }

package/readme.md

@@ -138,6 +138,7 @@ exposition:
 | `debug`       | Output server errors. Default `false`.                                                                            |
 | `ip`          | Header the client address is read from. See [Client address](documentation/ip.md).                              |
 | `bouncer`     | Meter of failed authentications per address. See [Identity authentication](documentation/identity.md#failed-authentications). |
+| `oauth`       | Authorization server exposed to OAuth clients. See [OAuth](documentation/oauth.md).                               |
 
 ### Observability
 
@@ -207,6 +208,8 @@ See also [telemetry ready probe](../telemetry/readme.md#ready-probe) and
 - [Resource Tree Definition](documentation/tree.md)
 - [Identity authentication](documentation/identity.md)
 - [Access authorization](documentation/access.md)
+- [OAuth authorization server](documentation/oauth.md)
+- [Consent](documentation/consent.md)
 - [BLOBs](documentation/octets.md)
 - [Components and resources](documentation/components.md)
 - [Caching](documentation/cache.md)

package/schemas/annotation.cos.yaml

@@ -50,6 +50,36 @@ properties:
   protocol:
     type: string
     enum: [h1, h2c]
+  oauth:
+    type: object
+    properties:
+      authorize:
+        description: The absolute URL of the consent page the application serves
+        type: string
+        pattern: ^https?://
+      resources:
+        description: Paths a token may be restricted to
+        type: array
+        items:
+          type: string
+          pattern: ^/
+      scopes:
+        type: array
+        items:
+          type: string
+      trust:
+        description: Origins whose Client ID Metadata Documents may be read
+        type: array
+        items:
+          type: string
+          pattern: ^https://
+      registration:
+        type: string
+        enum: [open, closed]
+        default: closed
+    required:
+      - authorize
+    additionalProperties: false
   /: {}
   authorities:
     type: object

package/source/Annotation.ts

@@ -23,9 +23,32 @@ export interface Annotation {
 
   /** Failed authentications an address may make; none are metered unless set. See `identity.md`. */
   bouncer?: Bouncer
+
+  /** The authorization server this context exposes; none is exposed without it. */
+  oauth?: OAuth
   '/'?: object // parsed and validated by RTD.syntax.parse
 }
 
+export interface OAuth {
+  /**
+   * Where a client sends the user to consent. The one endpoint of the flow that needs a
+   * person, and so the one this extension does not serve: an application builds it.
+   */
+  authorize: string
+
+  /** Paths a token may be restricted to, each advertised as a protected resource. */
+  resources?: string[]
+
+  /** What a client may ask for. Each is a role, or a scope within one. */
+  scopes?: string[]
+
+  /** Origins whose Client ID Metadata Documents may be read. None are without it. */
+  trust?: string[]
+
+  /** Dynamic Client Registration, off unless opened. */
+  registration?: 'open' | 'closed'
+}
+
 export interface Bouncer {
   /** what an address may fail at once, 20 by default */
   attempts?: number

package/source/Factory.ts

@@ -54,7 +54,7 @@ export class Factory implements extensions.Factory {
     const node = root.resolve()
     const methods = new EndpointsFactory(remotes)
     const directives = new DirectivesFactory(families, remotes, this.host, options)
-    const interception = new Interception(interceptors)
+    const interception = new Interception(interceptors, options)
     const tree = new Tree(node, methods, directives)
 
     const composition = new Composition(this.host)

package/source/HTTP/Server.ts

@@ -12,12 +12,13 @@ import { ClientError, Exception } from './exceptions.js'
 import { Context } from './Context.js'
 import { PROBE, Probe } from './Probe.js'
 import type { IncomingMessage, Protocol, ServerResponse } from './types.js'
-import type { Bouncer } from '../Annotation.js'
+import type { Bouncer, OAuth } from '../Annotation.js'
 
 export class Server extends Connector {
   private readonly server: http.Server | http2.Http2Server
   private readonly properties: Properties
-  private readonly authorities: Record<string, string>
+  /** Host to authority. A map: a `Host` of `constructor` names what a plain object answers. */
+  private readonly authorities: Map<string, string>
 
   /** Tracked for the drain: `Http2Server` has no `closeIdleConnections`. */
   private readonly sessions = new Set<http2.ServerHttp2Session>()
@@ -30,7 +31,7 @@ export class Server extends Connector {
     super()
 
     this.properties = properties
-    this.authorities = Object.fromEntries(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
+    this.authorities = new Map(Object.entries(properties.authorities).map(([key, value]) => [value, key]))
     this.server = instantiate(properties.protocol)
     this.probe = new Probe(properties.probe)
 
@@ -162,7 +163,7 @@ export class Server extends Connector {
 
     assert(this.process !== undefined, 'Request processor is not attached')
 
-    const authority = this.authorities[host] ?? host
+    const authority = this.authorities.get(host) ?? host
 
     // if the request carries no trace context, the trace starts here
     const remote = trace(request.headers)
@@ -239,7 +240,7 @@ export class Server extends Connector {
         if (!response.writableEnded) {
           response.statusCode = status
 
-          const message: OutgoingMessage = { status: response.statusCode }
+          const message: OutgoingMessage = { status: response.statusCode, authentic: true }
 
           // eslint-disable-next-line max-depth
           if (exception instanceof Exception && exception.headers !== undefined)
@@ -385,6 +386,9 @@ interface Properties {
 
   /** Failed authentications an address may make; none are metered unless set. */
   bouncer?: Bouncer
+
+  /** The authorization server this context exposes; none is exposed without it. */
+  oauth?: OAuth
 }
 
 export type Options = { authorities: Properties['authorities'] } & {

package/source/HTTP/formats/form.ts

@@ -0,0 +1,21 @@
+export const type = 'application/x-www-form-urlencoded'
+
+/**
+ * A form is read and never written: it is what an HTML form and a handful of protocols send,
+ * and nothing asks for a reply in it.
+ *
+ * A name repeated in a form is a list, which is how a form says one — `URLSearchParams` keeps
+ * every value, and a name given once stays the string it was written as.
+ */
+export function decode (buffer: Buffer, charset = 'utf-8'): any {
+  const params = new URLSearchParams(buffer.toString(charset as BufferEncoding))
+  const value: Record<string, string | string[]> = {}
+
+  for (const name of new Set(params.keys())) {
+    const values = params.getAll(name)
+
+    value[name] = values.length === 1 ? values[0] : values
+  }
+
+  return value
+}

package/source/HTTP/formats/index.ts

@@ -2,7 +2,9 @@ import * as json from './json.js'
 import * as yaml from './yaml.js'
 import * as msgpack from './msgpack.js'
 import * as text from './text.js'
+import * as form from './form.js'
 
+/** What a reply may be encoded as, and so what `accept` is negotiated against. */
 export const formats: Record<string, Format> = {
   [json.type]: json,
   [yaml.type]: yaml,
@@ -12,10 +14,23 @@ export const formats: Record<string, Format> = {
 
 export const types = Object.keys(formats)
 
-export interface Format {
+/**
+ * What a request body may arrive as. Everything a reply may be, and a form besides — which
+ * is read and never written, so it is not something a reply can be asked for.
+ */
+export const decoders: Record<string, Decoder> = {
+  ...formats,
+  [form.type]: form
+}
+
+export interface Decoder {
   readonly type: string
+
+  decode: (buffer: Buffer, charset?: string) => any
+}
+
+export interface Format extends Decoder {
   readonly multipart: string
 
   encode: (value: any) => Buffer
-  decode: (buffer: Buffer, charset?: string) => any
 }

package/source/HTTP/messages.test.ts

@@ -7,7 +7,7 @@ import { generate } from 'randomstring'
 import * as msgpack from 'msgpackr'
 import { multipart, read, type OutgoingMessage } from './messages.js'
 import { BadRequest, UnsupportedMediaType } from './exceptions.js'
-import { formats } from './formats/index.js'
+import { formats, types } from './formats/index.js'
 import { Timing } from './Timing.js'
 import type * as http from 'node:http'
 import type { Context } from './Context.js'
@@ -87,6 +87,30 @@ describe('read', () => {
     await assert.rejects(read(request), BadRequest)
   })
 
+  it('should parse application/x-www-form-urlencoded', async () => {
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
+    const form = 'grant_type=authorization_code&code=SplxlO&scope=a+b'
+    const request = createContext(generate(), headers, form)
+
+    assert.deepStrictEqual(await read(request), {
+      grant_type: 'authorization_code',
+      code: 'SplxlO',
+      scope: 'a b'
+    })
+  })
+
+  it('should read a repeated form name as the list it is', async () => {
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' }
+    const request = createContext(generate(), headers, 'resource=one&resource=two')
+
+    assert.deepStrictEqual(await read(request), { resource: ['one', 'two'] })
+  })
+
+  it('should not offer a form as a reply encoding', () => {
+    assert.ok(!types.includes('application/x-www-form-urlencoded'),
+      'a form is read and never written')
+  })
+
   it('should output correct mulitpart format', async () => {
     const response = new class extends PassThrough {
       public readonly headers = new Headers()

package/source/HTTP/messages.ts

@@ -4,7 +4,7 @@ import { pipeline } from 'node:stream/promises'
 import { createHash } from 'node:crypto'
 import * as contentType from 'content-type'
 import { console } from 'openspan'
-import { type Format, formats } from './formats/index.js'
+import { type Format, decoders } from './formats/index.js'
 import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js'
 import type { Context } from './Context.js'
 import type { ServerResponse } from './types.js'
@@ -49,10 +49,10 @@ export async function read (context: Context): Promise<any> {
 
   const { type, parameters } = contentType.parse(header)
 
-  if (!(type in formats))
+  if (!(type in decoders))
     throw new UnsupportedMediaType()
 
-  const format = formats[type]
+  const format = decoders[type]
   const buf = await context.buffer()
 
   try {
@@ -201,6 +201,13 @@ export interface OutgoingMessage {
 
   /** tag the response with a hash of the encoded body, see `conditional` */
   etag?: boolean
+
+  /**
+   * Built by the gateway rather than returned by an operation, as a request is `authentic`
+   * when it was made by one: what is in it is the gateway's own, and the checks that answer
+   * for what an operation returns have nothing to say about it.
+   */
+  authentic?: boolean
 }
 
 export interface Query {

package/source/Interception.ts

@@ -1,15 +1,18 @@
+import type * as http from './HTTP/index.js'
 import type { Input, Output } from './io.js'
 
 export class Interception implements Interceptor {
   private readonly interceptors: Interceptor[]
 
-  public constructor (interceptors: Interceptor[]) {
+  public constructor (interceptors: Interceptor[], options: http.Options) {
     this.interceptors = interceptors
 
     // interceptors are module singletons, so a second gateway in one process —
     // which is how the features run — would otherwise inherit the first one's state
-    for (const interceptor of interceptors)
+    for (const interceptor of interceptors) {
       interceptor.reset?.()
+      interceptor.mount?.(options)
+    }
   }
 
   public async intercept (input: Input): Promise<Output> {
@@ -29,4 +32,7 @@ export interface Interceptor {
 
   /** Discards whatever the interceptor accumulated while serving. */
   reset?: () => void
+
+  /** What the annotation says, for an interceptor that answers from it. */
+  mount?: (options: http.Options) => void
 }

package/source/deployment.ts

@@ -67,6 +67,9 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   if (annotation.bouncer !== undefined)
     properties.bouncer = annotation.bouncer
 
+  if (annotation.oauth !== undefined)
+    properties.oauth = annotation.oauth
+
   service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
     value: JSON.stringify(properties)
@@ -83,4 +86,4 @@ 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'>

package/source/directives/auth/Authorization.ts

@@ -16,7 +16,7 @@ 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'
@@ -34,7 +34,7 @@ import type {
   Identity,
   Context,
   Remote,
-  Schemes
+  Components
 } from './types.js'
 
 export class Authorization implements DirectiveFamily<Directive, Extension> {
@@ -42,7 +42,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
@@ -132,7 +132,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     if (identity === null)
       return
 
-    if (identity.scheme === PRIMARY && !identity.refresh)
+    if (identity.provider === PRIMARY && !identity.refresh)
       return
 
     if (await this.banned(identity))
@@ -140,7 +140,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 +170,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
+
+      provider = candidate
+      result = answer
+
+      break
+    }
 
-    if (result instanceof Error) {
-      const code: string | unknown = (result as unknown as { code: string }).code
+    if (result === null || result instanceof Error) {
+      const code = result === null ? UNRECOGNIZED : codeOf(result)
 
-      if (typeof code === 'string') {
+      if (code !== undefined) {
         console.info('Authentication failed', { code })
 
         context.rejection = code
@@ -201,9 +216,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 +244,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/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,

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

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.