sap-ai-dev-toolkit 0.9.9917 → 0.9.9920

package/src/apim-content.mjs

@@ -0,0 +1,157 @@
+// Private APIM content reads shared by authoring, inspection and release evidence.
+import { entity, key, list, sleep, withoutSecrets } from './integration-common.mjs';
+import { bundleDocumentation } from './apim-bundle.mjs';
+import { bundleDigest, readBundle, strFromU8 } from './iflow-bundle.mjs';
+import { isDeepStrictEqual } from 'node:util';
+import { IntegrationError } from './integration-http.mjs';
+
+export const APIM_BASE = '/apiportal/api/1.0/Management.svc';
+export const APIM_TRANSPORT = '/apiportal/api/1.0/Transport.svc/APIProxies';
+
+/** Resolve the published URL or the configured virtual host/base path. Callers enforce their surface's URL policy. */
+export function apiProxyRuntimeUrl(proxy, defaultHost) {
+  const candidates = [proxy?.publishUrl, ...list(proxy?.deploymentInfo).map(entry => entry?.publishUrl), proxy?.deploymentInfo?.publishUrl];
+  const published = candidates.find(value => typeof value === 'string' && /^https?:\/\/\S+$/.test(value));
+  if (published) return published;
+  const endpoint = list(proxy?.proxyEndPoints)[0];
+  const host = list(endpoint?.virtualhosts)[0] ?? defaultHost;
+  if (!endpoint || !host?.virtual_host) return null;
+  const port = Number(host.virtual_port);
+  const portText = !port || port === 443 || port === 80 ? '' : `:${port}`;
+  const path = endpoint.base_path ?? '';
+  return `${host.isSSL ? 'https' : 'http'}://${host.virtual_host}${portText}${path.startsWith('/') ? path : `/${path}`}`;
+}
+
+export async function readApiProxy(client, name, { deadline } = {}) {
+  const { status, data } = await client.request('GET', `${APIM_BASE}/APIProxies(${key(name)})`, {
+    query: { $expand: 'proxyEndPoints,targetEndPoints,proxyEndPoints/virtualhosts,deploymentInfo' },
+    expect: [200, 404], withStatus: true, deadline
+  });
+  if (status === 404) return null;
+  let defaultHost = null;
+  if (!list(list(data?.proxyEndPoints)[0]?.virtualhosts).length) {
+    defaultHost = list(await client.request('GET', `${APIM_BASE}/VirtualHosts`, {
+      query: { $filter: 'isDefault eq true' }, deadline
+    }))[0] ?? null;
+  }
+  return { ...withoutSecrets(entity(data)), runtime_url: apiProxyRuntimeUrl(data, defaultHost) };
+}
+
+export async function exportApiProxyArchive(client, name, { deadline } = {}) {
+  const { status, data } = await client.request('GET', APIM_TRANSPORT, {
+    query: { name }, accept: 'application/zip, application/octet-stream', responseType: 'bytes',
+    expect: [200, 404], withStatus: true, deadline
+  });
+  return status === 404 ? null : data;
+}
+
+export async function exportApiProxyBundle(client, name, options) {
+  const bytes = await exportApiProxyArchive(client, name, options);
+  if (bytes === null) return null;
+  try { return readBundle(bytes); }
+  catch { throw new IntegrationError(`API proxy ${name} export is not a readable zip archive`); }
+}
+
+// Only the observed portal documentation transformations are allowed. Unknown resources,
+// policies, endpoint XML and binary files must remain byte-for-byte equal.
+function normalizeDocumentationText(document) {
+  const opaque = new Set(['example', 'examples', 'default', 'enum', 'const']);
+  const entities = { lt: '<', gt: '>', amp: '&' };
+  const visit = value => {
+    if (!value || typeof value !== 'object') return;
+    for (const [name, child] of Object.entries(value)) {
+      if (name === 'description' && typeof child === 'string') value[name] = child.replace(/&(lt|gt|amp);/g, (_, entity) => entities[entity]).replace(/\s+/g, ' ').trim();
+      else if (!opaque.has(name) && !name.startsWith('x-')) visit(child);
+    }
+  };
+  visit(document);
+  return document;
+}
+
+function contentMatches(expected, actual, name, proxy) {
+  if (expected.size !== actual.size) return { verified: false, normalized: false };
+  let documentation = null;
+  let normalized = false;
+  for (const [path, bytes] of expected) {
+    const observed = actual.get(path);
+    if (!observed) return { verified: false, normalized: false };
+    if (Buffer.from(bytes).equals(Buffer.from(observed))) continue;
+    // Resolve the registration with the existing structural scanner, not a suffix guess.
+    try {
+      documentation ??= bundleDocumentation(expected, name);
+      if (path !== documentation.path || bundleDocumentation(actual, name).path !== path) return { verified: false, normalized: false };
+      const submitted = JSON.parse(strFromU8(bytes));
+      const received = JSON.parse(strFromU8(observed));
+      if (isDeepStrictEqual(submitted, received)) continue;
+      const runtime = new URL(proxy.runtime_url);
+      const endpoint = `${runtime.protocol}//${runtime.hostname}:${runtime.port || '443'}${runtime.pathname}`;
+      if (typeof proxy.title === 'string') submitted.info.title = proxy.title;
+      if (typeof proxy.description === 'string') submitted.info.description = proxy.description;
+      submitted.info['x-targetEndpoint'] = endpoint;
+      if (submitted.openapi) submitted.servers = [{ url: endpoint }];
+      if (!isDeepStrictEqual(normalizeDocumentationText(received), normalizeDocumentationText(submitted))) return { verified: false, normalized: false };
+      normalized = true;
+    } catch {
+      return { verified: false, normalized: false };
+    }
+  }
+  return { verified: true, normalized };
+}
+
+/** Import once; acceptance, complete content read-back and runtime evidence are separate facts. */
+export async function importApiProxyBundle(client, name, bytes, { readBackDelayMs = 5000, deadline = Date.now() + 20_000 } = {}) {
+  const intended = readBundle(bytes); // Reject malformed/unsafe archives before the mutation.
+  const intendedDigest = bundleDigest(intended);
+  const { status } = await client.request('POST', APIM_TRANSPORT, {
+    body: Buffer.from(bytes).toString('base64'), contentType: 'application/octet-stream',
+    accept: 'application/zip', responseType: 'none', expect: [200, 201], withStatus: true, deadline
+  });
+  const result = {
+    name, accepted: true, imported: true, http_status: status, outcome: 'unverified',
+    content_verified: false, read_back_verified: false, read_back_normalized: false,
+    runtime_verified: false, runtime_url: null, state: null,
+    intended_bundle_sha256: intendedDigest, observed_bundle_sha256: null,
+    effects: { draft_created_or_replaced: true, new_revision_imported: true, deployment_requested: true },
+    read_back_attempts: 0, stop_reason: 'source_limit',
+    note: 'Import accepted; runtime freshness/revision identity is unverified. Do not repeat the import blindly.'
+  };
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    if (attempt) {
+      if (Date.now() + readBackDelayMs >= deadline) { result.stop_reason = 'deadline'; break; }
+      await sleep(readBackDelayMs);
+    }
+    if (Date.now() >= deadline) { result.stop_reason = 'deadline'; break; }
+    result.read_back_attempts += 1;
+    let proxy = null;
+    try {
+      proxy = await readApiProxy(client, name, { deadline });
+      result.state = typeof proxy?.state === 'string' ? proxy.state.slice(0, 100) : null;
+      if (proxy?.runtime_url) {
+        const url = new URL(proxy.runtime_url);
+        if (!url.username && !url.password && ['https:', 'http:'].includes(url.protocol)) {
+          url.search = ''; url.hash = '';
+          if (url.href.length <= 2048) result.runtime_url = url.href;
+        }
+      }
+    } catch {
+      result.runtime_read_back_error = 'Proxy metadata read-back failed; response withheld.';
+    }
+    try {
+      const observed = await exportApiProxyBundle(client, name, { deadline });
+      if (!observed) { result.content_read_back_error = 'Imported content is not yet available.'; continue; }
+      result.observed_bundle_sha256 = bundleDigest(observed);
+      const comparison = contentMatches(intended, observed, name, proxy);
+      result.content_verified = result.read_back_verified = comparison.verified;
+      result.read_back_normalized = comparison.normalized;
+      if (comparison.verified) {
+        delete result.content_read_back_error;
+        result.stop_reason = 'end';
+        break;
+      }
+      result.content_read_back_error = 'Imported content read-back differs; do not repeat the import blindly.';
+    } catch {
+      result.content_read_back_error = 'Content read-back failed; response withheld. Do not repeat the import blindly.';
+    }
+  }
+  return result;
+}

package/src/apim-delete-tools.mjs

@@ -0,0 +1,139 @@
+// Native APIM object deletion. Never cascade to consumers, providers or credentials.
+import { z } from 'zod';
+import { IntegrationError, odataKey } from './integration-http.mjs';
+import { confirmation, entity, key, list, OVERWRITE_ANNOTATIONS, requireConfirmation, sleep } from './integration-common.mjs';
+import { registerApimCleanupTools } from './apim-cleanup-tools.mjs';
+
+const apimName = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/);
+const INACTIVE_STATES = new Set(['CREATED', 'UNDEPLOYED']);
+const MAX_DEPENDENCIES = 1000;
+
+export function registerApimDeleteTools(register, { request, readBackDelayMs = 5000 }) {
+  const pathFor = (collection, name) => `/${collection}(${key(name)})`;
+
+  async function named(collection, name) {
+    const { status, data } = await request('GET', pathFor(collection, name), { expect: [200, 404], withStatus: true });
+    if (status === 404) return null;
+    const value = entity(data);
+    if (value?.name !== name) throw new IntegrationError(`Cannot establish the identity of ${collection} ${name}; deletion refused`);
+    return value;
+  }
+
+  async function count(path, query) {
+    const text = await request('GET', `${path}/$count`, { query, accept: 'text/plain', responseType: 'text' });
+    if (typeof text !== 'string' || !/^\s*\d+\s*$/.test(text)) throw new IntegrationError('Invalid dependency count; deletion refused');
+    const value = Number(text.trim());
+    if (!Number.isSafeInteger(value)) throw new IntegrationError('Unsafe dependency count; deletion refused');
+    return value;
+  }
+
+  const deployments = name => count('/APIProxyDeployments', { $filter: `name eq ${odataKey(name)}` });
+
+  async function productDependencies(name) {
+    const path = `${pathFor('APIProxies', name)}/apiProducts`;
+    const names = new Set();
+    let expected = null;
+    let offset = 0;
+    do {
+      const raw = await request('GET', path, {
+        query: { $select: 'name', $orderby: 'name', $top: 100, $skip: offset, $inlinecount: 'allpages' }, unwrap: false
+      });
+      const page = raw?.d ?? raw;
+      const total = typeof page?.__count === 'string' && /^\d+$/.test(page.__count) ? Number(page.__count) : NaN;
+      if (!Number.isSafeInteger(total) || total > MAX_DEPENDENCIES || (expected !== null && total !== expected)) {
+        throw new IntegrationError('Cannot establish a complete stable product dependency list; deletion refused');
+      }
+      expected = total;
+      const rows = list(page);
+      if (!Array.isArray(page?.results) || (rows.length === 0 && names.size < expected)) {
+        throw new IntegrationError('Incomplete product dependency page; deletion refused');
+      }
+      for (const row of rows) {
+        if (typeof row?.name !== 'string' || !row.name || names.has(row.name)) {
+          throw new IntegrationError('Invalid or repeated product dependency; deletion refused');
+        }
+        names.add(row.name);
+      }
+      if (names.size > expected) throw new IntegrationError('Product dependencies changed during inspection; deletion refused');
+      offset += rows.length;
+    } while (names.size < expected);
+    if (await count(path) !== expected) throw new IntegrationError('Product dependencies changed during inspection; deletion refused');
+    return [...names];
+  }
+
+  async function inspectProduct(name) {
+    if (!(await named('APIProducts', name))) return null;
+    return { name, blockingApplicationCount: await count(`${pathFor('APIProducts', name)}/applications`) };
+  }
+
+  async function inspectProxy(name) {
+    const proxy = await named('APIProxies', name);
+    if (!proxy) {
+      if (await deployments(name)) throw new IntegrationError(`API proxy ${name} has no definition but still has deployment records; deletion is unverified`);
+      return null;
+    }
+    return { name, state: proxy.state, blockingProducts: await productDependencies(name) };
+  }
+
+  async function remove(collection, name) {
+    const { status } = await request('DELETE', pathFor(collection, name), {
+      expect: [200, 202, 204, 404], responseType: 'text', withStatus: true
+    });
+    // A successful HTTP response is not proof of deletion. Never retry DELETE.
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      if (attempt) await sleep(readBackDelayMs);
+      const definition = await named(collection, name);
+      if (!definition && (collection !== 'APIProxies' || await deployments(name) === 0)) {
+        return { name, ...(status === 404 ? { already_absent: true } : { deleted: true }), deletion_verified: true };
+      }
+    }
+    return { name, deleted: false, deletion_verified: false, pending: true,
+      note: 'Deletion is not yet verified: a definition or deployment record remains. Re-read before another deletion attempt.' };
+  }
+
+  async function deleteProduct(name) {
+    const product = await inspectProduct(name);
+    if (!product) return { name, already_absent: true, deletion_verified: true };
+    if (product.blockingApplicationCount) {
+      throw new IntegrationError(`API product ${name} is associated with ${product.blockingApplicationCount} application(s); deletion refused`);
+    }
+    return remove('APIProducts', name);
+  }
+
+  async function deleteProxy(name, { allow_deployed = false } = {}) {
+    const proxy = await inspectProxy(name);
+    if (!proxy) return { name, already_absent: true, deletion_verified: true };
+    if (proxy.blockingProducts.length) {
+      throw new IntegrationError(`API proxy ${name} is associated with ${proxy.blockingProducts.length} product(s); delete or disassociate those products first`);
+    }
+    if (proxy.state === 'DEPLOYED') {
+      if (!allow_deployed) throw new IntegrationError(`API proxy ${name} is deployed; allow_deployed=true is required to approve runtime removal`);
+    } else if (!INACTIVE_STATES.has(proxy.state)) {
+      throw new IntegrationError(`API proxy ${name} has an unknown or transitional lifecycle state; deletion refused`);
+    }
+    return remove('APIProxies', name);
+  }
+
+  register('apim_delete_api_product', 'Delete API product',
+    'Delete exactly one API product, including a published product, only when no application associations exist. '
+      + 'Never detaches or deletes applications or proxies. Verifies named-object absence after DELETE. '
+      + 'Requires confirmation exactly equal to DELETE API PRODUCT <name>.',
+    z.object({ name: apimName, confirmation }).strict(), OVERWRITE_ANNOTATIONS,
+    async ({ name, confirmation: approved }) => {
+      requireConfirmation(approved, `DELETE API PRODUCT ${name}`);
+      return deleteProduct(name);
+    });
+
+  register('apim_delete_api_proxy', 'Delete API proxy',
+    'Delete exactly one API proxy after proving it has no product associations. '
+      + 'Deployed proxies require allow_deployed=true to approve removal from runtime. '
+      + 'Uses native deletion, never guessed undeploy endpoints; verifies definition and deployment-record absence. '
+      + 'Never deletes providers, KVMs or credentials. Requires confirmation exactly equal to DELETE API PROXY <name>.',
+    z.object({ name: apimName, allow_deployed: z.boolean().default(false), confirmation }).strict(), OVERWRITE_ANNOTATIONS,
+    async ({ name, allow_deployed, confirmation: approved }) => {
+      requireConfirmation(approved, `DELETE API PROXY ${name}`);
+      return deleteProxy(name, { allow_deployed });
+    });
+
+  registerApimCleanupTools(register, { inspectProduct, inspectProxy, deleteProduct, deleteProxy });
+}

package/src/apim-documentation.mjs

@@ -0,0 +1,162 @@
+// Bounded, self-contained consumer documentation. Never return examples or arbitrary extension payloads.
+import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
+import { IntegrationError } from './integration-http.mjs';
+
+export const MAX_DOCUMENTATION_BYTES = 1024 * 1024;
+export const DOCUMENTATION_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = message => { throw new IntegrationError(`API documentation ${message}`); };
+
+function localReference(spec, ref) {
+  if (typeof ref !== 'string' || !(ref === '#' || ref.startsWith('#/'))) fail('must be self-contained; external references are not allowed');
+  if (ref === '#') return spec;
+  let pointer;
+  try { pointer = decodeURIComponent(ref.slice(2)); } catch { fail('contains an invalid local reference'); }
+  let target = spec;
+  for (const token of pointer.split('/')) {
+    if (/~(?:[^01]|$)/.test(token)) fail('contains an invalid local reference');
+    const part = token.replaceAll('~1', '/').replaceAll('~0', '~');
+    if ((!object(target) && !Array.isArray(target)) || !Object.hasOwn(target, part)) fail('contains an unresolved local reference');
+    target = target[part];
+  }
+  return target;
+}
+
+function resolve(spec, value) {
+  const seen = new Set();
+  while (object(value) && typeof value.$ref === 'string') {
+    const { $ref: ref, ...siblings } = value;
+    if (seen.has(ref)) fail('contains a cyclic structural reference');
+    seen.add(ref);
+    const target = localReference(spec, ref);
+    value = object(target) ? { ...target, ...siblings } : target;
+  }
+  return value;
+}
+
+function publicUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { fail('must use an absolute HTTPS public runtime URL'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash
+    || isIP(url.hostname.replace(/^\[|\]$/g, '')) || !url.hostname.includes('.')
+    || /(?:^|\.)(?:localhost|local|internal|test|invalid)$/.test(url.hostname)) {
+    fail('must use a credential-free HTTPS public runtime URL without query or fragment');
+  }
+  return url.href.replace(/\/$/, '');
+}
+
+/** Validate input without dereferencing URLs or returning document content in errors. */
+export function parseApiDocumentation(text, runtimeUrl, { allowMissingVersion = false } = {}) {
+  if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > MAX_DOCUMENTATION_BYTES) fail('JSON exceeds the 1 MiB limit');
+  let spec;
+  try { spec = JSON.parse(text); } catch { fail('must be valid OpenAPI JSON'); }
+  if (!object(spec) || !(spec.swagger === '2.0' || /^3\.(?:0|1)\.\d+$/.test(spec.openapi ?? ''))) fail('requires swagger 2.0 or openapi 3.0.x/3.1.x');
+  if (!object(spec.info) || typeof spec.info.title !== 'string' || !spec.info.title.trim()) fail('requires info.title');
+  if ((!allowMissingVersion || spec.info.version !== undefined)
+    && (typeof spec.info.version !== 'string' || !spec.info.version.trim())) fail('requires info.version');
+  if (!object(spec.paths)) fail('requires an object paths');
+  const expected = runtimeUrl === undefined ? undefined : publicUrl(runtimeUrl);
+  const checkUrl = value => {
+    const canonical = publicUrl(value);
+    if (expected !== undefined && canonical !== expected) fail('runtime URL does not match the named proxy');
+    return canonical;
+  };
+  const checkServers = value => {
+    if (value === undefined) return;
+    if (!Array.isArray(value) || !value.length) fail('servers must be a nonempty array');
+    for (const server of value) {
+      if (!object(server) || typeof server.url !== 'string' || /[{}]/.test(server.url)) fail('requires concrete runtime servers without variables');
+      checkUrl(server.url);
+    }
+  };
+  let servers;
+  if (spec.swagger === '2.0') {
+    if (!Array.isArray(spec.schemes) || spec.schemes.length !== 1 || spec.schemes[0] !== 'https'
+      || typeof spec.host !== 'string' || /[\/?#@]/.test(spec.host)
+      || typeof spec.basePath !== 'string' || !spec.basePath.startsWith('/')) fail('requires HTTPS schemes, host and basePath');
+    servers = [checkUrl(`https://${spec.host}${spec.basePath}`)];
+  } else {
+    if (!Array.isArray(spec.servers) || !spec.servers.length) fail('requires explicit runtime servers');
+    servers = spec.servers.map(server => {
+      if (!object(server) || typeof server.url !== 'string' || /[{}]/.test(server.url)) fail('requires concrete runtime servers without variables');
+      return checkUrl(server.url);
+    });
+  }
+  const stack = [spec];
+  while (stack.length) {
+    const value = stack.pop();
+    if (!value || typeof value !== 'object') continue;
+    for (const [key, item] of Object.entries(value)) {
+      if (key === '$ref') localReference(spec, item);
+      if (item && typeof item === 'object') stack.push(item);
+    }
+  }
+  for (const [path, original] of Object.entries(spec.paths)) {
+    if (path.startsWith('x-')) continue;
+    const item = resolve(spec, original);
+    if (!path.startsWith('/') || path.length > 2048 || /[?#\r\n]/.test(path) || !object(item)) fail('contains an invalid or overlong path item');
+    checkServers(item.servers);
+    for (const method of DOCUMENTATION_METHODS) {
+      const operation = item[method];
+      if (operation === undefined) continue;
+      if (!object(operation) || !object(operation.responses)) fail('operations require an object responses');
+      checkServers(operation.servers);
+    }
+  }
+  return { spec, servers: [...new Set(servers)] };
+}
+
+const bounded = value => typeof value === 'string' ? value.slice(0, 512) : undefined;
+const security = value => Array.isArray(value) ? value.filter(object).map(requirement => Object.fromEntries(
+  Object.entries(requirement).map(([name, scopes]) => [name, Array.isArray(scopes) ? scopes.filter(scope => typeof scope === 'string').map(bounded) : []])
+)) : [];
+
+/** Safe structural summary, with an optional selected operation instead of raw schemas or examples. */
+export function summarizeApiDocumentation(text, { path, method, operationOffset = 0 } = {}) {
+  const { spec, servers } = parseApiDocumentation(text, undefined, { allowMissingVersion: true });
+  const schemes = spec.swagger === '2.0' ? spec.securityDefinitions : spec.components?.securitySchemes;
+  const inventory = [];
+  for (const [itemPath, original] of Object.entries(spec.paths)) {
+    if (itemPath.startsWith('x-')) continue;
+    const item = resolve(spec, original);
+    for (const verb of DOCUMENTATION_METHODS) if (object(item[verb])) inventory.push({ path: itemPath, method: verb.toUpperCase(), operation_id: bounded(item[verb].operationId) ?? null });
+  }
+  const result = {
+    title: bounded(spec.info.title), version: bounded(spec.info.version) ?? null, openapi_version: spec.openapi ?? spec.swagger,
+    sha256: createHash('sha256').update(text).digest('hex'), bytes: Buffer.byteLength(text), servers,
+    path_count: Object.keys(spec.paths).filter(value => !value.startsWith('x-')).length, operation_count: inventory.length,
+    security_schemes: Object.entries(object(schemes) ? schemes : {}).map(([name, original]) => {
+      const scheme = resolve(spec, original);
+      return {
+        name, type: bounded(scheme?.type) ?? null, scheme: bounded(scheme?.scheme) ?? null,
+        in: bounded(scheme?.in) ?? null, parameter_name: bounded(scheme?.name) ?? null,
+        flows: object(scheme?.flows) ? Object.keys(scheme.flows) : [],
+        scopes: Object.keys(scheme?.scopes ?? {}).concat(...Object.values(scheme?.flows ?? {}).map(flow => Object.keys(flow?.scopes ?? {})))
+      };
+    }),
+    security: security(spec.security), operations: inventory.slice(operationOffset, operationOffset + 100),
+    operation_offset: operationOffset, next_operation_offset: operationOffset + 100 < inventory.length ? operationOffset + 100 : null
+  };
+  if (path !== undefined || method !== undefined) {
+    const verb = method?.toLowerCase();
+    const item = resolve(spec, spec.paths[path]);
+    const operation = item?.[verb];
+    if (!DOCUMENTATION_METHODS.includes(verb) || !object(operation)) fail('selected operation does not exist');
+    const parameters = new Map();
+    for (const original of [...(Array.isArray(item.parameters) ? item.parameters : []), ...(Array.isArray(operation.parameters) ? operation.parameters : [])]) {
+      const parameter = resolve(spec, original);
+      parameters.set(JSON.stringify([parameter?.in, parameter?.name]), parameter);
+    }
+    result.operation = {
+      path, method: verb.toUpperCase(), operation_id: bounded(operation.operationId) ?? null,
+      summary: bounded(operation.summary) ?? null, security: security(operation.security ?? spec.security),
+      parameters: [...parameters.values()]
+        .map(parameter => ({ name: bounded(parameter?.name) ?? null, in: bounded(parameter?.in) ?? null, required: parameter?.required === true, type: bounded(parameter?.type ?? resolve(spec, parameter?.schema)?.type) ?? null, ref: bounded(parameter?.$ref) ?? null })),
+      request_content_types: spec.swagger === '2.0' ? (operation.consumes ?? spec.consumes ?? []).filter(value => typeof value === 'string').map(bounded) : Object.keys(resolve(spec, operation.requestBody)?.content ?? {}),
+      response_statuses: Object.keys(operation.responses)
+    };
+    if (Buffer.byteLength(JSON.stringify(result.operation)) > 32 * 1024) fail('selected operation summary exceeds 32 KiB');
+  }
+  return result;
+}

package/src/apim-inspection.mjs

@@ -0,0 +1,141 @@
+// Static bundle evidence only: no policy/source text or effective-runtime security claims.
+import { z } from 'zod';
+import { strFromU8 } from 'fflate';
+import { apiProxyLayout, bundlePolicyNames, bundleJwtIssuers, xmlLocate, xmlChildren, xmlText, xmlAttributes } from './apim-bundle.mjs';
+import { exportApiProxyBundle, readApiProxy } from './apim-content.mjs';
+import { bundleDigest } from './iflow-bundle.mjs';
+import { stateDigest } from './integration-state.mjs';
+import { READ_ONLY_ANNOTATIONS } from './integration-common.mjs';
+import { IntegrationError } from './integration-http.mjs';
+
+const local = element => element.name.split(':').at(-1);
+const identifier = value => typeof value === 'string' && /^[A-Za-z0-9_.& -]{1,255}$/.test(value) ? value : null;
+const field = (xml, element, name) => xmlChildren(xml, element).find(child => local(child) === name);
+const value = (xml, element, name) => {
+  const child = field(xml, element, name);
+  return child ? xmlText(xml, child) : null;
+};
+const text = (files, path) => strFromU8(files.get(path));
+
+export function inspectApiProxyBundle(files, name) {
+  const layout = apiProxyLayout(files, name);
+  const rootXml = text(files, layout.root);
+  const root = xmlLocate(rootXml, []);
+  const policyLists = xmlChildren(rootXml, root).filter(child => local(child) === 'policies');
+  if (policyLists.length > 1) throw new IntegrationError('API proxy bundle has ambiguous policy registrations');
+  const names = bundlePolicyNames(files, name);
+  const registrations = policyLists[0] ? xmlChildren(rootXml, policyLists[0]).filter(child => local(child) === 'policy') : [];
+  const attachments = [];
+  const references = [];
+  const unresolved = [];
+  const addUnresolved = (source, reason) => {
+    if (!unresolved.some(item => item.source === source && item.reason === reason)) unresolved.push({ source, reason });
+  };
+  const addReference = (source, kind, raw, dynamic = false) => {
+    const alias = !dynamic && identifier(raw);
+    if (alias) {
+      if (!references.some(item => item.source === source && item.kind === kind && item.name === alias)) references.push({ source, kind, name: alias });
+    } else addUnresolved(source, `dynamic_or_unrecognized_${kind}`);
+  };
+  const scanReferences = (xml, element, source) => {
+    const attributes = xmlAttributes(xml, element);
+    if (attributes.ref) addUnresolved(source, 'dynamic_policy_reference');
+    if (local(element) === 'KeyValueMapOperations') {
+      if (attributes.mapIdentifier !== undefined) addReference(source, 'kvm', attributes.mapIdentifier, Boolean(attributes.ref));
+      else addUnresolved(source, 'dynamic_or_unrecognized_kvm');
+    }
+    const kind = ({ KeyStore: 'keystore', TrustStore: 'truststore', KeyAlias: 'certificate', CertificateAlias: 'certificate', certificate_alias: 'certificate', provider_id: 'provider', Provider: 'provider', APIProvider: 'provider' })[local(element)];
+    if (kind) addReference(source, kind, xmlText(xml, element), Boolean(attributes.ref) || xmlChildren(xml, element).length > 0);
+    for (const child of xmlChildren(xml, element)) scanReferences(xml, child, source);
+  };
+  const policies = names.map((policyName, index) => {
+    if (!identifier(policyName)) throw new IntegrationError('API proxy has an unsupported policy identity');
+    const path = `${layout.dir}Policy/${policyName}.xml`;
+    const registeredType = identifier(xmlAttributes(rootXml, registrations[index]).type);
+    if (!files.has(path)) {
+      addUnresolved(policyName, 'missing_policy_document');
+      return { name: policyName, registered_type: registeredType, type: null, document_present: false };
+    }
+    const xml = text(files, path);
+    const policy = xmlLocate(xml, []);
+    const type = identifier(local(policy));
+    if (['Javascript', 'PythonScript', 'JavaCallout', 'ServiceCallout'].includes(type)) addUnresolved(policyName, 'custom_or_dynamic_behavior');
+    const known = new Set(['AccessControl', 'AssignMessage', 'BasicAuth', 'DecodeJWT', 'ExtractVariable', 'GenerateJWT', 'GenerateSAMLAssertion', 'GetOAuthV2Info', 'Javascript', 'JSONThreatProtection', 'KeyValueMapOperations', 'LookupCache', 'OAuthV2', 'PopulateCache', 'PythonScript', 'Quota', 'RaiseFault', 'RegularExpressionProtection', 'ResponseCache', 'ServiceCallout', 'SetOAuthV2Info', 'SpikeArrest', 'ValidateSAMLAssertion', 'VerifyAPIKey', 'VerifyJWT', 'XMLThreatProtection']);
+    if (!known.has(type)) addUnresolved(policyName, 'unrecognized_policy_type');
+    if (registeredType && registeredType !== type) addUnresolved(policyName, 'policy_type_mismatch');
+    scanReferences(xml, policy, policyName);
+    return { name: policyName, registered_type: registeredType, type, document_present: true };
+  });
+  for (const [folder, endpoint] of [['APIProxyEndPoint', 'proxy'], ['APITargetEndPoint', 'target']]) {
+    for (const path of files.keys()) {
+      if (!path.startsWith(`${layout.dir}${folder}/`) || !path.endsWith('.xml')) continue;
+      const xml = text(files, path);
+      const endpointRoot = xmlLocate(xml, []);
+      const endpointName = identifier(value(xml, endpointRoot, 'name'));
+      const source = `${endpoint}:${endpointName ?? 'unknown'}`;
+      scanReferences(xml, endpointRoot, source);
+      const walk = (element, context) => {
+        const tag = local(element);
+        const next = { ...context };
+        if (['preFlow', 'postFlow', 'conditionalFlows', 'faultRules', 'defaultFaultRule'].includes(tag)) next.flow = tag;
+        if (tag === 'request' || tag === 'response') next.phase = tag;
+        if (tag === 'condition' && xmlText(xml, element)) return;
+        if (tag === 'step' || tag === 'Step') {
+          const policyName = identifier(value(xml, element, 'policy_name') ?? value(xml, element, 'Name'));
+          if (policyName) {
+            const condition = value(xml, element, 'condition') ?? value(xml, element, 'Condition');
+            attachments.push({ policy_name: policyName, endpoint, endpoint_name: endpointName, flow: next.flow ?? 'unknown', phase: next.phase ?? 'unknown', condition_present: Boolean(condition?.trim()) || Boolean(next.condition_present), registered: names.includes(policyName) });
+          } else addUnresolved(source, 'unrecognized_policy_attachment');
+        }
+        const condition = value(xml, element, 'condition') ?? value(xml, element, 'Condition');
+        if (condition?.trim()) next.condition_present = true;
+        for (const child of xmlChildren(xml, element)) walk(child, next);
+      };
+      walk(endpointRoot, {});
+    }
+  }
+  const unregisteredPolicyFiles = [...files.keys()].filter(path => path.startsWith(`${layout.dir}Policy/`) && path.endsWith('.xml') && !names.some(policyName => path === `${layout.dir}Policy/${policyName}.xml`)).map(path => identifier(path.slice(`${layout.dir}Policy/`.length, -4)) ?? 'unrecognized_identity');
+  if ([...files.keys()].some(path => path.startsWith(`${layout.dir}FileResource/`))) addUnresolved('file_resources', 'custom_or_dynamic_behavior');
+  const bundle_sha256 = bundleDigest(files);
+  return {
+    name, evidence: 'static_bundle', bundle_sha256, state_sha256: stateDigest(bundle_sha256), policies, attachments,
+    unregistered_policy_files: unregisteredPolicyFiles,
+    unattached_policies: names.filter(policyName => !attachments.some(item => item.policy_name === policyName)),
+    references, jwt_issuers: bundleJwtIssuers(files, name), unresolved,
+    effective_authentication: 'unverified', certificate_trust: 'unverified', effective_rate_limiting: 'unverified'
+  };
+}
+
+export async function inspectApiProxySecurity(client, name, { deadline } = {}) {
+  const files = await exportApiProxyBundle(client, name, { deadline });
+  if (!files) throw new IntegrationError(`API proxy ${name} does not exist`);
+  return inspectApiProxyBundle(files, name);
+}
+
+function safeRuntimeUrl(raw) {
+  try {
+    const url = new URL(raw);
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    url.username = ''; url.password = ''; url.search = ''; url.hash = '';
+    return url.href;
+  } catch { return null; }
+}
+
+export function registerApimInspectionTools(register, client) {
+  const input = { name: z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/) };
+  register('apim_get_api_proxy_status', 'Get API proxy operational status',
+    'Read allowlisted management state and deployment metadata. Runtime health remains unverified; runtime URL excludes credentials and query.', input, READ_ONLY_ANNOTATIONS,
+    async ({ name }) => {
+      const proxy = await readApiProxy(client, name);
+      if (!proxy) throw new IntegrationError(`API proxy ${name} does not exist`);
+      const safeScalar = entry => typeof entry === 'number' || typeof entry === 'boolean' ? entry : typeof entry === 'string' && /^[A-Za-z0-9_. :+TZ-]{1,255}$/.test(entry) ? entry : null;
+      const rawDeployments = proxy.deploymentInfo;
+      const deployments = Array.isArray(rawDeployments) ? rawDeployments : rawDeployments ? [rawDeployments] : [];
+      return { name, state: safeScalar(proxy.state), version: safeScalar(proxy.version),
+        deployment_metadata: deployments.length ? deployments.map(item => Object.fromEntries(['state', 'status', 'version', 'revision', 'deployedAt', 'deploymentTime'].filter(key => item[key] !== undefined).map(key => [key, safeScalar(item[key])]))) : null,
+        runtime_url: safeRuntimeUrl(proxy.runtime_url), runtime_health: 'unverified' };
+    });
+  register('apim_inspect_api_proxy_security', 'Inspect API proxy static security evidence',
+    'Privately inspect exported policy registrations, attachments and identifiable dependency aliases. Returns digests and static metadata, never source or proof of effective security.', input, READ_ONLY_ANNOTATIONS,
+    ({ name }) => inspectApiProxySecurity(client, name));
+}