sap-ai-dev-toolkit 0.9.9918 → 0.9.9921

package/src/integration-common.mjs

@@ -4,6 +4,7 @@ import { z } from 'zod';
 import { INTEGRATION_CONFIG_ERROR } from './integration-config.mjs';
 import { IntegrationError, odataKey } from './integration-http.mjs';
 import { strFromU8 } from './iflow-bundle.mjs';
+import { createCollectionPager, cursorSchema } from './integration-collections.mjs';
 
 export const INTEGRATION_MAX_OUTPUT_BYTES = 96 * 1024;
 export const FILE_TEXT_CAP = 48 * 1024;
@@ -69,6 +70,9 @@ export function requireConfirmation(actual, expected) {
 export function list(value) {
   if (Array.isArray(value)) return value;
   if (Array.isArray(value?.results)) return value.results;
+  if (Array.isArray(value?.value)) return value.value;
+  if (Array.isArray(value?.d?.results)) return value.d.results;
+  if (Array.isArray(value?.d)) return value.d;
   return [];
 }
 
@@ -78,7 +82,7 @@ export function entity(value) {
   if (!value || typeof value !== 'object') return value;
   const result = {};
   for (const [name, entry] of Object.entries(value)) {
-    if (name.startsWith('__')) continue;
+    if (name.startsWith('__') || name.startsWith('@odata.') || name === '@count') continue;
     if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.__deferred) continue;
     result[name] = entry && typeof entry === 'object' && Array.isArray(entry.results) ? entity(entry.results) : entity(entry);
   }
@@ -91,23 +95,23 @@ const PROVIDER_SECRET_KEYS = new Set(['password', 'clientSecret', 'userSecret',
 export function withoutSecrets(value) {
   if (Array.isArray(value)) return value.map(withoutSecrets);
   if (!value || typeof value !== 'object') return value;
+  const semanticName = value.Name ?? value.name ?? value.ParameterKey;
   return Object.fromEntries(Object.entries(value)
     .filter(([name]) => !PROVIDER_SECRET_KEYS.has(name))
-    .map(([name, entry]) => [name, withoutSecrets(entry)]));
+    .map(([name, entry]) => [name, /^(?:value|ParameterValue)$/i.test(name) && typeof semanticName === 'string'
+      && /password|secret|token|username|clientid|authorization/i.test(semanticName) ? REDACTED : withoutSecrets(entry)]));
 }
 
 export const REDACTED = '[redacted]';
-const SECRET_FIELD = /password|secret|passphrase|private_?key|api_?key|app_?key|consumer_?key|secure_?param|access_?token|refresh_?token/i;
+const SECRET_FIELD = /password|secret|passphrase|private[_-]?key|api[_-]?key|app[_-]?key|consumer[_-]?key|secure[_-]?param|access[_-]?token|refresh[_-]?token|authorization|cookie|(?:^|[_-])token(?:$|[_-])|csrf[_-]?token/i;
 const BINARY_FIELDS = new Set(['ArtifactContent', 'ResourceContent', 'PackageContent', 'CustomTagsConfigurationContent']);
 
-/**
- * Replace secret-looking values with [redacted] and omit base64 artifact content. Inside an object flagged
- * encrypted/isEncrypted (APIM key value maps) every nested `value` is redacted as well.
- */
+/** Redact known credential fields and semantic name/value pairs, not arbitrary source text. */
 export function redactSecrets(value, encrypted = false) {
   if (Array.isArray(value)) return value.map(entry => redactSecrets(entry, encrypted));
   if (!value || typeof value !== 'object') return value;
-  const inEncrypted = encrypted || value.encrypted === true || value.isEncrypted === true;
+  const inEncrypted = encrypted || value.encrypted === true || value.encrypted === 'true' || value.isEncrypted === true || value.isEncrypted === 'true';
+  const semanticName = value.Name ?? value.name ?? value.ParameterKey;
   const result = {};
   for (const [name, entry] of Object.entries(value)) {
     if (BINARY_FIELDS.has(name)) {
@@ -115,11 +119,11 @@ export function redactSecrets(value, encrypted = false) {
       continue;
     }
     if (entry !== null && entry !== undefined && entry !== '' && typeof entry !== 'object'
-      && (SECRET_FIELD.test(name) || (inEncrypted && name === 'value'))) {
+      && (SECRET_FIELD.test(name) || ((inEncrypted || (typeof semanticName === 'string' && SECRET_FIELD.test(semanticName))) && /^(?:value|ParameterValue)$/i.test(name)))) {
       result[name] = REDACTED;
       continue;
     }
-    result[name] = redactSecrets(entry, inEncrypted);
+    result[name] = redactSecrets(entry, inEncrypted || name === 'keyMapEntryValues');
   }
   return result;
 }
@@ -136,7 +140,17 @@ export function capText(text, limit) {
 }
 
 export function isoToOdataDateTime(value) {
-  return new Date(value).toISOString().slice(0, 19);
+  return new Date(value).toISOString().slice(0, -1);
+}
+
+/** Shared UTC half-open window for monitoring; milliseconds remain significant. */
+export function timeWindow(from, to) {
+  if (!isoDate.safeParse(from).success || !isoDate.safeParse(to).success) throw new IntegrationError('from and to must both be valid UTC timestamps');
+  const start = Date.parse(from);
+  const end = Date.parse(to);
+  if (end <= start) throw new IntegrationError('to must be after from');
+  if (end - start > 31 * 24 * 60 * 60 * 1000) throw new IntegrationError('The monitoring window must not exceed 31 days');
+  return { from: new Date(start).toISOString(), to: new Date(end).toISOString() };
 }
 
 function extensionOf(path) {
@@ -172,7 +186,9 @@ export function bundleFiles(bundle, filePath) {
 // ---------------------------------------------------------------- schemas
 
 export const confirmation = z.string().min(1).max(300);
-export const isoDate = z.string().max(40).refine(value => !Number.isNaN(Date.parse(value)), 'must be an ISO-8601 date/time');
+export const isoDate = z.string().max(40)
+  .regex(/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/, 'must be an explicit UTC timestamp')
+  .refine(value => Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 19) === value.slice(0, 19), 'must be a valid UTC date/time');
 export const top = (max = 200, fallback = 100) => z.number().int().min(1).max(max).default(fallback);
 export const secretValue = z.string().min(1).max(4096)
   .describe('Write-only: sent to the tenant once and never echoed back by any tool.');
@@ -183,6 +199,97 @@ const ODATA_SEGMENT = String.raw`[A-Za-z][A-Za-z0-9_]{0,99}(?:\([^/?#]{0,400}\))
 const ODATA_PATH = new RegExp(String.raw`^(?:/\$metadata|/${ODATA_SEGMENT}(?:/(?:${ODATA_SEGMENT}|\$count))*)$`);
 const ODATA_OPTIONS = ['$filter', '$select', '$expand', '$orderby', '$top', '$skip', '$inlinecount'];
 
+// Version 1: only implemented metadata projections authorize data access. Metadata discovery
+// does not authorize raw reads of newly discovered roots or GET function imports.
+const fields = names => value => pick(entity(value), names.split(','));
+const CPI_PROJECTORS = {
+  IntegrationPackages: fields('Id,Name,ShortText,Version,Mode'),
+  IntegrationDesigntimeArtifacts: fields('Id,Name,Version,Description,PackageId'),
+  ValueMappingDesigntimeArtifacts: fields('Id,Name,Version,Description,PackageId'),
+  ScriptCollectionDesigntimeArtifacts: fields('Id,Name,Version,Description,PackageId'),
+  MessageMappingDesigntimeArtifacts: fields('Id,Name,Version,Description,PackageId'),
+  Configurations: fields('ParameterKey,DataType'),
+  IntegrationRuntimeArtifacts: fields('Id,Name,Version,Type,Status,DeployedOn'),
+  MessageProcessingLogs: fields('MessageGuid,CorrelationId,ApplicationMessageId,IntegrationFlowName,Status,CustomStatus,LogStart,LogEnd'),
+  Runs: fields('Id,RunId,MessageGuid,LogStart,LogEnd,Status'),
+  MessageProcessingLogRuns: fields('Id,RunId,MessageGuid,LogStart,LogEnd,Status'),
+  RunSteps: fields('StepId,ModelStepId,Activity,Status,StepStart,StepStop'),
+  CustomHeaderProperties: fields('Name'),
+  JmsBrokers: fields('Name,Capacity,MaxCapacity,CapacityOk,CapacityWarning,CapacityError,QueueNumber,MaxQueueNumber,IsQueuesHigh,IsMessageSpoolHigh,IsTransactedSessionsHigh,IsConsumersHigh,IsProducersHigh'),
+  QueueStates: fields('Name,State'),
+  InactiveQueues: fields('Name,State'),
+  Queues: fields('Name,NumbOfMsgs,Size,Type,State,FillGrade,Active,Exclusive'),
+  DataStores: fields('DataStoreName,IntegrationFlow,Type,Visibility,NumberOfMessages,NumberOfOverdueMessages'),
+  Entries: fields('Id,Status,MessageId,DueAt,CreatedAt,RetainUntil'),
+  Variables: fields('Name,IntegrationFlow,Visibility,UpdatedAt,RetainUntil'),
+  UserCredentials: fields('Name,Kind,DeployedOn,Status'),
+  OAuth2ClientCredentials: fields('Name,Status'),
+  KeystoreEntries: fields('Alias,Type,KeyType,ValidNotBefore,ValidNotAfter'),
+  NumberRanges: fields('Name,Description,MinValue,MaxValue,CurrentValue,Rotate,FieldLength'),
+  StringParameters: fields('Pid,Id'),
+  BinaryParameters: fields('Pid,Id,ContentType')
+};
+const APIM_PROJECTORS = {
+  APIProviders: fields('name,title,destType,host,port,useSSL,isOnPremise,cloudConnectorLocation,pathPrefix'),
+  APIProviderAdditionalPropertys: value => ({ ...pick(value, ['entityId', 'name']), ...(/^(?:sap-client)$/i.test(value?.name ?? '') ? pick(value, ['value']) : {}) }),
+  APIProxies: fields('name,title,service_code,state,version,provider_name'),
+  APIProducts: fields('name,title,status,scope,quotaCount,quotaInterval,quotaTimeUnit'),
+  VirtualHosts: fields('id,name,virtual_host,virtual_port,isSSL,isDefault'),
+  KeyMapEntries: fields('name,encrypted,scope'),
+  keyMapEntryValues: value => ({ ...pick(value, ['name']), value: REDACTED }),
+  KeyMapEntryValues: value => ({ ...pick(value, ['name']), value: REDACTED }),
+  Applications: fields('id,title,version,status,status_code'),
+  Developers: fields('id,status,status_code'),
+  CertificateStoreReferences: fields('id,name,alias,type')
+};
+const CPI_NAVIGATIONS = {
+  IntegrationPackages: ['IntegrationDesigntimeArtifacts', 'ValueMappingDesigntimeArtifacts', 'ScriptCollectionDesigntimeArtifacts', 'MessageMappingDesigntimeArtifacts'],
+  IntegrationDesigntimeArtifacts: ['Configurations'],
+  MessageProcessingLogs: ['Runs', 'CustomHeaderProperties'],
+  MessageProcessingLogRuns: ['RunSteps'],
+  DataStores: ['Entries'],
+  JmsBrokers: ['QueueStates', 'InactiveQueues']
+};
+const APIM_NAVIGATIONS = { KeyMapEntries: ['keyMapEntryValues'] };
+const LOCAL_ROOTS = new Set(['DataStores', 'Entries', 'Variables', 'Queues', 'JmsBrokers', 'QueueStates', 'InactiveQueues', 'NumberRanges', 'UserCredentials', 'OAuth2ClientCredentials', 'KeystoreEntries']);
+const COUNT_ROOTS = new Set(['MessageProcessingLogs', 'IntegrationPackages', 'IntegrationRuntimeArtifacts', 'APIProxies', 'APIProviders', 'APIProducts', 'KeyMapEntries']);
+
+function readPolicy(name, path, query) {
+  const cpi = name === 'cpi_odata_get';
+  const projectors = cpi ? CPI_PROJECTORS : APIM_PROJECTORS;
+  const navigations = cpi ? CPI_NAVIGATIONS : APIM_NAVIGATIONS;
+  const parts = path.slice(1).split('/');
+  const count = parts.at(-1) === '$count';
+  if (count) parts.pop();
+  if (parts.length > 2) throw new IntegrationError('Only one documented metadata navigation level is allowed');
+  const roots = parts.map(part => /^([A-Za-z][A-Za-z0-9_]*)(?:\([^/]*\))?$/.exec(part)?.[1]);
+  const [root, navigation] = roots;
+  if (!root || !projectors[root] || (navigation && !navigations[root]?.includes(navigation))) {
+    throw new IntegrationError('This route has no safe metadata projector; use /$metadata for discovery or a dedicated tool');
+  }
+  if (count && (navigation || !COUNT_ROOTS.has(root))) throw new IntegrationError('A count contract is not established for this route');
+  for (const [option, value] of Object.entries(query)) {
+    if (!ODATA_OPTIONS.includes(option) && !(cpi && root === 'KeystoreEntries' && option === 'keystoreName')) throw new IntegrationError(`query option ${option} is not allowed`);
+    if (option === '$top' && !/^(?:[1-9]\d?|1\d\d|200)$/.test(value)) throw new IntegrationError('$top must be an integer from 1 to 200');
+    if (option === '$skip' && (!/^\d{1,7}$/.test(value) || Number(value) > 1_000_000)) throw new IntegrationError('$skip must be a bounded nonnegative integer');
+    if (option === '$inlinecount' && !['allpages', 'none'].includes(value)) throw new IntegrationError('$inlinecount must be allpages or none');
+    if (option === 'keystoreName' && !['system', 'backup_admin_system', 'KeyRenewal'].includes(value)) throw new IntegrationError('Unknown keystoreName');
+    if (option === '$select' && !/^[A-Za-z][A-Za-z0-9_]*(?:,[A-Za-z][A-Za-z0-9_]*)*$/.test(value)) throw new IntegrationError('$select must contain plain field names');
+    if (option === '$expand' && value.split(',').some(entry => !navigations[navigation ?? root]?.includes(entry))) throw new IntegrationError('$expand is not an allowed metadata navigation');
+    if (option === '$orderby' && !/^[A-Za-z][A-Za-z0-9_]*(?: (?:asc|desc))?$/.test(value)) throw new IntegrationError('$orderby must contain one plain field');
+  }
+  const selected = navigation ?? root;
+  const project = value => {
+    const result = projectors[selected](value);
+    for (const child of (query.$expand ?? '').split(',').filter(Boolean)) {
+      const raw = value?.[child];
+      if (raw !== undefined) result[child] = list(raw).map(projectors[child]);
+    }
+    return redactSecrets(withoutSecrets(result));
+  };
+  return { project, collection: parts.length === 2 || !parts[0].includes('('), mode: LOCAL_ROOTS.has(selected) ? 'local' : 'odata', count };
+}
+
 /** Summarize an OData $metadata document into entity sets and function imports. */
 export function metadataSummary(xml) {
   const attribute = (tag, name) => tag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
@@ -195,38 +302,36 @@ export function metadataSummary(xml) {
   return { entity_sets: entitySets, function_imports: functionImports };
 }
 
-/**
- * Register a guarded read-only GET over one OData service. Media ($value), $batch and $links
- * are rejected so payloads and binary content stay out of reach; secrets are redacted.
- */
-export function registerODataReader(register, { name, title, service, request, examples }) {
+/** A metadata-only, versioned route allowlist; never an arbitrary GET passthrough. */
+export function registerODataReader(register, { name, title, service, request, client, root, examples }) {
+  const pager = createCollectionPager(client ?? request, { root, request });
   register(name, title,
-    `Read-only GET against the ${service} OData API for entity sets without a dedicated tool. path is relative to the service root, e.g. ${examples}. Use /$metadata to list entity sets and function imports. Media streams ($value), $batch and $links are not allowed; secret-like fields and artifact content are redacted.`,
+    `Read allowlisted operational metadata from ${service}. Discover entity/path names with /$metadata; only implemented safe projectors authorize reads. No function imports, payloads, source, arbitrary expansions, configuration values or secrets. Examples: ${examples}. Collections use signed bounded cursors.`,
     {
-      path: z.string().max(1000).regex(ODATA_PATH, 'must be /$metadata or /EntitySet[(key)][/Navigation...][/$count] without $value, query string or ..')
+      path: z.string().max(1000).regex(ODATA_PATH, 'must be /$metadata or a metadata entity path without query string or media')
         .refine(value => !value.includes('..'), 'must not contain ..'),
-      query: z.record(z.string().regex(/^(?:\$[a-z]+|[A-Za-z][A-Za-z0-9_]{0,40})$/), z.string().max(2000)).optional()
-        .describe(`OData system options (${ODATA_OPTIONS.join(', ')}) and service-specific custom parameters (e.g. keystoreName).`)
+      query: z.record(z.string().max(50), z.string().max(2000)).optional(),
+      top: top(),
+      cursor: cursorSchema
     },
     READ_ONLY_ANNOTATIONS,
-    async ({ path, query = {} }) => {
-      for (const option of Object.keys(query)) {
-        if (option.startsWith('$') && !ODATA_OPTIONS.includes(option)) throw new IntegrationError(`query option ${option} is not allowed`);
-      }
+    async ({ path, query = {}, top: pageSize, cursor }) => {
       if (path === '/$metadata') {
+        if (cursor || Object.keys(query).length) throw new IntegrationError('Metadata discovery accepts no cursor or query options');
         return metadataSummary(await request('GET', path, { accept: 'application/xml', responseType: 'text' }));
       }
-      if (path.endsWith('/$count')) {
+      const policy = readPolicy(name, path, query);
+      if (policy.count) {
+        if (cursor) throw new IntegrationError('Count reads accept no cursor');
         const text = await request('GET', path, { query, accept: 'text/plain', responseType: 'text' });
-        return { count: Number(String(text).trim()) };
+        const trimmed = String(text).trim();
+        if (!/^\d+$/.test(trimmed) || !Number.isSafeInteger(Number(trimmed))) throw new IntegrationError('Count endpoint returned invalid nonnegative integer text');
+        return { count: Number(trimmed) };
+      }
+      if (policy.collection) {
+        return pager.page({ path, query, top: Number(query.$top ?? pageSize), cursor, project: policy.project, mode: policy.mode, orderBy: query.$orderby });
       }
-      const parsed = await request('GET', path, { query, unwrap: false });
-      const data = parsed?.d ?? parsed;
-      const total = Number(data?.__count);
-      const results = Array.isArray(data?.results) ? data.results : null;
-      const cleaned = redactSecrets(entity(results ?? data));
-      return results
-        ? { total: Number.isFinite(total) ? total : null, returned: results.length, more: Boolean(data?.__next), results: cleaned }
-        : cleaned;
+      if (cursor) throw new IntegrationError('Named metadata reads accept no cursor');
+      return policy.project(await request('GET', path, { query }));
     });
 }

package/src/integration-config.mjs

@@ -1,12 +1,13 @@
-// Resolves CPI (Cloud Integration) and APIM (API Management) OAuth client
-// credentials from the MCP host environment. Pure: no I/O, no network.
-// Every error message starts with a stable prefix (Explicit CPI/APIM, CPI_,
-// APIM_, No CPI/APIM, Multiple CPI/APIM, Configure CPI) so the tool layer
-// can surface it verbatim; no message ever echoes a secret value.
+// Resolves core OAuth credentials and independently configured optional services.
+// Pure: no I/O, no network. Stable error prefixes allow the tool layer to
+// surface configuration failures without echoing secret values.
+import { OPTIONAL_COMPONENT_KEYS, resolveOptionalConfig } from './integration-optional-config.mjs';
+
 
 const SIDES = Object.freeze({
   CPI: Object.freeze({ prefix: 'CPI', defaultVcapService: 'it-rt' }),
-  APIM: Object.freeze({ prefix: 'APIM', defaultVcapService: 'apimanagement-apiportal' })
+  APIM: Object.freeze({ prefix: 'APIM', defaultVcapService: 'apimanagement-apiportal' }),
+  DEVHUB: Object.freeze({ prefix: 'DEVHUB', defaultVcapService: 'apimanagement-devportal' })
 });
 
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
@@ -65,7 +66,7 @@ function explicitConfig(env, prefix) {
   });
 }
 
-/** Parse a CPI/APIM service key (nested `oauth` or flat APIM shape) into raw OAuth fields. */
+/** Parse an Integration Suite service key (nested `oauth` or flat shape) into raw OAuth fields. */
 function parseServiceKey(value, origin) {
   let key = value;
   if (typeof value === 'string') {
@@ -146,22 +147,27 @@ export function resolveIntegrationSideFromEnvironment(env, side) {
   return resolveSide(env, SIDES[side]);
 }
 
-/** Validate a pasted CPI/APIM service key (JSON text or object); returns the resolved side config. */
+/** Validate a pasted Integration Suite service key (JSON text or object); returns the resolved side config. */
 export function parseIntegrationServiceKey(side, value) {
   return finalize(side, 'stored-key', null, parseServiceKey(value, `${side} service key`));
 }
 
 /**
- * Resolve CPI and APIM client credentials; at least one side must be configured.
- * `stored` holds service keys saved by the setup wizard ({ cpi, apim }) and has the lowest precedence.
+ * Resolve core and optional credentials; absent configuration retains setup guidance.
+ * `stored` holds setup wizard keys with lowest precedence.
  */
 export function resolveIntegrationConfig(env = process.env, { stored } = {}) {
   const cpi = resolveSide(env, SIDES.CPI, stored);
   const apim = resolveSide(env, SIDES.APIM, stored);
-  if (!cpi && !apim) {
-    fail('Configure CPI (CPI_SERVICE_KEY or CPI_URL/CPI_TOKEN_URL/CPI_CLIENT_ID/CPI_CLIENT_SECRET) and/or APIM (APIM_SERVICE_KEY or APIM_*) credentials in the MCP host environment, or run sap-ai-dev --setup-integration to paste and verify service keys.');
+  const devhub = resolveSide(env, SIDES.DEVHUB, stored);
+  const optional = resolveOptionalConfig(env, stored);
+  if (!cpi && !apim && !devhub && !OPTIONAL_COMPONENT_KEYS.some(side => optional[side]) && !optional.optional_config_errors.length) {
+    fail('Configure CPI (CPI_SERVICE_KEY or CPI_URL/CPI_TOKEN_URL/CPI_CLIENT_ID/CPI_CLIENT_SECRET), APIM (APIM_SERVICE_KEY or APIM_*), and/or DEVHUB (DEVHUB_SERVICE_KEY or DEVHUB_URL/DEVHUB_TOKEN_URL/DEVHUB_CLIENT_ID/DEVHUB_CLIENT_SECRET) credentials in the MCP host environment, or run sap-ai-dev --setup-integration to paste and verify service keys.');
   }
-  return Object.freeze({ cpi, apim });
+  const environment = typeof env.INTEGRATION_ENVIRONMENT === 'string' && env.INTEGRATION_ENVIRONMENT.trim()
+    ? env.INTEGRATION_ENVIRONMENT.trim()
+    : 'default';
+  return Object.freeze({ cpi, apim, devhub, ...optional, environment });
 }
 
-export const INTEGRATION_CONFIG_ERROR = /^(?:Explicit CPI|Explicit APIM|CPI_|APIM_|No CPI|No APIM|Multiple CPI|Multiple APIM|Configure CPI|Stored (?:CPI|APIM)|Stored Integration Suite)/;
+export const INTEGRATION_CONFIG_ERROR = /^(?:Explicit (?:CPI|APIM|DEVHUB)|(?:CPI|APIM|DEVHUB)_|No (?:CPI|APIM|DEVHUB)|Multiple (?:CPI|APIM|DEVHUB)|Configure CPI|Stored (?:CPI|APIM|DEVHUB)|Stored Integration Suite)/;

package/src/integration-credentials.mjs

@@ -1,13 +1,14 @@
-// User-only store for CPI/APIM service keys pasted into `sap-ai-dev --setup-integration`.
-// The file lives outside mcp.json (~/.config/sap-ai-dev-toolkit/integration-suite.json, mode 0600)
-// and keeps only the four OAuth fields the companion needs; environment credentials take precedence.
+// User-only store for core service keys and normalized optional-service credentials.
+// The file lives outside mcp.json (~/.config/sap-ai-dev-toolkit/integration-suite.json, mode 0600).
+// Environment credentials take precedence; source metadata is never stored.
 import { readFileSync } from 'node:fs';
 import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { OPTIONAL_COMPONENT_KEYS, optionalConfigRecord } from './integration-optional-config.mjs';
 
-const SIDES = ['cpi', 'apim'];
+const SIDES = ['cpi', 'apim', 'devhub', ...OPTIONAL_COMPONENT_KEYS];
 
 export function integrationCredentialsPath(env = process.env) {
   const configHome = typeof env.XDG_CONFIG_HOME === 'string' && env.XDG_CONFIG_HOME.trim()
@@ -16,7 +17,7 @@ export function integrationCredentialsPath(env = process.env) {
   return join(configHome, 'sap-ai-dev-toolkit', 'integration-suite.json');
 }
 
-/** Stored service keys ({ cpi?, apim? }); {} when nothing was stored. */
+/** Stored keys/normalized optional records; malformed optional records remain isolated by the resolver. */
 export function readStoredIntegrationKeys(env = process.env) {
   const path = integrationCredentialsPath(env);
   let text;
@@ -32,23 +33,28 @@ export function readStoredIntegrationKeys(env = process.env) {
   } catch {
     throw new Error(`Stored Integration Suite credentials at ${path} are not valid JSON; rerun sap-ai-dev --setup-integration`);
   }
-  return Object.fromEntries(SIDES.filter(side => parsed?.[side]).map(side => [side, parsed[side]]));
+  return Object.fromEntries(SIDES.filter(side => Object.hasOwn(parsed || {}, side)).map(side => [side, parsed[side]]));
 }
 
-/** Save one side's verified OAuth client (resolved config) next to the other side's stored key. */
+/** Save one side alongside other stored keys; optional records contain only typed normalized fields. */
 export async function storeIntegrationKey(side, config, env = process.env) {
   const key = side.toLowerCase();
   if (!SIDES.includes(key)) throw new Error(`Unknown Integration Suite side ${side}`);
+  const optional = OPTIONAL_COMPONENT_KEYS.includes(key);
+  const record = optional ? optionalConfigRecord(key, config) : {
+    oauth: { url: config.url, tokenurl: config.tokenUrl, clientid: config.clientId, clientsecret: config.clientSecret }
+  };
   const path = integrationCredentialsPath(env);
   let existing = {};
   try {
     existing = readStoredIntegrationKeys(env);
-  } catch {
-    // An unreadable or corrupt store is replaced by the verified key.
+  } catch (error) {
+    // Optional setup never replaces a store it could not read; core setup behavior is unchanged.
+    if (optional) throw error;
   }
   const next = {
     ...existing,
-    [key]: { oauth: { url: config.url, tokenurl: config.tokenUrl, clientid: config.clientId, clientsecret: config.clientSecret } }
+    [key]: record
   };
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
   await chmod(dirname(path), 0o700).catch(() => {});