@owlmeans/server-auth 0.1.18-rc.8 → 0.1.18

package/src/manager/model.ts

@@ -1,18 +1,26 @@
 import type { AuthModel, AppConfig, AppContext } from './types.js'
-import { AuthenFailed, AuthenPayloadError } from '@owlmeans/auth'
-import type { AuthCredentials } from '@owlmeans/auth'
-import { getPlugin } from './plugins/utils.js'
+import { AuthenFailed, AuthenPayloadError, AuthError, AuthUnavailable, authHelper, type AuthCredentials } from '@owlmeans/auth'
+import { logger } from '@owlmeans/log'
+import { type EntityResolverService, ENTITY_RESOLVER } from '@owlmeans/auth-common'
+import { authPluginHelper } from './plugins/utils.js'
 import { AUTH_CACHE, AUTHEN_TIMEFRAME } from '../consts.js'
-import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
-import type { EnvelopeModel } from '@owlmeans/basic-envelope'
+import { EnvelopeKind, makeEnvelopeModel, type EnvelopeModel } from '@owlmeans/basic-envelope'
 import { createRelyFlow } from './rely/flow.js'
 import { trusted } from './utils/trusted.js'
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { Resource } from '@owlmeans/resource'
 import type { AuthSpent } from '../types.js'
+import { AuthChallengeReplayPolicy } from './plugins/consts.js'
+import type { Context } from './types.local.js'
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
+
+const log = logger('server-auth')
+
+/** An account id as a log may carry it: an e-mail is reduced to its domain. */
+const accountOf = (userId: string | undefined): string | undefined =>
+  userId == null ? undefined : userId.includes('@') ? `*@${userId.slice(userId.lastIndexOf('@') + 1)}` : userId
+
+const compact = <T extends Record<string, unknown>>(value: T): Partial<T> =>
+  Object.fromEntries(Object.entries(value).filter(([, entry]) => entry != null)) as Partial<T>
 
 export const makeAuthModel = (context: AppContext<AppConfig>): AuthModel => {
   const cache = (context: Context): Resource<AuthSpent> =>
@@ -20,7 +28,7 @@ export const makeAuthModel = (context: AppContext<AppConfig>): AuthModel => {
 
   const model: AuthModel = {
     init: async request => {
-      const plugin = await getPlugin(request.type, context)
+      const plugin = await authPluginHelper.getPlugin(request.type, context)
       const response = await plugin.init(request)
 
       const envelope = makeEnvelopeModel(plugin.type)
@@ -41,46 +49,79 @@ export const makeAuthModel = (context: AppContext<AppConfig>): AuthModel => {
     },
 
     authenticate: async credential => {
-      const [trustedUser, keyPair] = await trusted(context)
-      const envelope: EnvelopeModel = makeEnvelopeModel(credential.challenge, EnvelopeKind.Wrap)
-      if (!await envelope.verify(keyPair)) {
-        throw new AuthenFailed('challenge')
-      }
-
-      const msg: string = envelope.message(true)
-
+      // The one place every manager sign-in method (each plugin) is decided — logged once here.
+      const method = credential.type
       try {
-        await cache(context).create({ id: msg }, { ttl: (envelope.envelope.ttl ?? AUTHEN_TIMEFRAME) / 1000 })
-      } catch (e) {
-        const error = new AuthenFailed('challenge')
-        if (e instanceof Error) {
-          error.oiriginalStack = `${e} : ${e.stack}`
+        const [trustedUser, keyPair] = await trusted(context)
+        const envelope: EnvelopeModel = makeEnvelopeModel(credential.challenge, EnvelopeKind.Wrap)
+        if (!await envelope.verify(keyPair)) {
+          throw new AuthenFailed('challenge')
         }
-        throw error
-      }
 
-      if (credential.userId == null) {
-        throw new AuthenPayloadError('userId')
-      }
+        const msg: string = envelope.message(true)
+
+        const plugin = await authPluginHelper.getPlugin(envelope.type(), context)
 
-      const plugin = await getPlugin(envelope.type(), context)
+        if (plugin.challengeReplayPolicy !== AuthChallengeReplayPolicy.Plugin) {
+          try {
+            await cache(context).create({ id: msg }, { ttl: (envelope.envelope.ttl ?? AUTHEN_TIMEFRAME) / 1000 })
+          } catch (e) {
+            const error = new AuthenFailed('challenge')
+            if (e instanceof Error) {
+              error.oiriginalStack = `${e} : ${e.stack}`
+            }
+            throw error
+          }
+        }
 
-      // @TODO this token PROBABLY needs to be registered somewhere and rechecked
-      // from time to time to make sure that the session is not deleted 
-      // or permission hasn't changed.
-      // Alternative solution is to have permissions cached and cleaned 
-      // when some broadcast message is sent from authentication system.
+        if (credential.userId == null) {
+          throw new AuthenPayloadError('userId')
+        }
 
-      const challenge = credential.challenge
-      const { token } = await plugin.authenticate(Object.assign(credential, { challenge: msg }))
-      credential.challenge = token === '' ? challenge : token
+        // @TODO this token PROBABLY needs to be registered somewhere and rechecked
+        // from time to time to make sure that the session is not deleted 
+        // or permission hasn't changed.
+        // Alternative solution is to have permissions cached and cleaned 
+        // when some broadcast message is sent from authentication system.
+
+        const challenge = credential.challenge
+        const { token } = await plugin.authenticate(Object.assign(credential, { challenge: msg }))
+        credential.challenge = token === '' ? challenge : token
+
+        // Plugins accept whatever the caller typed — a current slug, a slug the organization has
+        // since retired, or (for a token minted before slugs existed) its stable key. The token is
+        // signed once and read for as long as it lives, so the value is canonicalized here rather
+        // than at every place that later reads it back.
+        const entitySlug = authHelper.entitySlugOf(credential)
+        if (entitySlug != null && context.hasService(ENTITY_RESOLVER)) {
+          const entity = await context.service<EntityResolverService>(ENTITY_RESOLVER).resolve(entitySlug)
+          if (entity == null) {
+            throw new AuthenFailed('entity')
+          }
+          credential.entitySlug = entity.slug
+        }
 
-      credential.credential = trustedUser.id
+        credential.credential = trustedUser.id
 
-      return {
-        token: await makeEnvelopeModel<AuthCredentials>(credential.type)
-          .send(credential, AUTHEN_TIMEFRAME)
-          .sign(keyPair, EnvelopeKind.Token)
+        const result = {
+          token: await makeEnvelopeModel<AuthCredentials>(credential.type)
+            .send(credential, AUTHEN_TIMEFRAME)
+            .sign(keyPair, EnvelopeKind.Token)
+        }
+        log.info('Signed in', compact({
+          method, accountId: accountOf(credential.userId), profileId: credential.profileId,
+          entitySlug: credential.entitySlug,
+        }), { event: 'auth.signed-in' })
+
+        return result
+      } catch (error) {
+        // An outage (`AuthUnavailable`) is not a refusal; it propagates and is logged as a failure.
+        if (error instanceof AuthError && !(error instanceof AuthUnavailable)) {
+          log.warn('Sign-in refused', compact({
+            method, accountId: accountOf(credential.userId), reason: error.message,
+          }), { event: 'auth.refused' })
+        }
+        throw error
       }
     },
 

package/src/manager/plugins/basic-ed25519.ts

@@ -1,18 +1,18 @@
 import { AuthenticationType, AuthenFailed, ALL_SCOPES, AuthRole } from '@owlmeans/auth'
 import type { AuthPlugin } from './types.js'
-import { assertType } from './utils.js'
-import { randomBytes } from '@noble/hashes/utils'
+import { authPluginHelper } from './utils.js'
+import { randomBytes } from '@noble/hashes/utils.js'
 import { base64 } from '@scure/base'
-import { fromPubKey } from '@owlmeans/basic-keys'
+import { keyHelper } from '@owlmeans/basic-keys'
 import type { AppConfig, AppContext } from '../types.js'
 import { TRUSTED } from '@owlmeans/config'
 import type { TrustedRecord } from '@owlmeans/auth-common'
 
-export const basicEd25519 = <C extends AppConfig, T extends AppContext<C>>(context: T): AuthPlugin => {
+export const makeBasicEd25519Plugin = <C extends AppConfig, T extends AppContext<C>>(context: T): AuthPlugin => {
   const plugin: AuthPlugin = {
     type: AuthenticationType.BasicEd25519,
     init: async request => {
-      assertType(request.type, plugin)
+      authPluginHelper.assertType(request.type, plugin)
 
       const challenge = base64.encode(randomBytes(32))
 
@@ -23,8 +23,8 @@ export const basicEd25519 = <C extends AppConfig, T extends AppContext<C>>(conte
       /**
        * @TODO We need to find users in some db not just in static
        */
-      const systemUser = await context.getConfigResource(TRUSTED)
-        .load<TrustedRecord>(credential.userId)
+      const systemUser = await context.getConfigResource<TrustedRecord>(TRUSTED)
+        .load(credential.userId)
 
       if (systemUser == null) {
         throw new AuthenFailed()
@@ -34,7 +34,7 @@ export const basicEd25519 = <C extends AppConfig, T extends AppContext<C>>(conte
         throw new SyntaxError('System user missconfigured')
       }
 
-      const key = fromPubKey(systemUser.credential)
+      const key = keyHelper.fromPubKey(systemUser.credential)
 
       if (!await key.verify(credential.challenge, credential.credential)) {
         throw new AuthenFailed(`challenge:${plugin.type}`)

package/src/manager/plugins/basic-rely.ts

@@ -7,17 +7,21 @@ import { trusted } from '../utils/trusted.js'
 import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
 import { AUTH_CACHE } from '../../consts.js'
 import { ResourceError } from '@owlmeans/resource'
+import type { Unsubscribe } from '@owlmeans/resource'
 import { RELY_CALL_TIMEOUT, RELY_PIN_PERFIX, RELY_TOKEN_PREFIX } from '@owlmeans/auth-common'
+import { logger } from '@owlmeans/log'
 
-const _subscriptions: Record<string, CallableFunction> = {}
-export const basicRely = (context: AppContext, type?: string): AuthPlugin => {
+const log = logger('server-auth:rely')
+
+const _subscriptions: Record<string, Unsubscribe> = {}
+export const makeBasicRelyPlugin = (context: AppContext, type?: string): AuthPlugin => {
   const plugin: AuthPlugin = {
     type: type ?? AuthenticationType.RelyHandshake,
 
     // This method is used by consumer and by provider (wallet)
     // to initialize shared authentication process.
-    // The idea is that both subscribe to wait for a handshake value
-    // from the peer, that in fact is a subscription to a redis message tunnel.  
+    // The idea is that both watch the record holding their own pin/token and wake
+    // up when the peer writes its handshake value into it.
     init: async (request: RelyAllowanceRequest): Promise<AllowanceResponse> => {
       const [, keyPair] = await trusted(context)
       const tunnel = context.resource<AuthRedisResource>(AUTH_CACHE)
@@ -41,8 +45,8 @@ export const basicRely = (context: AppContext, type?: string): AuthPlugin => {
 
           if (request.provideRely != null) {
             await Promise.all([pin, token].filter(key => key != null).map(async key => {
-              _subscriptions[key] = await tunnel.subscribe(async value => {
-                if (value.challenge != null) {
+              _subscriptions[key] = await tunnel.watch(key, async value => {
+                if (value?.challenge != null) {
                   const rely = makeEnvelopeModel<RelyToken>(value.challenge, EnvelopeKind.Wrap)
                   if (await rely.verify(keyPair)) {
                     [pin, token].filter(key => key != null).forEach(key => {
@@ -54,7 +58,7 @@ export const basicRely = (context: AppContext, type?: string): AuthPlugin => {
                     await request.provideRely?.(rely.message(), relyMsg, true)
                   }
                 }
-              }, { /*ttl: RELY_CALL_TIMEOUT,*/ key, once: true })
+              }, { once: true })
 
               // @TODO they need to be killed on close - but actually live a little bit longer 
               // then timeout for them is ok
@@ -74,7 +78,7 @@ export const basicRely = (context: AppContext, type?: string): AuthPlugin => {
           return response
         } catch (e) {
           if (e instanceof ResourceError) {
-            console.error('COLISION ON TRY TO CREATE RELY PIN\TOKEN...', e)
+            log.warn('Rely pin/token collision; retrying', e)
           } else {
             throw e
           }
@@ -117,7 +121,8 @@ export const basicRely = (context: AppContext, type?: string): AuthPlugin => {
         rely = envelop.message()
       } catch (e) {
         if (e instanceof ResourceError) {
-          console.error(e)
+          // The peer's pin/token is unknown; the refusal itself is logged where sign-in is decided.
+          log.debug('Rely peer lookup failed', e)
           throw new AuthorizationError('rely')
         } else {
           throw e

package/src/manager/plugins/consts.ts

@@ -0,0 +1,7 @@
+/** Ownership of atomic replay protection for a verified authentication challenge. */
+export enum AuthChallengeReplayPolicy {
+  /** Default: the auth manager consumes the challenge before plugin authentication. */
+  Manager = 'manager',
+  /** The plugin owns bounded attempts and atomic success consumption. */
+  Plugin = 'plugin',
+}

package/src/manager/plugins/export.ts

@@ -1,5 +1,10 @@
 
 export type * from './types.js'
+export type * from './re-captcha/types.js'
+export * from './consts.js'
+export * from './re-captcha/consts.js'
+export * from './re-captcha/policy.js'
+export * from './re-captcha/verifier.js'
 export * from './basic-ed25519.js'
 export * from './re-captcha.js'
 export * from './basic-rely.js'

package/src/manager/plugins/index.ts

@@ -1,21 +1,19 @@
 import { AuthenticationType } from '@owlmeans/auth'
-import type { AuthPlugin } from './types.js'
-import { basicEd25519 } from './basic-ed25519.js'
-import type { AppContext, AppConfig } from '../types.js'
-import { reCaptcha } from './re-captcha.js'
-import { basicRely } from './basic-rely.js'
+import type { AuthPluginFactory } from './types.js'
+import { makeBasicEd25519Plugin } from './basic-ed25519.js'
+import { makeReCaptchaPlugin } from './re-captcha.js'
+import { makeBasicRelyPlugin } from './basic-rely.js'
 
-export const plugins: Record<string, <C extends AppConfig, T extends AppContext<C>>(context: T) => AuthPlugin> = {}
+export const plugins: Record<string, AuthPluginFactory> = {}
 
-plugins[AuthenticationType.BasicEd25519] = basicEd25519 as typeof plugins[keyof typeof plugins]
-plugins[AuthenticationType.ReCaptcha] = reCaptcha as typeof plugins[keyof typeof plugins]
-plugins[AuthenticationType.RelyHandshake] = basicRely as typeof plugins[keyof typeof plugins]
+plugins[AuthenticationType.BasicEd25519] = makeBasicEd25519Plugin as AuthPluginFactory
+plugins[AuthenticationType.ReCaptcha] = makeReCaptchaPlugin as AuthPluginFactory
+plugins[AuthenticationType.RelyHandshake] = makeBasicRelyPlugin as AuthPluginFactory
 
 /** Register an external AuthPlugin factory under a custom type string. */
 export const registerPlugin = (
   type: string,
-  factory: <C extends AppConfig, T extends AppContext<C>>(context: T) => AuthPlugin
+  factory: AuthPluginFactory
 ): void => {
-  plugins[type] = factory as typeof plugins[keyof typeof plugins]
+  plugins[type] = factory
 }
-

package/src/manager/plugins/re-captcha/consts.local.ts

@@ -0,0 +1,8 @@
+/**
+ * The only credential fields a reCAPTCHA guest token keeps. Everything else the caller posted —
+ * a profile, an organization (`entitySlug` or `entityId`), permissions, groups, an expiry, a
+ * `source` — is dropped: the token proves a solved challenge, never an identity.
+ */
+export const RECAPTCHA_CREDENTIAL_FIELDS: readonly string[] = Object.freeze([
+  'type', 'role', 'userId', 'scopes', 'challenge', 'credential',
+])

package/src/manager/plugins/re-captcha/consts.ts

@@ -0,0 +1,8 @@
+/** The service alias the reCAPTCHA plugin resolves its verifier by. */
+export const RECAPTCHA_VERIFIER = 're-captcha-verifier'
+
+/** Google's siteverify endpoint — always https. */
+export const RECAPTCHA_SITEVERIFY_URL = 'https://www.google.com/recaptcha/api/siteverify'
+
+/** How long the default verifier waits for Google, in ms. */
+export const RECAPTCHA_VERIFY_TIMEOUT = 10_000

package/src/manager/plugins/re-captcha/policy.ts

@@ -0,0 +1,56 @@
+import { AuthenFailed } from '@owlmeans/auth'
+import { PluginMissconfigured } from '@owlmeans/config'
+import type { ReCaptchaPluginConfig, ReCaptchaPolicyModel, ReCaptchaResponse } from './types.js'
+
+/** A comma- or space-separated config string as its entries; `''` and absent are no entries. */
+const listOf = (value: unknown): string[] =>
+  typeof value === 'string' ? value.split(/[\s,]+/).map(entry => entry.trim()).filter(entry => entry !== '') : []
+
+/** A host as it is compared: lowercased, without a trailing dot or a leading `*.`/`.`. */
+const hostOf = (value: string): string => value.trim().toLowerCase().replace(/\.$/, '').replace(/^\*?\./, '')
+
+export const makeReCaptchaPolicyModel = (record: ReCaptchaPluginConfig): ReCaptchaPolicyModel => {
+  const hostnames = (): string[] => listOf(record.hostnames).map(hostOf).filter(host => host !== '')
+
+  const minScore = (): number | null => {
+    const value = record.minScore
+    if (value == null || (typeof value === 'string' && value.trim() === '')) {
+      return null
+    }
+    const score = typeof value === 'number' ? value : Number(value)
+    if (!Number.isFinite(score) || score < 0 || score > 1) {
+      throw new PluginMissconfigured('minScore')
+    }
+
+    return score
+  }
+
+  const actions = (): string[] => listOf(record.actions)
+
+  const assert = (response: ReCaptchaResponse): void => {
+    if (response.success !== true) {
+      const codes = Array.isArray(response['error-codes']) ? response['error-codes'] : []
+      throw new AuthenFailed('recaptcha:' + (codes.length > 0 ? codes.join(',') : 'unknown'))
+    }
+
+    const allowed = hostnames()
+    if (allowed.length > 0) {
+      const host = typeof response.hostname === 'string' ? hostOf(response.hostname) : ''
+      if (host === '' || !allowed.some(entry => host === entry || host.endsWith(`.${entry}`))) {
+        throw new AuthenFailed('recaptcha:hostname')
+      }
+    }
+
+    const floor = minScore()
+    if (floor != null && typeof response.score === 'number' && response.score < floor) {
+      throw new AuthenFailed('recaptcha:score')
+    }
+
+    const named = actions()
+    if (named.length > 0 && (typeof response.action !== 'string' || !named.includes(response.action))) {
+      throw new AuthenFailed('recaptcha:action')
+    }
+  }
+
+  return { record, hostnames, minScore, actions, assert }
+}

package/src/manager/plugins/re-captcha/types.ts

@@ -0,0 +1,85 @@
+import type { PluginConfig } from '@owlmeans/config'
+import type { InitializedService } from '@owlmeans/context'
+
+/** Google's siteverify answer, for a checkbox (v2) or a score-based (v3) token. */
+export interface ReCaptchaResponse {
+  success: boolean
+  /** When the challenge was solved, as an ISO date-time string. */
+  challenge_ts: string
+  /** The host of the page the token was solved on. */
+  hostname: string
+  /** Score-based keys only: 0.0 (a bot) … 1.0 (a person). */
+  score?: number
+  /** Score-based keys only: the action the page named when it asked for the token. */
+  action?: string
+  'error-codes'?: string[]
+}
+
+/** The siteverify form: the key's secret, the token the browser got, optionally the browser's IP. */
+export interface ReCaptchaRequest {
+  secret: string
+  response: string
+  remoteip?: string
+}
+
+/**
+ * Asks Google whether a reCAPTCHA token is good. The plugin resolves it by `RECAPTCHA_VERIFIER`, so a
+ * test (or a proxy) registers its own under that alias; without one, the default siteverify call runs.
+ */
+export interface ReCaptchaVerifierService extends InitializedService {
+  /**
+   * Google's answer for one token. A refusal is an answer (`success: false`), not an error.
+   *
+   * @throws {AuthUnavailable} when Google cannot be asked or answers something unreadable.
+   */
+  verify: (request: ReCaptchaRequest) => Promise<ReCaptchaResponse>
+}
+
+/** The one call the default verifier makes — `fetch`, or a stand-in a test injects. */
+export interface ReCaptchaFetch {
+  (url: string, init: RequestInit): Promise<Response>
+}
+
+export interface ReCaptchaVerifierOptions {
+  /** The siteverify address; must be https. Default `RECAPTCHA_SITEVERIFY_URL`. */
+  url?: string
+  /** Default: the global `fetch`. */
+  fetch?: ReCaptchaFetch
+  /** Milliseconds before the call is abandoned. Default `RECAPTCHA_VERIFY_TIMEOUT`. */
+  timeout?: number
+}
+
+/**
+ * The `MOD_RECAPTCHA` plugin record of the server config: the secret in `value` plus the policy.
+ * Every policy field is a string as a mounted config file delivers it; `''` or absent = no check.
+ */
+export interface ReCaptchaPluginConfig extends PluginConfig {
+  /** Hosts a token may be solved on, comma- or space-separated; a subdomain of an entry passes. */
+  hostnames?: string
+  /** The lowest score a score-based token may carry (0…1); a checkbox token has none and passes. */
+  minScore?: string | number
+  /** The actions a token may be issued for, comma- or space-separated; a token naming none fails. */
+  actions?: string
+}
+
+/** The policy one `MOD_RECAPTCHA` record states, applied to Google's answer. */
+export interface ReCaptchaPolicyModel {
+  readonly record: ReCaptchaPluginConfig
+  /** The allowed hosts, lowercased; empty = any host. */
+  hostnames: () => string[]
+  /**
+   * The lowest accepted score, or `null` for no score check.
+   *
+   * @throws {PluginMissconfigured} when the record's value is not a number between 0 and 1.
+   */
+  minScore: () => number | null
+  /** The allowed actions; empty = any action. */
+  actions: () => string[]
+  /**
+   * Accept Google's answer or refuse it, in this order: success, hostname, score, action.
+   *
+   * @throws {AuthenFailed} `recaptcha:<error-codes>`, `recaptcha:hostname`, `recaptcha:score`,
+   *   `recaptcha:action`.
+   */
+  assert: (response: ReCaptchaResponse) => void
+}

package/src/manager/plugins/re-captcha/verifier.ts

@@ -0,0 +1,74 @@
+import { AuthUnavailable } from '@owlmeans/auth'
+import { createService } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { logger } from '@owlmeans/log'
+import { RECAPTCHA_SITEVERIFY_URL, RECAPTCHA_VERIFIER, RECAPTCHA_VERIFY_TIMEOUT } from './consts.js'
+import type { ReCaptchaResponse, ReCaptchaVerifierOptions, ReCaptchaVerifierService } from './types.js'
+
+const log = logger('server-auth:re-captcha')
+
+/**
+ * The default verifier: one form POST to Google's siteverify. It holds no state and never touches
+ * its context, so the plugin may also run it unregistered.
+ *
+ * @throws {SyntaxError} for a siteverify address that is not https.
+ */
+export const createReCaptchaVerifierService = (
+  alias: string = RECAPTCHA_VERIFIER, options: ReCaptchaVerifierOptions = {}
+): ReCaptchaVerifierService => {
+  const url = options.url ?? RECAPTCHA_SITEVERIFY_URL
+  if (!url.startsWith('https://')) {
+    throw new SyntaxError(`reCAPTCHA siteverify must be https: ${url}`)
+  }
+  const timeout = options.timeout ?? RECAPTCHA_VERIFY_TIMEOUT
+
+  /** The answer, when it has the shape of one. */
+  const readAnswer = async (response: Response): Promise<ReCaptchaResponse | null> => {
+    try {
+      const answer = await response.json() as ReCaptchaResponse | null
+      return answer != null && typeof answer === 'object' && typeof answer.success === 'boolean' ? answer : null
+    } catch {
+      return null
+    }
+  }
+
+  return createService<ReCaptchaVerifierService>(alias, {
+    verify: async request => {
+      const body = new URLSearchParams({ secret: request.secret, response: request.response })
+      if (request.remoteip != null && request.remoteip !== '') {
+        body.set('remoteip', request.remoteip)
+      }
+
+      const send = options.fetch ?? fetch
+      let response: Response
+      try {
+        response = await send(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body,
+          signal: AbortSignal.timeout(timeout),
+        })
+      } catch (error) {
+        log.warn('reCAPTCHA siteverify unreachable', { error }, { event: 'auth.recaptcha.unavailable' })
+        throw new AuthUnavailable('recaptcha')
+      }
+
+      const answer = response.ok ? await readAnswer(response) : null
+      if (answer == null) {
+        log.warn('reCAPTCHA siteverify answered unusably', { status: response.status }, { event: 'auth.recaptcha.unavailable' })
+        throw new AuthUnavailable('recaptcha')
+      }
+
+      return answer
+    },
+  })
+}
+
+/** Register a verifier (the default siteverify call unless `options` say otherwise). */
+export const appendReCaptchaVerifierService = <C extends BasicConfig, T extends BasicContext<C>>(
+  context: T, alias: string = RECAPTCHA_VERIFIER, options?: ReCaptchaVerifierOptions
+): T => {
+  context.registerService(createReCaptchaVerifierService(alias, options))
+
+  return context
+}