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

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'
-import { assertType } from './utils.js'
+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]
+  }
 
-export const reCaptcha = <C extends AppConfig, T extends AppContext<C>>(context: T): AuthPlugin => {
   const plugin: AuthPlugin = {
     type: AuthenticationType.ReCaptcha,
 
     init: async request => {
-      assertType(request.type, plugin)
+      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(PLUGINS)
-      const config = await cfg.get<PluginConfig>(MOD_RECAPTCHA)
-      if (config.value == null) {
-        throw new PluginMissconfigured('value')
-      }
-      const validateRecaptcha = context.entrypoint<ClientEntrypoint<RecpatchaResponse>>(MOD_RECAPTCHA)
-      const [result, status] = await validateRecaptcha.call<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/supervisor.ts

@@ -1,13 +1,11 @@
-import { AuthenticationType, AuthenFailed, AuthRole, ALL_SCOPES, buildSupervisorPayload } from '@owlmeans/auth'
-import type { SupervisorCredentialPayload } from '@owlmeans/auth'
+import { AuthenticationType, AuthenFailed, AuthRole, ALL_SCOPES, buildSupervisorPayload, type SupervisorCredentialPayload } from '@owlmeans/auth'
 import type { AuthPlugin } from './types.js'
 import { base64 } from '@scure/base'
-import { randomBytes } from '@noble/hashes/utils'
-import { fromPubKey } from '@owlmeans/basic-keys'
+import { randomBytes } from '@noble/hashes/utils.js'
+import { keyHelper } from '@owlmeans/basic-keys'
 import { TRUSTED } from '@owlmeans/config'
 import type { TrustedRecord } from '@owlmeans/auth-common'
-import type { AppConfig, AppContext } from '../types.js'
-import type { SupervisorPluginOptions } from '../supervisor.js'
+import type { AppConfig, AppContext, SupervisorPluginOptions } from '../types.js'
 
 /**
  * PK-based supervisor authentication plugin. A privileged operator (or an e2e
@@ -48,12 +46,12 @@ export const makeSupervisorPlugin = (
       let matched: string | null = null
       for (const alias of opts.supervisors) {
         try {
-          const record = await context.getConfigResource(TRUSTED)
-            .load<TrustedRecord>(alias, 'name')
+          const record = await context.getConfigResource<TrustedRecord>(TRUSTED)
+            .load({ name: alias })
           if (record?.credential == null) {
             continue
           }
-          if (await fromPubKey(record.credential).verify(payload, parsed.signature)) {
+          if (await keyHelper.fromPubKey(record.credential).verify(payload, parsed.signature)) {
             matched = alias
             break
           }
@@ -71,8 +69,8 @@ export const makeSupervisorPlugin = (
 
       credential.userId = resolution.userId
       credential.profileId = resolution.profileId ?? resolution.userId
-      if (resolution.entityId != null) {
-        credential.entityId = resolution.entityId
+      if (resolution.entitySlug != null) {
+        credential.entitySlug = resolution.entitySlug
       }
       credential.scopes = resolution.scopes ?? credential.scopes ?? [ALL_SCOPES]
       credential.role = resolution.role ?? AuthRole.User

package/src/manager/plugins/types.ts

@@ -1,27 +1,36 @@
 import type { AllowanceResponse } from '@owlmeans/auth'
-import type { AuthModel } from '../types.js'
-import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { AppConfig, AppContext, AuthModel } from '../types.js'
 import type { RedisResource } from '@owlmeans/redis-resource'
 import type { ResourceRecord } from '@owlmeans/resource'
+import type { AuthChallengeReplayPolicy } from './consts.js'
 
 export interface AuthPlugin extends Omit<AuthModel, "rely"> {
   type: string
+  /**
+   * Who atomically consumes a verified challenge. The manager remains the default; a plugin may
+   * opt in only when its own credential protocol needs a bounded retry budget before consumption.
+   */
+  challengeReplayPolicy?: AuthChallengeReplayPolicy
 }
 
-export interface RecpatchaResponse {
-  success: boolean
-  challenge_ts: number
-  hostname: string
-  'error-codes'?: string[]
+export interface RelyRecord extends ResourceRecord, AllowanceResponse {
 }
 
-export interface RecaptchaRequest extends AbstractRequest<{
-  secret: string
-  response: string
-  remoteip?: string
-}> { }
+export interface AuthRedisResource extends RedisResource<RelyRecord> {}
 
-export interface RelyRecord extends ResourceRecord, AllowanceResponse {
+/** Builds the plugin of one authentication type over the context it serves. */
+export interface AuthPluginFactory {
+  <C extends AppConfig, T extends AppContext<C>>(context: T): AuthPlugin
 }
 
-export interface AuthRedisResource extends RedisResource<RelyRecord> {}
+/** Resolution of the registered plugins, and the check every plugin runs on what it is handed. */
+export interface AuthPluginHelper {
+  /** @throws {TypeMissmatchError} when a request names another plugin's type */
+  assertType: (type: string, plugin: AuthPlugin) => void
+  /**
+   * The registered plugin of a type, built over the context.
+   *
+   * @throws {AuthUnknown}
+   */
+  getPlugin: (type: string, context: AppContext<AppConfig>) => Promise<AuthPlugin>
+}

package/src/manager/plugins/utils.ts

@@ -1,21 +1,31 @@
 import { AuthUnknown, TypeMissmatchError } from '@owlmeans/auth'
-import type { AuthPlugin } from './types.js'
+import type { AuthPlugin, AuthPluginHelper } from './types.js'
 import type { AppContext, AppConfig } from '../types.js'
 
-export const assertType = (type: string, plugin: AuthPlugin) => {
-  if (type !== plugin.type) {
-    throw new TypeMissmatchError(plugin.type)
+export const createAuthPluginHelper = (): AuthPluginHelper => {
+  const assertType = (type: string, plugin: AuthPlugin): void => {
+    if (type !== plugin.type) {
+      throw new TypeMissmatchError(plugin.type)
+    }
   }
-}
 
-/**
- * @throws {AuthUnknown}
- */
-export const getPlugin = async (type: string, context: AppContext<AppConfig>): Promise<AuthPlugin> => {
-  const { plugins } = await import('./index.js')
-  const plugin = plugins[type]
-  if (plugin == null) {
-    throw new AuthUnknown(type)
+  const getPlugin = async (type: string, context: AppContext<AppConfig>): Promise<AuthPlugin> => {
+    const { plugins } = await import('./index.js')
+    const plugin = plugins[type]
+    if (plugin == null) {
+      throw new AuthUnknown(type)
+    }
+    return plugins[type](context)
   }
-  return plugins[type](context)
+
+  return { assertType, getPlugin }
 }
+
+export const authPluginHelper = createAuthPluginHelper()
+
+/** @deprecated compat:factory-refactor — use `authPluginHelper.assertType(…)` */
+export const assertType = (type: string, plugin: AuthPlugin): void => authPluginHelper.assertType(type, plugin)
+
+/** @deprecated compat:factory-refactor — use `authPluginHelper.getPlugin(…)` */
+export const getPlugin = async (type: string, context: AppContext<AppConfig>): Promise<AuthPlugin> =>
+  await authPluginHelper.getPlugin(type, context)

package/src/manager/rely/flow.ts

@@ -1,7 +1,6 @@
 import type { AllowanceRequest, Auth, AuthCredentials, RelyToken } from '@owlmeans/auth'
 import { AUTH_SCOPE, AuthenticationStage, AuthenticationType, AuthPluginError, AuthRole, RELY_3RD } from '@owlmeans/auth'
 import type { AuthenticateMethod, Connection, EventMessage, Message } from '@owlmeans/socket'
-import { isEventMessage, isMessage } from '@owlmeans/socket'
 import type { AppContext, RelyAllowanceRequest, RelyLinker, RelyCarrier } from '../types.js'
 import { makeAuthModel } from '../model.js'
 import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
@@ -9,6 +8,8 @@ import { trusted } from '../utils/trusted.js'
 import { RELY_TUNNEL } from '../consts.js'
 import type { RedisResource } from '@owlmeans/redis-resource'
 import { RELY_ACTION_TIMEOUT } from '@owlmeans/auth-common'
+import { logger } from '@owlmeans/log'
+import { socketMessageHelper } from '@owlmeans/socket'
 
 // 1. There is a difference between privileged (provider)
 //    and non-privileged (consumer) request 
@@ -20,6 +21,8 @@ import { RELY_ACTION_TIMEOUT } from '@owlmeans/auth-common'
 //    process can be started from scratch following same stages
 //    and using the same plugins but via socket
 
+const log = logger('server-auth:rely')
+
 export const createRelyFlow = (context: AppContext, conn: Connection, auth?: Auth | null): AuthenticateMethod => {
   const auhtenticate = conn.authenticate
 
@@ -29,29 +32,29 @@ export const createRelyFlow = (context: AppContext, conn: Connection, auth?: Aut
   const linker: RelyLinker = async (rely, source, notify) => {
     const tunnel = context.resource<RedisResource<Message<any>>>(RELY_TUNNEL)
     const closeReceiver = await tunnel.subscribe(async message => {
-      if (isMessage(message, true)) {
+      if (socketMessageHelper.isMessage(message, true)) {
         await conn.send(message)
-      } else if (isEventMessage(message, true)) {
+      } else if (socketMessageHelper.isEventMessage(message, true)) {
         if ((message as EventMessage<unknown>).event === 'close') {
           await conn.close()
           closeSender()
           await closeReceiver()
         }
       }
-    }, source.nonce)
+    }, { channel: source.nonce })
     // We allow to just forward call messages back and forth
-    conn._receiveCall = async msg => { console.info(source.nonce, 'Forward call', msg.method, msg.id) }
-    conn._receiveResult = async msg => { console.info(source.nonce, 'Forward result', msg.id) }
-    conn._receiveError = async msg => { console.info(source.nonce, 'Forward error', msg.id) }
+    conn._receiveCall = async msg => { log.debug('Forward call', { nonce: source.nonce, method: msg.method, id: msg.id }) }
+    conn._receiveResult = async msg => { log.debug('Forward result', { nonce: source.nonce, id: msg.id }) }
+    conn._receiveError = async msg => { log.debug('Forward error', { nonce: source.nonce, id: msg.id }) }
     conn.defaultCallTimeout = RELY_ACTION_TIMEOUT * 1000
     const closeSender = conn.listen(async message => {
-      if (isMessage(message, true)) {
+      if (socketMessageHelper.isMessage(message, true)) {
         const forward = { ...message }
         if (forward.rawData != null) {
           delete forward.rawData
         }
         await tunnel.publish(forward, rely.nonce)
-      } else if (isEventMessage(message, true)) {
+      } else if (socketMessageHelper.isEventMessage(message, true)) {
         if (message.event === 'close') {
           const forward = { ...message as Message<unknown> }
           if (forward.rawData != null) {
@@ -94,7 +97,7 @@ export const createRelyFlow = (context: AppContext, conn: Connection, auth?: Aut
         try {
           return [stage, await model.init(_payload as AllowanceRequest) as any]
         } catch (e) {
-          console.error(e)
+          log.warn('Rely init failed; connection closed', e)
           await conn.close()
         }
         break
@@ -118,7 +121,7 @@ export const createRelyFlow = (context: AppContext, conn: Connection, auth?: Aut
 
           return [AuthenticationStage.Authenticated, internalAuth as any]
         } catch (e) {
-          console.error(e)
+          log.warn('Rely authentication failed; connection closed', e)
           await conn.close()
         }
         break

package/src/manager/rely.ts

@@ -1,18 +1,15 @@
 import { assertContext, createService } from '@owlmeans/context'
 import { DEFAULT_RELY } from './consts.js'
 import type { AppContext, RelyService } from './types.js'
-import { AUTH_QUERY, AuthenFailed, AuthenticationType } from '@owlmeans/auth'
-import type { Auth, AuthCredentials, AuthToken } from '@owlmeans/auth'
+import { AUTH_QUERY, AuthenFailed, AuthenticationType, type Auth, type AuthCredentials, type AuthToken } from '@owlmeans/auth'
 import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
 import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import { AUTH_CACHE, AUTHEN_TIMEFRAME } from '../consts.js'
 import type { AuthSpent } from '../types.js'
 import type { Resource } from '@owlmeans/resource'
 import { trusted } from './utils/trusted.js'
+import type { Config, Context } from './types.local.js'
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
 
 export const createRelyService = (alias: string = DEFAULT_RELY): RelyService => {
   const _keyPair = async (context: Context) => {

package/src/manager/supervisor.ts

@@ -1,71 +1,25 @@
 import { AuthenticationType } from '@owlmeans/auth'
-import type { AuthPayload } from '@owlmeans/auth'
 import { DEFAULT_GUARD } from '@owlmeans/auth-common'
-import type { AppConfig, AppContext } from './types.js'
+import type { AppConfig, AppContext, SupervisorAuthOptions, SupervisorPluginOptions } from './types.js'
+import type { AuthPluginFactory } from './plugins/types.js'
 import { registerPlugin } from './plugins/index.js'
 import { makeSupervisorPlugin } from './plugins/supervisor.js'
-
-/**
- * What a `SupervisorUserResolver` returns: the identity the supervisor-minted
- * token will represent. Only `userId` is required - the rest default sensibly.
- */
-export interface SupervisorUserResolution extends Partial<Pick<AuthPayload,
-  'profileId' | 'entityId' | 'role' | 'scopes'>> {
-  userId: string
-}
-
-/**
- * Find-or-create the target identity for a supervisor login. `register` reflects
- * `allowRegistration`; when false the resolver should only look existing users up.
- * Wire this to the project's identity store (e.g. `@owlmeans/server-auth-identity`).
- */
-export interface SupervisorUserResolver {
-  <C extends AppConfig, T extends AppContext<C>>(
-    userId: string, context: T, opts: { register: boolean }
-  ): Promise<SupervisorUserResolution>
-}
-
-/** Resolved options handed to the plugin factory. */
-export interface SupervisorPluginOptions {
-  supervisors: string[]
-  allowRegistration: boolean
-  resolveUser?: SupervisorUserResolver
-}
-
-export interface SupervisorAuthOptions {
-  /** Trusted-record aliases authorized to act as supervisor. Default: master + superuser. */
-  supervisors?: string[]
-  /** Find-or-create the target user by id/email. Default: trust the id as-is. */
-  resolveUser?: SupervisorUserResolver
-  /** Allow minting a token for an unknown user (registration). Default: true. */
-  allowRegistration?: boolean
-  /** Force enable/disable. Default: development only (cfg.debug.all || cfg.debug.supervisor). */
-  enabled?: boolean
-  /**
-   * Also accept internal owlmeans `Ed25519BasicToken`s even when another guard
-   * (e.g. OIDC) is the primary guard on protected modules. Default: true.
-   */
-  acceptInternalTokens?: boolean
-  /** The internal-token guard to add as a coguard. Default: DEFAULT_GUARD ('auth'). */
-  guard?: string
-}
-
-const DEFAULT_SUPERVISORS = ['master', 'superuser']
+import { DEFAULT_SUPERVISORS } from './consts.local.js'
 
 const isDevelopment = (context: { cfg: { debug?: { all?: boolean, supervisor?: boolean } } }): boolean =>
   context.cfg.debug?.all === true || context.cfg.debug?.supervisor === true
 
 /**
  * Ensure the internal `Ed25519BasicToken` guard is accepted as a coguard on every
- * already-guarded backend module, so internal owlmeans tokens keep working even
+ * already-guarded backend entrypoint, so internal owlmeans tokens keep working even
  * when another guard (e.g. OIDC) is the primary guard. The primary guard stays
  * first; the internal guard is appended as a fallback (its `match` only fires for
  * an `Ed25519BasicToken` authorization header).
  */
 export const setupInternalTokenCoguard = (
-  modules: Array<{ guards?: string[] }>, guard: string = DEFAULT_GUARD
+  entrypoints: Array<{ guards?: string[] }>, guard: string = DEFAULT_GUARD
 ): void => {
-  modules.forEach(module => {
+  entrypoints.forEach(module => {
     if (module.guards != null && module.guards.length > 0 && !module.guards.includes(guard)) {
       module.guards.push(guard)
     }
@@ -78,7 +32,7 @@ export const setupInternalTokenCoguard = (
  *
  * It registers the supervisor auth plugin (verifies a front-end signature against
  * the allowlisted trusted keys, then resolves/registers the target user) and -
- * unless disabled - makes protected modules also accept internal owlmeans tokens
+ * unless disabled - makes protected entrypoints also accept internal owlmeans tokens
  * (requirement: understand internal tokens even when OIDC is the primary guard).
  */
 export const appendSupervisorAuth = <C extends AppConfig, T extends AppContext<C>>(
@@ -97,7 +51,7 @@ export const appendSupervisorAuth = <C extends AppConfig, T extends AppContext<C
 
   registerPlugin(
     AuthenticationType.Supervisor,
-    (ctx => makeSupervisorPlugin(ctx as unknown as AppContext<AppConfig>, resolved)) as Parameters<typeof registerPlugin>[1]
+    (ctx => makeSupervisorPlugin(ctx as unknown as AppContext<AppConfig>, resolved)) as AuthPluginFactory
   )
 
   if (opts?.acceptInternalTokens !== false) {

package/src/manager/types.local.ts

@@ -0,0 +1,5 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+export type Config = ServerConfig
+
+export type Context = ServerContext<Config>

package/src/manager/types.ts

@@ -1,4 +1,4 @@
-import type { AllowanceRequest, AllowanceResponse, Auth, AuthCredentials, AuthToken, RelyToken } from '@owlmeans/auth'
+import type { AllowanceRequest, AllowanceResponse, Auth, AuthCredentials, AuthToken, RelyToken, AuthPayload } from '@owlmeans/auth'
 import type { KlusterConfig } from '@owlmeans/kluster'
 import type { GuardService } from '@owlmeans/entrypoint'
 import type { ApiServerAppend } from '@owlmeans/server-api'
@@ -40,3 +40,48 @@ export interface RelyCarrier {
   source: RelyToken,
   rely: RelyToken
 }
+
+/**
+ * What a `SupervisorUserResolver` returns: the identity the supervisor-minted
+ * token will represent. Only `userId` is required - the rest default sensibly.
+ */
+export interface SupervisorUserResolution extends Partial<Pick<AuthPayload,
+  'profileId' | 'entitySlug' | 'role' | 'scopes'>> {
+  userId: string
+}
+
+/**
+ * Find-or-create the target identity for a supervisor login. `register` reflects
+ * `allowRegistration`; when false the resolver should only look existing users up.
+ * Wire this to the project's identity store (e.g. `@owlmeans/server-auth-identity`).
+ */
+export interface SupervisorUserResolver {
+  <C extends AppConfig, T extends AppContext<C>>(
+    userId: string, context: T, opts: { register: boolean }
+  ): Promise<SupervisorUserResolution>
+}
+
+/** Resolved options handed to the plugin factory. */
+export interface SupervisorPluginOptions {
+  supervisors: string[]
+  allowRegistration: boolean
+  resolveUser?: SupervisorUserResolver
+}
+
+export interface SupervisorAuthOptions {
+  /** Trusted-record aliases authorized to act as supervisor. Default: master + superuser. */
+  supervisors?: string[]
+  /** Find-or-create the target user by id/email. Default: trust the id as-is. */
+  resolveUser?: SupervisorUserResolver
+  /** Allow minting a token for an unknown user (registration). Default: true. */
+  allowRegistration?: boolean
+  /** Force enable/disable. Default: development only (cfg.debug.all || cfg.debug.supervisor). */
+  enabled?: boolean
+  /**
+   * Also accept internal owlmeans `Ed25519BasicToken`s even when another guard
+   * (e.g. OIDC) is the primary guard on protected entrypoints. Default: true.
+   */
+  acceptInternalTokens?: boolean
+  /** The internal-token guard to add as a coguard. Default: DEFAULT_GUARD ('auth'). */
+  guard?: string
+}

package/src/model/rely/consumer.ts

@@ -1,7 +1,9 @@
 import { makeRelyModel } from './peer.js'
+import type { RelyToken } from '@owlmeans/auth'
+import type { EnvelopeModel } from '@owlmeans/basic-envelope'
 import type { RelyOptions } from './types.js'
 
-export const makeConsumerRely = (opts?: RelyOptions) => {
+export const makeConsumerRely = (opts?: RelyOptions): EnvelopeModel<RelyToken> => {
   const model = makeRelyModel(opts)
   const msg = model.message()
   delete msg.pin

package/src/model/rely/peer.ts

@@ -7,6 +7,14 @@ import { base58 } from '@scure/base'
 import type { RelyOptions } from './types.js'
 import { RELY_CALL_TIMEOUT } from '@owlmeans/auth-common'
 
+const toNumber = (bytes: Uint8Array): string => {
+  let pinInt = 0n
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    pinInt = (pinInt << 8n) | BigInt(bytes[i]);
+  }
+  return pinInt.toString()
+}
+
 export const makeRelyModel = (opts?: RelyOptions): EnvelopeModel<RelyToken> => {
   const envelope = makeEnvelopeModel<RelyToken>(RELY_3RD)
 
@@ -33,11 +41,3 @@ export const makeRelyModel = (opts?: RelyOptions): EnvelopeModel<RelyToken> => {
 
   return envelope
 }
-
-const toNumber = (bytes: Uint8Array): string => {
-  let pinInt = 0n
-  for (let i = bytes.length - 1; i >= 0; i--) {
-    pinInt = (pinInt << 8n) | BigInt(bytes[i]);
-  }
-  return pinInt.toString()
-}

package/src/model/rely/provider.ts

@@ -1,8 +1,10 @@
 
 import { makeRelyModel } from './peer.js'
+import type { RelyToken } from '@owlmeans/auth'
+import type { EnvelopeModel } from '@owlmeans/basic-envelope'
 import type { RelyOptions } from './types.js'
 
-export const makeProviderRely = (opts?: RelyOptions) => {
+export const makeProviderRely = (opts?: RelyOptions): EnvelopeModel<RelyToken> => {
   const model = makeRelyModel(opts)
 
   return model

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'