@ateam-ai/mcp 0.4.90 → 0.4.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.4.90",
+  "version": "0.4.92",
   "mcpName": "io.github.ariekogan/ateam-mcp",
   "description": "A-Team MCP Server — build, validate, and deploy multi-agent solutions from any AI environment",
   "type": "module",
@@ -13,7 +13,7 @@
     "start:http": "node src/index.js --http",
     "dev": "node --watch src/index.js",
     "dev:http": "node --watch src/index.js --http",
-    "test": "node test/session-isolation.test.mjs && node test/widget-protocol.test.mjs && node test/actor-binding.test.mjs && node test/spec-topics.test.mjs && node test/example-types.test.mjs && node --test test/deploy-status-truth.test.mjs && node --test test/connector-source-provenance.test.mjs"
+    "test": "node test/session-isolation.test.mjs && node test/widget-protocol.test.mjs && node test/actor-binding.test.mjs && node test/spec-topics.test.mjs && node test/example-types.test.mjs && node --test test/deploy-status-truth.test.mjs && node --test test/connector-source-provenance.test.mjs && node --test test/bootstrap-base-url.test.mjs && node --test test/key-environment.test.mjs"
   },
   "keywords": [
     "mcp",

package/src/api.js

@@ -39,18 +39,135 @@ const authOverrides = new Map();  // bearerToken → { tenant, apiKey, updatedAt
 const sessionBearers = new Map(); // sessionId → bearerToken
 
 /**
- * Parse a tenant-embedded API key.
- * Format: adas_<tenant>_<32hex>
- * Legacy: adas_<32hex> (no tenant embedded)
- * @returns {{ tenant: string|null, isValid: boolean }}
+ * THE ENVIRONMENTS A KEY MAY NAME. A CLOSED SET, deliberately.
+ *
+ * If this were an open pattern like [a-z]+, a typo — `adas_prd_…` — would
+ * become a NEW VALID ENVIRONMENT rather than an error, and the caller would be
+ * routed somewhere that does not exist instead of being told they mistyped.
+ * That is the same silent-wrong class as an environment fallback. Add an
+ * environment HERE, in one place, or it does not exist.
+ */
+export const KEY_ENVIRONMENTS = Object.freeze({
+  prod: "https://api.ateam-ai.com",
+  dev: "https://dev-api.ateam-ai.com",
+});
+
+const TENANT_RE = "[a-z0-9][a-z0-9-]{0,28}[a-z0-9]";
+const ENV_KEY_RE = new RegExp(`^adas_(${Object.keys(KEY_ENVIRONMENTS).join("|")})_(${TENANT_RE})_([0-9a-f]{32})$`);
+const PLAIN_KEY_RE = new RegExp(`^adas_(${TENANT_RE})_([0-9a-f]{32})$`);
+
+/**
+ * THE SEALED FORM — `adas_<env>_<blob>`, where the tenant is INSIDE the blob.
+ *
+ * base64url of [version:1][nonce:8][AES-256-GCM(tenant)][tag:8][secret:16].
+ * The trailing 16 bytes — the actual secret — are in the clear; the sealing key
+ * protects ROUTING ONLY. So the blob is not "the encrypted key", and losing the
+ * sealing secret is an availability problem, not a credential breach.
+ *
+ * THIS FILE MUST NEVER DECODE IT, and the reason is specific to this package:
+ * `@ateam-ai/mcp` installs from npm onto developer laptops. Any decoder here
+ * would mean the sealing secret shipping with it. We learn the tenant by asking
+ * — GET /auth/whoami — never by parsing.
+ *
+ * Length bounds come from that byte layout: 1-char tenant = 34 bytes = 46
+ * base64url chars; 30-char tenant = 63 bytes = 84.
+ */
+const SEALED_KEY_RE = new RegExp(`^adas_(${Object.keys(KEY_ENVIRONMENTS).join("|")})_([A-Za-z0-9_-]{46,88})$`);
+
+/**
+ * Parse an API key.
+ * Sealed: adas_<env>_<blob>            (tenant NOT in the string — ask whoami)
+ * Format: adas_<env>_<tenant>_<32hex>  env ∈ prod|dev
+ * Older:  adas_<tenant>_<32hex>        (no environment named)
+ * Legacy: adas_<32hex>                 (no tenant either)
+ *
+ * ORDER IS LOAD-BEARING, and it is the order Core resolves in. base64url
+ * includes `-` and `_`, so a long-tenant key with a malformed secret has the
+ * SHAPE of a sealed blob. Trying the strict forms first means every well-formed
+ * key is claimed by the form it belongs to, and only genuine leftovers reach the
+ * blob pattern — where they parse as "sealed", fail to decrypt at Core, and
+ * authenticate as NOBODY. That residue is acceptable only because nothing here
+ * makes an authorisation decision. Reverse the order and a typo masquerades as
+ * a sealed key.
+ *
+ * `tenant: null` with `sealed: true` is the CORRECT answer, not a failure.
+ *
+ * `env: null` means the key does not SAY which environment it belongs to — not
+ * that it is production. Nothing here defaults it; a caller that needs to know
+ * must treat null as unknown.
+ *
+ * @returns {{ env: string|null, tenant: string|null, sealed: boolean, isValid: boolean }}
  */
 export function parseApiKey(key) {
-  if (!key || typeof key !== 'string') return { tenant: null, isValid: false };
-  const match = key.match(/^adas_([a-z0-9][a-z0-9-]{0,28}[a-z0-9])_([0-9a-f]{32})$/);
-  if (match) return { tenant: match[1], isValid: true };
+  const no = { env: null, tenant: null, sealed: false, isValid: false };
+  if (!key || typeof key !== 'string') return no;
+  const withEnv = key.match(ENV_KEY_RE);
+  if (withEnv) return { env: withEnv[1], tenant: withEnv[2], sealed: false, isValid: true };
+  const match = key.match(PLAIN_KEY_RE);
+  if (match) return { env: null, tenant: match[1], sealed: false, isValid: true };
   const legacy = key.match(/^adas_([0-9a-f]{32})$/);
-  if (legacy) return { tenant: null, isValid: true };
-  return { tenant: null, isValid: false };
+  if (legacy) return { env: null, tenant: null, sealed: false, isValid: true };
+  const sealed = key.match(SEALED_KEY_RE);
+  if (sealed) return { env: sealed[1], tenant: null, sealed: true, isValid: true };
+  return no;
+}
+
+/**
+ * ASK WHO THIS KEY IS. The replacement for splitting the string.
+ *
+ * Deliberately a bare fetch rather than request(): it runs BEFORE the session
+ * has credentials, which is the whole point — request() builds its headers from
+ * the session we are trying to populate.
+ *
+ * Returns { tenant, env } or throws. It does NOT fall back to anything. A key
+ * whose tenant cannot be established is a key we refuse to act for: guessing
+ * here would put a caller on someone else's data, which is the single failure
+ * this system must never have.
+ *
+ * `/auth/whoami` is served by the skill-validator (api.ateam-ai.com and
+ * dev-api.ateam-ai.com are BOTH the validator, not Core), which relays the
+ * tenant Core gave it when it verified the key. Same answer, one hop.
+ */
+export async function whoami(apiKey, baseUrl, { timeoutMs = 10_000 } = {}) {
+  if (!apiKey) throw new Error("whoami: no api key");
+  if (!baseUrl) throw new Error("whoami: no base url");
+  const res = await fetch(`${String(baseUrl).replace(/\/+$/, "")}/auth/whoami`, {
+    headers: { "X-API-KEY": apiKey },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text().catch(() => "");
+  if (!res.ok) {
+    throw new Error(`whoami failed at ${baseUrl} (HTTP ${res.status}): ${text.slice(0, 300)}`);
+  }
+  let json;
+  try { json = JSON.parse(text); } catch { throw new Error(`whoami returned non-JSON from ${baseUrl}: ${text.slice(0, 200)}`); }
+  if (!json?.ok || !json?.tenant) {
+    throw new Error(`whoami did not name a tenant at ${baseUrl}: ${text.slice(0, 300)}`);
+  }
+  return { tenant: json.tenant, env: json.env ?? null };
+}
+
+/** The API base a key's environment names, or null when it names none. */
+export function baseUrlForKeyEnv(key) {
+  const { env } = parseApiKey(key);
+  return env ? KEY_ENVIRONMENTS[env] : null;
+}
+
+/**
+ * Which known environment does this URL belong to? null = not a known host.
+ *
+ * Used to REFUSE a `url` that contradicts the key. Deliberately only recognises
+ * the known hosts: an unrecognised url (localhost, a staging box) is still
+ * allowed through, because the override exists for those — it just must not be
+ * a way to cross prod/dev by accident.
+ */
+export function envForBaseUrl(url) {
+  if (!url) return null;
+  const norm = String(url).replace(/\/+$/, "");
+  for (const [env, base] of Object.entries(KEY_ENVIRONMENTS)) {
+    if (norm === base) return env;
+  }
+  return null;
 }
 
 /**
@@ -65,20 +182,42 @@ export function setSessionCredentials(sessionId, { tenant, apiKey, apiUrl, expli
     const parsed = parseApiKey(apiKey);
     if (parsed.tenant) resolvedTenant = parsed.tenant;
   }
+  // A SEALED key legitimately carries no tenant, so "unresolved" here means two
+  // very different things and they must not share an outcome:
+  //
+  //   sealed  → the tenant is not IN the string and never will be. Null is the
+  //             honest answer until whoami is asked. Requests still work: Core
+  //             resolves the tenant from the key itself, and headers() simply
+  //             omits X-ADAS-TENANT rather than sending a guess.
+  //   not sealed → the key is malformed. Still a hard failure.
+  //
+  // The distinction is the whole discipline: we never INVENT a tenant, but
+  // "not stated yet" is not the same as "wrong", and conflating them would
+  // refuse every sealed key at the door.
+  const sealedKey = apiKey ? parseApiKey(apiKey).sealed : false;
   // Fail loudly — silent fallback to "main" previously let malformed API keys
   // or missing tenant args silently pivot all operations onto the wrong tenant.
   // Matches the pattern we killed in ADAS connectors (memory-mcp, docs-index-mcp,
   // nutrition-mcp) — `|| "default"` was the #1 source of cross-tenant leaks.
-  if (!resolvedTenant) {
+  if (!resolvedTenant && !sealedKey) {
     throw new Error(
       `setSessionCredentials: tenant could not be resolved for session ${sessionId} ` +
-      `(tenant arg ${tenant ? "present" : "missing"}, apiKey ${apiKey ? "present but malformed (expected adas_<tenant>_<hex>)" : "absent"}). ` +
+      `(tenant arg ${tenant ? "present" : "missing"}, apiKey ${apiKey ? "present but malformed (expected adas_<env>_<key>)" : "absent"}). ` +
       `Refusing to fall back to a default tenant.`
     );
   }
+  if (!resolvedTenant) {
+    console.warn(
+      `[Auth] Session ${sessionId} holds a sealed key whose tenant is not resolved yet. ` +
+      `Calls will still authenticate (the tenant is inside the key and Core resolves it); ` +
+      `anything that needs the tenant BY NAME must call whoami rather than assume one.`
+    );
+  }
   const existing = sessions.get(sessionId);
   sessions.set(sessionId, {
-    tenant: resolvedTenant,
+    // Never `undefined` — a missing tenant is an explicit null, so every reader
+    // sees "not resolved" rather than an absent property it might paper over.
+    tenant: resolvedTenant || null,
     apiKey,
     apiUrl: apiUrl || existing?.apiUrl || null,
     authExplicit: explicit || existing?.authExplicit || false,
@@ -88,7 +227,7 @@ export function setSessionCredentials(sessionId, { tenant, apiKey, apiUrl, expli
   });
   const urlNote = apiUrl ? `, url: ${apiUrl}` : "";
   const masterNote = masterKey ? ", MASTER MODE" : "";
-  console.log(`[Auth] Credentials set for session ${sessionId} (tenant: ${resolvedTenant}${explicit ? ", explicit" : ""}${urlNote}${masterNote})`);
+  console.log(`[Auth] Credentials set for session ${sessionId} (tenant: ${resolvedTenant || "unresolved — sealed key"}${explicit ? ", explicit" : ""}${urlNote}${masterNote})`);
 }
 
 /**
@@ -135,10 +274,15 @@ export function getCredentials(sessionId) {
   // If apiKey is present but tenant couldn't be derived, the key is malformed.
   // Previously fell back to "main" — this silently routed credentials to the
   // wrong tenant. Now we fail loudly.
-  if (apiKey && !tenant) {
+  //
+  // UNLESS THE KEY IS SEALED, where no tenant in the string is the design and
+  // not a defect. Same split as setSessionCredentials: "not stated" is not
+  // "wrong". Requests still authenticate, because the tenant is inside the key
+  // and Core reads it; headers() omits X-ADAS-TENANT rather than guessing one.
+  if (apiKey && !tenant && !parseApiKey(apiKey).sealed) {
     throw new Error(
       `getCredentials: apiKey is present (env ADAS_API_KEY) but tenant could not be resolved ` +
-      `(missing ADAS_TENANT env and apiKey is malformed — expected format adas_<tenant>_<hex>). ` +
+      `(missing ADAS_TENANT env and apiKey is malformed — expected format adas_<env>_<key>). ` +
       `Refusing to fall back to a default tenant.`
     );
   }

package/src/http.js

@@ -24,7 +24,7 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import express from "express";
 import { createServer } from "./server.js";
 import {
-  clearSession, setSessionCredentials, parseApiKey,
+  clearSession, setSessionCredentials, parseApiKey, whoami, baseUrlForKeyEnv, getCredentials,
   startSessionSweeper, getSessionStats, sweepStaleSessions,
   bindSessionBearer, getAuthOverride, getSessionBearer, bearerOwnershipOk,
 } from "./api.js";
@@ -302,7 +302,7 @@ export function startHttpServer(port = 3100) {
       if (sessionId && transports[sessionId]) {
         // Reuse existing session — seed credentials if Bearer token present
         transport = transports[sessionId];
-        seedCredentials(req, sessionId);
+        await seedCredentials(req, sessionId);
       } else if (isInitializeRequest(req.body) || (sessionId && !transports[sessionId])) {
         // New session, OR stale session with any request type (server restart recovery).
         // Many MCP clients (Claude mobile, Claude Code) cache the session ID and fail to
@@ -326,7 +326,7 @@ export function startHttpServer(port = 3100) {
         const newSessionId = sessionId || randomUUID();
 
         // Seed credentials from OAuth Bearer token before server starts
-        seedCredentials(req, newSessionId);
+        await seedCredentials(req, newSessionId);
 
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => newSessionId,
@@ -478,7 +478,7 @@ export function startHttpServer(port = 3100) {
  * If the user previously called ateam_auth to override (e.g., switch tenants),
  * that override is stored per bearer and takes priority here.
  */
-function seedCredentials(req, sessionId) {
+async function seedCredentials(req, sessionId) {
   const token = req.auth?.token;
   if (!token) return;
 
@@ -501,7 +501,35 @@ function seedCredentials(req, sessionId) {
   // redundant ateam_auth call. (The env-var guard in tools.js is unaffected —
   // env creds never flow through here; this path only fires for a real Bearer.)
   const parsed = parseApiKey(token);
-  if (parsed.isValid) {
-    setSessionCredentials(sessionId, { tenant: parsed.tenant, apiKey: token, explicit: true });
+  if (!parsed.isValid) return;
+
+  // The key's own environment decides the base. Without this a dev bearer
+  // silently used the process default, which is PRODUCTION — the same
+  // never-guess-the-environment rule ateam_auth already follows, applied to the
+  // path that had been missed.
+  const apiUrl = baseUrlForKeyEnv(token) || undefined;
+
+  if (parsed.tenant) {
+    setSessionCredentials(sessionId, { tenant: parsed.tenant, apiKey: token, apiUrl, explicit: true });
+    return;
+  }
+
+  // A SEALED key does not spell out its tenant, so it has to be asked for —
+  // ONCE. This runs on every request for an existing session, so without the
+  // guard below it would be a network round trip per MCP call.
+  const current = (() => { try { return getCredentials(sessionId); } catch { return null; } })();
+  if (current?.tenant && current.apiKey === token) return;
+
+  try {
+    const me = await whoami(token, apiUrl);
+    setSessionCredentials(sessionId, { tenant: me.tenant, apiKey: token, apiUrl, explicit: true });
+  } catch (err) {
+    // Credentials are still set: the tenant lives INSIDE the key and Core reads
+    // it, so calls authenticate correctly with no X-ADAS-TENANT header at all.
+    // What we must not do is fill the gap with a guess — an unresolved tenant
+    // is recorded as null and retried on the next request. Anything that needs
+    // the name will say it does not have it.
+    console.warn(`[Auth] whoami failed for session ${sessionId} at ${apiUrl}: ${err.message} — proceeding with the tenant unresolved, never assumed.`);
+    setSessionCredentials(sessionId, { tenant: null, apiKey: token, apiUrl, explicit: true });
   }
 }

package/src/tools.js

@@ -11,7 +11,7 @@
 import {
   get, post, patch, del,
   setSessionCredentials, isAuthenticated, isExplicitlyAuthenticated,
-  getCredentials, parseApiKey, touchSession, getSessionContext,
+  getCredentials, parseApiKey, whoami, baseUrlForKeyEnv, envForBaseUrl, touchSession, getSessionContext,
   setAuthOverride, switchTenant, isMasterMode, listTenants, getWhere, getBaseUrl,
 } from "./api.js";
 
@@ -3176,11 +3176,25 @@ function chainTreeOf(resp) {
 // is the difference between proving behaviour and matching a string that a
 // rename would quietly satisfy.
 export const handlers = {
-  ateam_bootstrap: async () => ({
+  // (_args, sid) — the SESSION ID IS LOAD-BEARING HERE.
+  //
+  // getBaseUrl(sessionId) resolves per-session first (api.js:326-339): a caller
+  // that passed `url` to ateam_auth is talking to THAT api, and the session
+  // holds it. Bootstrap called it with NO argument, so it skipped the
+  // per-session and bearer branches every time and reported the process
+  // DEFAULT — https://api.ateam-ai.com.
+  //
+  // The result was a tool that says PROD while the session is authenticated to
+  // DEV, in the one field whose whole job is to tell you which environment you
+  // are on. Observed live: a session working entirely against
+  // dev-api.ateam-ai.com was told base_url: https://api.ateam-ai.com, and had
+  // to learn from deploy errors which environment it was actually on. The
+  // dangerous direction is the mirror image — believing you are on dev.
+  ateam_bootstrap: async (_args, sid) => ({
     runtime: {
       ateam_mcp_version: MCP_VERSION,
-      base_url: getBaseUrl(),
-      _note: "The version of the ateam-mcp process actually serving this call, and the API it talks to. If a fix looks missing, check this FIRST — a local MCP process keeps running the code it loaded at session start, so a pushed/published fix is not live until the process restarts.",
+      base_url: getBaseUrl(sid),
+      _note: "The version of the ateam-mcp process actually serving this call, and the API THIS SESSION talks to (per-session, as set by ateam_auth's `url`). If a fix looks missing, check this FIRST — a local MCP process keeps running the code it loaded at session start, so a pushed/published fix is not live until the process restarts.",
     },
     platform_positioning: {
       name: "A-Team",
@@ -3514,22 +3528,76 @@ export const handlers = {
     if (!api_key) {
       return { ok: false, message: "Provide either api_key or master_key." };
     }
-    // Auto-extract tenant from key if not provided.
-    // Fail loudly if neither the explicit tenant arg nor a parseable apiKey
-    // yields a tenant — previously fell back to "main" silently.
-    let resolvedTenant = tenant;
+    // ── THE KEY NAMES ITS ENVIRONMENT ──────────────────────────────────────
+    //
+    // One public MCP endpoint, and until now nothing about a session said which
+    // environment it was on: the caller passed `url` or silently got the prod
+    // default. A dev key at the prod base is just a 401, diagnosed after the
+    // fact (see the hint below) and never prevented. The process starts at the
+    // key, so the key carries the environment.
+    //
+    // NO FALLBACK, in either direction. A key that names an environment routes
+    // there and NOWHERE else; if that backend rejects it, that is the answer.
+    // Retrying the sibling host is how a dev key deploys to production.
+    const keyEnv = parseApiKey(api_key).env;
+    const explicitUrl = url ? url.replace(/\/+$/, "") : undefined;
+
+    // An explicit url that CONTRADICTS the key is refused here, locally, before
+    // any network call. The override still exists for unusual hosts (localhost,
+    // a staging box) — envForBaseUrl only recognises the known prod/dev hosts,
+    // so anything else passes through untouched. What it must never be is a way
+    // to cross environments by accident.
+    if (keyEnv && explicitUrl) {
+      const urlEnv = envForBaseUrl(explicitUrl);
+      if (urlEnv && urlEnv !== keyEnv) {
+        return {
+          ok: false,
+          message: `Refusing to authenticate: this key names the "${keyEnv}" environment, but url points at "${urlEnv}" (${explicitUrl}). One of them is wrong, and guessing which would mean operating on the wrong system. Drop the url argument to use the key's own environment, or use a key for "${urlEnv}".`,
+        };
+      }
+    }
+
+    const apiUrl = explicitUrl || baseUrlForKeyEnv(api_key) || undefined;
+
+    // ── WHO IS THIS KEY? ───────────────────────────────────────────────────
+    //
+    // It used to be answered by splitting the string, which is exactly why the
+    // customer's name travelled inside the credential — into logs, screenshots,
+    // support tickets. A SEALED key (`adas_<env>_<blob>`) does not carry it, so
+    // we ASK. Order of preference, and nothing beyond it:
+    //
+    //   1. an explicit `tenant` argument
+    //   2. the tenant the key still spells out (older formats)
+    //   3. GET /auth/whoami
+    //
+    // A sealed key whose whoami fails is REFUSED. Not "authenticated without a
+    // tenant", not retried elsewhere: ateam_auth is the moment a session learns
+    // who it is, and half-knowing is how a caller ends up acting on the wrong
+    // account. Nothing here invents a tenant under any circumstances.
+    let resolvedTenant = tenant || parseApiKey(api_key).tenant;
     if (!resolvedTenant) {
-      const parsed = parseApiKey(api_key);
-      resolvedTenant = parsed.tenant;
+      const base = apiUrl || getBaseUrl(sessionId);
+      try {
+        const me = await whoami(api_key, base);
+        resolvedTenant = me.tenant;
+      } catch (err) {
+        return {
+          ok: false,
+          message:
+            `This key does not name its tenant — the tenant is sealed inside it and only the server can read it — ` +
+            `and ${base} could not tell me who you are: ${err.message} ` +
+            `Nothing was authenticated: acting on a guessed tenant is the one failure this must never have. ` +
+            `If that host is an older deployment without /auth/whoami, upgrade it or pass tenant: "<name>" explicitly.`,
+        };
+      }
     }
     if (!resolvedTenant) {
       return {
         ok: false,
-        message: `Could not resolve tenant from api_key (expected format: adas_<tenant>_<32hex>). Pass the "tenant" arg explicitly, or check that your API key is well-formed.`,
+        message: `Could not resolve tenant from api_key (expected format: adas_<env>_<key>). Pass the "tenant" arg explicitly, or check that your API key is well-formed.`,
       };
     }
-    // Normalize URL: strip trailing slash
-    const apiUrl = url ? url.replace(/\/+$/, "") : undefined;
+
     setSessionCredentials(sessionId, { tenant: resolvedTenant, apiKey: api_key, apiUrl, explicit: true });
     // Persist override per bearer (survives session changes)
     setAuthOverride(sessionId, { tenant: resolvedTenant, apiKey: api_key, apiUrl });
@@ -3540,6 +3608,23 @@ export const handlers = {
       return {
         ok: true,
         tenant: resolvedTenant,
+        // The environment is part of WHO YOU ARE NOW, so it is reported here and
+        // in ateam_bootstrap.runtime, from the same resolution — one question,
+        // one answer.
+        //
+        // A KEY THAT NAMES NO ENVIRONMENT GETS NO CLAIM. Until keys are
+        // recreated, a legacy `adas_<tenant>_<hex>` still authenticates and
+        // still lands on the process default — which is PRODUCTION. That
+        // routing predates this change and is not made worse by it, but
+        // reporting it as `environment: "prod"` would be: it would turn an
+        // unstated default into a confident assertion, which is the exact
+        // failure this whole change exists to remove. So the field says
+        // `unstated`, and the note says which base was used and why.
+        environment: keyEnv || (explicitUrl ? envForBaseUrl(explicitUrl) : null) || "unstated",
+        ...(!keyEnv && !explicitUrl && {
+          environment_note: `This key does not name an environment, so the process default was used (${getBaseUrl(sessionId)}). Recreate it as adas_<env>_<tenant>_<hex> to make the environment explicit — until then nothing here can confirm which system you are on.`,
+        }),
+        base_url: getBaseUrl(sessionId),
         message: `Authenticated to tenant "${resolvedTenant}"${urlNote}. ${result.solutions?.length || 0} solution(s) found.`,
       };
     } catch (err) {
@@ -3548,7 +3633,8 @@ export const handlers = {
       // versa). Surface the base we tried and, if it looks like that mismatch,
       // hint the dev-api retry — instead of a generic "invalid/unconfigured key".
       const base = getBaseUrl(sessionId) || "";
-      const wellFormedKey = parseApiKey(api_key).isValid;
+      const parsedKey = parseApiKey(api_key);
+      const wellFormedKey = parsedKey.isValid;
       const triedProd = /(?:^|\/\/)api\.ateam-ai\.com/.test(base);
       // THE HEADLINE MUST NOT CONTRADICT THE HINT. The upstream message is
       // "Invalid or unconfigured API key" — which for a well-formed key tried
@@ -3557,7 +3643,12 @@ export const handlers = {
       // did not need. The hint below already said the right thing and rescued a
       // session on 2026-08-21, but only because someone read past the first
       // line. Lead with the likely cause; keep the upstream text as detail.
-      if (wellFormedKey && triedProd) {
+      // A key that NAMES its environment cannot be in the wrong one — routing
+      // came from the key itself, and a contradicting url was refused above. So
+      // this hint is only for the older no-env keys that still land on the prod
+      // default. Offering it for an env-bearing key would send the reader
+      // chasing an environment mismatch that the format has already ruled out.
+      if (wellFormedKey && triedProd && !parsedKey.env) {
         return {
           ok: false,
           tenant: resolvedTenant,