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

package/source/Tenant.ts

@@ -1,7 +1,7 @@
 import { setTimeout } from 'node:timers/promises'
 import { Connector } from '@toa.io/core'
 import { BRANCH_TTL } from './const.js'
-import type { bindings } from '@toa.io/core'
+import type { bindings } from '@toa.io/core/types'
 import type { Label } from './discovery.js'
 import type { Branch } from './Branch.js'
 
@@ -11,7 +11,7 @@ export class Tenant extends Connector {
   private started = 0
   private stopped = false
 
-  public constructor (broadcast: Broadcast, branch: Omit<Branch, 'timestamp'>) {
+  public constructor(broadcast: Broadcast, branch: Omit<Branch, 'timestamp'>) {
     super()
 
     this.broadcast = broadcast
@@ -20,7 +20,7 @@ export class Tenant extends Connector {
     this.depends(broadcast)
   }
 
-  public override async open (): Promise<void> {
+  public override async open(): Promise<void> {
     this.started = Date.now()
 
     await this.expose()
@@ -35,35 +35,35 @@ export class Tenant extends Connector {
    * announces itself once more has its routes held open by whoever is listening, and the
    * requests that follow reach nothing.
    */
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     this.stopped = true
   }
 
-  private async announce (): Promise<void> {
+  private async announce(): Promise<void> {
     while (!this.stopped) {
       const delay = exposeInterval(Date.now() - this.started)
 
       await setTimeout(delay, undefined, { ref: false })
 
-      if (this.stopped)
-        break
+      if (this.stopped) break
 
       await this.expose()
     }
   }
 
-  private async expose (): Promise<void> {
+  private async expose(): Promise<void> {
     // the ping subscription outlives the announcing loop, and answering one on the way out
     // is the same announcement by another route
-    if (this.stopped)
-      return
+    if (this.stopped) return
 
     await this.broadcast.transmit('expose', { ...this.branch, timestamp: this.started })
   }
 }
 
-function exposeInterval (uptime: number): number {
-  return Math.round(EXPOSE_MAX - (EXPOSE_MAX - EXPOSE_MIN) * Math.exp(-uptime / EXPOSE_TAU))
+function exposeInterval(uptime: number): number {
+  return Math.round(
+    EXPOSE_MAX - (EXPOSE_MAX - EXPOSE_MIN) * Math.exp(-uptime / EXPOSE_TAU)
+  )
 }
 
 const EXPOSE_MIN = 5_000

package/source/deployment.ts

@@ -8,7 +8,11 @@ import { components } from './Composition.js'
 import { parse } from './RTD/syntax/index.js'
 import { DELAY, PORT, PROBE } from './HTTP/index.js'
 
-export function deployment (_: unknown, annotation?: Annotation): Dependency {
+/** Where Toa's release publishes this service's image. An application takes it
+ *  instead of building one when its context says `registry.services: published`. */
+export const image = 'ghcr.io/toa-io/extension-exposition-gateway'
+
+export function deployment(_: unknown, annotation?: Annotation): Dependency {
   assert.ok(annotation !== undefined, 'Exposition context annotation is required')
   schemas.annotation.validate(annotation)
 
@@ -17,8 +21,10 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   const service: Service = {
     group: 'exposition',
     name: 'gateway',
+    image,
     port: PORT,
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+      .version,
     variables: [],
     components: labels,
     resources: annotation.resources,
@@ -44,8 +50,7 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   service.ingress!.hosts = Object.values(authorities)
 
   // leaving these undefined lets the context's own ingress section supply them
-  if (annotation.class !== undefined)
-    service.ingress!.class = annotation.class
+  if (annotation.class !== undefined) service.ingress!.class = annotation.class
 
   if (annotation.annotations !== undefined)
     service.ingress!.annotations = annotation.annotations
@@ -55,26 +60,19 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
 
   const properties: Properties = { authorities }
 
-  if (debug === true)
-    properties.debug = true
+  if (debug === true) properties.debug = true
 
-  if (annotation.protocol !== undefined)
-    properties.protocol = annotation.protocol
+  if (annotation.protocol !== undefined) properties.protocol = annotation.protocol
 
-  if (annotation.ip !== undefined)
-    properties.ip = annotation.ip
+  if (annotation.ip !== undefined) properties.ip = annotation.ip
 
-  if (annotation.bouncer !== undefined)
-    properties.bouncer = annotation.bouncer
+  if (annotation.bouncer !== undefined) properties.bouncer = annotation.bouncer
 
-  if (annotation.oauth !== undefined)
-    properties.oauth = annotation.oauth
+  if (annotation.oauth !== undefined) properties.oauth = annotation.oauth
 
-  if (annotation.rpc !== undefined)
-    properties.rpc = annotation.rpc
+  if (annotation.rpc !== undefined) properties.rpc = annotation.rpc
 
-  if (annotation.mcp !== undefined)
-    properties.mcp = annotation.mcp
+  if (annotation.mcp !== undefined) properties.mcp = annotation.mcp
 
   service.variables!.push({
     name: 'TOA_EXPOSITION_PROPERTIES',
@@ -92,5 +90,7 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
   return { services: [service] }
 }
 
-type Properties = Pick<Annotation,
-'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip' | 'oauth' | 'rpc' | 'mcp'>
+type Properties = Pick<
+  Annotation,
+  'authorities' | 'debug' | 'protocol' | 'bouncer' | 'ip' | 'oauth' | 'rpc' | 'mcp'
+>

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

@@ -14,7 +14,10 @@ describe('anonymous', () => {
 
   it('should refuse a request that presents a credential', () => {
     // it would make the reply uncacheable, which is the whole of the rule
-    assert.equal(new Anonymous(true).authorize(null, context({ authorization: 'Token x' })), false)
+    assert.equal(
+      new Anonymous(true).authorize(null, context({ authorization: 'Token x' })),
+      false
+    )
   })
 
   it('should admit a procedure whatever the request presented', () => {
@@ -33,6 +36,9 @@ describe('anonymous', () => {
     const directive = new Anonymous(true)
 
     assert.equal(directive.admits(null, context({ authorization: 'Token x' })), false)
-    assert.equal(directive.admits(null, context({ authorization: 'Token x' }, true)), true)
+    assert.equal(
+      directive.admits(null, context({ authorization: 'Token x' }, true)),
+      true
+    )
   })
 })

package/source/directives/auth/Anonymous.ts

@@ -3,7 +3,7 @@ import { type Directive, type Context } from './types.js'
 export class Anonymous implements Directive {
   private readonly allow: boolean
 
-  public constructor (allow: boolean) {
+  public constructor(allow: boolean) {
     this.allow = allow
   }
 
@@ -12,16 +12,13 @@ export class Anonymous implements Directive {
    * of the rule, and none of it applies to a procedure: what a procedure answers is a value
    * in an envelope, and the envelope is the one thing that is cached or not.
    */
-  public authorize (_: any, context: Context): boolean {
-    if (context.procedural)
-      return this.allow
+  public authorize(_: any, context: Context): boolean {
+    if (context.procedural) return this.allow
 
-    return 'authorization' in context.request.headers
-      ? false
-      : this.allow
+    return 'authorization' in context.request.headers ? false : this.allow
   }
 
-  public admits (_: any, context: Context): boolean {
+  public admits(_: any, context: Context): boolean {
     return this.authorize(_, context)
   }
 }

package/source/directives/auth/Anyone.ts

@@ -3,15 +3,15 @@ import { type Directive, type Context } from './types.js'
 export class Anyone implements Directive {
   private readonly allow: boolean
 
-  public constructor (allow: boolean) {
+  public constructor(allow: boolean) {
     this.allow = allow
   }
 
-  public authorize (_: any, context: Context): boolean {
+  public authorize(_: any, context: Context): boolean {
     return context.identity !== null && this.allow
   }
 
-  public admits (_: any, context: Context): boolean {
+  public admits(_: any, context: Context): boolean {
     return this.authorize(_, context)
   }
 }

package/source/directives/auth/Assert.ts

@@ -7,26 +7,26 @@ import type { Context, Directive, Identity } from './types.js'
 export class Assert implements Directive {
   private readonly disabled: boolean
 
-  public constructor (enabled: boolean) {
-    assert.ok(typeof enabled === 'boolean', '`auth:assert` directive value must be a boolean')
+  public constructor(enabled: boolean) {
+    assert.ok(
+      typeof enabled === 'boolean',
+      '`auth:assert` directive value must be a boolean'
+    )
 
     this.disabled = !enabled
   }
 
-  public async authorize (identity: Identity | null, context: Context): Promise<boolean> {
-    if (!this.disabled)
-      await this.incept(context, identity)
+  public async authorize(identity: Identity | null, context: Context): Promise<boolean> {
+    if (!this.disabled) await this.incept(context, identity)
 
     return false
   }
 
-  private async incept (context: Context, identity: Identity | null): Promise<void> {
-    if (context.request.headers.authorization === undefined)
-      throw new http.Unauthorized()
+  private async incept(context: Context, identity: Identity | null): Promise<void> {
+    if (context.request.headers.authorization === undefined) throw new http.Unauthorized()
 
     if (identity === null) {
-      if (!Incept.acceptable(context))
-        throw new http.Unauthorized()
+      if (!Incept.acceptable(context)) throw new http.Unauthorized()
 
       context.identity = await Incept.incept(context, newid())
 

package/source/directives/auth/Authorization.ts

@@ -52,7 +52,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
   private meter: Quotas | null = null
   private sync: Sync | null = null
 
-  public mount (host: Host, options: http.Options): void {
+  public mount(host: Host, options: http.Options): void {
     this.sync?.dispose()
     this.sync = null
     this.meter = null
@@ -60,8 +60,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     const bouncer = options.bouncer
 
     // keyed by address, which is the deployment's to name, so off until it is set
-    if (bouncer === undefined)
-      return
+    if (bouncer === undefined) return
 
     this.meter = new Quotas({
       keys: Keys.create([{ method: 'ip', options: BOUNCER }]),
@@ -75,29 +74,35 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     this.sync.register(this.meter)
   }
 
-  public dispose (): void {
+  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`)
+  public create(name: string, value: any, remotes: Remotes): Directive {
+    assert.ok(name in constructors, `Directive 'auth:${name}' is not implemented`)
 
     const Class = constructors[name]
 
     for (const name of REMOTES)
       this.discovery[name] ??= remotes.discover('identity', name)
 
-    return match(Class,
-      Role, () => new Role(value as string | string[], this.discovery.roles),
-      Rule, () => new Rule(value as Record<string, string>, this.create.bind(this)),
-      Input, () => new Input(value as Declaration[], this.create.bind(this)),
-      Incept, () => new Incept(value as string, this.discovery),
-      Delegate, () => new Delegate(value as string, this.discovery.roles),
-      () => new Class(value))
+    return match(
+      Class,
+      Role,
+      () => new Role(value as string | string[], this.discovery.roles),
+      Rule,
+      () => new Rule(value as Record<string, string>, this.create.bind(this)),
+      Input,
+      () => new Input(value as Declaration[], this.create.bind(this)),
+      Incept,
+      () => new Incept(value as string, this.discovery),
+      Delegate,
+      () => new Delegate(value as string, this.discovery.roles),
+      () => new Class(value)
+    )
   }
 
-  public arrange (directives: Directive[]): void {
+  public arrange(directives: Directive[]): void {
     directives.sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1))
   }
 
@@ -105,28 +110,26 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
    * Authentication: who the credential names, if one is presented. A credential belongs to
    * the request, so it is read once however many calls the request carries.
    */
-  public async preflight (context: Context): Promise<void> {
+  public async preflight(context: Context): Promise<void> {
     context.identity = await this.resolve(context)
   }
 
   /** Authorization: whether that identity may make this call, which every call asks anew. */
-  public async precall (directives: Directive[],
+  public async precall(
+    directives: Directive[],
     context: Context,
-    parameters: Parameter[]): Promise<Output> {
+    parameters: Parameter[]
+  ): Promise<Output> {
     for (const directive of directives) {
       const allow = await directive.authorize(context.identity, context, parameters)
 
       if (allow)
-        if (this.permitted(context))
-          return directive.reply?.(context) ?? null
-        else
-          throw new http.Forbidden()
+        if (this.permitted(context)) return directive.reply?.(context) ?? null
+        else throw new http.Forbidden()
     }
 
-    if (context.identity === null)
-      throw new http.Unauthorized()
-    else
-      throw new http.Forbidden()
+    if (context.identity === null) throw new http.Unauthorized()
+    else throw new http.Forbidden()
   }
 
   /**
@@ -142,8 +145,11 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
    * admission is a disjunction and stops at the first that admits, while what the directives
    * fill is not any one of them's to state alone.
    */
-  public async explain (directives: Directive[], context: Context,
-    introspection: Introspection): Promise<Introspection | null> {
+  public async explain(
+    directives: Directive[],
+    context: Context,
+    introspection: Introspection
+  ): Promise<Introspection | null> {
     let untold = false
     let admitted = false
 
@@ -163,8 +169,7 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
       }
     }
 
-    if (!admitted && !untold)
-      return null
+    if (!admitted && !untold) return null
 
     // whichever of them admitted, a property any of them fills from the identity is filled
     // from the identity: what a caller sent there would be overwritten or forged
@@ -174,35 +179,36 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     return introspection
   }
 
-  public async settle (directives: Directive[],
+  public async settle(
+    directives: Directive[],
     context: Context,
-    response: http.OutgoingMessage): Promise<void> {
-    await Promise.all(directives.map(async (directive) =>
-      directive.settle?.(context, response)))
+    response: http.OutgoingMessage
+  ): Promise<void> {
+    await Promise.all(
+      directives.map(async (directive) => directive.settle?.(context, response))
+    )
   }
 
   /**
    * Re-issuing a credential, and refusing a ban, are the request's business: the header
    * carries one token however many calls were made, and a ban refuses all of them.
    */
-  public async depart (context: Context, response: http.OutgoingMessage): Promise<void> {
+  public async depart(context: Context, response: http.OutgoingMessage): Promise<void> {
     const identity = context.identity
 
-    if (identity === null)
-      return
+    if (identity === null) return
 
-    if (identity.provider === PRIMARY && !identity.refresh)
-      return
+    if (identity.provider === PRIMARY && !identity.refresh) return
 
-    if (await this.banned(identity))
+    // resolving already asked, for any provider but the primary
+    if (context.vetted !== true && (await this.banned(identity)))
       throw new http.Unauthorized()
 
     // 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.provider === PRIMARY)
       identity.roles = await Role.get(identity, this.discovery.roles)
-    else
-      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', {
@@ -216,17 +222,15 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     response.headers.set('cache-control', 'no-store')
   }
 
-  private async resolve (context: Context): Promise<Identity | null> {
+  private async resolve(context: Context): Promise<Identity | null> {
     const { authority } = context
     const { authorization } = context.request.headers
 
-    if (authorization === undefined)
-      return null
+    if (authorization === undefined) return null
 
     const retry = this.meter?.check(context, NONE) ?? 0
 
-    if (retry > 0)
-      throw new http.TooManyRequests(retry)
+    if (retry > 0) throw new http.TooManyRequests(retry)
 
     const [scheme, credentials] = split(authorization)
     const candidates = providersOf(scheme)
@@ -242,16 +246,18 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     for (const candidate of candidates) {
       this.components[candidate] ??= await this.discovery[candidate]
 
-      const answer = await this.components[candidate]!.invoke<AuthenticationResult>('authenticate', {
-        input: {
-          scheme,
-          authority,
-          credentials
+      const answer = await this.components[candidate]!.invoke<AuthenticationResult>(
+        'authenticate',
+        {
+          input: {
+            scheme,
+            authority,
+            credentials
+          }
         }
-      })
+      )
 
-      if (declined(answer))
-        continue
+      if (declined(answer)) continue
 
       provider = candidate
       result = answer
@@ -275,7 +281,11 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
 
     const identity = result.identity
 
-    if (provider !== PRIMARY && (await this.banned(identity))) throw new http.Unauthorized()
+    if (provider !== PRIMARY) {
+      if (await this.banned(identity)) throw new http.Unauthorized()
+
+      context.vetted = true
+    }
 
     identity.scheme = scheme
     identity.provider = provider!
@@ -284,17 +294,16 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
     return identity
   }
 
-  private permitted (context: Context): boolean {
+  private permitted(context: Context): boolean {
     const permissions = context.identity?.permissions
 
-    if (permissions === undefined)
-      return true
+    if (permissions === undefined) return true
 
     // 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> {
+  private async banned(identity: Identity): Promise<boolean> {
     this.bans ??= await this.discovery.bans
 
     const ban = await this.bans.invoke<Ban>('observe', { query: { id: identity.id } })
@@ -304,21 +313,27 @@ export class Authorization implements DirectiveFamily<Directive, Extension> {
 }
 
 /** Whether a provider says the credentials are not of its kind, so the next is asked. */
-function declined (result: AuthenticationResult): boolean {
+function declined(result: AuthenticationResult): boolean {
   return result instanceof Error && codeOf(result) === UNRECOGNIZED
 }
 
-function codeOf (result: Error): string | undefined {
+function codeOf(result: Error): string | undefined {
   const code: string | unknown = (result as unknown as { code: string }).code
 
   return typeof code === 'string' ? code : undefined
 }
 
 /** 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))
+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)
+  )
 }
 
 /**
@@ -326,12 +341,11 @@ export function permits (permissions: Record<string, string[]>, method: string,
  * matched on every request the identity makes. Patterns arrive with an identity, hence
  * the bound.
  */
-function glob (pattern: string): Minimatch {
+function glob(pattern: string): Minimatch {
   let compiled = GLOBS.get(pattern)
 
   if (compiled === undefined) {
-    if (GLOBS.size >= GLOBS_LIMIT)
-      GLOBS.clear()
+    if (GLOBS.size >= GLOBS_LIMIT) GLOBS.clear()
 
     compiled = new Minimatch(pattern)
 

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

@@ -4,7 +4,7 @@ import { Delegate } from './Delegate.js'
 import type { Introspection } from '../../Introspection.js'
 
 describe('auth:delegate', () => {
-  function explanation (): Introspection {
+  function explanation(): Introspection {
     return {
       input: {
         type: 'object',
@@ -20,7 +20,7 @@ describe('auth:delegate', () => {
   it('should take the property it embeds out of the input', () => {
     const delegate = new Delegate('identity', null as never)
     const described = delegate.describe(explanation())
-    const input = described.input as { properties: object, required: string[] }
+    const input = described.input as { properties: object; required: string[] }
 
     assert.deepStrictEqual(Object.keys(input.properties), ['title'])
     assert.deepStrictEqual(input.required, ['title'])

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 }
   }
 }