sap-ai-dev-toolkit 0.9.9917 → 0.9.9920

package/src/apim-bundle.mjs

@@ -19,7 +19,13 @@ export function xmlEscape(value) {
 }
 
 function xmlUnescape(value) {
-  return value.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&quot;', '"').replaceAll('&apos;', "'").replaceAll('&amp;', '&');
+  return value.replace(/&(?:#x([0-9a-f]+)|#([0-9]+)|(lt|gt|quot|apos|amp));/gi, (match, hex, decimal, named) => {
+    if (hex || decimal) {
+      const point = Number.parseInt(hex ?? decimal, hex ? 16 : 10);
+      return point > 0 && point <= 0x10ffff && !(point >= 0xd800 && point <= 0xdfff) ? String.fromCodePoint(point) : match;
+    }
+    return { lt: '<', gt: '>', quot: '"', apos: "'", amp: '&' }[named.toLowerCase()];
+  });
 }
 
 function proxyXml({ name, title, description, serviceType }) {
@@ -95,7 +101,7 @@ function locate(xml, path) {
   let element = childElements(xml, 0, xml.length)[0];
   if (!element) throw new IntegrationError('API proxy bundle XML has no root element');
   for (const name of path) {
-    element = children(xml, element).find(child => child.name === name);
+    element = children(xml, element).find(child => child.name.split(':').at(-1) === name);
     if (!element) return undefined;
   }
   return element;
@@ -145,24 +151,28 @@ function registerRootEntry(xml, listTag, entryTag, type, name, before = []) {
 
 function rootEntryNames(xml, listTag, entryTag) {
   const listElement = locate(xml, [listTag]);
-  return listElement ? children(xml, listElement).filter(child => child.name === entryTag).map(child => textOf(xml, child)) : [];
+  return listElement ? children(xml, listElement).filter(child => child.name.split(':').at(-1) === entryTag).map(child => textOf(xml, child)) : [];
 }
 
-/** Append a policy step to an endpoint flow (created when missing); an existing step for the policy is kept. */
+/** Append a step, or update only an explicitly supplied condition on its exact assignment. */
 function addStep(xml, flowTag, phase, policyName, condition) {
   const flowName = flowTag === 'preFlow' ? 'PreFlow' : 'PostFlow';
+  selectedSteps(xml, flowTag === 'preFlow' ? 'pre' : 'post', phase);
   xml = ensureChild(xml, [], flowTag, `<name>${flowName}</name>`, flowTag === 'preFlow' ? ['postFlow', 'conditionalFlows'] : ['conditionalFlows']);
   xml = ensureChild(xml, [flowTag], phase, `<isRequest>${phase === 'request'}</isRequest><steps></steps>`, phase === 'request' ? ['response'] : []);
   xml = ensureChild(xml, [flowTag, phase], 'steps');
   const steps = locate(xml, [flowTag, phase, 'steps']);
-  let sequence = 0;
-  for (const step of children(xml, steps).filter(child => child.name === 'step')) {
-    const fields = children(xml, step);
-    const field = name => fields.find(child => child.name === name);
-    if (field('policy_name') && textOf(xml, field('policy_name')) === policyName) return { xml, added: false };
-    const value = Number(field('sequence') ? textOf(xml, field('sequence')) : NaN);
-    if (Number.isFinite(value)) sequence = Math.max(sequence, value);
+  const assignments = supportedSteps(xml, steps);
+  const matches = assignments.filter(step => step.policy_name === policyName);
+  if (matches.length > 1) throw new IntegrationError('API proxy has ambiguous duplicate policy assignments');
+  if (matches.length) {
+    const existing = matches[0];
+    if (condition === undefined) return { xml, added: false };
+    const changed = setStepField(xml.slice(existing.element.start, existing.element.end), 'condition', condition);
+    return { xml: splice(xml, existing.element.start, existing.element.end, changed), added: false };
   }
+  let sequence = 0;
+  for (const assignment of assignments) sequence = Math.max(sequence, assignment.sequence);
   const step = `<step><policy_name>${xmlEscape(policyName)}</policy_name><condition>${xmlEscape(condition ?? '')}</condition><sequence>${sequence + 1}</sequence></step>`;
   return { xml: splice(xml, steps.contentEnd, steps.contentEnd, step), added: true };
 }
@@ -203,6 +213,275 @@ export function bundlePolicyNames(files, proxyName) {
   return rootEntryNames(readText(files, proxyLayout(files, proxyName).root), 'policies', 'policy');
 }
 
+/** Explicit HTTPS issuers from registered VerifyJWT policies, never unregistered files or variable refs. */
+export function bundleJwtIssuers(files, proxyName) {
+  const layout = proxyLayout(files, proxyName);
+  const rootXml = readText(files, layout.root);
+  const localName = element => element.name.split(':').at(-1);
+  const policyLists = children(rootXml, locate(rootXml, [])).filter(element => localName(element) === 'policies');
+  if (policyLists.length > 1) throw new IntegrationError('API proxy bundle has ambiguous policy registrations');
+  const policies = policyLists[0];
+  const issuers = new Set();
+  for (const entry of policies ? children(rootXml, policies) : []) {
+    if (localName(entry) !== 'policy') continue;
+    const name = textOf(rootXml, entry);
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)) continue;
+    const path = `${layout.dir}Policy/${name}.xml`;
+    if (!files.has(path)) continue;
+    const xml = readText(files, path);
+    const root = locate(xml, []);
+    if (localName(root) !== 'VerifyJWT') continue;
+    for (const issuer of children(xml, root).filter(element => localName(element) === 'Issuer')) {
+      if (children(xml, issuer).length || /\bref\s*=/.test(xml.slice(issuer.start, issuer.contentStart))) continue;
+      const raw = xml.slice(issuer.contentStart, issuer.contentEnd).trim();
+      const value = raw.startsWith('<![CDATA[') && raw.endsWith(']]>') ? raw.slice(9, -3).trim() : textOf(xml, issuer);
+      if (/[{}\s]/.test(value)) continue;
+      try {
+        const url = new URL(value);
+        if (url.protocol === 'https:' && !url.username && !url.password && !url.hash && !url.search) issuers.add(value);
+      } catch { /* Dynamic or malformed issuer text is not a trusted endpoint. */ }
+    }
+  }
+  return [...issuers];
+}
+
+// Shared structural scanner for read-only inspection and surgical policy editing.
+export { childElements, children as xmlChildren, locate as xmlLocate, textOf as xmlText, proxyLayout as apiProxyLayout };
+
+const localName = element => element?.name?.split(':').at(-1) ?? '';
+const oneChild = (xml, parent, name, required = false) => {
+  const matches = children(xml, parent).filter(child => localName(child) === name);
+  if (matches.length > 1 || (required && matches.length !== 1)) throw new IntegrationError(`Ambiguous API proxy policy layout: expected one ${name}`);
+  if (matches[0] && matches[0].name !== name) throw new IntegrationError('Unsupported namespaced API proxy assignment layout');
+  return matches[0];
+};
+
+function supportedSteps(xml, container) {
+  const elements = children(xml, container);
+  if (elements.some(element => element.name !== 'step')) throw new IntegrationError('Unsupported API proxy steps layout');
+  const result = elements.map(element => {
+    const policy = oneChild(xml, element, 'policy_name', true);
+    const condition = oneChild(xml, element, 'condition');
+    const sequence = oneChild(xml, element, 'sequence', true);
+    if (children(xml, element).some(child => !['policy_name', 'condition', 'sequence'].includes(child.name))
+      || [policy, condition, sequence].filter(Boolean).some(child => children(xml, child).length)) {
+      throw new IntegrationError('Unsupported API proxy step fields');
+    }
+    const policy_name = textOf(xml, policy);
+    const order = textOf(xml, sequence);
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,99}$/.test(policy_name) || !/^[1-9]\d*$/.test(order) || !Number.isSafeInteger(Number(order))) {
+      throw new IntegrationError('Unsupported API proxy step identity or sequence');
+    }
+    return { element, policy_name, condition: condition ? textOf(xml, condition) : '', sequence: Number(order) };
+  });
+  if (new Set(result.map(item => item.policy_name)).size !== result.length
+    || new Set(result.map(item => item.sequence)).size !== result.length) {
+    throw new IntegrationError('API proxy has ambiguous duplicate policy assignments or sequences');
+  }
+  if (result.some((item, index) => index && item.sequence <= result[index - 1].sequence)) {
+    throw new IntegrationError('API proxy step XML order disagrees with sequence order');
+  }
+  return result;
+}
+
+function setStepField(xml, name, value) {
+  const root = locate(xml, []);
+  const field = oneChild(xml, root, name);
+  if (field) return field.selfClosing ? expand(xml, field, xmlEscape(value))
+    : splice(xml, field.contentStart, field.contentEnd, xmlEscape(value));
+  return splice(xml, root.contentEnd, root.contentEnd, `<${name}>${xmlEscape(value)}</${name}>`);
+}
+
+function policyEditLayout(files, proxyName, endpoint, endpointName) {
+  const layout = proxyLayout(files, proxyName);
+  const rootXml = readText(files, layout.root);
+  const roots = [...files.keys()].filter(path => path.startsWith(layout.dir) && path.endsWith('.xml') && !path.slice(layout.dir.length).includes('/'));
+  if (roots.length !== 1 || locate(rootXml, []).name !== 'APIProxy'
+    || textOf(rootXml, oneChild(rootXml, locate(rootXml, []), 'name', true)) !== proxyName) {
+    throw new IntegrationError('Ambiguous API proxy root identity');
+  }
+  const folder = `${layout.dir}${endpoint === 'proxy' ? 'APIProxyEndPoint' : 'APITargetEndPoint'}/`;
+  const matches = [];
+  for (const path of files.keys()) {
+    if (!path.startsWith(folder) || !path.endsWith('.xml')) continue;
+    const xml = readText(files, path);
+    const root = locate(xml, []);
+    if (root.name !== (endpoint === 'proxy' ? 'ProxyEndPoint' : 'TargetEndPoint')) throw new IntegrationError('Unsupported API proxy endpoint layout');
+    if (textOf(xml, oneChild(xml, root, 'name', true)) === endpointName) matches.push({ path, xml });
+  }
+  if (matches.length !== 1) throw new IntegrationError('Expected one exact named API proxy endpoint');
+  return { ...layout, rootXml, ...matches[0] };
+}
+
+function selectedSteps(xml, flow, phase, create = false) {
+  const flowTag = flow === 'pre' ? 'preFlow' : 'postFlow';
+  const root = locate(xml, []);
+  const flowElement = oneChild(xml, root, flowTag);
+  const phaseElement = flowElement && oneChild(xml, flowElement, phase);
+  const steps = phaseElement && oneChild(xml, phaseElement, 'steps');
+  if (!create) return { xml, steps, assignments: steps ? supportedSteps(xml, steps) : [] };
+  xml = ensureChild(xml, [], flowTag, `<name>${flow === 'pre' ? 'PreFlow' : 'PostFlow'}</name>`, flow === 'pre' ? ['postFlow', 'conditionalFlows'] : ['conditionalFlows']);
+  xml = ensureChild(xml, [flowTag], phase, `<isRequest>${phase === 'request'}</isRequest><steps/>`, phase === 'request' ? ['response'] : []);
+  xml = ensureChild(xml, [flowTag, phase], 'steps');
+  return selectedSteps(xml, flow, phase);
+}
+
+/** Private full reference inventory, including conditional/fault and unknown assignment locations. */
+function policyReferences(files, layout) {
+  const references = new Set();
+  let unknown = false;
+  for (const [path] of files) {
+    if (!path.startsWith(layout.dir) || !path.endsWith('.xml')) continue;
+    const xml = readText(files, path);
+    const roots = childElements(xml, 0, xml.length);
+    if (roots.length !== 1) throw new IntegrationError('Ambiguous API proxy XML document');
+    const walk = (element, parent) => {
+      const tag = localName(element);
+      const fields = children(xml, element);
+      const attributes = xmlAttributes(xml, element);
+      if ((tag === 'steps' || tag === 'Steps') && fields.some(child => !['step', 'Step'].includes(localName(child)))) unknown = true;
+      if (/step/i.test(tag) && !['step', 'Step', 'steps', 'Steps'].includes(tag)) unknown = true;
+      if (tag === 'step' || tag === 'Step') {
+        const identities = fields.filter(child => ['policy_name', 'Name'].includes(localName(child)));
+        if (identities.length !== 1 || fields.some(child => !['policy_name', 'Name', 'condition', 'Condition', 'sequence'].includes(localName(child)))
+          || Object.keys(attributes).some(name => name !== 'name')) unknown = true;
+        if (identities.length === 1 && !children(xml, identities[0]).length) {
+          const name = textOf(xml, identities[0]);
+          if (/^[A-Za-z][A-Za-z0-9_-]{0,99}$/.test(name)) references.add(name);
+          else unknown = true;
+        } else unknown = true;
+      }
+      if (['policy_name', 'policyName', 'PolicyName', 'policyRef', 'PolicyRef', 'policy_ref'].includes(tag)) {
+        const name = textOf(xml, element);
+        if (fields.length || Object.keys(attributes).length || !/^[A-Za-z][A-Za-z0-9_-]{0,99}$/.test(name)) unknown = true;
+        else references.add(name);
+      }
+      if ((tag === 'policy' || tag === 'Policy') && !(path === layout.root && localName(parent ?? {}) === 'policies')) unknown = true;
+      if (/policy/i.test(tag) && !['policy', 'Policy', 'policy_name', 'policyName', 'PolicyName', 'policyRef', 'PolicyRef', 'policy_ref'].includes(tag)) unknown = true;
+      if (Object.keys(attributes).some(name => /policy/i.test(name))) unknown = true;
+      for (const child of fields) walk(child, element);
+    };
+    walk(roots[0]);
+  }
+  return { references, unknown };
+}
+
+/** Surgical complete-order edit for one exact assignment; never regenerate endpoints or shared resources. */
+export function editPolicySteps(files, proxyName, { endpoint, endpoint_name, flow, phase, steps, remove_unreferenced = [] }) {
+  const layout = policyEditLayout(files, proxyName, endpoint, endpoint_name);
+  const policyList = oneChild(layout.rootXml, locate(layout.rootXml, []), 'policies');
+  const registrations = policyList ? children(layout.rootXml, policyList) : [];
+  if (registrations.some(element => element.name !== 'policy' || children(layout.rootXml, element).length)) throw new IntegrationError('Unsupported API proxy policy registrations');
+  const registered = registrations.map(element => textOf(layout.rootXml, element));
+  if (new Set(registered).size !== registered.length) throw new IntegrationError('Ambiguous API proxy policy registrations');
+  if (new Set(steps.map(step => step.policy_name)).size !== steps.length || new Set(remove_unreferenced).size !== remove_unreferenced.length) {
+    throw new IntegrationError('Duplicate requested policy identities');
+  }
+  for (const step of steps) {
+    if (!registered.includes(step.policy_name) || !files.has(`${layout.dir}Policy/${step.policy_name}.xml`)) {
+      throw new IntegrationError('Every desired policy must have one existing registration and policy document');
+    }
+  }
+  const selected = selectedSteps(layout.xml, flow, phase, true);
+  let xml = selected.xml;
+  const desired = steps.map((step, index) => {
+    const existing = selected.assignments.find(item => item.policy_name === step.policy_name);
+    let body = existing ? xml.slice(existing.element.start, existing.element.end)
+      : `<step><policy_name>${xmlEscape(step.policy_name)}</policy_name><condition></condition><sequence>1</sequence></step>`;
+    if (step.condition !== undefined) body = setStepField(body, 'condition', step.condition);
+    return setStepField(body, 'sequence', index + 1);
+  });
+  if (selected.steps.selfClosing) xml = expand(xml, selected.steps, desired.join(''));
+  else {
+    const changes = selected.assignments.map((assignment, index) => ({ start: assignment.element.start, end: assignment.element.end, text: desired[index] ?? '' }));
+    if (desired.length > changes.length) changes.push({ start: selected.steps.contentEnd, end: selected.steps.contentEnd, text: desired.slice(changes.length).join('') });
+    for (const change of changes.sort((a, b) => b.start - a.start)) xml = splice(xml, change.start, change.end, change.text);
+  }
+  // Work on a private candidate until every deletion precondition passes.
+  const candidate = new Map(files);
+  writeText(candidate, layout.path, xml);
+  const inventory = policyReferences(candidate, layout);
+  for (const name of remove_unreferenced) {
+    if (!registered.includes(name) || !candidate.has(`${layout.dir}Policy/${name}.xml`)) throw new IntegrationError('Policy removal requires an existing registration and document');
+    if (inventory.unknown || inventory.references.has(name)) throw new IntegrationError('Policy removal blocked by retained or unknown policy references');
+  }
+  let rootXml = layout.rootXml;
+  for (const entry of registrations.filter(element => remove_unreferenced.includes(textOf(layout.rootXml, element))).sort((a, b) => b.start - a.start)) {
+    rootXml = splice(rootXml, entry.start, entry.end, '');
+  }
+  if (remove_unreferenced.length) writeText(candidate, layout.root, rootXml);
+  for (const name of remove_unreferenced) candidate.delete(`${layout.dir}Policy/${name}.xml`);
+  const assignments = selectedSteps(xml, flow, phase).assignments;
+  for (const [path, bytes] of candidate) files.set(path, bytes);
+  for (const name of remove_unreferenced) files.delete(`${layout.dir}Policy/${name}.xml`);
+  return {
+    endpoint, endpoint_name, flow, phase,
+    steps: assignments.map(item => ({ policy_name: item.policy_name, sequence: item.sequence, condition_present: Boolean(item.condition.trim()) })),
+    removed_policies: remove_unreferenced
+  };
+}
+
+export function xmlAttributes(xml, element) {
+  const attributes = {};
+  const opening = xml.slice(element.start, element.contentStart);
+  const pattern = /([A-Za-z_][\w.:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+  for (const match of opening.matchAll(pattern)) attributes[match[1].split(':').at(-1)] = xmlUnescape(match[2] ?? match[3]);
+  return attributes;
+}
+
+/** Locate only the unambiguous, registered SAP SWAGGER_JSON English documentation layout. */
+export function bundleDocumentation(files, proxyName) {
+  const { root, dir } = proxyLayout(files, proxyName);
+  const xml = readText(files, root);
+  const rootElement = locate(xml, []);
+  if (rootElement.name.split(':').at(-1) !== 'APIProxy') throw new IntegrationError('Unsupported API documentation layout: root is not APIProxy');
+  const rootFiles = [...files.keys()].filter(path => path.startsWith(dir) && path.endsWith('.xml') && !path.slice(dir.length).includes('/'));
+  if (rootFiles.length !== 1) throw new IntegrationError('Unsupported API documentation layout: ambiguous root XML');
+  const one = (source, parent, name) => {
+    const matches = children(source, parent).filter(element => element.name.split(':').at(-1) === name);
+    if (matches.length !== 1) throw new IntegrationError(`Unsupported API documentation layout: expected one ${name}`);
+    return matches[0];
+  };
+  if (textOf(xml, one(xml, rootElement, 'name')) !== proxyName) throw new IntegrationError('API documentation proxy name does not match bundle');
+  const endpointList = one(xml, rootElement, 'proxyEndPoints');
+  const endpoints = children(xml, endpointList).filter(element => element.name.split(':').at(-1) === 'proxyEndPoint');
+  if (endpoints.length !== 1 || textOf(xml, one(xml, endpoints[0], 'apiResourceName')) !== 'SWAGGER_JSON') {
+    throw new IntegrationError('Unsupported API documentation layout: expected a single SWAGGER_JSON endpoint registration');
+  }
+  const endpointName = textOf(xml, one(xml, endpoints[0], 'proxyEndPointName'));
+  const resourcePath = `${dir}APIResource/SWAGGER_JSON.xml`;
+  const documentationPath = `${dir}Documentation/SWAGGER_JSON_en.html`;
+  if (!files.has(resourcePath) || !files.has(documentationPath)) throw new IntegrationError('Unsupported API documentation layout: registered resource or document is missing');
+  const resource = readText(files, resourcePath);
+  const resourceRoot = locate(resource, []);
+  if (resourceRoot.name.split(':').at(-1) !== 'APIResource') throw new IntegrationError('Unsupported API documentation layout: resource is not APIResource');
+  if (textOf(resource, one(resource, resourceRoot, 'name')) !== 'SWAGGER_JSON') throw new IntegrationError('API documentation resource name does not match registration');
+  if (textOf(resource, one(resource, resourceRoot, 'resource_path')) !== 'SWAGGER_JSON'
+    || !endpointName || textOf(resource, one(resource, resourceRoot, 'proxyEndPointName')) !== endpointName) {
+    throw new IntegrationError('API documentation resource path or endpoint does not match registration');
+  }
+  const docs = one(resource, resourceRoot, 'documentations');
+  const english = children(resource, docs).filter(element => element.name.split(':').at(-1) === 'documentation');
+  if (english.length !== 1) throw new IntegrationError('Unsupported API documentation layout: expected one documentation');
+  const entry = english[0];
+  const opening = resource.slice(entry.start, entry.contentStart);
+  const attribute = name => {
+    const values = [...opening.matchAll(new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:\"([^\"]*)\"|'([^']*)')`, 'g'))];
+    return values.length === 1 ? xmlUnescape(values[0][1] ?? values[0][2]) : undefined;
+  };
+  if (attribute('locale') !== 'en' || attribute('mimeType') !== 'json' || children(resource, entry).length || textOf(resource, entry) !== 'SWAGGER_JSON') {
+    throw new IntegrationError('Unsupported API documentation layout: expected SWAGGER_JSON locale=en mimeType=json');
+  }
+  return { path: documentationPath, text: readText(files, documentationPath) };
+}
+
+/** Replace documentation bytes only; routing, provider and security resources remain untouched. */
+export function patchBundleDocumentation(files, proxyName, text) {
+  const { path } = bundleDocumentation(files, proxyName);
+  writeText(files, path, text);
+  return { path };
+}
+
 /**
  * Patch an exported bundle in place (Map path → bytes): root title/description/service_code when given,
  * proxy endpoint base_path, and the target head (url/provider_id/relativePath). Policies, steps,
@@ -302,7 +581,7 @@ export function policyDocuments(spec) {
       const steps = [place({ endpoint: 'target' })];
       const user = `private.${name}.user`;
       const password = `private.${name}.password`;
-      const get = (variable, entry) => `<Get assignTo="${xmlEscape(variable)}"><Key><Parameter>${xmlEscape(entry)}</Parameter></Key></Get>`;
+      const get = (variable, entry) => `<Get assignTo="${xmlEscape(variable)}" index="1"><Key><Parameter>${xmlEscape(entry)}</Parameter></Key></Get>`;
       return [
         {
           name: `${name}_kvm`,
@@ -316,7 +595,7 @@ export function policyDocuments(spec) {
           type: 'BasicAuth',
           xml: `${policyOpen('BasicAuthentication', 'true')}<Operation>Encode</Operation><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>`
             + `<User ref="${xmlEscape(user)}"></User><Password ref="${xmlEscape(password)}"></Password>`
-            + '<AssignTo createNew="false">request.header.Authorization</AssignTo></BasicAuthentication>',
+            + '<AssignTo createNew="true">request.header.Authorization</AssignTo></BasicAuthentication>',
           steps
         }
       ];
@@ -379,3 +658,127 @@ export function attachPolicies(files, proxyName, specs) {
   for (const { path, xml } of Object.values(endpoints)) writeText(files, path, xml);
   return { policies: documents.map(document => document.name), stepsAdded };
 }
+
+/**
+ * Select a backend from already verified JWT claims. Kept ES5-compatible because
+ * this same function is embedded in the gateway's JavaScript policy.
+ */
+export function selectAuthorizedBackend(claims, policy, now) {
+  if (!claims || claims.iss !== policy.issuer || claims.grant_type !== 'client_credentials'
+    || typeof claims.exp !== 'number' || !isFinite(claims.exp) || claims.exp <= now
+    || (claims.nbf !== undefined && (typeof claims.nbf !== 'number' || claims.nbf > now))
+    || !Array.isArray(claims.scope)) return null;
+  var prefix = policy.scopePrefix + '.';
+  var selected = null;
+  for (var i = 0; i < claims.scope.length; i += 1) {
+    var scope = claims.scope[i];
+    if (typeof scope !== 'string') return null;
+    if (scope.indexOf(prefix + 'S4') !== 0 || scope.slice(-7) !== '.Access') continue;
+    var system = scope.slice(prefix.length, -7);
+    if (policy.systems.indexOf(system) === -1 || (selected !== null && selected !== system)) return null;
+    selected = system;
+  }
+  var audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  return selected !== null && audiences.indexOf(prefix + selected) !== -1 ? selected : null;
+}
+
+/**
+ * Build one fully secured capability proxy with fixed provider-backed targets.
+ * Environment configuration changes at promotion; public names/paths do not.
+ * No credentials or caller-supplied target identifiers belong in this config.
+ */
+export function buildRoutedApiProxyBundle(config) {
+  const { name, title, description = 'OAuth client credentials; backend selected by one authorized system scope.',
+    basePath, serviceType, backendPath, issuer, jwksUrl, scopePrefix, environment, systems, vimVersion = false } = config;
+  if (!['production', 'non-production'].includes(environment)) throw new IntegrationError('An explicit deployment environment is required');
+  if (!Array.isArray(systems) || !systems.length) throw new IntegrationError('At least one fixed backend system is required');
+  if (new Set(systems.map(system => system.id)).size !== systems.length) throw new IntegrationError('Duplicate system route authorities are not allowed');
+  if (systems.some(system => !/^S4[DTQP](?:\d{3})?$/.test(system.id) || !system.provider || !system.kvm)) {
+    throw new IntegrationError('Every route requires a fixed S4 system, API provider and encrypted KVM name');
+  }
+  if (new Set(systems.map(system => system.id.charAt(2))).size !== systems.length) {
+    throw new IntegrationError('Duplicate backend credential-policy names are not allowed; configure one client per system');
+  }
+  if (environment === 'production' && (systems.length !== 1 || !/^S4P(?:\d{3})?$/.test(systems[0].id))) {
+    throw new IntegrationError('A production deployment must contain only one S4P backend');
+  }
+  if (environment === 'non-production' && systems.some(system => /^S4P/.test(system.id))) {
+    throw new IntegrationError('A non-production deployment cannot contain an S4P backend');
+  }
+  const issuerUrl = new URL(issuer);
+  const keysUrl = new URL(jwksUrl);
+  if (issuerUrl.protocol !== 'https:' || keysUrl.protocol !== 'https:' || keysUrl.origin !== issuerUrl.origin
+    || issuerUrl.username || issuerUrl.password || keysUrl.username || keysUrl.password
+    || issuerUrl.search || issuerUrl.hash || keysUrl.search || keysUrl.hash) {
+    throw new IntegrationError('JWKS must use the trusted HTTPS issuer origin without embedded credentials or query parameters');
+  }
+  if (!scopePrefix) throw new IntegrationError('The trusted application scope prefix is required');
+  const files = new Map();
+  const rootPath = `APIProxy/${name}.xml`;
+  const proxyPath = 'APIProxy/APIProxyEndPoint/default.xml';
+  const endpointName = index => index === 0 ? 'default' : systems[index].id;
+  let root = proxyXml({ name, title: title ?? name, description, serviceType });
+  const targets = locate(root, ['targetEndPoints']);
+  root = splice(root, targets.contentStart, targets.contentEnd,
+    systems.map((system, index) => `<targetEndPoint>${xmlEscape(endpointName(index))}</targetEndPoint>`).join(''));
+  writeText(files, rootPath, root);
+  let proxy = proxyEndPointXml(basePath);
+  const routes = locate(proxy, ['routeRules']);
+  proxy = splice(proxy, routes.contentStart, routes.contentEnd, systems.map((system, index) =>
+    `<routeRule><name>route${xmlEscape(system.id)}</name><conditions>${xmlEscape(`private.backendSystem = "${system.id}"`)}</conditions>`
+    + `<targetEndPointName>${xmlEscape(endpointName(index))}</targetEndPointName><sequence>${index + 1}</sequence><faultRules/></routeRule>`).join(''));
+  writeText(files, proxyPath, proxy);
+  const policy = { issuer, scopePrefix, systems: systems.map(system => system.id) };
+  const script = `${selectAuthorizedBackend.toString()}\n`
+    + 'var backend = null;\n'
+    + 'if (String(context.getVariable("jwt.VerifyClientCredentialsJWT.valid")) === "true") {\n'
+    + `  backend = selectAuthorizedBackend(JSON.parse(String(context.getVariable("jwt.VerifyClientCredentialsJWT.payload-json"))), ${JSON.stringify(policy)}, new Date().getTime() / 1000);\n`
+    + '}\ncontext.setVariable("private.backendSystem", backend === null ? "" : backend);\n'
+    + 'context.setVariable("private.backendAuthorized", backend === null ? "false" : "true");\n';
+  // Scope and its corresponding audience are checked together by the selector.
+  // VerifyJWT's multi-value Audience requires all values, not any one system.
+  const custom = (policyName, type, xml, condition) => ({
+    name: policyName, template: 'custom', endpoint: 'proxy', flow: 'pre', phase: 'request', condition, params: { type, xml }
+  });
+  attachPolicies(files, name, [
+    { name: 'NormalizeBackendEncoding', template: 'assign_headers', params: { message: 'request', set: { 'Accept-Encoding': 'gzip, deflate' } } },
+    custom('ExtractOAuthBearer', 'ExtractVariable',
+      `${policyOpen('ExtractVariables')}<Source>request</Source><Header name="Authorization"><Pattern ignoreCase="true">Bearer {access_token}</Pattern></Header>`
+      + '<VariablePrefix>private.oauth</VariablePrefix><IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables></ExtractVariables>'),
+    custom('FetchOAuthJwks', 'ServiceCallout',
+      `${policyOpen('ServiceCallout')}<Request clearPayload="true" variable="oauthJwksRequest"><Remove><Headers>`
+      + '<Header name="Authorization"/><Header name="Cookie"/><Header name="apikey"/></Headers></Remove>'
+      + '<Set><Headers><Header name="Accept">application/json</Header></Headers><Verb>GET</Verb></Set>'
+      + '<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables></Request><Response>oauthJwksResponse</Response><Timeout>10000</Timeout>'
+      + `<HTTPTargetConnection><URL>${xmlEscape(jwksUrl)}</URL></HTTPTargetConnection></ServiceCallout>`,
+      '(private.oauth.access_token != null) and (private.oauth.access_token != "")'),
+    custom('VerifyClientCredentialsJWT', 'VerifyJWT',
+      `${policyOpen('VerifyJWT')}<Algorithm>RS256</Algorithm><Source>private.oauth.access_token</Source><IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>`
+      + `<PublicKey><JWKS ref="oauthJwksResponse.content"/></PublicKey><Issuer>${xmlEscape(issuer)}</Issuer>`
+      + '<AdditionalClaims><Claim name="grant_type" type="string">client_credentials</Claim></AdditionalClaims></VerifyJWT>'),
+    { name: 'SelectAuthorizedBackend', template: 'javascript', params: { file: 'select-authorized-backend', script } },
+    { name: 'RejectUnauthorizedBackend', template: 'raise_fault', condition: 'private.backendAuthorized != "true"',
+      params: { status_code: 403, reason_phrase: 'Forbidden', content_type: 'application/json',
+        payload: '{"error":"Exactly one authorized system scope and its matching audience are required."}' } }
+  ]);
+  root = readText(files, rootPath);
+  for (const [index, system] of systems.entries()) {
+    const targetName = endpointName(index);
+    let target = targetEndPointXml({ provider: system.provider, relativePath: backendPath });
+    target = setRootText(target, 'name', targetName);
+    target = setRootText(target, 'isDefault', index === 0 ? 'true' : 'false');
+    const specs = [{ name: `SAPBackend${system.id.slice(2, 3)}`, template: 'basic_auth_from_kvm',
+      params: { kvm: system.kvm, user_key: 'username', password_key: 'password' } }];
+    if (vimVersion) specs.push({ name: 'VIMVersion', template: 'custom', endpoint: 'target', params: { type: 'AssignMessage',
+      xml: `${policyOpen('AssignMessage')}<Set><QueryParams><QueryParam name="version">1</QueryParam></QueryParams></Set>`
+        + '<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables><AssignTo createNew="false" type="request"/></AssignMessage>' } });
+    for (const document of specs.flatMap(policyDocuments)) {
+      root = registerRootEntry(root, 'policies', 'policy', document.type, document.name, ['fileResources']);
+      writeText(files, `APIProxy/Policy/${document.name}.xml`, `${XML_HEADER}\n${document.xml}`);
+      for (const step of document.steps) target = addStep(target, step.flow, step.phase, document.name, step.condition).xml;
+    }
+    writeText(files, `APIProxy/APITargetEndPoint/${targetName}.xml`, target);
+  }
+  writeText(files, rootPath, root);
+  return zipSync(Object.fromEntries(files));
+}

package/src/apim-cleanup-tools.mjs

@@ -0,0 +1,145 @@
+// Explicit-set APIM cleanup orchestration; native lifecycle operations are injected.
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { confirmation, OVERWRITE_ANNOTATIONS, requireConfirmation } from './integration-common.mjs';
+
+const APIM_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,99}$/;
+const names = z.array(z.string().regex(APIM_NAME)).max(100)
+  .refine(value => new Set(value).size === value.length, 'names must be unique').default([]);
+const cleanupInput = z.object({
+  products: names,
+  proxies: names,
+  allow_deployed: z.boolean().default(false),
+  dry_run: z.boolean().default(true),
+  confirmation: confirmation.optional()
+}).strict().refine(value => value.products.length + value.proxies.length > 0, 'select at least one product or proxy')
+  .refine(value => value.products.length + value.proxies.length <= 200, 'select at most 200 objects');
+
+// Unknown and transitional states are never treated as safe inactive proxies.
+const INACTIVE_STATES = new Set(['CREATED', 'UNDEPLOYED']);
+
+function approvalFor(products, proxies, allow_deployed) {
+  const digest = createHash('sha256').update(JSON.stringify({ products, proxies, allow_deployed })).digest('hex');
+  return `DELETE APIM OBJECTS ${digest}`;
+}
+
+function validInspection(value, name, dependencyField) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.name !== name) return false;
+  const dependencies = value[dependencyField];
+  return dependencyField === 'blockingApplicationCount'
+    ? Number.isSafeInteger(dependencies) && dependencies >= 0
+    : Array.isArray(dependencies) && dependencies.every(dependency => typeof dependency === 'string' && dependency.length > 0);
+}
+
+async function inspect(name, operation, dependencyField) {
+  try {
+    const value = await operation(name);
+    if (value === null) return { entry: { name, status: 'already_absent', blockers: [] }, value: null };
+    if (!validInspection(value, name, dependencyField)) {
+      return { entry: { name, status: 'failed', blockers: [{ code: 'invalid_inspection' }] }, value: null };
+    }
+    return { entry: { name, status: 'ready', blockers: [] }, value };
+  } catch {
+    // Callback errors and complete tenant entities may contain hosts or credentials.
+    return { entry: { name, status: 'failed', blockers: [{ code: 'inspection_failed' }] }, value: null };
+  }
+}
+
+function verifiedOutcome(value) {
+  if (!value || typeof value !== 'object' || value.pending === true || value.verified === false
+    || value.deletion_verified === false) return null;
+  if (value.deleted === true && value.already_absent !== true) return 'deleted';
+  if (value.already_absent === true && value.deleted !== true) return 'already_absent';
+  return null;
+}
+
+export function registerApimCleanupTools(register, operations) {
+  register('apim_cleanup_api_objects', 'Clean up explicit API products and proxies',
+    'Preflight explicit product/proxy lists (maximum 100 each, 200 total); dry_run defaults to true. '
+      + 'Never discovers targets, cascades, or deletes providers, KVMs, applications or credentials. '
+      + 'Products with application dependencies and proxies with unselected or blocked product dependencies block the entire batch. '
+      + 'DEPLOYED proxies additionally require allow_deployed=true; unknown lifecycle states block cleanup. '
+      + 'Execute only with the exact required_confirmation from a dry run of the same lists and allow_deployed value: '
+      + 'DELETE APIM OBJECTS <SHA256 of JSON {products:sorted names,proxies:sorted names,allow_deployed}>. '
+      + 'Deletes products first, stops at the first error or unverified result, and never retries. '
+      + 'complete is true only after execution verifies every selected object deleted or already absent.',
+    cleanupInput, OVERWRITE_ANNOTATIONS,
+    async input => {
+      const { products, proxies, allow_deployed, dry_run, confirmation: approved } = cleanupInput.parse(input);
+      const productNames = [...products].sort();
+      const proxyNames = [...proxies].sort();
+      const required_confirmation = approvalFor(productNames, proxyNames, allow_deployed);
+      // Approval is bound to the exact explicit set and deployment permission before any reads.
+      if (!dry_run) requireConfirmation(approved, required_confirmation);
+
+      const productEntries = [];
+      for (const name of productNames) {
+        const { entry, value } = await inspect(name, operations.inspectProduct, 'blockingApplicationCount');
+        if (value?.blockingApplicationCount) {
+          entry.status = 'blocked';
+          entry.blockers.push({ code: 'application_dependencies', count: value.blockingApplicationCount });
+        }
+        productEntries.push(entry);
+      }
+      const selectedProducts = new Map(productEntries.map(entry => [entry.name, entry]));
+      const proxyEntries = [];
+      for (const name of proxyNames) {
+        const { entry, value } = await inspect(name, operations.inspectProxy, 'blockingProducts');
+        if (value) {
+          const blocking = value.blockingProducts.filter(product => {
+            const selected = selectedProducts.get(product);
+            return !selected || !['ready', 'already_absent'].includes(selected.status);
+          });
+          if (blocking.length) {
+            entry.blockers.push({ code: 'product_dependencies', count: blocking.length });
+          }
+          if (value.state === 'DEPLOYED') {
+            if (!allow_deployed) entry.blockers.push({ code: 'deployed_requires_approval' });
+          } else if (!INACTIVE_STATES.has(value.state)) {
+            entry.blockers.push({ code: 'unknown_lifecycle_state' });
+          }
+          if (entry.blockers.length) entry.status = 'blocked';
+        }
+        proxyEntries.push(entry);
+      }
+
+      const all = [...productEntries, ...proxyEntries];
+      const preflight_ok = all.every(entry => ['ready', 'already_absent'].includes(entry.status));
+      const result = {
+        dry_run, allow_deployed, required_confirmation, preflight_ok, complete: false,
+        products: productEntries, proxies: proxyEntries
+      };
+      if (dry_run) return result;
+      for (const entry of all) {
+        if (entry.status === 'ready') entry.status = 'not_attempted';
+      }
+      if (!preflight_ok) return result;
+
+      const queue = [
+        ...productEntries.map(entry => ({ entry, remove: () => operations.deleteProduct(entry.name) })),
+        ...proxyEntries.map(entry => ({ entry, remove: () => operations.deleteProxy(entry.name, { allow_deployed }) }))
+      ];
+      for (const { entry, remove } of queue) {
+        if (entry.status === 'already_absent') continue;
+        let outcome;
+        try {
+          outcome = verifiedOutcome(await remove());
+        } catch {
+          entry.status = 'failed';
+          entry.blockers.push({ code: 'deletion_failed' });
+          entry.deletion_verified = false;
+          return result;
+        }
+        if (!outcome) {
+          entry.status = 'failed';
+          entry.blockers.push({ code: 'deletion_unverified' });
+          entry.deletion_verified = false;
+          return result;
+        }
+        entry.status = outcome;
+        if (outcome === 'deleted') entry.deletion_verified = true;
+      }
+      result.complete = true;
+      return result;
+    });
+}