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

package/source/directives/oauth/Discovery.ts

@@ -1,66 +0,0 @@
-import { documents, type Documents } from './documents.js'
-import type * as http from '../../HTTP/index.js'
-import type { Input, Output } from '../../io.js'
-import type { Interceptor } from '../../Interception.js'
-
-/**
- * What a client reads before it can authenticate: where the authorization server is, and
- * what this resource expects. Both are fixed paths a specification names, both must be
- * answered to anyone, and both are a function of the annotation alone — nothing is read to
- * build them, so they are built once per authority and served as they are.
- *
- * An interceptor rather than a route because `auth` runs before any directive: a client
- * re-reading discovery while holding a stale token would have it verified, and then be
- * refused a document that has to be public.
- */
-export class Discovery implements Interceptor {
-  /**
-   * A map, because the key is the request's authority and an unconfigured host is passed
-   * through as itself: `Host: constructor` names something a plain object answers on its own.
-   */
-  private readonly authorities = new Map<string, Documents>()
-
-  public mount(options: http.Options): void {
-    this.authorities.clear()
-
-    if (options.oauth === undefined) return
-
-    /*
-     * `https` always: RFC 8414 has an issuer be one, and OAuth 2.1 has every endpoint of an
-     * authorization server be one — the loopback exception is a client's redirect URI, not
-     * a server's address. A gateway served without TLS has no authorization server a client
-     * may use, and naming it `http` would hide that behind documents none should accept.
-     *
-     * The host is the configured one, not the request's, which is the client's to write: a
-     * forged one would have these documents name someone else's token endpoint.
-     */
-    for (const [authority, host] of Object.entries(options.authorities))
-      this.authorities.set(authority, documents(`https://${host}`, options.oauth))
-  }
-
-  public reset(): void {
-    this.authorities.clear()
-  }
-
-  public intercept(input: Input): Output {
-    const known = this.authorities.get(input.authority)
-
-    if (known === undefined) return null
-
-    // every reply, not just a document's: the challenge is what points a client here
-    input.pipelines.response.push((response) => {
-      if (response.status !== UNAUTHORIZED) return
-
-      response.headers ??= new Headers()
-      response.headers.set('www-authenticate', known.challenge(input.url.pathname))
-    })
-
-    const body = known.read(input.url.pathname)
-
-    if (body === undefined) return null
-
-    return { body, headers: new Headers({ 'cache-control': 'public, max-age=3600' }) }
-  }
-}
-
-const UNAUTHORIZED = 401

package/source/directives/oauth/documents.ts

@@ -1,110 +0,0 @@
-import type { OAuth } from '../../Annotation.js'
-
-/** The discovery documents of one authority, and the challenge that points at them. */
-export interface Documents {
-  /** The document a path names, or nothing when it names none. */
-  read: (pathname: string) => object | undefined
-
-  /** `WWW-Authenticate` for a request to this path, which names the resource it failed at. */
-  challenge: (pathname: string) => string
-}
-
-export function documents(issuer: string, oauth: OAuth): Documents {
-  const server = authorizationServer(issuer, oauth)
-  const resources = protectedResources(issuer, oauth)
-  const scope = oauth.scopes === undefined ? '' : `, scope="${oauth.scopes.join(' ')}"`
-
-  function read(pathname: string): object | undefined {
-    if (pathname === AUTHORIZATION_SERVER || pathname === OPENID_CONFIGURATION)
-      return server
-
-    if (pathname.startsWith(PROTECTED_RESOURCE))
-      return resources.get(pathname.slice(PROTECTED_RESOURCE.length))
-
-    return undefined
-  }
-
-  function challenge(pathname: string): string {
-    return `Bearer resource_metadata="${issuer}${PROTECTED_RESOURCE}${suffix(oauth, pathname)}"${scope}`
-  }
-
-  return { read, challenge }
-}
-
-/**
- * RFC 8414. `authorization_endpoint` is the application's own page and may be anywhere;
- * everything else this extension serves. Both flags are load-bearing for a client that
- * prefers Client ID Metadata Documents: without either it falls back to registration.
- */
-function authorizationServer(issuer: string, oauth: OAuth): object {
-  const metadata: Record<string, unknown> = {
-    issuer,
-    authorization_endpoint: oauth.authorize,
-    token_endpoint: `${issuer}${TOKEN}`,
-    response_types_supported: ['code'],
-    grant_types_supported: ['authorization_code'],
-    code_challenge_methods_supported: ['S256'],
-    token_endpoint_auth_methods_supported: ['none'],
-    client_id_metadata_document_supported: true,
-    authorization_response_iss_parameter_supported: true
-  }
-
-  if (oauth.registration === 'open')
-    metadata.registration_endpoint = `${issuer}${REGISTRATION}`
-
-  if (oauth.scopes !== undefined) metadata.scopes_supported = oauth.scopes
-
-  return metadata
-}
-
-/**
- * RFC 9728, keyed by the path the well-known segment is followed by: a client resolving
- * `https://host/mcp` reads `/.well-known/oauth-protected-resource/mcp`, and one that names
- * no path reads the document at the origin.
- */
-function protectedResources(issuer: string, oauth: OAuth): Map<string, object> {
-  const map = new Map<string, object>()
-
-  for (const path of oauth.resources ?? [])
-    map.set(canonical(path), resource(issuer, canonical(path), oauth))
-
-  map.set('', resource(issuer, '', oauth))
-
-  return map
-}
-
-function resource(issuer: string, path: string, oauth: OAuth): object {
-  const metadata: Record<string, unknown> = {
-    resource: issuer + path,
-    authorization_servers: [issuer],
-    bearer_methods_supported: ['header']
-  }
-
-  if (oauth.scopes !== undefined) metadata.scopes_supported = oauth.scopes
-
-  return metadata
-}
-
-/** The document a request to this path was refused against: the longest resource holding it. */
-function suffix(oauth: OAuth, pathname: string): string {
-  let longest = ''
-
-  for (const path of oauth.resources ?? [])
-    if (pathname.startsWith(path) && path.length > longest.length) longest = path
-
-  return canonical(longest)
-}
-
-/**
- * A resource is identified without its trailing slash — the form MCP asks for — while a
- * route is declared with one, so `/mcp/` identifies `…/mcp`.
- */
-function canonical(path: string): string {
-  return path.endsWith('/') ? path.slice(0, -1) : path
-}
-
-const AUTHORIZATION_SERVER = '/.well-known/oauth-authorization-server'
-const PROTECTED_RESOURCE = '/.well-known/oauth-protected-resource'
-const OPENID_CONFIGURATION = '/.well-known/openid-configuration'
-const TOKEN = '/identity/grants/'
-const REGISTRATION = '/identity/clients/'

package/source/directives/oauth/index.ts

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

package/source/directives/octets/Context.ts

@@ -1,23 +0,0 @@
-import assert from 'node:assert'
-import { Directive } from './Directive.js'
-import type { Output } from '../../io.js'
-
-export class Context extends Directive {
-  public readonly targeted = false
-  public readonly storage: string
-
-  public constructor(value: unknown) {
-    super()
-
-    assert.ok(
-      typeof value === 'string',
-      "Directive 'octets:context' must must be a string"
-    )
-
-    this.storage = value
-  }
-
-  public async apply(): Promise<Output> {
-    return null
-  }
-}

package/source/directives/octets/Delete.ts

@@ -1,96 +0,0 @@
-import { Readable } from 'stream'
-import { NotFound } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { Workflow } from './workflows/index.js'
-import { Directive } from './Directive.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Unit, Location } from './workflows/index.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Input } from './types.js'
-import type { Remotes } from '../../Remotes.js'
-import type { Entry } from '@toa.io/extensions.storages'
-
-export class Delete extends Directive {
-  public readonly targeted = true
-
-  private readonly workflow?: Workflow
-  private readonly discovery: Promise<Component>
-  private storage!: Component
-
-  public constructor(
-    options: Options | null,
-    discovery: Promise<Component>,
-    remotes: Remotes
-  ) {
-    super()
-    schemas.remove.validate(options)
-
-    if (options?.workflow !== undefined)
-      this.workflow = new Workflow(options.workflow, remotes)
-
-    this.discovery = discovery
-  }
-
-  public async apply(
-    storage: string,
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    const output: Output = {}
-
-    if (this.workflow !== undefined) {
-      const entry = await this.storage.invoke<Maybe<Entry>>('head', {
-        input: {
-          storage,
-          path: input.request.url
-        }
-      })
-
-      if (entry instanceof Error) throw new NotFound()
-
-      output.status = 202
-      output.body = Readable.from(this.execute(input, storage, entry, parameters))
-    } else await this.delete(storage, input)
-
-    return output
-  }
-
-  private async delete(storage: string, input: Input): Promise<void> {
-    await this.storage.invoke('delete', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-  }
-
-  // eslint-disable-next-line max-params
-  private async *execute(
-    input: Input,
-    storage: string,
-    entry: Entry,
-    parameters: Parameter[]
-  ): AsyncGenerator {
-    const location: Location = {
-      storage,
-      authority: input.authority,
-      path: input.request.url
-    }
-
-    for await (const chunk of this.workflow!.execute(location, entry, parameters)) {
-      yield chunk
-
-      if (typeof chunk === 'object' && chunk !== null && 'error' in chunk) return
-    }
-
-    await this.delete(storage, input)
-  }
-}
-
-export interface Options {
-  workflow?: Unit[] | Unit
-}

package/source/directives/octets/Directive.ts

@@ -1,21 +0,0 @@
-import type { Input } from './types.js'
-import type { Parameter } from '../../RTD/index.js'
-import type { Introspection } from '../../Introspection.js'
-import type * as io from '../../io.js'
-
-export abstract class Directive {
-  public readonly name = 'octets.' + this.constructor.name.toLowerCase()
-  public abstract readonly targeted: boolean
-
-  public abstract apply(
-    storage: string,
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<io.Output>
-
-  /**
-   * What a caller has to know to make the request. Only sending a file takes anything a
-   * schema does not already say; reading one and deleting one take nothing.
-   */
-  public describe?(introspection: Introspection): void
-}

package/source/directives/octets/Get.ts

@@ -1,88 +0,0 @@
-import { Forbidden, NotFound } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { Directive } from './Directive.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Entry, Stream } from '@toa.io/extensions.storages'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Input } from './types.js'
-
-export class Get extends Directive {
-  public readonly targeted = true
-
-  private readonly options: Required<Options> = {
-    meta: false
-  }
-
-  private readonly discovery: Promise<Component>
-  private storage!: Component
-
-  public constructor(options: Options | null, discovery: Promise<Component>) {
-    super()
-
-    schemas.get.validate(options)
-    Object.assign(this.options, options)
-
-    this.discovery = discovery
-  }
-
-  public async apply(storage: string, input: Input): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    if (input.subtype === 'octets.entry')
-      if (this.options.meta) return this.head(storage, input)
-      else throw new Forbidden('Metadata is not accessible')
-    else return await this.get(storage, input)
-  }
-
-  private async get(storage: string, input: Input): Promise<Output> {
-    if ('if-none-match' in input.request.headers) return { status: 304 }
-
-    const endpoint = input.request.method === 'GET' ? 'get' : 'head'
-
-    const entry = await this.storage.invoke<Maybe<Stream>>(endpoint, {
-      input: {
-        storage,
-        path: input.request.url,
-        range: input.request.headers.range,
-        agent: input.request.headers['user-agent']
-      }
-    })
-
-    if (entry instanceof Error) throw new NotFound()
-
-    const headers = new Headers({
-      'content-type': entry.type,
-      etag: `"${entry.checksum}"`
-    })
-
-    if (entry.range !== undefined) headers.set('content-range', entry.range)
-
-    // an absent content-length is what says the length is unknown; naming the encoding
-    // is redundant over HTTP/1.1 and forbidden over HTTP/2
-    if (entry.size !== null) headers.set('content-length', entry.size.toString())
-
-    return {
-      status: entry.partial === true ? 206 : 200,
-      headers,
-      body: endpoint === 'get' ? entry.stream : undefined
-    }
-  }
-
-  private async head(storage: string, input: Input): Promise<Output> {
-    const entry = await this.storage.invoke<Maybe<Entry>>('head', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-
-    if (entry instanceof Error) throw new NotFound()
-
-    return { body: entry }
-  }
-}
-
-export interface Options {
-  meta?: boolean
-}

package/source/directives/octets/Octets.ts

@@ -1,82 +0,0 @@
-import { NotFound } from '../../HTTP/index.js'
-import { Context } from './Context.js'
-import { Put } from './Put.js'
-import { Get } from './Get.js'
-import { Delete } from './Delete.js'
-import { WorkflowDirective } from './Workflow.js'
-import type { Directive } from './Directive.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 { Introspection } from '../../Introspection.js'
-import type { Input } from './types.js'
-
-export class Octets implements DirectiveFamily<Directive> {
-  public readonly name: string = 'octets'
-  public readonly mandatory: boolean = false
-
-  private discovery = null as unknown as Promise<Component>
-
-  public create(name: string, value: any, remotes: Remotes): Directive {
-    const Class = DIRECTIVES[name]
-
-    if (Class === undefined)
-      throw new Error(`Directive 'octets:${name}' is not implemented`)
-
-    this.discovery ??= remotes.discover('exposition', 'octets')
-
-    return new Class(value, this.discovery, remotes)
-  }
-
-  /** What the request takes, which only sending a file says anything about. */
-  public explain(directives: Directive[], _: Input, introspection: Introspection): Introspection {
-    for (const directive of directives) directive.describe?.(introspection)
-
-    return introspection
-  }
-
-  public async precall(
-    directives: Directive[],
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    let context: Context | null = null
-    let action: Directive | null = null
-
-    for (const directive of directives)
-      if (directive instanceof Context) context ??= directive
-      else if (action === null) action = directive
-      else throw new Error('Octets action is ambiguous')
-
-    if (action === null) return null
-
-    // noinspection PointlessBooleanExpressionJS
-    if (context === null) throw new Error('Octets context is not defined')
-
-    const targeted = input.request.url[input.request.url.length - 1] !== '/'
-
-    if (targeted !== action.targeted)
-      throw new NotFound(
-        `Trailing slash is ${action.targeted ? 'redundant' : 'required'}`
-      )
-
-    // noinspection JSObjectNullOrUndefined
-    return await action.apply(context.storage, input, parameters)
-  }
-}
-
-const DIRECTIVES: Record<string, Constructor> = {
-  context: Context,
-  put: Put,
-  get: Get,
-  head: Get,
-  delete: Delete,
-  workflow: WorkflowDirective
-}
-
-type Constructor = new (
-  value: any,
-  discovery: Promise<Component>,
-  remotes: Remotes
-) => Directive

package/source/directives/octets/Put.ts

@@ -1,186 +0,0 @@
-import { PassThrough } from 'node:stream'
-import { match } from 'matchacho'
-import * as http from '../../HTTP/index.js'
-import { cors } from '../cors/index.js'
-import * as schemas from './schemas.js'
-import { Workflow } from './workflows/index.js'
-import { Directive } from './Directive.js'
-import { toBytes } from './bytes.js'
-import type { Readable } from 'stream'
-import type { Parameter } from '../../RTD/index.js'
-import type { Unit, Location } from './workflows/index.js'
-import type { Entry } from '@toa.io/extensions.storages'
-import type { Remotes } from '../../Remotes.js'
-import type { Component } from '@toa.io/core'
-import type { Introspection } from '../../Introspection.js'
-import type { Output } from '../../io.js'
-import type { Input } from './types.js'
-
-export class Put extends Directive {
-  public readonly targeted = false
-
-  private readonly location?: string
-  private readonly accept?: string
-  private readonly limit: number
-  private readonly limitString: string
-  private readonly trust?: Array<string | RegExp>
-  private readonly workflow?: Workflow
-  private readonly discovery: Record<string, Promise<Component>> = {}
-  private storage: Component | null = null
-
-  public constructor(
-    options: Options | null,
-    discovery: Promise<Component>,
-    remotes: Remotes
-  ) {
-    super()
-
-    schemas.put.validate<Options>(options)
-
-    this.accept = match(
-      options?.accept,
-      String,
-      (value: string) => value,
-      Array,
-      (types: string[]) => types.join(','),
-      undefined
-    )
-
-    if (options?.workflow !== undefined)
-      this.workflow = new Workflow(options.workflow, remotes)
-
-    if (options?.trust !== undefined)
-      this.trust = options.trust.map((value: string) =>
-        value.startsWith('/') ? new RegExp(value.slice(1, -1)) : value
-      )
-
-    if (options?.location !== undefined) this.location = options.location
-
-    this.limitString = options?.limit ?? '64MiB'
-    this.limit = toBytes(this.limitString)
-    this.discovery.storage = discovery
-
-    cors.allow('content-attributes')
-    cors.allow('content-location')
-  }
-
-  /** What sending a file here takes: what may be sent, how much of it, and what comes back. */
-  public override describe(introspection: Introspection): void {
-    introspection.octets = {
-      ...(this.accept === undefined ? {} : { accept: this.accept }),
-      limit: this.limitString,
-      ...(this.workflow === undefined ? {} : { stream: true })
-    }
-  }
-
-  public async apply(
-    storage: string,
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    this.storage ??= await this.discovery.storage
-
-    const request: StoreRequest = {
-      input: {
-        storage,
-        request: input.request,
-        location: this.location,
-        accept: this.accept,
-        limit: this.limit,
-        trust: this.trust
-      }
-    }
-
-    const entry = await this.storage.invoke<Entry>('put', request)
-
-    return match<Output>(
-      entry,
-      Error,
-      (error: CodedError) => this.throw(error),
-      () => this.reply(input, storage, entry, parameters)
-    )
-  }
-
-  // eslint-disable-next-line max-params
-  private reply(
-    input: Input,
-    storage: string,
-    entry: Entry,
-    parameters: Parameter[]
-  ): Output {
-    const body =
-      this.workflow === undefined
-        ? entry
-        : this.execute(input, storage, entry, parameters)
-
-    return { body }
-  }
-
-  // eslint-disable-next-line max-params
-  private execute(
-    input: Input,
-    storage: string,
-    entry: Entry,
-    parameters: Parameter[]
-  ): Readable {
-    const stream = new PassThrough({ objectMode: true })
-
-    stream.push(entry)
-
-    const location: Location = {
-      storage,
-      authority: input.authority,
-      identity: input.identity?.id,
-      path: this.location ?? input.request.url
-    }
-
-    this.workflow!.execute(location, entry, parameters).pipe(stream)
-
-    return stream
-  }
-
-  private throw(error: CodedError): never {
-    throw match(
-      error.code,
-      'NOT_ACCEPTABLE',
-      () => new http.UnsupportedMediaType(),
-      'TYPE_MISMATCH',
-      () => new http.BadRequest(),
-      'LIMIT_EXCEEDED',
-      () => new http.RequestEntityTooLarge(`Size limit is ${this.limitString}`),
-      'LOCATION_UNTRUSTED',
-      () => new http.Forbidden(error.message),
-      'LOCATION_LENGTH',
-      () => new http.BadRequest(error.message),
-      'LOCATION_UNAVAILABLE',
-      () => new http.NotFound(error.message),
-      'INVALID_ID',
-      () => new http.BadRequest(error.message),
-      error
-    )
-  }
-}
-
-export interface Options {
-  location?: string
-  accept?: string | string[]
-  limit?: string
-  workflow?: Unit[] | Unit
-  trust?: string[]
-}
-
-interface StoreRequest {
-  input: {
-    storage: string
-    request: Input['request']
-    location?: string
-    accept?: string
-    limit?: number
-    trust?: Array<string | RegExp>
-    attributes?: Record<string, string>
-  }
-}
-
-interface CodedError extends Error {
-  code: string
-}