@cat-factory/integrations 0.166.21 → 0.167.0

package/dist/modules/serviceCatalog/backstage-catalog.logic.js

@@ -0,0 +1,362 @@
+import { RESERVED_CAPABILITY_TAGS, reservedCapabilityNearMiss } from '@cat-factory/contracts';
+// ---------------------------------------------------------------------------
+// Backstage-specific PURE logic: turning a Software Catalog entity into the platform's neutral
+// `ServiceCatalogEntry`, and back the other way for the query it takes to fetch one.
+//
+// Everything that knows what Backstage calls a service, an owner or an API definition lives in
+// this file and its client sibling. The importer that consumes the result
+// (`ServiceCatalogSyncService` in `@cat-factory/agents`) sees only the neutral vocabulary, which
+// is what makes a second portal product a second adapter rather than a branch inside the import.
+//
+// No I/O, so every mapping rule below is unit-testable without a live instance.
+// ---------------------------------------------------------------------------
+/** The namespace Backstage uses when an entity declares none. */
+const DEFAULT_NAMESPACE = 'default';
+/** How long a composed description may run: the catalog's own limit for the field. */
+export const MAX_DESCRIPTION_CHARS = 20_000;
+/** How long a summary line may run: the catalog's own limit for the field. */
+const MAX_SUMMARY_CHARS = 400;
+/** How many capability tags one imported service may carry. */
+const MAX_CAPABILITIES = 20;
+/**
+ * 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 const MAX_DEFINITION_CHARS = 1_000_000;
+/**
+ * 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 function parseEntityRef(raw, defaultKind) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const colon = trimmed.indexOf(':');
+    const kind = colon === -1 ? defaultKind : trimmed.slice(0, colon);
+    const rest = colon === -1 ? trimmed : trimmed.slice(colon + 1);
+    const slash = rest.indexOf('/');
+    const namespace = slash === -1 ? DEFAULT_NAMESPACE : rest.slice(0, slash);
+    const name = slash === -1 ? rest : rest.slice(slash + 1);
+    if (!kind.trim() || !name.trim())
+        return null;
+    return {
+        kind: kind.trim().toLowerCase(),
+        namespace: (namespace.trim() || DEFAULT_NAMESPACE).toLowerCase(),
+        name: name.trim(),
+    };
+}
+/** Render a reference in the canonical `kind:namespace/name` form the API addresses entities by. */
+export function formatEntityRef(ref) {
+    return `${ref.kind}:${ref.namespace}/${ref.name}`;
+}
+/**
+ * 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 function entityRef(entity) {
+    const name = entity.metadata?.name?.trim();
+    if (!name)
+        return null;
+    return formatEntityRef({
+        kind: (entity.kind ?? 'component').toLowerCase(),
+        namespace: entity.metadata?.namespace?.trim().toLowerCase() || DEFAULT_NAMESPACE,
+        name,
+    });
+}
+/**
+ * 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 function serviceIdForEntity(entity) {
+    return namespacedSlug(entity);
+}
+/**
+ * The slug an entity is stored under: its name, prefixed with its namespace when that is not the
+ * default one. Shared by {@link serviceIdForEntity} and {@link toServiceCatalogApi}.
+ *
+ * ONE rule for both, because the two ids collide for the same reason and the fix is the same:
+ * `payments/orders` and `billing/orders` are two different API entities whose names are equal, and
+ * deriving a contract id from the name alone silently keeps whichever the portal answered first.
+ * Component ids were prefixed from the start; interfaces were not, and there is no reading of the
+ * catalog under which one of these needs the namespace and the other does not.
+ */
+function namespacedSlug(entity) {
+    const name = slugify(entity.metadata?.name ?? '');
+    if (!name)
+        return null;
+    const namespace = entity.metadata?.namespace?.trim().toLowerCase();
+    const prefix = namespace && namespace !== DEFAULT_NAMESPACE ? `${slugify(namespace)}-` : '';
+    return slugify(`${prefix}${name}`) || 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 function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/g, '');
+}
+/**
+ * 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 function apiContractFormatForType(type) {
+    switch (type?.trim().toLowerCase()) {
+        case 'openapi':
+            return 'openapi';
+        case 'asyncapi':
+            return 'asyncapi';
+        case 'graphql':
+            return 'graphql';
+        case 'grpc':
+            return 'grpc';
+        default:
+            return null;
+    }
+}
+/** The annotation carrying a component's TechDocs location, when it publishes docs. */
+const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref';
+/** The annotation carrying a component's source location (its repository). */
+const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';
+/**
+ * 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 function toServiceCatalogEntry(entity, apis) {
+    const id = serviceIdForEntity(entity);
+    const ref = entityRef(entity);
+    if (!id || !ref)
+        return null;
+    const metadata = entity.metadata ?? {};
+    return {
+        id,
+        name: (metadata.title?.trim() || metadata.name?.trim() || id).slice(0, 200),
+        summary: entitySummary(entity),
+        description: composeDescription(entity),
+        capabilities: entityCapabilities(entity),
+        ref,
+        apis,
+    };
+}
+/**
+ * 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 function entitySummary(entity) {
+    const described = firstLine(entity.metadata?.description ?? '');
+    if (described)
+        return described.slice(0, MAX_SUMMARY_CHARS);
+    const type = entity.spec?.type?.trim() || (entity.kind ?? 'component').toLowerCase();
+    const owner = ownerLabel(entity.spec?.owner);
+    const summary = owner ? `${type} owned by ${owner}` : `${type} with no recorded owner`;
+    return summary.slice(0, MAX_SUMMARY_CHARS);
+}
+/**
+ * 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 function composeDescription(entity) {
+    const spec = entity.spec ?? {};
+    const metadata = entity.metadata ?? {};
+    const facts = [];
+    const owner = ownerLabel(spec.owner);
+    facts.push(owner ? `Owner: ${owner}` : 'Owner: not recorded in the catalog');
+    if (spec.system?.trim())
+        facts.push(`System: ${spec.system.trim()}`);
+    if (spec.domain?.trim())
+        facts.push(`Domain: ${spec.domain.trim()}`);
+    if (spec.lifecycle?.trim())
+        facts.push(`Lifecycle: ${spec.lifecycle.trim()}`);
+    if (spec.type?.trim())
+        facts.push(`Type: ${spec.type.trim()}`);
+    const source = metadata.annotations?.[SOURCE_LOCATION_ANNOTATION]?.trim();
+    if (source)
+        facts.push(`Source: ${source}`);
+    const docs = metadata.annotations?.[TECHDOCS_ANNOTATION]?.trim();
+    if (docs)
+        facts.push(`Docs: ${docs}`);
+    const links = (metadata.links ?? [])
+        .map((link) => describeLink(link))
+        .filter((line) => line !== null);
+    if (links.length > 0)
+        facts.push(`Links: ${links.join(', ')}`);
+    const prose = (metadata.description ?? '').trim();
+    const composed = prose ? `${facts.join('\n')}\n\n${prose}` : facts.join('\n');
+    return composed.slice(0, MAX_DESCRIPTION_CHARS);
+}
+function describeLink(link) {
+    const url = link.url?.trim();
+    if (!url)
+        return null;
+    const title = link.title?.trim();
+    return title ? `${title} (${url})` : url;
+}
+/**
+ * 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 function ownerLabel(owner) {
+    if (!owner?.trim())
+        return null;
+    const ref = parseEntityRef(owner, 'group');
+    if (!ref)
+        return null;
+    return `${ref.name} (${formatEntityRef(ref)})`;
+}
+/**
+ * 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 function entityCapabilities(entity) {
+    const raw = [...(entity.metadata?.tags ?? []), entity.spec?.type ?? ''];
+    const out = [];
+    for (const value of raw) {
+        const tag = slugify(value);
+        if (!tag)
+            continue;
+        if (RESERVED_CAPABILITY_TAGS.includes(tag) || reservedCapabilityNearMiss(tag))
+            continue;
+        if (out.includes(tag))
+            continue;
+        out.push(tag);
+        if (out.length >= MAX_CAPABILITIES)
+            break;
+    }
+    return out;
+}
+/** The API entity references one component declares, canonicalised and de-duplicated. */
+export function providedApiRefs(entity) {
+    const out = [];
+    for (const raw of entity.spec?.providesApis ?? []) {
+        const ref = parseEntityRef(raw, 'api');
+        if (!ref)
+            continue;
+        const formatted = formatEntityRef(ref);
+        if (!out.includes(formatted))
+            out.push(formatted);
+    }
+    return out;
+}
+/**
+ * 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 function toServiceCatalogApi(entity) {
+    const ref = entityRef(entity);
+    const id = namespacedSlug(entity);
+    if (!ref || !id)
+        return null;
+    const definition = entity.spec?.definition;
+    if (typeof definition !== 'string')
+        return null;
+    const trimmed = definition.trim();
+    if (!trimmed || trimmed.length > MAX_DEFINITION_CHARS)
+        return null;
+    const format = apiContractFormatForType(entity.spec?.type);
+    if (!format)
+        return null;
+    return {
+        id,
+        title: (entity.metadata?.title?.trim() || entity.metadata?.name?.trim() || id).slice(0, 200),
+        format,
+        definition,
+        ref,
+        revision: entity.metadata?.etag?.trim() || null,
+    };
+}
+function firstLine(value) {
+    return value.trim().split(/\r?\n/)[0]?.trim() ?? '';
+}
+/**
+ * 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 const CATALOG_LIST_FIELDS = [
+    'kind',
+    'metadata.name',
+    'metadata.namespace',
+    'metadata.title',
+    'metadata.description',
+    'metadata.tags',
+    'metadata.annotations',
+    'metadata.links',
+    'metadata.etag',
+    'spec.type',
+    'spec.lifecycle',
+    'spec.owner',
+    'spec.system',
+    'spec.domain',
+    'spec.providesApis',
+];
+/** The `fields` projection the batched API-entity request asks for: the list plus definitions. */
+export const API_FETCH_FIELDS = [...CATALOG_LIST_FIELDS, 'spec.definition'];
+//# sourceMappingURL=backstage-catalog.logic.js.map

package/dist/modules/serviceCatalog/backstage-catalog.logic.js.map

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

package/dist/modules/serviceCatalog/serviceCatalogAuth.d.ts

@@ -0,0 +1,42 @@
+import type { ServiceCatalogAuth, ServiceCatalogAuthMode } from '@cat-factory/contracts';
+/** Read a sealed credential bag back into the discriminated auth it was written from. */
+export declare function parseServiceCatalogAuth(plaintext: string, expected: ServiceCatalogAuthMode): ServiceCatalogAuth;
+/**
+ * The headers one catalog request carries.
+ *
+ * `bearer` is the token an OAuth2 exchange produced, resolved once by the caller. It is a
+ * parameter rather than something fetched here so this stays pure and so one import pass cannot
+ * fan out into one token request per page.
+ */
+export declare function serviceCatalogAuthHeaders(auth: ServiceCatalogAuth, bearer: string | null): Record<string, string>;
+/** Whether this mode's bearer value has to be resolved before any request is built. */
+export declare function requiresResolvedBearer(mode: ServiceCatalogAuthMode): boolean;
+/**
+ * Mint the short-lived HS256 token Backstage's LEGACY external-access mode accepts: a JWT whose
+ * subject is the vendor's fixed `backstage-server`, signed with the HMAC key the configured
+ * shared secret decodes to.
+ *
+ * The secret is base64-DECODED into key bytes rather than used as UTF-8, because that is how the
+ * vendor derives its own key and how its documentation has operators generate the value
+ * (`openssl rand -base64 32`). Signing with the raw characters of a base64 secret produces a
+ * different key, so the choice is not a preference: it decides whether the token verifies at all.
+ * A secret that is not base64 is REFUSED here rather than falling back to its raw bytes: the two
+ * readings of one string are indistinguishable, so a fallback would sign half the deployments in
+ * the world with the wrong key and surface as a 401 blaming the credential.
+ */
+export declare function mintLegacyBackstageToken(sharedSecret: string, nowSeconds: number): Promise<string>;
+/** The form body an OAuth2 client-credentials exchange posts. */
+export declare function clientCredentialsBody(auth: {
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+    audience?: string;
+}): string;
+/**
+ * The access token an OAuth2 token response carries, or null when the body is not one.
+ *
+ * Null rather than a throw so the caller can attach WHICH connection failed and what the provider
+ * answered; a bare parse error here would name neither.
+ */
+export declare function readAccessToken(body: unknown): string | null;
+//# sourceMappingURL=serviceCatalogAuth.d.ts.map

package/dist/modules/serviceCatalog/serviceCatalogAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceCatalogAuth.d.ts","sourceRoot":"","sources":["../../../src/modules/serviceCatalog/serviceCatalogAuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AA0BxF,yFAAyF;AACzF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,sBAAsB,GAC/B,kBAAkB,CA0BpB;AAgED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBxB;AAYD,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,CAST;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI5D"}

package/dist/modules/serviceCatalog/serviceCatalogAuth.js

@@ -0,0 +1,201 @@
+import { UnavailableError, ValidationError } from '@cat-factory/kernel';
+import { base64ToBytes, bytesToBase64Url, toBase64, toBase64Url } from '../shared/base64.js';
+// ---------------------------------------------------------------------------
+// Turning a stored service-catalog credential into the headers one request carries.
+//
+// Five of the six modes are a pure function of the bag and are computed per request. The sixth
+// (`oauth2-client-credentials`) needs a round trip to an identity provider, so the caller
+// resolves it ONCE per import pass and passes the resulting bearer value down; there is
+// deliberately no cache here, because the only two places a token could be held are a module
+// global (banned) and a per-isolate map that workerd may discard between invocations, and an
+// import pass is exactly the scope over which one token is both sufficient and safe.
+// ---------------------------------------------------------------------------
+/** How long a minted legacy service token is valid for. Short: it is minted per pass. */
+const LEGACY_TOKEN_TTL_SECONDS = 600;
+/**
+ * The `sub` Backstage's legacy service-to-service tokens carry.
+ *
+ * Fixed by the vendor rather than chosen here: its backend admits a legacy token only when the
+ * subject is this exact string, so it is a wire constant and not a configurable identity.
+ */
+const LEGACY_TOKEN_SUBJECT = 'backstage-server';
+/** Read a sealed credential bag back into the discriminated auth it was written from. */
+export function parseServiceCatalogAuth(plaintext, expected) {
+    if (expected === 'none')
+        return { mode: 'none' };
+    let parsed;
+    try {
+        parsed = JSON.parse(plaintext);
+    }
+    catch {
+        // silent-catch-ok: the parse error names only JSON syntax, and what the caller has to be
+        // told is which connection's bag will not open. The throw below says that.
+        parsed = null;
+    }
+    const bag = parsed && typeof parsed === 'object' ? parsed : null;
+    const auth = bag ? readAuth(bag, expected) : null;
+    if (!auth) {
+        // A row whose stored mode and stored bag disagree is corrupt, not a misconfiguration, so the
+        // remedy is re-entering the credential rather than anything the operator can adjust. Named
+        // as `unavailable` for that reason: a `ValidationError` here would blame the request.
+        // The SHARED reason, not one of this integration's own: an unopenable credential bag is the
+        // same fact here as for a document source or a tracker, with the same two remedies, and the
+        // SPA already carries copy naming both. `details.source` is what tells them apart.
+        throw new UnavailableError(`The stored service-catalog credential does not hold a '${expected}' credential. Re-enter the connection.`, 'connection_credentials_unreadable', { source: 'service_catalog' });
+    }
+    return auth;
+}
+/**
+ * Narrow a parsed bag against ONE declared mode.
+ *
+ * Keyed off the column's mode rather than the bag's own, so a bag that claims a different mode
+ * than the row does is refused instead of quietly switching schemes: the column is what every
+ * management read and the request builder branch on, and a disagreement between the two is the
+ * one state where trusting the ciphertext over the plaintext is wrong.
+ */
+function readAuth(bag, mode) {
+    switch (mode) {
+        case 'none':
+            return { mode: 'none' };
+        case 'static-token': {
+            const token = text(bag.token);
+            return token ? { mode, token } : null;
+        }
+        case 'legacy-shared-secret': {
+            const sharedSecret = text(bag.sharedSecret);
+            return sharedSecret ? { mode, sharedSecret } : null;
+        }
+        case 'oauth2-client-credentials': {
+            const tokenUrl = text(bag.tokenUrl);
+            const clientId = text(bag.clientId);
+            const clientSecret = text(bag.clientSecret);
+            if (!tokenUrl || !clientId || !clientSecret)
+                return null;
+            const scope = text(bag.scope);
+            const audience = text(bag.audience);
+            return {
+                mode,
+                tokenUrl,
+                clientId,
+                clientSecret,
+                ...(scope ? { scope } : {}),
+                ...(audience ? { audience } : {}),
+            };
+        }
+        case 'basic': {
+            const username = text(bag.username);
+            const password = text(bag.password);
+            return username && password ? { mode, username, password } : null;
+        }
+        case 'headers': {
+            const raw = Array.isArray(bag.headers) ? bag.headers : [];
+            const headers = [];
+            for (const entry of raw) {
+                if (!entry || typeof entry !== 'object')
+                    continue;
+                const name = text(entry.name);
+                const value = text(entry.value);
+                if (name && value)
+                    headers.push({ name, value });
+            }
+            return headers.length > 0 ? { mode, headers } : null;
+        }
+    }
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+/**
+ * The headers one catalog request carries.
+ *
+ * `bearer` is the token an OAuth2 exchange produced, resolved once by the caller. It is a
+ * parameter rather than something fetched here so this stays pure and so one import pass cannot
+ * fan out into one token request per page.
+ */
+export function serviceCatalogAuthHeaders(auth, bearer) {
+    switch (auth.mode) {
+        case 'none':
+            return {};
+        case 'static-token':
+            return { authorization: `Bearer ${auth.token}` };
+        case 'legacy-shared-secret':
+            // Minted asynchronously, so the caller supplies it through the same channel the OAuth2
+            // token uses. Reaching this with no bearer means the mint was skipped, which would send an
+            // UNAUTHENTICATED request and read back as a rejected credential.
+            return bearerHeaders(bearer, 'legacy service token');
+        case 'oauth2-client-credentials':
+            return bearerHeaders(bearer, 'OAuth2 access token');
+        case 'basic':
+            return { authorization: `Basic ${toBase64(`${auth.username}:${auth.password}`)}` };
+        case 'headers':
+            return Object.fromEntries(auth.headers.map((header) => [header.name, header.value]));
+    }
+}
+function bearerHeaders(bearer, what) {
+    if (!bearer) {
+        throw new UnavailableError(`The service-catalog ${what} was not resolved before the request was built.`, 'service_catalog_token_unresolved');
+    }
+    return { authorization: `Bearer ${bearer}` };
+}
+/** Whether this mode's bearer value has to be resolved before any request is built. */
+export function requiresResolvedBearer(mode) {
+    return mode === 'legacy-shared-secret' || mode === 'oauth2-client-credentials';
+}
+/**
+ * Mint the short-lived HS256 token Backstage's LEGACY external-access mode accepts: a JWT whose
+ * subject is the vendor's fixed `backstage-server`, signed with the HMAC key the configured
+ * shared secret decodes to.
+ *
+ * The secret is base64-DECODED into key bytes rather than used as UTF-8, because that is how the
+ * vendor derives its own key and how its documentation has operators generate the value
+ * (`openssl rand -base64 32`). Signing with the raw characters of a base64 secret produces a
+ * different key, so the choice is not a preference: it decides whether the token verifies at all.
+ * A secret that is not base64 is REFUSED here rather than falling back to its raw bytes: the two
+ * readings of one string are indistinguishable, so a fallback would sign half the deployments in
+ * the world with the wrong key and surface as a 401 blaming the credential.
+ */
+export async function mintLegacyBackstageToken(sharedSecret, nowSeconds) {
+    const keyBytes = base64ToBytes(sharedSecret);
+    if (!keyBytes || keyBytes.length === 0) {
+        throw new ValidationError('The Backstage shared secret must be base64 (the value `backend.auth.keys[].secret` holds). ' +
+            'If your instance authenticates some other way, use a static token or explicit headers instead.', { reason: 'service_catalog_shared_secret_not_base64' });
+    }
+    const header = toBase64Url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+    const payload = toBase64Url(JSON.stringify({
+        sub: LEGACY_TOKEN_SUBJECT,
+        iat: nowSeconds,
+        exp: nowSeconds + LEGACY_TOKEN_TTL_SECONDS,
+    }));
+    const signingInput = `${header}.${payload}`;
+    // `slice()` rather than the view: `base64ToBytes` returns a `subarray`, whose backing buffer
+    // WebCrypto's `BufferSource` overloads will not accept without a copy of its own bytes.
+    const key = await crypto.subtle.importKey('raw', keyBytes.slice().buffer, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(signingInput));
+    return `${signingInput}.${bytesToBase64Url(new Uint8Array(signature))}`;
+}
+/** The form body an OAuth2 client-credentials exchange posts. */
+export function clientCredentialsBody(auth) {
+    const form = new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: auth.clientId,
+        client_secret: auth.clientSecret,
+    });
+    if (auth.scope)
+        form.set('scope', auth.scope);
+    if (auth.audience)
+        form.set('audience', auth.audience);
+    return form.toString();
+}
+/**
+ * The access token an OAuth2 token response carries, or null when the body is not one.
+ *
+ * Null rather than a throw so the caller can attach WHICH connection failed and what the provider
+ * answered; a bare parse error here would name neither.
+ */
+export function readAccessToken(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const token = body.access_token;
+    return typeof token === 'string' && token.trim() ? token : null;
+}
+//# sourceMappingURL=serviceCatalogAuth.js.map

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

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

package/dist/modules/shared/base64.d.ts

@@ -0,0 +1,19 @@
+/** Base64 of `bytes`, padded. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Base64URL of `bytes`, unpadded, as every JWT segment is encoded. */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+/** Base64 of `input`'s UTF-8 bytes. */
+export declare function toBase64(input: string): string;
+/** Base64URL of `input`'s UTF-8 bytes. */
+export declare function toBase64Url(input: string): string;
+/**
+ * The bytes `value` encodes, or null when it is not base64 at all.
+ *
+ * Accepts base64URL (`-`/`_`) and a missing tail of `=` padding, because both forms turn up in
+ * secrets an operator pasted from somewhere else. Returns NULL rather than a best-effort decode
+ * of the prefix: the one caller is deriving an HMAC key, and a key silently decoded from the
+ * leading valid characters of a malformed secret would sign every request with the wrong key and
+ * fail as an authorization error that names the credential rather than its encoding.
+ */
+export declare function base64ToBytes(value: string): Uint8Array | null;
+//# sourceMappingURL=base64.d.ts.map