@owlmeans/server-auth 0.1.18-rc.55 → 0.1.18-rc.57

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

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

@@ -1,59 +1,74 @@
-import { AuthenFailed, AuthenticationType, AuthPluginError, MOD_RECAPTCHA, AUTH_SCOPE, AuthRole } from '@owlmeans/auth'
-import type { AppContext, AppConfig } from '../types.js'
-import type { AuthPlugin, RecaptchaRequest, RecpatchaResponse } from './types.js'
-import { PLUGINS } from '@owlmeans/config'
-import type { PluginConfig } from '@owlmeans/config'
-import { PluginMissconfigured } from '@owlmeans/config'
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
-import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { AUTH_SCOPE, AuthenticationType, AuthRole, GUEST_ID, MOD_RECAPTCHA } from '@owlmeans/auth'
+import type { AuthCredentials } from '@owlmeans/auth'
+import { PLUGINS, PluginMissconfigured } from '@owlmeans/config'
 import { base64 } from '@scure/base'
 import { randomBytes } from '@noble/hashes/utils.js'
+import type { AppContext, AppConfig } from '../types.js'
+import type { AuthPlugin } from './types.js'
 import { authPluginHelper } from './utils.js'
+import { RECAPTCHA_VERIFIER } from './re-captcha/consts.js'
+import { RECAPTCHA_CREDENTIAL_FIELDS } from './re-captcha/consts.local.js'
+import { makeReCaptchaPolicyModel } from './re-captcha/policy.js'
+import { createReCaptchaVerifierService } from './re-captcha/verifier.js'
+import type { ReCaptchaPluginConfig, ReCaptchaPolicyModel, ReCaptchaVerifierService } from './re-captcha/types.js'
 
+/**
+ * The reCAPTCHA sign-in: proves that a person solved a challenge, and nothing about who they are.
+ *
+ * The token the manager signs for it is a GUEST credential — `GUEST_ID`, role Guest, `[AUTH_SCOPE]`,
+ * type ReCaptcha — whatever identity the caller posted: a profile, an organization, permissions,
+ * groups, an expiry and a `source` are dropped before it is signed. Its single-use key is the
+ * server-issued challenge it carries. A route accepts it only through `makeReCaptchaGuard`; the
+ * bearer exchange refuses it.
+ */
 export const makeReCaptchaPlugin = <C extends AppConfig, T extends AppContext<C>>(context: T): AuthPlugin => {
+  const verifier = (): ReCaptchaVerifierService => context.hasService(RECAPTCHA_VERIFIER)
+    ? context.service<ReCaptchaVerifierService>(RECAPTCHA_VERIFIER)
+    : createReCaptchaVerifierService()
+
+  /** The secret and the policy of the `MOD_RECAPTCHA` record; no secret = no reCAPTCHA sign-in. */
+  const configured = async (): Promise<[string, ReCaptchaPolicyModel]> => {
+    const record = await context.getConfigResource<ReCaptchaPluginConfig>(PLUGINS).load(MOD_RECAPTCHA)
+    if (record == null || typeof record.value !== 'string' || record.value === '') {
+      throw new PluginMissconfigured('value')
+    }
+
+    return [record.value, makeReCaptchaPolicyModel(record)]
+  }
+
+  const resetIdentity = (credential: AuthCredentials): void => {
+    const fields = credential as unknown as Record<string, unknown>
+    for (const field of Object.keys(fields)) {
+      if (!RECAPTCHA_CREDENTIAL_FIELDS.includes(field)) {
+        delete fields[field]
+      }
+    }
+    credential.type = AuthenticationType.ReCaptcha
+    credential.role = AuthRole.Guest
+    credential.userId = GUEST_ID
+    credential.scopes = [AUTH_SCOPE]
+  }
+
   const plugin: AuthPlugin = {
     type: AuthenticationType.ReCaptcha,
 
     init: async request => {
       authPluginHelper.assertType(request.type, plugin)
 
-      const challenge = base64.encode(randomBytes(32))
-
-      return { challenge }
+      return { challenge: base64.encode(randomBytes(32)) }
     },
 
     authenticate: async credential => {
-      const cfg = context.getConfigResource<PluginConfig>(PLUGINS)
-      const config = await cfg.get(MOD_RECAPTCHA)
-      if (config.value == null) {
-        throw new PluginMissconfigured('value')
-      }
-      const validateRecaptcha = context.entrypoint<ClientEntrypoint<RecpatchaResponse>>(MOD_RECAPTCHA)
-      const { value: result, outcome: status } = await validateRecaptcha.invoke<RecpatchaResponse, RecaptchaRequest>({
-        body: {
-          secret: config.value,
-          response: credential.credential
-        },
-        headers: { 'content-type': 'application/x-www-form-urlencoded' }
-      })
-      if (status !== EntrypointOutcome.Ok) {
-        throw new AuthPluginError('recaptcha:api')
-      }
-      if (!result.success) {
-        throw new AuthenFailed('recaptcha:' + (result['error-codes']?.join(',') ?? 'unknown'))
-      }
+      const [secret, policy] = await configured()
+      // Read before the policy is judged: a misconfigured record fails before Google is asked.
+      policy.minScore()
 
-      credential.scopes = [AUTH_SCOPE]
-      credential.role = AuthRole.Guest
-      credential.type = AuthenticationType.ReCaptcha
+      const answer = await verifier().verify({ secret, response: credential.credential })
+      policy.assert(answer)
 
-      const [previous, challenge] = credential.challenge.split(':') as [string, string | undefined]
-      if (challenge != null) {
-        credential.challenge = previous
-
-        return { token: previous }
-      }
+      resetIdentity(credential)
 
+      // '' keeps the manager's own server-issued challenge on the token: that is its spend key.
       return { token: '' }
     }
   }

package/src/manager/plugins/types.ts

@@ -1,6 +1,5 @@
 import type { AllowanceResponse } from '@owlmeans/auth'
 import type { AppConfig, AppContext, AuthModel } from '../types.js'
-import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { RedisResource } from '@owlmeans/redis-resource'
 import type { ResourceRecord } from '@owlmeans/resource'
 import type { AuthChallengeReplayPolicy } from './consts.js'
@@ -14,19 +13,6 @@ export interface AuthPlugin extends Omit<AuthModel, "rely"> {
   challengeReplayPolicy?: AuthChallengeReplayPolicy
 }
 
-export interface RecpatchaResponse {
-  success: boolean
-  challenge_ts: number
-  hostname: string
-  'error-codes'?: string[]
-}
-
-export interface RecaptchaRequest extends AbstractRequest<{
-  secret: string
-  response: string
-  remoteip?: string
-}> { }
-
 export interface RelyRecord extends ResourceRecord, AllowanceResponse {
 }
 

package/src/re-captcha/guard.ts

@@ -0,0 +1,52 @@
+import { AUTH_SCOPE, AuthenticationType, AuthRole, GUEST_ID, RECAPTCHA_GUARD } from '@owlmeans/auth'
+import type { Auth } from '@owlmeans/auth'
+import { extractAuthToken } from '@owlmeans/auth-common/utils'
+import { createService } from '@owlmeans/context'
+import type { AbstractRequest, AbstractResponse, GuardService } from '@owlmeans/entrypoint'
+import type { Config, Context } from '../types.local.js'
+import { reCaptchaTokenOf } from './token.js'
+
+/**
+ * The guard of a route a reCAPTCHA-proven guest may call once (`RECAPTCHA_GUARD`):
+ * `Authorization: RE-CAPTCHA <token>`, the token the auth manager's reCAPTCHA plugin issued.
+ *
+ * Every check of `ReCaptchaTokenHelper.inspect`, then the spend — a token admits one request. The
+ * request's `auth` is a guest (`GUEST_ID`, role Guest, `[AUTH_SCOPE]`, type ReCaptcha) with an empty
+ * `token`: whatever reads an authorization downstream may log it. A refused token is no credential at
+ * all, so the request is unauthenticated (401).
+ */
+export const makeReCaptchaGuard = (alias: string = RECAPTCHA_GUARD): GuardService => {
+  const service: GuardService = createService<GuardService>(alias, {
+    match: async req => req != null && extractAuthToken(req, AuthenticationType.ReCaptcha) != null,
+
+    handle: async <T>(req: AbstractRequest, res: AbstractResponse<Auth>) => {
+      const context = service.assertCtx<Config, Context>()
+      const tokens = reCaptchaTokenOf(context)
+
+      const guest = await tokens.inspect(req)
+      if (guest == null || !await tokens.spend(guest)) {
+        return false as T
+      }
+
+      const auth: Auth = {
+        token: '',
+        type: AuthenticationType.ReCaptcha,
+        role: AuthRole.Guest,
+        userId: GUEST_ID,
+        scopes: [AUTH_SCOPE],
+        isUser: false,
+        source: context.cfg.service,
+        createdAt: new Date(),
+        expiresAt: guest.expiresAt,
+      }
+      res.resolve(auth)
+
+      return true as T
+    },
+
+    /** Server-side guard: it verifies what arrives, it never produces a credential. */
+    authenticated: async () => null,
+  })
+
+  return service
+}

package/src/re-captcha/index.ts

@@ -0,0 +1,3 @@
+export type * from './types.js'
+export * from './token.js'
+export * from './guard.js'

package/src/re-captcha/token.ts

@@ -0,0 +1,89 @@
+import { AuthenticationType, AuthRole, AuthUnavailable, GUEST_ID } from '@owlmeans/auth'
+import type { AuthCredentials } from '@owlmeans/auth'
+import { extractAuthToken, trust } from '@owlmeans/auth-common/utils'
+import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
+import type { EnvelopeModel } from '@owlmeans/basic-envelope'
+import { TRUSTED } from '@owlmeans/config'
+import { memoHelper } from '@owlmeans/context'
+import { logger } from '@owlmeans/log'
+import { RecordExists } from '@owlmeans/resource'
+import type { Resource } from '@owlmeans/resource'
+import { AUTH_CACHE, AUTH_SRV_KEY, AUTHEN_TIMEFRAME } from '../consts.js'
+import type { AuthSpent } from '../types.js'
+import type { Config, Context } from '../types.local.js'
+import type { ReCaptchaCarrier, ReCaptchaGuest, ReCaptchaTokenHelper } from './types.js'
+
+const log = logger('server-auth:re-captcha')
+
+export const makeReCaptchaTokenHelper = (context: Context): ReCaptchaTokenHelper => {
+  const refuse = (reason: string): null => {
+    log.debug('reCAPTCHA token refused', { reason }, { event: 'auth.refused' })
+    return null
+  }
+
+  const verify = async (token: string): Promise<ReCaptchaGuest | null> => {
+    let envelope: EnvelopeModel<AuthCredentials>
+    try {
+      envelope = makeEnvelopeModel<AuthCredentials>(token, EnvelopeKind.Token)
+    } catch {
+      return refuse('token')
+    }
+    if (envelope.type() !== AuthenticationType.ReCaptcha) {
+      return refuse('type')
+    }
+    // A guest token lives no longer than its spend record does, so it can never be spent twice.
+    const ttl = envelope.envelope.ttl
+    if (ttl == null || ttl > AUTHEN_TIMEFRAME) {
+      return refuse('ttl')
+    }
+
+    const signer = await trust<Config, Context>(context, TRUSTED, AUTH_SRV_KEY)
+    // Signature and expiry: an envelope past `dt + ttl` does not verify.
+    if (!await envelope.verify(signer.key)) {
+      return refuse('signature')
+    }
+
+    const credential = envelope.message<AuthCredentials>()
+    if (credential == null || typeof credential !== 'object') {
+      return refuse('token')
+    }
+    if (credential.credential !== signer.user.id) {
+      return refuse('issuer')
+    }
+    if (credential.type !== AuthenticationType.ReCaptcha || credential.role !== AuthRole.Guest
+      || credential.userId !== GUEST_ID) {
+      return refuse('guest')
+    }
+    if (typeof credential.challenge !== 'string' || credential.challenge === '') {
+      return refuse('challenge')
+    }
+
+    return { credential, challenge: credential.challenge, expiresAt: new Date(envelope.envelope.dt + ttl) }
+  }
+
+  const inspect = async (req: ReCaptchaCarrier): Promise<ReCaptchaGuest | null> => {
+    const token = extractAuthToken(req, AuthenticationType.ReCaptcha)
+
+    return token == null || token === '' ? null : await verify(token)
+  }
+
+  const spend = async (guest: ReCaptchaGuest): Promise<boolean> => {
+    try {
+      await context.resource<Resource<AuthSpent>>(AUTH_CACHE)
+        .create({ id: guest.challenge }, { ttl: AUTHEN_TIMEFRAME / 1000 })
+    } catch (error) {
+      if (error instanceof RecordExists || (error as { type?: string } | null)?.type === RecordExists.typeName) {
+        log.debug('reCAPTCHA token refused', { reason: 'spent' }, { event: 'auth.refused' })
+        return false
+      }
+      throw new AuthUnavailable('auth-cache')
+    }
+
+    return true
+  }
+
+  return { inspect, verify, spend }
+}
+
+/** The reCAPTCHA token checks of a context — built once per context. */
+export const reCaptchaTokenOf = memoHelper.oncePer(makeReCaptchaTokenHelper)

package/src/re-captcha/types.ts

@@ -0,0 +1,45 @@
+import type { AuthCredentials } from '@owlmeans/auth'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+
+/** A reCAPTCHA guest token that passed every check but the spend. */
+export interface ReCaptchaGuest {
+  /**
+   * The credential the auth manager signed: `GUEST_ID`, role Guest, type ReCaptcha, stamped with
+   * the auth service record's id. It names nobody.
+   */
+  credential: AuthCredentials
+  /** The server-issued challenge the token carries — the key it is spent under in `AUTH_CACHE`. */
+  challenge: string
+  /** When the token stops being accepted. */
+  expiresAt: Date
+}
+
+/** Anything that carries request headers: an entrypoint request, or a raw Fastify request. */
+export interface ReCaptchaCarrier extends Partial<Pick<AbstractRequest, 'headers'>> {}
+
+/**
+ * The checks of a reCAPTCHA guest token (`Authorization: RE-CAPTCHA <token>`), bound to the context
+ * whose `TRUSTED` record `AUTH_SRV_KEY` signed it and whose `AUTH_CACHE` spends it.
+ */
+export interface ReCaptchaTokenHelper {
+  /**
+   * The guest a request carries, checked WITHOUT spending: envelope type, signature by the auth
+   * service key, TTL (at most `AUTHEN_TIMEFRAME`), the auth record's stamp, type ReCaptcha, role
+   * Guest, `GUEST_ID`, a server-issued challenge. Made for a pre-parse check (before a body is read);
+   * the route itself still needs the guard, which spends.
+   *
+   * @returns `null` for a request without such a header or with a token that fails a check.
+   * @throws {SyntaxError} when the context has no `AUTH_SRV_KEY` trusted record (a configuration fault).
+   */
+  inspect: (req: ReCaptchaCarrier) => Promise<ReCaptchaGuest | null>
+  /** {@link inspect} for a bare token (the value after `RE-CAPTCHA `). */
+  verify: (token: string) => Promise<ReCaptchaGuest | null>
+  /**
+   * Spend the token: an atomic create-once of its challenge in `AUTH_CACHE` (Redis `SET NX` in a
+   * backend context), under the same key a bearer exchange and the IAM finalizer claim.
+   *
+   * @returns `false` when the token was spent before.
+   * @throws {AuthUnavailable} when the cache cannot answer.
+   */
+  spend: (guest: ReCaptchaGuest) => Promise<boolean>
+}

package/src/service.ts

@@ -4,7 +4,7 @@ import { AUTH_CACHE, AUTH_SRV_KEY, AUTHEN_TIMEFRAME, DEFAULT_ALIAS } from './con
 import type { AuthServiceAppend, AuthService, AuthSpent } from './types.js'
 import { assertContext, createService } from '@owlmeans/context'
 import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
-import { type Auth, type AuthCredentials, AuthenFailed, AuthorizationError, AuthroizationType, AuthUnavailable } from '@owlmeans/auth'
+import { type Auth, type AuthCredentials, AuthenFailed, AuthenticationType, AuthorizationError, AuthroizationType, AuthUnavailable } from '@owlmeans/auth'
 import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
 import type { Resource } from '@owlmeans/resource'
 import { createStaticResource } from '@owlmeans/static-resource'
@@ -164,7 +164,12 @@ export const makeAuthService = (alias: string = DEFAULT_ALIAS): AuthService => {
       const credentials = envelope.message()
       const msg = credentials.challenge
 
-      // @TODO This operation is not atomic in case of redis store usage and scling
+      // A reCAPTCHA token proves a solved challenge, never a person: it is spent by
+      // `makeReCaptchaGuard` on the one route that takes it and never becomes a session. Refused
+      // before the spend, so a token presented here stays usable where it belongs.
+      if (envelope.type() === AuthenticationType.ReCaptcha || credentials.type === AuthenticationType.ReCaptcha) {
+        throw refuse('guest', new AuthenFailed('guest'), credentials.userId)
+      }
 
       try {
         await cache(context).create({ id: msg }, { ttl: AUTHEN_TIMEFRAME / 1000 })