@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/config/models/app-config.backend.schemas.js

@@ -8,6 +8,7 @@ import { AnalyticsConfigSchema, AuditTrailConfigSchema, AppConfiguration_Shared_
 import { INFRA_DEFAULT_PORTS, STORAGE_DEFAULTS } from '@wildo-ai/platform-config-lib';
 import { ApplicationBackendDataEnvKeys } from '@wildo-ai/platform-core-shared';
 import { z } from 'zod';
+import { ExternalProvider_ConnectionShapeSchema } from '@wildo-ai/external-connectors-models';
 import { AllApplicationTypesSchema } from '../../applications/models/applications.backend.schemas.js';
 import { VerifiableJwtKeysSchema } from '../../security/authentications/models/jwt.backend.schemas.js';
 import { CimdApplicationConfigSchema, DynamicClientRegistrationConfigSchema } from '../../security/authentications/models/cimd.backend.schemas.js';
@@ -23,7 +24,7 @@ const ProviderScopeSelectionSchema = z.strictObject({
 });
 const ProviderSelectionPolicySchema = z.strictObject({
     primary: z.string().min(1),
-    fallbacks: z.array(z.string().min(1)).default([]),
+    whenUnavailable: z.array(z.string().min(1)).default([]),
 });
 const RuntimeProviderScopeSchema = z.strictObject({
     providers: z.record(z.string().min(1), ProviderScopeSelectionSchema).default({}),
@@ -36,9 +37,21 @@ const ProviderScopesSchema = z.strictObject({
     minions: z.record(z.string().min(1), RuntimeProviderScopeSchema).optional(),
     workers: z.record(z.string().min(1), RuntimeProviderScopeSchema).optional(),
 });
+/**
+ * WHICH of a provider's admissible connections this application permits.
+ *
+ * The runtime half of `providers.connections` in the SaaS config. The registry intersects it with the
+ * provider's own catalogue record, so this can only ever SUBTRACT: an application cannot declare a
+ * connection the vendor does not support into existence, and an absent entry means "everything the
+ * provider admits" rather than "nothing".
+ */
+const ProviderConnectionPolicySchema = z.strictObject({
+    admissible: z.array(ExternalProvider_ConnectionShapeSchema).min(1),
+});
 const ProvidersBlockSchema = z.strictObject({
     scopes: ProviderScopesSchema,
-}).default(() => ({ scopes: {} }));
+    connections: z.record(z.string().min(1), ProviderConnectionPolicySchema).default(() => ({})),
+}).default(() => ({ scopes: {}, connections: {} }));
 /**
  * Minion runtime inventory materialized from the SaaS declaration.
  *
@@ -55,12 +68,29 @@ const MinionResourceAccessSchema = z.strictObject({
  * The named runtime source for the minion execution-mode vocabulary (KD-3).
  *
  * A const object rather than a nominal enum, deliberately: the AUTHORING surface for these values
- * is `defineMinionConfig` in `platform-config-lib` (which this engine package must not depend on,
- * and which declares the same wire values structurally), and the CLI merge in
- * `app-runtime-targets.service.ts` carries them across that seam as plain strings. A nominal enum
- * here would break that seam's assignability while unifying nothing. When the vocabulary ever
- * gains a member, add it here AND in `define-minion-config.ts` in the same change — the two
- * declarations share wire values by contract, not by import.
+ * is `defineMinionConfig` in `platform-config-lib`, which declares the same wire values
+ * structurally, and the CLI merge in `app-runtime-targets.service.ts` carries them across that seam
+ * as plain strings. A nominal enum here would break that seam's assignability while unifying
+ * nothing. That reasoning is unchanged and is why this stays a const object.
+ *
+ * ## CORRECTION 2026-09-09 — the premise attached to it was false, and it was load-bearing
+ *
+ * This used to read "`defineMinionConfig` in `platform-config-lib` (which this engine package must
+ * not depend on ...)". There is no such prohibition, and there never was one this file honoured:
+ * `@wildo-ai/platform-config-lib` is a hard `dependencies` edge in this package's `package.json`,
+ * and line 29 of THIS file imports two runtime values (`INFRA_DEFAULT_PORTS`, `STORAGE_DEFAULTS`)
+ * across it. A boundary asserted in prose while the file beside it crosses the boundary is not a
+ * policy; it is a claim nobody checked.
+ *
+ * It mattered because it was cited. `app-configuration-loader.backend.service.ts` pointed at this
+ * note as the reason its bootstrap-response schema re-declared the managed minion and worker blocks
+ * by hand instead of importing them — and that hand copy silently stripped `mode`/`schedule` (the
+ * KD-12 cron-tick path, dead in production) and then `platformAccess`, because Zod deletes what a
+ * schema does not declare. The loader now imports the platform's own schemas; only the two
+ * declarations below remain, and they are held in step MECHANICALLY by
+ * `config/__tests__/managed-runtime-inventory-parity.backend.test.ts` rather than by a sentence
+ * asking the next author to remember. That pin covers this vocabulary too: adding a member here and
+ * not in `define-minion-config.ts` (or the reverse) reddens it.
  */
 export const APP_CONFIGURATION_MINION_MODES = {
     /** A long-running daemon; self-ticks from its own loop, never registered as a CronJob. */
@@ -74,8 +104,22 @@ const AppConfiguration_MinionEntrySchema = z.strictObject({
     mode: z.enum(APP_CONFIGURATION_MINION_MODES).optional(),
     schedule: z.string().min(1).optional(),
 });
-const AppConfiguration_MinionsSchema = z.record(z.string().min(1), AppConfiguration_MinionEntrySchema).default({});
-const AppConfiguration_WorkersSchema = z.record(z.string().min(1), z.strictObject({
+/**
+ * Exported ONLY so the parity pin can reach it — no production consumer imports either of these two
+ * from outside this module.
+ *
+ * `config/__tests__/managed-runtime-inventory-parity.backend.test.ts` compares this declaration,
+ * field for field, against `AdminAppManagedMinionsSchema` / `AdminAppManagedWorkersSchema` in
+ * `@wildo-ai/platform-config-lib` — the schemas the apps-manager wire actually carries. The two
+ * cannot simply be collapsed: this side is a `strictObject` annotated against a named interface for
+ * the TS7056 serialization-ceiling reason recorded on `AppConfiguration_MinionEntry` above, and the
+ * wire side must stay strip-tolerant so an additive platform change cannot brick an application
+ * backend mid-deploy. Two declarations are therefore the design; two declarations DRIFTING is the
+ * defect, and the pin is what separates the two.
+ */
+export const AppConfiguration_MinionsSchema = z.record(z.string().min(1), AppConfiguration_MinionEntrySchema).default({});
+/** Exported for the parity pin — see `AppConfiguration_MinionsSchema` above. */
+export const AppConfiguration_WorkersSchema = z.record(z.string().min(1), z.strictObject({
     name: z.string().min(1),
     displayName: z.string().min(1),
     description: z.string().optional(),
@@ -215,6 +259,52 @@ export const AppConfiguration_AuthSchema = AppConfiguration_Shared_AuthSchema.ex
      * by upgrading the framework.
      */
     dynamicClientRegistration: DynamicClientRegistrationConfigSchema.optional(),
+    /**
+     * Backend-only: how long a remembered OAuth consent ("remember this app") stays valid, in days.
+     *
+     * OPTIONAL — absent means `OAUTH_CONSENT_GRANT_DEFAULT_LIFETIME_DAYS` (180), whose reasoning is
+     * written at the constant. An application shortens it when its data is sensitive enough to want
+     * re-affirmation sooner, or lengthens it for a long-lived integration.
+     *
+     * The ceiling is ten years rather than unbounded: a lifetime long enough to be indistinguishable
+     * from "never" would reintroduce exactly the state this replaced, where a standing delegation of
+     * authority to a third party outlived any memory of granting it. There is no "never" value.
+     */
+    consentGrantLifetimeDays: z.number().int().min(1).max(3650).optional(),
+    /**
+     * Backend-only: where an application's SCIM discovery document sends a directory administrator
+     * for integration documentation — RFC 7643 §5's `documentationUri`, on the ServiceProviderConfig
+     * itself and on its OAuth bearer-token authentication scheme.
+     *
+     * OPTIONAL, and absence means the FIELDS ARE OMITTED rather than emptied. The RFC marks both as
+     * OPTIONAL, so a discovery document without them is conformant; a document carrying a URL that
+     * answers nothing is not, in any sense that matters to the person reading it.
+     *
+     * spec-cite: RFC 7643 §5 — the ServiceProviderConfig `documentationUri` attribute and the
+     * `authenticationSchemes` sub-attribute of the same name are each defined as "An HTTP-addressable
+     * URL pointing to the service provider's human-consumable help documentation. OPTIONAL."
+     *
+     * ## Why this is authored per application rather than defaulted
+     *
+     * The framework used to ship both values frozen, pointing at `docs.wildo.ai/scim` and
+     * `/scim/auth` — a host with no DNS record at all, so every application built on Wildo told its
+     * enterprise customers to go somewhere that does not resolve. Even had the pages existed, the
+     * RFC defines the field as "the SERVICE PROVIDER's human-consumable help documentation", and the
+     * service provider is the application, not the framework that built it. A directory
+     * administrator integrating with an application should not be routed to that application's
+     * vendor's vendor.
+     *
+     * So the value belongs to whoever has customers to send somewhere, and the default is silence.
+     * An application with no SCIM documentation says nothing, which is true; one that has written
+     * some says where, which is also true. There is no configuration that produces the previous
+     * behaviour, deliberately.
+     */
+    scimDocumentation: z.object({
+        /** RFC 7643 §5 `documentationUri` — how this application's SCIM implementation is integrated with. */
+        serviceProviderUri: z.url().optional(),
+        /** RFC 7643 §5 authentication-scheme `documentationUri` — how a caller obtains and uses its bearer token. */
+        authenticationSchemeUri: z.url().optional(),
+    }).optional(),
     /** Backend-only: password hashing configuration (rules are in shared passwordPolicy) */
     passwordHashing: z.object({
         argon2: Argon2PasswordHashingSchema.optional(),
@@ -330,11 +420,30 @@ export const EmailBrandTokens_ConfigSchema = z.object({
     primaryColor: z.string().optional(),
     secondaryColor: z.string().optional(),
     fontFamily: z.string().optional(),
-    logoUrl: z.string().optional(),
+    /*
+     * NO `logoUrl` here, deliberately (#448). It was accepted by this schema and never mapped into
+     * `EmailBrandTokens`, which has no logo field — so configuring it rendered nothing, on either of
+     * the two routes that existed.
+     *
+     * The logo is NOT a brand token, because it is SCOPE-RESOLVED rather than configured: the
+     * dispatcher and the three authentication paths resolve an email-optimised, absolute brand-asset
+     * URL into `primaryScopeContext.logoUrl` (LOCKUP → EMAIL purpose, with the resolver's own
+     * fallbacks, `undefined` when no asset has been generated). Every template reads it from there
+     * and passes it to `EmailLayout`. Routing it through a config key instead would have needed new
+     * plumbing for a value that already existed one field away, and would not have been per-scope —
+     * which matters now that organisation branding is becoming a real layer (#410).
+     */
 });
 export const AppConfiguration_Email_Schema = z.object({
     from: z.email({ error: 'Valid from email required' }),
-    replyTo: z.email().optional(),
+    /*
+     * NO application-level `replyTo`. It was declared here and read by no send path — reply-to comes
+     * only from the per-request `EmailSendRequest.replyTo`, which every provider module does forward
+     * (`ReplyTo` on Postmark, `reply_to` on SendGrid and Resend, `h:Reply-To` on Mailgun, `replyTo`
+     * on Brevo) and which the notification dispatcher and the authentication flows never set.
+     * Removed 2026-09-08 (#447): reply-to is per-request by design. An application that wants one on
+     * a framework-sent message needs the dispatcher to set it, not a config key nothing reads.
+     */
     isTransactionalWildoManaged: z.boolean(),
     isMarketingWildoManaged: z.boolean(),
     brandTokens: EmailBrandTokens_ConfigSchema.optional(),