@owlmeans/server-api 0.1.18-rc.3 → 0.1.18-rc.31

package/src/hold.ts

@@ -0,0 +1,84 @@
+import Fastify from 'fastify'
+import type { ServerConfig } from '@owlmeans/server-context'
+import { CLOSED_HOST, OPENED_HOST, PORT } from './consts.js'
+
+export interface ApiPortHoldOptions {
+  /**
+   * The one path answered 200 while the hold is in place — the app's health endpoint, so
+   * whatever supervises the process keeps a conventional liveness answer through the boot.
+   * Everything else answers 503 with the same body. Absent, everything is 503.
+   */
+  okPath?: string
+  /** Body of every answer, evaluated per request so a changing boot phase is reported live. */
+  payload?: () => unknown
+}
+
+export interface ApiPortHold {
+  /**
+   * Free the port for the real server. Awaits the actual close — `listen()` follows immediately,
+   * and a predecessor still bound makes it throw — and force-closes keep-alive sockets, so a
+   * supervisor's own poller cannot hold the release open.
+   */
+  release: () => Promise<void>
+}
+
+/**
+ * Own the app's port while the context initializes, and answer for the app until `listen()`
+ * takes over.
+ *
+ * The API server itself cannot do this: it builds its route table from the entrypoints the
+ * context knows about, so it can only bind AFTER `init()` resolves — and Fastify refuses new
+ * routes once it is listening. Without a hold, the whole boot window, and every way a boot can
+ * fail, leaves nothing on the port; the edge then answers a bare upstream connect error that
+ * names neither the app nor the reason, which is indistinguishable from a crashed pod or an app
+ * that was never installed.
+ *
+ * So the boot sequence an app wants is:
+ *
+ *     const hold = await holdApiPort(cfg, { okPath, payload })   // bind FIRST
+ *     try { ...initialize... } catch { record the failure; return }  // hold keeps answering
+ *     await hold.release()
+ *     await context.getApiServer().listen()
+ *
+ * Everything that is not the health path answers **503, not 404**: the routes the app really
+ * serves do not exist yet, and "no such route" would be a lie that outlives the boot.
+ *
+ * The port and host are resolved exactly as `listen()` resolves them — from the service's own
+ * declaration in `cfg.services[cfg.service]` — so the hold and the server can never disagree
+ * about which socket they are trading.
+ *
+ * A bind failure here (EADDRINUSE above all) throws to the caller and must be treated as fatal:
+ * a process that continues past it ends the boot with nothing listening and nothing holding the
+ * event loop, i.e. a clean exit 0 while a predecessor keeps serving stale code. Name the error
+ * and exit non-zero — that is what makes a supervisor reclaim the port instead of respawning
+ * into it.
+ */
+export const holdApiPort = async (
+  cfg: ServerConfig, opts: ApiPortHoldOptions = {}
+): Promise<ApiPortHold> => {
+  const config = cfg.services[cfg.service]
+  const port = config?.internalPort ?? config?.port ?? PORT
+  const host = config?.opened === true ? OPENED_HOST : CLOSED_HOST
+
+  const payload = opts.payload ?? (() => ({ status: 'OK' }))
+
+  // Quiet and disposable: no logger, no plugins, and connections are force-closed on release so
+  // the handover to the real server is bounded rather than waiting out a keep-alive.
+  const server = Fastify({ logger: false, forceCloseConnections: true })
+
+  if (opts.okPath != null) {
+    server.all(opts.okPath, async (_request, reply) => {
+      return await reply.code(200).send(payload())
+    })
+  }
+  server.setNotFoundHandler(async (_request, reply) => {
+    return await reply.code(503).send(payload())
+  })
+
+  await server.listen({ port, host })
+  console.log(`api-server: holding ${host}:${port} for the boot${opts.okPath != null ? ` (${opts.okPath})` : ''}`)
+
+  return {
+    release: async () => { await server.close() },
+  }
+}

package/src/index.ts

@@ -4,3 +4,5 @@ export * from './server.js'
 export * from './consts.js'
 export * from './errors.js'
 export * from './helper.js'
+export * from './hold.js'
+export * from './protocol.js'

package/src/protocol.ts

@@ -0,0 +1,185 @@
+import { assertContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import type {
+  BodyOf, EntrypointProtocolDeclaration, HandlerRequest, OpenRequest, OpenValue, ParamsOf, RequestOf, ResponseOf,
+} from '@owlmeans/entrypoint'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+import { HandlerMisconfiguredError } from './errors.js'
+
+/**
+ * True for a response the declaration left with no compile-time contract: `typed<any>()` (an
+ * `[any] extends [X]` conditional does not produce `any`'s usual both-branches union once the
+ * checked type is wrapped in a tuple, so it resolves to a single branch like any other type) and
+ * a response inferred as bare `typed()` with nothing to infer from, which resolves to `undefined`
+ * with no shape to validate a handler's return against — the same signal a zero-argument
+ * `contract()` produces for a genuinely response-less route. Neither means "this handler must
+ * return void": it means the declaration did not constrain the response, so the handler is free to
+ * return whatever its route actually sends.
+ */
+type IsUntypedResponse<T> = 0 extends (1 & T) ? true : [T] extends [undefined] ? true : false
+
+/**
+ * The type a bound handler is allowed to return for a given protocol response.
+ *
+ * A concretely typed or schema-backed `Response` is returned unchanged — the handler must produce
+ * exactly that shape. An untyped one (see `IsUntypedResponse` above) relaxes to `any`: the
+ * declaration made no promise about the response, so nothing here should force a handler bound to
+ * it into returning `void`.
+ */
+type HandlerResponse<Response> = IsUntypedResponse<Response> extends true ? any : Response
+type MaybePromise<Value> = Value | Promise<Value>
+type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: OpenValue }
+  ? Protocol : never
+type ParamsProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: object }
+  ? Protocol : never
+
+interface ContextCarrier<Context> {
+  _ctx?: Context
+}
+
+const contextFor = <Context extends BasicContext<BasicConfig>>(
+  request: AbstractRequest,
+  fallback: Context,
+): Context => {
+  const original = request.original
+  if (original != null && typeof original === 'object' && '_ctx' in original) {
+    return (original as ContextCarrier<Context>)._ctx ?? fallback
+  }
+
+  return fallback
+}
+
+const bind = <Protocol extends EntrypointProtocolDeclaration, Context extends BasicContext<BasicConfig>>(
+  protocol: Protocol,
+  execute: (request: HandlerRequest<RequestOf<Protocol>>, context: Context) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+): BoundEntrypointHandler<Protocol> => ({
+  protocol,
+  bind: ref => async (request, response) => {
+    const fallback = assertContext<BasicConfig, Context>(ref.ref?.ctx, protocol.alias)
+
+    try {
+      const typedRequest = (request as HandlerRequest<OpenRequest>) as HandlerRequest<RequestOf<Protocol>>
+      const value = await execute(
+        typedRequest,
+        contextFor(request, fallback),
+      )
+      response.resolve(value as ResponseOf<Protocol>, EntrypointOutcome.Ok)
+    } catch (error) {
+      response.reject(error as Error)
+    }
+
+    return response.value
+  },
+})
+
+/** Structural, not `instanceof`: a `BoundEntrypointHandler` crosses no class boundary a runtime check could use. */
+type AnyBoundHandler = BoundEntrypointHandler<EntrypointProtocolDeclaration>
+
+/**
+ * `value` is shaped like a `BoundEntrypointHandler` — never a plain function, which also carries
+ * its own `.bind` and would otherwise pass a `typeof value.bind === 'function'` check alone.
+ */
+const isBoundHandler = (value: unknown): value is AnyBoundHandler =>
+  typeof value === 'object' && value != null
+  && typeof (value as { bind?: unknown }).bind === 'function'
+  && (value as { protocol?: unknown }).protocol != null
+
+const warnedAliases = new Set<string>()
+
+/**
+ * What `body`/`params`/`request` do with something that is not the plain callback they declare —
+ * the shape a handler module wraps its own export in when it is bound TWICE. `null` means the
+ * second argument really is a callback and the caller should wrap it as usual.
+ *
+ * A handler bound to THIS protocol is returned unchanged, with a one-time warning: the module
+ * already produced a working `BoundEntrypointHandler`, and re-wrapping it here would only wrap it
+ * again — returning it as-is is what makes `bind(protocol, api.body(protocol, alreadyBound))`
+ * behave exactly like `bind(protocol, alreadyBound)`, which is what a wrap-once file looks like at
+ * this call site. Anything else — a handler bound to a DIFFERENT protocol, or a value that is
+ * neither a function nor a bound handler at all — answers every request on this route with
+ * {@link HandlerMisconfiguredError} instead of throwing `TypeError: handler is not a function`
+ * out of the request pipeline's own `try`, where the type name and the alias it happened on are
+ * both lost.
+ */
+const toleratedHandler = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol, handler: unknown
+): BoundEntrypointHandler<Protocol> | null => {
+  if (typeof handler === 'function') return null
+
+  if (isBoundHandler(handler)) {
+    if (handler.protocol.alias === protocol.alias) {
+      if (!warnedAliases.has(protocol.alias)) {
+        warnedAliases.add(protocol.alias)
+        console.warn(
+          `[server-api] ${protocol.alias}: handler is already bound — pass it to bind() directly; `
+          + 'wrapping it again here is a type error (TS2345 "BoundEntrypointHandler<…> is not '
+          + 'assignable"), tolerated at runtime for a project generated before the wrap-once rule.'
+        )
+      }
+
+      return handler as unknown as BoundEntrypointHandler<Protocol>
+    }
+
+    return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+      throw new HandlerMisconfiguredError(
+        `${protocol.alias}: handler is bound to a different protocol ('${handler.protocol.alias}')`
+      )
+    })
+  }
+
+  return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+    throw new HandlerMisconfiguredError(`${protocol.alias}: handler is not a function`)
+  })
+}
+
+/**
+ * Make server handlers that infer request sections and response values from their protocol.
+ * The protocol is passed once; application callbacks never name request or reply generics.
+ */
+export const handlers = <Context extends BasicContext<BasicConfig>>() => ({
+  body: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends BodyProtocol<Protocol> ? (
+        payload: BodyOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
+    (handler as (
+      payload: BodyOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.body as BodyOf<Protocol>, context, request)),
+
+  params: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends ParamsProtocol<Protocol> ? (
+        payload: ParamsOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
+    (handler as (
+      payload: ParamsOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.params as ParamsOf<Protocol>, context, request)),
+
+  request: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: (
+      request: HandlerRequest<RequestOf<Protocol>>,
+      context: Context,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, handler),
+})
+
+/** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
+export const uploadedFile = async (
+  request: HandlerRequest<{ body: object }>,
+): Promise<import('@fastify/multipart').MultipartFile | undefined> => {
+  const original = (request as AbstractRequest).original
+  if (original == null || typeof original !== 'object' || !('file' in original)) return undefined
+
+  return (original as import('fastify').FastifyRequest).file()
+}

package/src/server.ts

@@ -1,6 +1,6 @@
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { ApiServer, ApiServerAppend } from './types.js'
-import { Layer, assertContext, createService } from '@owlmeans/context'
+import { assertContext, createService } from '@owlmeans/context'
 import { canServeModule, executeResponse, provideRequest } from './utils/index.js'
 import { DEFAULT_ALIAS, CLOSED_HOST, PORT, OPENED_HOST } from './consts.js'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
@@ -57,8 +57,6 @@ export const createApiServer = (alias: string): ApiServer => {
      }*/
     }),
 
-    layers: [Layer.System],
-
     listen: async () => {
       const context = _assertContext(service.ctx as Context)
 
@@ -133,10 +131,8 @@ export const createApiServer = (alias: string): ApiServer => {
           return context
         }
 
-        // await module.route.resolve(context as any)
-        await module.resolve()
-        // Actually intermediate module can be created without handler by elevate function
-        if (module.route.match(request) && module.handle != null) {
+        // An intermediate route can be created without a handler by the binding layer.
+        if (module.route.match(request, module.mount()) && module.handle != null) {
           const response = provideResponse(reply)
           const currentRequest = provideRequest(module.alias, request, true)
           currentRequest.original._ctx = context
@@ -150,42 +146,38 @@ export const createApiServer = (alias: string): ApiServer => {
       }, Promise.resolve(context))
     })
 
-    await Promise.all(
-      context.entrypoints<ServerEntrypoint<FastifyRequest>>()
-        .filter(module => canServeModule(context, module) && !module.route.isIntermediate())
-        .map(async module => {
-          // await module.route.resolve(context as any)
-          await module.resolve()
-          const method = module.route.route.method ?? RouteMethod.GET
-          if (module.handle == null) {
-            return
-          }
-          server.route({
-            url: module.getPath(), method,
-            schema: {
-              consumes: [
-                'application/json',
-                'application/x-www-form-urlencoded',
-                'multipart/form-data',
-              ],
-              querystring: fixFormatDates(module.filter?.query ?? {}),
-              ...(
-                [
-                  RouteMethod.POST,
-                  RouteMethod.PATCH,
-                  RouteMethod.PUT
-                ].includes(method)
-                  ? { body: fixFormatDates(module.filter?.body ?? {}) }
-                  : {}
-              ),
-              params: fixFormatDates(module.filter?.params ?? {}),
-              response: module.filter?.response,
-              headers: fixFormatDates(module.filter?.headers ?? {})
-            },
-            handler: createServerHandler(module, location)
-          })
+    context.entrypoints<ServerEntrypoint<FastifyRequest>>()
+      .filter(module => canServeModule(context, module) && !module.route.isIntermediate())
+      .forEach(module => {
+        const method = module.route.route.method ?? RouteMethod.GET
+        if (module.handle == null) {
+          return
+        }
+        server.route({
+          url: module.mount(), method,
+          schema: {
+            consumes: [
+              'application/json',
+              'application/x-www-form-urlencoded',
+              'multipart/form-data',
+            ],
+            querystring: fixFormatDates(module.filter?.query ?? {}),
+            ...(
+              [
+                RouteMethod.POST,
+                RouteMethod.PATCH,
+                RouteMethod.PUT
+              ].includes(method)
+                ? { body: fixFormatDates(module.filter?.body ?? {}) }
+                : {}
+            ),
+            params: fixFormatDates(module.filter?.params ?? {}),
+            response: module.filter?.response,
+            headers: fixFormatDates(module.filter?.headers ?? {})
+          },
+          handler: createServerHandler(module, location)
         })
-    )
+      })
 
     service.initialized = true
   })
@@ -208,4 +200,3 @@ export const appendApiServer = <C extends Config, T extends ServerContext<C>>(
   return context
 }
 
-

package/src/types.ts

@@ -1,5 +1,5 @@
 
-import type { InitializedService, Layer } from '@owlmeans/context'
+import type { InitializedService } from '@owlmeans/context'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
 import '@fastify/middie/types/index.d.ts'
@@ -7,8 +7,6 @@ import '@fastify/middie/types/index.d.ts'
 export interface ApiServer extends InitializedService {
   server: FastifyInstance
 
-  layers: [Layer.System]
-
   listen: () => Promise<void>
 }
 

package/src/utils/error.ts

@@ -1,14 +1,31 @@
 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'
 
+/**
+ * Map a thrown error onto an HTTP status.
+ *
+ * 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.
+ *
+ * **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.
+ */
 export const handleError = (error: Error, reply: FastifyReply) => {
   let code: number = SERVER_ERROR
-  if (error instanceof AuthFailedError) {
-    code = UNAUTHORIZED_ERROR
-  } else if (error instanceof AccessError) {
+  if (error instanceof AuthForbidden || error instanceof AccessError) {
+    // An established identity that lacks the permission. Re-authenticating changes nothing.
     code = FORBIDDEN_ERROR
+  } else if (error instanceof AuthorizationError || error instanceof AuthFailedError) {
+    // 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
   }
   if (!reply.sent) {
     reply.code(code).send(

package/src/utils/guards.ts

@@ -1,4 +1,3 @@
-import { isContextWithoutIds, Layer } from '@owlmeans/context'
 import type { FastifyReply, FastifyRequest } from 'fastify'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
 import type { GuardService } from '@owlmeans/entrypoint'
@@ -7,6 +6,7 @@ import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import { executeResponse, provideRequest } from './payload.js'
 import { AuthFailedError } from '../errors.js'
 import type { Auth } from '@owlmeans/auth'
+import { attachEntity } from '@owlmeans/auth-common'
 
 type Config = ServerConfig
 interface Context<C extends Config = Config> extends ServerContext<C> { }
@@ -50,22 +50,15 @@ export const authorize = async <C extends Config, T extends Context<C>>(
       (req as any)._auth = request.auth
     }
 
-    if (request.auth?.entityId != null) {
-      // @TODO Probably we need to downgrade context in this case
-      if (!isContextWithoutIds(context as any)) {
-        throw SyntaxError(`Context should be without ids during authorization ${context.cfg.layer}:${context.cfg.layerId}`)
-      }
-
-      if (isContextWithoutIds(context as any) && context.cfg.layer !== Layer.Service) {
-        context = await context.updateContext(undefined, Layer.Service)
-        await context.waitForInitialized()
-      }
-      context = await context.updateContext(request.auth.entityId, Layer.Entity)
-      await context.waitForInitialized()
-
-      // We elevate module to the context level if it was changed
-      module = context.entrypoint(module.alias)
-      await module.resolve()
+    // The token names the organization by slug; everything downstream — grants, records, minted
+    // infrastructure names — keys on the entity's stable id. Resolving here, once, is what keeps a
+    // rename from being a sweep of every handler: the id arrives on the request, and a slug that
+    // has since been retired still resolves to the entity that retired it.
+    const entity = await attachEntity(context, request)
+    if (entity != null) {
+      // Carried on the raw request the same way `_auth` is, so the request the handler is given
+      // later — a different object, built after this runs — sees the same resolution.
+      ;(req as any)._entity = entity
     }
   }
   // Update context in request object

package/src/utils/payload.ts

@@ -9,6 +9,9 @@ export const provideRequest = (alias: string, req: Request, provision?: boolean)
   return {
     alias,
     auth: (req as any)._auth ?? undefined,
+    // Resolved once by `authorize` and carried by reference, exactly like `_auth`, so a handler
+    // reached through any path sees the same entity the guard admitted.
+    entity: (req as any)._entity ?? undefined,
     params: req.params as Record<string, string | number | undefined | null>,
     body: req.body as Record<string, any>,
     headers: req.headers,

package/src/utils/server.ts

@@ -23,7 +23,10 @@ export const canServeModule = (context: Context, module: CommonEntrypoint): modu
   if (module.route.route.service != null && module.route.route.service !== context.cfg.service) {
     return false
   }
-  if (module.route.route.protocol === RouteProtocols.SOCKET) {
+  // 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) {
     return false
   }
 

package/tests/handlers.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test'
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { handlers } from '../src/protocol.js'
+import { HandlerMisconfiguredError } from '../src/errors.js'
+
+/**
+ * A protocol-bound implementation is run with the smallest binding context the transport needs —
+ * same pattern as `@owlmeans/server-auth-token`'s own `handlers.spec.ts`.
+ */
+const invoke = async (handler: any, context: any, req: any = {}): Promise<any> => {
+  const res: any = { resolve: (value: unknown) => { res.value = value }, reject: (e: Error) => { res.error = e } }
+  await handler.bind({ ref: { ctx: context } })(req, res)
+  if (res.error != null) throw res.error
+
+  return res.value
+}
+
+const protocolFor = (alias: string): EntrypointProtocolDeclaration =>
+  ({ alias } as unknown as EntrypointProtocolDeclaration)
+
+const context = { alias: 'test-context' } as any
+const api = handlers<any>()
+
+describe('@owlmeans/server-api — handlers() wrap-once tolerance', () => {
+  test('a plain function is wrapped once and called with the context', async () => {
+    const protocol = protocolFor('api.thing.plain')
+    const handler = api.request(protocol, async (_req: any, ctx: any) => ({ ok: true, ctx }))
+
+    const result = await invoke(handler, context, {})
+    expect(result).toEqual({ ok: true, ctx: context })
+  })
+
+  test('a handler already bound to the SAME protocol is returned unchanged by body/params/request and still answers', async () => {
+    for (const method of ['body', 'params', 'request'] as const) {
+      const protocol = protocolFor(`api.thing.${method}`)
+      const bound = api.request(protocol, async () => ({ from: method }))
+
+      const wrapped = (api as any)[method](protocol, bound)
+      expect(wrapped).toBe(bound)
+
+      const result = await invoke(wrapped, context, {})
+      expect(result).toEqual({ from: method })
+    }
+  })
+
+  test('a handler bound to a DIFFERENT protocol answers with HandlerMisconfiguredError', async () => {
+    const protocolA = protocolFor('api.thing.mismatch-a')
+    const protocolB = protocolFor('api.thing.mismatch-b')
+    const boundToA = api.request(protocolA, async () => ({ from: 'a' }))
+
+    const wrapped = api.request(protocolB, boundToA as any)
+    expect(wrapped).not.toBe(boundToA)
+    await expect(invoke(wrapped, context, {})).rejects.toThrow(HandlerMisconfiguredError)
+  })
+
+  test('a value that is neither a function nor a bound handler answers with HandlerMisconfiguredError', async () => {
+    const protocol = protocolFor('api.thing.not-a-function')
+    const wrapped = api.request(protocol, { not: 'a function' } as any)
+
+    await expect(invoke(wrapped, context, {})).rejects.toThrow(HandlerMisconfiguredError)
+  })
+
+  test('the double-wrap warning fires once per alias, not once per call', async () => {
+    const protocol = protocolFor('api.thing.warn-once')
+    const bound = api.request(protocol, async () => 'ok')
+
+    const warnings: unknown[][] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => { warnings.push(args) }
+    try {
+      // Each call is a deliberate double wrap — the exact shape `tsc` rejects at the real call
+      // site (TS2345) — so it is exercised here through `any`, the same way `body`/`params`
+      // are reached dynamically above.
+      (api as any).request(protocol, bound);
+      (api as any).body(protocol, bound);
+      (api as any).params(protocol, bound)
+    } finally {
+      console.warn = original
+    }
+
+    expect(warnings.length).toBe(1)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -10,6 +10,7 @@
   "exclude": [
     "./dist/**/*",
     "./build/**/*",
+    "./tests/**/*",
     "./*.ts"
   ]
 }