sap-ai-dev-toolkit 0.9.9917 → 0.9.9920

package/src/integration-optional-config.mjs

@@ -0,0 +1,122 @@
+// Optional service credentials are host/setup inputs, never tool-call inputs.
+// Keep this parser independent of the core CPI/APIM/Developer Hub OAuth shapes.
+export const OPTIONAL_INPUTS = Object.freeze({
+  ctms: Object.freeze({ variable: 'CTMS_SERVICE_KEY', label: 'Cloud Transport Management' }),
+  ans: Object.freeze({ variable: 'ANS_CONFIG', label: 'Alert Notification' }),
+  event_mesh: Object.freeze({ variable: 'EVENT_MESH_CONFIG', label: 'Event Mesh' }),
+  aem: Object.freeze({ variable: 'AEM_CONFIG', label: 'Advanced Event Mesh cloud' }),
+  aem_semp: Object.freeze({ variable: 'AEM_SEMP_CONFIG', label: 'Advanced Event Mesh broker SEMP' }),
+  open_connectors: Object.freeze({ variable: 'OPEN_CONNECTORS_CONFIG', label: 'Open Connectors' }),
+  edge: Object.freeze({ variable: 'EDGE_CONFIG', label: 'Edge Integration Cell' })
+});
+export const OPTIONAL_COMPONENT_KEYS = Object.freeze(Object.keys(OPTIONAL_INPUTS));
+
+const FIELDS = Object.freeze({
+  ctms: ['url', 'tokenUrl', 'clientId', 'clientSecret'],
+  ans: ['url', 'username', 'password'],
+  event_mesh: ['url', 'tokenUrl', 'clientId', 'clientSecret', 'probeQueueName'],
+  aem: ['apiToken'],
+  aem_semp: ['url', 'msgVpnName', 'username', 'password'],
+  open_connectors: ['url', 'userSecret', 'organizationSecret'],
+  edge: ['url', 'clientId', 'clientSecret']
+});
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const SOURCES = new Set(['environment', 'stored-key', 'setup', 'configuration']);
+
+function invalid(side, detail) {
+  // Only fixed field names and messages enter errors; never interpolate supplied values.
+  throw new Error(`${OPTIONAL_INPUTS[side].variable}: ${detail}`);
+}
+
+function endpoint(side, name, value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    invalid(side, `${name} must be a valid URL`);
+  }
+  if (parsed.username || parsed.password || value.includes('?') || value.includes('#')) {
+    invalid(side, `${name} must not contain credentials, a query, or a fragment`);
+  }
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && LOOPBACK_HOSTS.has(parsed.hostname))) {
+    invalid(side, `${name} must use https`);
+  }
+  return parsed;
+}
+
+/** Resolve a typed optional record. Raw cTMS service keys require explicit host/setup permission. */
+export function parseOptionalConfig(side, value, { source = 'configuration', allowRawCtms = false } = {}) {
+  if (!OPTIONAL_COMPONENT_KEYS.includes(side)) throw new Error('Unknown optional Integration Suite component');
+  let record = value;
+  if (typeof record === 'string') {
+    if (source === 'stored-key') invalid(side, 'stored configuration must be a normalized object');
+    try {
+      record = JSON.parse(record);
+    } catch {
+      invalid(side, 'configuration must be valid JSON');
+    }
+  }
+  if (!record || typeof record !== 'object' || Array.isArray(record)) invalid(side, 'configuration must be an object');
+  if (side === 'ctms' && allowRawCtms && ['environment', 'setup'].includes(source) && Object.hasOwn(record, 'uri')) {
+    record = { url: record.uri, tokenUrl: record.uaa?.url, clientId: record.uaa?.clientid, clientSecret: record.uaa?.clientsecret };
+  }
+  const fields = FIELDS[side];
+  if (Object.keys(record).some(key => !fields.includes(key))) invalid(side, 'configuration contains unsupported fields');
+  const normalized = {};
+  for (const field of fields) {
+    const value = record[field];
+    if (field === 'probeQueueName' && value === undefined) continue;
+    if (typeof value !== 'string' || !value.trim()) invalid(side, `${field} must be a nonempty string`);
+    if (/[\u0000-\u001f\u007f]/.test(value)) invalid(side, `${field} must not contain control characters`);
+    if (side === 'open_connectors' && ['userSecret', 'organizationSecret'].includes(field) &&
+        (value.length > 16384 || !/^[\x21-\x7e]+$/.test(value) || value.includes(','))) {
+      invalid(side, `${field} must be an unambiguous printable authorization token`);
+    }
+    // Credential bytes are significant; trim endpoint/identity inputs only.
+    normalized[field] = ['url', 'tokenUrl', 'probeQueueName', 'msgVpnName'].includes(field) ? value.trim() : value;
+  }
+  if (normalized.url) {
+    const url = endpoint(side, 'url', normalized.url);
+    if (side === 'edge' && url.pathname !== '/') invalid(side, 'url must be the API virtual-host origin');
+    if (side === 'open_connectors' && !/\/elements\/api-v2\/?$/.test(url.pathname)) {
+      invalid(side, 'url must include /elements/api-v2');
+    }
+    normalized.url = url.href.replace(/\/+$/, '');
+  }
+  if (normalized.tokenUrl) {
+    const token = endpoint(side, 'tokenUrl', normalized.tokenUrl);
+    if (side === 'ctms' && !/\/oauth\/token\/?$/.test(token.pathname)) {
+      token.pathname = `${token.pathname.replace(/\/+$/, '')}/oauth/token`;
+    }
+    // Event Mesh's binding supplies the complete endpoint, not an OAuth base URL.
+    normalized.tokenUrl = token.href;
+  }
+  return Object.freeze({ ...normalized, source: SOURCES.has(source) ? source : 'configuration' });
+}
+
+/** Environment presence wins even for empty/malformed values; errors disable only that side. */
+export function resolveOptionalConfig(env = process.env, stored = {}) {
+  const resolved = {};
+  const errors = [];
+  for (const side of OPTIONAL_COMPONENT_KEYS) {
+    const { variable } = OPTIONAL_INPUTS[side];
+    const supplied = env[variable] !== undefined;
+    const source = supplied ? 'environment' : 'stored-key';
+    resolved[side] = null;
+    if (!supplied && !Object.hasOwn(stored || {}, side)) continue;
+    try {
+      resolved[side] = parseOptionalConfig(side, supplied ? env[variable] : stored[side], { source, allowRawCtms: supplied });
+    } catch (error) {
+      errors.push(Object.freeze({ component: side, source, variable, message: error.message }));
+    }
+  }
+  return Object.freeze({ ...resolved, optional_config_errors: Object.freeze(errors) });
+}
+
+/** Private-store projection: metadata is not part of the normalized credential record. */
+export function optionalConfigRecord(side, config) {
+  if (!OPTIONAL_COMPONENT_KEYS.includes(side)) throw new Error('Unknown optional Integration Suite component');
+  const record = Object.fromEntries(FIELDS[side].filter(field => Object.hasOwn(config || {}, field)).map(field => [field, config[field]]));
+  const { source, ...normalized } = parseOptionalConfig(side, record, { source: 'stored-key' });
+  return normalized;
+}

package/src/integration-optional-tools.mjs

@@ -0,0 +1,153 @@
+// Existing optional-service credentials only: no provisioning, SDK or tenant writes.
+import { createServiceClient, createStaticServiceClient } from './integration-http.mjs';
+import { registerAnsTools } from './integration-alerts.mjs';
+import { registerCtmsTools } from './integration-transport.mjs';
+import { registerMessagingTools, registerEventMeshTools, registerAemTools, registerAemSempTools } from './integration-messaging.mjs';
+import { createOpenConnectorsClient, registerOpenConnectorsTools } from './open-connectors-tools.mjs';
+import { registerEdgeMonitoringTools } from './edge-monitoring.mjs';
+
+export const OPTIONAL_CLIENT_KEYS = Object.freeze(['ctms', 'ans', 'event_mesh', 'aem', 'aem_semp', 'open_connectors', 'edge']);
+const PROBES = new WeakMap();
+const SCOPES = new WeakMap();
+const OBSERVED = [200, 204, 400, 401, 403, 404, 405, 429, 500, 501, 502, 503, 504, 529];
+const basic = (username, password) => `Basic ${Buffer.from(`${username}:${password}`, 'utf8').toString('base64')}`;
+
+function classify(status) {
+  if (status >= 200 && status < 300) return { result: 'ok', detail: 'Read-only API access verified; activation and entitlement remain unknown' };
+  if (status === 401) return { result: 'unauthenticated', detail: 'HTTP 401: authentication was not accepted' };
+  if (status === 403) return { result: 'forbidden', detail: 'HTTP 403: access denied; permission, activation and entitlement causes are not established' };
+  if (status === 404 || status === 501) return { result: 'unavailable', detail: `HTTP ${status}: endpoint unavailable; activation and entitlement remain unknown` };
+  if (status === 529) return { result: 'error', detail: 'HTTP 529: no SEMP session slot available; this is not an empty queue collection' };
+  return { result: 'error', detail: `HTTP ${status}` };
+}
+
+function collection(value, kind) {
+  if (kind === 'nodes') return Array.isArray(value?.nodes);
+  if (kind === 'ans') return Array.isArray(value?.results) && value?.metadata && typeof value.metadata === 'object';
+  if (kind === 'aem' || kind === 'semp') return Array.isArray(value?.data);
+  if (kind === 'instances') return Array.isArray(value);
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function source(probe, status, result, phase) {
+  // Probe paths are fixed routes or encoded queue identities; never query URLs or response bodies.
+  return { method: 'GET', path: probe.path, status, result, ...(phase ? { phase } : {}) };
+}
+
+async function readProbe(client, probe, deadline) {
+  try {
+    const { status, data } = await client.request('GET', probe.path, {
+      query: probe.query, expect: OBSERVED, withStatus: true, responseType: 'text',
+      accept: probe.kind === 'metadata' ? 'application/xml, text/xml' : 'application/json', deadline
+    });
+    let classification = classify(status);
+    if (classification.result === 'ok') {
+      if (probe.kind === 'metadata') {
+        if (!/<(?:[\w.-]+:)?Edmx\b/i.test(String(data))) classification = { result: 'error', detail: 'Local metadata response is not an OData metadata document' };
+      } else {
+        let value;
+        try { value = JSON.parse(data); } catch { /* Classify without including the body. */ }
+        if (!collection(value, probe.kind)) classification = { result: 'error', detail: 'Response does not match the documented API collection or named-resource contract' };
+      }
+    }
+    return { area: probe.area, status, ...classification, source: source(probe, status, classification.result) };
+  } catch (error) {
+    const status = Number.isInteger(error?.status) ? error.status : null;
+    const phase = String(error?.phase ?? '').startsWith('token') ? 'token' : undefined;
+    const classification = error?.stop_reason === 'deadline'
+      ? { result: 'error', detail: 'Verification deadline exceeded', stop_reason: 'deadline' }
+      : status === null ? { result: 'error', detail: 'Request failed without an HTTP response' }
+        : status >= 200 && status < 300 ? { result: 'error', detail: 'Response processing failed' } : classify(status);
+    if (phase && status !== null) classification.detail = `Token request failed (HTTP ${status}); response body withheld`;
+    return { area: probe.area, status, ...classification, source: source(probe, status, classification.result, phase) };
+  }
+}
+
+/** Private auth closures and probe state never enter summaries or MCP output. */
+export function createOptionalClients(config, { env = process.env, fetchImpl } = {}) {
+  const clients = {};
+  const options = { env, ...(fetchImpl ? { fetchImpl } : {}) };
+  const oauth = (label, side) => createServiceClient({ label, url: side.url, tokenUrl: side.tokenUrl, clientId: side.clientId, clientSecret: side.clientSecret, exposeErrorDetails: false, ...options });
+  const fixed = (label, side, authorization, extra = {}) => createStaticServiceClient({ label, url: side.url, authorization, ...options, ...extra });
+  for (const key of OPTIONAL_CLIENT_KEYS) {
+    const side = config?.[key];
+    if (!side) { clients[key] = null; continue; }
+    let client;
+    let probes;
+    if (key === 'ctms') {
+      client = oauth('cTMS', side);
+      probes = [{ area: 'Transport nodes', path: '/v2/nodes', kind: 'nodes' }];
+    } else if (key === 'ans') {
+      client = fixed('ANS', side, () => basic(side.username, side.password));
+      probes = ['subscription', 'condition', 'action'].map(name => ({ area: `Alert ${name} metadata`, path: `/cf/configuration/v1/${name}`, query: { page: 0, pageSize: 1 }, kind: 'ans' }));
+    } else if (key === 'event_mesh') {
+      client = oauth('Event Mesh', side);
+      probes = side.probeQueueName ? [{ area: 'Named queue management', path: `/hub/rest/api/v1/management/messaging/queues/${encodeURIComponent(side.probeQueueName)}`, kind: 'queue' }] : [];
+    } else if (key === 'aem') {
+      client = fixed('Advanced Event Mesh', { url: 'https://api.solace.cloud' }, () => `Bearer ${side.apiToken}`);
+      probes = [{ area: 'GA event broker services', path: '/api/v2/missionControl/eventBrokerServices', query: { pageNumber: 1, pageSize: 1, expand: 'allowedActions' }, kind: 'aem' }];
+    } else if (key === 'aem_semp') {
+      client = fixed('AEM SEMP', side, () => basic(side.username, side.password), { reuseCookies: true });
+      SCOPES.set(client, Object.freeze({ sempVpnName: side.msgVpnName }));
+      probes = [{ area: 'VPN queue metadata', path: `/SEMP/v2/monitor/msgVpns/${encodeURIComponent(side.msgVpnName)}/queues`, query: { count: 1 }, kind: 'semp' }];
+    } else if (key === 'open_connectors') {
+      client = createOpenConnectorsClient(side, options);
+      probes = [{ area: 'Connector instance identities', path: '/instances', query: { pageSize: 1 }, kind: 'instances' }];
+    } else if (key === 'edge') {
+      client = fixed('Edge Integration Cell', side, () => basic(side.clientId, side.clientSecret));
+      probes = [{ area: 'Local OData metadata', path: '/local/api/eic/v1/$metadata', kind: 'metadata' }];
+    }
+    clients[key] = client;
+    PROBES.set(client, probes);
+  }
+  return Object.freeze(clients);
+}
+
+/** Optional evidence is separate from configured core access and never proves entitlement. */
+export async function verifyOptionalClients(clients = {}, { deadline = Date.now() + 30_000 } = {}) {
+  const entries = await Promise.all(OPTIONAL_CLIENT_KEYS.map(async key => {
+    const client = clients[key];
+    if (!client) return [key, { configured: false, signed_in: false, ok: false, result: 'untested', activation: 'unknown', entitlement: 'unknown', checks: [] }];
+    const probes = PROBES.get(client);
+    if (!probes?.length) return [key, {
+      configured: true, signed_in: false, ok: false, result: 'untested', activation: 'unknown', entitlement: 'unknown',
+      detail: key === 'event_mesh' ? 'Set probeQueueName to an existing queue to test management access; no token or API request was made' : 'No private probe definition exists for this client', checks: []
+    }];
+    const checks = await Promise.all(probes.map(probe => readProbe(client, probe, deadline)));
+    const firstFailure = checks.find(check => check.result !== 'ok');
+    const result = firstFailure?.result ?? 'ok';
+    const signedIn = checks.some(check => check.status !== null && check.result !== 'unauthenticated' && check.source.phase !== 'token');
+    return [key, {
+      configured: true, signed_in: signedIn, ok: result === 'ok', result, activation: 'unknown', entitlement: 'unknown',
+      ...(firstFailure ? { error: firstFailure.detail } : {}), checks
+    }];
+  }));
+  const reports = Object.fromEntries(entries);
+  const configured = Object.entries(reports).filter(([, side]) => side.configured);
+  return {
+    ...reports,
+    optional_completeness: {
+      scope: 'configured_optional_access', configured: configured.map(([key]) => key),
+      complete: configured.every(([, side]) => side.result === 'ok'),
+      result: configured.length === 0 ? 'not_configured' : configured.every(([, side]) => side.result === 'ok') ? 'ok' : 'partial',
+      unverified: configured.filter(([, side]) => side.result !== 'ok').map(([key]) => key)
+    }
+  };
+}
+
+/** Optional authority is separate per client; configuration does not enable other adapters. */
+export function registerOptionalIntegrationTools(register, { ans, ctms, event_mesh, aem, aem_semp, open_connectors, edge } = {}) {
+  if (ans) registerAnsTools(register, ans);
+  if (ctms) registerCtmsTools(register, ctms);
+  registerMessagingTools(register, { event_mesh, aem, aem_semp }, SCOPES.get(aem_semp));
+  if (open_connectors) registerOpenConnectorsTools(register, open_connectors);
+  if (edge) registerEdgeMonitoringTools(register, edge);
+}
+
+export function optionalToolNames() {
+  const names = [];
+  registerAnsTools(name => names.push(name), null);
+  registerCtmsTools(name => names.push(name), null);
+  for (const registrar of [registerEventMeshTools, registerAemTools, registerAemSempTools, registerOpenConnectorsTools, registerEdgeMonitoringTools]) registrar(name => names.push(name), null);
+  return names;
+}