@toa.io/extensions.exposition 1.0.0-alpha.285 → 1.0.0-alpha.286

package/source/directives/auth/Delegate.ts

@@ -9,14 +9,13 @@ export class Delegate implements Directive {
   private readonly property: string
   private readonly discovery: Promise<Component>
 
-  public constructor (property: string, discovery: Promise<Component>) {
+  public constructor(property: string, discovery: Promise<Component>) {
     this.property = property
     this.discovery = discovery
   }
 
-  public async authorize (identity: Identity | null, context: Context): Promise<boolean> {
-    if (identity === null)
-      return false
+  public async authorize(identity: Identity | null, context: Context): Promise<boolean> {
+    if (identity === null) return false
 
     identity.roles ??= await Role.get(identity, this.discovery)
     context.pipelines.body.push((body) => this.embed(body, identity))
@@ -25,20 +24,19 @@ export class Delegate implements Directive {
   }
 
   /** It admits whoever there is, and embedding the identity is the request's business. */
-  public admits (identity: Identity | null): boolean {
+  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 {
+  public describe(introspection: Introspection): Introspection {
     take(introspection, this.property)
 
     return introspection
   }
 
-  private embed (body: unknown, identity: Identity): Record<string, unknown> {
-    if (body === undefined)
-      body = {}
+  private embed(body: unknown, identity: Identity): Record<string, unknown> {
+    if (body === undefined) body = {}
 
     check(body)
     body[this.property] = structuredClone(identity)
@@ -47,7 +45,7 @@ export class Delegate implements Directive {
   }
 }
 
-function check (body: unknown): asserts body is Record<string, unknown> {
+function check(body: unknown): asserts body is Record<string, unknown> {
   if (typeof body !== 'object' || body === null)
     throw new BadRequest('Invalid request body')
 }

package/source/directives/auth/Echo.ts

@@ -3,9 +3,8 @@ import type { OutgoingMessage } from '../../HTTP/index.js'
 import type { Directive, Identity, Context } from './types.js'
 
 export class Echo implements Directive {
-  public authorize (identity: Identity | null, context: Context): boolean {
-    if (identity === null && 'authorization' in context.request.headers)
-      return false
+  public authorize(identity: Identity | null, context: Context): boolean {
+    if (identity === null && 'authorization' in context.request.headers) return false
 
     context.identity ??= create()
 
@@ -13,15 +12,13 @@ export class Echo implements Directive {
   }
 
   /** What `authorize` answers, without inventing the identity it would go on to invent. */
-  public admits (identity: Identity | null, context: Context): boolean {
+  public admits(identity: Identity | null, context: Context): boolean {
     return !(identity === null && 'authorization' in context.request.headers)
   }
 
-  public reply (context: Context): OutgoingMessage {
+  public reply(context: Context): OutgoingMessage {
     const body = context.identity!
 
-    return body.scheme === null
-      ? { status: 201, body }
-      : { body }
+    return body.scheme === null ? { status: 201, body } : { body }
   }
 }

package/source/directives/auth/Federation.ts

@@ -5,33 +5,38 @@ import type { Parameter } from '../../RTD/index.js'
 export class Federation implements Directive {
   private readonly matchers: Array<[keyof Claims, Matcher]>
 
-  public constructor (options: Options) {
-    this.matchers = (Object.entries(options) as Array<[keyof Claims, string]>)
-      .map(([key, value]) => [key, toMatcher(value)])
-
-    assert.ok(this.matchers.length > 0, '`auth:claims` requires at least one property defined')
+  public constructor(options: Options) {
+    this.matchers = (Object.entries(options) as Array<[keyof Claims, string]>).map(
+      ([key, value]) => [key, toMatcher(value)]
+    )
+
+    assert.ok(
+      this.matchers.length > 0,
+      '`auth:claims` requires at least one property defined'
+    )
   }
 
-  public authorize (identity: Identity | null, context: Context, parameters: Parameter[]): boolean {
-    if (identity === null || !('claims' in identity))
-      return false
+  public authorize(
+    identity: Identity | null,
+    context: Context,
+    parameters: Parameter[]
+  ): boolean {
+    if (identity === null || !('claims' in identity)) return false
 
     const claims = (identity as FederatedIdentity).claims
 
     for (const [key, match] of this.matchers)
-      if (!match(claims[key], context, parameters))
-        return false
+      if (!match(claims[key], context, parameters)) return false
 
     return true
   }
 }
 
-function toMatcher (expression: string): Matcher {
+function toMatcher(expression: string): Matcher {
   if (expression.startsWith(':')) {
     const key = expression.slice(1) as 'authority'
 
-    if (key === 'authority')
-      return (value, context) => matches(value, context[key])
+    if (key === 'authority') return (value, context) => matches(value, context[key])
 
     if (key === 'domain')
       return (value, context) => {
@@ -46,20 +51,20 @@ function toMatcher (expression: string): Matcher {
   if (expression.startsWith('/:')) {
     const name = expression.slice(2)
 
-    return (value, _, parameters) => parameters
-      .some((parameter) => parameter.name === name && matches(value, parameter.value))
+    return (value, _, parameters) =>
+      parameters.some(
+        (parameter) => parameter.name === name && matches(value, parameter.value)
+      )
   }
 
   return (value) => matches(value, expression)
 }
 
-function matches (value: string | string[], reference: string): boolean {
-  return Array.isArray(value)
-    ? value.includes(reference)
-    : value === reference
+function matches(value: string | string[], reference: string): boolean {
+  return Array.isArray(value) ? value.includes(reference) : value === reference
 }
 
-function codomain (iss: string, context: Context): boolean {
+function codomain(iss: string, context: Context): boolean {
   const hostname = new URL(iss).hostname
   const dot = hostname.indexOf('.')
   const basename = dot === -1 ? hostname : hostname.slice(dot)
@@ -67,7 +72,11 @@ function codomain (iss: string, context: Context): boolean {
   return context.authority.slice(-basename.length) === basename
 }
 
-type Matcher = (value: string | string[], context: Context, parameters: Parameter[]) => boolean
+type Matcher = (
+  value: string | string[],
+  context: Context,
+  parameters: Parameter[]
+) => boolean
 
 interface Claims {
   iss: string

package/source/directives/auth/Id.ts

@@ -4,13 +4,16 @@ import { type Directive, type Identity } from './types.js'
 export class Id implements Directive {
   private readonly parameter: string
 
-  public constructor (parameter: string) {
+  public constructor(parameter: string) {
     this.parameter = parameter
   }
 
-  public authorize (identity: Identity | null, _: unknown, parameters: Parameter[]): boolean {
-    if (identity === null)
-      return false
+  public authorize(
+    identity: Identity | null,
+    _: unknown,
+    parameters: Parameter[]
+  ): boolean {
+    if (identity === null) return false
 
     const parameter = parameters.find((parameter) => parameter.name === this.parameter)
 

package/source/directives/auth/Incept.ts

@@ -6,7 +6,7 @@ import { create } from './create.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/core'
+import type { Maybe } from '@toa.io/core/types'
 import type { Directive, Discovery, Identity, Context, Components, Ban } from './types.js'
 
 export class Incept implements Directive {
@@ -16,15 +16,17 @@ export class Incept implements Directive {
 
   private readonly property: string | null
 
-  public constructor (property: string, discovery: Discovery) {
-    assert.ok(property === null || typeof property === 'string',
-      '`auth:incept` value must be a string or null')
+  public constructor(property: string, discovery: Discovery) {
+    assert.ok(
+      property === null || typeof property === 'string',
+      '`auth:incept` value must be a string or null'
+    )
 
     this.property = property
     Incept.discovery ??= discovery
   }
 
-  public static async incept (context: Context, id: string): Promise<Identity> {
+  public static async incept(context: Context, id: string): Promise<Identity> {
     const [scheme, credentials] = split(context.request.headers.authorization!)
     const candidates = providersOf(scheme)
 
@@ -36,29 +38,29 @@ export class Incept implements Directive {
     // 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()
+    if (provider === undefined) throw new http.Unauthorized()
 
     Incept.bans ??= await Incept.discovery.bans
 
     const ban = await Incept.bans.invoke<Ban>('observe', { query: { id } })
 
-    if (ban.banned)
-      throw new http.Unauthorized()
+    if (ban.banned) throw new http.Unauthorized()
 
     Incept.components[provider] ??= await Incept.discovery[provider]
 
-    const identity = await Incept.components[provider]!.invoke<Maybe<Identity>>('incept', {
-      input: {
-        scheme,
-        authority: context.authority,
-        id,
-        credentials
+    const identity = await Incept.components[provider]!.invoke<Maybe<Identity>>(
+      'incept',
+      {
+        input: {
+          scheme,
+          authority: context.authority,
+          id,
+          credentials
+        }
       }
-    })
+    )
 
-    if (identity instanceof Error)
-      throw new http.UnprocessableEntity(identity)
+    if (identity instanceof Error) throw new http.UnprocessableEntity(identity)
 
     identity.scheme = scheme
 
@@ -68,24 +70,25 @@ export class Incept implements Directive {
   }
 
   /** 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 static acceptable(context: Context): boolean {
+    return (
+      context.request.headers.authorization === undefined || context.rejection === UNKNOWN
+    )
   }
 
-  public authorize (identity: Identity | null, context: Context): boolean {
+  public authorize(identity: Identity | null, context: Context): boolean {
     return identity === null && Incept.acceptable(context)
   }
 
-  public reply (context: Context): http.OutgoingMessage | null {
-    if (this.property !== null)
-      return null
+  public reply(context: Context): http.OutgoingMessage | null {
+    if (this.property !== null) return null
 
     const body = create(context.request.headers.authorization)
 
     return { body }
   }
 
-  public async settle (context: Context, response: http.OutgoingMessage): Promise<void> {
+  public async settle(context: Context, response: http.OutgoingMessage): Promise<void> {
     const id = response.body?.[this.property ?? 'id']
 
     if (id === undefined) {
@@ -97,7 +100,10 @@ export class Incept implements Directive {
       return
     }
 
-    assert(typeof id === 'string', `Response body property "${this.property}" expected to be a string`)
+    assert(
+      typeof id === 'string',
+      `Response body property "${this.property}" expected to be a string`
+    )
 
     if (context.request.headers.authorization !== undefined)
       context.identity = await Incept.incept(context, id)

package/source/directives/auth/Input.ts

@@ -6,27 +6,40 @@ export class Input implements Directive {
   public priority = 0
   private readonly statements: Statement[] = []
 
-  public constructor (declarations: Declaration[], create: Create) {
-    this.statements = declarations.map((declaration) => new Statement(declaration, create))
+  public constructor(declarations: Declaration[], create: Create) {
+    this.statements = declarations.map(
+      (declaration) => new Statement(declaration, create)
+    )
   }
 
-  public async authorize (identity: Identity | null, context: Context, parameters: Parameter[]): Promise<boolean> {
-    context.pipelines.body.push(async (body) => this.check(identity, context, parameters, body))
+  public async authorize(
+    identity: Identity | null,
+    context: Context,
+    parameters: Parameter[]
+  ): Promise<boolean> {
+    context.pipelines.body.push(async (body) =>
+      this.check(identity, context, parameters, body)
+    )
 
     return false
   }
 
   // eslint-disable-next-line max-params
-  private async check (identity: Identity | null, context: Context, parameters: Parameter[], body: unknown): Promise<unknown> {
-    if (body === undefined || body === null || body.constructor !== Object)
-      return body
-
-    const settled = await Promise.allSettled(this.statements.map(async (statement) =>
-      statement.check(identity, context, parameters, body as Body)))
-
-    for (const result of settled)
-      if (result.status === 'rejected')
-        throw result.reason
+  private async check(
+    identity: Identity | null,
+    context: Context,
+    parameters: Parameter[],
+    body: unknown
+  ): Promise<unknown> {
+    if (body === undefined || body === null || body.constructor !== Object) return body
+
+    const settled = await Promise.allSettled(
+      this.statements.map(async (statement) =>
+        statement.check(identity, context, parameters, body as Body)
+      )
+    )
+
+    for (const result of settled) if (result.status === 'rejected') throw result.reason
 
     return body
   }
@@ -36,7 +49,7 @@ class Statement {
   private readonly properties: string[]
   private readonly directives: Directive[] = []
 
-  public constructor ({ prop, ...directives }: Declaration, create: Create) {
+  public constructor({ prop, ...directives }: Declaration, create: Create) {
     this.properties = typeof prop === 'string' ? [prop] : prop
 
     for (const [name, value] of Object.entries(directives)) {
@@ -47,17 +60,20 @@ class Statement {
   }
 
   // eslint-disable-next-line max-params
-  public async check (identity: Identity | null, context: Context, parameters: Parameter[], body: Body): Promise<void> {
+  public async check(
+    identity: Identity | null,
+    context: Context,
+    parameters: Parameter[],
+    body: Body
+  ): Promise<void> {
     const match = this.properties.some((property) => property in body)
 
-    if (!match)
-      return
+    if (!match) return
 
     for (const directive of this.directives) {
       const authorized = await directive.authorize(identity, context, parameters)
 
-      if (!authorized)
-        throw new Forbidden('Input property is not authorized')
+      if (!authorized) throw new Forbidden('Input property is not authorized')
     }
   }
 }

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

@@ -34,12 +34,19 @@ it('should return false if not matched', async () => {
 
   assert.strictEqual(result, false)
 
-  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}"`,
-        limit: 1024
-      }
-    })))
+  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}"`,
+            limit: 1024
+          }
+        })
+    )
+  )
 })
 
 it('should return true on exact match', async () => {
@@ -67,36 +74,55 @@ it('should return false on non-scope substring match', async () => {
 })
 
 it('should return true on match with parameters', async () => {
-  const result = await match(['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'], [{
-      name: 'org',
-      value: '29e54ae1'
-    }])
+  const result = await match(
+    ['app:{org}:reviews'],
+    ['app:29e54ae1:reviews'],
+    [
+      {
+        name: 'org',
+        value: '29e54ae1'
+      }
+    ]
+  )
 
   assert.strictEqual(result, true)
 })
 
 it('should return true on match with parameters', async () => {
-  const result = await match(['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'], [{
-      name: 'org',
-      value: '29e54ae1'
-    }])
+  const result = await match(
+    ['app:{org}:reviews'],
+    ['app:29e54ae1:reviews'],
+    [
+      {
+        name: 'org',
+        value: '29e54ae1'
+      }
+    ]
+  )
 
   assert.strictEqual(result, true)
 })
 
 it('should return false on mismatch with parameters', async () => {
-  const result = await match(['app:{org}:reviews'],
-    ['app:29e54ae1:reviews'], [{
-      name: 'org',
-      value: '88584c9b'
-    }])
+  const result = await match(
+    ['app:{org}:reviews'],
+    ['app:29e54ae1:reviews'],
+    [
+      {
+        name: 'org',
+        value: '88584c9b'
+      }
+    ]
+  )
 
   assert.strictEqual(result, false)
 })
 
-async function match (expected: string[], actual: string[], parameters: Parameter[] = []): Promise<boolean> {
+async function match(
+  expected: string[],
+  actual: string[],
+  parameters: Parameter[] = []
+): Promise<boolean> {
   const directive = new Role(expected, discovery)
 
   const identity: Identity = {
@@ -110,7 +136,7 @@ async function match (expected: string[], actual: string[], parameters: Paramete
   return await directive.authorize(identity, undefined, parameters)
 }
 
-function resetCalls (target = [remote, discovery], seen = new Set()) {
+function resetCalls(target = [remote, discovery], seen = new Set()) {
   if (target === null || typeof target !== 'object' || seen.has(target)) return
 
   seen.add(target)

package/source/directives/auth/Role.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert'
 import { quote } from '@toa.io/generic'
-import { type Component, type Query } from '@toa.io/core'
+import { type Component } from '@toa.io/core'
+import type { Query } from '@toa.io/core/types'
 import { type Directive, type Identity } from './types.js'
 import type { Parameter } from '../../RTD/index.js'
 
@@ -10,13 +11,16 @@ export class Role implements Directive {
   private readonly discovery: Promise<Component>
   private readonly dynamic: boolean
 
-  public constructor (roles: string | string[], discovery: Promise<Component>) {
+  public constructor(roles: string | string[], discovery: Promise<Component>) {
     this.roles = typeof roles === 'string' ? [roles] : roles
     this.discovery = discovery
     this.dynamic = this.roles.some((role) => role.includes('{'))
   }
 
-  public static async get (identity: Identity, discovery: Promise<Component>): Promise<string[]> {
+  public static async get(
+    identity: Identity,
+    discovery: Promise<Component>
+  ): Promise<string[]> {
     this.remote ??= await discovery
 
     const query: Query = {
@@ -27,9 +31,12 @@ export class Role implements Directive {
     return await this.remote.invoke('list', { query })
   }
 
-  public async authorize (identity: Identity | null, _: unknown, parameters: Parameter[]): Promise<boolean> {
-    if (identity === null)
-      return false
+  public async authorize(
+    identity: Identity | null,
+    _: unknown,
+    parameters: Parameter[]
+  ): Promise<boolean> {
+    if (identity === null) return false
 
     identity.roles ??= await Role.get(identity, this.discovery)
 
@@ -37,39 +44,39 @@ export class Role implements Directive {
   }
 
   /** 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
+  public async admits(identity: Identity | null): Promise<boolean | undefined> {
+    if (this.dynamic) return undefined
 
-    if (identity === null)
-      return false
+    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 {
+  private match(roles: string[], parameters: Parameter[]): boolean {
     const required = this.dynamic ? this.substitute(parameters) : this.roles
 
     for (const role of roles) {
-      const ok = required.some((expected) => expected === role || expected.startsWith(role + ':'))
+      const ok = required.some(
+        (expected) => expected === role || expected.startsWith(role + ':')
+      )
 
-      if (ok)
-        return true
+      if (ok) return true
     }
 
     return false
   }
 
-  private substitute (parameters: Parameter[]): string[] {
-    return this.roles.map((role) => role.replaceAll(/{(\w+)}/g, (_, key) => {
-      const value = parameters.find((parameter) => parameter.name === key)?.value
+  private substitute(parameters: Parameter[]): string[] {
+    return this.roles.map((role) =>
+      role.replaceAll(/{(\w+)}/g, (_, key) => {
+        const value = parameters.find((parameter) => parameter.name === key)?.value
 
-      assert.ok(value !== undefined,
-        `Role '${role}' requires '${key}' route parameter`)
+        assert.ok(value !== undefined, `Role '${role}' requires '${key}' route parameter`)
 
-      return value
-    }))
+        return value
+      })
+    )
   }
 }

package/source/directives/auth/Rule.ts

@@ -5,7 +5,7 @@ import type { Context, Directive, Identity, Create } from './types.js'
 export class Rule implements Directive {
   private readonly directives: Directive[] = []
 
-  public constructor (directives: Record<string, any>, create: Create) {
+  public constructor(directives: Record<string, any>, create: Create) {
     for (const [name, value] of Object.entries(directives)) {
       const directive = create(name, value)
 
@@ -13,19 +13,22 @@ export class Rule implements Directive {
     }
   }
 
-  public async authorize (identity: Identity | null, context: Context, parameters: Parameter[]): Promise<boolean> {
+  public async authorize(
+    identity: Identity | null,
+    context: Context,
+    parameters: Parameter[]
+  ): Promise<boolean> {
     for (const directive of this.directives) {
       const authorized = await directive.authorize(identity, context, parameters)
 
-      if (!authorized)
-        return false
+      if (!authorized) return false
     }
 
     return true
   }
 
   /** Whatever each of them makes of it, in the order they were declared. */
-  public describe (introspection: Introspection): Introspection {
+  public describe(introspection: Introspection): Introspection {
     for (const directive of this.directives)
       introspection = directive.describe?.(introspection) ?? introspection
 
@@ -33,7 +36,10 @@ export class Rule implements Directive {
   }
 
   /** 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> {
+  public async admits(
+    identity: Identity | null,
+    context: Context
+  ): Promise<boolean | undefined> {
     let untold = false
 
     for (const directive of this.directives) {
@@ -45,8 +51,7 @@ export class Rule implements Directive {
         continue
       }
 
-      if (!admits)
-        return false
+      if (!admits) return false
     }
 
     return untold ? undefined : true