@cat-factory/contracts 0.334.0 → 0.335.0

package/dist/service-catalog.d.ts

@@ -0,0 +1,223 @@
+import * as v from 'valibot';
+/**
+ * Which developer-portal product a connection talks to.
+ *
+ * A picklist with one member rather than a bare literal, because the read surface, the SPA and
+ * the stored row all name it: adding Port / Cortex / OpsLevel later is a member plus an adapter,
+ * and every `Record<ServiceCatalogProvider, …>` fails to compile until it is mapped. The
+ * platform-neutral vocabulary below (`ServiceCatalogEntry` in the kernel) is what the importer
+ * consumes, so nothing downstream of the adapter knows the word "Backstage".
+ */
+export declare const serviceCatalogProviderSchema: v.PicklistSchema<["backstage"], undefined>;
+export type ServiceCatalogProvider = v.InferOutput<typeof serviceCatalogProviderSchema>;
+/**
+ * How the platform authenticates to a SELF-HOSTED portal.
+ *
+ * These are the shapes organisations actually run Backstage behind, and each needs a different
+ * request built, which is why this is a closed vocabulary rather than a free-form header bag:
+ *
+ * - `none`: no auth on the catalog API. Real, and common on an instance reachable only inside a
+ *   VPN. It is admissible ONLY because the base URL is held to the deployment's
+ *   `UrlSafetyPolicy`, so reaching a private host is an operator decision already made.
+ * - `static-token`: a service-to-service token from Backstage's `backend.auth.externalAccess`
+ *   (`type: static`), sent as `Authorization: Bearer <token>`. The vendor's own recommended
+ *   way for an external system to read the catalog.
+ * - `legacy-shared-secret`: the older external-access route, still what a great many
+ *   self-hosted instances are configured for: a short-lived HS256 JWT signed with a secret
+ *   from `backend.auth.keys[]`. The platform MINTS the token per request rather than storing
+ *   one, which is why the stored credential is the secret and not a bearer value.
+ * - `oauth2-client-credentials`: the portal sits behind an IdP or an identity-aware proxy
+ *   (Keycloak, Okta, Entra, Google IAP). The platform exchanges a client id/secret at the
+ *   token endpoint and sends the result as a bearer token.
+ * - `basic`: HTTP Basic, i.e. a reverse proxy in front of the portal.
+ * - `headers`: an explicit header list, for a gateway that authenticates on its own header
+ *   names. A LIST rather than one pair because the common case needs two (a Cloudflare Access
+ *   service token is `CF-Access-Client-Id` plus `CF-Access-Client-Secret`), and a single-pair
+ *   shape would have sent half a credential.
+ */
+export declare const serviceCatalogAuthModeSchema: v.PicklistSchema<["none", "static-token", "legacy-shared-secret", "oauth2-client-credentials", "basic", "headers"], undefined>;
+export type ServiceCatalogAuthMode = v.InferOutput<typeof serviceCatalogAuthModeSchema>;
+/** The credential half of a connection, discriminated by the auth mode it belongs to. */
+export declare const serviceCatalogAuthSchema: v.VariantSchema<"mode", [v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"none", undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"static-token", undefined>;
+    readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"legacy-shared-secret", undefined>;
+    readonly sharedSecret: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"oauth2-client-credentials", undefined>;
+    /** The IdP's token endpoint. Held to the same URL policy as the portal's own base URL. */
+    readonly tokenUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    readonly clientId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    readonly clientSecret: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+    /** Optional `scope` / `audience` request parameters some IdPs require. */
+    readonly scope: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    readonly audience: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"basic", undefined>;
+    readonly username: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+    readonly password: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+    readonly mode: v.LiteralSchema<"headers", undefined>;
+    readonly headers: v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 100, undefined>, v.RegexAction<string, "must be a valid HTTP header name">]>;
+        readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>, v.RegexAction<string, "must not contain a line break">]>;
+    }, undefined>, undefined>, v.MinLengthAction<{
+        name: string;
+        value: string;
+    }[], 1, undefined>, v.MaxLengthAction<{
+        name: string;
+        value: string;
+    }[], 5, undefined>]>;
+}, undefined>], undefined>;
+export type ServiceCatalogAuth = v.InferOutput<typeof serviceCatalogAuthSchema>;
+/**
+ * The default filter, applied when a connection names none: the portal's SERVICE-like
+ * components.
+ *
+ * A default rather than a required field, because the honest alternative is worse in both
+ * directions. Importing the WHOLE catalog would fold a thousand-entity estate into every
+ * design prompt (the exact cost ADR 0031 split the catalog and contract reads to avoid), while
+ * refusing to import without a filter makes the first connection fail on a vendor query language
+ * the operator has no reason to know yet. `kind=component` is the one term that is right for
+ * every Backstage instance, and a narrower estate (a tag, a system, an owner) is one term more.
+ */
+export declare const DEFAULT_SERVICE_CATALOG_FILTER: readonly string[];
+/** How many services ONE import may bring in, and the ceiling on that number. */
+export declare const DEFAULT_MAX_CATALOG_SERVICES = 200;
+export declare const MAX_CATALOG_SERVICES_CEILING = 1000;
+/** Connect (or re-connect) the workspace's service catalog. Replaces any prior connection. */
+export declare const connectServiceCatalogSchema: v.ObjectSchema<{
+    readonly provider: v.OptionalSchema<v.PicklistSchema<["backstage"], undefined>, undefined>;
+    /** The portal's base URL, e.g. `https://backstage.corp.internal`. */
+    readonly baseUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+    readonly auth: v.VariantSchema<"mode", [v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"none", undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"static-token", undefined>;
+        readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"legacy-shared-secret", undefined>;
+        readonly sharedSecret: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"oauth2-client-credentials", undefined>;
+        /** The IdP's token endpoint. Held to the same URL policy as the portal's own base URL. */
+        readonly tokenUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 500, undefined>]>;
+        readonly clientId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+        readonly clientSecret: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+        /** Optional `scope` / `audience` request parameters some IdPs require. */
+        readonly scope: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+        readonly audience: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"basic", undefined>;
+        readonly username: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+        readonly password: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly mode: v.LiteralSchema<"headers", undefined>;
+        readonly headers: v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 100, undefined>, v.RegexAction<string, "must be a valid HTTP header name">]>;
+            readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>, v.RegexAction<string, "must not contain a line break">]>;
+        }, undefined>, undefined>, v.MinLengthAction<{
+            name: string;
+            value: string;
+        }[], 1, undefined>, v.MaxLengthAction<{
+            name: string;
+            value: string;
+        }[], 5, undefined>]>;
+    }, undefined>], undefined>;
+    /**
+     * Portal-side filter terms, ANDed. Empty/absent ⇒ {@link DEFAULT_SERVICE_CATALOG_FILTER}.
+     * Filtering AT THE PORTAL rather than after the fetch is what keeps a large estate from being
+     * paged through in full on every refresh.
+     */
+    readonly entityFilter: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 3, undefined>, v.MaxLengthAction<string, 200, undefined>, v.RegexAction<string, "must be a single `key=value` term (letters, digits and `_.-:/@`)">]>, undefined>, v.MaxLengthAction<string[], 10, undefined>]>, undefined>;
+    /**
+     * Whether to import the API definitions each service publishes (`spec.providesApis`).
+     * Defaults to true, being the half of the ask that lets a consumer call a shared service
+     * rather than merely know it exists.
+     */
+    readonly includeApis: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    /** Cap on imported services. Defaults to {@link DEFAULT_MAX_CATALOG_SERVICES}. */
+    readonly maxServices: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 1000, undefined>]>, undefined>;
+}, undefined>;
+export type ConnectServiceCatalogInput = v.InferOutput<typeof connectServiceCatalogSchema>;
+/**
+ * How much of the portal's matching estate one import covered.
+ *
+ * Three states rather than a count, for the reason the repo-source `folderScan` coverage has
+ * three: each needs a different fix from the person who connected it, and `truncated` must never
+ * read as `complete`. An importer that reported only "42 services" would leave an operator with
+ * a 300-service estate believing the catalog is the estate.
+ */
+export declare const serviceCatalogCoverageSchema: v.PicklistSchema<["complete", "truncated", "empty"], undefined>;
+export type ServiceCatalogCoverage = v.InferOutput<typeof serviceCatalogCoverageSchema>;
+/** What the LAST import concluded, as the management surface reports it. */
+export declare const serviceCatalogSyncStatusSchema: v.PicklistSchema<["ok", "partial", "failed"], undefined>;
+export type ServiceCatalogSyncStatus = v.InferOutput<typeof serviceCatalogSyncStatusSchema>;
+/**
+ * The connection as the management surface sees it: never a credential, not even a masked one.
+ *
+ * `authMode` is here because it is the one part of the credential that is configuration rather
+ * than secret, because the operator has to see WHICH scheme a stored connection uses to know whether
+ * it still matches how the portal is deployed.
+ */
+export declare const serviceCatalogConnectionSchema: v.ObjectSchema<{
+    readonly provider: v.PicklistSchema<["backstage"], undefined>;
+    readonly baseUrl: v.StringSchema<undefined>;
+    readonly authMode: v.PicklistSchema<["none", "static-token", "legacy-shared-secret", "oauth2-client-credentials", "basic", "headers"], undefined>;
+    readonly entityFilter: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly includeApis: v.BooleanSchema<undefined>;
+    readonly maxServices: v.NumberSchema<undefined>;
+    readonly lastSyncedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly lastSyncStatus: v.NullableSchema<v.PicklistSchema<["ok", "partial", "failed"], undefined>, undefined>;
+    /**
+     * What the last import wants a human to know: the truncation, the unreadable definitions, or
+     * the transport failure. Null when the last pass had nothing to report, which is the only
+     * state that needs no sentence.
+     */
+    readonly lastSyncMessage: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly connectedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type ServiceCatalogConnection = v.InferOutput<typeof serviceCatalogConnectionSchema>;
+/** Outcome of one import: what changed in the catalog, and what the pass could not do. */
+export declare const serviceCatalogSyncResultSchema: v.ObjectSchema<{
+    readonly upserted: v.NumberSchema<undefined>;
+    /** Services this connection produced before and the portal no longer offers. */
+    readonly tombstoned: v.NumberSchema<undefined>;
+    readonly unchanged: v.NumberSchema<undefined>;
+    /** API definitions stored across every imported service. */
+    readonly contracts: v.NumberSchema<undefined>;
+    readonly coverage: v.PicklistSchema<["complete", "truncated", "empty"], undefined>;
+    /**
+     * Entities the filter matched that did NOT become a service: no usable identity, or a name
+     * that yields no slug. Zero and "nothing matched" are told apart by {@link coverage}, and a
+     * non-zero value here is the only thing that explains a catalog thinner than the portal's
+     * own entity count.
+     */
+    readonly skippedServices: v.NumberSchema<undefined>;
+    /**
+     * Portal services this pass REFUSED to write because the workspace already registers a service
+     * under that id by another route (an upload, a linked repo).
+     *
+     * Its own count rather than folded into {@link skippedServices}, because the two name opposite
+     * faults with opposite remedies: a skipped service is an entity the PORTAL describes in a way
+     * this platform cannot use, and this is a collision between two things the workspace itself
+     * did. Refusing is the only safe disposition, since overwriting would silently replace a
+     * hand-authored service (and its uploaded contracts, and any platform capability it was granted)
+     * with the portal's row, and disconnecting would then tombstone the original.
+     */
+    readonly skippedConflicts: v.NumberSchema<undefined>;
+    /**
+     * API definitions a service DECLARES that this pass could not store: a type the platform
+     * serves no format for, an entity the portal would not return, an empty or oversized
+     * definition, or an id that collides with another interface of the same service. Reported
+     * rather than dropped, because a service listed with no interface reads to an agent as a
+     * service that publishes none.
+     */
+    readonly skippedApis: v.NumberSchema<undefined>;
+    readonly status: v.PicklistSchema<["ok", "partial", "failed"], undefined>;
+}, undefined>;
+export type ServiceCatalogSyncResult = v.InferOutput<typeof serviceCatalogSyncResultSchema>;
+//# sourceMappingURL=service-catalog.d.ts.map

package/dist/service-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-catalog.d.ts","sourceRoot":"","sources":["../src/service-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAqB5B;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,4CAA4B,CAAA;AACrE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,4BAA4B,gIAOvC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AA0BvF,yFAAyF;AACzF,eAAO,MAAM,wBAAwB;;;;;;;;;;IAMjC,0FAA0F;;;;IAI1F,0EAA0E;;;;;;;;;;;;;;;;;;;0BAa5E,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAqB/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAAuB,CAAA;AAEnF,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAC/C,eAAO,MAAM,4BAA4B,OAAQ,CAAA;AAEjD,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B;;IAEtC,qEAAqE;;;;;;;;;;;;QA3DnE,0FAA0F;;;;QAI1F,0EAA0E;;;;;;;;;;;;;;;;;;;;IA0D5E;;;;OAIG;;IAEH;;;;OAIG;;IAEH,kFAAkF;;aAIlF,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAE1F;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,iEAWvC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,0DAWzC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;IASzC;;;;OAIG;;;aAGH,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA;AAE3F,0FAA0F;AAC1F,eAAO,MAAM,8BAA8B;;IAEzC,gFAAgF;;;IAGhF,4DAA4D;;;IAG5D;;;;;OAKG;;IAEH;;;;;;;;;;OAUG;;IAEH;;;;;;OAMG;;;aAGH,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA"}

package/dist/service-catalog.js

@@ -0,0 +1,234 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Wire contracts for the SERVICE CATALOG connection: a workspace points the platform at the
+// developer portal its organisation already runs (Backstage today) and the platform imports
+// that portal's services (identity, ownership, and the API definitions each one publishes)
+// into the FOUNDATIONAL SERVICES catalog agents already read
+// (backend/docs/adr/0031-foundational-services.md).
+//
+// It is a THIRD supply route beside direct upload and a linked git repo, deliberately not a
+// second agent-facing catalog: an agent that was told about a service twice, once per
+// mechanism, is the accretion this reuse avoids. What the import produces is ordinary
+// `workspace`-tier foundational services, so the tiered merge, the suppression sub-resource,
+// the lazily-read contract documents and the injected `.cat-context/` files all work unchanged.
+//
+// Scoped to a WORKSPACE, like every other sealed vendor connection (observability, tracker,
+// document sources). That is also what makes it work on a mothership-mode node: the credential
+// bag travels as ciphertext and is opened by naming the row over the secret delegation, which
+// is workspace-keyed by construction.
+// ---------------------------------------------------------------------------
+/**
+ * Which developer-portal product a connection talks to.
+ *
+ * A picklist with one member rather than a bare literal, because the read surface, the SPA and
+ * the stored row all name it: adding Port / Cortex / OpsLevel later is a member plus an adapter,
+ * and every `Record<ServiceCatalogProvider, …>` fails to compile until it is mapped. The
+ * platform-neutral vocabulary below (`ServiceCatalogEntry` in the kernel) is what the importer
+ * consumes, so nothing downstream of the adapter knows the word "Backstage".
+ */
+export const serviceCatalogProviderSchema = v.picklist(['backstage']);
+/**
+ * How the platform authenticates to a SELF-HOSTED portal.
+ *
+ * These are the shapes organisations actually run Backstage behind, and each needs a different
+ * request built, which is why this is a closed vocabulary rather than a free-form header bag:
+ *
+ * - `none`: no auth on the catalog API. Real, and common on an instance reachable only inside a
+ *   VPN. It is admissible ONLY because the base URL is held to the deployment's
+ *   `UrlSafetyPolicy`, so reaching a private host is an operator decision already made.
+ * - `static-token`: a service-to-service token from Backstage's `backend.auth.externalAccess`
+ *   (`type: static`), sent as `Authorization: Bearer <token>`. The vendor's own recommended
+ *   way for an external system to read the catalog.
+ * - `legacy-shared-secret`: the older external-access route, still what a great many
+ *   self-hosted instances are configured for: a short-lived HS256 JWT signed with a secret
+ *   from `backend.auth.keys[]`. The platform MINTS the token per request rather than storing
+ *   one, which is why the stored credential is the secret and not a bearer value.
+ * - `oauth2-client-credentials`: the portal sits behind an IdP or an identity-aware proxy
+ *   (Keycloak, Okta, Entra, Google IAP). The platform exchanges a client id/secret at the
+ *   token endpoint and sends the result as a bearer token.
+ * - `basic`: HTTP Basic, i.e. a reverse proxy in front of the portal.
+ * - `headers`: an explicit header list, for a gateway that authenticates on its own header
+ *   names. A LIST rather than one pair because the common case needs two (a Cloudflare Access
+ *   service token is `CF-Access-Client-Id` plus `CF-Access-Client-Secret`), and a single-pair
+ *   shape would have sent half a credential.
+ */
+export const serviceCatalogAuthModeSchema = v.picklist([
+    'none',
+    'static-token',
+    'legacy-shared-secret',
+    'oauth2-client-credentials',
+    'basic',
+    'headers',
+]);
+const secretValue = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(8_000));
+const shortText = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(200));
+const url = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(500));
+/**
+ * A header name a gateway may authenticate on. Restricted to the RFC 7230 token characters this
+ * platform will emit, so a stored credential can never inject a second header or a request line
+ * (the value is checked the same way below, because a `\r\n` in either half is the same split).
+ */
+const headerName = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(100), v.regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, 'must be a valid HTTP header name'));
+const headerValue = v.pipe(v.string(), v.minLength(1), v.maxLength(8_000), v.regex(/^[^\r\n]+$/, 'must not contain a line break'));
+/** The credential half of a connection, discriminated by the auth mode it belongs to. */
+export const serviceCatalogAuthSchema = v.variant('mode', [
+    v.object({ mode: v.literal('none') }),
+    v.object({ mode: v.literal('static-token'), token: secretValue }),
+    v.object({ mode: v.literal('legacy-shared-secret'), sharedSecret: secretValue }),
+    v.object({
+        mode: v.literal('oauth2-client-credentials'),
+        /** The IdP's token endpoint. Held to the same URL policy as the portal's own base URL. */
+        tokenUrl: url,
+        clientId: shortText,
+        clientSecret: secretValue,
+        /** Optional `scope` / `audience` request parameters some IdPs require. */
+        scope: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(500))),
+        audience: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(500))),
+    }),
+    v.object({ mode: v.literal('basic'), username: shortText, password: secretValue }),
+    v.object({
+        mode: v.literal('headers'),
+        headers: v.pipe(v.array(v.object({ name: headerName, value: headerValue })), v.minLength(1), v.maxLength(5)),
+    }),
+]);
+/**
+ * One term of the portal-side entity filter, `key=value`.
+ *
+ * The charset is deliberately tight: these terms are serialised into the vendor's query string,
+ * so admitting `&` or `=` beyond the first would let a stored filter add query parameters the
+ * platform never meant to send (a `limit`, a second `filter`, a `fields` projection that drops
+ * the fields the importer reads). One `=`, no separators, no whitespace.
+ */
+const entityFilterTerm = v.pipe(v.string(), v.trim(), v.minLength(3), v.maxLength(200), v.regex(/^[A-Za-z0-9_.-]+=[A-Za-z0-9_.:/@-]+$/, 'must be a single `key=value` term (letters, digits and `_.-:/@`)'));
+/**
+ * The default filter, applied when a connection names none: the portal's SERVICE-like
+ * components.
+ *
+ * A default rather than a required field, because the honest alternative is worse in both
+ * directions. Importing the WHOLE catalog would fold a thousand-entity estate into every
+ * design prompt (the exact cost ADR 0031 split the catalog and contract reads to avoid), while
+ * refusing to import without a filter makes the first connection fail on a vendor query language
+ * the operator has no reason to know yet. `kind=component` is the one term that is right for
+ * every Backstage instance, and a narrower estate (a tag, a system, an owner) is one term more.
+ */
+export const DEFAULT_SERVICE_CATALOG_FILTER = ['kind=component'];
+/** How many services ONE import may bring in, and the ceiling on that number. */
+export const DEFAULT_MAX_CATALOG_SERVICES = 200;
+export const MAX_CATALOG_SERVICES_CEILING = 1_000;
+/** Connect (or re-connect) the workspace's service catalog. Replaces any prior connection. */
+export const connectServiceCatalogSchema = v.object({
+    provider: v.optional(serviceCatalogProviderSchema),
+    /** The portal's base URL, e.g. `https://backstage.corp.internal`. */
+    baseUrl: url,
+    auth: serviceCatalogAuthSchema,
+    /**
+     * Portal-side filter terms, ANDed. Empty/absent ⇒ {@link DEFAULT_SERVICE_CATALOG_FILTER}.
+     * Filtering AT THE PORTAL rather than after the fetch is what keeps a large estate from being
+     * paged through in full on every refresh.
+     */
+    entityFilter: v.optional(v.pipe(v.array(entityFilterTerm), v.maxLength(10))),
+    /**
+     * Whether to import the API definitions each service publishes (`spec.providesApis`).
+     * Defaults to true, being the half of the ask that lets a consumer call a shared service
+     * rather than merely know it exists.
+     */
+    includeApis: v.optional(v.boolean()),
+    /** Cap on imported services. Defaults to {@link DEFAULT_MAX_CATALOG_SERVICES}. */
+    maxServices: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(MAX_CATALOG_SERVICES_CEILING))),
+});
+/**
+ * How much of the portal's matching estate one import covered.
+ *
+ * Three states rather than a count, for the reason the repo-source `folderScan` coverage has
+ * three: each needs a different fix from the person who connected it, and `truncated` must never
+ * read as `complete`. An importer that reported only "42 services" would leave an operator with
+ * a 300-service estate believing the catalog is the estate.
+ */
+export const serviceCatalogCoverageSchema = v.picklist([
+    /** Every matching entity was imported. */
+    'complete',
+    /** The `maxServices` cap stopped the paging short, so the catalog is a PREFIX of the estate. */
+    'truncated',
+    /**
+     * The filter matched nothing at all. Kept apart from `complete` because zero services is
+     * never a healthy `complete`: it is a filter that names a kind, tag or system the portal does
+     * not use, and the remedy is editing the filter rather than waiting for a sync.
+     */
+    'empty',
+]);
+/** What the LAST import concluded, as the management surface reports it. */
+export const serviceCatalogSyncStatusSchema = v.picklist([
+    /** Everything the filter matched arrived, with nothing dropped. */
+    'ok',
+    /**
+     * The import ran and is INCOMPLETE: truncated by the cap, or with entities/definitions it
+     * could not use. Distinct from `failed`: the catalog holds real services, it just does not
+     * hold all of them, and only naming that keeps a partial estate from reading as the estate.
+     */
+    'partial',
+    /** The import could not read the portal at all; whatever the catalog holds is from before. */
+    'failed',
+]);
+/**
+ * The connection as the management surface sees it: never a credential, not even a masked one.
+ *
+ * `authMode` is here because it is the one part of the credential that is configuration rather
+ * than secret, because the operator has to see WHICH scheme a stored connection uses to know whether
+ * it still matches how the portal is deployed.
+ */
+export const serviceCatalogConnectionSchema = v.object({
+    provider: serviceCatalogProviderSchema,
+    baseUrl: v.string(),
+    authMode: serviceCatalogAuthModeSchema,
+    entityFilter: v.array(v.string()),
+    includeApis: v.boolean(),
+    maxServices: v.number(),
+    lastSyncedAt: v.nullable(v.number()),
+    lastSyncStatus: v.nullable(serviceCatalogSyncStatusSchema),
+    /**
+     * What the last import wants a human to know: the truncation, the unreadable definitions, or
+     * the transport failure. Null when the last pass had nothing to report, which is the only
+     * state that needs no sentence.
+     */
+    lastSyncMessage: v.nullable(v.string()),
+    connectedAt: v.number(),
+});
+/** Outcome of one import: what changed in the catalog, and what the pass could not do. */
+export const serviceCatalogSyncResultSchema = v.object({
+    upserted: v.number(),
+    /** Services this connection produced before and the portal no longer offers. */
+    tombstoned: v.number(),
+    unchanged: v.number(),
+    /** API definitions stored across every imported service. */
+    contracts: v.number(),
+    coverage: serviceCatalogCoverageSchema,
+    /**
+     * Entities the filter matched that did NOT become a service: no usable identity, or a name
+     * that yields no slug. Zero and "nothing matched" are told apart by {@link coverage}, and a
+     * non-zero value here is the only thing that explains a catalog thinner than the portal's
+     * own entity count.
+     */
+    skippedServices: v.number(),
+    /**
+     * Portal services this pass REFUSED to write because the workspace already registers a service
+     * under that id by another route (an upload, a linked repo).
+     *
+     * Its own count rather than folded into {@link skippedServices}, because the two name opposite
+     * faults with opposite remedies: a skipped service is an entity the PORTAL describes in a way
+     * this platform cannot use, and this is a collision between two things the workspace itself
+     * did. Refusing is the only safe disposition, since overwriting would silently replace a
+     * hand-authored service (and its uploaded contracts, and any platform capability it was granted)
+     * with the portal's row, and disconnecting would then tombstone the original.
+     */
+    skippedConflicts: v.number(),
+    /**
+     * API definitions a service DECLARES that this pass could not store: a type the platform
+     * serves no format for, an entity the portal would not return, an empty or oversized
+     * definition, or an id that collides with another interface of the same service. Reported
+     * rather than dropped, because a service listed with no interface reads to an agent as a
+     * service that publishes none.
+     */
+    skippedApis: v.number(),
+    status: serviceCatalogSyncStatusSchema,
+});
+//# sourceMappingURL=service-catalog.js.map

package/dist/service-catalog.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/contracts",
-  "version": "0.334.0",
+  "version": "0.335.0",
   "description": "Valibot wire contract shared between the Agent Architecture Board frontend and backend.",
   "repository": {
     "type": "git",