feat(api): publish stable connect-player channel marker

AGENTS.md

@@ -69,6 +69,17 @@ curl -I -L --fail https://github.com/minekube/connect-java/releases/download/<ve
   this with `includeTransitiveDeps = false`; back-porting that into a tag would
   change what the tag builds, so it is a rewrite, not a repair.
 
+## Public integration contract for login/auth plugins
+
+- The `connect-player` Netty channel attribute is a **permanent** public contract:
+  once external login plugins depend on the name it may never be removed, renamed,
+  or moved later in the connection lifecycle. Additive changes only.
+- Authoritative sources: `api/.../api/ConnectAttributes.java` (key + Javadoc contract),
+  the single set-site in `core/.../network/netty/LocalServerChannelWrapper.java`, and
+  `docs/login-plugin-integration.md` (the integrator-facing doc and the stability
+  commitment). Pinned by
+  `core/.../network/netty/ConnectPlayerAttributeBoundaryTest`.
+
 ## Injector Scoping (config availability)
 
 - The parent injector binds `ConfigHolder`; `ConnectPlatform.init()` populates it

README.md

@@ -13,6 +13,16 @@ low latency edge proxies network nearest to you.
 
 Please refer to https://connect.minekube.com for more documentation.
 
+## Integrating with login / auth plugins
+
+Connect authenticates players at the edge, so login plugins that force online mode on a
+Connect-tunneled connection hang the player's login. Connect publishes a stable
+`connect-player` channel attribute (mirroring Floodgate's `floodgate-player`) so any login
+plugin can detect a Connect player and skip its own flow.
+
+See [docs/login-plugin-integration.md](docs/login-plugin-integration.md) for the supported
+integration contract and its permanent-stability commitment.
+
 ## Connect libp2p endpoint mode
 
 The Connect libp2p endpoint path is enabled by configuring the Connect edge peer

api/src/main/java/com/minekube/connect/api/ConnectAttributes.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2021-2022 Minekube. https://minekube.com
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author Minekube
+ * @link https://github.com/minekube/connect-java
+ */
+
+package com.minekube.connect.api;
+
+import com.minekube.connect.api.player.ConnectPlayer;
+import io.netty.util.AttributeKey;
+
+/**
+ * Netty channel attributes Connect publishes for third-party plugins.
+ *
+ * <p><b>Stable public contract.</b> The attribute <i>names</i> in this class are a permanent part
+ * of Connect's public integration surface. External plugins (login/auth plugins in particular)
+ * identify Connect-tunneled connections by these names, usually without compiling against Connect
+ * at all. They will therefore never be removed or renamed. Treat them exactly like a published
+ * method signature: additive changes only.
+ */
+public final class ConnectAttributes {
+    /**
+     * Marks a proxy-facing connection as <b>already authenticated by Connect at the edge</b>.
+     *
+     * <p>The wire-visible attribute name is exactly {@code "connect-player"}, deliberately
+     * mirroring Floodgate's {@code "floodgate-player"} convention so plugin authors who already
+     * exempt Floodgate players can apply the identical pattern.
+     *
+     * <p><b>When it is set.</b> Connect sets this attribute when it creates the proxy-facing
+     * channel, before any platform login event fires, so it is readable from Velocity's
+     * {@code PreLoginEvent}/{@code GameProfileRequestEvent}, BungeeCord's {@code PreLoginEvent},
+     * and Spigot's login handling alike. It is set <b>only</b> for sessions Connect itself
+     * authenticated, i.e. when {@link com.minekube.connect.api.player.Auth#isPassthrough()} is
+     * {@code false}. Passthrough sessions are not authenticated by Connect and must still go
+     * through the server's own login flow, so the attribute is absent for them.
+     *
+     * <p><b>How to integrate.</b> A plugin that forces online mode, rewrites the game profile, or
+     * gates the player behind its own login flow should skip all of that when this attribute is
+     * present:
+     *
+     * <pre>{@code
+     * private static final AttributeKey<Object> CONNECT_PLAYER =
+     *         AttributeKey.valueOf("connect-player");
+     *
+     * if (channel.hasAttr(CONNECT_PLAYER) && channel.attr(CONNECT_PLAYER).get() != null) {
+     *     return; // externally authenticated by Connect - do not force online mode
+     * }
+     * }</pre>
+     *
+     * <p>Netty keys are interned by name, so the snippet above works without any compile-time
+     * dependency on Connect: presence alone is the signal. Plugins that do depend on Connect's API
+     * jar can use this constant directly and read the {@link ConnectPlayer} value for the player's
+     * real Mojang UUID, username and game profile. That is why the value is a {@code ConnectPlayer}
+     * rather than a bare {@code UUID} - it carries everything an integrator has been observed to
+     * need (identity, skin properties, {@link com.minekube.connect.api.player.Auth}), while callers
+     * who only need the boolean "is this Connect?" answer pay nothing for it.
+     *
+     * <p>Once the player is online, {@link ConnectApi#isConnectPlayer(java.util.UUID)} and
+     * {@link ConnectApi#getPlayer(java.util.UUID)} provide the same information keyed by UUID.
+     * This attribute exists because those lookups are only available after login completes, which
+     * is too late to avoid conflicting with Connect during login.
+     */
+    public static final AttributeKey<ConnectPlayer> CONNECT_PLAYER =
+            AttributeKey.valueOf("connect-player");
+
+    private ConnectAttributes() {
+    }
+}

core/src/main/java/com/minekube/connect/network/netty/LocalServerChannelWrapper.java

@@ -25,6 +25,9 @@
 
 package com.minekube.connect.network.netty;
 
+import com.minekube.connect.api.ConnectAttributes;
+import com.minekube.connect.api.player.ConnectPlayer;
+import com.minekube.connect.network.netty.LocalSession.Context;
 import io.netty.channel.local.LocalChannel;
 import io.netty.channel.local.LocalServerChannel;
 
@@ -40,9 +43,31 @@ protected LocalChannel newLocalChannel(LocalChannel peer) {
         // and access related session data from the channel
         if (peer instanceof LocalChannelWithSessionContext) {
             LocalChannelWrapper channel = new LocalChannelWrapper(this, peer);
-            channel.wrapper().setContext(((LocalChannelWithSessionContext) peer).getContext());
+            Context context = ((LocalChannelWithSessionContext) peer).getContext();
+            channel.wrapper().setContext(context);
+            markExternallyAuthenticated(channel, context);
             return channel;
         }
         return super.newLocalChannel(peer);
     }
+
+    /**
+     * Publishes the {@link ConnectAttributes#CONNECT_PLAYER} marker on the proxy-facing channel.
+     *
+     * <p>This is the earliest point at which both the channel and the Connect player identity
+     * exist, so the marker is readable by every platform's login handling (Velocity, BungeeCord,
+     * Spigot) before any of their events fire. Passthrough sessions are not authenticated by
+     * Connect and are deliberately left unmarked so they still go through the server's own login
+     * flow. See {@link ConnectAttributes#CONNECT_PLAYER} for the public contract.
+     */
+    private static void markExternallyAuthenticated(LocalChannelWrapper channel, Context context) {
+        if (context == null) {
+            return;
+        }
+        ConnectPlayer player = context.getPlayer();
+        if (player == null || player.getAuth() == null || player.getAuth().isPassthrough()) {
+            return;
+        }
+        channel.attr(ConnectAttributes.CONNECT_PLAYER).set(player);
+    }
 }

core/src/test/java/com/minekube/connect/network/netty/ConnectPlayerAttributeBoundaryTest.java

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2021-2022 Minekube. https://minekube.com
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author Minekube
+ * @link https://github.com/minekube/connect-java
+ */
+
+package com.minekube.connect.network.netty;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.minekube.connect.api.ConnectAttributes;
+import com.minekube.connect.api.player.Auth;
+import com.minekube.connect.api.player.ConnectPlayer;
+import com.minekube.connect.network.netty.LocalSession.Context;
+import com.minekube.connect.watch.SessionProposal;
+import io.netty.channel.local.LocalChannel;
+import io.netty.util.AttributeKey;
+import java.lang.reflect.Constructor;
+import java.net.InetSocketAddress;
+import minekube.connect.v1alpha1.WatchServiceOuterClass.SessionProtocol;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Boundary test for the public {@code connect-player} channel attribute.
+ *
+ * <p>The attribute name and the place it is set are a permanent public contract that third-party
+ * login plugins depend on (see {@link ConnectAttributes#CONNECT_PLAYER}). Renaming the attribute,
+ * or moving the marker off the proxy-facing channel creation path, silently breaks every external
+ * integration - so both are pinned here.
+ */
+class ConnectPlayerAttributeBoundaryTest {
+
+    /**
+     * The literal a third-party plugin writes. Deliberately duplicated instead of referencing the
+     * constant: a rename of the constant's value must fail this test.
+     */
+    private static final String WIRE_NAME = "connect-player";
+
+    @Test
+    void attributeNameIsExactlyConnectPlayer() {
+        assertEquals(WIRE_NAME, ConnectAttributes.CONNECT_PLAYER.name(),
+                "connect-player is a permanent public contract and must not be renamed");
+    }
+
+    @Test
+    void markerIsSetOnProxyFacingChannelForAuthenticatedSession() {
+        ConnectPlayer player = connectPlayer(false);
+        LocalChannel channel = newProxyFacingChannel(player);
+
+        // Read it back exactly the way an external plugin would: by name only, with no
+        // compile-time dependency on Connect.
+        AttributeKey<Object> externalKey = AttributeKey.valueOf(WIRE_NAME);
+        assertNotNull(channel.attr(externalKey).get(),
+                "externally authenticated Connect sessions must be marked at channel creation");
+        assertSame(player, channel.attr(ConnectAttributes.CONNECT_PLAYER).get());
+    }
+
+    @Test
+    void markerIsAbsentForPassthroughSession() {
+        LocalChannel channel = newProxyFacingChannel(connectPlayer(true));
+
+        assertNull(channel.attr(AttributeKey.valueOf(WIRE_NAME)).get(),
+                "passthrough sessions are not authenticated by Connect and must still go "
+                        + "through the server's own login flow");
+    }
+
+    /**
+     * Drives the real production path: {@link LocalServerChannelWrapper#newLocalChannel} is what
+     * creates the channel the proxy's login handling sees.
+     */
+    private static LocalChannel newProxyFacingChannel(ConnectPlayer player) {
+        LocalChannelWithSessionContext peer = new LocalChannelWithSessionContext();
+        peer.setContext(context(player));
+        return new LocalServerChannelWrapper().newLocalChannel(peer);
+    }
+
+    private static ConnectPlayer connectPlayer(boolean passthrough) {
+        ConnectPlayer player = mock(ConnectPlayer.class);
+        when(player.getAuth()).thenReturn(new Auth(passthrough));
+        return player;
+    }
+
+    private static Context context(ConnectPlayer player) {
+        try {
+            Constructor<Context> constructor = Context.class.getDeclaredConstructor(
+                    ConnectPlayer.class,
+                    InetSocketAddress.class,
+                    SessionProposal.class,
+                    String.class,
+                    String.class,
+                    SessionProtocol.class,
+                    com.minekube.connect.bedrock.BedrockAdmissionCoordinator.AdmissionToken.class);
+            constructor.setAccessible(true);
+            return constructor.newInstance(
+                    player,
+                    new InetSocketAddress("127.0.0.1", 0),
+                    mock(SessionProposal.class),
+                    "endpoint",
+                    "org",
+                    SessionProtocol.SESSION_PROTOCOL_JAVA,
+                    null);
+        } catch (ReflectiveOperationException e) {
+            throw new IllegalStateException(
+                    "LocalSession.Context shape changed; update the connect-player boundary test",
+                    e);
+        }
+    }
+}