@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/discord/voice/manager.js

@@ -0,0 +1,531 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { ChannelType, ReadyListener } from "@buape/carbon";
+import { AudioPlayerStatus, EndBehaviorType, VoiceConnectionStatus, createAudioPlayer, createAudioResource, entersState, joinVoiceChannel, } from "@discordjs/voice";
+import { resolveAgentDir } from "../../agents/agent-scope.js";
+import { agentCommand } from "../../commands/agent.js";
+import { logVerbose, shouldLogVerbose } from "../../globals.js";
+import { formatErrorMessage } from "../../infra/errors.js";
+import { resolvePreferredPoolbotTmpDir } from "../../infra/tmp-poolbot-dir.js";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+import { buildProviderRegistry, createMediaAttachmentCache, normalizeMediaAttachments, runCapability, } from "../../media-understanding/runner.js";
+import { resolveAgentRoute } from "../../routing/resolve-route.js";
+import { parseTtsDirectives } from "../../tts/tts-core.js";
+import { resolveTtsConfig, textToSpeech } from "../../tts/tts.js";
+const require = createRequire(import.meta.url);
+const SAMPLE_RATE = 48_000;
+const CHANNELS = 2;
+const BIT_DEPTH = 16;
+const MIN_SEGMENT_SECONDS = 0.35;
+const SILENCE_DURATION_MS = 1_000;
+const PLAYBACK_READY_TIMEOUT_MS = 15_000;
+const SPEAKING_READY_TIMEOUT_MS = 60_000;
+const logger = createSubsystemLogger("discord/voice");
+const logVoiceVerbose = (message) => {
+    logVerbose(`discord voice: ${message}`);
+};
+function mergeTtsConfig(base, override) {
+    if (!override) {
+        return base;
+    }
+    return {
+        ...base,
+        ...override,
+        modelOverrides: {
+            ...base.modelOverrides,
+            ...override.modelOverrides,
+        },
+        elevenlabs: {
+            ...base.elevenlabs,
+            ...override.elevenlabs,
+            voiceSettings: {
+                ...base.elevenlabs?.voiceSettings,
+                ...override.elevenlabs?.voiceSettings,
+            },
+        },
+        openai: {
+            ...base.openai,
+            ...override.openai,
+        },
+        edge: {
+            ...base.edge,
+            ...override.edge,
+        },
+    };
+}
+function resolveVoiceTtsConfig(params) {
+    if (!params.override) {
+        return { cfg: params.cfg, resolved: resolveTtsConfig(params.cfg) };
+    }
+    const base = params.cfg.messages?.tts ?? {};
+    const merged = mergeTtsConfig(base, params.override);
+    const messages = params.cfg.messages ?? {};
+    const cfg = {
+        ...params.cfg,
+        messages: {
+            ...messages,
+            tts: merged,
+        },
+    };
+    return { cfg, resolved: resolveTtsConfig(cfg) };
+}
+function buildWavBuffer(pcm) {
+    const blockAlign = (CHANNELS * BIT_DEPTH) / 8;
+    const byteRate = SAMPLE_RATE * blockAlign;
+    const header = Buffer.alloc(44);
+    header.write("RIFF", 0);
+    header.writeUInt32LE(36 + pcm.length, 4);
+    header.write("WAVE", 8);
+    header.write("fmt ", 12);
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(CHANNELS, 22);
+    header.writeUInt32LE(SAMPLE_RATE, 24);
+    header.writeUInt32LE(byteRate, 28);
+    header.writeUInt16LE(blockAlign, 32);
+    header.writeUInt16LE(BIT_DEPTH, 34);
+    header.write("data", 36);
+    header.writeUInt32LE(pcm.length, 40);
+    return Buffer.concat([header, pcm]);
+}
+function createOpusDecoder() {
+    try {
+        const OpusScript = require("opusscript");
+        const decoder = new OpusScript(SAMPLE_RATE, CHANNELS, OpusScript.Application.AUDIO);
+        return { decoder, name: "opusscript" };
+    }
+    catch (err) {
+        logger.warn(`discord voice: opusscript init failed: ${formatErrorMessage(err)}`);
+    }
+    try {
+        const { OpusEncoder } = require("@discordjs/opus");
+        const decoder = new OpusEncoder(SAMPLE_RATE, CHANNELS);
+        return { decoder, name: "@discordjs/opus" };
+    }
+    catch (err) {
+        logger.warn(`discord voice: opus decoder init failed: ${formatErrorMessage(err)}`);
+    }
+    return null;
+}
+async function decodeOpusStream(stream) {
+    const selected = createOpusDecoder();
+    if (!selected) {
+        return Buffer.alloc(0);
+    }
+    logVoiceVerbose(`opus decoder: ${selected.name}`);
+    const chunks = [];
+    try {
+        for await (const chunk of stream) {
+            if (!chunk || !(chunk instanceof Buffer) || chunk.length === 0) {
+                continue;
+            }
+            const decoded = selected.decoder.decode(chunk);
+            if (decoded && decoded.length > 0) {
+                chunks.push(Buffer.from(decoded));
+            }
+        }
+    }
+    catch (err) {
+        if (shouldLogVerbose()) {
+            logVerbose(`discord voice: opus decode failed: ${formatErrorMessage(err)}`);
+        }
+    }
+    return chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
+}
+function estimateDurationSeconds(pcm) {
+    const bytesPerSample = (BIT_DEPTH / 8) * CHANNELS;
+    if (bytesPerSample <= 0) {
+        return 0;
+    }
+    return pcm.length / (bytesPerSample * SAMPLE_RATE);
+}
+async function writeWavFile(pcm) {
+    const tempDir = await fs.mkdtemp(path.join(resolvePreferredPoolbotTmpDir(), "discord-voice-"));
+    const filePath = path.join(tempDir, `segment-${randomUUID()}.wav`);
+    const wav = buildWavBuffer(pcm);
+    await fs.writeFile(filePath, wav);
+    scheduleTempCleanup(tempDir);
+    return { path: filePath, durationSeconds: estimateDurationSeconds(pcm) };
+}
+function scheduleTempCleanup(tempDir, delayMs = 30 * 60 * 1000) {
+    const timer = setTimeout(() => {
+        fs.rm(tempDir, { recursive: true, force: true }).catch((err) => {
+            if (shouldLogVerbose()) {
+                logVerbose(`discord voice: temp cleanup failed for ${tempDir}: ${formatErrorMessage(err)}`);
+            }
+        });
+    }, delayMs);
+    timer.unref();
+}
+async function transcribeAudio(params) {
+    const ctx = {
+        MediaPath: params.filePath,
+        MediaType: "audio/wav",
+    };
+    const attachments = normalizeMediaAttachments(ctx);
+    if (attachments.length === 0) {
+        return undefined;
+    }
+    const cache = createMediaAttachmentCache(attachments);
+    const providerRegistry = buildProviderRegistry();
+    try {
+        const result = await runCapability({
+            capability: "audio",
+            cfg: params.cfg,
+            ctx,
+            attachments: cache,
+            media: attachments,
+            agentDir: resolveAgentDir(params.cfg, params.agentId),
+            providerRegistry,
+            config: params.cfg.tools?.media?.audio,
+        });
+        const output = result.outputs.find((entry) => entry.kind === "audio.transcription");
+        const text = output?.text?.trim();
+        return text || undefined;
+    }
+    finally {
+        await cache.cleanup();
+    }
+}
+export class DiscordVoiceManager {
+    params;
+    sessions = new Map();
+    botUserId;
+    voiceEnabled;
+    autoJoinTask = null;
+    constructor(params) {
+        this.params = params;
+        this.botUserId = params.botUserId;
+        this.voiceEnabled = params.discordConfig.voice?.enabled !== false;
+    }
+    setBotUserId(id) {
+        if (id) {
+            this.botUserId = id;
+        }
+    }
+    isEnabled() {
+        return this.voiceEnabled;
+    }
+    async autoJoin() {
+        if (!this.voiceEnabled) {
+            return;
+        }
+        if (this.autoJoinTask) {
+            return this.autoJoinTask;
+        }
+        this.autoJoinTask = (async () => {
+            const entries = this.params.discordConfig.voice?.autoJoin ?? [];
+            logVoiceVerbose(`autoJoin: ${entries.length} entries`);
+            const seenGuilds = new Set();
+            for (const entry of entries) {
+                const guildId = entry.guildId.trim();
+                if (!guildId) {
+                    continue;
+                }
+                if (seenGuilds.has(guildId)) {
+                    logger.warn(`discord voice: autoJoin has multiple entries for guild ${guildId}; skipping`);
+                    continue;
+                }
+                seenGuilds.add(guildId);
+                logVoiceVerbose(`autoJoin: joining guild ${guildId} channel ${entry.channelId}`);
+                await this.join({
+                    guildId: entry.guildId,
+                    channelId: entry.channelId,
+                });
+            }
+        })().finally(() => {
+            this.autoJoinTask = null;
+        });
+        return this.autoJoinTask;
+    }
+    status() {
+        return Array.from(this.sessions.values()).map((session) => ({
+            ok: true,
+            message: `connected: guild ${session.guildId} channel ${session.channelId}`,
+            guildId: session.guildId,
+            channelId: session.channelId,
+        }));
+    }
+    async join(params) {
+        if (!this.voiceEnabled) {
+            return {
+                ok: false,
+                message: "Discord voice is disabled (channels.discord.voice.enabled).",
+            };
+        }
+        const guildId = params.guildId.trim();
+        const channelId = params.channelId.trim();
+        if (!guildId || !channelId) {
+            return { ok: false, message: "Missing guildId or channelId." };
+        }
+        logVoiceVerbose(`join requested: guild ${guildId} channel ${channelId}`);
+        const existing = this.sessions.get(guildId);
+        if (existing && existing.channelId === channelId) {
+            logVoiceVerbose(`join: already connected to guild ${guildId} channel ${channelId}`);
+            return { ok: true, message: `Already connected to <#${channelId}>.`, guildId, channelId };
+        }
+        if (existing) {
+            logVoiceVerbose(`join: replacing existing session for guild ${guildId}`);
+            await this.leave({ guildId });
+        }
+        const channelInfo = await this.params.client.fetchChannel(channelId).catch(() => null);
+        if (!channelInfo || ("type" in channelInfo && !isVoiceChannel(channelInfo.type))) {
+            return { ok: false, message: `Channel ${channelId} is not a voice channel.` };
+        }
+        const channelGuildId = "guildId" in channelInfo ? channelInfo.guildId : undefined;
+        if (channelGuildId && channelGuildId !== guildId) {
+            return { ok: false, message: "Voice channel is not in this guild." };
+        }
+        const voicePlugin = this.params.client.getPlugin("voice");
+        if (!voicePlugin) {
+            return { ok: false, message: "Discord voice plugin is not available." };
+        }
+        const adapterCreator = voicePlugin.getGatewayAdapterCreator(guildId);
+        const connection = joinVoiceChannel({
+            channelId,
+            guildId,
+            adapterCreator,
+            selfDeaf: false,
+            selfMute: false,
+        });
+        try {
+            await entersState(connection, VoiceConnectionStatus.Ready, PLAYBACK_READY_TIMEOUT_MS);
+            logVoiceVerbose(`join: connected to guild ${guildId} channel ${channelId}`);
+        }
+        catch (err) {
+            connection.destroy();
+            return { ok: false, message: `Failed to join voice channel: ${formatErrorMessage(err)}` };
+        }
+        const sessionChannelId = channelInfo?.id ?? channelId;
+        // Use the voice channel id as the session channel so text chat in the voice channel
+        // shares the same session as spoken audio.
+        if (sessionChannelId !== channelId) {
+            logVoiceVerbose(`join: using session channel ${sessionChannelId} for voice channel ${channelId}`);
+        }
+        const route = resolveAgentRoute({
+            cfg: this.params.cfg,
+            channel: "discord",
+            accountId: this.params.accountId,
+            guildId,
+            peer: { kind: "channel", id: sessionChannelId },
+        });
+        const player = createAudioPlayer();
+        connection.subscribe(player);
+        const entry = {
+            guildId,
+            channelId,
+            sessionChannelId,
+            route,
+            connection,
+            player,
+            playbackQueue: Promise.resolve(),
+            processingQueue: Promise.resolve(),
+            activeSpeakers: new Set(),
+            stop: () => {
+                player.stop();
+                connection.destroy();
+            },
+        };
+        const speakingHandler = (userId) => {
+            void this.handleSpeakingStart(entry, userId).catch((err) => {
+                logger.warn(`discord voice: capture failed: ${formatErrorMessage(err)}`);
+            });
+        };
+        connection.receiver.speaking.on("start", speakingHandler);
+        connection.on(VoiceConnectionStatus.Disconnected, async () => {
+            try {
+                await Promise.race([
+                    entersState(connection, VoiceConnectionStatus.Signalling, 5_000),
+                    entersState(connection, VoiceConnectionStatus.Connecting, 5_000),
+                ]);
+            }
+            catch {
+                this.sessions.delete(guildId);
+                connection.destroy();
+            }
+        });
+        connection.on(VoiceConnectionStatus.Destroyed, () => {
+            this.sessions.delete(guildId);
+        });
+        player.on("error", (err) => {
+            logger.warn(`discord voice: playback error: ${formatErrorMessage(err)}`);
+        });
+        this.sessions.set(guildId, entry);
+        return {
+            ok: true,
+            message: `Joined <#${channelId}>.`,
+            guildId,
+            channelId,
+        };
+    }
+    async leave(params) {
+        const guildId = params.guildId.trim();
+        logVoiceVerbose(`leave requested: guild ${guildId} channel ${params.channelId ?? "current"}`);
+        const entry = this.sessions.get(guildId);
+        if (!entry) {
+            return { ok: false, message: "Not connected to a voice channel." };
+        }
+        if (params.channelId && params.channelId !== entry.channelId) {
+            return { ok: false, message: "Not connected to that voice channel." };
+        }
+        entry.stop();
+        this.sessions.delete(guildId);
+        logVoiceVerbose(`leave: disconnected from guild ${guildId} channel ${entry.channelId}`);
+        return {
+            ok: true,
+            message: `Left <#${entry.channelId}>.`,
+            guildId,
+            channelId: entry.channelId,
+        };
+    }
+    async destroy() {
+        for (const entry of this.sessions.values()) {
+            entry.stop();
+        }
+        this.sessions.clear();
+    }
+    enqueueProcessing(entry, task) {
+        entry.processingQueue = entry.processingQueue
+            .then(task)
+            .catch((err) => logger.warn(`discord voice: processing failed: ${formatErrorMessage(err)}`));
+    }
+    enqueuePlayback(entry, task) {
+        entry.playbackQueue = entry.playbackQueue
+            .then(task)
+            .catch((err) => logger.warn(`discord voice: playback failed: ${formatErrorMessage(err)}`));
+    }
+    async handleSpeakingStart(entry, userId) {
+        if (!userId || entry.activeSpeakers.has(userId)) {
+            return;
+        }
+        if (this.botUserId && userId === this.botUserId) {
+            return;
+        }
+        entry.activeSpeakers.add(userId);
+        logVoiceVerbose(`capture start: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+        if (entry.player.state.status === AudioPlayerStatus.Playing) {
+            entry.player.stop(true);
+        }
+        const stream = entry.connection.receiver.subscribe(userId, {
+            end: {
+                behavior: EndBehaviorType.AfterSilence,
+                duration: SILENCE_DURATION_MS,
+            },
+        });
+        stream.on("error", (err) => {
+            logger.warn(`discord voice: receive error: ${formatErrorMessage(err)}`);
+        });
+        try {
+            const pcm = await decodeOpusStream(stream);
+            if (pcm.length === 0) {
+                logVoiceVerbose(`capture empty: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+                return;
+            }
+            const { path: wavPath, durationSeconds } = await writeWavFile(pcm);
+            if (durationSeconds < MIN_SEGMENT_SECONDS) {
+                logVoiceVerbose(`capture too short (${durationSeconds.toFixed(2)}s): guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+                return;
+            }
+            logVoiceVerbose(`capture ready (${durationSeconds.toFixed(2)}s): guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+            this.enqueueProcessing(entry, async () => {
+                await this.processSegment({ entry, wavPath, userId, durationSeconds });
+            });
+        }
+        finally {
+            entry.activeSpeakers.delete(userId);
+        }
+    }
+    async processSegment(params) {
+        const { entry, wavPath, userId, durationSeconds } = params;
+        logVoiceVerbose(`segment processing (${durationSeconds.toFixed(2)}s): guild ${entry.guildId} channel ${entry.channelId}`);
+        const transcript = await transcribeAudio({
+            cfg: this.params.cfg,
+            agentId: entry.route.agentId,
+            filePath: wavPath,
+        });
+        if (!transcript) {
+            logVoiceVerbose(`transcription empty: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+            return;
+        }
+        logVoiceVerbose(`transcription ok (${transcript.length} chars): guild ${entry.guildId} channel ${entry.channelId}`);
+        const speakerLabel = await this.resolveSpeakerLabel(entry.guildId, userId);
+        const prompt = speakerLabel ? `${speakerLabel}: ${transcript}` : transcript;
+        const result = await agentCommand({
+            message: prompt,
+            sessionKey: entry.route.sessionKey,
+            agentId: entry.route.agentId,
+            messageChannel: "discord",
+            deliver: false,
+        }, this.params.runtime);
+        const replyText = (result.payloads ?? [])
+            .map((payload) => payload.text)
+            .filter((text) => typeof text === "string" && text.trim())
+            .join("\n")
+            .trim();
+        if (!replyText) {
+            logVoiceVerbose(`reply empty: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+            return;
+        }
+        logVoiceVerbose(`reply ok (${replyText.length} chars): guild ${entry.guildId} channel ${entry.channelId}`);
+        const { cfg: ttsCfg, resolved: ttsConfig } = resolveVoiceTtsConfig({
+            cfg: this.params.cfg,
+            override: this.params.discordConfig.voice?.tts,
+        });
+        const directive = parseTtsDirectives(replyText, ttsConfig.modelOverrides);
+        const speakText = directive.overrides.ttsText ?? directive.cleanedText.trim();
+        if (!speakText) {
+            logVoiceVerbose(`tts skipped (empty): guild ${entry.guildId} channel ${entry.channelId} user ${userId}`);
+            return;
+        }
+        const ttsResult = await textToSpeech({
+            text: speakText,
+            cfg: ttsCfg,
+            channel: "discord",
+            overrides: directive.overrides,
+        });
+        if (!ttsResult.success || !ttsResult.audioPath) {
+            logger.warn(`discord voice: TTS failed: ${ttsResult.error ?? "unknown error"}`);
+            return;
+        }
+        const audioPath = ttsResult.audioPath;
+        logVoiceVerbose(`tts ok (${speakText.length} chars): guild ${entry.guildId} channel ${entry.channelId}`);
+        this.enqueuePlayback(entry, async () => {
+            logVoiceVerbose(`playback start: guild ${entry.guildId} channel ${entry.channelId} file ${path.basename(audioPath)}`);
+            const resource = createAudioResource(audioPath);
+            entry.player.play(resource);
+            await entersState(entry.player, AudioPlayerStatus.Playing, PLAYBACK_READY_TIMEOUT_MS).catch(() => undefined);
+            await entersState(entry.player, AudioPlayerStatus.Idle, SPEAKING_READY_TIMEOUT_MS).catch(() => undefined);
+            logVoiceVerbose(`playback done: guild ${entry.guildId} channel ${entry.channelId}`);
+        });
+    }
+    async resolveSpeakerLabel(guildId, userId) {
+        try {
+            const member = await this.params.client.fetchMember(guildId, userId);
+            return member.nickname ?? member.user?.globalName ?? member.user?.username ?? userId;
+        }
+        catch {
+            try {
+                const user = await this.params.client.fetchUser(userId);
+                return user.globalName ?? user.username ?? userId;
+            }
+            catch {
+                return userId;
+            }
+        }
+    }
+}
+export class DiscordVoiceReadyListener extends ReadyListener {
+    manager;
+    constructor(manager) {
+        super();
+        this.manager = manager;
+    }
+    async handle() {
+        await this.manager.autoJoin();
+    }
+}
+function isVoiceChannel(type) {
+    return type === ChannelType.GuildVoice || type === ChannelType.GuildStageVoice;
+}

package/dist/gateway/auth.js

@@ -1,36 +1,41 @@
 import { readTailscaleWhoisIdentity } from "../infra/tailscale.js";
 import { safeEqualSecret } from "../security/secret-equal.js";
 import { AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET, } from "./auth-rate-limit.js";
-import { isLoopbackAddress, isTrustedProxyAddress, resolveHostName, parseForwardedForClientIp, resolveGatewayClientIp, } from "./net.js";
+import { isLoopbackAddress, isTrustedProxyAddress, resolveHostName, resolveClientIp, } from "./net.js";
 function normalizeLogin(login) {
     return login.trim().toLowerCase();
 }
 function headerValue(value) {
     return Array.isArray(value) ? value[0] : value;
 }
+const TAILSCALE_TRUSTED_PROXIES = ["127.0.0.1", "::1"];
 function resolveTailscaleClientIp(req) {
     if (!req) {
         return undefined;
     }
-    const forwardedFor = headerValue(req.headers?.["x-forwarded-for"]);
-    return forwardedFor ? parseForwardedForClientIp(forwardedFor) : undefined;
+    return resolveClientIp({
+        remoteAddr: req.socket?.remoteAddress ?? "",
+        forwardedFor: headerValue(req.headers?.["x-forwarded-for"]),
+        trustedProxies: [...TAILSCALE_TRUSTED_PROXIES],
+    });
 }
-function resolveRequestClientIp(req, trustedProxies) {
+function resolveRequestClientIp(req, trustedProxies, allowRealIpFallback = false) {
     if (!req) {
         return undefined;
     }
-    return resolveGatewayClientIp({
+    return resolveClientIp({
         remoteAddr: req.socket?.remoteAddress ?? "",
         forwardedFor: headerValue(req.headers?.["x-forwarded-for"]),
         realIp: headerValue(req.headers?.["x-real-ip"]),
         trustedProxies,
+        allowRealIpFallback,
     });
 }
-export function isLocalDirectRequest(req, trustedProxies) {
+export function isLocalDirectRequest(req, trustedProxies, allowRealIpFallback = false) {
     if (!req) {
         return false;
     }
-    const clientIp = resolveRequestClientIp(req, trustedProxies) ?? "";
+    const clientIp = resolveRequestClientIp(req, trustedProxies, allowRealIpFallback) ?? "";
     if (!isLoopbackAddress(clientIp)) {
         return false;
     }
@@ -104,28 +109,60 @@ async function resolveVerifiedTailscaleUser(params) {
     };
 }
 export function resolveGatewayAuth(params) {
-    const authConfig = params.authConfig ?? {};
+    const baseAuthConfig = params.authConfig ?? {};
+    const authOverride = params.authOverride ?? undefined;
+    const authConfig = { ...baseAuthConfig };
+    if (authOverride) {
+        if (authOverride.mode !== undefined) {
+            authConfig.mode = authOverride.mode;
+        }
+        if (authOverride.token !== undefined) {
+            authConfig.token = authOverride.token;
+        }
+        if (authOverride.password !== undefined) {
+            authConfig.password = authOverride.password;
+        }
+        if (authOverride.allowTailscale !== undefined) {
+            authConfig.allowTailscale = authOverride.allowTailscale;
+        }
+        if (authOverride.rateLimit !== undefined) {
+            authConfig.rateLimit = authOverride.rateLimit;
+        }
+        if (authOverride.trustedProxy !== undefined) {
+            authConfig.trustedProxy = authOverride.trustedProxy;
+        }
+    }
     const env = params.env ?? process.env;
     const token = authConfig.token ?? env.POOLBOT_GATEWAY_TOKEN ?? undefined;
     const password = authConfig.password ?? env.POOLBOT_GATEWAY_PASSWORD ?? undefined;
     const trustedProxy = authConfig.trustedProxy;
     let mode;
-    if (authConfig.mode) {
+    let modeSource;
+    if (authOverride?.mode !== undefined) {
+        mode = authOverride.mode;
+        modeSource = "override";
+    }
+    else if (authConfig.mode) {
         mode = authConfig.mode;
+        modeSource = "config";
     }
     else if (password) {
         mode = "password";
+        modeSource = "password";
     }
     else if (token) {
         mode = "token";
+        modeSource = "token";
     }
     else {
-        mode = "none";
+        mode = "token";
+        modeSource = "default";
     }
     const allowTailscale = authConfig.allowTailscale ??
         (params.tailscaleMode === "serve" && mode !== "password" && mode !== "trusted-proxy");
     return {
         mode,
+        modeSource,
         token,
         password,
         allowTailscale,
@@ -182,10 +219,15 @@ function authorizeTrustedProxy(params) {
     }
     return { user };
 }
+function shouldAllowTailscaleHeaderAuth(authSurface) {
+    return authSurface === "ws-control-ui";
+}
 export async function authorizeGatewayConnect(params) {
     const { auth, connectAuth, req, trustedProxies } = params;
     const tailscaleWhois = params.tailscaleWhois ?? readTailscaleWhoisIdentity;
-    const localDirect = isLocalDirectRequest(req, trustedProxies);
+    const authSurface = params.authSurface ?? "http";
+    const allowTailscaleHeaderAuth = shouldAllowTailscaleHeaderAuth(authSurface);
+    const localDirect = isLocalDirectRequest(req, trustedProxies, params.allowRealIpFallback === true);
     if (auth.mode === "trusted-proxy") {
         if (!auth.trustedProxy) {
             return { ok: false, reason: "trusted_proxy_config_missing" };
@@ -203,8 +245,13 @@ export async function authorizeGatewayConnect(params) {
         }
         return { ok: false, reason: result.reason };
     }
+    if (auth.mode === "none") {
+        return { ok: true, method: "none" };
+    }
     const limiter = params.rateLimiter;
-    const ip = params.clientIp ?? resolveRequestClientIp(req, trustedProxies) ?? req?.socket?.remoteAddress;
+    const ip = params.clientIp ??
+        resolveRequestClientIp(req, trustedProxies, params.allowRealIpFallback === true) ??
+        req?.socket?.remoteAddress;
     const rateLimitScope = params.rateLimitScope ?? AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET;
     if (limiter) {
         const rlCheck = limiter.check(ip, rateLimitScope);
@@ -217,7 +264,7 @@ export async function authorizeGatewayConnect(params) {
             };
         }
     }
-    if (auth.allowTailscale && !localDirect) {
+    if (allowTailscaleHeaderAuth && auth.allowTailscale && !localDirect) {
         const tailscaleCheck = await resolveVerifiedTailscaleUser({
             req,
             tailscaleWhois,
@@ -265,3 +312,15 @@ export async function authorizeGatewayConnect(params) {
     limiter?.recordFailure(ip, rateLimitScope);
     return { ok: false, reason: "unauthorized" };
 }
+export async function authorizeHttpGatewayConnect(params) {
+    return authorizeGatewayConnect({
+        ...params,
+        authSurface: "http",
+    });
+}
+export async function authorizeWsControlUiGatewayConnect(params) {
+    return authorizeGatewayConnect({
+        ...params,
+        authSurface: "ws-control-ui",
+    });
+}