@adrata/adrata-mcp 1.0.2 → 1.0.6

package/README.md

@@ -502,6 +502,31 @@ Enterprise authentication uses the `connect_workspace` tool for a browser-based
 
 Alternatively, set `ADRATA_OAUTH_TOKEN` directly for CI/CD or scripted environments.
 
+### Independent QA worker identities
+
+Run QA1 and QA2 as separate MCP processes with separate OAuth stores. Each
+process must complete its own interactive `connect_workspace({ writeAccess:
+true })` flow, which gives it a distinct dynamically registered OAuth client
+and token set:
+
+```bash
+# QA1 process
+ADRATA_MCP_IDENTITY_POOL=qa1 \
+ADRATA_MCP_CONFIG_DIR=/var/lib/adrata/mcp/qa1 \
+npx -y @adrata/adrata-mcp
+
+# QA2 process
+ADRATA_MCP_IDENTITY_POOL=qa2 \
+ADRATA_MCP_CONFIG_DIR=/var/lib/adrata/mcp/qa2 \
+npx -y @adrata/adrata-mcp
+```
+
+A named pool intentionally ignores `ADRATA_OAUTH_TOKEN`, the shared
+`adrata login` session, API keys, CLI tokens, and `~/.adrata/tokens.json`.
+Missing or shared `ADRATA_MCP_CONFIG_DIR` configuration fails closed; do not
+copy one pool's token file into another. The pool name is process routing
+metadata, while the independently issued OAuth credential is the QA identity.
+
 ## Troubleshooting
 
 ### Server fails to start
@@ -526,7 +551,10 @@ Alternatively, set `ADRATA_OAUTH_TOKEN` directly for CI/CD or scripted environme
 
 - The server auto-refreshes stored tokens from `~/.adrata/tokens.json`
 - If refresh fails, run `connect_workspace` again
-- Delete `~/.adrata/tokens.json` to start fresh
+- Never delete or disconnect the shared `~/.adrata/tokens.json` session as a
+  repair step; that silently signs every local agent out. Re-run
+  `connect_workspace` in the affected process. For a named QA pool, use that
+  pool's own `ADRATA_MCP_CONFIG_DIR` and complete consent there.
 
 ### Tools return empty results
 

package/access/auth.js

@@ -21,6 +21,7 @@ import {
   getValidToken,
   OAUTH_SCOPE,
   describeOAuthScopeCapabilities,
+  validateNamedPoolStorage,
   ReconnectRequiredError,
   TransientRefreshError,
 } from './oauth.js';
@@ -108,6 +109,49 @@ export function loadAgentSession() {
  *   5. No credentials (free)
  */
 export function authenticate() {
+  const identityPool = namedIdentityPoolConfiguration();
+  if (identityPool.active) {
+    if (!identityPool.valid) {
+      return {
+        tier: TIERS.FREE,
+        token: null,
+        apiKey: null,
+        apiUrl: process.env.ADRATA_API_URL || null,
+        workspaceId: process.env.ADRATA_WORKSPACE_ID || null,
+        authenticated: false,
+        source: 'none',
+        identityPool: identityPool.name,
+        message: identityPool.message,
+      };
+    }
+    const storedTokens = loadTokens();
+    if (storedTokens?.accessToken) {
+      return {
+        tier: TIERS.ENTERPRISE,
+        token: storedTokens.accessToken,
+        apiKey: null,
+        apiUrl: process.env.ADRATA_API_URL || storedTokens.apiBase || null,
+        workspaceId: storedTokens.workspaceId || process.env.ADRATA_WORKSPACE_ID || null,
+        authenticated: true,
+        source: 'stored_pool',
+        identityPool: identityPool.name,
+        issuerApiBase: storedTokens.apiBase || null,
+        _storedTokens: storedTokens,
+      };
+    }
+    return {
+      tier: TIERS.FREE,
+      token: null,
+      apiKey: null,
+      apiUrl: process.env.ADRATA_API_URL || null,
+      workspaceId: process.env.ADRATA_WORKSPACE_ID || null,
+      authenticated: false,
+      source: 'none',
+      identityPool: identityPool.name,
+      message: `No dedicated OAuth connection found for named MCP identity pool ${identityPool.name}. Run connect_workspace in that pool's MCP process.`,
+    };
+  }
+
   const oauthToken = process.env.ADRATA_OAUTH_TOKEN || '';
   const cliConfig = loadCliConfig();
   const apiKey = process.env.ADRATA_API_KEY || process.env.ADRATA_API_TOKEN || cliConfig.token || '';
@@ -189,6 +233,10 @@ export function authenticate() {
   };
 }
 
+export function namedIdentityPoolConfiguration(env = process.env) {
+  return validateNamedPoolStorage(env);
+}
+
 /**
  * Re-authenticate after a connect/disconnect event.
  * Returns a fresh auth context.
@@ -363,7 +411,7 @@ export async function getValidAgentToken(
 }
 
 export function assertOAuthIssuerMatchesTarget(authContext, apiBase) {
-  const issuerBound = authContext.source === 'stored' || authContext.source === 'agent_config';
+  const issuerBound = ['stored', 'stored_pool', 'agent_config'].includes(authContext.source);
   if (!issuerBound || !authContext.issuerApiBase) return;
   const issuer = new URL(authContext.issuerApiBase).origin;
   const target = new URL(apiBase).origin;

package/access/oauth.js

@@ -14,7 +14,18 @@
 import { createServer } from 'node:http';
 import { randomBytes, createCipheriv, createDecipheriv, createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, chmodSync } from 'node:fs';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { canonicalResource } from './resource-metadata.js';
@@ -23,10 +34,8 @@ import { canonicalResource } from './resource-metadata.js';
 // Constants
 // ---------------------------------------------------------------------------
 
-const ADRATA_DIR = process.env.ADRATA_MCP_CONFIG_DIR
-  ? resolve(process.env.ADRATA_MCP_CONFIG_DIR)
-  : join(homedir(), '.adrata');
-const TOKEN_FILE = join(ADRATA_DIR, 'tokens.json');
+const DEFAULT_ADRATA_DIR = join(homedir(), '.adrata');
+const IDENTITY_POOL_MARKER = 'identity-pool.json';
 const CALLBACK_PORT = 19472; // Ephemeral port for OAuth callback
 const CALLBACK_PATH = '/oauth/callback';
 // IPv4 loopback is FIRST and that order is load-bearing, not cosmetic.
@@ -104,8 +113,64 @@ export const OAUTH_WRITE_SCOPE = [
   'write:companies', 'write:people', 'write:buyer-groups',
   'write:opportunities', 'write:actions', 'write:tasks',
   'write:partnerships', 'write:sequences', 'write:campaigns', 'write:data',
+  // Authorising an external system to write into the workspace — connecting a
+  // CRM, or binding a source-control repository to a board. Its absence was not
+  // a deliberate least-privilege call, because `read:integrations` was already
+  // granted by default: the connection could SEE every integration and connect
+  // none of them.
+  //
+  // Measured 2026-08-29. `POST /api/v1/scm/connections` returned 403
+  // insufficient_scope against a session holding ten other write scopes, so the
+  // Starfield board could not be wired to GitHub from the only layer that has a
+  // connect flow at all — there is no Connections UI for source control. Every
+  // card move stayed manual as a result.
+  //
 ].join(' ');
 
+/**
+ * Scopes this client knows about that the DEPLOYED authorization server may not.
+ *
+ * `write:integrations` authorises an external system to write into the
+ * workspace — connecting a CRM, or binding a source-control repository to a
+ * board. It was added here on 2026-08-29 (#2375) because `read:integrations`
+ * was already in the default grant, so a connection could SEE every integration
+ * and connect none of them: `POST /api/v1/scm/connections` returned 403
+ * insufficient_scope against a session holding ten other write scopes.
+ *
+ * It is NOT requested by default, and the reason is a property of OAuth rather
+ * than of this scope. **One unrecognised scope rejects the entire authorization
+ * request** — the server answers `invalid_scope` and issues nothing, so asking
+ * for a scope the running API has never heard of does not degrade the grant, it
+ * destroys it. Measured the same day: production served build `19ccef3a4a`,
+ * twenty-eight commits behind the `main` that introduced the scope, and every
+ * `connect_workspace({ writeAccess: true })` failed outright while read-only
+ * connected instantly. The board could not be written to at all, by any agent,
+ * for hours — a strictly worse outcome than never having asked.
+ *
+ * Discovery cannot decide this for us today, which is worth recording so the
+ * obvious fix is not attempted twice. The API does serve RFC 8414 metadata at
+ * `/.well-known/oauth-authorization-server`, but its `scopes_supported`
+ * advertises FIVE scopes while the same server happily issues thirteen on a
+ * read-only connect. Intersecting a request against that list would strip
+ * scopes that demonstrably work. Fix the metadata first; then this list can go
+ * away in favour of asking the server what it supports.
+ *
+ * To request it once the API is deployed at or past the commit that added it:
+ *
+ *     ADRATA_MCP_REQUEST_PENDING_SCOPES=1
+ *
+ * Verify first, because the failure is total rather than partial:
+ *
+ *     curl -s https://api.adrata.com/health | jq -r .build_sha
+ *     git show <sha>:code/api/crates/security/src/scopes.rs | grep -c write:integrations
+ */
+export const OAUTH_PENDING_SCOPE = ['write:integrations'].join(' ');
+
+/** Whether to also request scopes the deployed server may not recognise yet. */
+export function requestsPendingScopes(env = process.env) {
+  return env.ADRATA_MCP_REQUEST_PENDING_SCOPES === '1';
+}
+
 /**
  * Scope string for a connection. Read-only unless write access is requested.
  *
@@ -114,7 +179,11 @@ export const OAUTH_WRITE_SCOPE = [
  * so elevation is opt-in on exactly one value.
  */
 export function oauthScopeFor({ writeAccess = false } = {}) {
-  return writeAccess === true ? `${OAUTH_SCOPE} ${OAUTH_WRITE_SCOPE}` : OAUTH_SCOPE;
+  if (writeAccess !== true) return OAUTH_SCOPE;
+  const write = requestsPendingScopes()
+    ? `${OAUTH_WRITE_SCOPE} ${OAUTH_PENDING_SCOPE}`
+    : OAUTH_WRITE_SCOPE;
+  return `${OAUTH_SCOPE} ${write}`;
 }
 
 /**
@@ -240,9 +309,11 @@ export function oauthCallbackPage({ success, title, message, detail }) {
 }
 
 /**
- * Derive a machine-specific encryption key from hostname + username.
+ * Derive a runtime-layout-specific encryption key from home directory + user.
  * This is intentionally not high-security — it prevents casual plaintext
- * exposure while remaining portable across sessions without a password.
+ * exposure while remaining portable across sessions without a password. AWS
+ * workers sharing one token store must therefore pin the same runtime user and
+ * home directory; a different container user/home cannot decrypt that store.
  */
 function deriveKey() {
   const material = `adrata-mcp:${homedir()}:${process.env.USER || process.env.USERNAME || 'default'}`;
@@ -272,9 +343,76 @@ function normalizeTokenResult(result) {
   };
 }
 
+/**
+ * The default registration name, used when the agent has not declared itself.
+ *
+ * Every install registered under this until 2026-08-29, which is why the board
+ * can say a program moved a card but not WHICH program. The server treats it as
+ * an undeclared installation and the card reads `unrecorded` — deliberately, so
+ * that the cards already filed under it are never retroactively given a name
+ * nobody recorded.
+ */
+export const DEFAULT_CLIENT_NAME = 'Adrata MCP';
+
+/**
+ * The agents that can declare themselves, keyed by the value of `ADRATA_AGENT`.
+ *
+ * The same closed vocabulary the API resolves against
+ * (`adrata_routes_gtm::work_boards::species::NAMED_AGENTS`) and the same one the
+ * settings page publishes as `McpClientId`. A value outside it is ignored rather
+ * than passed through: a registration name is drawn on a consent screen and, once
+ * this lands, next to work on a board, so an arbitrary string is not something to
+ * forward on trust.
+ */
+const DECLARABLE_AGENTS = new Map([
+  ['claude-code', 'Claude Code'],
+  ['codex', 'Codex'],
+  ['grok', 'Grok'],
+]);
+
+/**
+ * What this installation should register itself as.
+ *
+ * The declaration is made ONCE, here, at connect time — not on every write —
+ * because the name then lives in the server's own registration record and is
+ * read off the verified credential rather than off a request. That is the whole
+ * difference between a label bound to a credential and a header a caller sends.
+ *
+ * `ADRATA_AGENT` mirrors `JOURNAL_AGENT`, which is the one place this company
+ * already asks an agent to name itself, and it carries the same rule from
+ * `journal/README.md`: never guess. An unset or unrecognised value registers
+ * under {@link DEFAULT_CLIENT_NAME} and the board reads `unrecorded`, which is
+ * the honest answer and the one failure direction that under-reports rather than
+ * mislabels.
+ *
+ * What this asserts, precisely: that whoever ran `connect_workspace` said this
+ * was Claude Code. It is not proof of what is at the other end — nothing short
+ * of a per-vendor attested credential would be — and the API never lets it
+ * promote a caller's species or change who a card says did the work.
+ *
+ * Pure, so the exact bytes sent to Dynamic Client Registration can be asserted
+ * in a test rather than discovered in a consent screen.
+ */
+export function declaredClientName(env = process.env) {
+  const declared = String(env.ADRATA_AGENT ?? '')
+    .trim()
+    .toLowerCase();
+  // The EXACT vocabulary string, with nothing appended. A decorated name like
+  // "Claude Code (Adrata MCP)" would read better in a client list and would
+  // resolve to nothing, because the API matches the closed vocabulary exactly
+  // rather than searching inside a string — and a matcher that searched would be
+  // one an arbitrary registration could satisfy by containing the word.
+  return DECLARABLE_AGENTS.get(declared) ?? DEFAULT_CLIENT_NAME;
+}
+
 /**
  * Register a fresh native/public client for this explicit connection attempt.
  * PKCE protects the code exchange; an npm-embedded client secret would not.
+ *
+ * A FRESH client per attempt is what makes naming the agent possible at all:
+ * Claude Code and Codex on one machine become two distinct `oauth_clients` rows,
+ * so the API's per-credential actor key already tells them apart. Until now they
+ * merely shared a display name.
  */
 export async function registerNativeClient(
   apiBase,
@@ -287,7 +425,7 @@ export async function registerNativeClient(
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      client_name: 'Adrata MCP',
+      client_name: declaredClientName(),
       redirect_uris: redirectUris,
       grant_types: ['authorization_code', 'refresh_token'],
       response_types: ['code'],
@@ -404,9 +542,91 @@ function decrypt(ciphertext) {
 // Token storage
 // ---------------------------------------------------------------------------
 
-function ensureDir() {
-  if (!existsSync(ADRATA_DIR)) {
-    mkdirSync(ADRATA_DIR, { recursive: true, mode: 0o700 });
+export function validateNamedPoolStorage(env = process.env, home = homedir()) {
+  const name = env.ADRATA_MCP_IDENTITY_POOL?.trim();
+  if (!name) {
+    return { active: false, valid: true, name: null, configDir: null, message: null };
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
+    return {
+      active: true,
+      valid: false,
+      name,
+      configDir: null,
+      message: 'ADRATA_MCP_IDENTITY_POOL must use 1-64 letters, numbers, dots, underscores, or hyphens.',
+    };
+  }
+  const configured = env.ADRATA_MCP_CONFIG_DIR?.trim();
+  if (!configured) {
+    return {
+      active: true,
+      valid: false,
+      name,
+      configDir: null,
+      message: `ADRATA_MCP_CONFIG_DIR is required for named MCP identity pool ${name}.`,
+    };
+  }
+  const configDir = resolve(configured);
+  const sharedDir = join(home, '.adrata');
+  if (configDir === sharedDir) {
+    return {
+      active: true,
+      valid: false,
+      name,
+      configDir,
+      message: `Named MCP identity pool ${name} cannot use the shared ${join(sharedDir, 'tokens.json')} store.`,
+    };
+  }
+  return { active: true, valid: true, name, configDir, message: null };
+}
+
+function tokenStorage() {
+  const pool = validateNamedPoolStorage();
+  if (pool.active && !pool.valid) return { ...pool, tokenFile: null };
+  const configDir = pool.active
+    ? pool.configDir
+    : (process.env.ADRATA_MCP_CONFIG_DIR?.trim()
+        ? resolve(process.env.ADRATA_MCP_CONFIG_DIR)
+        : DEFAULT_ADRATA_DIR);
+  return {
+    ...pool,
+    configDir,
+    tokenFile: join(configDir, 'tokens.json'),
+    markerFile: join(configDir, IDENTITY_POOL_MARKER),
+  };
+}
+
+function ensureDir(configDir) {
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  }
+}
+
+function storedPoolName(storage) {
+  if (!storage.active) return null;
+  try {
+    const marker = JSON.parse(readFileSync(storage.markerFile, 'utf8'));
+    return typeof marker?.identityPool === 'string' ? marker.identityPool : null;
+  } catch {
+    return null;
+  }
+}
+
+function claimNamedPoolStorage(storage) {
+  if (!storage.active) return;
+  const marker = `${JSON.stringify({ version: 1, identityPool: storage.name }, null, 2)}\n`;
+  try {
+    writeFileSync(storage.markerFile, marker, { flag: 'wx', mode: 0o600 });
+    try { chmodSync(storage.markerFile, 0o600); } catch { /* best-effort */ }
+    return;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  const owner = storedPoolName(storage);
+  if (owner !== storage.name) {
+    throw new Error(
+      `MCP config directory ${storage.configDir} already belongs to named MCP identity pool ${owner || 'unknown'}.`,
+    );
   }
 }
 
@@ -414,14 +634,32 @@ function ensureDir() {
  * Save tokens to ~/.adrata/tokens.json (encrypted).
  */
 export function saveTokens(tokenData) {
-  ensureDir();
+  const storage = tokenStorage();
+  if (!storage.valid) throw new Error(storage.message);
+  ensureDir(storage.configDir);
+  claimNamedPoolStorage(storage);
   const payload = {
     v: 1,
     data: encrypt(JSON.stringify(tokenData)),
     updatedAt: new Date().toISOString(),
   };
-  writeFileSync(TOKEN_FILE, JSON.stringify(payload, null, 2), { mode: 0o600 });
-  try { chmodSync(TOKEN_FILE, 0o600); } catch { /* best-effort */ }
+  // Readers in other MCP processes must see either the complete old envelope
+  // or the complete new one. A direct truncate/write can expose half JSON and
+  // make a healthy pool look disconnected during refresh-token rotation.
+  const nonce = randomBytes(12).toString('hex');
+  const temporary = join(storage.configDir, `.tokens-${process.pid}-${nonce}.tmp`);
+  try {
+    writeFileSync(temporary, JSON.stringify(payload, null, 2), {
+      flag: 'wx',
+      mode: 0o600,
+    });
+    try { chmodSync(temporary, 0o600); } catch { /* best-effort */ }
+    renameSync(temporary, storage.tokenFile);
+    try { chmodSync(storage.tokenFile, 0o600); } catch { /* best-effort */ }
+  } catch (error) {
+    try { if (existsSync(temporary)) unlinkSync(temporary); } catch { /* best-effort */ }
+    throw error;
+  }
 }
 
 /**
@@ -429,8 +667,10 @@ export function saveTokens(tokenData) {
  */
 export function loadTokens() {
   try {
-    if (!existsSync(TOKEN_FILE)) return null;
-    const raw = JSON.parse(readFileSync(TOKEN_FILE, 'utf8'));
+    const storage = tokenStorage();
+    if (!storage.valid || !existsSync(storage.tokenFile)) return null;
+    if (storage.active && storedPoolName(storage) !== storage.name) return null;
+    const raw = JSON.parse(readFileSync(storage.tokenFile, 'utf8'));
     if (raw.v !== 1 || !raw.data) return null;
     return JSON.parse(decrypt(raw.data));
   } catch {
@@ -443,7 +683,10 @@ export function loadTokens() {
  */
 export function clearTokens() {
   try {
-    if (existsSync(TOKEN_FILE)) unlinkSync(TOKEN_FILE);
+    const storage = tokenStorage();
+    if (!storage.valid) return;
+    if (storage.active && storedPoolName(storage) !== storage.name) return;
+    if (existsSync(storage.tokenFile)) unlinkSync(storage.tokenFile);
   } catch { /* ignore */ }
 }
 
@@ -513,6 +756,10 @@ export class TransientRefreshError extends Error {
 
 const REFRESH_MAX_ATTEMPTS = 3;
 const REFRESH_BASE_DELAY_MS = 250;
+const REFRESH_LOCK_FILE = '.tokens-refresh.lock';
+const REFRESH_LOCK_POLL_MS = 25;
+const REFRESH_LOCK_WAIT_MS = 120_000;
+const REFRESH_LOCK_STALE_MS = 300_000;
 
 function refreshBackoffDelay(attempt) {
   // Exponential backoff with light jitter: ~250ms then ~500ms between attempts.
@@ -533,6 +780,66 @@ function sleep(ms) {
  */
 const _inflightRefresh = new Map();
 
+function tokenRevision(tokens) {
+  if (!tokens) return null;
+  return [
+    tokens.clientId,
+    tokens.refreshToken,
+    tokens.accessToken,
+    tokens.expiresAt,
+    tokens.apiBase,
+  ].map((value) => String(value ?? '')).join('\u0000');
+}
+
+/**
+ * Elect one refresher across every MCP process sharing this config directory.
+ * The file is the lock: `wx` is atomic on the shared filesystem. A generous
+ * stale threshold recovers a process/container that died while holding it.
+ */
+async function acquireRefreshLock() {
+  const storage = tokenStorage();
+  if (!storage.valid) throw new Error(storage.message);
+  ensureDir(storage.configDir);
+  claimNamedPoolStorage(storage);
+  const lockFile = join(storage.configDir, REFRESH_LOCK_FILE);
+  const nonce = randomBytes(16).toString('hex');
+  const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
+
+  while (true) {
+    try {
+      const descriptor = openSync(lockFile, 'wx', 0o600);
+      try {
+        writeFileSync(descriptor, `${JSON.stringify({ pid: process.pid, nonce, createdAt: new Date().toISOString() })}\n`);
+      } finally {
+        closeSync(descriptor);
+      }
+      return () => {
+        try {
+          const owner = JSON.parse(readFileSync(lockFile, 'utf8'));
+          if (owner?.nonce === nonce) unlinkSync(lockFile);
+        } catch { /* already released or replaced after stale recovery */ }
+      };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+
+    try {
+      if (Date.now() - statSync(lockFile).mtimeMs > REFRESH_LOCK_STALE_MS) {
+        unlinkSync(lockFile);
+        continue;
+      }
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+    }
+    if (Date.now() >= deadline) {
+      throw new TransientRefreshError(
+        'Timed out waiting for another MCP worker to finish rotating the shared refresh token.',
+      );
+    }
+    await sleep(REFRESH_LOCK_POLL_MS + Math.floor(Math.random() * REFRESH_LOCK_POLL_MS));
+  }
+}
+
 /**
  * Refresh the access token using the refresh token.
  *
@@ -549,13 +856,35 @@ export async function refreshAccessToken(apiBase, fetchImpl = fetch) {
   const existing = _inflightRefresh.get(apiBase);
   if (existing) return existing;
 
-  const inflight = performTokenRefresh(apiBase, fetchImpl).finally(() => {
+  const observedRevision = tokenRevision(loadTokens());
+  const inflight = performLockedTokenRefresh(apiBase, fetchImpl, observedRevision).finally(() => {
     _inflightRefresh.delete(apiBase);
   });
   _inflightRefresh.set(apiBase, inflight);
   return inflight;
 }
 
+async function performLockedTokenRefresh(apiBase, fetchImpl, observedRevision) {
+  const releaseLock = await acquireRefreshLock();
+  try {
+    // Another process may have won while this one waited. Reload only after
+    // acquiring the filesystem lock and consume its rotated result instead of
+    // posting the now-revoked refresh token we originally observed.
+    const current = loadTokens();
+    if (
+      current
+      && tokenRevision(current) !== observedRevision
+      && storedSessionMatchesApiBase(apiBase, current)
+      && !isTokenExpired(current)
+    ) {
+      return current;
+    }
+    return await performTokenRefresh(apiBase, fetchImpl);
+  } finally {
+    releaseLock();
+  }
+}
+
 async function performTokenRefresh(apiBase, fetchImpl) {
   const tokens = loadTokens();
   if (!tokens || !tokens.refreshToken) {
@@ -576,7 +905,7 @@ async function performTokenRefresh(apiBase, fetchImpl) {
     refresh_token: tokens.refreshToken,
     // RFC 8707: keep the same audience binding the initial grant used so the
     // refreshed access token stays bound to the /api/v1/mcp resource.
-    resource: tokens.resource || canonicalResource(),
+    resource: tokens.resource || canonicalResource(apiBase),
   });
 
   let lastError;
@@ -669,7 +998,7 @@ export async function getValidToken(apiBase, { forceRefresh = false, fetchImpl =
 /**
  * Build the OAuth authorization URL.
  */
-function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH_SCOPE) {
+export function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH_SCOPE) {
   // Use the web app's OAuth authorize page (user-facing login + consent screen)
   const url = new URL(`${OAUTH_BASE_PATH}/authorize`, apiBase);
   url.searchParams.set('client_id', clientId);
@@ -680,7 +1009,7 @@ function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH
   url.searchParams.set('source', 'mcp');
   // RFC 8707 Resource Indicator — request a token audience-bound to this MCP
   // resource so it cannot be replayed against a different service.
-  url.searchParams.set('resource', canonicalResource());
+  url.searchParams.set('resource', canonicalResource(apiBase));
   url.searchParams.set('code_challenge', pkce.challenge);
   url.searchParams.set('code_challenge_method', 'S256');
   return { url: url.toString(), state, codeVerifier: pkce.verifier };
@@ -853,7 +1182,7 @@ export function createOAuthCallbackRequestHandler({
 /**
  * Exchange an authorization code for tokens.
  */
-async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri) {
+export async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri, fetchImpl = fetch) {
   const url = new URL(`${OAUTH_BASE_PATH}/token`, apiBase);
   const body = new URLSearchParams({
     grant_type: 'authorization_code',
@@ -861,10 +1190,10 @@ async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri)
     code,
     code_verifier: codeVerifier,
     redirect_uri: redirectUri,
-    resource: canonicalResource(),
+    resource: canonicalResource(apiBase),
   });
 
-  const res = await fetch(url.toString(), {
+  const res = await fetchImpl(url.toString(), {
     method: 'POST',
     headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
     body,
@@ -1026,7 +1355,7 @@ export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
     clientId,
     clientRegistration: registration.clientRegistration,
     tokenEndpointAuthMethod: registration.tokenEndpointAuthMethod,
-    resource: canonicalResource(),
+    resource: canonicalResource(apiBase),
     apiBase,
     connectedAt: new Date().toISOString(),
   };

package/access/resource-metadata.js

@@ -35,8 +35,16 @@ export function authorizationServers() {
  * The canonical resource identifier for this MCP server. RFC 8707 clients
  * send this as the `resource` parameter so the AS can bind the token's
  * audience to it. Defaults to the REST MCP resource the Rust AS advertises.
+ *
+ * Client flows pass their explicit API base so a staging authorization request
+ * cannot accidentally ask for a production-bound token. Hosted resource-server
+ * callers omit it and continue to use the configured authorization server.
+ *
+ * @param {string} [apiBase] - Explicit authorization-server/API base for a
+ *   client connection.
  */
-export function canonicalResource() {
+export function canonicalResource(apiBase) {
+  if (apiBase) return `${apiBase.replace(/\/$/, '')}/api/v1/mcp`;
   if (process.env.ADRATA_MCP_RESOURCE) return process.env.ADRATA_MCP_RESOURCE.trim();
   const as = authorizationServers()[0] || 'https://api.adrata.com';
   return `${as.replace(/\/$/, '')}/api/v1/mcp`;