@browserstack/mcp-server 2.2.0 → 2.2.1-beta.1

package/dist/tools/ask-browserstack/central-oauth.js

@@ -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,24 +17,20 @@
  * 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 { createHash } from "node:crypto";
-import { apiClient } from "../../lib/apiClient.js";
+import { CentralAuthError, mintCentralToken as mintShared, mintForm as mintFormShared, REQUESTED_EXPIRES_IN, } from "../../lib/central-oauth.js";
 import appConfig from "../../config.js";
 import logger from "../../logger.js";
 import { AGENT_TIMEOUT_MS, AskError } from "./config.js";
+export { fetchTokenTransport, refusalIsAboutScope, REQUESTED_EXPIRES_IN, resetTokenCache, TOKEN_TIMEOUT_MS, } 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):
@@ -46,10 +52,11 @@ import { AGENT_TIMEOUT_MS, AskError } from "./config.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 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 const REQUESTED_EXPIRES_IN = 3600;
 /**
  * Treat a token as stale this long before it actually expires.
  *
@@ -60,49 +67,6 @@ export const REQUESTED_EXPIRES_IN = 3600;
  * expired credential, which is the exact mid-flight expiry this cache exists to prevent.
  */
 export const REFRESH_SKEW_MS = AGENT_TIMEOUT_MS + 60_000;
-/** The token endpoint gets its own, much shorter budget than `/agent`. */
-export const TOKEN_TIMEOUT_MS = 15_000;
-/**
- * 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;
-}
 /**
  * The ways authentication can fail, kept apart because a user cannot act on them otherwise.
  *
@@ -141,137 +105,51 @@ export const AUTH_SERVER_ERROR_DETAIL = (status) => `BrowserStack auth is unavai
     `BrowserStack auth is back.`;
 export const AUTH_UNUSABLE_DETAIL = (status) => `BrowserStack auth answered HTTP ${status} without issuing a token. NOTHING REACHED THE ` +
     `AGENT — no request was made, no prompt appeared and nothing was changed.`;
-const cache = new Map();
-/** Drop every cached token. For tests, and for a credential rotation. */
-export function resetTokenCache() {
-    cache.clear();
-}
-/**
- * The cache key.
- *
- * Keyed on the access key so that ROTATING it mints immediately rather than leaving a
- * revoked credential working until expiry — but on a SHA-256 of it, never the value, so the
- * secret is not left sitting in a map key for the life of the process.
- */
-function cacheKey(url, credentials) {
-    const digest = createHash("sha256")
-        .update(credentials.accessKey)
-        .digest("hex");
-    return `${url} ${credentials.username} ${CENTRAL_SCOPE} ${digest}`;
-}
-/**
- * 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 function fetchTokenTransport(timeoutMs = TOKEN_TIMEOUT_MS) {
-    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,
-                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" };
-        }
-    };
-}
-/** The exact form body of the `client_credentials` grant. */
+/** The exact form body of the `client_credentials` grant, at Atlas's scope. */
 export function mintForm(credentials) {
-    return {
-        grant_type: "client_credentials",
-        username: credentials.username,
-        access_key: credentials.accessKey,
-        scope: CENTRAL_SCOPE,
-        expires_in: String(REQUESTED_EXPIRES_IN),
-    };
+    return mintFormShared(credentials, CENTRAL_SCOPE, REQUESTED_EXPIRES_IN);
 }
-async function mintOnce(url, credentials, transport) {
-    const response = await transport(url, mintForm(credentials));
-    if (response.status === 0)
-        throw new AskError(AUTH_UNREACHABLE_DETAIL);
-    // 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 AskError(AUTH_SERVER_ERROR_DETAIL(response.status));
+/** Every failure kind gets Atlas's own sentence; none of them carries the response body. */
+function toAskError(error) {
+    if (!(error instanceof CentralAuthError))
+        return error;
+    switch (error.kind) {
+        case "no_credentials":
+            return new AskError("BrowserStack AI is not authenticated: BROWSERSTACK_USERNAME and " +
+                "BROWSERSTACK_ACCESS_KEY are required to sign in");
+        case "unreachable":
+            return new AskError(AUTH_UNREACHABLE_DETAIL);
+        case "server_error":
+            return new AskError(AUTH_SERVER_ERROR_DETAIL(error.status));
+        case "refused_scope":
+            return new AskError(AUTH_SCOPE_REFUSED_DETAIL(error.status));
+        case "refused_credentials":
+            return new AskError(AUTH_REJECTED_DETAIL(error.status));
+        default:
+            return new AskError(AUTH_UNUSABLE_DETAIL(error.status));
     }
-    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 message — a non-200 body can
-        // echo the access key straight back.
-        throw new AskError(refusalIsAboutScope(response.status, response.body)
-            ? AUTH_SCOPE_REFUSED_DETAIL(response.status)
-            : AUTH_REJECTED_DETAIL(response.status));
-    }
-    const body = typeof response.body === "object" && response.body !== null
-        ? response.body
-        : {};
-    const token = body.access_token;
-    if (typeof token !== "string" || !token) {
-        throw new AskError(AUTH_UNUSABLE_DETAIL(response.status));
-    }
-    // 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 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 async function mintCentralToken(url, credentials, transport, 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 AskError("BrowserStack AI is not authenticated: BROWSERSTACK_USERNAME and " +
-            "BROWSERSTACK_ACCESS_KEY are required to sign in");
-    }
-    // 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. Keying on
-    // username + sha256(accessKey) already means one user can never be SERVED another's token,
-    // but containment is not the contract; not holding it at all is.
-    if (appConfig.REMOTE_MCP) {
-        return mintOnce(url, credentials, transport).then(({ token }) => {
-            logger.info("askBrowserStackAI: signed in as %s", credentials.username);
-            return token;
+    try {
+        return await mintShared({
+            url,
+            scope: CENTRAL_SCOPE,
+            credentials,
+            transport,
+            refreshSkewMs: REFRESH_SKEW_MS,
+            cacheEnabled: !appConfig.REMOTE_MCP,
+            now,
+            onMinted: (lifetimeMs) => logger.info("askBrowserStackAI: signed in as %s (lifetime %ss)", credentials.username, Math.round(lifetimeMs / 1000)),
         });
     }
-    const key = cacheKey(url, credentials);
-    const entry = cache.get(key);
-    if (entry && entry.token && now < entry.expiresAt - REFRESH_SKEW_MS) {
-        return entry.token;
+    catch (error) {
+        throw toAskError(error);
     }
-    // Double-checked through a shared promise: concurrent callers await the same mint.
-    if (entry?.inflight)
-        return entry.inflight;
-    const pending = mintOnce(url, credentials, transport)
-        .then(({ token, lifetimeMs }) => {
-        cache.set(key, { token, expiresAt: now + lifetimeMs });
-        logger.info("askBrowserStackAI: signed in as %s (lifetime %ss)", credentials.username, Math.round(lifetimeMs / 1000));
-        return token;
-    })
-        .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;
 }

package/dist/tools/capability-registry/bind.js

@@ -230,6 +230,15 @@ function coerceType(value, param, label = param.name) {
         if (expected === "integer" && !Number.isInteger(parsed)) {
             throw new InvocationError(`'${label}' must be a whole number, not ${JSON.stringify(raw)}`);
         }
+        // Past 2^53 `Number` rounds: TRA's 17-digit unique-error cluster ids came back as a
+        // neighbouring id, so the call silently targeted the wrong cluster. Keep the caller's
+        // exact digits instead — path and query serialise a string identically, and a JSON body
+        // carrying a digit string still binds to a Long on the server.
+        if (expected === "integer" &&
+            !Number.isSafeInteger(parsed) &&
+            /^-?\d+$/.test(raw)) {
+            return raw;
+        }
         return parsed;
     }
     if (expected === "boolean") {
@@ -280,6 +289,12 @@ function place(root, pointer, value) {
     }
     cursor[segments[segments.length - 1]] = value;
 }
+const MAP_KEY = /^[A-Za-z0-9][\w.-]*$/;
+function keyedParam(group, params) {
+    if (group !== "body")
+        return undefined;
+    return params.find((param) => /^\{\w+\}$/.test(param.name));
+}
 const GROUPS = [
     { group: "path_params", declared: "path_params" },
     { group: "query", declared: "query" },
@@ -298,9 +313,10 @@ export function bind(capability, args) {
         }
         const params = capability[declared] || [];
         const byName = new Map(params.map((param) => [param.name, param]));
+        const keyed = keyedParam(group, params);
         // Unknown arguments are an error rather than being dropped: silently ignoring a
         // misspelled filter would return a larger result set that looks like a correct answer.
-        const unknown = Object.keys(supplied).filter((name) => !byName.has(name));
+        const unknown = Object.keys(supplied).filter((name) => !byName.has(name) && !keyed);
         if (unknown.length > 0) {
             // A CALLER WHO SENT THE WRAPPER WE BUILD DESERVES TO BE TOLD SO.
             //
@@ -331,7 +347,10 @@ export function bind(capability, args) {
                     : ""));
         }
         for (const [name, raw] of Object.entries(supplied)) {
-            const param = byName.get(name);
+            const param = byName.get(name) ?? keyed;
+            if (param === keyed && !MAP_KEY.test(name)) {
+                throw new InvocationError(`'${name}' is not a usable ${keyed.name} key: use the id exactly as a read returned it`);
+            }
             const value = coerce(raw, param);
             if (group === "path_params") {
                 // Encode with nothing exempt: a `/` inside a path value would otherwise rewrite the
@@ -339,7 +358,10 @@ export function bind(capability, args) {
                 path = path.replaceAll(`{${name}}`, encodeURIComponent(pathSegment(value, name)));
             }
             else if (group === "body") {
-                place(body, param.json_path || `/${name}`, value);
+                const pointer = param.json_path || `/${param.name}`;
+                place(body, param === keyed && !byName.has(name)
+                    ? pointer.replace(keyed.name, name)
+                    : pointer, value);
             }
             else {
                 query[name] = value;
@@ -354,9 +376,14 @@ export function bind(capability, args) {
         if (group === "query")
             continue;
         const supplied = args[group] || {};
-        for (const param of capability[declared] ||
-            []) {
-            if (param.required && !(param.name in supplied))
+        const params = capability[declared] || [];
+        const keyed = keyedParam(group, params);
+        const declaredNames = new Set(params.map((param) => param.name));
+        for (const param of params) {
+            const present = param.name in supplied ||
+                (param === keyed &&
+                    Object.keys(supplied).some((name) => !declaredNames.has(name)));
+            if (param.required && !present)
                 missing.push(param.name);
         }
     }
@@ -367,5 +394,14 @@ export function bind(capability, args) {
     if (leftover) {
         throw new InvocationError(`path placeholder(s) not supplied: ${leftover.join(", ")}`);
     }
-    return { path, query, body: Object.keys(body).length > 0 ? body : undefined };
+    // An explicitly supplied empty body is still a body. Dropping it sent no request body at
+    // all, and a route with a required @RequestBody (TRA close_build, whose guidance says to
+    // send `{}`) answered 400 "Invalid request payload". GET/HEAD never carry one.
+    const sentEmptyBody = args.body !== undefined &&
+        !["GET", "HEAD"].includes(capability.method.toUpperCase());
+    return {
+        path,
+        query,
+        body: Object.keys(body).length > 0 || sentEmptyBody ? body : undefined,
+    };
 }

package/dist/tools/capability-registry/discovery.js

@@ -79,7 +79,9 @@ export async function discoverBaseUrl(product, source, credentials, transport) {
             `set probe_path in its index`);
     }
     // The same scheme the invocation will use, so a host that answers here answers there.
-    const headers = authHeaders(credentials, source.auth);
+    // Minted ONCE for the whole probe, not per candidate: the token is the caller's identity
+    // and does not vary by which region answers.
+    const headers = await authHeaders(credentials, source.auth, product);
     const failures = [];
     for (const candidate of candidates) {
         const response = await transport("GET", `${candidate}${path}`, headers, {});

package/dist/tools/capability-registry/egress.d.ts

@@ -16,11 +16,10 @@
  * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
  * credentials are wrong.
  */
+import { TokenTransport } from "../../lib/central-oauth.js";
 import { AuthScheme } from "./types.js";
-export interface Credentials {
-    username: string;
-    accessKey: string;
-}
+export type { Credentials } from "../../lib/central-oauth.js";
+import type { Credentials } from "../../lib/central-oauth.js";
 export interface HttpResponse {
     status: number;
     body: unknown;
@@ -39,6 +38,14 @@ export declare const DEFAULT_AUTH: AuthScheme;
  * the common case, not a hypothetical.
  */
 export declare function renderTemplate(template: string, credentials: Credentials): string;
-export declare function authHeaders(credentials: Credentials, auth?: AuthScheme): Record<string, string>;
+/**
+ * The headers for one outbound call.
+ *
+ * ASYNC BECAUSE ONE SCHEME NEEDS A ROUND TRIP. `apiKey` and `http` are pure string work, but
+ * `oauth2` exchanges the caller's credentials for a JWT before anything can be sent, and
+ * there was nowhere to put that while this was synchronous. Both call sites were already
+ * inside async functions, so the cost is two `await`s.
+ */
+export declare function authHeaders(credentials: Credentials, auth?: AuthScheme, product?: string, tokenTransport?: TokenTransport): Promise<Record<string, string>>;
 /** A fetch-based transport. Redirects are NOT followed. */
 export declare function fetchTransport(timeoutMs?: number): Transport;

package/dist/tools/capability-registry/egress.js

@@ -16,7 +16,9 @@
  * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
  * credentials are wrong.
  */
+import { fetchTokenTransport, } from "../../lib/central-oauth.js";
 import { InvocationError } from "./index-loader.js";
+import { bearerToken } from "./oauth.js";
 /** What this server can put into a credential template. Nothing else is fillable. */
 const PLACEHOLDERS = ["username", "access_key"];
 /** The historical default, and what an index without an `auth` block still gets. */
@@ -48,7 +50,15 @@ export function renderTemplate(template, credentials) {
         .replaceAll("{username}", credentials.username)
         .replaceAll("{access_key}", credentials.accessKey);
 }
-export function authHeaders(credentials, auth = DEFAULT_AUTH) {
+/**
+ * The headers for one outbound call.
+ *
+ * ASYNC BECAUSE ONE SCHEME NEEDS A ROUND TRIP. `apiKey` and `http` are pure string work, but
+ * `oauth2` exchanges the caller's credentials for a JWT before anything can be sent, and
+ * there was nowhere to put that while this was synchronous. Both call sites were already
+ * inside async functions, so the cost is two `await`s.
+ */
+export async function authHeaders(credentials, auth = DEFAULT_AUTH, product = "this product", tokenTransport = fetchTokenTransport()) {
     if (!credentials?.username || !credentials?.accessKey) {
         // Refusing here beats sending unauthenticated and surfacing the product's 401, which
         // reads like the user's problem when it is our missing configuration.
@@ -59,6 +69,19 @@ export function authHeaders(credentials, auth = DEFAULT_AUTH) {
         "request-source": "ai-chatbot",
         "Content-Type": "application/json",
     };
+    if (auth.type === "oauth2") {
+        // Refused rather than ignored, which is the same call `in: cookie` and `in: query` get
+        // below: a field that looks like it selects behaviour and does not is how someone
+        // spends an afternoon on a 401 they were never going to be able to explain.
+        const stray = ["in", "name", "template"].filter((field) => auth[field] !== undefined);
+        if (stray.length > 0) {
+            throw new InvocationError(`oauth2 auth does not take ${stray.join(", ")}: a bearer token's presentation is ` +
+                `fixed at 'Authorization: Bearer' (RFC 6750). Remove ${stray.length > 1 ? "them" : "it"}, ` +
+                `or use apiKey if this product really does read a different header.`);
+        }
+        const token = await bearerToken(product, auth, credentials, tokenTransport);
+        return { Authorization: `Bearer ${token}`, ...common };
+    }
     const value = renderTemplate(auth.template || DEFAULT_AUTH.template, credentials);
     if (auth.type === "apiKey") {
         // Header only. `cookie` needs a session this server does not have, and `query` would

package/dist/tools/capability-registry/oauth.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bearer-JWT auth for products whose API does not accept `Api-Token`.
+ *
+ * The registry was built on "the caller's credentials, forwarded — never a token this server
+ * mints", and this is the first product that cannot work that way. The security property is
+ * unchanged: the exchange uses the caller's own username and access key, the JWT carries
+ * their `user_id`/`group_id` as signed claims, and the scopes narrow it BELOW what the raw
+ * credential could do. What changes is that a token is now minted rather than formatted, so
+ * the sentence to hold onto is "the server grants nothing beyond the caller's own identity",
+ * not "the server mints nothing".
+ *
+ * The mint itself lives in `lib/central-oauth.ts` and is shared with `askBrowserStackAI`.
+ * This module is only the part that is the registry's: where the endpoint and scopes come
+ * from, what a product is allowed to ask for, and how a failure is worded.
+ */
+import { Credentials, TokenTransport } from "../../lib/central-oauth.js";
+import { AuthScheme } from "./types.js";
+/**
+ * Where a central-OAuth JWT is minted, when a product does not name its own.
+ *
+ * Staging, for anyone setting the override:
+ *   CAPABILITY_REGISTRY_AUTH_TOKEN_URL = https://auth-preprod.bsstag.com/oauth2/v2/token
+ */
+export declare const DEFAULT_AUTH_TOKEN_URL = "https://auth.browserstack.com/oauth2/v2/token";
+/**
+ * The default scope set, and why it is a PAIR.
+ *
+ * `ai_agent` is the scope a product's gate matches on. `oauth_user_profile` is not extra
+ * authority — it is what makes the scope obtainable through the username+access_key flow at
+ * all, and this is measured rather than assumed: `ai_agent` alone comes back
+ * `400 invalid_request`, the pair mints, and the granted token's `scopes` claim carries both.
+ *
+ * Deliberately NOT `ask-browserstack`'s `CENTRAL_SCOPE`, which pairs `ai_agent_notify`
+ * instead — Atlas names its own so that changing this one cannot silently change what Atlas
+ * is authorised for.
+ */
+export declare const DEFAULT_SCOPES: readonly ["ai_agent", "oauth_user_profile"];
+/**
+ * Small, because the registry uses the token for ONE HTTP call.
+ *
+ * Nothing here holds it for the length of a run the way Atlas does, so this only has to
+ * cover clock skew and the flight time of the request it opens.
+ */
+export declare const REFRESH_SKEW_MS = 60000;
+/** For tests, and for anything that legitimately re-resolves. */
+export declare function resetOAuthAnnouncements(): void;
+/**
+ * Three rungs: the operator's override, then the product's declaration, then the built-in.
+ *
+ * Matching `base_url`, where config is explicitly "a default, not the last word" — a
+ * deployment pointed at staging must not be overruled by whatever an index happens to carry.
+ */
+export declare function resolveTokenUrl(product: string, auth?: AuthScheme): string;
+/** Two rungs. A scope does not vary by deployment the way a host does, so there is no env one. */
+export declare function resolveScope(auth?: AuthScheme): string;
+/**
+ * The Bearer value for one invocation.
+ *
+ * Cached per user for the life of the token when this process serves one caller, and not at
+ * all when it serves many — `mintCentralToken` is handed `cacheEnabled` rather than deciding
+ * for itself, because the rule is about THIS deployment, not about the mint.
+ */
+export declare function bearerToken(product: string, auth: AuthScheme | undefined, credentials: Credentials, transport: TokenTransport): Promise<string>;