@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.292

package/source/directives/auth/Federation.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert'
+import type { Directive, Identity, Context } from './types.js'
+import type { Introspection } from '../../Introspection.js'
+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'
+    )
+  }
+
+  /** Which claims it takes needs the request; that it takes an identity does not. */
+  public admits(identity: Identity | null): boolean | undefined {
+    return identity === null ? false : undefined
+  }
+
+  /** Which claims is the application's business; that it takes an identity is the caller's. */
+  public describe(introspection: Introspection): Introspection {
+    return { ...introspection, authenticated: true }
+  }
+
+  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
+
+    return true
+  }
+}
+
+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 === 'domain')
+      return (value, context) => {
+        return Array.isArray(value)
+          ? value.some((iss) => codomain(iss, context))
+          : codomain(value, context)
+      }
+
+    throw new Error('Unknown `auth:claims` syntax: ' + expression)
+  }
+
+  if (expression.startsWith('/:')) {
+    const name = expression.slice(2)
+
+    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 codomain(iss: string, context: Context): boolean {
+  const hostname = new URL(iss).hostname
+  const dot = hostname.indexOf('.')
+  const basename = dot === -1 ? hostname : hostname.slice(dot)
+
+  return context.authority.slice(-basename.length) === basename
+}
+
+type Matcher = (
+  value: string | string[],
+  context: Context,
+  parameters: Parameter[]
+) => boolean
+
+interface Claims {
+  iss: string
+  sub: string
+  aud: string | string[]
+}
+
+interface Options extends Partial<Claims> {
+  iss: string
+}
+
+interface FederatedIdentity extends Identity {
+  claims: Claims
+}

package/source/directives/auth/Id.ts

@@ -1,16 +1,34 @@
-import { type Parameter } from '../../RTD'
-import { type Directive, type Identity } from './types'
+import { type Parameter } from '../../RTD/index.js'
+import { type Directive, type Identity } from './types.js'
+import type { Introspection } from '../../Introspection.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, _: any, parameters: Parameter[]): boolean {
-    if (identity === null)
-      return false
+  /**
+   * Whether it is *this* identity's cannot be told from a description, which has no route
+   * variable to read — but that there must be an identity at all can, and a caller with
+   * none is refused whatever the value would have been.
+   */
+  public admits(identity: Identity | null): boolean | undefined {
+    return identity === null ? false : undefined
+  }
+
+  /** Reaching it is being the identity it is about, which is what `private` says. */
+  public describe(introspection: Introspection): Introspection {
+    return { ...introspection, private: true }
+  }
+
+  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

@@ -1,48 +1,117 @@
-import { type Maybe } from '@toa.io/types'
-import * as http from '../../HTTP'
-import { type Directive, type Discovery, type Identity, type Input, type Schemes } from './types'
-import { split } from './split'
-import { PROVIDERS } from './schemes'
+import assert from 'node:assert'
+import { console } from 'openspan'
+import * as http from '../../HTTP/index.js'
+import { split } from './split.js'
+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/types'
+import type { Directive, Discovery, Identity, Context, Components, Ban } from './types.js'
 
 export class Incept implements Directive {
-  private readonly property: string
-  private readonly discovery: Discovery
-  private readonly schemes: Schemes = {} as unknown as Schemes
+  private static readonly components: Components = {}
+  private static discovery: Discovery
+  private static bans: Component | null = null
+
+  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) {
     this.property = property
-    this.discovery = discovery
+    Incept.discovery ??= discovery
   }
 
-  public authorize (identity: Identity | null, input: Input): boolean {
-    return identity === null && 'authorization' in input.request.headers
-  }
+  public static async incept(context: Context, id: string): Promise<Identity> {
+    const [scheme, credentials] = split(context.request.headers.authorization!)
+    const candidates = providersOf(scheme)
+
+    if (candidates === undefined)
+      throw new http.BadRequest('Authentication scheme is not supported')
+
+    // 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()
 
-  public async settle (input: Input, response: http.OutgoingMessage): Promise<void> {
-    const id = response.body?.[this.property]
+    Incept.bans ??= await Incept.discovery.bans
 
-    if (id === undefined)
-      throw new http.Conflict('Identity inception has failed as the response body ' +
-        ` does not contain the '${this.property}' property.`)
+    const ban = await Incept.bans.invoke<Ban>('observe', { query: { id } })
 
-    const [scheme, credentials] = split(input.request.headers.authorization!)
-    const provider = PROVIDERS[scheme]
+    if (ban.banned) throw new http.Unauthorized()
 
-    this.schemes[scheme] ??= await this.discovery[provider]
+    Incept.components[provider] ??= await Incept.discovery[provider]
 
-    const identity = await this.schemes[scheme]
-      .invoke<Maybe<Identity>>('incept', {
-      input: {
-        authority: input.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)
+
+    identity.scheme = scheme
+
+    // the roles are read where the token is minted: an Identity incepted as the principal
+    // has one already
+    return identity
+  }
+
+  /** 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 {
+    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> {
+    const id = response.body?.[this.property ?? 'id']
+
+    if (id === undefined) {
+      console.debug('Inception skipped: response does not contain expected property', {
+        property: this.property,
+        response
+      })
+
+      return
+    }
+
+    assert(
+      typeof id === 'string',
+      `Response body property "${this.property}" expected to be a string`
+    )
 
-    if (identity instanceof Error)
-      throw new http.UnprocessableEntity(identity)
+    if (context.request.headers.authorization !== undefined)
+      context.identity = await Incept.incept(context, id)
+    else {
+      const identity = { id, scheme: null, refresh: true }
+      const roles = await Role.get(identity, Incept.discovery.roles)
 
-    input.identity = identity
-    input.identity.scheme = scheme
+      context.identity = { ...identity, roles }
+    }
   }
 }

package/source/directives/auth/Input.ts

@@ -0,0 +1,92 @@
+import { Forbidden } from '../../HTTP/index.js'
+import type { Parameter } from '../../RTD/index.js'
+import type { Context, Directive, Identity, Create } from './types.js'
+
+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)
+    )
+  }
+
+  /** It admits nobody: it says what a body may carry, not who may send one. */
+  public admits(): boolean {
+    return false
+  }
+
+  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
+
+    return body
+  }
+}
+
+class Statement {
+  private readonly properties: string[]
+  private readonly directives: Directive[] = []
+
+  public constructor({ prop, ...directives }: Declaration, create: Create) {
+    this.properties = typeof prop === 'string' ? [prop] : prop
+
+    for (const [name, value] of Object.entries(directives)) {
+      const directive = create(name, value)
+
+      this.directives.push(directive)
+    }
+  }
+
+  // eslint-disable-next-line max-params
+  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
+
+    for (const directive of this.directives) {
+      const authorized = await directive.authorize(identity, context, parameters)
+
+      if (!authorized) throw new Forbidden('Input property is not authorized')
+    }
+  }
+}
+
+export interface Declaration {
+  [key: Exclude<string, 'prop'>]: unknown
+
+  prop: string | string[]
+}
+
+type Body = Record<string, unknown>

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

@@ -1,17 +1,21 @@
+import { it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
+
 import { type Component } from '@toa.io/core'
 import { generate } from 'randomstring'
-import { Role } from './Role'
-import { type Identity } from './types'
-import type { Parameter } from '../../RTD'
+import { Role } from './Role.js'
+import { type Identity } from './types.js'
+import type { Parameter } from '../../RTD/index.js'
 
 const remote = {
-  invoke: jest.fn()
-} as unknown as jest.MockedObject<Component>
+  invoke: mock.fn()
+} as unknown as Component
 
 const discovery = Promise.resolve(remote)
 
 beforeEach(() => {
-  jest.clearAllMocks()
+  resetCalls()
 })
 
 it('should return false if not matched', async () => {
@@ -24,77 +28,101 @@ it('should return false if not matched', async () => {
     refresh: false
   }
 
-  remote.invoke.mockResolvedValueOnce(['guest'])
+  remote.invoke.mock.mockImplementationOnce(async () => ['guest'])
 
   const result = await directive.authorize(identity, undefined, [])
 
-  expect(result).toBe(false)
-
-  expect(remote.invoke)
-    .toBeCalledWith('list', {
-      query: {
-        criteria: `identity==${identity.id}`,
-        limit: 1024
-      }
-    })
+  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
+          }
+        })
+    )
+  )
 })
 
 it('should return true on exact match', async () => {
   const result = await match(['admin', 'user'], ['user'])
 
-  expect(result).toBe(true)
+  assert.strictEqual(result, true)
 })
 
 it('should return true on scope match', async () => {
   const result = await match(['system:identity:roles'], ['system'])
 
-  expect(result).toBe(true)
+  assert.strictEqual(result, true)
 })
 
 it('should return false on scope mismatch', async () => {
   const result = await match(['system:identity'], ['system:identity:roles'])
 
-  expect(result).toBe(false)
+  assert.strictEqual(result, false)
 })
 
 it('should return false on non-scope substring match', async () => {
   const result = await match(['system:identity'], ['system:iden'])
 
-  expect(result).toBe(false)
+  assert.strictEqual(result, false)
 })
 
 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'
+      }
+    ]
+  )
 
-  expect(result).toBe(true)
+  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'
+      }
+    ]
+  )
 
-  expect(result).toBe(true)
+  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'
+      }
+    ]
+  )
 
-  expect(result).toBe(false)
+  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 = {
@@ -103,7 +131,17 @@ async function match
     refresh: false
   }
 
-  remote.invoke.mockResolvedValueOnce(actual)
+  remote.invoke.mock.mockImplementationOnce(async () => actual)
 
   return await directive.authorize(identity, undefined, parameters)
 }
+
+function resetCalls(target = [remote, discovery], seen = new Set()) {
+  if (target === null || typeof target !== 'object' || seen.has(target)) return
+
+  seen.add(target)
+
+  for (const value of Object.values(target))
+    if (typeof value === 'function' && value.mock !== undefined) value.mock.resetCalls()
+    else resetCalls(value, seen)
+}