sap-ai-dev-toolkit 0.9.9918 → 0.9.9921

package/src/apim-monitoring.mjs

@@ -0,0 +1,140 @@
+// Read-only APIM analytics. This public V4 service is separate from Management.svc.
+import { z } from 'zod';
+import { READ_ONLY_ANNOTATIONS, isoDate, timeWindow, top } from './integration-common.mjs';
+import { IntegrationError, odataKey } from './integration-http.mjs';
+import { createCollectionPager, cursorSchema, decodeCollection } from './integration-collections.mjs';
+import { registerApimInspectionTools } from './apim-inspection.mjs';
+
+const ANALYTICS_ROOT = '/api/1.0/AnalyticsService';
+const PATH = '/ResultsUTC';
+const METRICS = Object.freeze([
+  ['CallCount', 'total_calls'], ['SumErrors', 'total_errors'], ['SumPolicyError', 'total_policy_errors'],
+  ['SumTargetError', 'total_target_errors'], ['SumResponseTime', 'total_response_time'], ['SumTargetResponseTime', 'total_target_response_time']
+]);
+// The service rejects derived aggregate aliases that collide with source entity properties.
+const AGGREGATE = `$count as source_records,${METRICS.map(([name, alias]) => `${name} with sum as ${alias}`).join(',')},CreatedTime with max as data_through`;
+const inputs = {
+  from: isoDate, to: isoDate,
+  proxy_names: z.array(z.string().min(1).max(100).regex(/^[^\x00-\x1f\x7f]+$/)).min(1).max(20).optional()
+};
+const pageInputs = { top: top(200, 100), cursor: cursorSchema };
+const granularities = { minute: ['Minute', 60000], hour: ['Hour', 3600000], day: ['Day', 86400000] };
+
+function selection(args) {
+  const window = timeWindow(args.from, args.to);
+  const predicates = [`CreatedTime ge ${window.from}`, `CreatedTime lt ${window.to}`];
+  if (args.proxy_names) predicates.push(`(${args.proxy_names.map(name => `ApiProxy eq ${odataKey(name)}`).join(' or ')})`);
+  return { window, filter: predicates.join(' and ') };
+}
+function number(value) {
+  return (typeof value === 'number' || typeof value === 'string' && value.trim() !== '') && Number.isFinite(Number(value)) && Number(value) >= 0 ? Number(value) : null;
+}
+function timestamp(value) {
+  return isoDate.safeParse(value).success ? new Date(value).toISOString() : null;
+}
+function metrics(row) {
+  const values = Object.fromEntries(METRICS.map(([name, alias]) => [name, number(row?.[alias])]));
+  const sourceRecords = number(row?.source_records);
+  const empty = sourceRecords === 0 && METRICS.every(([, alias]) => row[alias] === null) && row.data_through === null;
+  const calls = values.CallCount;
+  const complete = empty || Number.isSafeInteger(sourceRecords) && Object.values(values).every(value => value !== null)
+    && ['CallCount', 'SumErrors', 'SumPolicyError', 'SumTargetError'].every(name => Number.isSafeInteger(values[name]))
+    && values.SumErrors <= calls && values.SumPolicyError <= calls && values.SumTargetError <= calls
+    && (sourceRecords !== 0 || calls === 0) && (calls === 0 || timestamp(row?.data_through) !== null);
+  return {
+    source_records: Number.isSafeInteger(sourceRecords) ? sourceRecords : null,
+    calls, errors: values.SumErrors, policy_errors: values.SumPolicyError, target_errors: values.SumTargetError,
+    response_time_sum: values.SumResponseTime, target_response_time_sum: values.SumTargetResponseTime,
+    error_rate: complete && calls > 0 ? values.SumErrors / calls : null,
+    mean_response_time: complete && calls > 0 ? values.SumResponseTime / calls : null,
+    mean_target_response_time: complete && calls > 0 ? values.SumTargetResponseTime / calls : null,
+    data_through: timestamp(row?.data_through), metrics_complete: complete
+  };
+}
+function coverage(window, dataThrough) {
+  return {
+    window, data_through: dataThrough,
+    watermark_lag_ms: dataThrough === null ? null : Math.max(0, Date.parse(window.to) - Date.parse(dataThrough)),
+    scope: 'service_reported_analytics', instantaneous_health: 'unverified',
+    note: 'Source watermark is the latest reported analytics timestamp; analytics may be delayed. Response times retain service units.'
+  };
+}
+function failure(error) {
+  const status = Number.isInteger(error?.status) ? error.status : null;
+  return { result: status === 401 ? 'unauthenticated' : status === 403 ? 'forbidden' : status === 404 || status === 501 ? 'unavailable' : 'error', status,
+    ...(error?.code === 'INTEGRATION_DEADLINE' ? { stop_reason: 'deadline' } : {}) };
+}
+
+export function registerApimMonitoringTools(register, client) {
+  const pager = createCollectionPager(client, { root: ANALYTICS_ROOT });
+  register('apim_get_analytics', 'Get API Management analytics',
+    'Read server-aggregated calls, errors and weighted mean response times for explicit UTC [from,to), at most 31 days. The data watermark may lag; no traffic is no_data, not healthy. No request URLs or personal data are returned.',
+    inputs, READ_ONLY_ANNOTATIONS, async args => {
+      const { window, filter } = selection(args);
+      let decoded;
+      try {
+        decoded = decodeCollection(await client.request('GET', `${ANALYTICS_ROOT}${PATH}`, {
+          query: { $apply: `filter(${filter})/aggregate(${AGGREGATE})` }, unwrap: false, deadline: Date.now() + 30000
+        }));
+      } catch (error) {
+        return { window, complete: false, outcome: 'source_failure', source_result: failure(error), coverage: coverage(window, null) };
+      }
+      // An aggregate has zero or one row. Never sum a sampled/malformed multirow response locally.
+      const sourceComplete = !decoded.next && (decoded.total === null || decoded.total === decoded.items.length) && decoded.items.length <= 1;
+      const summary = metrics(decoded.items.length === 1 ? decoded.items[0] : null);
+      const empty = decoded.items.length === 0 && sourceComplete;
+      const complete = sourceComplete && (empty || summary.metrics_complete);
+      return { window, ...summary, complete, outcome: !complete ? 'partial' : empty || summary.calls === 0 || summary.source_records === 0 ? 'no_data' : 'data',
+        source_result: { result: 'ok', complete: sourceComplete }, coverage: coverage(window, summary.data_through) };
+    });
+
+  const grouped = (kind, args) => {
+    const { window, filter } = selection(args);
+    const series = kind === 'series';
+    let grouping = 'ApiProxy,ResponseCode';
+    if (series) {
+      const [field, duration] = granularities[args.granularity];
+      const buckets = Math.ceil(Date.parse(window.to) / duration) - Math.floor(Date.parse(window.from) / duration);
+      if (buckets > 1000) throw new IntegrationError('The analytics series must not exceed 1000 requested time buckets');
+      grouping = field;
+    }
+    const query = {
+      $apply: `filter(${filter}${series ? '' : ' and ResponseCode ge 400'})/groupby((${grouping}),aggregate(${AGGREGATE}))`,
+      $count: 'true'
+    };
+    // Authenticate and bind the cursor before entering the source-error boundary: invalid input is an error, not source failure.
+    pager.validateCursor(args.cursor);
+    return { window, grouping, query, series };
+  };
+  async function groupedPage(kind, args) {
+    const { window, grouping, query, series } = grouped(kind, args);
+    // page() rejects query/filter changes before network access; keep those errors visible to the caller.
+    try {
+      const page = await pager.page({ path: PATH, query, orderBy: grouping.split(',').map(name => `${name} asc`).join(','),
+        top: args.top, cursor: args.cursor, fallback: false, deadline: Date.now() + 30000, maxBytes: 90 * 1024,
+        project: row => ({ ...(series ? { bucket: timestamp(row[grouping]) } : {
+          proxy_name: typeof row.ApiProxy === 'string' ? row.ApiProxy.slice(0, 100) : null,
+          response_code: number(row.ResponseCode)
+        }), ...metrics(row) }) });
+      const metricsComplete = page.items.every(row => row.metrics_complete && (series ? row.bucket !== null : row.proxy_name !== null && Number.isInteger(row.response_code) && row.response_code >= 400));
+      const dataThrough = page.items.map(row => row.data_through).filter(Boolean).sort().at(-1) ?? null;
+      return { ...page, window, ...(series ? { granularity: args.granularity } : {}),
+        complete: page.complete && metricsComplete, metrics_complete: metricsComplete,
+        outcome: !metricsComplete || !['end', 'more'].includes(page.stop_reason) || page.source_result ? 'partial' : page.returned === 0 && page.complete ? 'no_data' : 'data',
+        coverage: { ...coverage(window, dataThrough), watermark_scope: 'returned_groups', totals_scope: 'each_group_only' } };
+    } catch (error) {
+      if (error instanceof IntegrationError && /cursor|continuation/i.test(error.message)) throw error;
+      return { window, items: [], returned: 0, total: null, complete: false, next_cursor: null,
+        stop_reason: error?.code === 'INTEGRATION_DEADLINE' ? 'deadline' : 'source_limit',
+        outcome: 'source_failure', source_result: failure(error), coverage: coverage(window, null) };
+    }
+  }
+  register('apim_get_analytics_series', 'Get API Management analytics series',
+    'Read paged V4 server aggregates grouped by Minute, Hour or Day, ordered by bucket. At most 1000 requested buckets and 200 rows per page. Means are weighted by calls; page metrics are not tenant totals.',
+    { ...inputs, granularity: z.enum(['minute', 'hour', 'day']), ...pageInputs }, READ_ONLY_ANNOTATIONS,
+    args => groupedPage('series', args));
+  register('apim_get_api_error_breakdown', 'Get API Management error breakdown',
+    'Read paged V4 server aggregates grouped by exact API proxy and response code >=400 for explicit UTC [from,to). Group count and continuation apply to this error grouping, not all calls.',
+    { ...inputs, ...pageInputs }, READ_ONLY_ANNOTATIONS, args => groupedPage('errors', args));
+  registerApimInspectionTools(register, client);
+}

package/src/apim-policy-steps.mjs

@@ -0,0 +1,31 @@
+// Explicit complete-order policy assignment edits; source and condition values stay private.
+import { z } from 'zod';
+import { editPolicySteps } from './apim-bundle.mjs';
+import { exportApiProxyBundle, importApiProxyBundle } from './apim-content.mjs';
+import { bundleDigest, writeBundle } from './iflow-bundle.mjs';
+import { confirmation, requireConfirmation, OVERWRITE_ANNOTATIONS } from './integration-common.mjs';
+import { IntegrationError } from './integration-http.mjs';
+
+export function registerApimPolicyStepTools(register, client, { readBackDelayMs } = {}) {
+  const name = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/);
+  register('apim_edit_policy_steps', 'Edit API proxy policy steps',
+    'Replace the complete ordered steps for one exact named proxy/target endpoint pre/post request/response phase. Requires the fresh exported bundle SHA-256; omitted step conditions preserve existing conditions (new steps are unconditional). Explicit remove_unreferenced deletes only unreferenced policy registrations/documents after a full static reference inventory, never shared scripts/resources. Ambiguous layouts fail before import. Import replaces the draft, imports a new revision and requests deployment. Content/order/condition verification is separate from runtime freshness. Requires confirmation exactly equal to EDIT API PROXY POLICY STEPS <name>.',
+    z.object({
+      name, expected_bundle_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+      endpoint: z.enum(['proxy', 'target']), endpoint_name: name,
+      flow: z.enum(['pre', 'post']), phase: z.enum(['request', 'response']),
+      steps: z.array(z.object({ policy_name: name, condition: z.string().max(4096).optional() }).strict()).max(200),
+      remove_unreferenced: z.array(name).max(200).optional(), confirmation
+    }).strict(), OVERWRITE_ANNOTATIONS,
+    async args => {
+      requireConfirmation(args.confirmation, `EDIT API PROXY POLICY STEPS ${args.name}`);
+      const files = await exportApiProxyBundle(client, args.name);
+      if (!files) throw new IntegrationError(`API proxy ${args.name} does not exist`);
+      if (bundleDigest(files) !== args.expected_bundle_sha256) throw new IntegrationError('API proxy bundle changed; inspect the fresh bundle and approve its digest before editing policy steps');
+      const assignments = editPolicySteps(files, args.name, args);
+      // Shared import compares every member, including exact assignment XML, order and conditions.
+      // A stale export therefore cannot verify an accepted import, even if runtime says DEPLOYED.
+      const deployment = await importApiProxyBundle(client, args.name, writeBundle(files), { readBackDelayMs });
+      return { ...deployment, updated: deployment.content_verified, assignments_verified: deployment.content_verified, ...assignments };
+    });
+}

package/src/apim-runtime.mjs

@@ -0,0 +1,262 @@
+import { z } from 'zod';
+import { EnvHttpProxyAgent, fetch as undiciFetch } from 'undici';
+import { apiProxyRuntimeUrl } from './apim-content.mjs';
+import { READ_ONLY_ANNOTATIONS, entity, key, list, metadataSummary } from './integration-common.mjs';
+import { IntegrationError } from './integration-http.mjs';
+import { bundleJwtIssuers } from './apim-bundle.mjs';
+import { serviceKeyCredentials } from './cf-destination.mjs';
+import { readBundle } from './iflow-bundle.mjs';
+
+const APIM_BASE = '/apiportal/api/1.0/Management.svc';
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+
+async function responseText(response) {
+  const chunks = [];
+  let length = 0;
+  for await (const chunk of response.body ?? []) {
+    length += chunk.byteLength;
+    if (length > MAX_RESPONSE_BYTES) throw new IntegrationError('API response exceeded the safe size limit');
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks, length).toString('utf8');
+}
+
+/** Execute a bounded API read with exactly one credential retained only in memory. */
+export async function runApiProxyGet({ apim, consumerKey, bearerToken, proxyName, path, query = {}, env = process.env, fetchImpl = undiciFetch }) {
+  if (!apim) throw new IntegrationError('Configure APIM credentials to resolve the deployed API proxy before testing it');
+  const credentials = [consumerKey, bearerToken].filter(value => value !== undefined);
+  if (credentials.length !== 1 || typeof credentials[0] !== 'string' || !credentials[0] || /[\r\n]/.test(credentials[0])) {
+    throw new IntegrationError('Provide exactly one private consumer API key or bearer token');
+  }
+  const safeResult = value => redactPrivateValues(value, credentials);
+  if (!/^\/(?:\$metadata|[A-Za-z_][A-Za-z0-9_]*)$/.test(path)) {
+    throw new IntegrationError('API read path must be /$metadata or one entity set; navigation, encoded paths and query strings are not allowed');
+  }
+  for (const name of Object.keys(query)) {
+    if (!['$top', '$select', '$filter'].includes(name)) throw new IntegrationError('Only $top, $select and $filter are allowed for API reads');
+  }
+  const metadata = path === '/$metadata';
+  if (metadata && Object.keys(query).length) throw new IntegrationError('Metadata reads do not accept entity query options');
+  const top = Number(query.$top ?? 1);
+  if (!metadata && (!Number.isInteger(top) || top < 1 || top > 10)) throw new IntegrationError('API reads require $top between 1 and 10');
+  const proxy = await apim.request('GET', `${APIM_BASE}/APIProxies(${key(proxyName)})`, {
+    query: { $expand: 'proxyEndPoints,proxyEndPoints/virtualhosts,deploymentInfo' }
+  });
+  if (proxy?.state !== 'DEPLOYED') throw new IntegrationError('The API proxy is not deployed');
+  let defaultHost = null;
+  if (!list(list(proxy?.proxyEndPoints)[0]?.virtualhosts).length) {
+    defaultHost = list(await apim.request('GET', `${APIM_BASE}/VirtualHosts`, { query: { $filter: 'isDefault eq true' } }))[0];
+  }
+  const runtime = apiProxyRuntimeUrl(proxy, defaultHost);
+  if (!runtime) throw new IntegrationError('The API proxy has no runtime URL');
+  const base = new URL(runtime);
+  if (base.protocol !== 'https:' || base.username || base.password || base.search || base.hash) {
+    throw new IntegrationError('API smoke requests require a credential-free HTTPS runtime URL from API Management');
+  }
+  const target = new URL(base.href);
+  target.pathname = `${base.pathname.replace(/\/+$/, '')}${path}`;
+  for (const [name, value] of Object.entries(query)) target.searchParams.set(name, String(value));
+  if (!metadata) target.searchParams.set('$top', String(top));
+  const httpProxy = env.HTTP_PROXY || env.http_proxy;
+  const httpsProxy = env.HTTPS_PROXY || env.https_proxy;
+  const dispatcher = httpProxy || httpsProxy
+    ? new EnvHttpProxyAgent({ httpProxy, httpsProxy, noProxy: env.NO_PROXY || env.no_proxy })
+    : undefined;
+  try {
+    let response;
+    try {
+      response = await fetchImpl(target.href, {
+        method: 'GET',
+        headers: { ...(bearerToken === undefined ? { apikey: consumerKey } : { authorization: `Bearer ${bearerToken}` }), accept: metadata ? 'application/xml' : 'application/json', 'accept-encoding': 'gzip, deflate' },
+        redirect: 'manual',
+        signal: AbortSignal.timeout(30000),
+        ...(dispatcher ? { dispatcher } : {})
+      });
+    } catch {
+      throw new IntegrationError('API proxy GET failed (network error or timeout); credentials were not returned');
+    }
+    const status = response.status;
+    if (status !== 200) {
+      await response.body?.cancel().catch(() => {});
+      throw new IntegrationError(`API proxy GET failed (HTTP ${status}); response body withheld to protect credentials; redirects are not followed`);
+    }
+    let text;
+    try {
+      text = await responseText(response);
+    } catch {
+      throw new IntegrationError('API response could not be read within the safe size limit; response withheld');
+    }
+    const result = { proxy: proxyName, runtime_url: base.href, path, status, content_type: response.headers.get('content-type') };
+    if (metadata) {
+      if (!/<(?:\w+:)?Edmx\b/.test(text)) throw new IntegrationError('API proxy returned HTTP 200 but not an OData metadata document');
+      return safeResult({ ...result, metadata: metadataSummary(text) });
+    }
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      throw new IntegrationError('API proxy returned HTTP 200 but not JSON');
+    }
+    const rows = data?.d?.results ?? data?.value;
+    if (!Array.isArray(rows)) throw new IntegrationError('API proxy response is not an OData entity collection');
+    if (rows.length > top) throw new IntegrationError('API proxy did not honor the bounded $top request');
+    return safeResult({ ...result, returned: rows.length, fields: [...new Set(rows.flatMap(row => Object.keys(entity(row) ?? {})))] });
+  } finally {
+    await dispatcher?.close();
+  }
+}
+
+/** Redact private values without replacing JSON syntax or corrupting scalar literals. */
+export function redactPrivateValues(value, secrets) {
+  const privateValues = [...new Set(secrets)].filter(value => typeof value === 'string' && value).sort((a, b) => b.length - a.length);
+  const redactText = text => {
+    for (const secret of privateValues) text = text.replaceAll(secret, '[redacted]');
+    return text;
+  };
+  const redact = entry => {
+    if (Array.isArray(entry)) return entry.map(redact);
+    if (entry && typeof entry === 'object') {
+      return Object.fromEntries(Object.entries(entry).map(([name, value]) => [redactText(name), redact(value)]));
+    }
+    if (typeof entry === 'string') return redactText(entry);
+    if (entry === undefined) return entry;
+    const text = String(entry);
+    const redacted = redactText(text);
+    return redacted === text ? entry : redacted;
+  };
+  return redact(value);
+}
+
+function oauthEndpoint(credentials) {
+  const auth = credentials?.uaa ?? credentials?.oauth ?? credentials;
+  const clientId = auth?.clientid ?? auth?.client_id;
+  const clientSecret = auth?.clientsecret ?? auth?.client_secret;
+  if (typeof clientId !== 'string' || !clientId || typeof clientSecret !== 'string' || !clientSecret) {
+    throw new IntegrationError('OAuth probing requires a client ID and client secret; certificate-only service keys are not supported');
+  }
+  const address = auth.tokenurl ?? auth.token_url ?? auth.url;
+  let url;
+  try {
+    if (typeof address !== 'string' || /[\s@?#]/.test(address)) throw new Error();
+    url = new URL(address);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error();
+    if (url.pathname === '/') url.pathname = '/oauth/token';
+    if (url.pathname !== '/oauth/token') throw new Error();
+  } catch {
+    throw new IntegrationError('OAuth service key requires a credential-free HTTPS /oauth/token endpoint without a query or fragment');
+  }
+  return { url, clientId, clientSecret };
+}
+
+/** Acquire a narrowly scoped XSUAA token only after pinning its endpoint to fresh proxy policy. */
+export async function runApiProxyOAuthGet({ apim, oauth, proxyName, path, query, env = process.env, fetchImpl = undiciFetch, execFileImpl }) {
+  if (!oauth || typeof oauth.scope !== 'string' || !oauth.scope || oauth.scope.length > 512 || /[\s\x00-\x1f\x7f]/.test(oauth.scope)) {
+    throw new IntegrationError('OAuth probing requires exactly one nonempty whitespace-free scope');
+  }
+  for (const reference of [oauth.service_instance, oauth.service_key]) {
+    if (typeof reference !== 'string' || !/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,255}$/.test(reference)) {
+      throw new IntegrationError('OAuth probing requires CF service instance and service key names, not credentials');
+    }
+  }
+  if (!apim) throw new IntegrationError('Configure APIM credentials before OAuth probing');
+  const bundle = await apim.request('GET', '/apiportal/api/1.0/Transport.svc/APIProxies', {
+    query: { name: proxyName }, accept: 'application/zip, application/octet-stream', responseType: 'bytes'
+  });
+  let issuers;
+  try {
+    issuers = bundleJwtIssuers(readBundle(bundle), proxyName);
+  } catch {
+    throw new IntegrationError('The selected proxy bundle could not be inspected for an explicit VerifyJWT issuer');
+  }
+  if (!issuers.length) throw new IntegrationError('The selected proxy has no explicit HTTPS VerifyJWT issuer for OAuth probing');
+  let credentials;
+  try {
+    credentials = await serviceKeyCredentials(oauth.service_instance, oauth.service_key, 'OAuth', { env, execFileImpl });
+  } catch {
+    throw new IntegrationError('The referenced CF OAuth service key could not be read; credential details withheld');
+  }
+  const { url, clientId, clientSecret } = oauthEndpoint(credentials);
+  if (!issuers.some(issuer => new URL(issuer).href === url.href)) {
+    throw new IntegrationError('The OAuth token endpoint does not match an explicit VerifyJWT issuer of the selected proxy; no credentials were sent');
+  }
+  const httpProxy = env.HTTP_PROXY || env.http_proxy;
+  const httpsProxy = env.HTTPS_PROXY || env.https_proxy;
+  const dispatcher = httpProxy || httpsProxy
+    ? new EnvHttpProxyAgent({ httpProxy, httpsProxy, noProxy: env.NO_PROXY || env.no_proxy })
+    : undefined;
+  let bearerToken;
+  try {
+    let response;
+    try {
+      response = await fetchImpl(url.href, {
+        method: 'POST',
+        headers: { authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`, 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json', 'accept-encoding': 'gzip, deflate' },
+        body: new URLSearchParams({ grant_type: 'client_credentials', scope: oauth.scope }).toString(),
+        redirect: 'manual', signal: AbortSignal.timeout(30000),
+        ...(dispatcher ? { dispatcher } : {})
+      });
+    } catch {
+      throw new IntegrationError('OAuth token request failed (network error or timeout); credential details withheld');
+    }
+    if (response.status !== 200) {
+      await response.body?.cancel().catch(() => {});
+      throw new IntegrationError(`OAuth token request failed (HTTP ${response.status}); response withheld; redirects are not followed`);
+    }
+    let token;
+    try {
+      token = JSON.parse(await responseText(response));
+    } catch {
+      throw new IntegrationError('OAuth token response was unreadable or invalid; response withheld');
+    }
+    if (typeof token?.access_token !== 'string' || !token.access_token || /[\s\x00-\x1f\x7f]/.test(token.access_token) || typeof token.token_type !== 'string' || token.token_type.toLowerCase() !== 'bearer') {
+      throw new IntegrationError('OAuth token response did not contain a usable bearer token; response withheld');
+    }
+    if (token.scope !== undefined && (typeof token.scope !== 'string' || token.scope.trim() !== oauth.scope)) {
+      throw new IntegrationError('OAuth token response did not grant exactly the requested scope; response withheld');
+    }
+    bearerToken = token.access_token;
+  } finally {
+    await dispatcher?.close();
+  }
+  const result = await runApiProxyGet({ apim, bearerToken, proxyName, path, query, env, fetchImpl });
+  return redactPrivateValues(result, [clientId, clientSecret, bearerToken]);
+}
+
+/** The APIM runtime surface is available without Developer Hub; API-key mode alone requires it. */
+export function registerApimRuntimeTools(register, { apim, devhub, env, fetchImpl, execFileImpl } = {}) {
+  const applicationId = z.string().min(1).max(256).regex(/^[A-Za-z0-9_-]+$/);
+  const proxyName = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/);
+  async function getApplication(id) {
+    if (!devhub) throw new IntegrationError('Configure Developer Hub credentials to use application_id API-key authentication');
+    const { status, data } = await devhub.request('GET', `/odata/1.0/data.svc/APIMgmt.Applications(${key(id)})`, {
+      query: { $expand: 'ToAPIProductsDetails,ToSubscriptions/ToAPIProduct,ToSubscriptions/ToRatePlan' },
+      expect: [200, 404], withStatus: true
+    });
+    if (status === 404) throw new IntegrationError(`Developer Hub application ${id} does not exist`);
+    return data;
+  }
+  register('apim_test_api', 'Test API with private API-key or OAuth credentials',
+    'Execute a GET-only OData metadata or bounded entity read against an APIM-resolved deployed proxy. Supply exactly one authentication source: application_id for a private Developer Hub key (requires DEVHUB), or oauth CF service/key references and one scope for external XSUAA client_credentials (works without DEVHUB). Fresh VerifyJWT issuer pinning precedes credential use. No keys, secrets, tokens, headers or business row values returned; no redirects or arbitrary URLs.',
+    {
+      application_id: applicationId.optional(),
+      oauth: z.object({
+        service_instance: z.string().regex(/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,255}$/),
+        service_key: z.string().regex(/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,255}$/),
+        scope: z.string().min(1).max(512).regex(/^[^\s\x00-\x1f\x7f]+$/)
+      }).strict().optional(),
+      proxy_name: proxyName,
+      path: z.string().regex(/^\/(?:\$metadata|[A-Za-z_][A-Za-z0-9_]*)$/),
+      query: z.object({
+        $top: z.number().int().min(1).max(10).optional(),
+        $select: z.string().min(1).max(1024).optional(),
+        $filter: z.string().min(1).max(2048).optional()
+      }).strict().optional()
+    }, READ_ONLY_ANNOTATIONS,
+    async ({ application_id, oauth, proxy_name, path, query }) => {
+      if ((application_id !== undefined) === (oauth !== undefined)) throw new IntegrationError('Provide exactly one authentication source: application_id or oauth');
+      if (oauth !== undefined) return runApiProxyOAuthGet({ apim, oauth, proxyName: proxy_name, path, query, env, fetchImpl, execFileImpl });
+      const application = await getApplication(application_id);
+      const result = await runApiProxyGet({ apim, consumerKey: application?.app_key, proxyName: proxy_name, path, query, env, fetchImpl });
+      return redactPrivateValues({ application_id, ...result }, [application?.app_key, application?.app_secret]);
+    });
+}