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

package/source/Factory.ts

@@ -10,6 +10,7 @@ import { families, interceptors } from './directives/index.js'
 import { DirectivesFactory } from './Directive.js'
 import { Composition } from './Composition.js'
 import * as root from './root.js'
+import { ATOM_GROUP } from './const.js'
 import { Interception } from './Interception.js'
 import * as http from './HTTP/index.js'
 import type { Branch } from './Branch.js'
@@ -18,14 +19,14 @@ import type { Broadcast } from './Gateway.js'
 import type { Connector, Locator, extensions } from '@toa.io/core'
 
 export class Factory implements extensions.Factory {
-  private readonly boot: Bootloader
+  private readonly host: Host
 
-  public constructor (boot: Bootloader) {
-    this.boot = boot
+  public constructor (host: Host) {
+    this.host = host
   }
 
   public async tenant (locator: Locator, node: syntax.Node): Promise<Connector> {
-    const broadcast: Broadcast = await this.boot.bindings.broadcast(CHANNEL, locator.id)
+    const broadcast: Broadcast = await this.host.broadcast(CHANNEL, locator.id)
     const hash = createHash('sha256').update(JSON.stringify(node)).digest('hex')
 
     // no timestamp: the tenant stamps each announcement with its own start time
@@ -47,20 +48,22 @@ export class Factory implements extensions.Factory {
     configureLogs()
 
     const options = JSON.parse(process.env.TOA_EXPOSITION_PROPERTIES) as http.Options
-    const broadcast: Broadcast = await this.boot.bindings.broadcast(CHANNEL)
+    const broadcast: Broadcast = await this.host.broadcast(CHANNEL)
     const server = http.Server.create({ ...options })
-    const remotes = new Remotes(this.boot)
+    const remotes = new Remotes(this.host)
     const node = root.resolve()
     const methods = new EndpointsFactory(remotes)
-    const directives = new DirectivesFactory(families, remotes)
+    const directives = new DirectivesFactory(families, remotes, this.host, options)
     const interception = new Interception(interceptors)
     const tree = new Tree(node, methods, directives)
 
-    const composition = new Composition(this.boot)
+    const composition = new Composition(this.host)
     const gateway = new Gateway(broadcast, tree, interception)
 
     gateway.depends(remotes)
     gateway.depends(composition)
+    // what the directives meter through; one atom per process, connected once
+    gateway.depends(this.host.atom(ATOM_GROUP))
 
     server.attach(gateway.process.bind(gateway))
     server.depends(gateway)
@@ -101,4 +104,4 @@ function development (): TracesOptions {
 }
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-export type Bootloader = typeof import('@toa.io/boot')
+export type Host = extensions.Host

package/source/HTTP/Context.ts

@@ -5,6 +5,7 @@ import { console } from 'openspan'
 import { Timing } from './Timing.js'
 import { type Format, formats, types } from './formats/index.js'
 import { read } from './messages.js'
+import { address } from './address.js'
 import type { OutgoingMessage } from './messages.js'
 import type { IncomingMessage } from './types.js'
 
@@ -12,6 +13,9 @@ export class Context {
   public readonly id: string
   public readonly authority: string
   public readonly request: IncomingMessage
+
+  /** the client address, read as the deployment says; none otherwise, see `documentation/ip.md` */
+  public readonly ip: string | undefined
   public readonly url: URL
   public readonly subtype: string | null = null
   public readonly encoder: Format | null = null
@@ -30,6 +34,7 @@ export class Context {
     url: URL) {
     this.authority = authority
     this.request = request
+    this.ip = address(request, properties.ip)
 
     this.id = crypto.randomUUID()
     // parsed by the server, which had to parse it anyway to know the request is valid
@@ -80,13 +85,15 @@ export class Context {
     const headers = { ...request.headers }
 
     if (headers.authorization !== undefined)
-      // only scheme
-      headers.authorization = headers.authorization.slice(0, headers.authorization.indexOf(' '))
+      headers.authorization = SCHEME.exec(headers.authorization)?.[1] ?? '[malformed]'
 
     console.debug('Received request', { method: request.method, url: request.url, headers })
   }
 }
 
+/** The scheme of an `authorization` header; the value after it is a credential. */
+const SCHEME = /^(\w{1,32})(?: |$)/
+
 interface Pipelines {
   body: Array<(input: unknown) => unknown>
   response: Array<(output: OutgoingMessage) => void | Promise<void>>
@@ -94,6 +101,9 @@ interface Pipelines {
 
 interface Properties {
   debug: boolean
+
+  /** the header the client address is read from; the connection's without one */
+  ip?: string
 }
 
 /**

package/source/HTTP/Server.ts

@@ -12,6 +12,7 @@ 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'
 
 export class Server extends Connector {
   private readonly server: http.Server | http2.Http2Server
@@ -129,10 +130,10 @@ export class Server extends Connector {
     // no listener on `request.socket`: under HTTP/2 it is the session's socket, shared by
     // every concurrent stream, and removing listeners on it would strip the siblings'
 
-    const host = authorityOf(request)
+    const host = authorityOf(request)?.toLowerCase()
 
-    if (host === undefined) {
-      console.warn('Request without an authority', errorAttributes(request, new Error('No authority')))
+    if (host === undefined || !HOST.test(host)) {
+      console.warn('Request without a valid authority', errorAttributes(request, new Error('Invalid authority')))
 
       response.writeHead(400).end()
 
@@ -350,6 +351,12 @@ function trace (headers: IncomingMessage['headers']): SpanContext | null {
   return null
 }
 
+/**
+ * A host name with an optional port, or a bracketed IPv6 literal. The URL parser admits
+ * `,` `;` `=` `(` `)` and quotes in a host, and the authority is written into criteria.
+ */
+const HOST = /^(?:[a-z0-9.-]{1,253}|\[[0-9a-f:.]{2,45}\])(?::\d{1,5})?$/
+
 const RAY = /^[\da-f]{32}$/i
 const ZERO_RAY = '0'.repeat(32)
 
@@ -372,6 +379,12 @@ interface Properties {
 
   /** Port of the readiness probe, which is HTTP/1.1 whatever the gateway serves. */
   probe: number
+
+  /** The header the client address is read from; the connection's address without one. */
+  ip?: string
+
+  /** Failed authentications an address may make; none are metered unless set. */
+  bouncer?: Bouncer
 }
 
 export type Options = { authorities: Properties['authorities'] } & {

package/source/HTTP/address.test.ts

@@ -0,0 +1,22 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { address } from './address.js'
+import type { IncomingMessage } from './types.js'
+
+const request = (headers: Record<string, string>): IncomingMessage =>
+  ({ headers, socket: { remoteAddress: '9.9.9.9' } }) as unknown as IncomingMessage
+
+it('should be nothing without a header named', () => {
+  assert.equal(address(request({ 'x-forwarded-for': '1.1.1.1' })), undefined)
+})
+
+it('should be the last value of the named header', () => {
+  assert.equal(address(request({ 'x-forwarded-for': '1.1.1.1, 2.2.2.2' }), 'x-forwarded-for'), '2.2.2.2')
+  assert.equal(address(request({ 'cf-connecting-ip': '3.3.3.3' }), 'cf-connecting-ip'), '3.3.3.3')
+})
+
+it('should be nothing when the named header is absent or empty', () => {
+  assert.equal(address(request({}), 'x-real-ip'), undefined)
+  assert.equal(address(request({ 'x-real-ip': ' ' }), 'x-real-ip'), undefined)
+})

package/source/HTTP/address.ts

@@ -0,0 +1,17 @@
+import type { IncomingMessage } from './types.js'
+
+/**
+ * The client address: the value of the header the deployment names, and nothing otherwise.
+ * Of a header holding a list, the last value is the one the edge in front appended. The
+ * connection's address is never it: behind an edge it is the edge's.
+ */
+export function address (request: IncomingMessage, header?: string): string | undefined {
+  if (header === undefined)
+    return
+
+  const value = request.headers[header]
+  const raw = Array.isArray(value) ? value[value.length - 1] : value
+  const last = raw?.slice(raw.lastIndexOf(',') + 1).trim()
+
+  return last === '' ? undefined : last
+}

package/source/Query.test.ts

@@ -19,7 +19,21 @@ it('should combine request criteria', async () => {
   const instance = new Query(query)
   const result = instance.fit({ criteria: 'qux==4' }, parameters)
 
-  assert.deepStrictEqual(result.query!.criteria, '(bar==2;baz==3);(foo==1);(qux==4)')
+  assert.deepStrictEqual(result.query!.criteria, '(bar=="2";baz=="3");(foo==1);(qux==4)')
+})
+
+it('should quote parameter values', async () => {
+  const query: syntax.Query = {
+    omit: { range: [0, 1] },
+    limit: { range: [0, 1] }
+  }
+
+  const parameters: Parameter[] = [{ name: 'user', value: 'me"),(user=="victim' }]
+
+  const instance = new Query(query)
+  const result = instance.fit({}, parameters)
+
+  assert.deepStrictEqual(result.query!.criteria, '(user=="me\\"),(user==\\"victim")')
 })
 
 it('should set id parameter as query.id', async () => {

package/source/Query.ts

@@ -1,4 +1,5 @@
 import assert from 'node:assert'
+import { quote } from '@toa.io/generic'
 import * as http from './HTTP/index.js'
 import { type Parameter } from './RTD/index.js'
 import * as schemas from './schemas.js'
@@ -132,8 +133,9 @@ export class Query {
     }
 
     if (parameters.length > 0) {
+      // a segment may carry `,` `;` `(` `)` `=`, which is criteria grammar when unquoted
       const criteria = parameters
-        .map(({ name, value }) => `${name}==${value}`)
+        .map(({ name, value }) => `${name}==${quote(value)}`)
         .join(';')
 
       groups.push({ criteria, operator: this.prepend })

package/source/RTD/Directives.ts

@@ -1,7 +1,10 @@
 import type { Parameter } from './Match.js'
 import type * as syntax from './syntax/index.js'
-import type { Context, OutgoingMessage } from '../HTTP/index.js'
+import type { Context, OutgoingMessage, Options } from '../HTTP/index.js'
 import type { Output } from '../io.js'
+import type { extensions } from '@toa.io/core'
+
+type Host = extensions.Host
 
 export interface Directives {
   preflight: (context: Context, parameters: Parameter[]) => Promise<Output>
@@ -28,6 +31,12 @@ export interface DirectiveFamily<TDirective = any, TExtension = any> {
 
   create: (name: string, ...rest: any[]) => TDirective
 
+  /**
+   * Called once per gateway with what the host provides and how the gateway is configured,
+   * before any directive is created.
+   */
+  mount?: (host: Host, options: Options) => void
+
   /**
    * Puts the directives of one route in the order they must run in. Called once, when
    * the set is built — the order cannot depend on the request.

package/source/Remotes.test.ts

@@ -5,19 +5,14 @@ import { isDeepStrictEqual } from 'node:util'
 import { generate } from 'randomstring'
 import { Connector } from '@toa.io/core'
 import { Remotes } from './Remotes.js'
-import type { Bootloader } from './Factory.js'
-import type { Locator, Source } from '@toa.io/core'
+import type { Host } from './Factory.js'
 
-mock.module('@toa.io/boot', { namedExports: ({
-  remote: async (locator: Locator, source?: Source) => await boot.remote(locator, source)
-}) })
-
-const boot = {
+const host = {
   remote: mock.fn(async () => ({
     connect: mock.fn(() => undefined),
     link: mock.fn(() => undefined)
   }))
-} as unknown as Bootloader
+} as unknown as Host
 
 const namespace = generate()
 const name = generate()
@@ -25,15 +20,15 @@ const name = generate()
 let remotes: Remotes
 
 beforeEach(() => {
-  remotes = new Remotes(boot)
+  remotes = new Remotes(host)
 })
 
 it('should create remote', async () => {
   const remote = await remotes.discover(namespace, name)
 
-  assert.ok(boot.remote.mock.calls.some((call: any) => call.arguments.length === 2 && isPartial(call.arguments[0], { namespace, name }) && call.arguments[1] !== null && call.arguments[1] !== undefined))
+  assert.ok(host.remote.mock.calls.some((call: any) => call.arguments.length === 2 && isPartial(call.arguments[0], { namespace, name }) && call.arguments[1] !== null && call.arguments[1] !== undefined))
 
-  assert.deepStrictEqual(remote, await boot.remote.mock.calls[0].result)
+  assert.deepStrictEqual(remote, await host.remote.mock.calls[0].result)
 })
 
 it('should be instance of Connector', async () => {
@@ -49,7 +44,7 @@ it('should depend on created remotes', async () => {
 it('should attribute calls to the gateway', async () => {
   await remotes.discover(namespace, name)
 
-  assert.ok(boot.remote.mock.calls.some((call: any) => call.arguments.length === 2 && call.arguments[0] !== null && call.arguments[0] !== undefined && isDeepStrictEqual(call.arguments[1], { service: 'exposition' })))
+  assert.ok(host.remote.mock.calls.some((call: any) => call.arguments.length === 2 && call.arguments[0] !== null && call.arguments[0] !== undefined && isDeepStrictEqual(call.arguments[1], { service: 'exposition' })))
 })
 
 function isPartial (actual, expected) {

package/source/Remotes.ts

@@ -1,13 +1,13 @@
 import { Locator, Connector, type Remote, type Source } from '@toa.io/core'
-import { type Bootloader } from './Factory.js'
+import { type Host } from './Factory.js'
 
 export class Remotes extends Connector {
-  private readonly boot: Bootloader
+  private readonly host: Host
   private readonly cache: Record<string, Promise<Remote>> = {}
 
-  public constructor (boot: Bootloader) {
+  public constructor (host: Host) {
     super()
-    this.boot = boot
+    this.host = host
   }
 
   public async discover (namespace: string, name: string, version: string = 'local'): Promise<Remote> {
@@ -21,7 +21,7 @@ export class Remotes extends Connector {
 
   private async locate (locator: Locator): Promise<Remote> {
     // the gateway is the origin of every call it forwards
-    const remote = await this.boot.remote(locator, SOURCE)
+    const remote = await this.host.remote(locator, SOURCE)
 
     this.depends(remote)
 

package/source/const.ts

@@ -1 +1,4 @@
 export const BRANCH_TTL = 1_800_000
+
+/** The replicas of the gateway decide together, whatever context they serve. */
+export const ATOM_GROUP = 'exposition'

package/source/deployment.ts

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

package/source/directives/auth/Assert.ts

@@ -25,6 +25,9 @@ export class Assert implements Directive {
       throw new http.Unauthorized()
 
     if (identity === null) {
+      if (!Incept.acceptable(context))
+        throw new http.Unauthorized()
+
       context.identity = await Incept.incept(context, newid())
 
       context.pipelines.response.push((response) => {

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

@@ -0,0 +1,24 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { permits } from './Authorization.js'
+
+const permissions = { '/users/me/**': ['GET'], '/notes/': ['*'] }
+
+it('should permit a matching method and path', () => {
+  assert.equal(permits(permissions, 'GET', '/users/me/posts/'), true)
+  assert.equal(permits(permissions, 'DELETE', '/notes/'), true)
+})
+
+it('should refuse another method or path', () => {
+  assert.equal(permits(permissions, 'POST', '/users/me/posts/'), false)
+  assert.equal(permits(permissions, 'GET', '/admin/'), false)
+})
+
+it('should be matched on the routed path, not on the request URL', () => {
+  const raw = '/users/me/%2e%2e/admin/'
+  const routed = new URL(raw, 'https://example.com').pathname
+
+  assert.equal(routed, '/users/admin/')
+  assert.equal(permits(permissions, 'GET', routed), false)
+})

package/source/directives/auth/Authorization.ts

@@ -16,11 +16,15 @@ import { Federation } from './Federation.js'
 import { Anyone } from './Anyone.js'
 import { Input, type Declaration } from './Input.js'
 import { split } from './split.js'
-import { PRIMARY, PROVIDERS } from './schemes.js'
+import { PRIMARY, provider as providerOf } 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 { Component } from '@toa.io/core'
 import type { Remotes } from '../../Remotes.js'
 import type { Parameter, DirectiveFamily } from '../../RTD/index.js'
+import type { Host } from '../../Factory.js'
 import type {
   AuthenticationResult,
   Ban,
@@ -43,6 +47,37 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   private tokens: Component | null = null
   private bans: Component | null = null
 
+  /** Failed authentications per address, reconciled with the other gateways. */
+  private meter: Quotas | null = null
+  private sync: Sync | null = null
+
+  public mount (host: Host, options: http.Options): void {
+    this.sync?.dispose()
+    this.sync = null
+    this.meter = null
+
+    const bouncer = options.bouncer
+
+    // keyed by address, which is the deployment's to name, so off until it is set
+    if (bouncer === undefined)
+      return
+
+    this.meter = new Quotas({
+      keys: Keys.create([{ method: 'ip', options: BOUNCER }]),
+      requests: bouncer.attempts ?? ATTEMPTS,
+      interval: (bouncer.interval ?? INTERVAL) * 1000,
+      conditional: true, // charged on a rejection, not on a check
+      name: METER
+    })
+
+    this.sync = new Sync(host.atom(ATOM_GROUP))
+    this.sync.register(this.meter)
+  }
+
+  public dispose (): void {
+    this.sync?.dispose()
+  }
+
   public create (name: string, value: any, remotes: Remotes): Directive {
     assert.ok(name in constructors,
       `Directive 'auth:${name}' is not implemented`)
@@ -68,7 +103,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   public async preflight (directives: Directive[],
     context: Context,
     parameters: Parameter[]): Promise<Output> {
-    context.identity = await this.resolve(context.authority, context.request.headers.authorization)
+    context.identity = await this.resolve(context)
 
     for (const directive of directives) {
       const allow = await directive.authorize(context.identity, context, parameters)
@@ -103,8 +138,12 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     if (await this.banned(identity))
       throw new http.Unauthorized()
 
-    // Role directive may have already set the value
-    identity.roles ??= await Role.get(identity, this.discovery.roles)
+    // 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)
+      identity.roles = await Role.get(identity, this.discovery.roles)
+    else
+      identity.roles ??= await Role.get(identity, this.discovery.roles)
     this.tokens ??= await this.discovery.tokens
 
     const token = await this.tokens.invoke<string>('encrypt', {
@@ -118,12 +157,20 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     response.headers.set('cache-control', 'no-store')
   }
 
-  private async resolve (authority: string, authorization: string | undefined): Promise<Identity | null> {
+  private async resolve (context: Context): Promise<Identity | null> {
+    const { authority } = context
+    const { authorization } = context.request.headers
+
     if (authorization === undefined)
       return null
 
+    const retry = this.meter?.check(context, NONE) ?? 0
+
+    if (retry > 0)
+      throw new http.TooManyRequests(retry)
+
     const [scheme, credentials] = split(authorization)
-    const provider = PROVIDERS[scheme]
+    const provider = providerOf(scheme)
 
     if (provider === undefined)
       throw new http.Unauthorized(`Unknown authentication scheme '${scheme}'`)
@@ -141,9 +188,14 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     if (result instanceof Error) {
       const code: string | unknown = (result as unknown as { code: string }).code
 
-      if (typeof code === 'string')
+      if (typeof code === 'string') {
         console.info('Authentication failed', { code })
 
+        context.rejection = code
+      }
+
+      this.meter?.use(context, null)
+
       return null
     }
 
@@ -163,10 +215,8 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     if (permissions === undefined)
       return true
 
-    return Object.entries(permissions).some(([pattern, methods]) => {
-      return methods.some((method) => method === '*' || method === context.request.method) &&
-        glob(pattern).match(context.request.url)
-    })
+    // the route is matched on the normalized path, so the permission is too
+    return permits(permissions, context.request.method, context.url.pathname)
   }
 
   private async banned (identity: Identity): Promise<boolean> {
@@ -178,6 +228,13 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   }
 }
 
+/** Whether the permissions admit the method on the path the request is routed by. */
+export function permits (permissions: Record<string, string[]>, method: string, pathname: string): boolean {
+  return Object.entries(permissions).some(([pattern, methods]) =>
+    methods.some((allowed) => allowed === '*' || allowed === method) &&
+    glob(pattern).match(pathname))
+}
+
 /**
  * `minimatch(str, pattern)` compiles the pattern on every call, and a permission is
  * matched on every request the identity makes. Patterns arrive with an identity, hence
@@ -198,6 +255,18 @@ function glob (pattern: string): Minimatch {
   return compiled
 }
 
+/** What an address may fail at once, and the seconds it takes to earn them back. */
+const ATTEMPTS = 20
+const INTERVAL = 60
+
+/** Who is speaking when a request cannot be keyed. */
+const BOUNCER = 'Authentication bouncer'
+
+/** The meter's name in the atom: `atom:exposition:meter:credentials:<address>`. */
+const METER = 'credentials'
+
+const NONE: Parameter[] = []
+
 const GLOBS = new Map<string, Minimatch>()
 const GLOBS_LIMIT = 1024
 

package/source/directives/auth/Incept.ts

@@ -3,7 +3,7 @@ import { console } from 'openspan'
 import * as http from '../../HTTP/index.js'
 import { split } from './split.js'
 import { create } from './create.js'
-import { PROVIDERS, INCEPTION } from './schemes.js'
+import { INCEPTION, UNKNOWN, provider as providerOf } from './schemes.js'
 import { Role } from './Role.js'
 import type { Component } from '@toa.io/core'
 import type { Maybe } from '@toa.io/types'
@@ -26,7 +26,7 @@ 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 = PROVIDERS[scheme]
+    const provider = providerOf(scheme)
 
     if (provider === undefined)
       throw new http.BadRequest('Authentication scheme is not supported')
@@ -61,8 +61,13 @@ export class Incept implements Directive {
     return identity
   }
 
-  public authorize (identity: Identity | null): boolean {
-    return identity === null
+  /** Credentials that were rejected for any reason but being unknown are not incepted. */
+  public static acceptable (context: Context): boolean {
+    return context.request.headers.authorization === undefined || context.rejection === UNKNOWN
+  }
+
+  public authorize (identity: Identity | null, context: Context): boolean {
+    return identity === null && Incept.acceptable(context)
   }
 
   public reply (context: Context): http.OutgoingMessage | null {

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

@@ -36,7 +36,7 @@ it('should return false if not matched', async () => {
 
   assert.ok(remote.invoke.mock.calls.some((call: any) => call.arguments.length === 2 && isDeepStrictEqual(call.arguments[0], 'list') && isDeepStrictEqual(call.arguments[1], {
       query: {
-        criteria: `identity==${identity.id}`,
+        criteria: `identity=="${identity.id}"`,
         limit: 1024
       }
     })))

package/source/directives/auth/Role.ts

@@ -1,4 +1,5 @@
 import assert from 'node:assert'
+import { quote } from '@toa.io/generic'
 import { type Component, type Query } from '@toa.io/core'
 import { type Directive, type Identity } from './types.js'
 import type { Parameter } from '../../RTD/index.js'
@@ -19,7 +20,7 @@ export class Role implements Directive {
     this.remote ??= await discovery
 
     const query: Query = {
-      criteria: `identity==${identity.id}`,
+      criteria: `identity==${quote(identity.id)}`,
       limit: 1024
     }
 

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

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