#!/usr/bin/env node import { readFile, writeFile, mkdir } from "node:fs/promises"; import { dirname, resolve } from "node:path"; const EXTERNAL_SCOPES = Object.freeze(["adresse-extern", "archiv-extern", "termin-extern", "vorgang-extern", "aktivitaet-extern"]); const CAPABILITY_BY_TAG = Object.freeze({ Adresse: "address", Aktivitaet: "activity", Aktivitaetenverwaltung: "activity", ArchivExternal: "archive", Monteursteuerung: "schedule", Projekt: "project", Projektampel: "project", Termin: "schedule", VorgangAnzeige: "project", VorgangInfo: "project", }); const MUTATION_PATH_PATTERN = /\/(?:Add|Delete|Import|Publish|Remove|Reset|Save)[^/]*$/u; const SUPPORTED_METHODS = new Set(["delete", "get", "post", "put", "patch"]); const CONTRACT_OUTPUT = "packages/integrations/src/kwp/contract/kwp-scoped-openapi.json"; const CATALOG_OUTPUT = "packages/integrations/src/kwp/contract/catalog.generated.ts"; const SCOPE_DOC_OUTPUT = "docs/integrations/KWP-API-SCOPE.md"; const [inputArg, contractOutputArg, scopeDocOutputArg, catalogOutputArg] = process.argv.slice(2); if (!inputArg) { process.stderr.write("Usage: node scripts/generate-kwp-scoped-contract.mjs [contract-output] [scope-doc-output] [catalog-output]\n"); process.exitCode = 1; } else { await generate({ inputPath: resolve(inputArg), contractOutputPath: resolve(contractOutputArg ?? CONTRACT_OUTPUT), scopeDocOutputPath: resolve(scopeDocOutputArg ?? SCOPE_DOC_OUTPUT), catalogOutputPath: resolve(catalogOutputArg ?? CATALOG_OUTPUT), }); } async function generate({ inputPath, contractOutputPath, scopeDocOutputPath, catalogOutputPath }) { const source = JSON.parse(await readFile(inputPath, "utf8")); assertOpenApi(source); const allOperations = listOperations(source); const scopedOperations = allOperations .filter((operation) => operation.scopes.some((scope) => EXTERNAL_SCOPES.includes(scope))) .map((operation) => ({ ...operation, capability: requireCapability(operation.tag), mode: MUTATION_PATH_PATTERN.test(operation.path) ? "mutation" : "read", })) .sort(compareOperations); assertInventory(allOperations, scopedOperations); const duplicatePaths = new Set( scopedOperations .filter((operation, index, operations) => operations.some((candidate, candidateIndex) => candidateIndex !== index && candidate.path === operation.path)) .map((operation) => operation.path) ); const paths = {}; for (const operation of scopedOperations) { const operationId = buildOperationId(operation, duplicatePaths); const operationContract = stripDocumentationMetadata(structuredClone(operation.contract)); operationContract.operationId = operationId; operationContract["x-hivegrid-capability"] = operation.capability; operationContract["x-hivegrid-mode"] = operation.mode; paths[operation.path] ??= {}; paths[operation.path][operation.method] = operationContract; } const schemaNames = collectReferencedSchemaNames(paths, source.components.schemas); const schemas = Object.fromEntries( [...schemaNames].sort((left, right) => left.localeCompare(right)).map((name) => [name, stripDocumentationMetadata(source.components.schemas[name])]) ); const inventory = { sourceOperationCount: allOperations.length, scopedOperationCount: scopedOperations.length, readOperationCount: scopedOperations.filter((operation) => operation.mode === "read").length, mutationOperationCount: scopedOperations.filter((operation) => operation.mode === "mutation").length, excludedOperationCount: allOperations.length - scopedOperations.length, externalScopes: EXTERNAL_SCOPES, capabilities: Object.fromEntries( [...new Set(scopedOperations.map((operation) => operation.capability))].sort().map((capability) => [ capability, { total: scopedOperations.filter((operation) => operation.capability === capability).length, read: scopedOperations.filter((operation) => operation.capability === capability && operation.mode === "read").length, mutation: scopedOperations.filter((operation) => operation.capability === capability && operation.mode === "mutation").length, }, ]) ), }; const scopedContract = { openapi: source.openapi, info: { title: "KWP Api, licensed scope", version: source.info.version, }, paths: sortObject(paths), components: { schemas }, "x-hivegrid-inventory": inventory, }; await mkdir(dirname(contractOutputPath), { recursive: true }); await writeFile(contractOutputPath, `${JSON.stringify(scopedContract, null, 2)}\n`); await mkdir(dirname(scopeDocOutputPath), { recursive: true }); await writeFile(scopeDocOutputPath, renderScopeDocument(scopedOperations, inventory, inputPath)); await mkdir(dirname(catalogOutputPath), { recursive: true }); await writeFile(catalogOutputPath, renderTypeScriptCatalog(scopedOperations, duplicatePaths, inventory)); process.stdout.write( `Generated ${scopedOperations.length} KWP scoped operations (${inventory.readOperationCount} read, ${inventory.mutationOperationCount} mutation).\n` ); } function assertOpenApi(value) { if ( !value || typeof value !== "object" || typeof value.openapi !== "string" || !value.info || typeof value.info.version !== "string" || !value.paths || typeof value.paths !== "object" || !value.components?.schemas || typeof value.components.schemas !== "object" ) { throw new Error("The input is not the expected KWP OpenAPI document"); } } function listOperations(source) { const operations = []; for (const [path, pathItem] of Object.entries(source.paths)) { for (const [method, contract] of Object.entries(pathItem)) { if (!SUPPORTED_METHODS.has(method) || !contract || typeof contract !== "object") continue; const tag = Array.isArray(contract.tags) ? contract.tags[0] : undefined; if (typeof tag !== "string" || tag.length === 0) { throw new Error(`KWP operation ${method.toUpperCase()} ${path} has no tag`); } operations.push({ method, path, tag, summary: typeof contract.summary === "string" ? contract.summary : "", scopes: readSecurityScopes(contract.security), contract, }); } } return operations; } function readSecurityScopes(security) { if (!Array.isArray(security)) return []; return [ ...new Set( security.flatMap((entry) => entry && typeof entry === "object" && Array.isArray(entry.oauth2) ? entry.oauth2.filter((scope) => typeof scope === "string") : [] ) ), ]; } function requireCapability(tag) { const capability = CAPABILITY_BY_TAG[tag]; if (!capability) throw new Error(`Scoped KWP tag ${tag} is not assigned to a capability`); return capability; } function assertInventory(allOperations, scopedOperations) { const readCount = scopedOperations.filter((operation) => operation.mode === "read").length; const mutationCount = scopedOperations.length - readCount; if (allOperations.length !== 554 || scopedOperations.length !== 113 || readCount !== 77 || mutationCount !== 36) { throw new Error(`KWP inventory drifted: total=${allOperations.length}, scoped=${scopedOperations.length}, read=${readCount}, mutation=${mutationCount}`); } } function buildOperationId(operation, duplicatePaths) { const base = `${toIdentifier(operation.tag, false)}${toIdentifier(operation.path.split("/").at(-1), true)}`; return duplicatePaths.has(operation.path) ? `${base}${toIdentifier(operation.method, true)}` : base; } function toIdentifier(value, upperFirst) { const words = String(value ?? "").match(/[A-Za-z0-9]+/gu) ?? []; const joined = words .map((word, index) => { const normalized = word[0].toUpperCase() + word.slice(1); if (index === 0 && !upperFirst) return normalized[0].toLowerCase() + normalized.slice(1); return normalized; }) .join(""); if (!joined) throw new Error(`Cannot derive an operation identifier from ${value}`); return joined; } function collectReferencedSchemaNames(value, allSchemas) { const found = new Set(); const pending = [...findRefs(value)]; while (pending.length > 0) { const ref = pending.pop(); const prefix = "#/components/schemas/"; if (!ref.startsWith(prefix)) { throw new Error(`Unsupported KWP contract reference ${ref}`); } const name = decodeURIComponent(ref.slice(prefix.length)); if (found.has(name)) continue; const schema = allSchemas[name]; if (!schema) throw new Error(`Missing KWP schema ${name}`); found.add(name); pending.push(...findRefs(schema)); } return found; } function findRefs(value) { if (Array.isArray(value)) return value.flatMap(findRefs); if (!value || typeof value !== "object") return []; return Object.entries(value).flatMap(([key, nested]) => (key === "$ref" && typeof nested === "string" ? [nested] : findRefs(nested))); } function stripDocumentationMetadata(value) { if (Array.isArray(value)) return value.map(stripDocumentationMetadata); if (!value || typeof value !== "object") return value; return Object.fromEntries( Object.entries(value) .filter(([key]) => key !== "description") .map(([key, nested]) => [key, stripDocumentationMetadata(nested)]) ); } function compareOperations(left, right) { return ( left.capability.localeCompare(right.capability) || left.tag.localeCompare(right.tag) || left.path.localeCompare(right.path) || left.method.localeCompare(right.method) ); } function sortObject(value) { return Object.fromEntries( Object.entries(value) .sort(([left], [right]) => left.localeCompare(right)) .map(([key, nested]) => [key, nested && typeof nested === "object" && !Array.isArray(nested) ? sortObject(nested) : nested]) ); } function renderScopeDocument(operations, inventory) { const capabilityRows = Object.entries(inventory.capabilities) .map(([capability, counts]) => `| ${capability} | ${counts.total} | ${counts.read} | ${counts.mutation} |`) .join("\n"); const operationRows = operations .map((operation) => { const id = buildOperationId( operation, new Set( operations .filter((candidate, index, all) => all.some((other, otherIndex) => otherIndex !== index && other.path === candidate.path)) .map((candidate) => candidate.path) ) ); return `| \`${id}\` | ${operation.capability} | ${operation.mode} | \`${operation.method.toUpperCase()}\` | \`${operation.path}\` | ${escapeTableText(operation.summary)} |`; }) .join("\n"); return `# KWP API: lizenzierter HiveGrid-Scope > Generiert aus der am 2026-07-24 secretsicher gelesenen Tenant-OpenAPI. Die kundenspezifische > Roh-Spezifikation, Server-URL und Credentials werden nicht eingecheckt. ## Inventur - OpenAPI-Operationen gesamt: **${inventory.sourceOperationCount}** - Über die fünf HiveGrid-\`*-extern\`-Scopes erreichbar: **${inventory.scopedOperationCount}** - Semantisch lesend und runtime-allowlisted: **${inventory.readOperationCount}** - Mutierend, nur Contract/Fixture und runtime-gesperrt: **${inventory.mutationOperationCount}** - Außerhalb des lizenzierten HiveGrid-Scopes: **${inventory.excludedOperationCount}** | Capability | Gesamt | Read | Mutation | |---|---:|---:|---:| ${capabilityRows} Die OpenAPI-Security-Arrays nennen mehrere alternative KWP-Produkte und die fünf externen Scopes, obwohl die OAuth-Flow-Scope-Liste diese externen Namen nicht aufführt. HiveGrid klassifiziert eine Operation nur dann als scoped, wenn mindestens einer der fünf tatsächlich angeforderten externen Scopes am Endpoint steht. ## Sicherheitsvertrag - Fachcode übergibt nur eine feste Operation-ID plus deren typisierten Input, niemals URL, Pfad, Token, Mandant oder Kundenkürzel. - \`Search\`, \`Load\`, \`Count\`, \`Get\` und \`Check\` können trotz \`POST\` read-only sein. - \`Save\`, \`Add\`, \`Delete\`, \`Remove\`, \`Import\`, \`Publish\` und \`Reset\` sind Mutation. - Mutation wird vor Rate-Budget, Relay-Auflösung und HTTP blockiert. - Der Scoped-Contract enthält nur rekursiv benötigte Schemas und keine tenant-spezifische Server-URL. ## Operationen | ID | Capability | Modus | Methode | Pfad | KWP-Zusammenfassung | |---|---|---|---|---|---| ${operationRows} `; } function renderTypeScriptCatalog(operations, duplicatePaths, inventory) { const entries = operations .map((operation) => { const value = { id: buildOperationId(operation, duplicatePaths), capability: operation.capability, mode: operation.mode, method: operation.method.toUpperCase(), path: operation.path, }; return ` ${JSON.stringify(value)},`; }) .join("\n"); return `// Generated by scripts/generate-kwp-scoped-contract.mjs. Do not edit manually. export const KWP_SCOPED_OPERATION_INVENTORY = Object.freeze({ sourceOperationCount: ${inventory.sourceOperationCount}, scopedOperationCount: ${inventory.scopedOperationCount}, readOperationCount: ${inventory.readOperationCount}, mutationOperationCount: ${inventory.mutationOperationCount}, excludedOperationCount: ${inventory.excludedOperationCount}, } as const); export const KWP_SCOPED_OPERATIONS = Object.freeze([ ${entries} ] as const); export type KwpScopedOperation = (typeof KWP_SCOPED_OPERATIONS)[number]; export type KwpScopedOperationId = KwpScopedOperation["id"]; export type KwpReadOperationId = Extract["id"]; export type KwpMutationOperationId = Extract["id"]; export type KwpCapability = KwpScopedOperation["capability"]; `; } function escapeTableText(value) { return value.replaceAll("|", "\\|").replaceAll(/\s+/gu, " ").trim(); }