@browserstack/mcp-server 1.5.1-beta.2 → 2.0.0-beta.1

package/dist/lib/central-oauth.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Mint a BrowserStack central-OAuth JWT from the caller's username and access key.
+ *
+ * WHAT IS MINTED IS THE CALLER, NOT A SERVICE ACCOUNT. The exchange takes the user's own
+ * credentials and returns a JWT whose `user` claim carries their `user_id`/`group_id`, so a
+ * product authorises against signed claims rather than against anything we put in a request
+ * body. Scopes narrow it further. The property this preserves is the one the whole surface
+ * rests on: an agent can never do what the user could not.
+ *
+ * SECRET HYGIENE IS THE WHOLE POINT OF THIS MODULE, and Atlas's `central_oauth.py` learned
+ * it the hard way: "The body can echo the credential back on some errors, so it is NOT
+ * logged or raised — only the status." Neither the access key nor the minted token is ever
+ * logged, returned in an error, or put in a message. Only a status code is.
+ *
+ * THIS MODULE IS THE MECHANISM AND NOTHING ELSE. It throws `CentralAuthError` carrying a
+ * `kind`, and each caller words its own message from that: `ask-browserstack` tells the
+ * reader nothing reached the agent, the capability registry tells them which product could
+ * not be reached. Sharing the mechanism is what stops a second, subtly different minter
+ * existing; sharing the prose would put Atlas's wording in front of a registry user.
+ */
+export interface Credentials {
+    username: string;
+    accessKey: string;
+}
+export interface TokenResponse {
+    status: number;
+    body: unknown;
+    /** Only when there was no response at all to speak for itself. */
+    error?: string;
+}
+export type TokenTransport = (url: string, form: Record<string, string>) => Promise<TokenResponse>;
+/** What we ask for. The endpoint clamps to its own maximum, so the response wins. */
+export declare const REQUESTED_EXPIRES_IN = 3600;
+/**
+ * The token endpoint gets its own, short budget — it is not the call being made.
+ *
+ * READ AT CALL TIME, NEVER IN A DEFAULT PARAMETER — see `fetchTokenTransport`.
+ */
+export declare const TOKEN_TIMEOUT_MS = 15000;
+/**
+ * How a mint failed, in the terms a reader can act on.
+ *
+ * `refused_scope` is a provisioning problem, `refused_credentials` is "your password is
+ * wrong", `server_error` is "auth is down" and `unreachable` is "we could not get there".
+ * Four different fixes, so they must not collapse into one — routing a 503 to "your
+ * credentials were rejected" has already sent someone to audit env vars that had worked
+ * minutes earlier.
+ */
+export type AuthFailureKind = "no_credentials" | "unreachable" | "server_error" | "refused_scope" | "refused_credentials" | "unusable";
+/** Carries the classification and the status. NEVER any part of the response body. */
+export declare class CentralAuthError extends Error {
+    readonly kind: AuthFailureKind;
+    readonly status: number;
+    readonly scope: string;
+    constructor(kind: AuthFailureKind, status: number, scope: string);
+}
+/**
+ * Was this refusal about the SCOPE or about the CREDENTIAL?
+ *
+ * The two need completely different fixes — provisioning versus a password — so collapsing
+ * them into one message sends someone to the wrong place entirely. Our form has five fields
+ * and four of them are constants, so a refusal of the REQUEST (as opposed to the caller) can
+ * only really be about the scope.
+ *
+ * Nothing from the body is ever surfaced; the code is used to classify and then discarded.
+ */
+export declare function refusalIsAboutScope(status: number, body: unknown): boolean;
+/**
+ * One canonical string for a scope set.
+ *
+ * `["a","b"]` and `["b","a"]` are the same grant, and without this they are two cache keys
+ * and two mints for it. Sorted and deduped so the key is a property of the grant rather
+ * than of how someone happened to write it down.
+ */
+export declare function normaliseScopes(scopes: readonly string[]): string;
+/** The exact form body of the `client_credentials` grant. */
+export declare function mintForm(credentials: Credentials, scope: string, expiresIn?: number): Record<string, string>;
+/**
+ * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
+ *
+ * `raise_error: false` keeps the status-first contract this transport has always had: the
+ * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
+ * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
+ *
+ * `timeoutMs` IS RESOLVED INSIDE THE CLOSURE, NOT AS A DEFAULT PARAMETER, and that is load
+ * bearing.
+ *
+ * This module sits inside an import cycle — `lib/apiClient` -> `lib/utils` -> `src/index`,
+ * the entry — so its top-level bindings are evaluated AFTER the entry starts running. Tool
+ * registration calls `fetchTokenTransport()` during that window: the function itself is
+ * hoisted and callable, but a default parameter reading `TOKEN_TIMEOUT_MS` is still in its
+ * temporal dead zone and threw `Cannot access 'TOKEN_TIMEOUT_MS' before initialization` on
+ * every server start. Reading it when a token is actually minted defers it past init.
+ *
+ * Anything else added here must follow the same rule until that cycle is broken.
+ */
+export declare function fetchTokenTransport(timeoutMs?: number): TokenTransport;
+/** Drop every cached token. For tests, and for a credential rotation. */
+export declare function resetTokenCache(): void;
+export interface MintOptions {
+    url: string;
+    /** Already normalised — `normaliseScopes` at the edge, not here. */
+    scope: string;
+    credentials: Credentials;
+    transport: TokenTransport;
+    /**
+     * Treat a token as stale this long before it actually expires.
+     *
+     * It must cover everything the token has to outlive, not merely clock skew: a caller that
+     * holds it for the length of a run needs a skew at least that long, or a human approves a
+     * write and the egress that follows fails on an expired credential.
+     */
+    refreshSkewMs: number;
+    /**
+     * False in a multi-tenant process. These are per-user attested credentials and the hosted
+     * process is shared by every tenant — `rules/multi-tenant-safety.md` forbids holding user
+     * data in module-level state there, so hosted mode mints per call. The cache key already
+     * means one user can never be SERVED another's token, but containment is not the
+     * contract; not holding it at all is.
+     */
+    cacheEnabled: boolean;
+    onMinted?: (lifetimeMs: number) => void;
+    now?: number;
+}
+/**
+ * Return a valid token, minting one only when the cache has nothing fresh.
+ *
+ * Minting per call would add a round trip to every request and make the token endpoint a hot
+ * dependency of the whole surface.
+ */
+export declare function mintCentralToken(options: MintOptions): Promise<string>;
+/** Drop the cached token for exactly these credentials — used after an upstream 401. */
+export declare function invalidateToken(url: string, scope: string, credentials: Credentials): void;

package/dist/lib/central-oauth.js

@@ -0,0 +1,246 @@
+/**
+ * Mint a BrowserStack central-OAuth JWT from the caller's username and access key.
+ *
+ * WHAT IS MINTED IS THE CALLER, NOT A SERVICE ACCOUNT. The exchange takes the user's own
+ * credentials and returns a JWT whose `user` claim carries their `user_id`/`group_id`, so a
+ * product authorises against signed claims rather than against anything we put in a request
+ * body. Scopes narrow it further. The property this preserves is the one the whole surface
+ * rests on: an agent can never do what the user could not.
+ *
+ * SECRET HYGIENE IS THE WHOLE POINT OF THIS MODULE, and Atlas's `central_oauth.py` learned
+ * it the hard way: "The body can echo the credential back on some errors, so it is NOT
+ * logged or raised — only the status." Neither the access key nor the minted token is ever
+ * logged, returned in an error, or put in a message. Only a status code is.
+ *
+ * THIS MODULE IS THE MECHANISM AND NOTHING ELSE. It throws `CentralAuthError` carrying a
+ * `kind`, and each caller words its own message from that: `ask-browserstack` tells the
+ * reader nothing reached the agent, the capability registry tells them which product could
+ * not be reached. Sharing the mechanism is what stops a second, subtly different minter
+ * existing; sharing the prose would put Atlas's wording in front of a registry user.
+ */
+import { createHash } from "node:crypto";
+import { apiClient } from "./apiClient.js";
+/** What we ask for. The endpoint clamps to its own maximum, so the response wins. */
+export const REQUESTED_EXPIRES_IN = 3600;
+/**
+ * The token endpoint gets its own, short budget — it is not the call being made.
+ *
+ * READ AT CALL TIME, NEVER IN A DEFAULT PARAMETER — see `fetchTokenTransport`.
+ */
+export const TOKEN_TIMEOUT_MS = 15_000;
+/** Carries the classification and the status. NEVER any part of the response body. */
+export class CentralAuthError extends Error {
+    kind;
+    status;
+    scope;
+    constructor(kind, status, scope) {
+        super(`central auth ${kind} (HTTP ${status})`);
+        this.kind = kind;
+        this.status = status;
+        this.scope = scope;
+        this.name = "CentralAuthError";
+    }
+}
+/**
+ * The OAuth2 error codes we are willing to read out of a failure body.
+ *
+ * `error` is a fixed enum token in the spec, so it cannot carry a credential;
+ * `error_description` is free text and demonstrably CAN ("access_key <key> is invalid"),
+ * which is why only the code is ever looked at and only when it is one of these. Anything
+ * else is ignored entirely and the classification falls back to the status.
+ */
+const SCOPE_ERROR_CODES = [
+    "invalid_scope",
+    "unauthorized_client",
+    "invalid_request",
+];
+const CREDENTIAL_ERROR_CODES = [
+    "invalid_client",
+    "invalid_grant",
+    "access_denied",
+];
+/**
+ * Was this refusal about the SCOPE or about the CREDENTIAL?
+ *
+ * The two need completely different fixes — provisioning versus a password — so collapsing
+ * them into one message sends someone to the wrong place entirely. Our form has five fields
+ * and four of them are constants, so a refusal of the REQUEST (as opposed to the caller) can
+ * only really be about the scope.
+ *
+ * Nothing from the body is ever surfaced; the code is used to classify and then discarded.
+ */
+export function refusalIsAboutScope(status, body) {
+    const payload = typeof body === "object" && body !== null
+        ? body
+        : {};
+    const code = typeof payload.error === "string" ? payload.error : "";
+    if (SCOPE_ERROR_CODES.includes(code))
+        return true;
+    if (CREDENTIAL_ERROR_CODES.includes(code))
+        return false;
+    // No usable code. OAuth2 answers a bad REQUEST with 400 and a bad CLIENT with 401/403, so
+    // the status is the next best evidence.
+    return status === 400;
+}
+/**
+ * One canonical string for a scope set.
+ *
+ * `["a","b"]` and `["b","a"]` are the same grant, and without this they are two cache keys
+ * and two mints for it. Sorted and deduped so the key is a property of the grant rather
+ * than of how someone happened to write it down.
+ */
+export function normaliseScopes(scopes) {
+    return [
+        ...new Set(scopes.flatMap((scope) => scope.split(/\s+/)).filter(Boolean)),
+    ]
+        .sort()
+        .join(" ");
+}
+/** The exact form body of the `client_credentials` grant. */
+export function mintForm(credentials, scope, expiresIn = REQUESTED_EXPIRES_IN) {
+    return {
+        grant_type: "client_credentials",
+        username: credentials.username,
+        access_key: credentials.accessKey,
+        scope,
+        expires_in: String(expiresIn),
+    };
+}
+/**
+ * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
+ *
+ * `raise_error: false` keeps the status-first contract this transport has always had: the
+ * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
+ * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
+ *
+ * `timeoutMs` IS RESOLVED INSIDE THE CLOSURE, NOT AS A DEFAULT PARAMETER, and that is load
+ * bearing.
+ *
+ * This module sits inside an import cycle — `lib/apiClient` -> `lib/utils` -> `src/index`,
+ * the entry — so its top-level bindings are evaluated AFTER the entry starts running. Tool
+ * registration calls `fetchTokenTransport()` during that window: the function itself is
+ * hoisted and callable, but a default parameter reading `TOKEN_TIMEOUT_MS` is still in its
+ * temporal dead zone and threw `Cannot access 'TOKEN_TIMEOUT_MS' before initialization` on
+ * every server start. Reading it when a token is actually minted defers it past init.
+ *
+ * Anything else added here must follow the same rule until that cycle is broken.
+ */
+export function fetchTokenTransport(timeoutMs) {
+    return async (url, form) => {
+        try {
+            const response = await apiClient.post({
+                url,
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: new URLSearchParams(form).toString(),
+                timeout: timeoutMs ?? TOKEN_TIMEOUT_MS,
+                raise_error: false,
+            });
+            return { status: response.status, body: response.data ?? null };
+        }
+        catch {
+            // DNS, TLS, timeout — all of them mean "no token". The reason is deliberately not
+            // carried: it can name the URL and, on some stacks, echo the request body.
+            return { status: 0, body: null, error: "auth could not be reached" };
+        }
+    };
+}
+const cache = new Map();
+/** Drop every cached token. For tests, and for a credential rotation. */
+export function resetTokenCache() {
+    cache.clear();
+}
+/**
+ * The cache key.
+ *
+ * Every part of it is something that changes WHICH token is correct:
+ *
+ *   url      a different issuer is a different token
+ *   scope    a token minted for one scope set must never be served for another
+ *   username the identity the JWT attests
+ *   digest   so ROTATING the access key mints immediately rather than leaving a revoked
+ *            credential working until expiry — hashed, never the value, so the secret is
+ *            not left sitting in a map key for the life of the process
+ *
+ * The PRODUCT is deliberately absent: the token is the caller's identity, not a product's,
+ * so two products on the same endpoint and scopes share one mint.
+ */
+function cacheKey(url, scope, credentials) {
+    const digest = createHash("sha256")
+        .update(credentials.accessKey)
+        .digest("hex");
+    return `${url} ${credentials.username} ${scope} ${digest}`;
+}
+async function mintOnce(url, scope, credentials, transport) {
+    const response = await transport(url, mintForm(credentials, scope));
+    if (response.status === 0)
+        throw new CentralAuthError("unreachable", 0, scope);
+    // 5xx BEFORE the refusal branch: a server error is not a refusal, and reading it as one
+    // is worse than saying nothing — it names the caller's credentials as the fault.
+    if (response.status >= 500)
+        throw new CentralAuthError("server_error", response.status, scope);
+    if (response.status !== 200) {
+        // ONLY THE STATUS CROSSES. The body is read solely to tell a provisioning problem from a
+        // credential one, and nothing out of it is ever put in the error.
+        throw new CentralAuthError(refusalIsAboutScope(response.status, response.body)
+            ? "refused_scope"
+            : "refused_credentials", response.status, scope);
+    }
+    const body = typeof response.body === "object" && response.body !== null
+        ? response.body
+        : {};
+    const token = body.access_token;
+    if (typeof token !== "string" || !token)
+        throw new CentralAuthError("unusable", response.status, scope);
+    // Trust the SERVER's lifetime over what we asked for — it clamps to its own maximum, and
+    // caching for the requested hour when it granted less would hand out a dead token.
+    const granted = Number(body.expires_in);
+    const seconds = Number.isFinite(granted) && granted > 0 ? granted : REQUESTED_EXPIRES_IN;
+    return { token, lifetimeMs: seconds * 1000 };
+}
+/**
+ * Return a valid token, minting one only when the cache has nothing fresh.
+ *
+ * Minting per call would add a round trip to every request and make the token endpoint a hot
+ * dependency of the whole surface.
+ */
+export async function mintCentralToken(options) {
+    const { url, scope, credentials, transport, cacheEnabled } = options;
+    const now = options.now ?? Date.now();
+    // Refused before any network call, and by name: these ARE the auth credential now, not
+    // merely attribution, so an empty one is our missing configuration rather than the user's
+    // rejected password, and must not read like one.
+    if (!credentials?.username || !credentials?.accessKey)
+        throw new CentralAuthError("no_credentials", 0, scope);
+    const finish = ({ token, lifetimeMs, }) => {
+        options.onMinted?.(lifetimeMs);
+        return token;
+    };
+    if (!cacheEnabled)
+        return mintOnce(url, scope, credentials, transport).then(finish);
+    const key = cacheKey(url, scope, credentials);
+    const entry = cache.get(key);
+    if (entry && entry.token && now < entry.expiresAt - options.refreshSkewMs)
+        return entry.token;
+    // Double-checked through a shared promise: concurrent callers await the same mint.
+    if (entry?.inflight)
+        return entry.inflight;
+    const pending = mintOnce(url, scope, credentials, transport)
+        .then(({ token, lifetimeMs }) => {
+        cache.set(key, { token, expiresAt: now + lifetimeMs });
+        return finish({ token, lifetimeMs });
+    })
+        .catch((error) => {
+        // Never leave a rejected promise cached, or every later call inherits this failure.
+        cache.delete(key);
+        throw error;
+    });
+    cache.set(key, { token: "", expiresAt: 0, inflight: pending });
+    return pending;
+}
+/** Drop the cached token for exactly these credentials — used after an upstream 401. */
+export function invalidateToken(url, scope, credentials) {
+    cache.delete(cacheKey(url, scope, credentials));
+}

package/dist/lib/instrumentation.d.ts

@@ -3,12 +3,25 @@ export type ClientInfo = {
     version?: string;
 };
 export type ToolOutcome = "ok" | "error_result" | "threw";
+/**
+ * Extra fields a caller may attach to its own row (the capability registry records what
+ * it invoked and how the product answered). Values are scalars so every field stays one
+ * queryable column.
+ *
+ * SOME OF IT IS FREE TEXT, and this comment used to claim the opposite. The registry
+ * records `search_query` and `change_summary`, both written by the agent from what the
+ * user asked for, and both leave the machine on every search and every write. They go
+ * through `capability-registry/redact.ts` first, which strips PII it can identify by
+ * SHAPE and caps the length — it cannot strip a person's name, and says so. Anything
+ * added here that carries user text must go through the same filter.
+ */
+export type MCPEventExtras = Record<string, string | number | boolean | undefined>;
 /**
  * Inside `withToolCall` this only records into the call's context; the single row is
  * written when the handler settles. Outside one (`started` heartbeat, unwrapped host
  * tools) it posts a row immediately, as before.
  */
-export declare function trackMCP(toolName: string, clientInfo: ClientInfo, error?: unknown, config?: any): void;
+export declare function trackMCP(toolName: string, clientInfo: ClientInfo, error?: unknown, config?: any, extras?: MCPEventExtras): void;
 /**
  * Runs a tool handler and writes one MCPInstrumentation row when it settles: success,
  * duration_ms, outcome (ok / error_result / threw), error fields on failure.

package/dist/lib/instrumentation.js

@@ -47,7 +47,7 @@ const callContext = new AsyncLocalStorage();
  * written when the handler settles. Outside one (`started` heartbeat, unwrapped host
  * tools) it posts a row immediately, as before.
  */
-export function trackMCP(toolName, clientInfo, error, config) {
+export function trackMCP(toolName, clientInfo, error, config, extras) {
     const ctx = callContext.getStore();
     if (ctx) {
         if (clientInfo?.name && !ctx.clientInfo?.name)
@@ -56,6 +56,9 @@ export function trackMCP(toolName, clientInfo, error, config) {
             ctx.config = config;
         if (error)
             ctx.error = error;
+        // Later calls win, so a handler can record an identity first and the outcome after.
+        if (extras)
+            ctx.extras = { ...ctx.extras, ...extras };
         return;
     }
     if (clientInfo?.name) {
@@ -70,6 +73,9 @@ export function trackMCP(toolName, clientInfo, error, config) {
             ...baseProperties(toolName, clientInfo),
             success: !error,
             ...(error ? errorProperties(error) : {}),
+            // Undefined entries are dropped by JSON.stringify, so an absent extra is an
+            // absent column rather than a null one.
+            ...(extras ?? {}),
         },
     };
     sendEvent(event, config);
@@ -117,6 +123,7 @@ export async function withToolCall(toolName, getClientInfo, config, fn) {
                     duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
                     outcome,
                     ...(ctx.error !== undefined ? errorProperties(ctx.error) : {}),
+                    ...(ctx.extras ?? {}),
                 },
             };
             sendEvent(event, ctx.config ?? config);

package/dist/server-factory.js

@@ -17,6 +17,7 @@ import addBuildInsightsTools from "./tools/build-insights.js";
 import { setupOnInitialized } from "./oninitialized.js";
 import addRCATools from "./tools/rca-agent.js";
 import addAskBrowserStackAITool from "./tools/ask-browserstack/register.js";
+import addCapabilityRegistryTools from "./tools/capability-registry/register.js";
 import { instrumentToolLatency } from "./lib/tool-latency.js";
 import { nodeUpgradeNotice } from "./lib/node-version-notice.js";
 /**
@@ -58,6 +59,10 @@ export class BrowserStackMcpServer {
             // permission asks back to this client, so a write can be confirmed by the human
             // sitting in front of it rather than refused for want of anyone to ask.
             addAskBrowserStackAITool,
+            // Driven by a prebuilt index rather than hand-written per endpoint. Registers
+            // nothing (and logs why) when the artifact is absent, so a packaging problem cannot
+            // take the other products' tools down with it.
+            addCapabilityRegistryTools,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

package/dist/tools/ask-browserstack/central-oauth.d.ts

@@ -1,5 +1,15 @@
 /**
- * Mint a BrowserStack central-OAuth JWT from the caller's username and access key.
+ * Atlas's view of the central-OAuth mint.
+ *
+ * The MECHANISM — the form, the transport, the classification, the cache — moved to
+ * `src/lib/central-oauth.ts` when the capability registry needed the same exchange for
+ * products whose APIs take a Bearer JWT rather than `Api-Token`. Two minters would have
+ * drifted, and the one that drifted would have been the one with fewer tests.
+ *
+ * What stays here is everything ATLAS-SPECIFIC and nothing else: the scope pair, the skew
+ * that exists because Atlas holds the token for a whole run, and the messages — which say
+ * "nothing reached the agent" and name `ai_agent_notify`, and would be actively wrong in
+ * front of a capability-registry user.
  *
  * This replaces a shared delegation token, and the upgrade is not cosmetic.
  * `validate_delegation_token` refuses any token without `user.user_id`/`user.group_id`, so
@@ -7,20 +17,17 @@
  * user from signed claims rather than from anything we put in the request body, and reuses
  * this same JWT as its `egress_token` — so the product call a human approves runs as that
  * human, not as a shared service account.
- *
- * SECRET HYGIENE IS THE WHOLE POINT OF THIS MODULE, and Atlas's `central_oauth.py` learned
- * it the hard way: "The body can echo the credential back on some errors, so it is NOT
- * logged or raised — only the status." Neither the access key nor the minted token is ever
- * logged, returned, or put in an error message. Only a status code is.
  */
-import { Credentials } from "./egress.js";
+import { Credentials, mintCentralToken as mintShared } from "../../lib/central-oauth.js";
+export { fetchTokenTransport, refusalIsAboutScope, REQUESTED_EXPIRES_IN, resetTokenCache, TOKEN_TIMEOUT_MS, type TokenResponse, type TokenTransport, } from "../../lib/central-oauth.js";
 /**
  * BOTH PARTS ARE REQUIRED, AND THERE IS NO FALLBACK TO ANOTHER SCOPE.
  *
  * `oauth_user_profile` stays because it is what makes the pair obtainable through the
- * username+access_key flow at all. `ai_agent_notify` is what Atlas matches on
- * (`delegation.required_scope`, checked as exact membership of the token's `scopes` claim in
- * `web/oauth.py`); both halves move together with Atlas.
+ * username+access_key flow at all — measured, not assumed: the paired scope mints, and the
+ * other half alone comes back `400 invalid_request`. `ai_agent_notify` is what Atlas matches
+ * on (`delegation.required_scope`, checked as exact membership of the token's `scopes` claim
+ * in `web/oauth.py`); both halves move together with Atlas.
  *
  * THIS SCOPE MAY SIMPLY NOT BE ISSUABLE TO US, and the reasons are worth stating rather than
  * discovering. From the merged `browserstack/railsApp#175367` (2026-08-24):
@@ -42,10 +49,11 @@ import { Credentials } from "./egress.js";
  * application — and it is reported as one, naming the scope. It is never retried with a
  * different scope: a silent downgrade to a different authorization is exactly the kind of
  * thing nobody notices until it matters.
+ *
+ * Named here rather than taken from the shared default, so that changing the registry's
+ * scopes can never silently change what Atlas is authorised for.
  */
 export declare const CENTRAL_SCOPE = "oauth_user_profile ai_agent_notify";
-/** What we ask for. The endpoint clamps to its own maximum, so the response wins. */
-export declare const REQUESTED_EXPIRES_IN = 3600;
 /**
  * Treat a token as stale this long before it actually expires.
  *
@@ -56,26 +64,6 @@ export declare const REQUESTED_EXPIRES_IN = 3600;
  * expired credential, which is the exact mid-flight expiry this cache exists to prevent.
  */
 export declare const REFRESH_SKEW_MS: number;
-/** The token endpoint gets its own, much shorter budget than `/agent`. */
-export declare const TOKEN_TIMEOUT_MS = 15000;
-export interface TokenResponse {
-    status: number;
-    body: unknown;
-    /** Only when there was no response at all to speak for itself. */
-    error?: string;
-}
-export type TokenTransport = (url: string, form: Record<string, string>) => Promise<TokenResponse>;
-/**
- * Was this refusal about the SCOPE or about the CREDENTIAL?
- *
- * The two need completely different fixes — provisioning versus a password — so collapsing
- * them into one message sends someone to the wrong place entirely. Our form has five fields
- * and four of them are constants, so a refusal of the REQUEST (as opposed to the caller) can
- * only really be about the scope.
- *
- * Nothing from the body is ever surfaced; the code is used to classify and then discarded.
- */
-export declare function refusalIsAboutScope(status: number, body: unknown): boolean;
 /**
  * The ways authentication can fail, kept apart because a user cannot act on them otherwise.
  *
@@ -99,22 +87,13 @@ export declare const AUTH_UNREACHABLE_DETAIL: string;
  */
 export declare const AUTH_SERVER_ERROR_DETAIL: (status: number) => string;
 export declare const AUTH_UNUSABLE_DETAIL: (status: number) => string;
-/** Drop every cached token. For tests, and for a credential rotation. */
-export declare function resetTokenCache(): void;
-/**
- * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
- *
- * `raise_error: false` keeps the status-first contract this transport has always had: the
- * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
- * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
- */
-export declare function fetchTokenTransport(timeoutMs?: number): TokenTransport;
-/** The exact form body of the `client_credentials` grant. */
+/** The exact form body of the `client_credentials` grant, at Atlas's scope. */
 export declare function mintForm(credentials: Credentials): Record<string, string>;
 /**
  * Return a valid token, minting one only when the cache has nothing fresh.
  *
- * Minting per tool call would add a round trip to every request and make the token endpoint
- * a hot dependency of the whole surface.
+ * NOT CACHED IN HOSTED MODE. These tokens are per-user, attested credentials, and the
+ * process is shared by every tenant — `rules/multi-tenant-safety.md` forbids holding user
+ * data in module-level state there, so remote mode mints per call.
  */
-export declare function mintCentralToken(url: string, credentials: Credentials, transport: TokenTransport, now?: number): Promise<string>;
+export declare function mintCentralToken(url: string, credentials: Credentials, transport: Parameters<typeof mintShared>[0]["transport"], now?: number): Promise<string>;