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

package/README.md

@@ -1,72 +1,250 @@
 # @owlmeans/server-auth
 
-Server-side Ed25519 authentication service for OwlMeans backends.
-
-## Overview
-
-- Implements the `GuardService` interface for Ed25519-signed token verification
-- `appendAuthService()` registers the auth guard into a server context
-- `DEFAULT_ALIAS` (`'auth'`) is the service alias and re-exported as `DAUTH_GUARD` via `@owlmeans/server-app`
-- Handles token caching via a static resource identified by `AUTH_CACHE`
+The server side of OwlMeans authentication, in two halves. The root export is what every protected
+API service needs: the guard that verifies an Ed25519-signed bearer token and resolves
+`request.auth`, and the dispatcher bindings that exchange a credential issued by the auth manager
+for a bearer of this service. The `./manager` subpath is the auth manager application itself — the
+challenge endpoints, the authentication plugin registry, the signed credential envelope and the rely
+handshake. An ordinary service imports the root (usually implicitly, through
+`@owlmeans/server-app`'s `makeContext`); only the auth manager imports `./manager`. OIDC tokens are
+`@owlmeans/server-oidc-rp`, long-lived API keys `@owlmeans/server-auth-token`, local
+account/profile records `@owlmeans/server-auth-identity`, and the browser side `@owlmeans/client-auth`.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-auth
+bun add @owlmeans/server-auth@^0.1.18
 ```
 
+## Concepts
+
+- **Guard** — the `AuthService` registered as `auth` (the value of `DEFAULT_GUARD`). `match` hits a
+  request carrying an `ed25519-basic-token`; `handle` verifies it against this service's own trusted
+  key (`cfg.alias ?? cfg.service`) and resolves the `Auth`. It authenticates only — authorization is
+  gates and handlers.
+- **Token exchange** — `authenticate(token)` verifies a credential envelope against the
+  `auth-service` trusted record (`AUTH_SRV_KEY`), burns its challenge into `AUTH_CACHE`, and returns
+  a bearer signed by this service.
+- **`AUTH_CACHE`** — the anti-replay store: each challenge is created once with an
+  `AUTHEN_TIMEFRAME` TTL. A static in-process resource by default.
+- **Auth manager** — the `./manager` application: `init(request)` returns a challenge,
+  `authenticate(credential)` returns a signed credential envelope, and the slug on the credential is
+  canonicalized through the entity resolver before signing.
+- **Authentication plugin** — `{ type, init, authenticate }` registered under an
+  `AuthenticationType`; the manager dispatches by the request's `type`.
+- **Rely** — the wallet handshake that lets one authenticated party vouch for another over a socket
+  (`DEFAULT_RELY` guard, `RELY_TUNNEL`).
+
 ## Usage
 
-Registered automatically by `makeContext()` from `@owlmeans/server-app`. To customize, pass `customize: true` and append manually:
+### Protect routes on an ordinary service
 
-```typescript
-import { makeContext } from '@owlmeans/server-app'
-import { appendAuthService, AUTH_CACHE } from '@owlmeans/server-auth'
+`@owlmeans/server-app`'s `makeContext(cfg)` registers the guard. A protocol opts in with `guards`,
+and everything declared under it inherits them.
 
-const context = makeContext(appConfig, true)  // skip default auth
+```ts
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { route, RouteMethod } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
 
-// Append auth with custom config
-appendAuthService(context)
+const invoiceBase = openProtocol(route('my-app:api:invoice', '/invoice'), { guards: DEFAULT_GUARD })
+
+export const invoiceProtocols = {
+  base: invoiceBase,
+  list: protocol(
+    route('my-app:api:invoice:list', '/', { parent: invoiceBase, method: RouteMethod.GET }),
+    contract(typed<Invoice[]>()),
+  ),
+}
 ```
 
-Reference the guard by alias when protecting routes:
+```ts
+import { handlers } from '@owlmeans/server-app'
+import { makeEntityScope } from '@owlmeans/auth-common'
 
-```typescript
-import { DAUTH_GUARD } from '@owlmeans/server-app'
-// same as DEFAULT_ALIAS from @owlmeans/server-auth
+const api = handlers<Context>()
 
-const adminModule = module(route('admin', '/admin'), guard(DAUTH_GUARD))
+export const list = api.request(invoiceProtocols.list, async (request, context) => {
+  // request.auth is the verified Auth: userId, profileId, role, scopes, entitySlug
+  const { items } = await context.invoice().list({ entityId: makeEntityScope(request).requireEntityKey() })
+  return items
+})
 ```
 
-## API
+### Scaled deployment
+
+Replace the in-process cache with a shared one before registering the guard, and declare the trusted
+keys the guard verifies against.
+
+```ts
+import { makeContext as makeAppContext } from '@owlmeans/server-app'
+import { appendRedis } from '@owlmeans/redis'
+import { makeRedisResource } from '@owlmeans/redis-resource'
+import { appendAuthService, AUTH_CACHE, AUTH_SRV_KEY } from '@owlmeans/server-auth'
+import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
+
+// config.ts — keys are loaded from the environment, never committed
+cfg.trusted.push({
+  id: process.env.AUTH_SERVICE_DID!, name: AUTH_SRV_KEY,
+  credential: process.env.AUTH_SERVICE_PUB!, scopes: ['*'],
+})
+cfg.trusted.push({
+  id: process.env.MY_APP_API_DID!, name: MY_APP_API,
+  credential: process.env.MY_APP_API_PUB!, secret: process.env.MY_APP_API_PK!, scopes: ['*'],
+})
+
+// context.ts
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeAppContext<C, T>(cfg, true)
+  appendRedis<C, T>(context)
+
+  context.registerResource(makeRedisResource(AUTH_CACHE))
+  appendAuthService<C, T>(context)
+  appendAuthIdentityResources(context)
+
+  return context
+}
+```
+
+### Verify a token outside the HTTP pipeline
+
+```ts
+import type { AuthServiceAppend } from '@owlmeans/server-auth'
+
+const readAuth = async (context: Context & AuthServiceAppend, authorization: string) =>
+  context.auth().unpack(authorization) // 'ED25519-BASIC-TOKEN <envelope>' -> Auth, or throws
+```
+
+### Run the auth manager
+
+```ts
+import { config, makeContext, main } from '@owlmeans/server-auth/manager'
+import type { AppConfig } from '@owlmeans/server-auth/manager'
+import '@owlmeans/server-oidc-rp/auth/plugins' // optional: OIDC and Google login plugins
+
+const cfg = config<AppConfig>(MY_APP_AUTH, commonConfig as AppConfig)
+const context = makeContext(cfg)
+
+await main(context)
+```
+
+### Add an authentication method
+
+```ts
+import { registerPlugin } from '@owlmeans/server-auth/manager/plugins'
+import type { AuthPlugin } from '@owlmeans/server-auth/manager/plugins'
 
-### `appendAuthService<C, T>(context): void`
+registerPlugin('my-method', context => ({
+  type: 'my-method',
+  init: async request => ({ challenge: /* unique per request */ '' }),
+  authenticate: async credential => {
+    // verify credential.credential, then set userId / profileId / entitySlug / role / scopes
+    return { token: '' } // '' keeps the manager's own challenge as the credential token
+  },
+}) as AuthPlugin)
+```
+
+### Accept a reCAPTCHA-proven guest on one route
+
+The manager's reCAPTCHA plugin signs a GUEST token (`GUEST_ID`, role Guest, `[AUTH_SCOPE]`) whatever
+identity the caller posts. A route takes it through the reCAPTCHA guard, which spends it once:
+
+```ts
+import { CMOD_RECAPTCHA, MOD_RECAPTCHA, RECAPTCHA_GUARD } from '@owlmeans/auth'
+import { clientPlugin, plugin } from '@owlmeans/config'
+import { makeReCaptchaGuard, reCaptchaTokenOf } from '@owlmeans/server-auth'
 
-Registers the Ed25519 auth service and its nonce cache resource into the context.
+// config: the secret plus the policy (strings, '' = no check), and the browser's site key
+plugin(cfg, {
+  value: '/etc/master-secret/recaptcha-secret',
+  hostnames: 'example.org, example.com', minScore: '0.5', actions: 'inquiry',
+}, MOD_RECAPTCHA)
+clientPlugin(cfg, '/etc/app-config/recaptcha-site-key', CMOD_RECAPTCHA)
+
+// context: the guard of the route's `guards: [RECAPTCHA_GUARD]` (`Authorization: RE-CAPTCHA <token>`)
+context.registerService(makeReCaptchaGuard())
+// a pre-parse check that does not spend:
+const guest = await reCaptchaTokenOf(context).inspect(request) // null = 401
+```
+
+## API
 
-### `makeAuthService(alias?): AuthService`
+### Root export
 
-Creates the auth service directly (used internally by `appendAuthService`).
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendAuthService(ctx, alias = DEFAULT_ALIAS)` | function | Register the guard as `context.auth()`; registers a static `AUTH_CACHE` when the context has none |
+| `makeAuthService(alias?)` | function | The guard: `match`, `handle`, `unpack(token)`, `authenticate(token)` |
+| `entrypoints` | const | Server bindings of `authProtocols.dispatcher` and `authProtocols.dispatcherAuthenticate` |
+| `DEFAULT_ALIAS` | const | `'auth'` — equals `DEFAULT_GUARD`; re-exported as `DAUTH_GUARD` by `@owlmeans/server-app` |
+| `AUTH_CACHE` | const | `'auth-cache'` — the single-use challenge store |
+| `AUTH_SRV_KEY` | const | `'auth-service'` — the trusted record whose key signs credential envelopes |
+| `AUTHEN_TIMEFRAME` | const | `15 * 60 * 1000` ms — challenge lifetime and anti-replay window |
+| `makeRelyModel`, `makeProviderRely`, `makeConsumerRely` | function | Rely envelope models |
+| `AuthService`, `AuthServiceAppend`, `AuthSpent`, `RelyOptions` | type | Guard service, context mixin, cache record, rely options |
+| `makeReCaptchaGuard(alias = RECAPTCHA_GUARD)` | function | Guard of a route a reCAPTCHA guest calls once: verifies and spends `RE-CAPTCHA <token>` |
+| `makeReCaptchaTokenHelper(ctx)`, `reCaptchaTokenOf(ctx)` | function | `inspect(req)` / `verify(token)` (no spend) and `spend(guest)` |
+| `ReCaptchaGuest`, `ReCaptchaCarrier`, `ReCaptchaTokenHelper` | type | Inspection result, header carrier, token checks |
 
-### `DEFAULT_ALIAS`
+### `./manager`
 
-The auth service alias: `'auth'`. Re-exported as `DAUTH_GUARD` from `@owlmeans/server-app`.
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeContext(cfg, customize?)` | function | Server context with API server, API client, socket service, rely guard and static `AUTH_CACHE` |
+| `main(ctx)` | function | Register the manager entrypoints, init and listen |
+| `entrypoints` | const | Bindings for authen, init, authenticate, rely and api-config |
+| `authenticationInit`, `authenticate`, `rely` | function | Implementations bound to the auth protocols |
+| `plugins`, `registerPlugin(type, factory)` | const / function | The plugin registry |
+| `appendSupervisorAuth(ctx, opts?)`, `setupInternalTokenCoguard(entrypoints, guard?)` | function | PK supervisor login (development only by default) |
+| `createRelyService(alias?)`, `createRelyFlow(context, conn, auth?)` | function | Rely guard service and socket authentication flow |
+| `DEFAULT_RELY`, `RELY_TUNNEL` | const | `'auth-rely'`, `'rely-tunnel'` |
+| `config`, `service`, `TRUSTED`, `addWebService`, `AppType`, `assertContext`, `klusterize`, `stab`, `backend`, `filterObject` | re-export | Config and context helpers for a manager app |
+| `handleIntermediate`, `handleBody`, `handleRequest`, `handleParams` | re-export | `@owlmeans/server-api` wrappers |
+| `AUTHEN`, `AUTHEN_AUTHEN`, `AUTHEN_INIT`, `GUARD_ED25519`, `BED255_CASHE_RESOURCE` | re-export | Auth aliases |
+| `AppConfig`, `AppContext`, `AuthModel`, `RelyService`, `RelyAllowanceRequest`, `RelyLinker`, `RelyCarrier` | type | Manager shapes |
+| `SupervisorAuthOptions`, `SupervisorUserResolver`, `SupervisorUserResolution`, `SupervisorPluginOptions` | type | Supervisor options |
+| `TrustedRecord`, `RefedEntrypointHandler`, `AbstractRequest`, `AbstractResponse` | type | Re-exported types |
 
-### `AUTH_CACHE`
+### `./manager/plugins`
 
-Resource alias for the nonce replay-prevention cache.
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `registerPlugin(type, factory)`, `plugins` | function / const | The module-level registry |
+| `authPluginHelper.getPlugin(type, context)`, `authPluginHelper.assertType(type, plugin)` | method | Resolution; `getPlugin` throws `AuthUnknown(type)` for an unregistered type |
+| `makeBasicEd25519Plugin`, `makeReCaptchaPlugin`, `makeBasicRelyPlugin` | function | Built-in plugin factories |
+| `makeSupervisorPlugin(context, opts)` | function | PK supervisor plugin factory |
+| `createReCaptchaVerifierService(alias?, opts?)`, `appendReCaptchaVerifierService(ctx, alias?, opts?)` | function | Google siteverify over `fetch` (https only); the plugin's seam |
+| `makeReCaptchaPolicyModel(record)` | function | The `MOD_RECAPTCHA` record's policy: `hostnames()`, `minScore()`, `actions()`, `assert(answer)` |
+| `RECAPTCHA_VERIFIER`, `RECAPTCHA_SITEVERIFY_URL`, `RECAPTCHA_VERIFY_TIMEOUT` | const | `'re-captcha-verifier'`, Google's endpoint, 10 s |
+| `AuthPlugin`, `AuthPluginFactory`, `AuthPluginHelper`, `RelyRecord`, `AuthRedisResource` | type | Plugin shapes |
+| `ReCaptchaResponse`, `ReCaptchaRequest`, `ReCaptchaVerifierService`, `ReCaptchaVerifierOptions`, `ReCaptchaFetch`, `ReCaptchaPluginConfig`, `ReCaptchaPolicyModel` | type | reCAPTCHA shapes |
 
-## Product-Viable Integration Notes
+## Common pitfalls
 
-- Register `appendAuthService(context)` before `appendAuthIdentityResources(context)` and product-specific gate services.
-- Register `AUTH_CACHE` explicitly as a Redis resource when customizing the backend context.
-- This package verifies bearer tokens and populates `request.auth`; authorization remains the job of module gates and handler-level entity checks.
-- Pair it with `@owlmeans/server-auth-identity` when external provider login should produce durable local account/profile/credentials records.
+- The guard verifies a bearer and sets `request.auth`; it decides nothing about ownership. Pair it
+  with gates and keep a handler-level organization check.
+- The default static `AUTH_CACHE` is correct for one replica only. Register a Redis resource under
+  the same alias before `appendAuthService` in any scaled deployment.
+- A plugin's `init` must return a challenge unique per request; a repeated challenge collides in
+  `AUTH_CACHE` and fails as `AuthenFailed('challenge')`.
+- The manager replaces whatever slug a plugin sets on `credential.entitySlug` with the current slug;
+  an unresolvable value fails as `AuthenFailed('entity')`. A token carries `entitySlug`, never an
+  entity id.
+- Register `appendAuthService` before `appendAuthIdentityResources` and product gate services.
+- Import `./manager` only in the auth manager process.
+- A reCAPTCHA token is a guest token: the bearer exchange (`authenticate`) refuses it, and only
+  `makeReCaptchaGuard` accepts it — once.
 
-## Related Packages
+## Related packages
 
-- [`@owlmeans/auth-common`](../auth-common) — `GUARD_ED25519` constant and auth modules
+- [`@owlmeans/auth`](../auth) — `Auth`, `AuthCredentials`, error classes
+- [`@owlmeans/auth-common`](../auth-common) — `DEFAULT_GUARD`, `authProtocols`, `trust()`, entity helpers
+- [`@owlmeans/server-auth-identity`](../server-auth-identity) — local identity records and the entity resolver
+- [`@owlmeans/server-oidc-rp`](../server-oidc-rp) — OIDC login plugins and guard
+- [`@owlmeans/server-auth-otp`](../server-auth-otp) — email OTP plugin
+- [`@owlmeans/server-auth-token`](../server-auth-token) — long-lived access tokens
 - [`@owlmeans/server-app`](../server-app) — `makeContext` calls `appendAuthService` by default
+- [`@owlmeans/client-auth`](../client-auth) — the browser side
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -76,7 +254,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/server-auth",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-21T09:53:56.640Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.722Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -11,6 +11,13 @@
       "category": "package-specific",
       "file": "skills/server-auth/SKILL.md",
       "canonicalPath": ".agents/skills/server-auth/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "supervisor-auth",
+      "category": "multi-package",
+      "file": "skills/supervisor-auth/SKILL.md",
+      "canonicalPath": ".agents/skills/supervisor-auth/SKILL.md"
     }
   ]
 }

package/agent-meta/skills/server-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-auth
-description: How to use @owlmeans/server-auth — server-side authentication manager, AUTH_API alias, setupAuthServiceModules() to wire auth modules into your app. Auto-invoked when importing auth manager primitives.
+description: How to use @owlmeans/server-auth — the server side of OwlMeans authentication. Two halves in one package - appendAuthService/makeAuthService, which verify Ed25519 bearer tokens on an ordinary API server, and the ./manager subpath, which IS the auth manager service (challenge, plugin registry, credential envelope, rely). Also the reCAPTCHA guest path - the plugin's verifier and policy record, and makeReCaptchaGuard, which spends a guest token once. Auto-invoked when importing the server auth guard or the reCAPTCHA guard, registering an auth plugin, or building the auth manager.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,41 +8,180 @@ user-invocable: false
 # @owlmeans/server-auth
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-auth": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/server-auth": "^0.1.18"` in `dependencies`
 
-## Key Exports
+Two halves, deliberately split by subpath:
+
+- the **root** export is what every protected API server needs — the guard that verifies an
+  `Ed25519BasicToken` bearer and resolves an `Auth`;
+- **`./manager`** is the auth manager application itself — it serves `/authentication/init` and
+  `/authentication/authenticate`, owns the plugin registry, and signs the credential envelope.
+
+An ordinary service imports the root. Only the auth manager imports `./manager`.
+
+## Key Exports — root
+
+| Export | Description |
+|--------|-------------|
+| `appendAuthService(ctx, alias?)` | Register the guard on a server context and expose it as `context.auth()`. Registers a static `AUTH_CACHE` resource when the context has none |
+| `makeAuthService(alias?)` | The guard service itself: `match`, `handle`, `unpack(token)`, `authenticate(token)` |
+| `entrypoints` | `DISPATCHER` and `DISPATCHER_AUTHEN`, server-bound — spread these into a service that accepts a manager-issued credential and exchanges it for a bearer |
+| `DEFAULT_ALIAS` | `'auth'` — the guard's service alias, matching `DEFAULT_GUARD` |
+| `AUTH_CACHE` | `'auth-cache'` — the single-use challenge store |
+| `AUTH_SRV_KEY` | `'auth-service'` — the TRUSTED record whose key signs credential envelopes |
+| `AUTHEN_TIMEFRAME` | `15 * 60 * 1000` — challenge lifetime and anti-replay window, in ms |
+| `AuthService`, `AuthServiceAppend`, `AuthSpent` | Types |
+| `makeRelyModel`, `makeProviderRely`, `makeConsumerRely`, `RelyOptions` | The rely (wallet handshake) models |
+| `makeReCaptchaGuard(alias = RECAPTCHA_GUARD)` | The guard of a route a reCAPTCHA guest calls once — see "reCAPTCHA guests" |
+| `makeReCaptchaTokenHelper(ctx)`, `reCaptchaTokenOf(ctx)` | `inspect(req)` / `verify(token)` → `ReCaptchaGuest \| null` without spending; `spend(guest)` → `false` when spent before |
+| `ReCaptchaGuest`, `ReCaptchaCarrier`, `ReCaptchaTokenHelper` | Types: `{ credential, challenge, expiresAt }`, `{ headers? }`, the helper |
+
+## Key Exports — `./manager`
 
 | Export | Description |
 |--------|-------------|
-| `setupAuthServiceModules(modules, alias)` | Wire auth modules into your app modules array |
-| `AUTH_API` (re-exported) | Auth service alias |
-| Auth service factory | Backend auth manager |
-| Plugin types | Pluggable auth verifiers |
+| `makeContext(cfg, customize?)` | A server context preconfigured with the API server, API client, socket service and static `AUTH_CACHE` |
+| `main(ctx)` | Register the manager entrypoints, configure, init and listen |
+| `entrypoints` | `AUTHEN`, `AUTHEN_INIT`, `AUTHEN_AUTHEN`, `AUTHEN_RELY` and the api-config entrypoints |
+| `authenticationInit`, `authenticate`, `rely` | Implementations bound to auth protocols: `init(request)` → challenge, `authenticate(credential)` → signed credential envelope, and the rely socket |
+| `plugins`, `registerPlugin(type, factory)` | The plugin registry (also on `./manager/plugins`) |
+| `appendSupervisorAuth(ctx, opts?)`, `setupInternalTokenCoguard(entrypoints, guard?)` | PK supervisor login — see the `supervisor-auth` skill |
+| `createRelyService(alias?)`, `DEFAULT_RELY`, `RELY_TUNNEL` | The rely guard service |
+| `AppConfig`, `AppContext`, `AuthModel`, `RelyService`, `RelyAllowanceRequest`, `RelyLinker`, `RelyCarrier` | Types |
 
-## Subpath Exports
+`./manager` also re-exports the handful of symbols a manager application needs from elsewhere
+(`config`, `service`, `TRUSTED`, `bind`, `handlers`, `backend`,
+`GUARD_ED25519`, `AUTHEN*` aliases, `TrustedRecord`), so a manager app can be written against this
+one import.
 
-- `./manager` — auth manager service implementation
-- `./manager/plugins` — pluggable manager plugins
+## Key Exports — `./manager/plugins`
+
+| Export | Description |
+|--------|-------------|
+| `AuthPlugin` | `{ type, init(request), authenticate(credential) }` — `AuthModel` minus `rely` |
+| `registerPlugin(type, factory)` | Add a plugin under a type string. The registry is a module-level singleton |
+| `plugins` | The registry map |
+| `authPluginHelper.getPlugin(type, context)`, `authPluginHelper.assertType(type, plugin)` | Resolution; `getPlugin` throws `AuthUnknown(type)` for an unregistered type |
+| `makeBasicEd25519Plugin`, `makeReCaptchaPlugin`, `makeBasicRelyPlugin` | The plugin factories registered out of the box, for `AuthenticationType.BasicEd25519`, `ReCaptcha` and `RelyHandshake` |
+| `makeSupervisorPlugin(context, opts)` | The PK supervisor plugin factory |
+| `createReCaptchaVerifierService(alias = RECAPTCHA_VERIFIER, opts?)`, `appendReCaptchaVerifierService(ctx, alias?, opts?)` | Google siteverify: one `fetch` form POST (`opts.url` must be https, `opts.fetch` injectable, `opts.timeout` default 10 s) |
+| `makeReCaptchaPolicyModel(record)` | The `MOD_RECAPTCHA` record's policy: `hostnames()`, `minScore()`, `actions()`, `assert(answer)` |
+| `RECAPTCHA_VERIFIER`, `RECAPTCHA_SITEVERIFY_URL`, `RECAPTCHA_VERIFY_TIMEOUT` | `'re-captcha-verifier'`, `https://www.google.com/recaptcha/api/siteverify`, `10_000` |
+| `ReCaptchaResponse`, `ReCaptchaRequest`, `ReCaptchaVerifierService`, `ReCaptchaVerifierOptions`, `ReCaptchaFetch`, `ReCaptchaPluginConfig`, `ReCaptchaPolicyModel` | reCAPTCHA types |
+| `RelyRecord`, `AuthRedisResource` | Types |
 
 ## Usage
 
+Protect an ordinary API server:
+
+```typescript
+import { appendAuthService } from '@owlmeans/server-auth'
+import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
+
+// in makeContext, after the db/cache services are appended:
+appendAuthService(context)
+appendAuthIdentityResources(context)
+```
+
+Add an authentication method to the manager:
+
 ```typescript
-import { setupAuthServiceModules } from '@owlmeans/server-auth'
-import { AUTH_API } from '@owlmeans/auth-common'
+import { registerPlugin } from '@owlmeans/server-auth/manager/plugins'
+import type { AuthPlugin } from '@owlmeans/server-auth/manager/plugins'
 
-setupAuthServiceModules(appModules, AUTH_API)
+registerPlugin('my-method', context => ({
+  type: 'my-method',
+  init: async request => ({ challenge: /* unique per request */ '' }),
+  authenticate: async credential => {
+    // verify credential.credential, then set userId / profileId / entitySlug / role / scopes
+    return { token: '' }   // '' keeps the manager's own challenge as the credential token
+  },
+}) as AuthPlugin)
 ```
 
-## Product-Viable Usage Notes
+## reCAPTCHA guests
+
+A reCAPTCHA sign-in proves that a person solved a challenge — nothing about who they are.
+
+**Config.** One Backend plugin record `MOD_RECAPTCHA` holds the secret in `value` and the policy in
+extra string fields (`''` or absent = no check; each may be a file path the file config reader
+resolves); the browser's site key is a separate Frontend record `CMOD_RECAPTCHA`. Only Frontend
+records are advertised, so the secret and the policy never reach a browser.
+
+```ts
+plugin(cfg, { value: '/etc/master-secret/recaptcha-secret',
+  hostnames: 'example.org, example.com', minScore: '0.5', actions: 'inquiry' }, MOD_RECAPTCHA)
+clientPlugin(cfg, '/etc/app-config/recaptcha-site-key', CMOD_RECAPTCHA)
+```
+
+| Field | Check (refusal) |
+|---|---|
+| `value` | the siteverify secret; missing or `''` → `PluginMissconfigured('value')` before Google is asked |
+| — | Google's `success` (`AuthenFailed('recaptcha:<error-codes>')`, `recaptcha:unknown` without codes) |
+| `hostnames` | comma/space list; the answer's `hostname` equals an entry or is its subdomain (`recaptcha:hostname`) |
+| `minScore` | 0…1; a score-based answer with `score < minScore` (`recaptcha:score`); a checkbox answer has no score and passes; a non-number → `PluginMissconfigured('minScore')` |
+| `actions` | comma/space list; the answer's `action` must be one of them — an answer without one fails (`recaptcha:action`) |
+
+**Plugin.** `makeReCaptchaPlugin` asks the verifier registered under `RECAPTCHA_VERIFIER` (a test
+or proxy registers its own; without one the default siteverify `fetch` runs — Google is always
+https, `cfg.security.unsecure` does not apply). Google unreachable or answering garbage is
+`AuthUnavailable` (503), never a refusal. After a passing answer the credential keeps ONLY `type`,
+`role`, `userId`, `scopes`, `challenge`, `credential`, set to a guest: `GUEST_ID`, `AuthRole.Guest`,
+`[AUTH_SCOPE]`, type ReCaptcha. A posted `profileId`, `entitySlug`/`entityId`, `permissions`,
+`groups`, `expiresAt`, `source` or `publicKey` is dropped; `source` never changes the spend key.
+
+**Token.** The manager signs it as usual: an `AUTHEN_TIMEFRAME` envelope of type `re-captcha` whose
+`challenge` is the server-issued wrapped challenge (the spend key) and whose `credential` is the
+`AUTH_SRV_KEY` record's id. The browser sends it as `Authorization: RE-CAPTCHA <token>`.
+
+**Guard.** A route takes it with `guards: [RECAPTCHA_GUARD]` and `makeReCaptchaGuard()` registered
+in a context holding the `AUTH_SRV_KEY` trusted record (public key is enough) and a shared
+`AUTH_CACHE`. `reCaptchaTokenOf(ctx).inspect(req)` checks, without spending: envelope type, a TTL
+of at most `AUTHEN_TIMEFRAME`, signature and expiry, the auth record's stamp, type ReCaptcha, role
+Guest, `GUEST_ID`, a non-empty challenge. The guard then spends it — an atomic create-once of the
+challenge in `AUTH_CACHE` (Redis `SET NX`), the same key a bearer exchange and the integrated IAM's
+finalizer claim, so a token is spent once across the platform. A replay, or any failed check, is
+401. `req.auth` becomes a guest with `token: ''` and `expiresAt` = the token's expiry. Use
+`inspect` for a pre-parse check (before a large body is read); the route still needs the guard.
+
+**Never a session.** `AuthService.authenticate` (the dispatcher's bearer exchange) refuses a
+credential whose envelope or `type` is ReCaptcha (`AuthenFailed('guest')`) before spending it. A
+service that judges manager tokens itself (a finalizer) must check the method it expects — the
+token's type and its challenge's envelope type — not just the signature, since one key signs every
+method's token.
+
+## Rules
 
-- Backend context registers `appendAuthService(context)` before identity resources and product-specific gate services.
-- `AUTH_CACHE` must be registered as a Redis resource when the backend context does not rely on the default `server-app` setup.
-- `server-auth` verifies bearer tokens and populates `req.auth`; it does not decide product ownership or permissions by itself.
-- Pair this package with `@owlmeans/server-auth-identity` when an external provider such as Google should map into local account/profile/credentials records.
-- Pair it with `@owlmeans/entrypoint` gates for authorization, and keep handler-level `entityId` checks as a second line of defense.
+- The guard verifies a bearer token and populates `req.auth`. It decides nothing about ownership or
+  permissions — pair it with `@owlmeans/entrypoint` gates, and keep a handler-level organization
+  check as a second line of defence.
+- `AUTH_CACHE` is the anti-replay store: the manager burns each decoded challenge into it as a
+  create-once record with `AUTHEN_TIMEFRAME` TTL. `appendAuthService` registers a **static**
+  (in-process) resource when the context has none, which is correct for a single replica only —
+  register a Redis resource under the same alias before calling it in any scaled deployment.
+- A plugin's `init` must return a challenge that is unique per request. A challenge that repeats
+  across independent attempts collides in `AUTH_CACHE` and surfaces as `AuthenFailed('challenge')`.
+- Bearers issued by this service carry an absolute seven-day expiry and an opaque session id. In a
+  context with `AUTH_SESSION_MANAGER`, the guard rejects an absent, expired, pending or revoked
+  session and re-signs fresh profile claims after a registry revision. Registry or identity-store
+  failure is `AuthUnavailable` (503), never a false 401/logout.
+- The session registry (`AUTH_SESSION_MANAGER`) is `@owlmeans/server-auth-session`'s, not exported
+  here; `appendAuthService` installs its memory manager only as a single-process default. A
+  central or multi-replica issuer registers `appendRedisAuthSessionManager(context)` before it;
+  the manager is the authority that fences, refreshes or revokes an organization profile's sessions.
+- The manager canonicalizes the organization entity: whatever slug (current, retired, or the frozen
+  key) a plugin leaves on `credential.entitySlug` is resolved through `ENTITY_RESOLVER` and replaced
+  with the current slug before the envelope is signed. An unresolvable value throws
+  `AuthenFailed('entity')`. Where no resolver is registered the value is passed through untouched.
+- Pair this package with `@owlmeans/server-auth-identity` when an external provider (Google, OIDC,
+  email OTP) must map onto local account/profile/credential records.
+- A reCAPTCHA token is a guest token: only `makeReCaptchaGuard` accepts it, once; the bearer
+  exchange refuses it (see "reCAPTCHA guests").
 
 ## Depends On
 
-- `@owlmeans/auth`, `@owlmeans/auth-common`
-- `@owlmeans/server-entrypoint`, `@owlmeans/server-context`
-- `@owlmeans/basic-keys` — Ed25519 verification
+- `@owlmeans/auth`, `@owlmeans/auth-common` — types, aliases, `trust()`, `extractAuthToken`
+- `@owlmeans/basic-envelope`, `@owlmeans/basic-keys` — envelope signing and Ed25519 verification
+- `@owlmeans/server-context`, `@owlmeans/server-entrypoint`, `@owlmeans/server-api`
+- `@owlmeans/config` — the `TRUSTED` config resource
+- `@owlmeans/static-resource` — the default `AUTH_CACHE` backing