@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/gateway/role-policy.js

@@ -0,0 +1,17 @@
+import { isNodeRoleMethod } from "./method-scopes.js";
+export const GATEWAY_ROLES = ["operator", "node"];
+export function parseGatewayRole(roleRaw) {
+    if (roleRaw === "operator" || roleRaw === "node") {
+        return roleRaw;
+    }
+    return null;
+}
+export function roleCanSkipDeviceIdentity(role, sharedAuthOk) {
+    return role === "operator" && sharedAuthOk;
+}
+export function isRoleAuthorizedForMethod(role, method) {
+    if (isNodeRoleMethod(method)) {
+        return role === "node";
+    }
+    return role === "operator";
+}

package/dist/gateway/server/ws-connection/connect-policy.js

@@ -0,0 +1,37 @@
+import { roleCanSkipDeviceIdentity } from "../../role-policy.js";
+export function resolveControlUiAuthPolicy(params) {
+    const allowInsecureAuthConfigured = params.isControlUi && params.controlUiConfig?.allowInsecureAuth === true;
+    const dangerouslyDisableDeviceAuth = params.isControlUi && params.controlUiConfig?.dangerouslyDisableDeviceAuth === true;
+    return {
+        allowInsecureAuthConfigured,
+        dangerouslyDisableDeviceAuth,
+        // `allowInsecureAuth` must not bypass secure-context/device-auth requirements.
+        allowBypass: dangerouslyDisableDeviceAuth,
+        device: dangerouslyDisableDeviceAuth ? null : params.deviceRaw,
+    };
+}
+export function shouldSkipControlUiPairing(policy, sharedAuthOk) {
+    return policy.allowBypass && sharedAuthOk;
+}
+export function evaluateMissingDeviceIdentity(params) {
+    if (params.hasDeviceIdentity) {
+        return { kind: "allow" };
+    }
+    if (params.isControlUi && !params.controlUiAuthPolicy.allowBypass) {
+        // Allow localhost Control UI connections when allowInsecureAuth is configured.
+        // Localhost has no network interception risk, and browser SubtleCrypto
+        // (needed for device identity) is unavailable in insecure HTTP contexts.
+        // Remote connections are still rejected to preserve the MitM protection
+        // that the security fix (#20684) intended.
+        if (!params.controlUiAuthPolicy.allowInsecureAuthConfigured || !params.isLocalClient) {
+            return { kind: "reject-control-ui-insecure-auth" };
+        }
+    }
+    if (roleCanSkipDeviceIdentity(params.role, params.sharedAuthOk)) {
+        return { kind: "allow" };
+    }
+    if (!params.authOk && params.hasSharedAuth) {
+        return { kind: "reject-unauthorized" };
+    }
+    return { kind: "reject-device-required" };
+}

package/dist/gateway/server/ws-connection/message-handler.js

@@ -7,17 +7,20 @@ import { recordRemoteNodeInfo, refreshRemoteNodeBins } from "../../../infra/skil
 import { upsertPresence } from "../../../infra/system-presence.js";
 import { loadVoiceWakeConfig } from "../../../infra/voicewake.js";
 import { rawDataToString } from "../../../infra/ws.js";
+import { roleScopesAllow } from "../../../shared/operator-scope-compat.js";
 import { isGatewayCliClient, isWebchatClient } from "../../../utils/message-channel.js";
 import { resolveRuntimeServiceVersion } from "../../../version.js";
 import { AUTH_RATE_LIMIT_SCOPE_DEVICE_TOKEN, AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET, } from "../../auth-rate-limit.js";
-import { authorizeGatewayConnect, isLocalDirectRequest } from "../../auth.js";
+import { authorizeHttpGatewayConnect, authorizeWsControlUiGatewayConnect, isLocalDirectRequest, } from "../../auth.js";
+import { buildCanvasScopedHostUrl, CANVAS_CAPABILITY_TTL_MS, mintCanvasCapabilityToken, } from "../../canvas-capability.js";
 import { buildDeviceAuthPayload } from "../../device-auth.js";
-import { isLoopbackAddress, isTrustedProxyAddress, resolveGatewayClientIp } from "../../net.js";
+import { isLoopbackAddress, isTrustedProxyAddress, resolveClientIp } from "../../net.js";
 import { resolveHostName } from "../../net.js";
 import { resolveNodeCommandAllowlist } from "../../node-command-policy.js";
 import { checkBrowserOrigin } from "../../origin-check.js";
 import { GATEWAY_CLIENT_IDS } from "../../protocol/client-info.js";
 import { ErrorCodes, errorShape, formatValidationErrors, PROTOCOL_VERSION, validateConnectParams, validateRequestFrame, } from "../../protocol/index.js";
+import { parseGatewayRole } from "../../role-policy.js";
 import { MAX_BUFFERED_BYTES, MAX_PAYLOAD_BYTES, TICK_INTERVAL_MS } from "../../server-constants.js";
 import { handleGatewayRequest } from "../../server-methods.js";
 import { formatError } from "../../server-utils.js";
@@ -25,12 +28,20 @@ import { formatForLog, logWs } from "../../ws-log.js";
 import { truncateCloseReason } from "../close-reason.js";
 import { buildGatewaySnapshot, getHealthCache, getHealthVersion, incrementPresenceVersion, refreshGatewayHealthSnapshot, } from "../health-state.js";
 import { formatGatewayAuthFailureMessage } from "./auth-messages.js";
+import { evaluateMissingDeviceIdentity, resolveControlUiAuthPolicy, shouldSkipControlUiPairing, } from "./connect-policy.js";
 const DEVICE_SIGNATURE_SKEW_MS = 10 * 60 * 1000;
 export function attachGatewayWsMessageHandler(params) {
     const { socket, upgradeReq, connId, remoteAddr, forwardedFor, realIp, requestHost, requestOrigin, requestUserAgent, canvasHostUrl, connectNonce, resolvedAuth, rateLimiter, gatewayMethods, events, extraHandlers, buildRequestContext, send, close, isClosed, clearHandshakeTimer, getClient, setClient, setHandshakeState, setCloseCause, setLastFrameMeta, logGateway, logHealth, logWsControl, } = params;
     const configSnapshot = loadConfig();
     const trustedProxies = configSnapshot.gateway?.trustedProxies ?? [];
-    const clientIp = resolveGatewayClientIp({ remoteAddr, forwardedFor, realIp, trustedProxies });
+    const allowRealIpFallback = configSnapshot.gateway?.allowRealIpFallback === true;
+    const clientIp = resolveClientIp({
+        remoteAddr,
+        forwardedFor,
+        realIp,
+        trustedProxies,
+        allowRealIpFallback,
+    });
     // If proxy headers are present but the remote address isn't trusted, don't treat
     // the connection as local. This prevents auth bypass when running behind a reverse
     // proxy without proper configuration - the proxy's loopback connection would otherwise
@@ -42,7 +53,7 @@ export function attachGatewayWsMessageHandler(params) {
     const hostIsLocal = hostName === "localhost" || hostName === "127.0.0.1" || hostName === "::1";
     const hostIsTailscaleServe = hostName.endsWith(".ts.net");
     const hostIsLocalish = hostIsLocal || hostIsTailscaleServe;
-    const isLocalClient = isLocalDirectRequest(upgradeReq, trustedProxies);
+    const isLocalClient = isLocalDirectRequest(upgradeReq, trustedProxies, allowRealIpFallback);
     const reportedClientIp = isLocalClient || hasUntrustedProxyHeaders
         ? undefined
         : clientIp && !isLoopbackAddress(clientIp)
@@ -162,7 +173,7 @@ export function attachGatewayWsMessageHandler(params) {
                     return;
                 }
                 const roleRaw = connectParams.role ?? "operator";
-                const role = roleRaw === "operator" || roleRaw === "node" ? roleRaw : null;
+                const role = parseGatewayRole(roleRaw);
                 if (!role) {
                     markHandshakeFailure("invalid-role", {
                         role: roleRaw,
@@ -202,52 +213,64 @@ export function attachGatewayWsMessageHandler(params) {
                 const hasTokenAuth = Boolean(connectParams.auth?.token);
                 const hasPasswordAuth = Boolean(connectParams.auth?.password);
                 const hasSharedAuth = hasTokenAuth || hasPasswordAuth;
-                const allowInsecureControlUi = isControlUi && configSnapshot.gateway?.controlUi?.allowInsecureAuth === true;
-                const disableControlUiDeviceAuth = isControlUi && configSnapshot.gateway?.controlUi?.dangerouslyDisableDeviceAuth === true;
-                const allowControlUiBypass = allowInsecureControlUi || disableControlUiDeviceAuth;
-                const device = disableControlUiDeviceAuth ? null : deviceRaw;
-                const hasDeviceTokenCandidate = Boolean(connectParams.auth?.token && device);
-                let authResult = await authorizeGatewayConnect({
-                    auth: resolvedAuth,
-                    connectAuth: connectParams.auth,
-                    req: upgradeReq,
-                    trustedProxies,
-                    rateLimiter: hasDeviceTokenCandidate ? undefined : rateLimiter,
-                    clientIp,
-                    rateLimitScope: AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET,
+                const controlUiAuthPolicy = resolveControlUiAuthPolicy({
+                    isControlUi,
+                    controlUiConfig: configSnapshot.gateway?.controlUi,
+                    deviceRaw,
                 });
-                if (hasDeviceTokenCandidate &&
-                    authResult.ok &&
-                    rateLimiter &&
-                    (authResult.method === "token" || authResult.method === "password")) {
-                    const sharedRateCheck = rateLimiter.check(clientIp, AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET);
-                    if (!sharedRateCheck.allowed) {
-                        authResult = {
-                            ok: false,
-                            reason: "rate_limited",
-                            rateLimited: true,
-                            retryAfterMs: sharedRateCheck.retryAfterMs,
-                        };
-                    }
-                    else {
-                        rateLimiter.reset(clientIp, AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET);
-                    }
-                }
-                let authOk = authResult.ok;
-                let authMethod = authResult.method ?? (resolvedAuth.mode === "password" ? "password" : "token");
-                const sharedAuthResult = hasSharedAuth
-                    ? await authorizeGatewayConnect({
-                        auth: { ...resolvedAuth, allowTailscale: false },
+                const device = controlUiAuthPolicy.device;
+                const resolveAuthState = async () => {
+                    const hasDeviceTokenCandidate = Boolean(connectParams.auth?.token && device);
+                    let nextAuthResult = await authorizeWsControlUiGatewayConnect({
+                        auth: resolvedAuth,
                         connectAuth: connectParams.auth,
                         req: upgradeReq,
                         trustedProxies,
-                        // Shared-auth probe only; rate-limit side effects are handled in
-                        // the primary auth flow (or deferred for device-token candidates).
+                        allowRealIpFallback,
+                        rateLimiter: hasDeviceTokenCandidate ? undefined : rateLimiter,
+                        clientIp,
                         rateLimitScope: AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET,
-                    })
-                    : null;
-                const sharedAuthOk = sharedAuthResult?.ok === true &&
-                    (sharedAuthResult.method === "token" || sharedAuthResult.method === "password");
+                    });
+                    if (hasDeviceTokenCandidate &&
+                        nextAuthResult.ok &&
+                        rateLimiter &&
+                        (nextAuthResult.method === "token" || nextAuthResult.method === "password")) {
+                        const sharedRateCheck = rateLimiter.check(clientIp, AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET);
+                        if (!sharedRateCheck.allowed) {
+                            nextAuthResult = {
+                                ok: false,
+                                reason: "rate_limited",
+                                rateLimited: true,
+                                retryAfterMs: sharedRateCheck.retryAfterMs,
+                            };
+                        }
+                        else {
+                            rateLimiter.reset(clientIp, AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET);
+                        }
+                    }
+                    const nextAuthMethod = nextAuthResult.method ?? (resolvedAuth.mode === "password" ? "password" : "token");
+                    const sharedAuthResult = hasSharedAuth
+                        ? await authorizeHttpGatewayConnect({
+                            auth: { ...resolvedAuth, allowTailscale: false },
+                            connectAuth: connectParams.auth,
+                            req: upgradeReq,
+                            trustedProxies,
+                            allowRealIpFallback,
+                            // Shared-auth probe only; rate-limit side effects are handled in
+                            // the primary auth flow (or deferred for device-token candidates).
+                            rateLimitScope: AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET,
+                        })
+                        : null;
+                    const nextSharedAuthOk = sharedAuthResult?.ok === true &&
+                        (sharedAuthResult.method === "token" || sharedAuthResult.method === "password");
+                    return {
+                        authResult: nextAuthResult,
+                        authOk: nextAuthResult.ok,
+                        authMethod: nextAuthMethod,
+                        sharedAuthOk: nextSharedAuthOk,
+                    };
+                };
+                let { authResult, authOk, authMethod, sharedAuthOk } = await resolveAuthState();
                 const rejectUnauthorized = (failedAuth) => {
                     markHandshakeFailure("unauthorized", {
                         authMode: resolvedAuth.mode,
@@ -274,37 +297,55 @@ export function attachGatewayWsMessageHandler(params) {
                     sendHandshakeErrorResponse(ErrorCodes.INVALID_REQUEST, authMessage);
                     close(1008, truncateCloseReason(authMessage));
                 };
-                if (!device) {
-                    if (scopes.length > 0 && !allowControlUiBypass) {
+                const clearUnboundScopes = () => {
+                    if (scopes.length > 0 && !controlUiAuthPolicy.allowBypass) {
                         scopes = [];
                         connectParams.scopes = scopes;
                     }
-                    const canSkipDevice = sharedAuthOk;
-                    if (isControlUi && !allowControlUiBypass) {
-                        const errorMessage = "control ui requires HTTPS or localhost (secure context)";
-                        markHandshakeFailure("control-ui-insecure-auth");
+                };
+                const handleMissingDeviceIdentity = () => {
+                    if (!device) {
+                        clearUnboundScopes();
+                    }
+                    const decision = evaluateMissingDeviceIdentity({
+                        hasDeviceIdentity: Boolean(device),
+                        role,
+                        isControlUi,
+                        controlUiAuthPolicy,
+                        sharedAuthOk,
+                        authOk,
+                        hasSharedAuth,
+                        isLocalClient,
+                    });
+                    if (decision.kind === "allow") {
+                        return true;
+                    }
+                    if (decision.kind === "reject-control-ui-insecure-auth") {
+                        const errorMessage = "control ui requires device identity (use HTTPS or localhost secure context)";
+                        markHandshakeFailure("control-ui-insecure-auth", {
+                            insecureAuthConfigured: controlUiAuthPolicy.allowInsecureAuthConfigured,
+                        });
                         sendHandshakeErrorResponse(ErrorCodes.INVALID_REQUEST, errorMessage);
                         close(1008, errorMessage);
-                        return;
+                        return false;
                     }
-                    // Allow shared-secret authenticated connections (e.g., control-ui) to skip device identity
-                    if (!canSkipDevice) {
-                        if (!authOk && hasSharedAuth) {
-                            rejectUnauthorized(authResult);
-                            return;
-                        }
-                        markHandshakeFailure("device-required");
-                        sendHandshakeErrorResponse(ErrorCodes.NOT_PAIRED, "device identity required");
-                        close(1008, "device identity required");
-                        return;
+                    if (decision.kind === "reject-unauthorized") {
+                        rejectUnauthorized(authResult);
+                        return false;
                     }
+                    markHandshakeFailure("device-required");
+                    sendHandshakeErrorResponse(ErrorCodes.NOT_PAIRED, "device identity required");
+                    close(1008, "device identity required");
+                    return false;
+                };
+                if (!handleMissingDeviceIdentity()) {
+                    return;
                 }
                 if (device) {
-                    const derivedId = deriveDeviceIdFromPublicKey(device.publicKey);
-                    if (!derivedId || derivedId !== device.id) {
+                    const rejectDeviceAuthInvalid = (reason, message) => {
                         setHandshakeState("failed");
                         setCloseCause("device-auth-invalid", {
-                            reason: "device-id-mismatch",
+                            reason,
                             client: connectParams.client.id,
                             deviceId: device.id,
                         });
@@ -312,61 +353,29 @@ export function attachGatewayWsMessageHandler(params) {
                             type: "res",
                             id: frame.id,
                             ok: false,
-                            error: errorShape(ErrorCodes.INVALID_REQUEST, "device identity mismatch"),
+                            error: errorShape(ErrorCodes.INVALID_REQUEST, message),
                         });
-                        close(1008, "device identity mismatch");
+                        close(1008, message);
+                    };
+                    const derivedId = deriveDeviceIdFromPublicKey(device.publicKey);
+                    if (!derivedId || derivedId !== device.id) {
+                        rejectDeviceAuthInvalid("device-id-mismatch", "device identity mismatch");
                         return;
                     }
                     const signedAt = device.signedAt;
                     if (typeof signedAt !== "number" ||
                         Math.abs(Date.now() - signedAt) > DEVICE_SIGNATURE_SKEW_MS) {
-                        setHandshakeState("failed");
-                        setCloseCause("device-auth-invalid", {
-                            reason: "device-signature-stale",
-                            client: connectParams.client.id,
-                            deviceId: device.id,
-                        });
-                        send({
-                            type: "res",
-                            id: frame.id,
-                            ok: false,
-                            error: errorShape(ErrorCodes.INVALID_REQUEST, "device signature expired"),
-                        });
-                        close(1008, "device signature expired");
+                        rejectDeviceAuthInvalid("device-signature-stale", "device signature expired");
                         return;
                     }
                     const nonceRequired = !isLocalClient;
                     const providedNonce = typeof device.nonce === "string" ? device.nonce.trim() : "";
                     if (nonceRequired && !providedNonce) {
-                        setHandshakeState("failed");
-                        setCloseCause("device-auth-invalid", {
-                            reason: "device-nonce-missing",
-                            client: connectParams.client.id,
-                            deviceId: device.id,
-                        });
-                        send({
-                            type: "res",
-                            id: frame.id,
-                            ok: false,
-                            error: errorShape(ErrorCodes.INVALID_REQUEST, "device nonce required"),
-                        });
-                        close(1008, "device nonce required");
+                        rejectDeviceAuthInvalid("device-nonce-missing", "device nonce required");
                         return;
                     }
                     if (providedNonce && providedNonce !== connectNonce) {
-                        setHandshakeState("failed");
-                        setCloseCause("device-auth-invalid", {
-                            reason: "device-nonce-mismatch",
-                            client: connectParams.client.id,
-                            deviceId: device.id,
-                        });
-                        send({
-                            type: "res",
-                            id: frame.id,
-                            ok: false,
-                            error: errorShape(ErrorCodes.INVALID_REQUEST, "device nonce mismatch"),
-                        });
-                        close(1008, "device nonce mismatch");
+                        rejectDeviceAuthInvalid("device-nonce-mismatch", "device nonce mismatch");
                         return;
                     }
                     const payload = buildDeviceAuthPayload({
@@ -380,21 +389,7 @@ export function attachGatewayWsMessageHandler(params) {
                         nonce: providedNonce || undefined,
                         version: providedNonce ? "v2" : "v1",
                     });
-                    const rejectDeviceSignatureInvalid = () => {
-                        setHandshakeState("failed");
-                        setCloseCause("device-auth-invalid", {
-                            reason: "device-signature",
-                            client: connectParams.client.id,
-                            deviceId: device.id,
-                        });
-                        send({
-                            type: "res",
-                            id: frame.id,
-                            ok: false,
-                            error: errorShape(ErrorCodes.INVALID_REQUEST, "device signature invalid"),
-                        });
-                        close(1008, "device signature invalid");
-                    };
+                    const rejectDeviceSignatureInvalid = () => rejectDeviceAuthInvalid("device-signature", "device signature invalid");
                     const signatureOk = verifyDeviceSignature(device.publicKey, payload, device.signature);
                     const allowLegacy = !nonceRequired && !providedNonce;
                     if (!signatureOk && allowLegacy) {
@@ -422,19 +417,7 @@ export function attachGatewayWsMessageHandler(params) {
                     }
                     devicePublicKey = normalizeDevicePublicKeyBase64Url(device.publicKey);
                     if (!devicePublicKey) {
-                        setHandshakeState("failed");
-                        setCloseCause("device-auth-invalid", {
-                            reason: "device-public-key",
-                            client: connectParams.client.id,
-                            deviceId: device.id,
-                        });
-                        send({
-                            type: "res",
-                            id: frame.id,
-                            ok: false,
-                            error: errorShape(ErrorCodes.INVALID_REQUEST, "device public key invalid"),
-                        });
-                        close(1008, "device public key invalid");
+                        rejectDeviceAuthInvalid("device-public-key", "device public key invalid");
                         return;
                     }
                 }
@@ -472,9 +455,28 @@ export function attachGatewayWsMessageHandler(params) {
                     rejectUnauthorized(authResult);
                     return;
                 }
-                const skipPairing = allowControlUiBypass && sharedAuthOk;
+                const skipPairing = shouldSkipControlUiPairing(controlUiAuthPolicy, sharedAuthOk);
                 if (device && devicePublicKey && !skipPairing) {
-                    const requirePairing = async (reason, _paired) => {
+                    const formatAuditList = (items) => {
+                        if (!items || items.length === 0) {
+                            return "<none>";
+                        }
+                        const out = new Set();
+                        for (const item of items) {
+                            const trimmed = item.trim();
+                            if (trimmed) {
+                                out.add(trimmed);
+                            }
+                        }
+                        if (out.size === 0) {
+                            return "<none>";
+                        }
+                        return [...out].toSorted().join(",");
+                    };
+                    const logUpgradeAudit = (reason, currentRoles, currentScopes) => {
+                        logGateway.warn(`security audit: device access upgrade requested reason=${reason} device=${device.id} ip=${reportedClientIp ?? "unknown-ip"} auth=${authMethod} roleFrom=${formatAuditList(currentRoles)} roleTo=${role} scopesFrom=${formatAuditList(currentScopes)} scopesTo=${formatAuditList(scopes)} client=${connectParams.client.id} conn=${connId}`);
+                    };
+                    const requirePairing = async (reason) => {
                         const pairing = await requestDevicePairing({
                             deviceId: device.id,
                             publicKey: devicePublicKey,
@@ -485,7 +487,7 @@ export function attachGatewayWsMessageHandler(params) {
                             role,
                             scopes,
                             remoteIp: reportedClientIp,
-                            silent: isLocalClient,
+                            silent: isLocalClient && reason === "not-paired",
                         });
                         const context = buildRequestContext();
                         if (pairing.request.silent === true) {
@@ -532,32 +534,48 @@ export function attachGatewayWsMessageHandler(params) {
                         }
                     }
                     else {
-                        const allowedRoles = new Set(Array.isArray(paired.roles) ? paired.roles : paired.role ? [paired.role] : []);
+                        const pairedRoles = Array.isArray(paired.roles)
+                            ? paired.roles
+                            : paired.role
+                                ? [paired.role]
+                                : [];
+                        const pairedScopes = Array.isArray(paired.scopes)
+                            ? paired.scopes
+                            : Array.isArray(paired.approvedScopes)
+                                ? paired.approvedScopes
+                                : [];
+                        const allowedRoles = new Set(pairedRoles);
                         if (allowedRoles.size === 0) {
-                            const ok = await requirePairing("role-upgrade", paired);
+                            logUpgradeAudit("role-upgrade", pairedRoles, pairedScopes);
+                            const ok = await requirePairing("role-upgrade");
                             if (!ok) {
                                 return;
                             }
                         }
                         else if (!allowedRoles.has(role)) {
-                            const ok = await requirePairing("role-upgrade", paired);
+                            logUpgradeAudit("role-upgrade", pairedRoles, pairedScopes);
+                            const ok = await requirePairing("role-upgrade");
                             if (!ok) {
                                 return;
                             }
                         }
-                        const pairedScopes = Array.isArray(paired.scopes) ? paired.scopes : [];
                         if (scopes.length > 0) {
                             if (pairedScopes.length === 0) {
-                                const ok = await requirePairing("scope-upgrade", paired);
+                                logUpgradeAudit("scope-upgrade", pairedRoles, pairedScopes);
+                                const ok = await requirePairing("scope-upgrade");
                                 if (!ok) {
                                     return;
                                 }
                             }
                             else {
-                                const allowedScopes = new Set(pairedScopes);
-                                const missingScope = scopes.find((scope) => !allowedScopes.has(scope));
-                                if (missingScope) {
-                                    const ok = await requirePairing("scope-upgrade", paired);
+                                const scopesAllowed = roleScopesAllow({
+                                    role,
+                                    requestedScopes: scopes,
+                                    allowedScopes: pairedScopes,
+                                });
+                                if (!scopesAllowed) {
+                                    logUpgradeAudit("scope-upgrade", pairedRoles, pairedScopes);
+                                    const ok = await requirePairing("scope-upgrade");
                                     if (!ok) {
                                         return;
                                     }
@@ -630,6 +648,13 @@ export function attachGatewayWsMessageHandler(params) {
                     snapshot.health = cachedHealth;
                     snapshot.stateVersion.health = getHealthVersion();
                 }
+                const canvasCapability = role === "node" && canvasHostUrl ? mintCanvasCapabilityToken() : undefined;
+                const canvasCapabilityExpiresAtMs = canvasCapability
+                    ? Date.now() + CANVAS_CAPABILITY_TTL_MS
+                    : undefined;
+                const scopedCanvasHostUrl = canvasHostUrl && canvasCapability
+                    ? (buildCanvasScopedHostUrl(canvasHostUrl, canvasCapability) ?? canvasHostUrl)
+                    : canvasHostUrl;
                 const helloOk = {
                     type: "hello-ok",
                     protocol: PROTOCOL_VERSION,
@@ -641,7 +666,7 @@ export function attachGatewayWsMessageHandler(params) {
                     },
                     features: { methods: gatewayMethods, events },
                     snapshot,
-                    canvasHostUrl,
+                    canvasHostUrl: scopedCanvasHostUrl,
                     auth: deviceToken
                         ? {
                             deviceToken: deviceToken.token,
@@ -663,6 +688,8 @@ export function attachGatewayWsMessageHandler(params) {
                     connId,
                     presenceKey,
                     clientIp: reportedClientIp,
+                    canvasCapability,
+                    canvasCapabilityExpiresAtMs,
                 };
                 setClient(nextClient);
                 setHandshakeState("connected");