@owlmeans/server-api 0.1.18-rc.32 → 0.1.18-rc.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.32",
+  "version": "0.1.18-rc.34",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -33,15 +33,15 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.28",
-    "@owlmeans/auth": "^0.1.18-rc.26",
-    "@owlmeans/auth-common": "^0.1.18-rc.28",
-    "@owlmeans/context": "^0.1.18-rc.24",
-    "@owlmeans/error": "^0.1.18-rc.26",
-    "@owlmeans/entrypoint": "^0.1.18-rc.27",
-    "@owlmeans/route": "^0.1.18-rc.25",
-    "@owlmeans/server-context": "^0.1.18-rc.27",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.26",
+    "@owlmeans/api": "^0.1.18-rc.30",
+    "@owlmeans/auth": "^0.1.18-rc.28",
+    "@owlmeans/auth-common": "^0.1.18-rc.30",
+    "@owlmeans/context": "^0.1.18-rc.26",
+    "@owlmeans/error": "^0.1.18-rc.28",
+    "@owlmeans/entrypoint": "^0.1.18-rc.29",
+    "@owlmeans/route": "^0.1.18-rc.27",
+    "@owlmeans/server-context": "^0.1.18-rc.29",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.28",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
     "fastify-raw-body": "^5.0.0",

package/src/server.ts

@@ -8,6 +8,7 @@ import { RouteMethod } from '@owlmeans/route'
 import { createServerHandler, fixFormatDates } from './utils/index.js'
 import { provideResponse } from '@owlmeans/entrypoint'
 import { TOKEN_UPDATE } from '@owlmeans/auth-common'
+import { INCIDENT_ID_HEADER } from './utils/error.js'
 
 import Fastify from 'fastify'
 import type { FastifyRequest } from 'fastify'
@@ -99,7 +100,7 @@ export const createApiServer = (alias: string): ApiServer => {
         ...Object.values(RouteMethod).map(method => method.toUpperCase()),
         'HEAD', 'OPTIONS'
       ],
-      exposedHeaders: [TOKEN_UPDATE]
+      exposedHeaders: [TOKEN_UPDATE, INCIDENT_ID_HEADER]
     })
 
     await server.register(Multipart, {
@@ -199,4 +200,3 @@ export const appendApiServer = <C extends Config, T extends ServerContext<C>>(
 
   return context
 }
-

package/src/types.ts

@@ -18,7 +18,20 @@ export interface ApiServerAppend {
   getApiServer: () => ApiServer
 }
 
-export interface Config extends ServerConfig { }
+export type HttpErrorExposure = 'production' | 'development'
+
+export interface HttpErrorsConfig {
+  /** Production is the safe default; development is the only mode that exposes stacks. */
+  exposure?: HttpErrorExposure
+}
+
+export interface HttpConfig {
+  errors?: HttpErrorsConfig
+}
+
+export interface Config extends ServerConfig {
+  http?: HttpConfig
+}
 
 export interface Context<C extends Config = Config> extends ServerContext<C>,
   ApiServerAppend { }

package/src/utils/error.ts

@@ -2,34 +2,205 @@ import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api
 import type { FastifyReply } from 'fastify'
 import { AccessError, AuthFailedError } from '../errors.js'
 import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
-import { ResilientError } from '@owlmeans/error'
+import { isResilientError, ResilientError, SEPARATOR } from '@owlmeans/error'
+import { randomUUID } from 'node:crypto'
+import type { Config, HttpErrorExposure } from '../types.js'
+
+export const INCIDENT_ID_HEADER = 'X-Incident-ID'
+
+/**
+ * What an error class may declare about the HTTP status it is answered with.
+ *
+ * Structural on purpose: the classes that declare it live in packages that must not depend on an
+ * HTTP server (`@owlmeans/payment`, a product's contract package), so they write a plain
+ * `public static httpStatus = 409` and nothing imports this type.
+ */
+export interface HttpStatusDeclaration {
+  httpStatus?: unknown
+  /** Explicit opt-in for a declared 5xx response. Client-error declarations need no opt-in. */
+  allowServerErrorStatus?: unknown
+}
+
+const CLIENT_ERROR_FIRST = 400
+const CLIENT_ERROR_LAST = 499
+const SERVER_ERROR_FIRST = 500
+const SERVER_ERROR_LAST = 599
+
+/**
+ * The HTTP status an error's class declares, or `null` when it declares none that may be honoured.
+ *
+ * Read through the constructor chain — a static property is inherited, so a subclass answers what
+ * its nearest declaring ancestor says, and redeclares to change it. An integer 4xx is honoured
+ * directly. A 5xx is honoured only with `allowServerErrorStatus = true`, so a domain class must
+ * explicitly opt in to exposing a precise availability response. The read is structural, so a
+ * class from a duplicate module copy declares exactly what the imported one does.
+ */
+export const declaredErrorStatus = (error: unknown): number | null => {
+  if (error == null || typeof error !== 'object') {
+    return null
+  }
+  const declaration = error.constructor as HttpStatusDeclaration | undefined
+  const status = declaration?.httpStatus
+  if (typeof status !== 'number' || !Number.isInteger(status)) {
+    return null
+  }
+  if (status >= CLIENT_ERROR_FIRST && status <= CLIENT_ERROR_LAST) return status
+  if (status >= SERVER_ERROR_FIRST && status <= SERVER_ERROR_LAST
+    && declaration?.allowServerErrorStatus === true) return status
+
+  return null
+}
+
+/**
+ * The registered type names an error carries: its own `type`, and the static `typeName` of every
+ * class on its constructor chain.
+ *
+ * This is how a class is recognised when `instanceof` cannot see it. A process that loads a package
+ * twice — `bun --preserve-symlinks` over a linked workspace resolves one package through several
+ * `node_modules` paths — holds several copies of every error class, and an error built by one copy
+ * is not an instance of another. The registered names are the same in every copy. A subclass's
+ * `typeName` does not reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`), so
+ * a family is recognised by walking the chain and matching names exactly, never by a substring.
+ */
+const typeNamesOf = (error: object): Set<string> => {
+  const names = new Set<string>()
+  const type = (error as { type?: unknown }).type
+  if (typeof type === 'string') {
+    names.add(type)
+  }
+  let ctor: unknown = error.constructor
+  while (typeof ctor === 'function') {
+    const name = (ctor as { typeName?: unknown }).typeName
+    if (typeof name === 'string') {
+      names.add(name)
+    }
+    ctor = Object.getPrototypeOf(ctor)
+  }
+
+  return names
+}
+
+const isOfFamily = (names: Set<string>, family: string[]): boolean =>
+  family.some(typeName => names.has(typeName))
 
 /**
- * Map a thrown error onto an HTTP status.
+ * The HTTP status an error is answered with, read off the error exactly as given.
  *
  * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
  * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
  * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
  * one answers 500, which reports a refused request as a crashed server: the client cannot tell
  * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
- * application fell over.
+ * application fell over. A family member is recognised by class OR by registered type name
+ * ({@link typeNamesOf}), so a class from a duplicate module copy answers the same status.
  *
  * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
- * tested first or every refusal of a permission is reported as a failure to authenticate.
+ * tested first or every refusal of a permission is reported as a failure to authenticate. Both
+ * auth branches come before a class's own declaration, so an auth refusal can never be restated
+ * as something else. Everything that is neither an auth error nor a class declaring an allowed
+ * {@link declaredErrorStatus} answers 500.
  */
-export const handleError = (error: Error, reply: FastifyReply) => {
-  let code: number = SERVER_ERROR
-  if (error instanceof AuthForbidden || error instanceof AccessError) {
+export const errorStatus = (error: unknown): number => {
+  if (error == null || typeof error !== 'object') {
+    return SERVER_ERROR
+  }
+  const names = typeNamesOf(error)
+  if (error instanceof AuthForbidden || error instanceof AccessError
+    || isOfFamily(names, [AuthForbidden.typeName, AccessError.typeName])) {
     // An established identity that lacks the permission. Re-authenticating changes nothing.
-    code = FORBIDDEN_ERROR
-  } else if (error instanceof AuthorizationError || error instanceof AuthFailedError) {
+    return FORBIDDEN_ERROR
+  }
+  if (error instanceof AuthorizationError || error instanceof AuthFailedError
+    || isOfFamily(names, [AuthorizationError.typeName, AuthFailedError.typeName])) {
     // No usable credential — absent, expired, revoked, or naming a session this server no longer
     // holds. The caller is told to sign in, not that signing in would not help.
-    code = UNAUTHORIZED_ERROR
+    return UNAUTHORIZED_ERROR
+  }
+
+  return declaredErrorStatus(error) ?? SERVER_ERROR
+}
+
+export interface SerializedHttpError {
+  status: number
+  body: string
+  incidentId: string
+}
+
+/** Invalid or absent configuration always resolves to the production-safe policy. */
+export const errorExposure = (config?: Pick<Config, 'http'>): HttpErrorExposure =>
+  config?.http?.errors?.exposure === 'development' ? 'development' : 'production'
+
+/**
+ * Preserve a typed/marshalled error when possible without asking `ensure` to convert a plain
+ * error. In particular, `ensure` deliberately rethrows SyntaxError; an HTTP boundary still has
+ * to serialize it safely and let the incident log retain the original object.
+ */
+const normalizeForWire = (error: Error): Error => {
+  if (error instanceof SyntaxError || isResilientError(error)) {
+    return error
+  }
+  if (error.message.includes(SEPARATOR)) {
+    const ensured = ResilientError.ensure(error)
+    // The catch-all converter's legacy constructor shape shifts an ordinary error's fields.
+    // Only keep `ensure`'s result when a registered wire prefix actually rebuilt something.
+    if (ensured.type !== error.message || ensured.message !== error.stack) {
+      return ensured
+    }
   }
+  return error
+}
+
+/** One central wire shape for every server error. */
+export const serializeError = (
+  error: Error, exposure: HttpErrorExposure = 'production'
+): SerializedHttpError => {
+  const normalized = normalizeForWire(error)
+  const thrown = errorStatus(error)
+  const status = thrown !== SERVER_ERROR ? thrown : errorStatus(normalized)
+  const incidentId = randomUUID()
+  // The server log owns every diagnostic. Production callers receive only its correlation key;
+  // development keeps the typed wire form so local clients can retain their usual error details.
+  Object.assign(error, { incidentId })
+  if (isResilientError(normalized)) normalized.incidentId = incidentId
+  const body = exposure === 'production'
+    ? incidentId
+    : ResilientError.marshal(normalized, { includeStack: true, incidentId }).message
+
+  return { status, body, incidentId }
+}
+
+/** Apply safe response metadata carried by an error without coupling its package to Fastify. */
+export const applyErrorHeaders = (error: unknown, reply: FastifyReply): void => {
+  if (error == null || typeof error !== 'object') {
+    return
+  }
+  const retryAfter = (error as { retryAfter?: unknown }).retryAfter
+  if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0) {
+    reply.header('Retry-After', String(Math.ceil(retryAfter)))
+  }
+}
+
+/**
+ * Answer a thrown error: a status, and the marshalled `ResilientError` as the body.
+ *
+ * The status is resolved in two steps. The error AS THROWN comes first: it is the one object whose
+ * class is certainly the class that was raised, while `ResilientError.ensure` rebuilds through the
+ * registry of whichever `@owlmeans/error` copy this module loaded — under duplicate module copies
+ * that turns a perfectly recognisable auth refusal into a plain `ResilientError` answering 500.
+ * Only when the thrown error answers 500 is the ENSURED error asked, because the rebuild is what
+ * gives a status to a marshalled error that crossed a hop as a plain `Error`.
+ */
+export const handleError = (
+  error: Error, reply: FastifyReply, exposure: HttpErrorExposure = 'production'
+) => {
   if (!reply.sent) {
-    reply.code(code).send(
-      ResilientError.marshal(ResilientError.ensure(error as Error)).message
-    )
+    const serialized = serializeError(error, exposure)
+    applyErrorHeaders(error, reply)
+    // Fastify/Pino's `err` serializer retains the original type, message and full stack. This is
+    // the one log entry that owns those details in production, keyed by the response incident ID.
+    reply.log.error({ err: error, incidentId: serialized.incidentId }, 'Request failed')
+    reply.header(INCIDENT_ID_HEADER, serialized.incidentId)
+      .code(serialized.status)
+      .send(serialized.body)
   }
 }

package/src/utils/payload.ts

@@ -1,8 +1,9 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { AbstractResponse, AbstractRequest } from '@owlmeans/entrypoint'
 import type { Request, Response } from '../types.js'
-import { ACCEPTED, CREATED, OK, SERVER_ERROR } from '@owlmeans/api'
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api'
 import type { AnySchemaObject } from 'ajv'
+import { handleError } from './error.js'
 
 export const provideRequest = (alias: string, req: Request, provision?: boolean): AbstractRequest => {
   provision = provision ?? false
@@ -35,7 +36,7 @@ export const executeResponse = <T>(response: AbstractResponse<T>, reply: Respons
     if (throwOnError ?? false) {
       throw response.error
     }
-    reply.code(SERVER_ERROR).send(response.error.message)
+    handleError(response.error, reply)
     return true
   } else if (response.outcome != null) {
     switch (response.outcome) {

package/src/utils/server.ts

@@ -5,15 +5,16 @@ import type { FixerService, ServerEntrypoint } from '@owlmeans/server-entrypoint
 import type { CommonEntrypoint } from '@owlmeans/entrypoint'
 import type { GateService } from '@owlmeans/entrypoint'
 import { provideResponse } from '@owlmeans/entrypoint'
-import type { ServerContext, ServerConfig } from '@owlmeans/server-context'
+import type { ServerContext } from '@owlmeans/server-context'
 import { ResilientError } from '@owlmeans/error'
 import { OK } from '@owlmeans/api'
-import { handleError } from './error.js'
+import { errorExposure, handleError } from './error.js'
 import { executeResponse, provideRequest } from './payload.js'
 import { authorize } from './guards.js'
 import { RouteProtocols } from '@owlmeans/route'
+import type { Config as ApiConfig } from '../types.js'
 
-type Config = ServerConfig
+type Config = ApiConfig
 type Context = ServerContext<Config>
 
 export const canServeModule = (context: Context, module: CommonEntrypoint): module is ServerEntrypoint<unknown> => {
@@ -23,10 +24,9 @@ export const canServeModule = (context: Context, module: CommonEntrypoint): modu
   if (module.route.route.service != null && module.route.route.service !== context.cfg.service) {
     return false
   }
-  // Only the protocols HTTP actually carries. A socket is upgraded elsewhere and a queued job is
-  // taken off the broker by the worker — mounting either on the HTTP server would answer it twice.
-  if (module.route.route.protocol === RouteProtocols.SOCKET
-    || module.route.route.protocol === RouteProtocols.QUEUE) {
+  // HTTP serves only its own protocol. Custom transports are handled by their owning packages.
+  if (module.route.route.protocol != null
+    && module.route.route.protocol !== RouteProtocols.WEB) {
     return false
   }
 
@@ -66,14 +66,11 @@ export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, lo
         reply.code(OK).send(response.value)
       }
     } catch (error) {
-      console.error(`Error in ${module.alias} (${location})`)
-      console.error(JSON.stringify(error, null, 2))
-      console.error(error)
       if (module.fixer != null) {
         const fixer: FixerService = context.service(module.fixer)
         fixer.handle(reply, ResilientError.ensure(error as Error))
         return
       }
-      handleError(error as Error, reply)
+      handleError(error as Error, reply, errorExposure(context.cfg))
     }
   }

package/tests/error-status.spec.ts

@@ -0,0 +1,290 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import Fastify from 'fastify'
+import type { FastifyInstance } from 'fastify'
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
+import { ResilientError, SEPARATOR } from '@owlmeans/error'
+import { provideResponse } from '@owlmeans/entrypoint'
+import { errorExposure, errorStatus, handleError, INCIDENT_ID_HEADER } from '../src/utils/error.js'
+import { executeResponse } from '../src/utils/payload.js'
+import { AccessError, AuthFailedError } from '../src/errors.js'
+
+class OutOfCredit extends ResilientError {
+  public static override typeName = 'ServerApiSpecOutOfCredit'
+  public static httpStatus = 402
+
+  constructor(message: string = 'error') {
+    super(OutOfCredit.typeName, `out-of-credit:${message}`)
+  }
+}
+
+/** Inherits 402 without redeclaring it. */
+class OutOfCreditForStory extends OutOfCredit {
+  public static override typeName = 'ServerApiSpecOutOfCreditForStory'
+
+  constructor() {
+    super('story')
+    this.type = OutOfCreditForStory.typeName
+  }
+}
+
+/** Redeclares its parent's status to a conflict. */
+class Busy extends OutOfCredit {
+  public static override typeName = 'ServerApiSpecBusy'
+  public static override httpStatus = 409
+
+  constructor() {
+    super('busy')
+    this.type = Busy.typeName
+  }
+}
+
+/** An auth refusal that also declares a status: the auth mapping still wins. */
+class DeclaringForbidden extends AuthForbidden {
+  public static override typeName = 'ServerApiSpecDeclaringForbidden'
+  public static httpStatus = 402
+
+  constructor() {
+    super('declaring')
+    this.type = DeclaringForbidden.typeName
+  }
+}
+
+class TemporarilyUnavailable extends ResilientError {
+  public static override typeName = 'ServerApiSpecTemporarilyUnavailable'
+  public static httpStatus = 503
+  public static allowServerErrorStatus = true
+
+  constructor() {
+    super(TemporarilyUnavailable.typeName, 'temporarily-unavailable')
+  }
+}
+
+class Throttled extends ResilientError {
+  public static override typeName = 'ServerApiSpecThrottled'
+  public static httpStatus = 429
+  public readonly retryAfter = 17.2
+
+  constructor() {
+    super(Throttled.typeName, 'throttled')
+  }
+}
+
+const declaring = (typeName: string, httpStatus: unknown) => {
+  class Declaring extends ResilientError {
+    public static override typeName = typeName
+    public static httpStatus = httpStatus
+
+    constructor(message: string = 'error') {
+      super(typeName, message)
+    }
+  }
+  return Declaring
+}
+
+/**
+ * A duplicate module copy of the error family — what a process loading `@owlmeans/error` through
+ * several `node_modules` paths holds: the same registered names, none of the imported classes.
+ */
+class ForeignResilientError extends Error {
+  public static typeName = 'ResilientError'
+  public type: string
+
+  constructor(type: string, message: string) {
+    super(message)
+    this.type = type
+  }
+}
+
+class ForeignAuthFailedError extends ForeignResilientError {
+  public static override typeName = 'AuthFailedError'
+
+  constructor() {
+    super(ForeignAuthFailedError.typeName, 'api:auth:error')
+  }
+}
+
+class ForeignAuthorizationError extends ForeignResilientError {
+  public static override typeName = 'AuthorizationError'
+
+  constructor(message: string = 'error') {
+    super(ForeignAuthorizationError.typeName, `auth:authorization:${message}`)
+  }
+}
+
+class ForeignAuthForbidden extends ForeignAuthorizationError {
+  public static override typeName = 'ForbiddenAuthorizationError'
+
+  constructor(message: string = 'error') {
+    super(`forbidden:${message}`)
+    this.type = ForeignAuthForbidden.typeName
+  }
+}
+
+/** A subclass whose own name embeds nothing of its parent's, like `EntitlementRefusal`. */
+class ForeignEntitlementRefusal extends ForeignAuthForbidden {
+  public static override typeName = 'EntitlementRefusal'
+
+  constructor() {
+    super('entitlement')
+    this.type = ForeignEntitlementRefusal.typeName
+  }
+}
+
+/** A declared refusal no registry of this process knows. */
+class ForeignOutOfCredit extends ForeignResilientError {
+  public static override typeName = 'ServerApiSpecForeignOutOfCredit'
+  public static httpStatus = 402
+
+  constructor() {
+    super(ForeignOutOfCredit.typeName, 'out-of-credit:foreign')
+  }
+}
+
+const typed = (type: string) => Object.assign(new Error('typed'), { type })
+
+ResilientError.registerErrorClass(OutOfCredit)
+ResilientError.registerErrorClass(OutOfCreditForStory)
+ResilientError.registerErrorClass(Busy)
+ResilientError.registerErrorClass(DeclaringForbidden)
+
+let server: FastifyInstance
+let thrown: unknown
+
+beforeAll(async () => {
+  server = Fastify()
+  server.get('/handle', async (_req, reply) => {
+    handleError(thrown as Error, reply)
+    return reply
+  })
+  server.get('/handle-development', async (_req, reply) => {
+    handleError(thrown as Error, reply, 'development')
+    return reply
+  })
+  server.get('/execute', async (_req, reply) => {
+    const response = provideResponse(reply)
+    response.reject(thrown as Error)
+    executeResponse(response, reply)
+    return reply
+  })
+  await server.ready()
+})
+
+afterAll(async () => {
+  await server.close()
+})
+
+const answer = async (error: unknown, path: string = '/handle') => {
+  thrown = error
+  const reply = await server.inject({ method: 'GET', url: path })
+  return {
+    status: reply.statusCode,
+    body: reply.body,
+    incidentId: reply.headers[INCIDENT_ID_HEADER.toLowerCase()],
+    retryAfter: reply.headers['retry-after'],
+  }
+}
+
+describe('@owlmeans/server-api — production error exposure', () => {
+  test('returns only an incident id in production and correlates it with the header', async () => {
+    const response = await answer(new Error('private-marker'))
+    expect(response.body).toBe(response.incidentId)
+    expect(response.body).not.toContain('private-marker')
+    expect(response.body).not.toContain(SEPARATOR)
+    expect(response.body).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/)
+  })
+
+  test('includes stacks only under explicit development exposure and safely serializes SyntaxError', async () => {
+    const development = await answer(new Error('development-marker'), '/handle-development')
+    const [type, message, stack, incidentId] = development.body.split(SEPARATOR, 4)
+    expect(type).toBe(ResilientError.typeName)
+    expect(message).toBe('development-marker')
+    expect(stack).toContain('development-marker')
+    expect(incidentId).toBe(development.incidentId)
+
+    const syntax = await answer(new SyntaxError('bad wiring'))
+    expect(syntax.status).toBe(500)
+    expect(syntax.body).toBe(syntax.incidentId)
+    expect(syntax.body).not.toContain('bad wiring')
+
+    expect(errorExposure()).toBe('production')
+    expect(errorExposure({ http: { errors: { exposure: 'development' } } })).toBe('development')
+  })
+})
+
+describe('@owlmeans/server-api — handleError status', () => {
+  test('keeps the auth mappings: forbidden 403, unauthenticated 401', async () => {
+    expect((await answer(new AuthForbidden('x'))).status).toBe(403)
+    expect((await answer(new AccessError())).status).toBe(403)
+    expect((await answer(new AuthorizationError('x'))).status).toBe(401)
+    expect((await answer(new AuthFailedError())).status).toBe(401)
+    expect((await answer(new DeclaringForbidden())).status).toBe(403)
+  })
+
+  test('honours a 4xx a class declares — inherited, redeclared, or after a marshal hop', async () => {
+    const refused = await answer(new OutOfCredit('create'))
+    expect(refused.status).toBe(402)
+    expect(refused.body).toBe(refused.incidentId)
+
+    expect((await answer(new OutOfCreditForStory())).status).toBe(402)
+    expect((await answer(new Busy())).status).toBe(409)
+    expect((await answer(ResilientError.marshal(new Busy()))).status).toBe(409)
+    expect((await answer(new ForeignOutOfCredit())).status).toBe(402)
+  })
+
+  test('answers 500 for no declaration, or one outside the client-error range', async () => {
+    expect((await answer(new ResilientError('Plain', 'plain'))).status).toBe(500)
+    expect((await answer(new Error('boom'))).status).toBe(500)
+    for (const status of [500, 503, 200, 302, 399, 600, 402.5, '402', null]) {
+      const Declaring = declaring(`ServerApiSpecDeclaring${String(status)}`, status)
+      expect((await answer(new Declaring())).status).toBe(500)
+    }
+    for (const type of ['AuthFailedErrorX', 'NotAuthorizationError', 'Forbidden', 'ResilientError']) {
+      expect((await answer(typed(type))).status).toBe(500)
+      expect((await answer(new ForeignResilientError(type, 'near-miss'))).status).toBe(500)
+    }
+  })
+
+  test('honours an explicitly exposed 5xx without opening arbitrary server statuses', async () => {
+    expect((await answer(new TemporarilyUnavailable())).status).toBe(503)
+    const Unexposed = declaring('ServerApiSpecUnexposed503', 503)
+    expect((await answer(new Unexposed())).status).toBe(500)
+  })
+
+  test('emits Retry-After for a throttled response', async () => {
+    const response = await answer(new Throttled())
+    expect(response.status).toBe(429)
+    expect(response.retryAfter).toBe('18')
+  })
+
+  test('executeResponse answers a rejected response with the same status', async () => {
+    expect((await answer(new OutOfCredit('create'), '/execute')).status).toBe(402)
+    expect((await answer(new AuthForbidden('x'), '/execute')).status).toBe(403)
+    expect((await answer(new ResilientError('Plain', 'plain'), '/execute')).status).toBe(500)
+  })
+})
+
+describe('@owlmeans/server-api — auth status across a rebuild and duplicate module copies', () => {
+  test('an AuthFailedError answers 401 as thrown and after a marshal round trip', async () => {
+    expect((await answer(new AuthFailedError())).status).toBe(401)
+    expect((await answer(ResilientError.marshal(new AuthFailedError()))).status).toBe(401)
+    expect(errorStatus(ResilientError.ensure(ResilientError.marshal(new AuthFailedError())))).toBe(401)
+    expect((await answer(new AuthFailedError(), '/execute')).status).toBe(401)
+  })
+
+  test('a class from another module copy answers by its registered type name', async () => {
+    // The rebuild alone loses it — the regression this resolution exists for.
+    expect(errorStatus(ResilientError.ensure(new ForeignAuthFailedError()))).toBe(500)
+    expect((await answer(new ForeignAuthFailedError())).status).toBe(401)
+    expect((await answer(new ForeignAuthorizationError())).status).toBe(401)
+    expect((await answer(new ForeignAuthForbidden())).status).toBe(403)
+    expect((await answer(new ForeignAuthForbidden(), '/execute')).status).toBe(403)
+  })
+
+  test('the family is read off the instance type or the constructor chain, 403 before 401', async () => {
+    expect((await answer(typed('AuthFailedError'))).status).toBe(401)
+    expect((await answer(typed('ForbiddenAuthorizationError'))).status).toBe(403)
+    expect((await answer(typed('AccessAuthFailedError'))).status).toBe(403)
+    // Its own type names nothing of the family; only the chain does.
+    expect((await answer(new ForeignEntitlementRefusal())).status).toBe(403)
+  })
+})