@adrata/adrata-mcp 1.0.1 → 1.0.3

package/README.md

@@ -10,7 +10,7 @@ This package is also published as **[`@adrata/starfield-mcp`](https://www.npmjs.
 (binary `starfield-mcp`), for people wiring a coding agent to their Starfield
 board rather than to the CRM. It is not a fork and not a subset: it depends on
 this package, defaults `ADRATA_MCP_SERVER_NAME` to `Starfield` so the client's
-server list says Starfield, and imports the same `server.js`. Same 233 tools,
+server list says Starfield, and imports the same `server.js`. Same governed tool surface,
 same tiers, same governed-write contract, and nothing to keep in sync.
 
 Install whichever name matches what you are doing. If you already have one, you

package/access/auth.js

@@ -16,10 +16,27 @@
  */
 
 import { TIERS, getToolTier, tierSatisfies } from './tiers.js';
-import { loadTokens, getValidToken, OAUTH_SCOPE, describeOAuthScopeCapabilities } from './oauth.js';
-import { existsSync, readFileSync } from 'node:fs';
+import {
+  loadTokens,
+  getValidToken,
+  OAUTH_SCOPE,
+  describeOAuthScopeCapabilities,
+  ReconnectRequiredError,
+  TransientRefreshError,
+} from './oauth.js';
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, resolve, join } from 'node:path';
+import { dirname, isAbsolute, resolve, join } from 'node:path';
 
 const DEFAULT_CLI_CONFIG_PATH = join(homedir(), '.config', 'adrata', 'cli.json');
 const DEFAULT_AGENT_CONFIG_PATH = join(homedir(), '.config', 'adrata', 'agent.json');
@@ -53,7 +70,7 @@ export function loadCliConfig() {
 
 /**
  * Read the shared agent session (device-flow OAuth, written by `adrata login`).
- * Returns { accessToken, apiBase, workspaceId } or null when absent/unusable.
+ * Returns the full refreshable session or null when absent/unusable.
  */
 export function loadAgentSession() {
   try {
@@ -66,8 +83,14 @@ export function loadAgentSession() {
     if (!accessToken) return null;
     return {
       accessToken,
+      refreshToken: str('refreshToken'),
+      accessExpiresAt:
+        typeof parsed.accessExpiresAt === 'number' && Number.isFinite(parsed.accessExpiresAt)
+          ? parsed.accessExpiresAt
+          : null,
       apiBase: str('apiBase')?.replace(/\/+$/, '') ?? null,
       workspaceId: str('workspaceId'),
+      user: parsed.user && typeof parsed.user === 'object' ? parsed.user : null,
     };
   } catch {
     return null;
@@ -119,6 +142,7 @@ export function authenticate() {
       authenticated: true,
       source: 'agent_config',
       issuerApiBase: agentSession.apiBase || null,
+      _agentSession: agentSession,
     };
   }
 
@@ -173,6 +197,171 @@ export function reauthenticate() {
   return authenticate();
 }
 
+const AGENT_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+const AGENT_REFRESH_LOCK_STALE_MS = 30_000;
+const AGENT_REFRESH_LOCK_WAIT_MS = 10_000;
+const AGENT_REFRESH_MAX_ATTEMPTS = 3;
+const AGENT_REFRESH_BASE_DELAY_MS = 250;
+const _agentRefreshInflight = new Map();
+
+function agentSessionFresh(session) {
+  return (
+    typeof session?.accessExpiresAt === 'number' &&
+    Date.now() < session.accessExpiresAt - AGENT_REFRESH_BUFFER_MS
+  );
+}
+
+function persistAgentSession(path, session) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function agentRefreshBackoffDelay(attempt) {
+  const base = AGENT_REFRESH_BASE_DELAY_MS * 2 ** (attempt - 1);
+  return base + Math.floor(Math.random() * AGENT_REFRESH_BASE_DELAY_MS);
+}
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireAgentRefreshLock(path) {
+  const lockPath = `${path}.refresh.lock`;
+  const deadline = Date.now() + AGENT_REFRESH_LOCK_WAIT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      closeSync(fd);
+      return () => {
+        try {
+          unlinkSync(lockPath);
+        } catch {
+          // Another process may have cleaned a stale lock after this process was interrupted.
+        }
+      };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > AGENT_REFRESH_LOCK_STALE_MS) {
+          unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+  throw new TransientRefreshError('Timed out waiting for another MCP client to refresh the shared session.');
+}
+
+/**
+ * Return a valid token from the shared `adrata login` session.
+ *
+ * Refresh tokens rotate, while several MCP hosts may read the same agent.json. The in-process
+ * single-flight prevents duplicate refreshes inside one server and the adjacent lock file extends
+ * that guarantee across Codex/Claude/Cursor processes. The winner atomically replaces agent.json;
+ * waiters re-read it and reuse the rotated token instead of presenting the now-revoked old one.
+ */
+export async function getValidAgentToken(
+  apiBase,
+  { fetchImpl = fetch, forceRefresh = false, rejectedToken = null } = {},
+) {
+  const path = getAgentConfigPath();
+  const quick = loadAgentSession();
+  if (!quick) return null;
+  if (!forceRefresh && agentSessionFresh(quick)) return quick.accessToken;
+
+  const key = `${path}|${new URL(apiBase).origin}`;
+  const existing = _agentRefreshInflight.get(key);
+  if (existing) return existing;
+
+  const inflight = (async () => {
+    const release = await acquireAgentRefreshLock(path);
+    try {
+      const current = loadAgentSession();
+      if (!current) return null;
+      if (current.apiBase && new URL(current.apiBase).origin !== new URL(apiBase).origin) {
+        throw new ReconnectRequiredError(
+          'Shared agent session/API mismatch. Run adrata login against the target environment.',
+        );
+      }
+      if (rejectedToken && current.accessToken !== rejectedToken) return current.accessToken;
+      if (!forceRefresh && agentSessionFresh(current)) return current.accessToken;
+      if (!current.refreshToken) {
+        throw new ReconnectRequiredError(
+          'The shared adrata login session has no refresh token. Run adrata login once to reconnect.',
+        );
+      }
+
+      let data;
+      let lastTransientError;
+      for (let attempt = 1; attempt <= AGENT_REFRESH_MAX_ATTEMPTS; attempt += 1) {
+        let response;
+        try {
+          response = await fetchImpl(`${apiBase.replace(/\/+$/, '')}/api/auth/refresh-token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshToken: current.refreshToken }),
+          });
+        } catch (error) {
+          lastTransientError = new TransientRefreshError(
+            `Shared session refresh network error: ${error.message}`,
+            { cause: error },
+          );
+          if (attempt < AGENT_REFRESH_MAX_ATTEMPTS) {
+            await wait(agentRefreshBackoffDelay(attempt));
+            continue;
+          }
+          throw lastTransientError;
+        }
+
+        data = await response.json().catch(() => ({}));
+        if (response.ok) break;
+        if (response.status === 429 || response.status >= 500) {
+          lastTransientError = new TransientRefreshError(
+            `Shared session refresh failed (${response.status}).`,
+          );
+          if (attempt < AGENT_REFRESH_MAX_ATTEMPTS) {
+            await wait(agentRefreshBackoffDelay(attempt));
+            continue;
+          }
+          throw lastTransientError;
+        }
+        throw new ReconnectRequiredError(
+          `Shared adrata login refresh was rejected (${response.status}). Run adrata login once to reconnect.`,
+        );
+      }
+
+      if (!data?.accessToken || !data?.refreshToken || !Number.isFinite(data?.expires)) {
+        throw new TransientRefreshError('Shared session refresh returned an incomplete token response.');
+      }
+
+      const workspaceId =
+        data.user?.activeWorkspaceId ?? data.user?.workspaces?.[0]?.id ?? current.workspaceId;
+      const updated = {
+        ...current,
+        apiBase: apiBase.replace(/\/+$/, ''),
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        accessExpiresAt: data.expires * 1000,
+        workspaceId,
+        user: data.user ?? current.user,
+        updatedAt: new Date().toISOString(),
+      };
+      persistAgentSession(path, updated);
+      return updated.accessToken;
+    } finally {
+      release();
+    }
+  })().finally(() => _agentRefreshInflight.delete(key));
+
+  _agentRefreshInflight.set(key, inflight);
+  return inflight;
+}
+
 export function assertOAuthIssuerMatchesTarget(authContext, apiBase) {
   const issuerBound = authContext.source === 'stored' || authContext.source === 'agent_config';
   if (!issuerBound || !authContext.issuerApiBase) return;

package/access/oauth.js

@@ -51,6 +51,18 @@ export const OAUTH_CALLBACK_ENDPOINTS = Object.freeze([
   { host: '::1', url: `http://[::1]:${CALLBACK_PORT}${CALLBACK_PATH}` },
 ]);
 const OAUTH_BASE_PATH = '/api/v1/enterprise/oauth';
+export const SEEDED_PUBLIC_CLIENT_ID = 'adrata-mcp-client';
+// The static production client's registered read ceiling. Newer optional read
+// families are available through DCR, but asking the seeded client for them
+// makes `/authorize` reject the WHOLE request before it can present consent.
+// Write scopes are intentionally not listed: current APIs may elevate those
+// only after a signed-in workspace member approves them.
+export const SEEDED_PUBLIC_READ_SCOPE = [
+  'read:companies', 'read:people', 'read:opportunities', 'read:actions',
+  'read:pipeline', 'read:speedrun', 'read:signals', 'read:search',
+  'read:analytics', 'read:buyer-groups', 'read:tasks', 'read:integrations',
+  'ai:base',
+].join(' ');
 // Read-only surface + the AI dispatcher. `ai:base` is required for anything
 // routing through POST /api/v1/ai-crm-tools/execute. The additional read:*
 // scopes unblock ~30 tools that scope_guard gates behind their own families
@@ -92,6 +104,22 @@ 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.
+  //
+  // Still opt-in: this list is only requested by connect_workspace({ writeAccess:
+  // true }), so the default grant remains read-only and a leaked token cannot
+  // authorise an integration.
+  'write:integrations',
 ].join(' ');
 
 /**
@@ -288,7 +316,12 @@ export async function registerNativeClient(
   });
   const data = await res.json().catch(() => ({}));
   if (!res.ok) {
-    throw new Error(`OAuth client registration failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`);
+    const error = new Error(
+      `OAuth client registration failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`
+    );
+    error.status = res.status;
+    error.oauthCode = data?.error;
+    throw error;
   }
   if (typeof data.client_id !== 'string' || !data.client_id) {
     throw new Error('OAuth client registration returned no client_id.');
@@ -303,6 +336,61 @@ export async function registerNativeClient(
   };
 }
 
+/**
+ * Choose the public client for one connection attempt.
+ *
+ * Dynamic registration is preferred because it narrows each installation to
+ * its exact loopback redirect. Production also carries a seeded public PKCE
+ * client for continuity during a rollout, behind a proxy that blocks DCR, or
+ * after the per-IP DCR ceiling is reached. A public client id is not a secret;
+ * the authorization code remains bound to the exact redirect and PKCE
+ * verifier, and write scopes still require the signed-in human consent step.
+ */
+export async function registrationForConnection({
+  apiBase,
+  redirectUris,
+  requestedScope,
+  fetchImpl = fetch,
+  configuredClientId = process.env.ADRATA_MCP_CLIENT_ID?.trim(),
+} = {}) {
+  if (configuredClientId) {
+    return {
+      clientId: configuredClientId,
+      tokenEndpointAuthMethod: 'none',
+      clientRegistration: 'configured',
+    };
+  }
+
+  try {
+    return {
+      ...(await registerNativeClient(apiBase, fetchImpl, redirectUris, requestedScope)),
+      clientRegistration: 'dynamic',
+    };
+  } catch (error) {
+    // These responses mean registration is unavailable, not that the
+    // authorization itself was refused. Do not mask a malformed request (400)
+    // or an API failure (5xx): both need fixing rather than a second path.
+    if (![403, 404, 429].includes(error?.status)) throw error;
+    return {
+      clientId: SEEDED_PUBLIC_CLIENT_ID,
+      tokenEndpointAuthMethod: 'none',
+      clientRegistration: 'seeded_fallback',
+      // Keep requested write scopes: they are not self-granted here. The
+      // authorize endpoint intersects them with the authenticated approver's
+      // role and requires explicit consent. Only the extra READ families need
+      // narrowing to the seeded client's registered ceiling.
+      scope: [
+        ...SEEDED_PUBLIC_READ_SCOPE.split(' ').filter((scope) =>
+          String(requestedScope ?? '').split(/\s+/).includes(scope)
+        ),
+        ...String(requestedScope ?? '')
+          .split(/\s+/)
+          .filter((scope) => scope.startsWith('write:')),
+      ].join(' '),
+    };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Encryption helpers
 // ---------------------------------------------------------------------------
@@ -504,7 +592,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;
@@ -597,7 +685,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);
@@ -608,7 +696,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 };
@@ -781,7 +869,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',
@@ -789,10 +877,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,
@@ -901,24 +989,26 @@ export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
   // Prefer an explicitly provisioned client when an operator supplies one.
   // Otherwise use RFC 7591 DCR so every installation gets a real public client
   // instead of relying on a database seed or a secret embedded in npm.
-  const configuredClientId = process.env.ADRATA_MCP_CLIENT_ID?.trim();
   let registration;
   try {
-    registration = configuredClientId
-      ? { clientId: configuredClientId, tokenEndpointAuthMethod: 'none' }
-      : await registerNativeClient(apiBase, fetch, [callbackServer.redirectUri], requestedScope);
+    registration = await registrationForConnection({
+      apiBase,
+      redirectUris: [callbackServer.redirectUri],
+      requestedScope,
+    });
   } catch (error) {
     callbackServer.close();
     throw error;
   }
   const clientId = registration.clientId;
+  const authorizationScope = registration.scope || requestedScope;
   const authUrl = buildAuthUrl(
     apiBase,
     clientId,
     callbackServer.redirectUri,
     state,
     pkce,
-    requestedScope,
+    authorizationScope,
   ).url;
 
   if (process.env.ADRATA_MCP_PRINT_AUTH_URL === '1') {
@@ -948,11 +1038,11 @@ export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
     // The SERVER's granted scope wins. If the authorization server narrows the
     // grant (unregistered client scope, consent declined), the stored scope
     // must reflect what was actually granted -- never what we asked for.
-    scope: tokenResult.scope || requestedScope,
+    scope: tokenResult.scope || authorizationScope,
     clientId,
-    clientRegistration: configuredClientId ? 'configured' : 'dynamic',
+    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`;

package/access/tiers.js

@@ -100,6 +100,26 @@ export const TOOL_TIERS = {
   list_overdue_actions: TIERS.PRO,
   list_today_actions: TIERS.PRO,
   list_notes: TIERS.PRO,
+
+  // --- The nine spaces, as read surfaces ---
+  //
+  // Every one of these is a READ over data a seller can already see in the app, so they sit at
+  // PRO alongside the record reads they summarise. None mutates anything; the writes behind these
+  // surfaces (a stage move, an edit) go through the existing governed tools rather than getting a
+  // second, laxer door here.
+  //
+  // list_spaces is the map of what a workspace can actually open, so it answers the same question
+  // the chooser does and is deliberately the cheapest call in the set.
+  list_spaces: TIERS.PRO,
+  get_pipeline_board: TIERS.PRO,
+  get_calendar_agenda: TIERS.PRO,
+  get_customer_health: TIERS.PRO,
+  get_market_overview: TIERS.PRO,
+  list_content_files: TIERS.PRO,
+  // Finance and the connector estate describe the WORKSPACE rather than a seller's book, so they
+  // sit with the other administrative reads: an operator question, not a selling one.
+  get_finance_overview: TIERS.ENTERPRISE,
+  list_workspace_connectors: TIERS.ENTERPRISE,
   log_interaction: TIERS.PRO,
 
   // --- ENTERPRISE tier: CRM CRUD, sequences, campaigns, admin, bulk ---
@@ -166,6 +186,9 @@ export const TOOL_TIERS = {
   adrata_api_request: TIERS.ENTERPRISE,
   adrata_ai_tool_catalog: TIERS.ENTERPRISE,
   adrata_ai_tool_execute: TIERS.ENTERPRISE,
+  search_capabilities: TIERS.ENTERPRISE,
+  describe_capability: TIERS.ENTERPRISE,
+  run_capability: TIERS.ENTERPRISE,
   // Sloan (AI executive assistant) — same governed dispatcher path as
   // adrata_ai_tool_execute, so same tier.
   sloan_status: TIERS.ENTERPRISE,
@@ -195,18 +218,30 @@ export const TOOL_TIERS = {
   // the tool — only exists on an OAuth token.
   list_my_work_items: TIERS.ENTERPRISE,
   list_work_boards: TIERS.ENTERPRISE,
+  get_work_item_delivery_evidence: TIERS.ENTERPRISE,
+  audit_work_hub: TIERS.ENTERPRISE,
+  list_work_item_acceptance_criteria: TIERS.ENTERPRISE,
   get_work_board: TIERS.ENTERPRISE,
   get_work_item: TIERS.ENTERPRISE,
   get_work_item_history: TIERS.ENTERPRISE,
   get_work_item_comments: TIERS.ENTERPRISE,
   get_work_board_rollup: TIERS.ENTERPRISE,
   list_work_board_rollups: TIERS.ENTERPRISE,
+  set_work_board_archived: TIERS.ENTERPRISE,
+  set_work_board_column_wip_limit: TIERS.ENTERPRISE,
   move_work_item: TIERS.ENTERPRISE,
   set_work_item_tag: TIERS.ENTERPRISE,
   set_work_item_kind: TIERS.ENTERPRISE,
   create_work_item: TIERS.ENTERPRISE,
+  add_work_item_acceptance_criterion: TIERS.ENTERPRISE,
+  satisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,
+  unsatisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,
   comment_on_work_item: TIERS.ENTERPRISE,
   flag_work_item: TIERS.ENTERPRISE,
+  // The containers above the cards, and the "add this to the roadmap" verb.
+  // Same reasoning as every board tool: scopes are real workspace records.
+  list_work_scopes: TIERS.ENTERPRISE,
+  add_to_roadmap: TIERS.ENTERPRISE,
 
   // --- ENTERPRISE tier: Paper desktop app surfaces ---
   paper_list_documents: TIERS.ENTERPRISE,