@wildo-ai/saas-models 1.1.2 → 1.1.4

package/dist/esm/external-providers/frontend-provider-entry.shared.schemas.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { FileStorageAccepted } from '@wildo-ai/zod-decorators';
 /**
  * Bundle-safe frontend provider atoms shared by every browser-bound runtime.
  *
@@ -6,9 +7,48 @@ import { z } from 'zod';
  * `@wildo-ai/saas-models/public-runtime` can expose the types without pulling
  * the heavier application-config bootstrap contract into browser bundles.
  */
+/**
+ * One provider as it crosses the DATA channel: authored on a facet module,
+ * projected into a companion contribution, materialized into the generated
+ * frontend-services artifact, served on `/application-config`, and parsed by the
+ * app, the website and the technical doc.
+ *
+ * ## Why this is a LOOSE object
+ *
+ * It is a WIRE RECORD produced by one package version and read by another, and a
+ * strict object silently STRIPS what a newer producer added — which is how a
+ * provider's CSP footprint would vanish between the CLI that wrote it and the
+ * runtime that needs it, leaving a policy that is correct in development
+ * (report-only) and wrong in production (enforcing). #328 made
+ * `ProviderCompanionContributionSchema` loose for exactly this reason, one file
+ * over; the entry rides INSIDE that contribution, so leaving it strict left the
+ * hole one layer down. Required fields stay required; unknown keys are kept
+ * rather than dropped, so a re-emitting consumer cannot silently discard what it
+ * did not understand.
+ *
+ * ## What may and may not be added here
+ *
+ * Only things a JSON channel can carry. A function-valued field would be
+ * stripped by `JSON.stringify` with no error anywhere — the provider would look
+ * declared and do nothing. Executable provider surface (`sdk.activate`,
+ * `publicConfigSchema`, and, from S4b, `components`) belongs on the facet module
+ * types in `@wildo-ai/external-connectors-public`, which reach a bundle through
+ * the generated `frontend-providers.generated.ts` CODE channel instead.
+ */
 export declare const FrontendProviderEntrySchema: z.ZodObject<{
     metadata: z.ZodObject<{
         ref: z.ZodString;
+        packageName: z.ZodString;
+        tier: z.ZodEnum<typeof import("./provider-metadata.shared.schemas").ProviderTier>;
+        vendor: z.ZodString;
+        origin: z.ZodObject<{
+            kind: z.ZodEnum<typeof import("./provider-metadata.shared.schemas").ProviderOriginKind>;
+            catalogue: z.ZodOptional<z.ZodObject<{
+                source: z.ZodEnum<typeof import("./provider-metadata.shared.schemas").ProviderCatalogueSource>;
+                sourceRef: z.ZodString;
+                sourceVersion: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
         displayNameLabelKey: z.ZodOptional<z.ZodString>;
         displayName: z.ZodOptional<z.ZodString>;
         iconRef: z.ZodOptional<z.ZodString>;
@@ -16,12 +56,99 @@ export declare const FrontendProviderEntrySchema: z.ZodObject<{
     providerCapabilities: z.ZodArray<z.ZodString>;
     protocols: z.ZodArray<z.ZodString>;
     publicConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
+    /**
+     * Origins this provider needs the composed CSP of its service to admit.
+     * Consumed by `resolveCspPolicy`'s provider layer; absent means the provider
+     * reaches nothing beyond the surface's own origin.
+     */
+    csp: z.ZodOptional<z.ZodObject<{
+        scriptOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        connectOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        frameOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        imgOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        styleOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        fontOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        derivedOrigins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            publicConfigKey: z.ZodString;
+            bucket: z.ZodEnum<typeof import("./provider-frontend-surface.shared.schemas").ProviderFrontendCspOriginBucket>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    /**
+     * The vendor SDK package this provider loads on demand — the DATA half only.
+     * Its presence tells a surface that the provider HAS executable code to
+     * activate, which is the difference between "declared" and "live" once the
+     * CODE channel is consulted.
+     */
+    sdk: z.ZodOptional<z.ZodObject<{
+        packageName: z.ZodString;
+        versionRange: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    /** Third-party `<script>` tags the surface must add for this provider. */
+    scripts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        src: z.ZodString;
+        integrity: z.ZodOptional<z.ZodString>;
+        crossOrigin: z.ZodOptional<z.ZodEnum<typeof import("./provider-frontend-surface.shared.schemas").ProviderFrontendScriptCrossOrigin>>;
+        async: z.ZodOptional<z.ZodBoolean>;
+        defer: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    /**
+     * The components this provider contributes, by capability — the DATA half
+     * only, exactly as `sdk` is. It says a component EXISTS and what contract it
+     * commits to; the loader stays on the CODE channel, because a function does
+     * not survive `JSON.stringify` and a field that vanishes silently is worse
+     * than a field that was never declared.
+     *
+     * A surface reads this to know a chooser is worth rendering, and to know what
+     * a selection will contain, BEFORE it downloads any provider's component.
+     */
+    components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        selectionDelivery: z.ZodOptional<z.ZodEnum<typeof import("./provider-frontend-surface.shared.schemas").ProviderFrontendSelectionDelivery>>;
+    }, z.core.$strict>>>;
+    /**
+     * The public-config keys the provider module DECLARES it reads — the DATA
+     * half of its `publicConfigSchema`, mirrored here so the companion walk can
+     * refuse an application-supplied key the module never declared, without
+     * executing the module (#394 P3). Absent when the module's schema is not
+     * introspectable, which the overlay reads as "cannot enforce here", never as
+     * "declares nothing".
+     */
+    publicConfigKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /**
+     * The `z_file` storage this provider's file picker is the FRONT DOOR of — the
+     * join key between the provider vocabulary (`google-drive`) and the z_file
+     * vocabulary (`FileStorageAccepted.GOOGLE_DRIVE`) (#394 P5).
+     *
+     * A picker that hands back a `REMOTE_REFERENCE` leaves the bytes at the
+     * vendor, so the FILES row it produces is stored in THAT storage, and a field
+     * may only receive it when its `storageAccepted` names that storage. The
+     * chooser therefore offers such a picker only to a field that accepts the
+     * storage, and the backend refuses the link otherwise — both read this
+     * field. A picker that delivers bytes (`BROWSER_READABLE_*`) declares no
+     * storage: its bytes are ingested into whatever the field's own storage is,
+     * and it is offered to every field.
+     *
+     * DATA half only, like `components`: the backend storage provider that
+     * SERVES the storage is CODE, keyed by the same enum member and naming this
+     * provider back as its `connectedProviderRef`; a pin holds the two ends equal.
+     */
+    fileStorage: z.ZodOptional<z.ZodEnum<typeof FileStorageAccepted>>;
+}, z.core.$loose>;
 export type FrontendProviderEntry = z.infer<typeof FrontendProviderEntrySchema>;
 export declare const FrontendProvidersBlockSchema: z.ZodObject<{
     providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         metadata: z.ZodObject<{
             ref: z.ZodString;
+            packageName: z.ZodString;
+            tier: z.ZodEnum<typeof import("./provider-metadata.shared.schemas").ProviderTier>;
+            vendor: z.ZodString;
+            origin: z.ZodObject<{
+                kind: z.ZodEnum<typeof import("./provider-metadata.shared.schemas").ProviderOriginKind>;
+                catalogue: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodEnum<typeof import("./provider-metadata.shared.schemas").ProviderCatalogueSource>;
+                    sourceRef: z.ZodString;
+                    sourceVersion: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
             displayNameLabelKey: z.ZodOptional<z.ZodString>;
             displayName: z.ZodOptional<z.ZodString>;
             iconRef: z.ZodOptional<z.ZodString>;
@@ -29,7 +156,83 @@ export declare const FrontendProvidersBlockSchema: z.ZodObject<{
         providerCapabilities: z.ZodArray<z.ZodString>;
         protocols: z.ZodArray<z.ZodString>;
         publicConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>>;
+        /**
+         * Origins this provider needs the composed CSP of its service to admit.
+         * Consumed by `resolveCspPolicy`'s provider layer; absent means the provider
+         * reaches nothing beyond the surface's own origin.
+         */
+        csp: z.ZodOptional<z.ZodObject<{
+            scriptOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            connectOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            frameOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            imgOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            styleOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            fontOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            derivedOrigins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                publicConfigKey: z.ZodString;
+                bucket: z.ZodEnum<typeof import("./provider-frontend-surface.shared.schemas").ProviderFrontendCspOriginBucket>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        /**
+         * The vendor SDK package this provider loads on demand — the DATA half only.
+         * Its presence tells a surface that the provider HAS executable code to
+         * activate, which is the difference between "declared" and "live" once the
+         * CODE channel is consulted.
+         */
+        sdk: z.ZodOptional<z.ZodObject<{
+            packageName: z.ZodString;
+            versionRange: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        /** Third-party `<script>` tags the surface must add for this provider. */
+        scripts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            src: z.ZodString;
+            integrity: z.ZodOptional<z.ZodString>;
+            crossOrigin: z.ZodOptional<z.ZodEnum<typeof import("./provider-frontend-surface.shared.schemas").ProviderFrontendScriptCrossOrigin>>;
+            async: z.ZodOptional<z.ZodBoolean>;
+            defer: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        /**
+         * The components this provider contributes, by capability — the DATA half
+         * only, exactly as `sdk` is. It says a component EXISTS and what contract it
+         * commits to; the loader stays on the CODE channel, because a function does
+         * not survive `JSON.stringify` and a field that vanishes silently is worse
+         * than a field that was never declared.
+         *
+         * A surface reads this to know a chooser is worth rendering, and to know what
+         * a selection will contain, BEFORE it downloads any provider's component.
+         */
+        components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            selectionDelivery: z.ZodOptional<z.ZodEnum<typeof import("./provider-frontend-surface.shared.schemas").ProviderFrontendSelectionDelivery>>;
+        }, z.core.$strict>>>;
+        /**
+         * The public-config keys the provider module DECLARES it reads — the DATA
+         * half of its `publicConfigSchema`, mirrored here so the companion walk can
+         * refuse an application-supplied key the module never declared, without
+         * executing the module (#394 P3). Absent when the module's schema is not
+         * introspectable, which the overlay reads as "cannot enforce here", never as
+         * "declares nothing".
+         */
+        publicConfigKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /**
+         * The `z_file` storage this provider's file picker is the FRONT DOOR of — the
+         * join key between the provider vocabulary (`google-drive`) and the z_file
+         * vocabulary (`FileStorageAccepted.GOOGLE_DRIVE`) (#394 P5).
+         *
+         * A picker that hands back a `REMOTE_REFERENCE` leaves the bytes at the
+         * vendor, so the FILES row it produces is stored in THAT storage, and a field
+         * may only receive it when its `storageAccepted` names that storage. The
+         * chooser therefore offers such a picker only to a field that accepts the
+         * storage, and the backend refuses the link otherwise — both read this
+         * field. A picker that delivers bytes (`BROWSER_READABLE_*`) declares no
+         * storage: its bytes are ingested into whatever the field's own storage is,
+         * and it is offered to every field.
+         *
+         * DATA half only, like `components`: the backend storage provider that
+         * SERVES the storage is CODE, keyed by the same enum member and naming this
+         * provider back as its `connectedProviderRef`; a pin holds the two ends equal.
+         */
+        fileStorage: z.ZodOptional<z.ZodEnum<typeof FileStorageAccepted>>;
+    }, z.core.$loose>>>;
 }, z.core.$strip>;
 export type FrontendProvidersBlock = z.infer<typeof FrontendProvidersBlockSchema>;
 //# sourceMappingURL=frontend-provider-entry.shared.schemas.d.ts.map

package/dist/esm/external-providers/frontend-provider-entry.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-provider-entry.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/frontend-provider-entry.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;iBAKtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;iBAEvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}
+{"version":3,"file":"frontend-provider-entry.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/external-providers/frontend-provider-entry.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAS/D;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;IAKtC;;;;OAIG;;;;;;;;;;;;;IAEH;;;;;OAKG;;;;;IAEH,0EAA0E;;;;;;;;IAE1E;;;;;;;;;OASG;;;;IAEH;;;;;;;OAOG;;IAEH;;;;;;;;;;;;;;;;;OAiBG;;iBAEH,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;QAzDvC;;;;WAIG;;;;;;;;;;;;;QAEH;;;;;WAKG;;;;;QAEH,0EAA0E;;;;;;;;QAE1E;;;;;;;;;WASG;;;;QAEH;;;;;;;WAOG;;QAEH;;;;;;;;;;;;;;;;;WAiBG;;;iBAOH,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/esm/external-providers/frontend-provider-entry.shared.schemas.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
+import { FileStorageAccepted } from '@wildo-ai/zod-decorators';
 import { ProviderMetadataSchema } from './provider-metadata.shared.schemas.js';
+import { ProviderFrontendComponentDescriptorsSchema, ProviderFrontendCspFootprintSchema, ProviderFrontendScriptDeclarationSchema, ProviderFrontendSdkDescriptorSchema, } from './provider-frontend-surface.shared.schemas.js';
 /**
  * Bundle-safe frontend provider atoms shared by every browser-bound runtime.
  *
@@ -7,11 +9,93 @@ import { ProviderMetadataSchema } from './provider-metadata.shared.schemas.js';
  * `@wildo-ai/saas-models/public-runtime` can expose the types without pulling
  * the heavier application-config bootstrap contract into browser bundles.
  */
-export const FrontendProviderEntrySchema = z.object({
+/**
+ * One provider as it crosses the DATA channel: authored on a facet module,
+ * projected into a companion contribution, materialized into the generated
+ * frontend-services artifact, served on `/application-config`, and parsed by the
+ * app, the website and the technical doc.
+ *
+ * ## Why this is a LOOSE object
+ *
+ * It is a WIRE RECORD produced by one package version and read by another, and a
+ * strict object silently STRIPS what a newer producer added — which is how a
+ * provider's CSP footprint would vanish between the CLI that wrote it and the
+ * runtime that needs it, leaving a policy that is correct in development
+ * (report-only) and wrong in production (enforcing). #328 made
+ * `ProviderCompanionContributionSchema` loose for exactly this reason, one file
+ * over; the entry rides INSIDE that contribution, so leaving it strict left the
+ * hole one layer down. Required fields stay required; unknown keys are kept
+ * rather than dropped, so a re-emitting consumer cannot silently discard what it
+ * did not understand.
+ *
+ * ## What may and may not be added here
+ *
+ * Only things a JSON channel can carry. A function-valued field would be
+ * stripped by `JSON.stringify` with no error anywhere — the provider would look
+ * declared and do nothing. Executable provider surface (`sdk.activate`,
+ * `publicConfigSchema`, and, from S4b, `components`) belongs on the facet module
+ * types in `@wildo-ai/external-connectors-public`, which reach a bundle through
+ * the generated `frontend-providers.generated.ts` CODE channel instead.
+ */
+export const FrontendProviderEntrySchema = z.looseObject({
     metadata: ProviderMetadataSchema,
     providerCapabilities: z.array(z.string().min(1)),
     protocols: z.array(z.string().min(1)),
     publicConfig: z.record(z.string(), z.unknown()).optional(),
+    /**
+     * Origins this provider needs the composed CSP of its service to admit.
+     * Consumed by `resolveCspPolicy`'s provider layer; absent means the provider
+     * reaches nothing beyond the surface's own origin.
+     */
+    csp: ProviderFrontendCspFootprintSchema.optional(),
+    /**
+     * The vendor SDK package this provider loads on demand — the DATA half only.
+     * Its presence tells a surface that the provider HAS executable code to
+     * activate, which is the difference between "declared" and "live" once the
+     * CODE channel is consulted.
+     */
+    sdk: ProviderFrontendSdkDescriptorSchema.optional(),
+    /** Third-party `<script>` tags the surface must add for this provider. */
+    scripts: z.array(ProviderFrontendScriptDeclarationSchema).optional(),
+    /**
+     * The components this provider contributes, by capability — the DATA half
+     * only, exactly as `sdk` is. It says a component EXISTS and what contract it
+     * commits to; the loader stays on the CODE channel, because a function does
+     * not survive `JSON.stringify` and a field that vanishes silently is worse
+     * than a field that was never declared.
+     *
+     * A surface reads this to know a chooser is worth rendering, and to know what
+     * a selection will contain, BEFORE it downloads any provider's component.
+     */
+    components: ProviderFrontendComponentDescriptorsSchema.optional(),
+    /**
+     * The public-config keys the provider module DECLARES it reads — the DATA
+     * half of its `publicConfigSchema`, mirrored here so the companion walk can
+     * refuse an application-supplied key the module never declared, without
+     * executing the module (#394 P3). Absent when the module's schema is not
+     * introspectable, which the overlay reads as "cannot enforce here", never as
+     * "declares nothing".
+     */
+    publicConfigKeys: z.array(z.string().min(1)).optional(),
+    /**
+     * The `z_file` storage this provider's file picker is the FRONT DOOR of — the
+     * join key between the provider vocabulary (`google-drive`) and the z_file
+     * vocabulary (`FileStorageAccepted.GOOGLE_DRIVE`) (#394 P5).
+     *
+     * A picker that hands back a `REMOTE_REFERENCE` leaves the bytes at the
+     * vendor, so the FILES row it produces is stored in THAT storage, and a field
+     * may only receive it when its `storageAccepted` names that storage. The
+     * chooser therefore offers such a picker only to a field that accepts the
+     * storage, and the backend refuses the link otherwise — both read this
+     * field. A picker that delivers bytes (`BROWSER_READABLE_*`) declares no
+     * storage: its bytes are ingested into whatever the field's own storage is,
+     * and it is offered to every field.
+     *
+     * DATA half only, like `components`: the backend storage provider that
+     * SERVES the storage is CODE, keyed by the same enum member and naming this
+     * provider back as its `connectedProviderRef`; a pin holds the two ends equal.
+     */
+    fileStorage: z.enum(FileStorageAccepted).optional(),
 });
 export const FrontendProvidersBlockSchema = z.object({
     providers: z.record(z.string().min(1), FrontendProviderEntrySchema).default({}),

package/dist/esm/external-providers/frontend-provider-entry.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-provider-entry.shared.schemas.js","sourceRoot":"","sources":["../../../../src/external-providers/frontend-provider-entry.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,QAAQ,EAAE,sBAAsB;IAChC,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC3D,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,2BAA2B,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAChF,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\nimport { ProviderMetadataSchema } from './provider-metadata.shared.schemas';\n\n/**\n * Bundle-safe frontend provider atoms shared by every browser-bound runtime.\n *\n * This file intentionally stops at the provider-entry/block level so\n * `@wildo-ai/saas-models/public-runtime` can expose the types without pulling\n * the heavier application-config bootstrap contract into browser bundles.\n */\nexport const FrontendProviderEntrySchema = z.object({\n  metadata: ProviderMetadataSchema,\n  providerCapabilities: z.array(z.string().min(1)),\n  protocols: z.array(z.string().min(1)),\n  publicConfig: z.record(z.string(), z.unknown()).optional(),\n});\nexport type FrontendProviderEntry = z.infer<typeof FrontendProviderEntrySchema>;\n\nexport const FrontendProvidersBlockSchema = z.object({\n  providers: z.record(z.string().min(1), FrontendProviderEntrySchema).default({}),\n});\nexport type FrontendProvidersBlock = z.infer<typeof FrontendProvidersBlockSchema>;\n"]}
+{"version":3,"file":"frontend-provider-entry.shared.schemas.js","sourceRoot":"","sources":["../../../src/external-providers/frontend-provider-entry.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EACL,0CAA0C,EAC1C,kCAAkC,EAClC,uCAAuC,EACvC,mCAAmC,GACpC,MAAM,4CAA4C,CAAC;AAEpD;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC;IACvD,QAAQ,EAAE,sBAAsB;IAChC,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC1D;;;;OAIG;IACH,GAAG,EAAE,kCAAkC,CAAC,QAAQ,EAAE;IAClD;;;;;OAKG;IACH,GAAG,EAAE,mCAAmC,CAAC,QAAQ,EAAE;IACnD,0EAA0E;IAC1E,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC,QAAQ,EAAE;IACpE;;;;;;;;;OASG;IACH,UAAU,EAAE,0CAA0C,CAAC,QAAQ,EAAE;IACjE;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,QAAQ,EAAE;CACpD,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,2BAA2B,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAChF,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\nimport { FileStorageAccepted } from '@wildo-ai/zod-decorators';\nimport { ProviderMetadataSchema } from './provider-metadata.shared.schemas';\nimport {\n  ProviderFrontendComponentDescriptorsSchema,\n  ProviderFrontendCspFootprintSchema,\n  ProviderFrontendScriptDeclarationSchema,\n  ProviderFrontendSdkDescriptorSchema,\n} from './provider-frontend-surface.shared.schemas';\n\n/**\n * Bundle-safe frontend provider atoms shared by every browser-bound runtime.\n *\n * This file intentionally stops at the provider-entry/block level so\n * `@wildo-ai/saas-models/public-runtime` can expose the types without pulling\n * the heavier application-config bootstrap contract into browser bundles.\n */\n\n/**\n * One provider as it crosses the DATA channel: authored on a facet module,\n * projected into a companion contribution, materialized into the generated\n * frontend-services artifact, served on `/application-config`, and parsed by the\n * app, the website and the technical doc.\n *\n * ## Why this is a LOOSE object\n *\n * It is a WIRE RECORD produced by one package version and read by another, and a\n * strict object silently STRIPS what a newer producer added — which is how a\n * provider's CSP footprint would vanish between the CLI that wrote it and the\n * runtime that needs it, leaving a policy that is correct in development\n * (report-only) and wrong in production (enforcing). #328 made\n * `ProviderCompanionContributionSchema` loose for exactly this reason, one file\n * over; the entry rides INSIDE that contribution, so leaving it strict left the\n * hole one layer down. Required fields stay required; unknown keys are kept\n * rather than dropped, so a re-emitting consumer cannot silently discard what it\n * did not understand.\n *\n * ## What may and may not be added here\n *\n * Only things a JSON channel can carry. A function-valued field would be\n * stripped by `JSON.stringify` with no error anywhere — the provider would look\n * declared and do nothing. Executable provider surface (`sdk.activate`,\n * `publicConfigSchema`, and, from S4b, `components`) belongs on the facet module\n * types in `@wildo-ai/external-connectors-public`, which reach a bundle through\n * the generated `frontend-providers.generated.ts` CODE channel instead.\n */\nexport const FrontendProviderEntrySchema = z.looseObject({\n  metadata: ProviderMetadataSchema,\n  providerCapabilities: z.array(z.string().min(1)),\n  protocols: z.array(z.string().min(1)),\n  publicConfig: z.record(z.string(), z.unknown()).optional(),\n  /**\n   * Origins this provider needs the composed CSP of its service to admit.\n   * Consumed by `resolveCspPolicy`'s provider layer; absent means the provider\n   * reaches nothing beyond the surface's own origin.\n   */\n  csp: ProviderFrontendCspFootprintSchema.optional(),\n  /**\n   * The vendor SDK package this provider loads on demand — the DATA half only.\n   * Its presence tells a surface that the provider HAS executable code to\n   * activate, which is the difference between \"declared\" and \"live\" once the\n   * CODE channel is consulted.\n   */\n  sdk: ProviderFrontendSdkDescriptorSchema.optional(),\n  /** Third-party `<script>` tags the surface must add for this provider. */\n  scripts: z.array(ProviderFrontendScriptDeclarationSchema).optional(),\n  /**\n   * The components this provider contributes, by capability — the DATA half\n   * only, exactly as `sdk` is. It says a component EXISTS and what contract it\n   * commits to; the loader stays on the CODE channel, because a function does\n   * not survive `JSON.stringify` and a field that vanishes silently is worse\n   * than a field that was never declared.\n   *\n   * A surface reads this to know a chooser is worth rendering, and to know what\n   * a selection will contain, BEFORE it downloads any provider's component.\n   */\n  components: ProviderFrontendComponentDescriptorsSchema.optional(),\n  /**\n   * The public-config keys the provider module DECLARES it reads — the DATA\n   * half of its `publicConfigSchema`, mirrored here so the companion walk can\n   * refuse an application-supplied key the module never declared, without\n   * executing the module (#394 P3). Absent when the module's schema is not\n   * introspectable, which the overlay reads as \"cannot enforce here\", never as\n   * \"declares nothing\".\n   */\n  publicConfigKeys: z.array(z.string().min(1)).optional(),\n  /**\n   * The `z_file` storage this provider's file picker is the FRONT DOOR of — the\n   * join key between the provider vocabulary (`google-drive`) and the z_file\n   * vocabulary (`FileStorageAccepted.GOOGLE_DRIVE`) (#394 P5).\n   *\n   * A picker that hands back a `REMOTE_REFERENCE` leaves the bytes at the\n   * vendor, so the FILES row it produces is stored in THAT storage, and a field\n   * may only receive it when its `storageAccepted` names that storage. The\n   * chooser therefore offers such a picker only to a field that accepts the\n   * storage, and the backend refuses the link otherwise — both read this\n   * field. A picker that delivers bytes (`BROWSER_READABLE_*`) declares no\n   * storage: its bytes are ingested into whatever the field's own storage is,\n   * and it is offered to every field.\n   *\n   * DATA half only, like `components`: the backend storage provider that\n   * SERVES the storage is CODE, keyed by the same enum member and naming this\n   * provider back as its `connectedProviderRef`; a pin holds the two ends equal.\n   */\n  fileStorage: z.enum(FileStorageAccepted).optional(),\n});\nexport type FrontendProviderEntry = z.infer<typeof FrontendProviderEntrySchema>;\n\nexport const FrontendProvidersBlockSchema = z.object({\n  providers: z.record(z.string().min(1), FrontendProviderEntrySchema).default({}),\n});\nexport type FrontendProvidersBlock = z.infer<typeof FrontendProvidersBlockSchema>;\n"]}

package/dist/esm/external-providers/frontend-provider-public-config.shared.d.ts

@@ -0,0 +1,175 @@
+/**
+ * How an APPLICATION supplies a frontend provider's public configuration — the
+ * keys a picker needs that only the application can know (a Drive `appId`, a
+ * OneDrive `clientId`) — and the two guards that keep that channel from
+ * carrying anything else.
+ *
+ * ## The gap this closes
+ *
+ * A frontend provider's `publicConfig` was HARD-CODED on the engine's provider
+ * module and projected verbatim onto the wire. The only way to set a picker's
+ * `appId` was to edit engine code. The backend never had that problem: an
+ * application authors `providerConfigurations[providerRef][protocolKind]` in
+ * `wildo.saas.config.ts`, and SSO's public OAuth client id already travels that
+ * way, keyed by the protocol (`sso_oauth2`).
+ *
+ * This file gives the frontend the same channel, keyed by the same vocabulary:
+ * `providerConfigurations[providerRef][frontend_sdk]`. One authority for
+ * "what an application configured for this provider", read by both sides.
+ *
+ * ## Two guards, because `publicConfig` is served to every browser
+ *
+ * 1. **Only DECLARED keys cross.** A provider module declares the keys it reads
+ *    (`publicConfigSchema` — see `defineFrontendPublicConfigSchema` below, which
+ *    is what makes those keys READABLE without running the schema). A key the
+ *    module never declared is refused with the provider and key named, at the
+ *    two places the overlay runs: `wildo config sync` and the backend's
+ *    fallback projection. A misspelled `apiId` therefore fails where it was
+ *    typed, instead of silently contributing nothing and leaving a picker that
+ *    reports "no appId" at the moment a user opens it.
+ *
+ * 2. **A secret never crosses.** A frontend provider owns no secrets by
+ *    construction (`secretsContractShape: []`), so the only way one reaches a
+ *    browser is an author typing the BACKEND module's secret into the frontend
+ *    bag. The overlay refuses any key whose name matches a slug or an
+ *    environment-variable name from the same vendor's backend secrets
+ *    contract — `GOOGLE_OAUTH2_CLIENT_SECRET` cannot be typed into the bag that
+ *    every visitor downloads.
+ *
+ * Both guards are decisions about NAMES, so they run wherever the names are
+ * known and need no schema execution. Value VALIDATION (is `appId` a string?)
+ * is the schema's job and runs where the schema is: at hydration (FE-8) and, on
+ * the backend fallback, before serving.
+ *
+ * ## Why the overlay is a pure function in this package
+ *
+ * It has THREE call sites that must agree — the companion walk in
+ * `platform-config-lib`, the backend fallback in `saas-backend-lib`, and any
+ * future producer of a `FrontendProviderEntry` — and #380 already paid once for
+ * a projection that landed on one site and not another. A function both import
+ * cannot be applied differently by each.
+ */
+/**
+ * The key under `providerConfigurations[providerRef]` an application uses to
+ * supply a frontend provider's public configuration.
+ *
+ * The protocol kind, exactly as SSO's channel is keyed by ITS protocol kind
+ * (`sso_oauth2`): the bag is per-provider, per-protocol, and a frontend module
+ * speaks `FRONTEND_SDK`. Not a new literal — the enum member is the one source.
+ */
+export declare const FRONTEND_PROVIDER_PUBLIC_CONFIG_KEY: string;
+/** Why an application-supplied public-config bag was refused. */
+export declare enum FrontendProviderPublicConfigRefusal {
+    /** A key the provider module does not declare — almost always a misspelling. */
+    UNDECLARED_KEY = "UNDECLARED_KEY",
+    /** A key naming a secret from the same vendor's backend contract. Never negotiable. */
+    SECRET_KEY = "SECRET_KEY",
+    /** The supplied bag is not a plain object — a string, an array, `null`. */
+    NOT_AN_OBJECT = "NOT_AN_OBJECT"
+}
+export declare class FrontendProviderPublicConfigError extends Error {
+    readonly providerRef: string;
+    readonly refusal: FrontendProviderPublicConfigRefusal;
+    readonly keys: readonly string[];
+    constructor(providerRef: string, refusal: FrontendProviderPublicConfigRefusal, keys: readonly string[], message: string);
+}
+export interface OverlayFrontendProviderPublicConfigInput {
+    readonly providerRef: string;
+    /** What the provider module authored — its own defaults, e.g. `{ authProviderRef: 'google' }`. */
+    readonly authored: Readonly<Record<string, unknown>> | undefined;
+    /** What the application supplied under `providerConfigurations[providerRef][frontend_sdk]`. */
+    readonly supplied: unknown;
+    /**
+     * The keys the provider module declares it reads. `undefined` means the
+     * module declared no introspectable schema, so guard 1 cannot run HERE and
+     * hydration's validation is the gate; an empty array means the module
+     * declares it reads NOTHING, so every supplied key is refused.
+     */
+    readonly declaredKeys: readonly string[] | undefined;
+    /** Slugs and environment-variable names of the same vendor's backend secrets. */
+    readonly forbiddenKeys: ReadonlySet<string>;
+}
+/**
+ * Merges what the application supplied over what the module authored, refusing
+ * the two classes of key that must never reach a browser.
+ *
+ * Supplied values WIN over authored ones for the same key: the module's value is
+ * a default, and an application that names a key means it. Absent `supplied`
+ * returns the authored bag untouched — an application that configured nothing
+ * is the ordinary case, not a refusal.
+ */
+export declare function overlayFrontendProviderPublicConfig(input: OverlayFrontendProviderPublicConfigInput): Readonly<Record<string, unknown>> | undefined;
+/**
+ * The value kinds a public-config key may declare. Scalars only, on purpose: a
+ * public key is an identifier or a flag, and a structured value here is a
+ * design smell — a provider that needs one has a capability-level shape
+ * (`FrontendFilePickerPublicConfigSchema`) to declare it in.
+ */
+export declare enum FrontendPublicConfigValueKind {
+    STRING = "string",
+    NUMBER = "number",
+    BOOLEAN = "boolean"
+}
+export interface FrontendPublicConfigKeySpec {
+    readonly kind: FrontendPublicConfigValueKind;
+    /** Absent = optional. Picker keys are usually optional: a missing one is reported when the picker opens, not by dropping the provider. */
+    readonly required?: boolean;
+    /** For the person writing `wildo.saas.config.ts`. Not validated; surfaced in refusals. */
+    readonly description?: string;
+}
+/** A Standard Schema v1 validator that ALSO says which keys it declares. */
+export interface FrontendPublicConfigSchema<TOutput = Readonly<Record<string, unknown>>> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: 'wildo';
+        validate(value: unknown): {
+            readonly value: TOutput;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+                readonly path?: ReadonlyArray<PropertyKey>;
+            }>;
+        };
+    };
+    /**
+     * The keys this schema admits, readable without running it.
+     *
+     * This is the DATA half of the declaration, and it is why this helper exists
+     * rather than "use Zod": Standard Schema v1 exposes `validate` and nothing
+     * else, so a schema alone cannot tell the companion walk which keys an
+     * application may supply — and the walk runs in Node, from a projected
+     * contribution, without the module. `projectFrontendProviderContribution`
+     * mirrors this list onto the entry as `publicConfigKeys`.
+     */
+    readonly declaredKeys: readonly string[];
+}
+/**
+ * Declares a frontend provider's public-config keys ONCE and gets both halves:
+ * a strict Standard Schema v1 validator (the CODE half hydration runs) and the
+ * key list (the DATA half the companion walk reads).
+ *
+ * Dependency-free by design. It lives here because the engine's provider modules
+ * live in `@wildo-ai/external-connectors-public`, whose bare-specifier allow-list
+ * holds exactly one entry — this package's `/public-runtime` — so those modules
+ * can declare a schema without that package growing a validation library. An
+ * application module may still use Zod (a Zod object satisfies Standard Schema
+ * and its `shape` keys are read the same way).
+ *
+ * Strict: an unknown key is an issue, never ignored. Silently ignoring is the
+ * defect FE-8 closed — a renamed key yielding `undefined` and a picker that
+ * accepts more than it should with no error anywhere.
+ */
+export declare function defineFrontendPublicConfigSchema(keys: Readonly<Record<string, FrontendPublicConfigKeySpec>>): FrontendPublicConfigSchema;
+/**
+ * Reads the declared keys off a provider's `publicConfigSchema`, whatever
+ * library produced it.
+ *
+ * Two shapes are recognised, and the order matters: a schema built by
+ * `defineFrontendPublicConfigSchema` states its keys outright; a Zod object
+ * exposes them as `shape`. Anything else — a hand-written Standard Schema, a
+ * library without introspection — yields `undefined`, which the overlay reads
+ * as "cannot enforce here" rather than as "declares nothing". That distinction
+ * is load-bearing: an empty list refuses EVERY supplied key.
+ */
+export declare function readDeclaredPublicConfigKeys(schema: unknown): readonly string[] | undefined;
+//# sourceMappingURL=frontend-provider-public-config.shared.d.ts.map

package/dist/esm/external-providers/frontend-provider-public-config.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-provider-public-config.shared.d.ts","sourceRoot":"","sources":["../../../src/external-providers/frontend-provider-public-config.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,EAAE,MAA4D,CAAC;AAE/G,iEAAiE;AACjE,oBAAY,mCAAmC;IAC7C,gFAAgF;IAChF,cAAc,mBAAmB;IACjC,uFAAuF;IACvF,UAAU,eAAe;IACzB,2EAA2E;IAC3E,aAAa,kBAAkB;CAChC;AAED,qBAAa,iCAAkC,SAAQ,KAAK;IAExD,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,OAAO,EAAE,mCAAmC;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE;gBAFvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mCAAmC,EAC5C,IAAI,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,wCAAwC;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,wCAAwC,GAC9C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAiD/C;AAED;;;;;GAKG;AACH,oBAAY,6BAA6B;IACvC,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,0IAA0I;IAC1I,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B,CAAC,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrF,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,GACnB;YAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;SAAE,GAC3B;YAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;gBAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC;KAClH,CAAC;IACF;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC,GAC1D,0BAA0B,CAiC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAU3F"}