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

package/source/directives/auth/Rule.ts

@@ -1,59 +0,0 @@
-import { type Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type { Context, Directive, Identity, Create } from './types.js'
-
-export class Rule implements Directive {
-  private readonly directives: Directive[] = []
-
-  public constructor(directives: Record<string, any>, create: Create) {
-    for (const [name, value] of Object.entries(directives)) {
-      const directive = create(name, value)
-
-      this.directives.push(directive)
-    }
-  }
-
-  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
-    }
-
-    return true
-  }
-
-  /** Whatever each of them makes of it, in the order they were declared. */
-  public describe(introspection: Introspection): Introspection {
-    for (const directive of this.directives)
-      introspection = directive.describe?.(introspection) ?? introspection
-
-    return introspection
-  }
-
-  /** All of them, so one that refuses ends it and one that cannot tell leaves it untold. */
-  public async admits(
-    identity: Identity | null,
-    context: Context
-  ): Promise<boolean | undefined> {
-    let untold = false
-
-    for (const directive of this.directives) {
-      const admits = await directive.admits?.(identity, context)
-
-      if (admits === undefined) {
-        untold = true
-
-        continue
-      }
-
-      if (!admits) return false
-    }
-
-    return untold ? undefined : true
-  }
-}

package/source/directives/auth/Scheme.ts

@@ -1,31 +0,0 @@
-import * as http from '../../HTTP/index.js'
-import { type Directive, type Identity, type Context } from './types.js'
-import { split } from './split.js'
-
-export class Scheme implements Directive {
-  private readonly scheme: string
-  private readonly Scheme: string
-
-  public constructor(scheme: string) {
-    this.scheme = scheme.toLowerCase()
-    this.Scheme = scheme[0].toUpperCase() + scheme.substring(1)
-  }
-
-  public authorize(_: Identity | null, context: Context): boolean {
-    if (context.request.headers.authorization === undefined) return false
-
-    const [scheme] = split(context.request.headers.authorization)
-
-    if (scheme !== this.scheme)
-      throw new http.Forbidden(
-        this.Scheme + ' authentication scheme is required to access this resource'
-      )
-
-    return false
-  }
-
-  /** It admits nobody: it is there to refuse a scheme, not to authorize one. */
-  public admits(): boolean {
-    return false
-  }
-}

package/source/directives/auth/create.ts

@@ -1,11 +0,0 @@
-import { newid } from '@toa.io/generic'
-import type { Identity } from './types.js'
-
-export function create(credentials?: string): Identity {
-  return {
-    id: newid(),
-    scheme: credentials?.split(' ')[0] ?? null,
-    refresh: false,
-    roles: []
-  }
-}

package/source/directives/auth/index.ts

@@ -1,3 +0,0 @@
-import { Authorization } from './Authorization.js'
-
-export const authorization = new Authorization()

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

@@ -1,18 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { providers } from './schemes.js'
-
-it('should resolve a known scheme', () => {
-  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(providers(name), undefined)
-})

package/source/directives/auth/schemes.ts

@@ -1,39 +0,0 @@
-import type { Remote, Scheme } from './types.js'
-
-/**
- * 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: Remote = 'tokens'
-
-/**
- * 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 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.
- */
-export const UNKNOWN = 'NOT_FOUND'

package/source/directives/auth/split.ts

@@ -1,14 +0,0 @@
-import * as http from '../../HTTP/index.js'
-import { type Scheme } from './types.js'
-
-export function split(authorization: string): [Scheme, string] {
-  const space = authorization.indexOf(' ')
-
-  if (space === -1) throw new http.Unauthorized('Malformed authorization header')
-
-  const Scheme = authorization.slice(0, space)
-  const scheme = Scheme.toLowerCase() as Scheme
-  const value = authorization.slice(space + 1)
-
-  return [scheme, value]
-}

package/source/directives/auth/types.ts

@@ -1,75 +0,0 @@
-import { type Component } from '@toa.io/core'
-import type { Maybe } from '@toa.io/core/types'
-import { type Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type * as http from '../../HTTP/index.js'
-import type * as io from '../../io.js'
-
-export interface Directive {
-  priority?: number
-
-  authorize: (
-    identity: Identity | null,
-    context: Context,
-    parameters: Parameter[]
-  ) => boolean | Promise<boolean>
-
-  /**
-   * Whether this admits the identity where that can be told without a request — which is
-   * what describing a method is. `undefined` says it cannot be told: a directive reading a
-   * route variable's value or the body has neither here, and one that is not implemented
-   * says the same by its absence. Nothing here may have an effect on the request.
-   */
-  admits?: (
-    identity: Identity | null,
-    context: Context
-  ) => boolean | undefined | Promise<boolean | undefined>
-
-  /**
-   * What this directive makes of what the method says about itself, which is the reverse of
-   * what it does to a request: a property it fills from the identity is taken out of the
-   * input, because it is not the caller's to send — and a description that offers one invites
-   * a caller to name an identity that is not theirs. Nothing here may have an effect on the
-   * request.
-   */
-  describe?: (introspection: Introspection) => Introspection
-
-  reply?: (context: Context) => http.OutgoingMessage | null
-
-  settle?: (context: Context, response: http.OutgoingMessage) => Promise<void>
-}
-
-export interface Identity {
-  readonly id: string
-  roles?: string[]
-  permissions?: Record<string, string[]>
-  scheme: string | null // null for transient identities
-
-  /** The component that verified the credentials; none for a transient identity. */
-  provider?: Remote
-  refresh: boolean
-}
-
-export interface Extension {
-  identity: Identity | null
-
-  /** the error code the presented credentials were rejected with, when they were */
-  rejection?: string
-
-  /** whether the identity was checked against the bans while being resolved */
-  vetted?: boolean
-}
-
-export interface Ban {
-  banned: boolean
-}
-
-export type Context = io.Input & Extension
-export type AuthenticationResult = Maybe<{ identity: Identity; refresh: boolean }>
-
-export type Scheme = 'basic' | 'token' | 'bearer' | 'code' | 'otp'
-export type Remote = 'basic' | 'federation' | 'tokens' | 'roles' | 'bans' | 'otp'
-export type Discovery = Record<Remote, Promise<Component>>
-export type Components = Partial<Record<Remote, Component>>
-
-export type Create = (name: string, value: any, ...args: any[]) => Directive

package/source/directives/cache/Cache.ts

@@ -1,92 +0,0 @@
-import { Control } from './Control.js'
-import { Exact } from './Exact.js'
-import { matches, tag } from './etag.js'
-import type { Output } from '../../io.js'
-import type { AuthenticatedContext, Directive } from './types.js'
-import type { DirectiveFamily } from '../../RTD/index.js'
-import type * as http from '../../HTTP/index.js'
-
-export class Cache implements DirectiveFamily<Directive> {
-  public readonly name: string = 'cache'
-  public readonly mandatory: boolean = true
-
-  public create(name: string, value: any): Directive {
-    const Class = constructors[name]
-
-    if (Class === undefined)
-      throw new Error(`Directive 'cache:${name}' is not implemented`)
-
-    return new Class(value)
-  }
-
-  public precall(): Output {
-    return null
-  }
-
-  public async settle(
-    directives: Directive[],
-    context: AuthenticatedContext,
-    response: http.OutgoingMessage
-  ): Promise<void> {
-    const directive = directives[0]
-    const method = context.request.method
-    const safe = method === 'GET' || method === 'HEAD'
-
-    response.headers ??= new Headers()
-
-    validate(context, response, response.headers, safe)
-
-    // `cache:exact` sets what it is given, whatever the method: whether a reply may be
-    // stored at all is not a question about the method's cacheability, and a token
-    // endpoint answers a POST it must not have kept
-    if (directive instanceof Exact) {
-      directive.set(context, response.headers)
-
-      return
-    }
-
-    if (!safe) return
-
-    if (directive === undefined) {
-      if (context.identity !== null && !Control.disabled(response.headers)) {
-        response.headers.set('cache-control', 'private')
-        response.headers.append('vary', 'authorization')
-      }
-    } else directive.set(context, response.headers)
-  }
-}
-
-/**
- * The validators a reply carries: the timestamp as `last-modified`, whatever the method, and
- * on a safe one the version as its `etag`. A client that sends the tag back in `if-none-match`
- * already has the representation and is told so, with the tag as it sent it. A reply without
- * a version has no tag: nothing identifies it but its body, and hashing that on every reply
- * is what a version is for.
- */
-// eslint-disable-next-line max-params
-function validate(
-  context: AuthenticatedContext,
-  response: http.OutgoingMessage,
-  headers: Headers,
-  safe: boolean
-): void {
-  const { version, modified } = response
-
-  if (modified !== undefined)
-    headers.set('last-modified', new Date(modified).toUTCString())
-
-  if (version === undefined || !safe) return
-
-  const sent = context.request.headers['if-none-match']
-
-  if (sent !== undefined && matches(sent, version)) {
-    response.status = 304
-    response.body = undefined
-    headers.set('etag', sent)
-  } else headers.set('etag', tag(version))
-}
-
-const constructors: Record<string, new (value: any) => Directive> = {
-  control: Control,
-  exact: Exact
-}

package/source/directives/cache/Control.ts

@@ -1,81 +0,0 @@
-import { match } from 'matchacho'
-import type { AuthenticatedContext, Directive } from './types.js'
-
-export class Control implements Directive {
-  protected readonly value: string
-  private control: string | null = null
-  private vary: boolean = false
-
-  public constructor(value: string) {
-    this.value = value
-  }
-
-  public static disabled(headers: Headers): boolean {
-    const value = headers.get('cache-control')
-
-    if (value === null) return false
-
-    const directives = mask(value)
-
-    return (directives & NO_STORE) === NO_STORE
-  }
-
-  public set(context: AuthenticatedContext, headers: Headers): void {
-    this.control ??= this.resolve(context)
-
-    if (Control.disabled(headers)) return
-
-    headers.set('cache-control', this.control)
-
-    if (this.vary) headers.append('vary', 'authorization')
-  }
-
-  protected resolve(request: AuthenticatedContext): string {
-    if (request.identity === null) return this.value
-
-    const directives = mask(this.value)
-
-    if ((directives & PRIVATE) === PRIVATE) this.vary = true
-
-    if ((directives & (PUBLIC | NO_CACHE)) === PUBLIC) return 'no-cache, ' + this.value
-
-    if ((directives & (PUBLIC | PRIVATE)) === 0) {
-      this.vary = true
-
-      return 'private, ' + this.value
-    }
-
-    return this.value
-  }
-}
-
-function mask(value: string): number {
-  const directives = value.match(DIRECTIVES_RX)
-
-  if (directives === null) return 0
-
-  let mask = 0
-
-  for (const directive of directives)
-    mask |= match<number>(
-      directive,
-      'private',
-      PRIVATE,
-      'public',
-      PUBLIC,
-      'no-cache',
-      NO_CACHE,
-      'no-store',
-      NO_STORE,
-      0
-    )
-
-  return mask
-}
-
-const DIRECTIVES_RX = /\b(private|public|no-cache|no-store)\b/gi
-
-const PUBLIC = 1
-const PRIVATE = 2
-const NO_CACHE = 4
-const NO_STORE = 8

package/source/directives/cache/Exact.ts

@@ -1,7 +0,0 @@
-import { Control } from './Control.js'
-
-export class Exact extends Control {
-  protected override resolve(): string {
-    return this.value
-  }
-}

package/source/directives/cache/etag.ts

@@ -1,38 +0,0 @@
-/**
- * An entity tag is its version in quotes, `"3"`, or the same marked weak, `W/"3"`. A client
- * sends one back in `if-match` and `if-none-match`; what it sent is compared here as a string
- * and parsed only where a version is needed of it.
- */
-export function tag(version: number): string {
-  return `"${version}"`
-}
-
-/** Whether the tag a client sent names the version, strong or weak. */
-export function matches(sent: string, version: number): boolean {
-  const strong = tag(version)
-
-  return sent === strong || sent === 'W/' + strong
-}
-
-/** The version a tag names, or nothing for a tag that is not one. */
-export function parse(sent: string): number | null {
-  const strong = sent.startsWith('W/') ? sent.slice(2) : sent
-
-  if (
-    strong.length < 3 ||
-    strong.length > 34 ||
-    !strong.startsWith('"') ||
-    !strong.endsWith('"')
-  )
-    return null
-
-  const digits = strong.slice(1, -1)
-
-  for (let i = 0; i < digits.length; i++) {
-    const code = digits.charCodeAt(i)
-
-    if (code < 48 || code > 57) return null
-  }
-
-  return Number.parseInt(digits)
-}

package/source/directives/cache/index.ts

@@ -1,3 +0,0 @@
-import { Cache } from './Cache.js'
-
-export const cache = new Cache()

package/source/directives/cache/types.ts

@@ -1,9 +0,0 @@
-import type { Input } from '../../io.js'
-
-export interface Directive {
-  set: (input: Input, headers: Headers) => void
-}
-
-export interface AuthenticatedContext extends Input {
-  identity?: unknown | null
-}

package/source/directives/cors/CORS.test.ts

@@ -1,75 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { CORS } from './CORS.js'
-import type { Input } from '../../io.js'
-
-const input = (method: string, headers: Record<string, string>): Input =>
-  ({
-    request: { method, headers },
-    pipelines: { body: [], response: [] }
-  }) as unknown as Input
-
-describe('cors', () => {
-  let cors: CORS
-
-  beforeEach(() => {
-    cors = new CORS()
-    cors.reset()
-  })
-
-  it('should answer a preflight', () => {
-    const output = cors.intercept(
-      input('OPTIONS', {
-        origin: 'https://hello.world',
-        'access-control-request-method': 'GET'
-      })
-    )
-
-    assert.equal(output?.status, 204)
-    assert.equal(output?.headers?.get('access-control-allow-origin'), 'https://hello.world')
-  })
-
-  it('should allow OPTIONS, so that one can be preflighted at all', () => {
-    const output = cors.intercept(
-      input('OPTIONS', {
-        origin: 'https://hello.world',
-        'access-control-request-method': 'OPTIONS'
-      })
-    )
-
-    assert.match(output?.headers?.get('access-control-allow-methods') ?? '', /\bOPTIONS\b/)
-  })
-
-  it('should pass an OPTIONS that is not a preflight through', () => {
-    /*
-     * A browser puts `Origin` on every request whose method is not `GET` or `HEAD`, its own
-     * `OPTIONS` included — so answering this one here would put introspection out of reach
-     * of any page. Do not restore the `Origin`-only test.
-     */
-    const output = cors.intercept(input('OPTIONS', { origin: 'https://hello.world' }))
-
-    assert.equal(output, null)
-  })
-
-  it('should decorate a reply that is not a preflight', () => {
-    const request = input('OPTIONS', { origin: 'https://hello.world' })
-
-    cors.intercept(request)
-
-    const message = {}
-
-    for (const transform of request.pipelines.response) transform(message)
-
-    const headers = (message as { headers?: Headers }).headers
-
-    assert.equal(headers?.get('access-control-allow-origin'), 'https://hello.world')
-    assert.equal(headers?.get('access-control-allow-credentials'), 'true')
-    assert.equal(headers?.get('vary'), 'origin')
-  })
-
-  it('should pass a request carrying no origin through', () => {
-    assert.equal(cors.intercept(input('OPTIONS', {})), null)
-    assert.equal(cors.intercept(input('GET', {})), null)
-  })
-})

package/source/directives/cors/CORS.ts

@@ -1,88 +0,0 @@
-import type { Input, Output } from '../../io.js'
-import type { Interceptor } from '../../Interception.js'
-
-/** What is allowed before any directive asks for more. */
-const REQUEST_HEADERS = [
-  'accept',
-  'authorization',
-  'content-type',
-  'if-match',
-  'if-none-match'
-]
-
-export class CORS implements Interceptor {
-  public readonly name = 'cors'
-
-  private requestHeaders = new Set<string>(REQUEST_HEADERS)
-
-  private readonly headers = new Headers({
-    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK, OPTIONS',
-    'access-control-allow-credentials': 'true',
-    'access-control-allow-headers': this.allowedHeaders(),
-    'access-control-max-age': '3600',
-    'cache-control': 'max-age=3600',
-    vary: 'origin'
-  })
-
-  public intercept(input: Input): Output {
-    const origin = input.request.headers.origin
-    const requested = input.request.headers['access-control-request-method']
-
-    /*
-     * A preflight is `OPTIONS` carrying `Access-Control-Request-Method`, and only that. A
-     * browser puts `Origin` on every request whose method is not `GET` or `HEAD` — its own
-     * `OPTIONS` included, same-origin or not — so answering that one here would put
-     * introspection out of reach of any page.
-     */
-    if (origin !== undefined && requested !== undefined && input.request.method === 'OPTIONS')
-      return this.preflightResponse(origin)
-
-    input.pipelines.response.push((output) => {
-      output.headers ??= new Headers()
-
-      if (origin !== undefined) {
-        output.headers.set('access-control-allow-origin', origin)
-        output.headers.set('access-control-allow-credentials', 'true')
-        output.headers.set(
-          'access-control-expose-headers',
-          'authorization, content-type, content-length, date, etag, last-modified'
-        )
-      }
-
-      const method = input.request.method
-
-      if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS')
-        output.headers.append('vary', 'origin')
-    })
-
-    return null
-  }
-
-  public reset(): void {
-    this.requestHeaders = new Set(REQUEST_HEADERS)
-    this.headers.set('access-control-allow-headers', this.allowedHeaders())
-  }
-
-  public allow(header: string): void {
-    this.requestHeaders.add(header.toLowerCase())
-    this.headers.set('access-control-allow-headers', this.allowedHeaders())
-  }
-
-  /**
-   * Sorted, because the set is filled as branches merge and their order is not
-   * fixed — an unsorted value would differ between otherwise identical processes,
-   * and between one restart and the next.
-   */
-  private allowedHeaders(): string {
-    return Array.from(this.requestHeaders).sort().join(', ')
-  }
-
-  private preflightResponse(origin: string): Output {
-    this.headers.set('access-control-allow-origin', origin)
-
-    return {
-      status: 204,
-      headers: this.headers
-    }
-  }
-}

package/source/directives/cors/index.ts

@@ -1,3 +0,0 @@
-import { CORS } from './CORS.js'
-
-export const cors = new CORS()