JAMES-4210 Introduce shared SASL SPI

Introduce a protocol-neutral SASL SPI in `protocols/api`.

The new API models SASL as a stateful exchange with protocol-neutral
initial requests, continuation steps, success/failure results, and
authentication identities. It also exposes password and bearer-token
authentication service contracts through `SaslSessionContext` so future
mechanism implementations do not depend directly on IMAP or SMTP classes.

Add contract tests covering one-step mechanisms, multi-step mechanisms,
password-like authentication through the context service contract,
delegated identities, defensive byte-array copying, and exchange cleanup.

Author: quantranhong1999

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/BearerTokenSaslAuthenticationService.java

@@ -0,0 +1,32 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+import org.apache.james.core.Username;
+
+/**
+ * Protocol-provided service used by bearer-token based SASL mechanisms.
+ */
+public interface BearerTokenSaslAuthenticationService {
+    /**
+     * Authenticates the token and returns the authenticated SASL identity.
+     */
+    SaslAuthenticationResult authenticate(String token, Username authorizationId);
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/PasswordSaslAuthenticationService.java

@@ -0,0 +1,34 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+import java.util.Optional;
+
+import org.apache.james.core.Username;
+
+/**
+ * Protocol-provided service used by password based SASL mechanisms.
+ */
+public interface PasswordSaslAuthenticationService {
+    /**
+     * Authenticates the supplied credentials and returns the authenticated SASL identity.
+     */
+    SaslAuthenticationResult authenticate(Username authenticationId, String password, Optional<Username> authorizationId);
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslAuthenticationResult.java

@@ -0,0 +1,37 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+/**
+ * Result returned by protocol-provided authentication services.
+ */
+public interface SaslAuthenticationResult {
+    /**
+     * Successful authentication result.
+     */
+    record Success(SaslIdentity identity, String log) implements SaslAuthenticationResult {
+    }
+
+    /**
+     * Failed authentication result.
+     */
+    record Failure(String log) implements SaslAuthenticationResult {
+    }
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslExchange.java

@@ -0,0 +1,43 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+/**
+ * Stateful SASL authentication exchange.
+ */
+public interface SaslExchange extends AutoCloseable {
+    /**
+     * Starts the exchange and returns the first server step.
+     */
+    SaslStep firstStep();
+
+    /**
+     * Continues the exchange with a decoded client response.
+     */
+    SaslStep onResponse(byte[] clientResponse);
+
+    /**
+     * Aborts the exchange after a client cancellation or protocol-level failure.
+     */
+    void abort();
+
+    @Override
+    void close();
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslIdentity.java

@@ -0,0 +1,31 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+import org.apache.james.core.Username;
+
+/**
+ * SASL authentication and authorization identities.
+ *
+ * @param authenticationId identity proven by the SASL mechanism
+ * @param authorizationId identity requested for protocol access
+ */
+public record SaslIdentity(Username authenticationId, Username authorizationId) {
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslInitialRequest.java

@@ -0,0 +1,49 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * Protocol-neutral initial SASL request.
+ *
+ * @param protocol protocol receiving the SASL exchange
+ * @param mechanismName requested SASL mechanism name
+ * @param initialResponse decoded initial client response, when supplied by the client
+ */
+public record SaslInitialRequest(SaslProtocol protocol, String mechanismName, Optional<byte[]> initialResponse) {
+    public SaslInitialRequest(SaslProtocol protocol, String mechanismName, Optional<byte[]> initialResponse) {
+        Objects.requireNonNull(protocol);
+        Objects.requireNonNull(mechanismName);
+        Objects.requireNonNull(initialResponse);
+
+        this.protocol = protocol;
+        this.mechanismName = mechanismName;
+        this.initialResponse = initialResponse.map(byte[]::clone);
+    }
+
+    /**
+     * Returns a defensive copy of the decoded initial client response.
+     */
+    public Optional<byte[]> initialResponse() {
+        return initialResponse.map(byte[]::clone);
+    }
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslMechanism.java

@@ -0,0 +1,45 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+/**
+ * Protocol-neutral SASL mechanism.
+ */
+public interface SaslMechanism {
+    /**
+     * Returns the SASL mechanism name advertised to clients.
+     */
+    String name();
+
+    /**
+     * Whether this mechanism can be used by the supplied protocol.
+     */
+    boolean supports(SaslProtocol protocol);
+
+    /**
+     * Whether this mechanism is currently usable for the supplied session context.
+     */
+    boolean isAvailable(SaslSessionContext context);
+
+    /**
+     * Starts a new SASL exchange for one client authentication attempt.
+     */
+    SaslExchange start(SaslInitialRequest request, SaslSessionContext context);
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslProtocol.java

@@ -0,0 +1,30 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+/**
+ * Protocols that can host SASL authentication.
+ */
+public enum SaslProtocol {
+    IMAP,
+    SMTP,
+    MANAGESIEVE,
+    POP3
+}

protocols/api/src/main/java/org/apache/james/protocols/api/sasl/SaslSessionContext.java

@@ -0,0 +1,47 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one   *
+ * or more contributor license agreements.  See the NOTICE file *
+ * distributed with this work for additional information        *
+ * regarding copyright ownership.  The ASF licenses this file   *
+ * to you under the Apache License, Version 2.0 (the            *
+ * "License"); you may not use this file except in compliance   *
+ * with the License.  You may obtain a copy of the License at   *
+ *                                                              *
+ *   http://www.apache.org/licenses/LICENSE-2.0                 *
+ *                                                              *
+ * Unless required by applicable law or agreed to in writing,   *
+ * software distributed under the License is distributed on an  *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
+ * KIND, either express or implied.  See the License for the    *
+ * specific language governing permissions and limitations      *
+ * under the License.                                           *
+ ****************************************************************/
+
+package org.apache.james.protocols.api.sasl;
+
+import java.util.Optional;
+
+/**
+ * Protocol-provided context exposed to SASL mechanisms.
+ */
+public interface SaslSessionContext {
+    /**
+     * Protocol currently running the SASL exchange.
+     */
+    SaslProtocol protocol();
+
+    /**
+     * Whether TLS is active for the current session.
+     */
+    boolean isTlsStarted();
+
+    /**
+     * Looks up optional protocol or server configuration required by a mechanism.
+     */
+    <T> Optional<T> configuration(Class<T> configurationType);
+
+    /**
+     * Looks up protocol-provided services, such as password or bearer-token authentication.
+     */
+    <T> Optional<T> service(Class<T> serviceType);
+}