docs(auth): clarify login chain sequencing and security ordering requirements

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);

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);