[Bccorb]

The v0.20 work for the Python adapter: the console proxy headers, placeholder secrets, recovery sessions, and account recovery notice delivery.

#12: console proxy headers

• The console proxy now also forwards the API's X-Frame-Options, Content-Security-Policy and X-Content-Type-Options, on GET and HEAD, so the console served on the app origin cannot be framed.

Placeholder secrets (fells-code/seamless-auth-server#231)

• Adapter refuses cookie_secret or service_secret set to dev-only-cookie-signing-key-replace-me, GRAB_FROM_SEAMLESS_AUTH_PORTAL_DEV, or anything containing replace-me (case-insensitive).
• They are allowed only with insecure_cookies=True, the adapter's local development mode.

Recovery sessions (fells-code/seamless-auth-server#232)

• The guard refuses an access token carrying recovery: true (from the cookie or a bearer token) by raising EnrollmentRequired, a subclass of Unauthenticated. Only a literal true counts.
  • Django require_auth answers 403 {"error": "enrollment_required"}.
  • FastAPI RequireUser answers 403 {"detail": "enrollment_required"}, matching its existing 401 and 403 bodies.
• Opt-in options: RequireUser(auth, allow_recovery=True), @require_auth(allow_recovery=True) and authenticate(..., allow_recovery=True). User.recovery reports the state.
• In cookie transport, when a recovery session gets a 2xx from POST /webauthn/register/finish or POST /totp/enroll/verify, the adapter refreshes in the same response, so the access cookie drops the claim.
  • If the request already refreshed silently, it uses the new refresh token.
  • If that refresh fails, the enrollment response is returned unchanged.
• In bearer transport the client holds its own refresh token and calls POST /auth/refresh itself. This is documented.

#13: account recovery delivery

• New option deliver_account_notices (default False, needs deliver). With it set, a manifest route marked notices: true (today POST /recovery/verify) is called with external delivery, the delivery service token, and x-seamless-auth-delivery-kinds: account_notice_email,account_notice_sms.
• The adapter delivers every item in deliveries and strips deliveries from the response in both transports.
  • If at least one notice is delivered, the client gets the API's body.
  • If none is delivered, the adapter cancels the request with POST /recovery/cancel {"cancelToken": <fragment of cancelUrl>} (proxy service token, no credential) and answers 503 {"error": "recovery_notice_failed"}.
• With the option off, external mode and the kinds header are not sent on that route, so the API sends the notices itself.
• Delivery gains notice, subject, text, cancel_url and purpose, plus is_account_recovery.
  • cancel_url and text (which contains the link) are hidden from repr.
  • Delivery failures are logged by exception type only, so neither the cancel URL nor its token is ever logged.
• otp_email and otp_sms with purpose: "account_recovery" reach the callback with that purpose. The README asks apps to word them as a recovery code.
• An unknown delivery kind is logged and skipped.
• The manifest parser keeps the new optional notices field. The bundled manifest is synced from the API's committed copy (apiVersion 0.19.4), which adds the /recovery/*, /recovery-codes*, GET /recovery/requests, DELETE /recovery/requests/{id} and /system-config/policy* routes.
• Tests cover these pass-throughs: 503 recovery_notice_failed, 403 step_up_required, every new access route, and the pre-auth recovery routes, including /recovery/complete issuing a recovery session.

Checks

$ uv run ruff check .
All checks passed!
$ uv run ruff format --check .
34 files already formatted
$ uv run mypy
Success: no issues found in 13 source files
$ uv run pytest
============================= 227 passed in 0.66s ==============================

Each commit was also checked on its own (ruff, mypy, pytest). The conformance suite was not run locally; it runs in CI.

Closes #12
Closes #13