@cat-factory/integrations 0.166.22 → 0.168.0

package/dist/modules/serviceCatalog/ServiceCatalogConnectionService.js

@@ -0,0 +1,177 @@
+import { DEFAULT_MAX_CATALOG_SERVICES, DEFAULT_SERVICE_CATALOG_FILTER, } from '@cat-factory/contracts';
+import { createOrgSecretCipher, noopLogger, orgSecretRef } from '@cat-factory/kernel';
+import { assertSafePublicUrl } from '../shared/url-guard.js';
+import { BackstageCatalogClient } from './BackstageCatalogClient.js';
+import { parseServiceCatalogAuth } from './serviceCatalogAuth.js';
+// ---------------------------------------------------------------------------
+// The workspace's SERVICE CATALOG connection: connect, read, probe, disconnect, and build the
+// client an import reads through.
+//
+// The credential bag is sealed and opened here and only here, so nothing else in the feature
+// (the controller, the importer, the sweeps) ever holds plaintext. The cipher goes through
+// `createOrgSecretCipher`, which makes a mothership-mode node open the row by NAMING it over the
+// secret delegation rather than with a key it does not have.
+// ---------------------------------------------------------------------------
+/**
+ * The HKDF domain the service-catalog credential is sealed under.
+ *
+ * Its own domain rather than the documents or environments one, so a key rotation or a compromise
+ * scoped to one integration cannot open another's rows. Declared HERE, once, and imported by both
+ * runtime facades and by `SEALED_SECRET_SOURCES`: the value has to be the same in all three or a
+ * mothership-delegated unseal authenticates against a different derived key, and that drift is
+ * both silent and unrecoverable, which is not a property any copied literal should carry.
+ */
+export const SERVICE_CATALOG_CIPHER_INFO = 'cat-factory:service-catalog';
+export class ServiceCatalogConnectionService {
+    deps;
+    log;
+    orgSecrets;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.logger ?? noopLogger;
+        this.orgSecrets = createOrgSecretCipher({
+            cipher: deps.secretCipher,
+            ...(deps.secretDelegate ? { delegate: deps.secretDelegate } : {}),
+        });
+    }
+    /**
+     * The connection as the management surface sees it, or null when there is none.
+     *
+     * A tombstoned row answers NULL, exactly as `resolveClient` and the importer treat one. The
+     * repository's `get` deliberately still returns it, because a re-connect reads the row to keep
+     * the prior verdict and the original `connectedAt`; the disposal of a tombstone is the caller's,
+     * and every caller but that one wants "there is no connection". Returning it here would render a
+     * disconnected workspace as connected, with an "Import now" button that 404s.
+     */
+    async get(workspaceId) {
+        const record = await this.deps.serviceCatalogConnectionRepository.get(workspaceId);
+        return record && record.deletedAt === null ? toWire(record) : null;
+    }
+    /**
+     * Connect or replace the workspace's connection.
+     *
+     * The base URL is validated BEFORE anything is sealed, so a typo or a blocked host is refused
+     * while the operator is still looking at the form rather than becoming a stored connection that
+     * fails on every import.
+     */
+    async connect(workspaceId, input) {
+        const baseUrl = this.assertBaseUrl(input.baseUrl);
+        const now = this.deps.clock.now();
+        const existing = await this.deps.serviceCatalogConnectionRepository.get(workspaceId);
+        const record = {
+            workspaceId,
+            provider: input.provider ?? 'backstage',
+            baseUrl,
+            authMode: input.auth.mode,
+            credentialsCipher: await this.sealAuth(workspaceId, input.auth),
+            entityFilter: normalizeFilter(input.entityFilter),
+            includeApis: input.includeApis ?? true,
+            maxServices: input.maxServices ?? DEFAULT_MAX_CATALOG_SERVICES,
+            // The prior pass's verdict is KEPT rather than cleared. Re-entering a rotated token does not
+            // change what the last import found, and blanking it would present a workspace with a
+            // truncated estate as one that has never imported.
+            lastSyncedAt: existing?.lastSyncedAt ?? null,
+            lastSyncStatus: existing?.lastSyncStatus ?? null,
+            lastSyncMessage: existing?.lastSyncMessage ?? null,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            deletedAt: null,
+        };
+        await this.deps.serviceCatalogConnectionRepository.upsert(record);
+        this.log.info('serviceCatalog.connected', {
+            workspaceId,
+            provider: record.provider,
+            authMode: record.authMode,
+        });
+        return toWire(record);
+    }
+    /** Forget the credential. Tombstoning what it imported is the importer's half, called beside. */
+    async disconnect(workspaceId) {
+        await this.deps.serviceCatalogConnectionRepository.softDelete(workspaceId, this.deps.clock.now());
+        this.log.info('serviceCatalog.disconnected', { workspaceId });
+    }
+    /**
+     * Probe with the SUBMITTED credentials rather than the stored ones.
+     *
+     * Which is the point of the endpoint: an operator testing a connection is testing what they just
+     * typed, and probing the stored row would answer about the credential they are replacing.
+     */
+    async probe(input) {
+        const baseUrl = this.assertBaseUrl(input.baseUrl);
+        return this.buildClient(baseUrl, input.auth).probe();
+    }
+    /**
+     * The client for a workspace's stored connection, or null when it has none.
+     *
+     * Wired as the `ResolveServiceCatalogClient` port the importer depends on. It REJECTS when a row
+     * exists whose bag will not open, because that is a deployment fault with its own remedy
+     * (re-enter the credential) and is not the same fact as a workspace that never connected a
+     * portal, which the importer treats as nothing to do.
+     */
+    resolveClient = async (workspaceId) => {
+        const record = await this.deps.serviceCatalogConnectionRepository.get(workspaceId);
+        if (!record || record.deletedAt !== null)
+            return null;
+        const auth = await this.openAuth(record);
+        return this.buildClient(record.baseUrl, auth);
+    };
+    buildClient(baseUrl, auth) {
+        return new BackstageCatalogClient({
+            baseUrl,
+            auth,
+            clock: this.deps.clock,
+            logger: this.log,
+            ...(this.deps.urlPolicy ? { urlPolicy: this.deps.urlPolicy } : {}),
+            ...(this.deps.fetchImpl ? { fetchImpl: this.deps.fetchImpl } : {}),
+        });
+    }
+    assertBaseUrl(baseUrl) {
+        const normalized = baseUrl.trim().replace(/\/+$/, '');
+        assertSafePublicUrl(normalized, {
+            subject: 'Service catalog',
+            label: 'base URL',
+            ...(this.deps.urlPolicy ? { policy: this.deps.urlPolicy } : {}),
+        });
+        return normalized;
+    }
+    /**
+     * Seal the credential half of the submitted auth.
+     *
+     * `none` seals NOTHING and stores the empty string, rather than an envelope around an empty
+     * object. An unauthenticated portal has no secret, so a deployment whose `ENCRYPTION_KEY`
+     * drifted must keep working against it: sealing a placeholder would make the one mode with no
+     * credential the one that fails on a key problem.
+     */
+    async sealAuth(workspaceId, auth) {
+        if (auth.mode === 'none')
+            return '';
+        return this.orgSecrets.encryptFor(orgSecretRef('service_catalog_connection', workspaceId), JSON.stringify(auth));
+    }
+    async openAuth(record) {
+        if (record.authMode === 'none')
+            return { mode: 'none' };
+        const plaintext = await this.orgSecrets.decryptFor(orgSecretRef('service_catalog_connection', record.workspaceId), record.credentialsCipher);
+        return parseServiceCatalogAuth(plaintext, record.authMode);
+    }
+}
+/** The stored row's non-secret half. */
+function toWire(record) {
+    return {
+        provider: record.provider,
+        baseUrl: record.baseUrl,
+        authMode: record.authMode,
+        entityFilter: record.entityFilter,
+        includeApis: record.includeApis,
+        maxServices: record.maxServices,
+        lastSyncedAt: record.lastSyncedAt,
+        lastSyncStatus: record.lastSyncStatus,
+        lastSyncMessage: record.lastSyncMessage,
+        connectedAt: record.createdAt,
+    };
+}
+/** An empty filter falls back to the default rather than importing the whole estate. */
+function normalizeFilter(entityFilter) {
+    const terms = (entityFilter ?? []).map((term) => term.trim()).filter(Boolean);
+    return terms.length > 0 ? terms : [...DEFAULT_SERVICE_CATALOG_FILTER];
+}
+//# sourceMappingURL=ServiceCatalogConnectionService.js.map

package/dist/modules/serviceCatalog/ServiceCatalogConnectionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceCatalogConnectionService.js","sourceRoot":"","sources":["../../../src/modules/serviceCatalog/ServiceCatalogConnectionService.ts"],"names":[],"mappings":"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"}

package/dist/modules/serviceCatalog/backstage-catalog.logic.d.ts

@@ -0,0 +1,173 @@
+import type { ApiContractFormat } from '@cat-factory/contracts';
+import type { ServiceCatalogApi, ServiceCatalogEntry } from '@cat-factory/kernel';
+/** How long a composed description may run: the catalog's own limit for the field. */
+export declare const MAX_DESCRIPTION_CHARS = 20000;
+/**
+ * How large one API definition may be and still be stored.
+ *
+ * The same ceiling a direct upload is held to, deliberately: a document past it is not served to
+ * an agent in any useful form (the contract render caps far lower and says what it dropped), and
+ * letting the import store what an upload would be refused would make the two supply routes
+ * disagree about what a contract is.
+ */
+export declare const MAX_DEFINITION_CHARS = 1000000;
+/** A Backstage entity, as much of it as this adapter reads. */
+export interface BackstageEntity {
+    kind?: string;
+    metadata?: {
+        name?: string;
+        namespace?: string;
+        title?: string;
+        description?: string;
+        tags?: string[];
+        etag?: string;
+        annotations?: Record<string, string>;
+        links?: {
+            url?: string;
+            title?: string;
+        }[];
+    };
+    spec?: {
+        type?: string;
+        lifecycle?: string;
+        owner?: string;
+        system?: string;
+        domain?: string;
+        definition?: string;
+        providesApis?: string[];
+    };
+}
+/** A parsed entity reference (`component:default/orders`). */
+export interface BackstageEntityRef {
+    kind: string;
+    namespace: string;
+    name: string;
+}
+/**
+ * Parse one of the several shapes Backstage accepts for a reference, with `defaultKind` filling
+ * the one a compact reference omits.
+ *
+ * Compact references are the norm rather than an edge case: `spec.owner: payments` and
+ * `providesApis: [orders-api]` are what a hand-written `catalog-info.yaml` contains, and the
+ * kind is implied by the FIELD they appear in. Returns null when there is no name at all, so a
+ * malformed reference is reported rather than resolved to something plausible.
+ */
+export declare function parseEntityRef(raw: string, defaultKind: string): BackstageEntityRef | null;
+/** Render a reference in the canonical `kind:namespace/name` form the API addresses entities by. */
+export declare function formatEntityRef(ref: BackstageEntityRef): string;
+/**
+ * The canonical reference for an entity as it came back, or null when it carries no name.
+ *
+ * Kind AND namespace are lower-cased, exactly as {@link parseEntityRef} does to the references it
+ * reads out of `providesApis` and `spec.owner`. Both halves matter: an entity declaring
+ * `namespace: Payments` would otherwise be recorded as `component:Payments/orders` while every
+ * reference the platform builds for the same entity resolves to `payments/...`, so the stored
+ * provenance would address nothing and the sync's `sourcePath` comparison would be against a value
+ * the canonical form can never produce.
+ */
+export declare function entityRef(entity: BackstageEntity): string | null;
+/**
+ * The foundational-service id an entity is imported under: its name as a lower-kebab slug,
+ * prefixed with its namespace when that is not the default one.
+ *
+ * The namespace prefix is what keeps the id unique. Backstage namespaces exist precisely so two
+ * teams can both own an `api` component, and slugging on the name alone would collapse them onto
+ * one catalog entry, silently, and in favour of whichever the portal paged first. The `default`
+ * namespace is left off because it is the one every hand-written entity lands in, and prefixing
+ * it would put `default-` in front of an organisation's entire estate.
+ *
+ * Null when nothing slug-shaped survives (a name of only punctuation), which the caller reports
+ * as a skipped entity rather than importing under a generated id nobody can look up.
+ */
+export declare function serviceIdForEntity(entity: BackstageEntity): string | null;
+/**
+ * A lower-kebab slug, or the empty string when the input holds nothing slug-shaped.
+ *
+ * Capped at the 64 characters the catalog's own id rule allows, and the cap is a plain prefix by
+ * design: a truncated slug still has to be STABLE across imports, and any cleverer strategy (a
+ * hash suffix, dropping interior words) would produce a different id the day a name grows.
+ */
+export declare function slugify(value: string): string;
+/**
+ * The format an API entity's declared `spec.type` maps to, or null when the platform serves none
+ * for it.
+ *
+ * Null rather than a fallback, and that is the whole point of the function. Backstage's API type
+ * is an open vocabulary (`trpc`, `sql`, `soap` and anything an organisation invents all appear),
+ * and storing one of those AS OpenAPI would produce a contract that fails the OpenAPI parse and
+ * lists zero operations, which reads to an Architect as a fully-specified service that offers no
+ * endpoints. The importer reports a null as a skipped interface instead, which says the opposite
+ * and is true.
+ */
+export declare function apiContractFormatForType(type: string | undefined): ApiContractFormat | null;
+/**
+ * Map one catalog entity onto the platform's neutral entry, with `apis` supplied separately
+ * (they are separate entities, fetched in one batch rather than one request per service).
+ *
+ * Returns null when the entity yields no usable identity, which the caller counts as skipped.
+ */
+export declare function toServiceCatalogEntry(entity: BackstageEntity, apis: ServiceCatalogApi[]): ServiceCatalogEntry | null;
+/**
+ * The one-line relevance signal.
+ *
+ * Falls back to the facts the entity DOES carry rather than to a placeholder, because a catalog
+ * whose every summary reads "no description" is a catalog a reader stops reading. A component's
+ * type and owner are the two things a portal always has, and together they are a real answer to
+ * "is this the service I am looking for".
+ */
+export declare function entitySummary(entity: BackstageEntity): string;
+/**
+ * The composed description: the portal's structured facts as labelled lines, then the entity's
+ * own prose.
+ *
+ * The ORDER is the load-bearing part. Ownership is what a triage reader needs first and it is
+ * also what a cap must never drop, so the labelled facts come before the free text and the
+ * truncation falls on the prose. A description that lost its owner line to a long README excerpt
+ * would be the one field this composition exists to guarantee.
+ */
+export declare function composeDescription(entity: BackstageEntity): string;
+/**
+ * A readable owner: the reference's NAME, with the full reference beside it.
+ *
+ * Both halves, because they answer different questions. `payments` is what a human recognises
+ * and what an agent can put in a report; `group:default/payments` is what someone can look up in
+ * the portal. Rendering only the reference makes the estate read like machine output, and
+ * rendering only the name loses which namespace (and which kind of owner) it belongs to.
+ */
+export declare function ownerLabel(owner: string | undefined): string | null;
+/**
+ * The capability tags an imported service carries: the entity's own tags plus its declared type.
+ *
+ * A RESERVED platform tag is dropped rather than imported, and that is a rule rather than a cap.
+ * `asset-storage` and `generation-context` are spellings the platform assigns meaning to (the
+ * first makes a service selectable as a binary-output step's storage target), so accepting one
+ * from an external portal would let whoever edits a `catalog-info.yaml` enrol a component into a
+ * platform capability that nobody at this deployment chose. A NEAR-MISS of a reserved tag goes
+ * the same way, since importing it would put a tag in the catalog that reads as the reserved one
+ * and behaves as nothing.
+ */
+export declare function entityCapabilities(entity: BackstageEntity): string[];
+/** The API entity references one component declares, canonicalised and de-duplicated. */
+export declare function providedApiRefs(entity: BackstageEntity): string[];
+/**
+ * Map one API entity onto a neutral interface, or null when it carries nothing storable.
+ *
+ * The three null cases are deliberately not distinguished HERE (an unusable type, an empty
+ * definition and an oversized one all become one skipped interface), because the caller reports
+ * a count and every one of them has the same remedy at the portal: give the API entity a
+ * definition this platform can serve. What must not happen is any of them being stored anyway.
+ */
+export declare function toServiceCatalogApi(entity: BackstageEntity): ServiceCatalogApi | null;
+/**
+ * The `fields` projection the LIST request asks for.
+ *
+ * Naming the fields is what keeps a large estate's listing cheap: without it Backstage returns
+ * every entity in full, relations included, and an API entity's `spec.definition` can be
+ * hundreds of kilobytes. `spec.definition` is deliberately absent here: the definitions are
+ * read in the second, batched request, for only the APIs the imported components actually
+ * declare.
+ */
+export declare const CATALOG_LIST_FIELDS: readonly string[];
+/** The `fields` projection the batched API-entity request asks for: the list plus definitions. */
+export declare const API_FETCH_FIELDS: readonly string[];
+//# sourceMappingURL=backstage-catalog.logic.d.ts.map

package/dist/modules/serviceCatalog/backstage-catalog.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backstage-catalog.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/serviceCatalog/backstage-catalog.logic.ts"],"names":[],"mappings":"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"}