From 9cbdf6219cd953f290acd8dacee19a4f34d66788 Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 8 Mar 2026 11:49:11 -0400 Subject: [PATCH 1/3] docs(auth): clarify login chain sequencing and security ordering reqs Signed-off-by: Josh --- lib/private/Authentication/Login/Chain.php | 24 ++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/lib/private/Authentication/Login/Chain.php b/lib/private/Authentication/Login/Chain.php index fc90d9225a7cd..4b20ff3254a58 100644 --- a/lib/private/Authentication/Login/Chain.php +++ b/lib/private/Authentication/Login/Chain.php @@ -8,6 +8,9 @@ */ namespace OC\Authentication\Login; +/** + * Orchestrates the login command chain in a security-sensitive order for interactive authentication. + */ class Chain { public function __construct( private PreLoginHookCommand $preLoginHookCommand, @@ -25,19 +28,36 @@ public function __construct( ) { } + /** + * Runs the login pipeline for one login attempt. + * + * Commands share mutable LoginData and may have side effects. + * A command may opt to permit processing to continue or return a final LoginResult early. + * + * If order changes, review login-flow invariants and related tests. + */ public function process(LoginData $loginData): LoginResult { + // Phase 1: pre-auth hooks and eligibility checks $chain = $this->preLoginHookCommand; $chain ->setNext($this->userDisabledCheckCommand) + + // Phase 2: primary authentication and login-state transition ->setNext($this->uidLoginCommand) ->setNext($this->loggedInCheckCommand) ->setNext($this->completeLoginCommand) - ->setNext($this->flowV2EphemeralSessionsCommand) + + // Phase 3: session strategy and token materialization + ->setNext($this->flowV2EphemeralSessionsCommand) // must precede standard token creation ->setNext($this->createSessionTokenCommand) + + // Phase 4: post-auth maintenance and context updates ->setNext($this->clearLostPasswordTokensCommand) ->setNext($this->updateLastPasswordConfirmCommand) ->setNext($this->setUserTimezoneCommand) - ->setNext($this->twoFactorCommand) + + // Phase 5: assurance/finalization gates + ->setNext($this->twoFactorCommand) // before remembered-login finalization ->setNext($this->finishRememberedLoginCommand); return $chain->process($loginData); From 3dd0b3602d7c1fbd7b3620c665a3becaf34863f6 Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 8 Mar 2026 12:33:06 -0400 Subject: [PATCH 2/3] docs(auth): clarify WebAuthn login chain sequencing and security ordering reqs Signed-off-by: Josh --- .../Authentication/Login/WebAuthnChain.php | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/lib/private/Authentication/Login/WebAuthnChain.php b/lib/private/Authentication/Login/WebAuthnChain.php index 6732a4339fa8c..d137b472e3e96 100644 --- a/lib/private/Authentication/Login/WebAuthnChain.php +++ b/lib/private/Authentication/Login/WebAuthnChain.php @@ -8,6 +8,14 @@ */ namespace OC\Authentication\Login; +/** + * Orchestrates the WebAuthn (passkeys/security keys) login command chain in a + * security-sensitive order for interactive authentication. + * + * Mirrors the main login-chain {@see Chain} with adaptations to the + * WebAuthn-specific authentication flow (i.e., no pre-login hook or Flow v2 + * ephemeral-session step). + */ class WebAuthnChain { public function __construct( private UserDisabledCheckCommand $userDisabledCheckCommand, @@ -23,17 +31,28 @@ public function __construct( ) { } + /** + * Runs the WebAuthn login pipeline for one login attempt. + */ public function process(LoginData $loginData): LoginResult { + // Phase 1: pre-auth eligibility checks $chain = $this->userDisabledCheckCommand; $chain + // Phase 2: primary authentication and login-state transition ->setNext($this->webAuthnLoginCommand) ->setNext($this->loggedInCheckCommand) ->setNext($this->completeLoginCommand) + + // Phase 3: session strategy and token materialization ->setNext($this->createSessionTokenCommand) + + // Phase 4: post-auth maintenance and context updates ->setNext($this->clearLostPasswordTokensCommand) ->setNext($this->updateLastPasswordConfirmCommand) ->setNext($this->setUserTimezoneCommand) - ->setNext($this->twoFactorCommand) + + // Phase 5: assurance/finalization gates + ->setNext($this->twoFactorCommand) // before remembered-login finalization ->setNext($this->finishRememberedLoginCommand); return $chain->process($loginData); From 674bf104e79a906a6c93165eb822031ce18bed0c Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 8 Mar 2026 12:54:50 -0400 Subject: [PATCH 3/3] chore(WebAuthnChain.php): make php-cs happy Signed-off-by: Josh --- lib/private/Authentication/Login/WebAuthnChain.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/private/Authentication/Login/WebAuthnChain.php b/lib/private/Authentication/Login/WebAuthnChain.php index d137b472e3e96..289b916bfaf3f 100644 --- a/lib/private/Authentication/Login/WebAuthnChain.php +++ b/lib/private/Authentication/Login/WebAuthnChain.php @@ -12,7 +12,7 @@ * Orchestrates the WebAuthn (passkeys/security keys) login command chain in a * security-sensitive order for interactive authentication. * - * Mirrors the main login-chain {@see Chain} with adaptations to the + * Mirrors the main login-chain {@see Chain} with adaptations to the * WebAuthn-specific authentication flow (i.e., no pre-login hook or Flow v2 * ephemeral-session step). */