haveapi 0.31.2 → 0.32.1

data/doc/client-examples.md

@@ -1,5 +1,7 @@
 # Client examples in API documentation
 
+For browser sign-in to the documentation, see [OAuth sign-in](documentation-oauth.md).
+
 The Ruby server renders examples from the current user's API description.
 JavaScript and TypeScript examples cover callback and async clients; Python
 examples cover sync and async clients. These clients need no server
@@ -8,18 +10,39 @@ Ruby, PHP, CLI, curl and HTTP examples are also available. A sample
 that a client cannot represent shows a limitation instead of dropping input or
 inventing a successful result.
 
-Go, Rust and generated TypeScript tabs require a profile for a generated SDK.
-Their package versions are independent of HaveAPI and the API version. Without a
-profile, the server
-hides those clients from the overview and all initialization, authentication and
-action panels. Install the matching generator gem only when configuring its
-profile; ordinary servers do not depend on these generators.
-
-## Configure a generated SDK
-
-Register profiles before mounting the server. For an SDK that matches the
-current
-API, configure its package identity:
+Examples default to **Simple**. Action examples assume an initialized and, when
+needed, authenticated `api`; initialization and authentication examples are on
+separate pages. The Examples selector stays visible and offers **With error
+handling** when the current page has examples with additional error handling
+for that client. Examples without a distinct error-handling form remain Simple.
+Both levels preserve the same sample values, path arguments and operation
+semantics. Extra setup alone does not create another choice; built-in
+limitations have one Simple panel.
+See [the documentation UI guide](documentation-ui.md) for navigation and saved
+display preferences.
+
+Examples use placeholder credentials: `user` / `secret`, `example-token` and
+`example-access-token`. Replace them with your application's values. Renderers
+use these public literals rather than reading credentials from the environment,
+current user, profile settings or private defaults.
+
+Token-login and challenge inputs use the authorized description's field names,
+types and finite machine-readable choices. Required inputs remain present, and
+the lifetime is explicitly fixed. Custom validation may require different
+values; an unrepresentable required field produces a limitation. Continuation
+names and inputs follow the advertised actions, while the runtime supplies and
+propagates intermediate tokens.
+
+Go, Rust and TypeScript API clients require a configured profile. Their package
+versions are independent of HaveAPI and the API version. Without a profile, the
+server omits those clients from the overview and example panels. Install the
+matching generator gem when configuring its profile; ordinary servers do not
+depend on these generators.
+
+## Configure an API client
+
+Register profiles before mounting the server. For an API client that matches the
+current API, configure its package identity:
 
 ```ruby
 api.documentation_clients('1.0',
@@ -40,30 +63,27 @@ api.mount('/api/')
 matching generator in the server's Ruby environment: `haveapi-go-client`,
 `haveapi-rust-client`, or the source-distributed `haveapi-typescript-client`.
 See the [TypeScript generator guide](../clients/typescript/README.md) for its
-setup. An explicit `generator_version` requires the installed generator to
-report
+setup. An explicit `generator_version` requires the installed generator to report
 that version; the server never downloads one. This version is independent of the
-SDK and API versions.
+API client and API versions.
 
 At the end of mount, the server builds one private structural model per
-configured
-API version. The model includes authentication resources, routes and changes
-from
-post-mount hooks, so canonical names and parent arguments use the complete API
+configured API version. The model includes authentication resources, routes and
+changes from post-mount hooks, so canonical names and parent arguments use the complete API
 declaration. The private copy excludes examples, prose and parameter defaults.
 HTML requests use the current user's authorized description, fields and samples;
 they never expose the private model or its initialization diagnostics. Without
 a configured profile, the server loads no optional generator and hides the Go,
-Rust and generated TypeScript panels. The callback and async TypeScript
+Rust and TypeScript API client panels. The callback and async TypeScript
 examples remain separate and need no profile.
 
-Automatic profiles assume that the installed SDK matches the current server's
-generation contract. A package name or version does not prove its contents.
-An older SDK can lack new actions or use different names after a collision or
-route change. Check actual SDK compatibility before advertising it; use a saved
-schema override below when the SDK represents an older or restricted API.
+Automatic profiles assume that the installed API client matches the current
+server's generation contract. A package name or version does not prove its
+contents. An older API client can lack new actions or use different names after
+a collision or route change. Check compatibility before advertising a client;
+use a saved-schema override for an older or restricted API.
 
-### Optional SDK versions and sources
+### Optional API client versions and sources
 
 Set `module_version: 'v1.2.3'` for Go, `crate_version: '1.2.3'` for Rust or
 `package_version: '1.2.3'` for TypeScript when a specific package version is
@@ -89,13 +109,15 @@ examples also show their Tokio and serde_json requirements.
 
 TypeScript accepts ordinary lowercase npm package names, including scoped names,
 and optional concrete SemVer versions. Tags, version ranges, Git URLs, local
-paths
-and custom factories are not profile options. Configure a package that users can
-install; the server does not check its availability or publish it. Generated
-snippets use the package's public `createClient` export and the published
-`haveapi-client` 0.30.2 runtime.
+paths and custom factories are not profile options. Configure a package that
+users can install; the server does not check its availability or publish it.
+TypeScript examples call the package's typed properties through its public
+`createClient` export. The profile does not detect or select the application's
+installed `haveapi-client` runtime. The installation command above uses the
+version supported by the [TypeScript generator](../clients/typescript/README.md);
+the examples do not report it as a configured runtime version.
 
-For an unpublished Rust SDK, supply an HTTPS Git URL and a full commit SHA:
+For an unpublished Rust API client, supply an HTTPS Git URL and a full commit SHA:
 
 ```ruby
 api.documentation_clients('7.0',
@@ -122,8 +144,8 @@ credentials, query strings, fragments or control characters; revisions must be
 40 hexadecimal characters. Branches, tags, local paths and custom registries are
 not supported. An explicit crate version additionally constrains the selected
 source package. The server never fetches the repository or runs these user
-installation commands. These settings do not regenerate or publish an SDK and
-do not establish that this particular SDK matches a given API surface.
+installation commands. These settings do not regenerate or publish an API client
+or establish that it matches a given API surface.
 
 ### Saved-schema overrides
 
@@ -153,9 +175,9 @@ api.documentation_clients('1.0',
 
 Paths name trusted absolute local files. `description_path` is Go's saved
 machine-readable description, not HTML. For Rust and TypeScript, `snapshot_path`
-selects the saved schema and capture metadata. These files select an exact SDK
-shape in place of the current
-server declaration. Keep the files private and retain them with the SDK release.
+selects the saved schema and capture metadata. These files select an exact API
+client shape in place of the current server declaration. Keep them private and
+retain them with the API client release.
 
 Rust's legacy `generator_config_path` supplies the crate name/version and full
 packaging configuration. It is mutually exclusive with inline `crate_name` and
@@ -174,9 +196,9 @@ server application. An older explicitly pinned generator can serve a suitable
 legacy file profile, but automatic/inline Rust mode requires the new factory
 interface and never guesses a fallback.
 
-A saved SDK can still serve examples after unrelated live additions. Each sample
-must match its saved route, layout and supplied parameter contracts; unavailable
-or stale samples show a limitation. Hidden actions, fields, defaults and samples
+A saved API client can still serve examples after unrelated live additions. Each
+sample must match its saved route, layout and supplied parameter contracts;
+unavailable or stale samples show a limitation. Hidden actions, fields, defaults and samples
 remain hidden from the current user. The server never fetches descriptions,
 regenerates packages or runs a compiler/formatter during an HTML request.
 
@@ -192,6 +214,11 @@ Existing renderer positional constructors and `init`, `auth(method, desc)` and
 The registry binds a request-local `HaveAPI::ClientExample::Context` through
 `with_context`. It holds the selected version, URLs including the API mount,
 the filtered description, and the current resource, action and sample.
+Its `detail` reader is exactly `:simple` or `:thorough`, defaulting to `:simple`.
+Both construction and `context.with(detail: ...)` reject other values, including
+strings and nil. Changing detail shares the existing owned data, as other
+context derivations do. The base renderer's `thorough?` helper reads this value;
+legacy positional renderer instances use simple behavior.
 Construction copies and freezes Hash, Array and String data without freezing
 the caller's containers. Each request owns its description snapshot.
 `context.with(...)` creates a distinct frozen context, sharing unchanged fields
@@ -215,6 +242,74 @@ strings, escaped once by the templates. A stable class `id` identifies a
 variant; `code` selects its syntax language. `available?(context)` controls the
 overview and every panel before rendering.
 
+Renderer classes declare presentation with `language 'python'`,
+`language_label 'Python'` and, for a client variant, `variant 'Async'`. These
+class methods also read the metadata. The language is a stable lower-case group
+ID, independent of the syntax lexer and exact client ID. An unspecified language
+defaults to the renderer's own `id`, its language label defaults to `label`, and
+its variant is nil. Metadata is declared on each class; a subclass without its
+own metadata gets those defaults. Keep client IDs and registry order stable.
+
+The class query `detail_levels_for(kind, context:, result:, auth_method: nil,
+auth_description: nil)` selects the meaningful levels for each example group.
+`result` is the already-rendered Simple result. Return a frozen `[:simple]` or
+`[:simple, :thorough]`; other values are errors. The base implementation returns
+the inherited `detail_levels` declaration, which defaults to both levels for
+custom renderers. A custom Simple limitation does not suppress its distinct
+thorough implementation. Direct rendering at either Context detail remains
+supported, independently of the choices advertised in HTML.
+
+Ruby and PHP offer both levels for representable initialization, authentication
+and actions. Ruby OAuth remains unsupported. Their constructors are lazy, so
+With error handling runs setup explicitly and handles validation, API,
+authentication and protocol failures. Ruby rescues `ValidationError` before its
+`ActionFailed` parent and reads response errors only from an actual `Response`.
+PHP uses its framework exceptions and `getErrors()` where supported, and
+rethrows unknown dependency exceptions. Its OAuth session, state, PKCE, redirect
+and token exchange remain part of the example.
+
+Callback JavaScript and TypeScript offer both levels for actions. Initialization
+and authentication already check the ready result and offer Simple only. Async
+JavaScript, async TypeScript and Python offer both for representable examples.
+
+Go's Simple actions already check transport and API failures. Both levels are
+available only for successful blocking actions with an authorized operation-status
+helper. Its initialization and credential setters make no request and offer
+Simple only. Rust offers both for representable code, with explicit handling of
+fallible construction and send results. Its authentication setters configure
+credentials without validating them over the network.
+
+Typed TypeScript initialization is Simple only. Supported Basic/token
+authentication and actions offer both with awaited `AsyncError` handling; OAuth
+remains a limitation. CLI, curl and HTTP offer Simple only: the CLI reports
+failures and exits nonzero, while the transcripts show protocol responses.
+All built-in limitation results offer Simple only.
+
+Go, Rust and TypeScript wrappers delegate to their configured adapter's
+`detail_levels_for(kind:, context:, result:, mode:, auth_method: nil,
+auth_description: nil)` when it implements that query. Older adapters retain
+the wrapper's declared levels, including a distinct thorough result after a
+Simple limitation. Those adapters may still offer identical code at both levels.
+A query that returns invalid levels or raises an error does not use this fallback.
+Capability queries must not render again or inspect unrelated resources.
+The HTML producer renders each advertised detail once and
+publishes its choices in the example group's `data-example-details` map. Client
+metadata contains the ordered union for the current page; clients without any
+example groups get Simple. Neither the group nor page choices change the saved
+detail preference.
+
+Simple action renderers use the established `api` and show the actual call and
+relevant result. Initialize and authenticate it using the separate examples.
+Python async fragments belong inside an async function; their comment makes that
+context explicit. Python setup examples use a minimal async function and
+`asyncio.run`, while sync examples run at top level. Neither level has a
+`__main__` guard. Thorough sync examples use top-level `try`/`except`.
+
+Translate and validate samples before selecting presentation detail. Keep exact
+names, parent arguments, false, zero, empty strings, nullable values and blocking
+operation behavior. Do not shorten examples by dropping unsupported input or
+removing lines from an already rendered program.
+
 Generated-client adapters belong to their generator gems and consume context
 readers without depending on the server gem. They resolve names using the
 complete private generator model and never run a compiler, formatter or
@@ -223,11 +318,87 @@ in an HTML request. Keep adapter rendering read-only: configured adapters are
 frozen
 and shared, while authorized description snapshots belong to individual
 requests.
+Adapters keep their existing `render(kind:, context:, mode:, ...)` signature and
+read `context.detail` directly. Test contexts must provide the reader. An older
+third-party adapter can ignore this additive field and retain the wrapper's
+declared choices without implementing the new capability query.
 Derived contexts within one request share unchanged owned data. Supplying a
 resource, action or sample still copies that supplied subtree, so a resource
 with
 many actions can remain costly to render.
 
+## Example source style
+
+Generated examples follow the conventions of their output language. These rules
+apply to initialization, authentication and action examples, including inherited
+callback, sync, async and blocking variants. Keep Simple and With error handling
+consistent where both are supported.
+
+| Language | Source conventions |
+| --- | --- |
+| PHP | Four-space blocks and array nesting; single quotes for ordinary static strings without interpolation; spaces around concatenation. Keep escaped double quotes where control strings or newline output require them. |
+| Ruby | Two-space blocks and single quotes for plain authored strings. Keep `dump`, `inspect` and PP encoding for sample data. |
+| JavaScript / TypeScript | Two-space blocks, double-quoted strings and import specifiers, semicolons, and conventional spacing after commas and colons and inside import/object braces. Preserve safe computed keys and typed property access. |
+| Python | Four-space suites and the existing double-quoted data encoding. Omit empty optional import slots; use one blank line before module-level executable code and two around top-level async definitions. |
+| Go | Tabs, gofmt-compatible spacing and separate standard-library/client import groups. Keep native double-quoted string encoding. |
+| Rust | Four-space blocks, conventional Rust spacing/imports and the existing string encoder in both async and blocking examples. |
+| CLI / curl | Preserve shell continuations. Serialize data first, then encode every complete dynamic shell argument with `Shellwords.escape`; this includes URLs, headers, option names and values. |
+| HTTP | Preserve the protocol/JSON transcript, especially the header/body separator. Shell quoting rules do not apply. |
+
+At known fragment boundaries, omit absent fragments and separate logical blocks
+with one useful blank line, subject to the language rules above. Avoid leading
+or trailing blank padding, duplicate separators and whitespace on empty lines.
+Keep formatting in the owning language renderer or adapter. Do not normalize
+whole rendered programs or custom-renderer output with a shared regex or
+formatter, or add a runtime formatter dependency. Tests may use native formatters.
+
+For CLI and curl, keep authored shell syntax separate from argument data. Encode
+each argument once after its value has been serialized; surrounding raw data
+with single or double quotes is insufficient. Check generated commands with
+temporary fake executables: require successful execution, exact captured argument
+values and order, and no unintended command execution. Parse captured curl JSON
+to verify that shell encoding preserves the complete request body.
+
+CLI and curl examples can show response output after the executable command.
+Keep every physical response line inert when the complete block is pasted into a
+shell. Normalize CRLF and bare CR to LF only within display-only response
+fragments, then prefix every resulting line with `# `. Do not normalize or
+comment the request command, and do not use shell escaping as a substitute for
+commenting each physical response line. Regression tests must execute the
+complete displayed block with temporary fake executables, preserve the exact
+request arguments and curl JSON, and prove that hostile multiline response
+values stay visible without being evaluated.
+
+Keep encoded data separate from authored syntax. Preserve runtime values,
+Unicode, apostrophes, backslashes, dollar signs, control bytes, empty values,
+false, zero and null. PHP control strings may need double quotes with dollar
+signs, backslashes and quotes escaped and PHP-valid control escapes; JSON
+`\u` escapes are not a PHP string encoder. Never turn a newline into literal
+backslash-n or let wrapper indentation change literal bytes.
+
+Formatting changes must preserve public sample credentials, request inputs,
+error handlers and control flow, direct-call/custom-adapter compatibility, and
+meaningful detail choices. Do not add panels solely to show different formatting.
+
+When changing a renderer:
+
+- Inspect relevant initialization, authentication and action output for affected
+  variants and both direct detail inputs. Cover absent optional fragments and
+  literal edge cases where the change can affect them.
+- Use existing [server example specs](../servers/ruby/spec/client_examples/) for
+  PHP literal round trips and real handlers, Ruby syntax, Python AST/separation,
+  detail behavior and custom whitespace. Use the owning
+  [Go documentation specs](../clients/go/spec/unit/documentation_spec.rb),
+  [TypeScript documentation specs](../clients/typescript/spec/unit/) and
+  [Rust development checks](../clients/rust/docs/development.md) when affected.
+  TypeScript coverage includes source, strict compilation and performance specs.
+- Search neighboring HTML, fixture and performance assertions for exact source
+  spelling. Update intentional quote/import/spacing expectations while retaining
+  semantic assertions, traversal/allocation bounds and strict compiler checks.
+- Follow [development commands](agent-instructions/development.md) and the
+  existing verification requirements. Select checks by affected language and
+  behavior; an unrelated edit does not require every language toolchain.
+
 ## Verification
 
 `make test-documentation` checks renderers, contexts, profiles, rendered HTML
@@ -268,9 +439,11 @@ The target synchronizes shared documentation before running the harness.
 Standard
 output is JSON; shell/dependency preparation happens before the redirected
 command.
-No network server, database, generated SDK compilation or formatter is involved.
-The synthetic fixture uses Basic users `admin` and `member`, both with the local
-test password `fixture-only`.
+No network server, database, API client compilation or formatter is involved.
+The synthetic fixture has users `admin` and `member`. Direct-render and description
+lanes use Basic authentication with the local password `fixture-only`. HTML
+requests use real documentation OAuth cookies on supported sources, with token
+validation on each request; historical sources without that feature use Basic.
 
 Defaults measure two shapes with eight ordinary actions each: eight resources
 with one action, and one resource with eight actions. Each ordinary action also
@@ -351,8 +524,8 @@ failure class, while concentrated-resource costs and other future regressions
 still need representative measurements.
 
 Each client also has acceptance commands that check executable snippets against
-installed packages or a generated SDK. These use
-rendered source against disposable fixtures; syntax checks alone do not
+installed packages or an API client. These run rendered source against
+disposable fixtures; syntax checks alone do not
 establish that client calls or authentication work. See each client's
 development documentation for its test environment. Highlighter rebuilding is
 described in [utils/highlight](../utils/highlight/README.md).

data/doc/documentation-oauth.md

@@ -0,0 +1,188 @@
+# OAuth sign-in for HTML documentation
+
+The Ruby server can use an existing OAuth provider to sign readers into its HTML
+documentation. This is an optional confidential client: the server exchanges
+authorization codes and keeps the client secret out of the browser. Passwords,
+MFA, account recovery and optional SSO remain with the provider.
+
+## Configure the client
+
+Register a dedicated confidential client with your OAuth provider. Use the exact
+HTTPS callback `<API mount>_documentation/oauth/callback`, fixed access-token
+expiry and no refresh token. Keep existing default OAuth clients unchanged.
+
+Configure the documentation client before mounting the server:
+
+```ruby
+api.documentation_oauth(
+  client_id: ENV.fetch('DOCUMENTATION_CLIENT_ID'),
+  client_secret: ENV.fetch('DOCUMENTATION_CLIENT_SECRET'),
+  redirect_uri: 'https://docs.example.test/api/_documentation/oauth/callback',
+  session_secret: File.binread('/run/secrets/documentation-session'),
+  scope: ['all'],
+  session_lifetime: 3600
+)
+api.mount('/api/')
+```
+
+Generate at least 64 bytes of cryptographically random session secret material
+once, keep it private, and supply the same value to every worker. Do not generate
+it on each startup. Changing it signs existing documentation sessions out. Client
+credentials and session secrets must not be committed or included in diagnostics.
+
+`scope` defaults to `[]`. Request only the scopes needed by the application.
+vpsAdmin uses `['all']` to describe the actions available to the signed-in user's
+role. Its resulting bearer token can also authorize API requests, so keeping the
+documentation cookie out of API authentication is essential.
+
+`session_lifetime` defaults to 3600 seconds and accepts integers from 1 to 86400.
+The actual session ends at the earlier of this limit and the provider's access
+token expiry. No refresh token is stored or used.
+
+`switch_user` defaults to `false` and accepts only `true` or `false`. Enable it
+only after verifying that a fresh authorization for this dedicated client lets
+the reader enter different credentials. This option asserts that the operator
+has checked that behavior; it does not discover account-selection support or
+send `prompt` or `select_account` parameters.
+
+`switch_user_revoke_params` defaults to `{}` and accepts a static hash of string
+keys and string values. These fields are added to the revoke POST only for a
+validated Switch user request. They are never sent during ordinary Sign out,
+authorization or token exchange. The required `client_id`, `client_secret`,
+`token` and `token_type_hint` fields cannot be configured through this option.
+The server copies and freezes the hash and its strings at startup; browser
+fields and later changes to the original hash cannot change the revoke payload.
+The option has no effect when `switch_user` is `false`.
+
+For example, a dedicated nondefault vpsAdmin client can allow SSO and use the
+provider's `close_sso` revoke parameter when switching:
+
+```ruby
+api.documentation_oauth(
+  # Include the client, callback, session and scope options shown above.
+  switch_user: true,
+  switch_user_revoke_params: { 'close_sso' => '1' }
+)
+```
+
+Verify that the provider accepts these parameters and that the next authorization
+allows different credentials. Revoking the documentation token alone can leave
+SSO available when another active authorization shares it. Provider-specific
+SSO closure need not revoke that other authorization's access token. A dedicated
+client with SSO disabled is another way to permit account switching.
+
+The callback must be an absolute HTTPS URL with the exact mounted callback path,
+without credentials, query or fragment. The server takes authorize, token and
+revoke endpoints from its default version's configured OAuth provider metadata
+at mount time. Those endpoints must also use HTTPS. It does not discover an
+issuer from a browser request or follow endpoint redirects. Missing providers,
+invalid configuration and repeated or late configuration fail startup.
+
+## HTTPS and worker requirements
+
+Serve the documentation at the configured HTTPS origin. The Rack request scheme
+and host must reflect that origin. When using a reverse proxy, configure trusted
+forwarding in the server/proxy; do not trust arbitrary client-supplied forwarding
+headers. A private development CA must be trusted by both the reader's browser
+and the server's standard HTTPS trust store. Never disable peer verification.
+
+Token and revoke exchanges use bounded HTTPS requests. If the provider shares
+the documentation server's public origin, the server needs enough concurrent
+request capacity to handle a token exchange while the callback is running.
+A single-request worker cannot serve both sides of that exchange.
+
+## Browser session and access checks
+
+Sign-in uses state and S256 PKCE, with a ten-minute encrypted pending cookie.
+Return navigation contains validated documentation version/page/resource fields
+and an optional bounded fragment, rather than an arbitrary return URL. Callback
+errors offer a retry without exposing provider responses or exception details.
+Successful callbacks redirect promptly to a clean documentation URL.
+Failed, cancelled and replayed callbacks consume pending state and preserve an
+existing authenticated documentation session.
+
+Authenticated cookies contain only the access token, expiry and logout CSRF
+nonce. ActiveSupport MessageEncryptor protects them with AES-256-GCM and JSON;
+separate purposes bind pending and authenticated cookies to the client, callback
+and API mount. Cookies are Secure, HttpOnly, SameSite=Lax, mount-scoped and have
+no Domain attribute. Complete cookies are limited to 3800 bytes; oversized token
+responses fail sign-in rather than producing truncated sessions. Browser storage
+used for documentation preferences never contains tokens.
+
+HTML documentation GET and HEAD requests, including the versions index and
+search-index representations, use only the documentation cookie on its configured
+HTTPS origin. Without that configuration or a valid cookie, documentation is
+anonymous. Basic credentials, Bearer/custom token headers and query credentials
+do not select its identity. With API credentials for user A and a valid
+documentation cookie for user B, the reference and its account controls use B.
+Invalid or conflicting API credentials do not affect that selection.
+
+Each network page request decrypts and validates the cookie, then validates its
+token through the requested version's OAuth2 provider and runs the existing
+post-authentication hook before describing resources. It passes the original
+request and the cookie token separately, without changing request headers or
+parameters. Identity and roles are never taken from a cached user ID. A revoked
+or expired session returns to the public view; an inaccessible selected resource
+is 404. Conditional search-index requests perform the same validation.
+
+The standard OAuth2 provider delegates this explicit validation to its existing
+`config.find_user_by_access_token(request, token)` callback. A custom provider
+named `oauth2` must implement `authenticate_access_token(request, token)` to
+support documentation sessions. Unsupported versions or providers cannot fall
+back to Basic, Token or another API authenticator. Ordinary API actions, OPTIONS
+descriptions, mutations and provider endpoints retain their complete existing
+authentication chain and credential-conflict rules. The documentation cookie
+does not authenticate those operations.
+
+Account sign-in, sign-out and switching belong to this documentation session.
+The compatibility GET URLs `_login` and `_logout` redirect with HTTP 303 to the
+default version overview without authenticating, challenging, clearing cookies or
+revoking tokens. They ignore arbitrary return destinations. API Basic challenges
+continue to work, and documentation switching does not erase cached Basic
+credentials or sign out of an API client.
+
+Personalized HTML and authentication responses use private, no-store caching.
+Documentation pages use `Referrer-Policy: strict-origin` so native sign-out and
+Switch user forms retain their same-origin `Origin` header. Referrers contain at
+most the origin and are omitted on HTTPS-to-HTTP downgrades. Login, callback,
+sign-out and authentication error responses use `Referrer-Policy: no-referrer`.
+Configure access and error logs so callback query strings, tokens, passwords and
+client credentials are not retained.
+
+## Sign-out and recovery
+
+Sign-out is a same-origin POST with a session-bound CSRF nonce. The server
+attempts access-token revocation and clears local authenticated and pending
+cookies. If revocation fails, the response states that local sign-out succeeded
+but the server session may remain until expiry. It does not claim a successful
+revocation, queue tokens for retry, or request a whole-account SSO sign-out.
+
+When `switch_user: true`, readers authenticated by a documentation cookie see
+Switch user in Documentation settings. It submits the existing same-origin,
+CSRF-protected logout POST with one URL-encoded scalar `switch_user=1`.
+Disabled, duplicate, array and other invalid switch fields or invalid origin/CSRF
+are rejected before sign-out or revocation. Ordinary Sign out sends no switch
+field. API credentials on the request do not affect these cookie-session operations.
+
+After successful local sign-out and revocation, switching returns 303 to the
+fixed documentation login route for the default version. That login creates new
+state and PKCE values; the old pending attempt and session are cleared. No return
+URL or scope supplied by the switch request changes that destination. Cancelling
+the new authorization leaves the old documentation session signed out. A revoke
+failure retains the 502 response described above and does not continue to login.
+Switching can request provider-specific SSO behavior through the configured
+revoke parameters; HaveAPI does not interpret them or guarantee whole-account
+sign-out. Ordinary Sign out still revokes only the documentation token without
+those parameters.
+
+To disable this feature, remove its optional configuration before starting older
+documentation code. In particular, remove `switch_user_revoke_params` before
+rolling back to a HaveAPI version that does not support it; the unknown option
+would prevent startup. Upgrade HaveAPI before enabling the option, including on
+each worker that loads the configuration. Existing API data needs no migration
+or rollback. Cookies expire or are ignored. Disable or revoke the dedicated
+OAuth client through normal provider administration when needed; documentation
+rollback does not delete clients automatically. Without this configuration, documentation remains
+anonymous and offers no authentication controls; ordinary API authentication is
+unchanged. Older documentation code may use API credentials and legacy browser
+sign-in routes again. Rolling back requires no cookie or database migration.