feat: configure authenticated player entry routes

docs/openapi.yaml

@@ -341,6 +341,18 @@ components:
         startedAt: { type: string, format: date-time }
         logsAvailable: { type: boolean }
 
+    EntryPolicySettings:
+      type: object
+      required: [mode, defaultServer, requireAccountLink, offlineAction, waitingSpace, fallbackServer, revision]
+      properties:
+        mode: { type: string, enum: [lobby, direct, domain] }
+        defaultServer: { type: string, description: Required for direct mode; optional fallback destination for unmatched hostnames. }
+        requireAccountLink: { type: boolean, description: Require Limbo web sign-in and panel association in addition to proxy game identity authentication. }
+        offlineAction: { type: string, enum: [wake, fallback, disconnect] }
+        waitingSpace: { type: string, enum: [login, lobby], description: Web sign-in currently requires lobby waiting. }
+        fallbackServer: { type: string, description: Required for fallback action and distinct from the default server. }
+        revision: { type: string, description: Opaque revision; stale or concurrent writes return 409. }
+
     WakePolicySettings:
       type: object
       required: [maxRunningServers, wakeCooldownSeconds, revision, managed]
@@ -4454,6 +4466,65 @@ paths:
         '409': { description: Another node task is running or this task cannot be retried. }
         '503': { description: Host node execution service is unavailable. }
 
+  /api/v1/internal/settings/entry-policy:
+    get:
+      tags: [internal]
+      operationId: internalEntryPolicy
+      summary: Read player entry policy for the authenticated proxy and login gate.
+      x-felis-face: [internal]
+      x-felis-tier: service
+      x-felis-callers: [velocity, limbo]
+      security: [{ serviceToken: [] }]
+      responses:
+        '200':
+          description: Current policy; proxy snapshots it for each new connection.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/EntryPolicySettings' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+
+  /api/v1/settings/entry-policy:
+    get:
+      tags: [account]
+      operationId: getEntryPolicy
+      summary: Read player entry policy (Owner).
+      x-felis-face: [external]
+      x-felis-tier: owner
+      security: [{ sessionCookie: [] }]
+      responses:
+        '200':
+          description: Current policy and revision; an unsaved deployment preserves its legacy routing.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/EntryPolicySettings' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+    put:
+      tags: [account]
+      operationId: setEntryPolicy
+      summary: Save player entry policy (Owner, fresh reauthentication).
+      description: Applies to new connections within the proxy's 15-second refresh interval. Does not change online-mode, autostart authorization or existing players, and does not stop system spaces automatically.
+      x-felis-face: [external]
+      x-felis-tier: owner
+      security: [{ sessionCookie: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/EntryPolicySettings' }
+      responses:
+        '200':
+          description: Saved policy and revision.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/EntryPolicySettings' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { description: Selected server does not exist. }
+        '409': { description: Policy changed; reload before saving. }
+
   /api/v1/settings/wake-policy:
     get:
       tags: [account]

docs/operations.md

@@ -903,3 +903,49 @@ configuration, or test the profile-query API.
 Saving requires Owner access on the operator host and recent reauthentication for
 a local session. A revision conflict preserves the draft; discard it and reload
 before editing the newer configuration.
+
+## 8. Player entry policy
+
+Owner → Platform settings → Player entry policy configures the proxy's destination
+independently from game identity authentication and panel account association.
+
+| Mode | Destination after authentication |
+| --- | --- |
+| Lobby | Formal lobby, where the player selects a server |
+| Direct to main server | Selected main server, regardless of connection hostname |
+| Route by hostname | Server matched by hostname; optional default for unmatched hostnames |
+
+For a single-server deployment, select **Direct to main server**, choose the main
+server, and disable **Require panel account linking**. A running main server then
+accepts authenticated players without entering the login space or lobby. Game
+identity authentication and the global blacklist remain enforced; this setting does
+not enable offline-mode or change authentication sources. Players can associate a
+panel account separately through `/link`.
+
+Choose how to handle an offline destination:
+
+- **Start automatically and wait** uses the existing wake permission, maintenance,
+  admission limit and cooldown checks. Select a running Limbo login space or formal
+  lobby for the wait. An unlinked player requires an autostart policy that permits
+  their verified identity; selecting a main server does not grant startup rights.
+- **Enter a fallback server** requires a separate running server. The proxy does not
+  start the fallback implicitly; it rejects the connection if both destinations
+  are unavailable.
+- **Reject with an explanation** requires no waiting space.
+
+When panel account linking is required, Limbo retains its web sign-in, blacklist
+check, timeout and release controls. The existing web sign-in flow requires the
+login space and formal lobby, and uses the lobby for startup waiting. Automatic
+Limbo waiting does not issue a link code or start a web sign-in timer; the proxy's
+queue controls startup progress and disconnects Limbo waits after failure or timeout.
+A failed transfer includes the backend refusal when available.
+
+Saving requires fresh Owner reauthentication and the current revision. The proxy
+reads changes within 15 seconds and snapshots the policy for each new connection;
+current players keep their connection policy. Existing deployments retain hostname
+routing, required web sign-in and lobby waiting until a policy is saved. Update the
+API and game plugins together before using this setting.
+
+Unused login/lobby spaces can be stopped from **Login & lobby**. Saving a policy
+does not stop them automatically or disconnect existing players. Re-running setup
+preserves the desired state of existing system servers.