feat: add filters to support logistration integration

CHANGELOG.rst

@@ -33,7 +33,32 @@ Unreleased
 ----------
 .. scriv-insert-here
 
-.. _changelog-3.7.0:
+.. _changelog-3.9.0:
+
+[3.9.0] - 2026-08-04
+--------------------
+
+Added
+~~~~~
+
+* Added new ``authentication`` architecture subdomain
+
+* Added six new authentication-related filters:
+
+  * ``LogistrationViewContextGenerated``
+  * ``AuthnMFEContextGenerated``
+  * ``LoginAltRedirectURLRequested``
+  * ``LoginFormGenerated``
+  * ``RegistrationFormGenerated``
+  * ``LogistrationViewRenderCompleted``
+
+* Added three new structural types used by several of the above filters:
+
+  * ``FormDescriptionProtocol`` - declares the minimal surface of the form
+    description that the form filters pass to pipeline steps.
+  * ``ProviderConfigProtocol`` - declares the minimal surface of the third-party
+    auth provider configuration that the form filters pass to pipeline steps.
+  * ``RunningPipeline`` - authentication pipeline state.
 
 [3.8.0] - 2026-07-07
 ---------------------

MANIFEST.in

@@ -3,4 +3,5 @@ include LICENSE.txt
 include README.rst
 include requirements/base.in
 recursive-include openedx_filters *.html *.png *.gif *.js *.css *.jpg *.jpeg *.svg *.py
+include openedx_filters/py.typed
 include requirements/constraints.txt

docs/conf.py

@@ -37,13 +37,19 @@
     'sphinx_copybutton',
     'sphinx.ext.graphviz',
     'sphinxcontrib.mermaid',
+    'myst_parser',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.linkcode',
 ]
 
+# Render fenced ```mermaid code blocks in Markdown (MyST) sources through the
+# sphinxcontrib.mermaid directive, so the same fences render both on GitHub and
+# in the Sphinx-built docs.
+myst_fence_as_directive = ["mermaid"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/decisions/0008-authentication-subdomain.md

@@ -0,0 +1,100 @@
+# 8. The authentication architecture subdomain
+
+## Status
+
+Accepted
+
+## Context
+
+Filters are grouped by architecture subdomain (see
+[ADR-4](0004-filters-naming-and-versioning.rst)).
+Until now, the filters covering how users sign in and register —
+`StudentLoginRequested` and `StudentRegistrationRequested` — have lived in the
+`learning` subdomain, because that was the only user-facing subdomain available
+at the time.
+
+A new set of filters covering the login and registration *user experience* is
+being introduced: hooks around the login/registration page context and render
+lifecycle, the login and registration form descriptions, the authentication MFE
+(`frontend-app-authn`) context, and the post-login redirect. These needed a
+home, and `learning` is a poor fit: authentication gates access for *every* user
+of the platform — learners and content authors alike — so it is a distinct
+bounded context rather than a learning activity.
+
+## Decision
+
+We will introduce a new "Authentication" architecture subdomain, implemented in
+`openedx_filters/authentication/` with filter types under
+`org.openedx.authentication.*`. From now onward, new authentication-related
+filters should be added here.
+
+Docs: This new subdomain will be added to the [Architecture Subdomains Reference](../reference/architecture-subdomains.rst)
+alongside "Learning" and "Content Authoring".
+
+The following filters are added to it:
+
+- `LogistrationViewContextGenerated` — enrich the legacy (server-rendered) login/registration page context.
+- `LogistrationViewRenderCompleted` — modify the rendered legacy login/registration page response.
+- `AuthnMFEContextGenerated` — enrich the authentication MFE context.
+- `LoginFormGenerated` — augment the generated login form description.
+- `RegistrationFormGenerated` — augment the generated registration form description.
+- `LoginAltRedirectURLRequested` — choose an alternative post-login redirect.
+
+The diagram below shows when each authn-related filter fires within the authn flow.
+
+```mermaid
+flowchart TD
+    classDef filter fill:#e8f0fe,stroke:#1a73e8,color:#0a3069
+
+    ROUTES["/login and /register routes"]
+    LEGACY["Legacy logistration view<br/>(server-rendered)"]
+    MFE["Authn MFE<br/>(frontend-app-authn)"]
+
+    LogistrationViewContextGenerated["<b>LogistrationViewContextGenerated</b><br/><i>enrich legacy page context</i>"]:::filter
+    LogistrationViewRenderCompleted["<b>LogistrationViewRenderCompleted</b><br/><i>post-render response hook,<br/>useful for setting extra cookies</i>"]:::filter
+    AuthnMFEContextGenerated["<b>AuthnMFEContextGenerated</b><br/><i>enrich MFE context</i>"]:::filter
+    LoginFormGenerated["<b>LoginFormGenerated</b><br/><i>augment login form fields</i>"]:::filter
+    RegistrationFormGenerated["<b>RegistrationFormGenerated</b><br/><i>augment registration form fields</i>"]:::filter
+    StudentRegistrationRequested["<b>StudentRegistrationRequested</b><br/><i>hook for blocking registration</i>"]:::filter
+    StudentLoginRequested["<b>StudentLoginRequested</b><br/><i>hook for blocking login</i>"]:::filter
+    LoginAltRedirectURLRequested["<b>LoginAltRedirectURLRequested</b><br/><i>force alternative post-login redirect</i>"]:::filter
+
+    RENDERED["Legacy page rendered"]
+    FORMS["Login/registration<br/>FormDescription generation"]
+    LOGINPOST["Login POST endpoint"]
+    REGPOST["Registration POST endpoint"]
+    DEST["Post-auth destination,<br/><i>URL possibly overridden by filter</i>"]
+
+    ROUTES -- "AuthN MFE disabled for flow" --> LEGACY
+    ROUTES -- "AuthN MFE enabled for flow" --> MFE
+    LEGACY --> LogistrationViewContextGenerated --> RENDERED --> LogistrationViewRenderCompleted
+    LogistrationViewRenderCompleted -- "Get FormDescription via python API" --> FORMS
+    MFE --> AuthnMFEContextGenerated
+    AuthnMFEContextGenerated -- "Get FormDescription via REST API" --> FORMS
+    %% invisible edge: pin AuthnMFEContextGenerated to the same rank as
+    %% LogistrationViewContextGenerated so both *ContextGenerated filters render on the same level
+    AuthnMFEContextGenerated ~~~ RENDERED
+    FORMS -- "is /login route" --> LoginFormGenerated
+    FORMS -- "is /register route" --> RegistrationFormGenerated
+    %% invisible edge: pin LoginFormGenerated to the same rank as
+    %% RegistrationFormGenerated so both *FormGenerated filters render on the same level
+    LoginFormGenerated ~~~ REGPOST
+    LoginFormGenerated -- "submit login" --> LOGINPOST
+    RegistrationFormGenerated -- "submit registration" --> REGPOST
+    REGPOST --> StudentRegistrationRequested
+    LOGINPOST --> StudentLoginRequested
+    StudentLoginRequested -- "AuthN MFE enabled and the request is for first-party auth" --> LoginAltRedirectURLRequested
+    StudentLoginRequested -- "otherwise" --> DEST
+    LoginAltRedirectURLRequested --> DEST
+    StudentRegistrationRequested -- "account created and logged in" --> DEST
+```
+
+## Consequences
+
+- Future authentication-related filters have a clear, accurately named home and
+  no longer need to borrow the "Learning" subdomain.
+- The pre-existing authn filters `StudentLoginRequested` and
+  `StudentRegistrationRequested` filters **remain in the `learning` subdomain**.
+  They are released, versioned public contracts, and re-homing them would be a
+  breaking change for existing consumers. A future major version could migrate
+  the two longstanding filters.

docs/decisions/index.rst

@@ -14,3 +14,4 @@ Decisions
    0005-filters-payload
    0006-filter-debug-tooling
    0007-filter-design-practices
+   0008-authentication-subdomain

docs/reference/architecture-subdomains.rst

@@ -8,6 +8,8 @@ Currently, these are the `architecture subdomains`_ used by the Open edX Filters
 +-------------------+----------------------------------------------------------------------------------------------------+
 | Subdomain Name    | Description                                                                                        |
 +===================+====================================================================================================+
+| Authentication    | Handles how users sign in, register, and are routed through login/registration flows.              |
++-------------------+----------------------------------------------------------------------------------------------------+
 | Content Authoring | Allows educators to create, modify, package, annotate (tag), and share learning content.           |
 +-------------------+----------------------------------------------------------------------------------------------------+
 | Learning          | Allows learners to consume content and perform actions in a learning activity on the platform.     |

docs/reference/filters.rst

@@ -20,6 +20,18 @@ Course Authoring Subdomain
 .. automodule:: openedx_filters.course_authoring.filters
    :members:
 
+Authentication Subdomain
+*************************
+
+.. automodule:: openedx_filters.authentication.filters
+   :members:
+
+Some of these filters hand their pipeline steps payloads whose shape is declared as a
+structural type, so that steps do not couple to a concrete platform implementation:
+
+.. automodule:: openedx_filters.authentication.types
+   :members:
+
 **Maintenance chart**
 
 +--------------+-------------------------------+----------------+--------------------------------+

openedx_filters/__init__.py

@@ -6,7 +6,7 @@
 
 from openedx_filters.filters import *
 
-__version__ = "3.8.0"
+__version__ = "3.9.0"
 
 if sys.version_info < (3, 12):  # pragma: no cover
     warnings.warn(

openedx_filters/authentication/__init__.py

@@ -0,0 +1,6 @@
+"""
+Filters related to the authentication subdomain.
+
+The authentication subdomain covers how users sign in, register, and are routed through
+login and registration flows.
+"""