sap-ai-dev-toolkit 0.9.9918 → 0.9.9920

package/src/devhub-retirement.mjs

@@ -0,0 +1,345 @@
+// Consumer retirement never cascades to products, proxies, developers or runtime credentials.
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { IntegrationError } from './integration-http.mjs';
+import { entity, key, OVERWRITE_ANNOTATIONS, READ_ONLY_ANNOTATIONS, requireConfirmation, sleep, top } from './integration-common.mjs';
+import { createCollectionPager, cursorSchema, decodeCollection } from './integration-collections.mjs';
+import { canonicalDigest } from './integration-state.mjs';
+import { redactPrivateValues } from './apim-runtime.mjs';
+
+const DATA = '/odata/1.0/data.svc';
+const PREVIEW_TTL = 15 * 60 * 1000;
+const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+const MAX_RELATIONSHIPS = 2000;
+const applicationId = z.string().min(1).max(256).regex(/^[A-Za-z0-9_-]+$/);
+const productName = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/);
+const confirmation = z.string().min(1).max(512).optional();
+const idValue = value => typeof value === 'string' && /^[A-Za-z0-9_.-]{1,256}$/.test(value) ? value : null;
+const subscribed = value => value === true || value === 'true' ? true : value === false || value === 'false' ? false : null;
+const statusValue = value => typeof value === 'string' && /^[A-Za-z0-9 _-]{1,64}$/.test(value) ? value : null;
+const applicationPath = id => `/APIMgmt.Applications(${key(id)})`;
+const subscriptionPath = id => `/APIMgmt.Subscriptions(${key(id)})`;
+const identityFor = (row, navigation) => navigation === 'ToSubscriptions' ? idValue(row?.id) : idValue(row?.product_id ?? row?.name ?? row?.id);
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const failure = error => ({ result: 'error', ...(Number.isInteger(error?.status) ? { status: error.status } : {}) });
+const credentialEffects = Object.freeze({ api_key_invalidation: 'unverified', issued_oauth_token_revocation: 'unverified' });
+
+function privateValues(value, values = []) {
+  if (!value || typeof value !== 'object') return values;
+  for (const [name, entry] of Object.entries(value)) {
+    if (/^(?:app_key|app_secret|consumer_?key|consumer_?secret|access_token|refresh_token|password)$/i.test(name) && typeof entry === 'string' && entry) values.push(entry);
+    else if (entry && typeof entry === 'object') privateValues(entry, values);
+  }
+  return values;
+}
+
+function subscriptionSummary(value, application) {
+  return {
+    subscription_id: idValue(value?.id), application_id: idValue(value?.app_id) ?? application,
+    product_id: idValue(value?.product_id), rate_plan_id: idValue(value?.ratePlan_id),
+    is_subscribed: subscribed(value?.isSubscribed), approval_status: statusValue(value?.status),
+    ...(value?.status_code !== undefined ? { approval_status_code: statusValue(String(value.status_code)) } : {})
+  };
+}
+
+function relationPage(value) {
+  try {
+    const decoded = decodeCollection(value);
+    if (!value || value.__deferred) return null;
+    const source = value.d ?? value;
+    const count = source.__count ?? source['@odata.count'] ?? source['@count'];
+    if (count !== undefined && decoded.total === null) return null;
+    if (decoded.items.some(row => !row || typeof row !== 'object' || Array.isArray(row))) return null;
+    return decoded;
+  } catch { return null; }
+}
+
+function referenceEvidence(value, path = '', references = []) {
+  if (!value || typeof value !== 'object') return references;
+  for (const [name, entry] of Object.entries(value)) {
+    if (name === '__metadata' && typeof entry?.uri === 'string') references.push([path, entry.uri]);
+    else if (entry && typeof entry === 'object') referenceEvidence(entry, `${path}/${name}`, references);
+  }
+  return references;
+}
+
+/** Register with a null client for tool-name enumeration; all client access stays in handlers. */
+export function registerDevhubRetirementTools(register, client, { readBackDelayMs = 5000 } = {}) {
+  const previews = new Map();
+  const request = (method, path, options) => client.request(method, `${DATA}${path}`, options);
+  const origin = () => {
+    if (!client || typeof client.origin !== 'string') throw new IntegrationError('Developer Hub has no pinned origin');
+    return new URL(client.origin).origin;
+  };
+
+  async function namedApplication(id, expanded = true) {
+    const response = await request('GET', applicationPath(id), {
+      ...(expanded ? { query: { $expand: 'ToAPIProductsDetails,ToSubscriptions/ToAPIProduct,ToSubscriptions/ToRatePlan' } } : {}),
+      expect: [200, 404], withStatus: true, unwrap: false
+    });
+    if (response.status === 404) return null;
+    const value = response.data?.d ?? response.data;
+    if (!value || value.id !== id) throw new IntegrationError('Cannot establish the requested consumer application identity');
+    if (Buffer.byteLength(JSON.stringify(value)) > MAX_SOURCE_BYTES) throw new IntegrationError('Consumer application relationships exceed the safe source limit');
+    return value;
+  }
+
+  // Follow only a supplied same-navigation continuation, never invent another endpoint/query shape.
+  async function inventoryRelationship(application, navigation) {
+    let raw = application[navigation];
+    const rows = [];
+    const seen = new Set();
+    const links = new Set();
+    let expected = null;
+    let bytes = 0;
+    const path = `${applicationPath(application.id)}/${navigation}`;
+    for (let page = 0; page < 256; page += 1) {
+      const decoded = relationPage(raw);
+      if (!decoded) return { rows, complete: false, stop_reason: 'unknown_relationship_shape' };
+      bytes += Buffer.byteLength(JSON.stringify(raw));
+      if (bytes > MAX_SOURCE_BYTES || rows.length + decoded.items.length > MAX_RELATIONSHIPS) return { rows, complete: false, stop_reason: 'source_limit' };
+      if (decoded.total !== null) {
+        if (expected !== null && expected !== decoded.total) return { rows, complete: false, stop_reason: 'source_changed' };
+        expected = decoded.total;
+      }
+      for (const row of decoded.items) {
+        const id = identityFor(row, navigation);
+        if (!id || seen.has(id) || navigation === 'ToSubscriptions' && (!idValue(row.product_id) || row.app_id !== undefined && row.app_id !== application.id)) {
+          return { rows, complete: false, stop_reason: 'ambiguous_relationship' };
+        }
+        seen.add(id);
+        rows.push(row);
+      }
+      if (!decoded.next) return { rows, complete: expected === null || expected === rows.length, stop_reason: expected !== null && expected !== rows.length ? 'source_limit' : 'end' };
+      let next;
+      try { next = new URL(decoded.next, `${origin()}${DATA}${path}`); } catch { return { rows, complete: false, stop_reason: 'invalid_continuation' }; }
+      if (next.origin !== origin() || next.username || next.password || next.hash || decodeURIComponent(next.pathname) !== decodeURIComponent(`${DATA}${path}`)
+        || [...next.searchParams.keys()].some(name => !['$skip', '$skiptoken', '$top', '$inlinecount', '$count', '$format', '$expand', '$orderby'].includes(name) || next.searchParams.getAll(name).length !== 1)
+        || links.has(next.href)) return { rows, complete: false, stop_reason: 'invalid_continuation' };
+      links.add(next.href);
+      try { raw = await request('GET', path, { query: Object.fromEntries(next.searchParams), unwrap: false }); }
+      catch (error) { return { rows, complete: false, stop_reason: 'source_error', source_result: failure(error) }; }
+    }
+    return { rows, complete: false, stop_reason: 'source_limit' };
+  }
+
+  async function inspect(id) {
+    const application = await namedApplication(id);
+    if (!application) return null;
+    const subscriptions = await inventoryRelationship(application, 'ToSubscriptions');
+    const legacy = await inventoryRelationship(application, 'ToAPIProductsDetails');
+    const owner = { developer_id: application.developer_id ?? null, reg_id: application.reg_id ?? null };
+    const ownerKnown = Object.values(owner).some(value => typeof value === 'string' && value.length > 0);
+    const statesKnown = subscriptions.rows.every(row => subscribed(row.isSubscribed) !== null);
+    const complete = ownerKnown && subscriptions.complete && legacy.complete && statesKnown;
+    const sortRows = (rows, navigation) => [...rows].sort((a, b) => compare(identityFor(a, navigation), identityFor(b, navigation)))
+      .map(row => ({ value: entity(row), relationship_references: referenceEvidence(row) }));
+    return {
+      application, subscriptions, legacy, complete, owner,
+      evidence: { owner, subscriptions: sortRows(subscriptions.rows, 'ToSubscriptions'), legacy_product_links: sortRows(legacy.rows, 'ToAPIProductsDetails') },
+      private_values: privateValues(application).concat(privateValues(subscriptions.rows), privateValues(legacy.rows)),
+      findings: [
+        ...(!ownerKnown ? ['owner_unknown'] : []), ...(!statesKnown ? ['subscription_state_unknown'] : []),
+        ...(!subscriptions.complete ? [`subscriptions_${subscriptions.stop_reason}`] : []),
+        ...(!legacy.complete ? [`legacy_products_${legacy.stop_reason}`] : [])
+      ]
+    };
+  }
+
+  function subscriptionPage(application) {
+    const page = relationPage(application.ToSubscriptions);
+    if (!page) throw new IntegrationError('Consumer subscription relationships are incomplete or unsupported');
+    const secrets = privateValues(application);
+    return {
+      results: page.items.map(row => redactPrivateValues(subscriptionSummary(row, application.id), secrets)),
+      ...(page.total === null ? {} : { __count: String(page.total) }), ...(page.next ? { __next: page.next } : {})
+    };
+  }
+
+  // A local page re-reads exactly the documented expanded application; signed cursors detect drift.
+  const collections = createCollectionPager(client, {
+    root: DATA,
+    request: async (_method, path) => {
+      const match = /^\/APIMgmt\.Applications\('([A-Za-z0-9_-]+)'\)\/ToSubscriptions$/.exec(decodeURIComponent(path));
+      if (!match) throw new IntegrationError('Invalid consumer subscription listing');
+      const application = await namedApplication(match[1]);
+      if (!application) throw new IntegrationError('Consumer application does not exist');
+      return subscriptionPage(application);
+    }
+  });
+
+  function reference(value, collection, expectedId, { nullable = false, scalar } = {}) {
+    const page = value === null ? { items: [], total: null, next: null } : Array.isArray(value) || value?.results || value?.value ? relationPage(value)
+      : value && typeof value === 'object' && !value.__deferred ? { items: [value], total: null, next: null } : null;
+    if (nullable && (!page && value === undefined && (scalar === null || scalar === '') || page && page.items.length === 0 && !page.next && (page.total === null || page.total === 0) && (scalar === undefined || scalar === null || scalar === ''))) return null;
+    if (!page || page.next || page.items.length !== 1 || page.total !== null && page.total !== 1) throw new IntegrationError('Subscription relationship references are incomplete or ambiguous; unsubscribe refused');
+    const uri = page.items[0]?.__metadata?.uri;
+    if (typeof uri !== 'string' || /[\x00-\x20\x7f\\]/.test(uri)) throw new IntegrationError('Subscription relationship has no authoritative reference; unsubscribe refused');
+    let url;
+    try { url = new URL(uri, `${origin()}${DATA}/`); } catch { throw new IntegrationError('Invalid subscription relationship reference'); }
+    if (url.origin !== origin() || url.username || url.password || url.search || url.hash) throw new IntegrationError('Subscription relationship leaves the pinned service');
+    const match = /^\/odata\/1\.0\/data\.svc\/APIMgmt\.(APIProducts|Applications|RatePlans)\('((?:[^']|'')*)'\)$/.exec(decodeURIComponent(url.pathname));
+    const id = match?.[2]?.replaceAll("''", "'");
+    if (match?.[1] !== collection || !idValue(id) || expectedId !== undefined && id !== expectedId || scalar && id !== scalar) throw new IntegrationError('Subscription relationship identity does not match its scalar IDs');
+    return [{ __metadata: { uri } }];
+  }
+
+  async function namedSubscription(id, application, product) {
+    const response = await request('GET', subscriptionPath(id), {
+      query: { $expand: 'ToAPIProduct,ToApplication,ToRatePlan' }, expect: [200, 404], withStatus: true, unwrap: false
+    });
+    if (response.status === 404) throw new IntegrationError('The selected subscription no longer exists');
+    const value = response.data?.d ?? response.data;
+    if (value?.id !== id || value.app_id !== application || value.product_id !== product || typeof value.developer_id !== 'string' || !value.developer_id || subscribed(value.isSubscribed) === null) {
+      throw new IntegrationError('Cannot establish the exact subscription and owner identities; unsubscribe refused');
+    }
+    const body = { id, app_id: value.app_id, product_id: value.product_id, developer_id: value.developer_id, isSubscribed: false };
+    for (const field of ['reg_id', 'ratePlan_id']) if (value[field] !== undefined) body[field] = value[field];
+    body.ToAPIProduct = reference(value.ToAPIProduct, 'APIProducts', product);
+    body.ToApplication = reference(value.ToApplication, 'Applications', application);
+    const ratePlan = reference(value.ToRatePlan, 'RatePlans', undefined, { nullable: true, scalar: value.ratePlan_id });
+    if (ratePlan) body.ToRatePlan = ratePlan;
+    return { value, body };
+  }
+
+  register('devhub_list_subscriptions', 'List consumer application subscriptions',
+    'List bounded subscription/application/product/rate-plan identities and subscribed/approval state from the expanded consumer application. No credentials or developer personal details are returned; incomplete relationships remain explicit.',
+    z.object({ application_id: applicationId, top: top(), cursor: cursorSchema }).strict(), READ_ONLY_ANNOTATIONS,
+    async ({ application_id, cursor, ...args }) => {
+      const scope = 'devhub_subscriptions';
+      if (cursor && collections.cursorContext(cursor, { scope })?.application_id !== application_id) throw new IntegrationError('Subscription cursor belongs to a different application');
+      const application = await namedApplication(application_id);
+      if (!application) throw new IntegrationError('Consumer application does not exist');
+      const legacy = relationPage(application.ToAPIProductsDetails);
+      const subscriptions = relationPage(application.ToSubscriptions);
+      const page = await collections.page({
+        ...args, cursor, path: `${applicationPath(application_id)}/ToSubscriptions`, mode: 'local',
+        raw: subscriptionPage(application), scope, context: { application_id }
+      });
+      const legacyComplete = Boolean(legacy && !legacy.next && (legacy.total === null || legacy.total === legacy.items.length));
+      const model = !legacyComplete ? 'unknown' : legacy.items.length
+        ? subscriptions?.items.length ? 'mixed' : 'legacy' : 'subscription';
+      return {
+        ...page, model, legacy_product_link_count: legacy?.total ?? (legacyComplete ? legacy.items.length : null),
+        legacy_relationships_complete: legacyComplete, complete: page.complete && legacyComplete,
+        ...(!legacyComplete && page.stop_reason === 'end' ? { stop_reason: 'source_limit' } : {})
+      };
+    });
+
+  register('devhub_unsubscribe_application', 'Unsubscribe application from a product',
+    'Preview by default. Execute one documented batch PUT for the exact existing subscription, preserving its actual relationship references; legacy or ambiguous models are refused. Requires UNSUBSCRIBE APPLICATION <application_id> FROM <product> before requests. Fresh isSubscribed:false read-back is required; this does not prove API-key invalidation or OAuth-token revocation.',
+    z.object({ application_id: applicationId, product: productName, dry_run: z.boolean().default(true), confirmation }).strict(), OVERWRITE_ANNOTATIONS,
+    async ({ application_id, product, dry_run = true, confirmation: approved }) => {
+      const required = `UNSUBSCRIBE APPLICATION ${application_id} FROM ${product}`;
+      if (!dry_run) requireConfirmation(approved, required);
+      const inventory = await inspect(application_id);
+      if (!inventory) throw new IntegrationError('Consumer application does not exist');
+      if (!inventory.complete) throw new IntegrationError('Cannot establish complete consumer relationships and owner; unsubscribe refused');
+      if (inventory.legacy.rows.length) throw new IntegrationError('Legacy product links are present; mixing subscription models is refused');
+      const matches = inventory.subscriptions.rows.filter(row => row.product_id === product);
+      if (matches.length !== 1) throw new IntegrationError('Expected exactly one existing subscription for the selected product; unsubscribe refused');
+      const subscription = await namedSubscription(matches[0].id, application_id, product);
+      if (inventory.owner.developer_id && inventory.owner.developer_id !== subscription.value.developer_id) throw new IntegrationError('Subscription owner differs from the application owner; unsubscribe refused');
+      const secrets = inventory.private_values.concat(privateValues(subscription.value));
+      const base = { application_id, product, subscription_id: subscription.value.id, ...credentialEffects };
+      if (dry_run) return redactPrivateValues({ ...base, dry_run: true, complete: true, is_subscribed: subscribed(subscription.value.isSubscribed), required_confirmation: required,
+        impact: 'Set only the selected existing subscription to isSubscribed:false; retain the application and every other subscription.' }, secrets);
+      if (subscribed(subscription.value.isSubscribed) === false) return redactPrivateValues({ ...base, accepted: false, already_unsubscribed: true, unsubscribed: true, read_back_verified: true }, secrets);
+      const intendedDigest = canonicalDigest({ body: subscription.body, relationship_references: referenceEvidence(subscription.body) });
+      const batch = `batch_${randomUUID()}`;
+      const changeset = `changeset_${randomUUID()}`;
+      const payload = [
+        `--${batch}`, `Content-Type: multipart/mixed; boundary=${changeset}`, '', `--${changeset}`,
+        'Content-Type: application/http', 'Content-Transfer-Encoding: binary', 'Content-ID: 1', '',
+        `PUT APIMgmt.Subscriptions(${key(subscription.value.id)}) HTTP/1.1`, 'Content-Type: application/json', 'Accept: application/json', '',
+        JSON.stringify(subscription.body), `--${changeset}--`, `--${batch}--`, ''
+      ].join('\r\n');
+      let response;
+      try { response = await request('POST', '/$batch', { body: payload, contentType: `multipart/mixed; boundary=${batch}`, accept: 'multipart/mixed', responseType: 'text', expect: [200, 202], withStatus: true }); }
+      catch (error) { return redactPrivateValues({ ...base, accepted: Number.isInteger(error?.status) ? false : null, unsubscribed: false, read_back_verified: false, outcome: 'unverified', source_result: failure(error) }, secrets); }
+      const statuses = [...String(response.data).matchAll(/(?:^|\r?\n)HTTP\/1\.[01] (\d{3})(?:[ \r\n])/g)].map(match => Number(match[1]));
+      const result = { ...base, batch_accepted: true, http_status: response.status, member_statuses: statuses.slice(0, 20), member_count: statuses.length,
+        member_statuses_truncated: statuses.length > 20, accepted: statuses.length === 1 ? statuses[0] >= 200 && statuses[0] < 300 : null,
+        unsubscribed: false, read_back_verified: false, outcome: 'unverified' };
+      if (result.accepted !== true) return redactPrivateValues({ ...result, ...(result.accepted === false ? { outcome: 'failed' } : {}) }, secrets);
+      const inner = String(response.data).slice(String(response.data).search(/HTTP\/1\.[01] /));
+      const headerEnd = /\r?\n\r?\n/.exec(inner);
+      if (!headerEnd) return redactPrivateValues(result, secrets);
+      const embeddedBody = inner.slice(headerEnd.index + headerEnd[0].length).split(/\r?\n--/)[0].trim();
+      if (embeddedBody) {
+        let decoded;
+        try { decoded = JSON.parse(embeddedBody); } catch { return redactPrivateValues(result, secrets); }
+        if (decoded?.error) return redactPrivateValues({ ...result, accepted: false, outcome: 'failed' }, secrets);
+        if (!decoded || typeof decoded !== 'object' || !(decoded.d || decoded.id)) return redactPrivateValues(result, secrets);
+      }
+      for (let attempt = 0; attempt < 4; attempt += 1) {
+        if (attempt) await sleep(readBackDelayMs);
+        try {
+          const observed = await namedSubscription(subscription.value.id, application_id, product);
+          secrets.push(...privateValues(observed.value));
+          if (subscribed(observed.value.isSubscribed) === false && canonicalDigest({ body: observed.body, relationship_references: referenceEvidence(observed.body) }) === intendedDigest) {
+            return redactPrivateValues({ ...result, unsubscribed: true, read_back_verified: true, outcome: 'succeeded' }, secrets);
+          }
+        } catch (error) { return redactPrivateValues({ ...result, source_result: failure(error) }, secrets); }
+      }
+      return redactPrivateValues(result, secrets);
+    });
+
+  register('devhub_delete_application', 'Delete consumer application',
+    'Preview by default; cache the complete owner/subscription/legacy-link approval for 15 minutes. Active subscriptions or any legacy product links require separately approved allow_active_subscriptions:true. Execute requires DELETE CONSUMER APPLICATION <SHA256> matching that cached preview before requests, then fresh equal relationships. DELETE once and verify named absence; API-key invalidation and issued OAuth-token revocation remain unverified.',
+    z.object({ application_id: applicationId, dry_run: z.boolean().default(true), allow_active_subscriptions: z.boolean().default(false), confirmation }).strict(), OVERWRITE_ANNOTATIONS,
+    async ({ application_id, dry_run = true, allow_active_subscriptions = false, confirmation: approved }) => {
+      for (const [digest, preview] of previews) if (Date.now() >= preview.expires) previews.delete(digest);
+      let cached;
+      if (!dry_run) {
+        const match = /^DELETE CONSUMER APPLICATION ([a-f0-9]{64})$/.exec(approved ?? '');
+        cached = match ? previews.get(match[1]) : null;
+        if (!cached || cached.application_id !== application_id || cached.allow_active_subscriptions !== allow_active_subscriptions) {
+          throw new IntegrationError('A matching unexpired deletion preview confirmation is required; request a new dry run before any network access');
+        }
+        requireConfirmation(approved, cached.required_confirmation);
+        // Claim once before yielding to network I/O; concurrent executions cannot reuse this approval.
+        previews.delete(match[1]);
+      }
+      const inventory = await inspect(application_id);
+      if (!inventory) return { application_id, dry_run, accepted: false, already_absent: true, deleted: false, deletion_verified: true, ...credentialEffects };
+      const binding = { origin: origin(), application_id, allow_active_subscriptions, ...inventory.evidence };
+      const digest = canonicalDigest(binding);
+      const required = `DELETE CONSUMER APPLICATION ${digest}`;
+      const active = inventory.subscriptions.rows.filter(row => subscribed(row.isSubscribed) === true).length;
+      const dependencyBlocked = !allow_active_subscriptions && (active > 0 || inventory.legacy.rows.length > 0);
+      const blocked = !inventory.complete || dependencyBlocked;
+      if (dry_run) {
+        if (!blocked) {
+          if (previews.size >= 128 && !previews.has(digest)) previews.delete(previews.keys().next().value);
+          previews.set(digest, { application_id, allow_active_subscriptions, binding, required_confirmation: required, expires: Date.now() + PREVIEW_TTL });
+        }
+        return redactPrivateValues({
+          application_id, host: new URL(origin()).host, dry_run: true, complete: inventory.complete, blocked, allow_active_subscriptions,
+          owner: { identity_sha256: canonicalDigest(inventory.owner) },
+          subscriptions: { count: inventory.subscriptions.rows.length, active_count: active, complete: inventory.subscriptions.complete,
+            items: inventory.subscriptions.rows.slice(0, 100).map(row => subscriptionSummary(row, application_id)), summaries_truncated: inventory.subscriptions.rows.length > 100 },
+          legacy_product_links: { count: inventory.legacy.rows.length, complete: inventory.legacy.complete,
+            product_ids: inventory.legacy.rows.slice(0, 100).map(row => identityFor(row, 'ToAPIProductsDetails')), summaries_truncated: inventory.legacy.rows.length > 100 },
+          findings: [...inventory.findings, ...(dependencyBlocked ? ['active_subscriptions_or_legacy_product_links_require_explicit_permission'] : [])],
+          ...(blocked ? {} : { required_confirmation: required, approval_expires_at: new Date(Date.now() + PREVIEW_TTL).toISOString() }),
+          impact: 'Delete only this consumer application and its application associations. No product/proxy/developer deletion; credential and token revocation are not verified.', ...credentialEffects
+        }, inventory.private_values);
+      }
+      if (!inventory.complete || blocked || Date.now() >= cached.expires || canonicalDigest(cached.binding) !== digest) throw new IntegrationError('Consumer owner or relationships changed, became incomplete, or approval expired; deletion refused. Request a new dry run.');
+      const base = { application_id, ...credentialEffects };
+      const clean = value => redactPrivateValues(value, inventory.private_values);
+      let response;
+      try { response = await request('DELETE', applicationPath(application_id), { expect: [...Array.from({ length: 100 }, (_, index) => 200 + index), 404], responseType: 'none', withStatus: true }); }
+      catch (error) { return clean({ ...base, accepted: Number.isInteger(error?.status) ? false : null, deleted: false, deletion_verified: false, outcome: 'unverified', source_result: failure(error) }); }
+      const accepted = response.status >= 200 && response.status < 300;
+      const result = { ...base, accepted, http_status: response.status, deleted: false, deletion_verified: false, outcome: 'unverified' };
+      for (let attempt = 0; attempt < 4; attempt += 1) {
+        if (attempt) await sleep(readBackDelayMs);
+        try {
+          if (!await namedApplication(application_id, false)) return clean({ ...result, deleted: accepted, already_absent: !accepted, deletion_verified: true, outcome: 'succeeded' });
+        } catch (error) { return clean({ ...result, source_result: failure(error) }); }
+      }
+      return clean({ ...result, pending: true });
+    });
+}

package/src/devhub-tools.mjs

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { CREATE_ANNOTATIONS, OVERWRITE_ANNOTATIONS, READ_ONLY_ANNOTATIONS, entity, key, list, pick, redactSecrets, requireConfirmation, top } from './integration-common.mjs';
+import { IntegrationError } from './integration-http.mjs';
+import { redactPrivateValues } from './apim-runtime.mjs';
+import { createCollectionPager, cursorSchema } from './integration-collections.mjs';
+import { registerDevhubRetirementTools } from './devhub-retirement.mjs';
+
+const DATA = '/odata/1.0/data.svc';
+const applicationId = z.string().min(1).max(256).regex(/^[A-Za-z0-9_-]+$/);
+const developerId = z.string().min(1).max(256).regex(/^[A-Za-z0-9_.@-]+$/);
+const productName = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,99}$/);
+const confirmation = z.string().min(1);
+const EMPTY_ID = '00000000000000000000000000000000';
+
+function applicationSummary(value) {
+  if (!value) return null;
+  const cleaned = entity(value);
+  const summary = {
+    ...redactSecrets(pick(cleaned, ['id', 'title', 'description', 'version', 'callbackurl', 'developer_id', 'reg_id', 'status', 'status_code', 'valid_from', 'valid_to', 'ToSubscriptions', 'ToAPIProductsDetails'])),
+    has_consumer_key: typeof cleaned.app_key === 'string' && cleaned.app_key.length > 0
+  };
+  return redactPrivateValues(summary, [cleaned.app_key, cleaned.app_secret]);
+}
+
+function applicationListSummary(value) {
+  const application = entity(value);
+  return redactPrivateValues(pick(application, ['id', 'title', 'version', 'status', 'status_code', 'valid_from', 'valid_to']),
+    [application.app_key, application.app_secret]);
+}
+
+function developerListSummary(value) {
+  return {
+    ...pick(value, ['id', 'status']),
+    roles: list(value.rolesAccess).map(role => pick(role, ['role', 'status']))
+  };
+}
+
+/** Register Developer Hub tools; application credentials are never returned. */
+export function registerDevhubTools(register, client, { readBackDelayMs } = {}) {
+  const request = (method, path, options) => client.request(method, `${DATA}${path}`, options);
+  const collections = createCollectionPager(client, { root: DATA, request });
+  const registrations = createCollectionPager(client, { root: '/api/1.0' });
+  registerDevhubRetirementTools(register, client, { readBackDelayMs });
+  async function getApplication(id) {
+    const { status, data } = await request('GET', `/APIMgmt.Applications(${key(id)})`, {
+      query: { $expand: 'ToAPIProductsDetails,ToSubscriptions/ToAPIProduct,ToSubscriptions/ToRatePlan' },
+      expect: [200, 404], withStatus: true
+    });
+    if (status === 404) throw new IntegrationError(`Developer Hub application ${id} does not exist`);
+    return data;
+  }
+
+  register('devhub_list_developers', 'List Developer Hub developers',
+    'List registered Developer Hub role/status metadata without personal details or credentials. Requires a Developer Hub API-access service key.',
+    { top: top(), cursor: cursorSchema }, READ_ONLY_ANNOTATIONS,
+    async args => registrations.page({
+      ...args, path: '/registrations', query: { type: 'registered' }, mode: 'local', project: developerListSummary
+    }));
+
+  register('devhub_create_developer', 'Onboard application developer',
+    'Submit Developer Hub onboarding for an application developer using the admin API-access key. Approval is a separate devhub_approve_developer operation. Requires confirmation CREATE DEVELOPER <user_id>.',
+    {
+      user_id: developerId,
+      first_name: z.string().min(1).max(255),
+      last_name: z.string().min(1).max(255),
+      email: z.string().email().max(255),
+      country: z.string().max(255).default(''),
+      reason: z.string().min(1).max(2048),
+      confirmation
+    }, CREATE_ANNOTATIONS,
+    async ({ user_id, first_name, last_name, email, country, reason, confirmation }) => {
+      requireConfirmation(confirmation, `CREATE DEVELOPER ${user_id}`);
+      await client.request('POST', '/api/1.0/registrations', {
+        json: {
+          userId: user_id, firstName: first_name, lastName: last_name, emailId: email, country,
+          rolesAccess: [{ requestReason: reason, role: 'API_ApplicationDeveloper' }]
+        },
+        expect: [201]
+      });
+      return { created: true, user_id, role: 'API_ApplicationDeveloper', approval_required: true };
+    });
+
+  register('devhub_approve_developer', 'Approve application developer',
+    'Approve an onboarded Developer Hub application developer using the admin API-access key. Requires confirmation APPROVE DEVELOPER <user_id>.',
+    { user_id: developerId, reason: z.string().min(1).max(2048), confirmation }, OVERWRITE_ANNOTATIONS,
+    async ({ user_id, reason, confirmation }) => {
+      requireConfirmation(confirmation, `APPROVE DEVELOPER ${user_id}`);
+      await client.request('PUT', `/api/1.0/registrations/${encodeURIComponent(user_id)}`, {
+        json: { rolesAccess: [{ status: 'registered', role: 'API_ApplicationDeveloper', responseReason: reason }] },
+        expect: [200, 204]
+      });
+      return { approved: true, user_id, role: 'API_ApplicationDeveloper' };
+    });
+
+  register('devhub_create_application', 'Create subscribed consumer application',
+    'Create a Developer Hub application on behalf of a registered developer with product subscriptions. SAP provisions the consumer key; key/secret values are redacted from output. External governance, if configured, may leave subscriptions pending. Requires confirmation CREATE CONSUMER APPLICATION <application_id>.',
+    {
+      application_id: applicationId,
+      developer_id: developerId,
+      title: z.string().min(1).max(255),
+      description: z.string().max(2048).default(''),
+      callback_url: z.string().url().max(2048).refine(value => {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !url.username && !url.password;
+      }, 'callback URL must use HTTPS without embedded credentials').optional(),
+      products: z.array(productName).min(1).max(50).refine(values => new Set(values).size === values.length, 'products must be unique'),
+      confirmation
+    }, CREATE_ANNOTATIONS,
+    async ({ application_id, developer_id, title, description, callback_url, products, confirmation }) => {
+      requireConfirmation(confirmation, `CREATE CONSUMER APPLICATION ${application_id}`);
+      const found = list(await request('GET', '/APIMgmt.Applications', {
+        query: { $filter: `id eq '${application_id}'`, $top: 1 }
+      }));
+      if (found.some(app => app.id === application_id)) throw new IntegrationError(`Developer Hub application ${application_id} already exists; read it instead of creating it again`);
+      for (const product of products) {
+        const { status } = await request('GET', `/APIMgmt.APIProducts(${key(product)})`, { expect: [200, 404], withStatus: true });
+        if (status === 404) throw new IntegrationError(`Developer Hub product ${product} is not available; publish it before creating the application`);
+      }
+      const created = await request('POST', '/APIMgmt.Applications', {
+        json: {
+          id: application_id, version: '1', title, description, callbackurl: callback_url ?? null, developer_id,
+          ToSubscriptions: products.map(product => ({
+            id: EMPTY_ID, ToAPIProduct: [{ __metadata: { uri: `APIMgmt.APIProducts('${product}')` } }]
+          }))
+        },
+        expect: [200, 201]
+      });
+      return {
+        created: true, application_id, application: applicationSummary(created),
+        note: 'Read the application to check subscription approval and key availability. Do not repeat creation after a successful write.'
+      };
+    });
+
+  register('devhub_subscribe_application', 'Subscribe application to a product',
+    'Create a product subscription for an existing subscription-based Developer Hub application. Does not bypass external governance or return key/secret values. Requires confirmation SUBSCRIBE APPLICATION <application_id> TO <product>.',
+    { application_id: applicationId, product: productName, confirmation }, CREATE_ANNOTATIONS,
+    async ({ application_id, product, confirmation }) => {
+      requireConfirmation(confirmation, `SUBSCRIBE APPLICATION ${application_id} TO ${product}`);
+      const application = await getApplication(application_id);
+      const subscriptions = list(application.ToSubscriptions);
+      if (subscriptions.some(subscription => subscription.product_id === product)) {
+        throw new IntegrationError(`Application ${application_id} already has a subscription for ${product}; read its status instead of creating a duplicate`);
+      }
+      if (!subscriptions.length && list(application.ToAPIProductsDetails).length) {
+        throw new IntegrationError('This application uses legacy product links; create a subscription-based application instead of mixing subscription models');
+      }
+      const created = await request('POST', '/APIMgmt.Subscriptions', {
+        json: {
+          id: EMPTY_ID,
+          ToAPIProduct: [{ __metadata: { uri: `APIMgmt.APIProducts('${product}')` } }],
+          ToApplication: [{ __metadata: { uri: `APIMgmt.Applications('${application_id}')` } }]
+        },
+        expect: [200, 201]
+      });
+      return { created: true, application_id, product, subscription: redactPrivateValues(redactSecrets(entity(created)), [application.app_key, application.app_secret]) };
+    });
+
+  register('devhub_list_applications', 'List consumer applications',
+    'List Developer Hub application metadata. Consumer keys and secrets are not returned; use devhub_get_application for subscription details.',
+    { top: top(), cursor: cursorSchema }, READ_ONLY_ANNOTATIONS,
+    async args => collections.page({
+      ...args, path: '/APIMgmt.Applications', orderBy: 'id asc', identity: application => application.id,
+      project: applicationListSummary
+    }));
+
+  register('devhub_get_application', 'Get consumer application',
+    'Read one Developer Hub application with its product subscriptions. Consumer key/secret values are redacted; has_consumer_key reports key availability.',
+    { application_id: applicationId }, READ_ONLY_ANNOTATIONS,
+    async ({ application_id }) => applicationSummary(await getApplication(application_id)));
+
+}
+
+export function devhubToolNames() {
+  const names = [];
+  registerDevhubTools(name => names.push(name), null);
+  return names;
+}

package/src/edge-monitoring.mjs

@@ -0,0 +1,101 @@
+// Read-only Edge local API discovery and shared, payload-free MPL diagnosis.
+import { READ_ONLY_ANNOTATIONS } from './integration-common.mjs';
+import { IntegrationError } from './integration-http.mjs';
+import { createCollectionPager } from './integration-collections.mjs';
+import { getMessageLog, listMessageLogs, messageGuid, mplListInputs } from './cpi-monitoring.mjs';
+import { childElements, xmlChildren, xmlAttributes } from './apim-bundle.mjs';
+
+const ROOT = '/local/api/eic/v1';
+const MPL_ROOT = '/local/api/v1';
+const SOURCES = [
+  'https://github.com/SAP-docs/btp-integration-suite/blob/main/docs/ISuite_Edge_Integration_Cell/local-odata-api-access-fe61332.md',
+  'https://github.com/SAP-docs/btp-integration-suite/blob/main/docs/ISuite_Edge_Integration_Cell/operations-cockpit-api-da1abc0.md'
+];
+const ROUTES = [
+  '/Components', '/Components/<component ID>/Pods', '/Components/<component ID>/Pods/<pod name>/Events',
+  '/Components/<component ID>/Pods/<pod name>/Metrics', '/Components/<component ID>/RuntimeParameters',
+  '/Jobs', '/Jobs/<jobId>/Schedule'
+];
+const localName = element => element.name.split(':').at(-1);
+const identifier = value => typeof value === 'string' && value.length <= 200 && /^[A-Za-z_][A-Za-z0-9_.]*$/.test(value);
+
+function operationalBoundary() {
+  return {
+    published_routes: ROUTES.map(path => `${ROOT}${path}`),
+    operational_field_contract: 'not_established',
+    discovery_scope: 'Entity presence is discovery only, not an administrative or field-level operational contract.',
+    native_handoff: {
+      prerequisites: ['Exact Edge cell/runtime, component/pod/job identities and authorized native cockpit access'],
+      steps: ['Open the Edge Integration Cell Operations Cockpit', 'Select Component Monitor or Job Management and the exact component/pod/job', 'Inspect native status, event logs, metrics or schedule; correlate supported local MPL identities separately'],
+      safety_warning: 'No component status guesses, restart, Kubernetes, job-control, message-store or payload access is provided.',
+      post_action_verification: ['Refresh native diagnostics and read bounded local MPL metadata for the exact message/time window']
+    },
+    source_links: [...SOURCES]
+  };
+}
+
+function metadataInventory(xml) {
+  if (typeof xml !== 'string' || /<!DOCTYPE|<!ENTITY/i.test(xml)) throw new IntegrationError('Edge local metadata is not a supported OData metadata document');
+  try {
+    const roots = childElements(xml, 0, xml.length);
+    if (roots.length !== 1 || localName(roots[0]) !== 'Edmx') throw new Error('root');
+    const services = xmlChildren(xml, roots[0]).filter(element => localName(element) === 'DataServices');
+    if (services.length !== 1) throw new Error('services');
+    const schemas = [];
+    const entity_sets = [];
+    let complete = true;
+    const accept = (array, value) => {
+      array.push(value);
+      if (Buffer.byteLength(JSON.stringify({ schemas, entity_sets }, null, 2)) > 80 * 1024) { array.pop(); complete = false; }
+    };
+    for (const schema of xmlChildren(xml, services[0]).filter(element => localName(element) === 'Schema')) {
+      const namespace = xmlAttributes(xml, schema).Namespace;
+      if (!identifier(namespace)) { complete = false; continue; }
+      accept(schemas, namespace);
+      for (const container of xmlChildren(xml, schema).filter(element => localName(element) === 'EntityContainer')) {
+        for (const set of xmlChildren(xml, container).filter(element => localName(element) === 'EntitySet')) {
+          const attrs = xmlAttributes(xml, set);
+          if (!identifier(attrs.Name) || !identifier(attrs.EntityType)) { complete = false; continue; }
+          accept(entity_sets, { name: attrs.Name, entity_type: attrs.EntityType });
+        }
+      }
+    }
+    if (!schemas.length) throw new Error('schemas');
+    return { schemas, entity_sets, complete, stop_reason: complete ? 'end' : 'source_limit' };
+  } catch {
+    // Never copy an unexpected XML tag, annotation, property or schema body into diagnostics.
+    throw new IntegrationError('Edge local metadata is not a supported OData metadata document');
+  }
+}
+
+async function localRead(operation) {
+  try { return await operation(); }
+  catch (error) {
+    if (!Number.isInteger(error?.status) || error.status < 400) throw error;
+    const detail = error.status === 401 ? 'A local 401 may indicate a missing /local prefix or authentication failure.'
+      : error.status === 403 ? 'Access is denied; an unsupported local endpoint can also return 403.'
+        : 'The requested local read could not be completed.';
+    throw new IntegrationError(`Edge local API read failed (HTTP ${error.status}). ${detail} Activation and entitlement remain unknown; no health or no-traffic conclusion is established.`, { status: error.status });
+  }
+}
+
+/** Construction performs no network or client access, including null-client name discovery. */
+export function registerEdgeMonitoringTools(register, client) {
+  const read = (path, options) => client.request('GET', `${MPL_ROOT}${path}`, options);
+  const pager = createCollectionPager(client, { root: MPL_ROOT, request: (_method, path, options) => read(path, options) });
+
+  register('edge_get_api_metadata', 'Discover Edge local API metadata',
+    'Read /local/api/eic/v1/$metadata as bounded schema/entity-set identities only. Published component/pod/job routes are discovery, not safe field-level status contracts. Use the native Operations Cockpit for those diagnostics; no raw XML, source, payloads, actions or arbitrary reads.',
+    {}, READ_ONLY_ANNOTATIONS, () => localRead(async () => {
+      const xml = await client.request('GET', `${ROOT}/$metadata`, { responseType: 'text', accept: 'application/xml, text/xml' });
+      return { result: 'ok', service_root: ROOT, ...metadataInventory(xml), ...operationalBoundary() };
+    }));
+
+  register('edge_list_message_logs', 'List Edge local message logs',
+    'Read bounded local MPL metadata in the shared fixed UTC [from,to) LogStart window of at most 31 days. Supply both timestamps or neither (frozen last 24 hours). Signed continuations retain that window; traversal is best effort. /local and configured local Basic authority are preserved. Access denial establishes neither no traffic nor non-entitlement.',
+    mplListInputs, READ_ONLY_ANNOTATIONS, args => localRead(() => listMessageLogs(pager, args)));
+
+  register('edge_get_message_log', 'Get Edge local message log',
+    'Read one local MPL identity, bounded redacted error text and credential-filtered custom header properties using the same diagnostic contract as CPI. No payloads, attachments, cloud statistics or JMS access. A local 401 may indicate missing /local; unsupported endpoints can return 403, not proof of non-entitlement.',
+    { message_guid: messageGuid }, READ_ONLY_ANNOTATIONS, ({ message_guid }) => localRead(() => getMessageLog(read, pager, message_guid)));
+}