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

package/dist/esm/external-providers/services/external-providers-registry.backend.service.js

@@ -16,10 +16,14 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { injectable, inject } from 'inversify';
-import { EngineCapabilityResolutionMode, getEngineCapabilityResolutionMode, PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY, } from '@wildo-ai/saas-models';
-import { ExternalProvider_ExchangeProtocol_Kind, LLMProvider_OperationKey, DocumentExtractionProvider_OperationKey, EmbeddingsProvider_OperationKey, APPLICATION_ENVIRONMENT, } from '@wildo-ai/external-connectors-models';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { injectable, inject, optional } from 'inversify';
+import { EngineCapability, EngineCapabilityResolutionMode, ENGINE_CAPABILITIES_REQUIRING_A_PROVIDER_WHEN_ENABLED, getEngineCapabilityResolutionMode, PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY, } from '@wildo-ai/saas-models';
+import { ExternalProvider_ExchangeProtocol_Kind, LLMProvider_OperationKey, DocumentExtractionProvider_OperationKey, EmbeddingsProvider_OperationKey, APPLICATION_ENVIRONMENT, ProviderProtocolRuntimeKind, ExternalProvider_SecretScope, } from '@wildo-ai/external-connectors-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { ProviderCredentialResolutionSource } from '@wildo-ai/saas-models';
+import { ExternalProvider_Connection_DelegationMode, ExternalProvider_Connection_OwnerScope, } from '@wildo-ai/external-connectors-models';
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
 import { describeCaughtError } from '../../errors/utils/error-log-level-classification.backend.utils.js';
 import { ErrorType, ErrorCustomMessageReference, isWildoBackendError } from '@wildo-ai/saas-models';
@@ -72,19 +76,46 @@ const RUNTIME_EMBEDDINGS_OPERATION_TO_SEMANTIC_OPERATION = {
 const RUNTIME_DOCUMENT_EXTRACTION_OPERATION_TO_SEMANTIC_OPERATION = {
     extractDocumentText: DocumentExtractionProvider_OperationKey.EXTRACT_DOCUMENT_TEXT,
 };
+/**
+ * What a provider admits when NOBODY HAS JUDGED IT — the SAFETY NET, not the answer.
+ *
+ * Named and stated once because it was previously an anonymous literal inlined at two call sites,
+ * and a value that applies to most of the catalogue should be readable as the decision it is.
+ *
+ * ONE row, and it is the conservative end deliberately. APPLICATION x SERVICE is the deployment's
+ * own credential, authored in the environment by the operator — the only claim that needs no
+ * knowledge of the vendor whatsoever.
+ *
+ * It was briefly widened to include ORGANIZATION x SERVICE, with a careful argument that a tenant
+ * bringing its own key is a fact about Wildo's tenancy model rather than about any vendor. The
+ * argument holds and the change was still wrong: it made a blanket rule decide for 688 vendors at
+ * once, which is precisely the per-vendor judgement this framework refuses to shortcut. A default
+ * that carries the whole catalogue is not a fallback — it is mass management with a justification
+ * attached, and the justification is what makes it hard to notice.
+ *
+ * So a provider earns every row beyond this one by somebody ANALYSING it and recording why, as
+ * `providers/catalogue-record/decisions/slack.json` does. The population that needs that judgement
+ * is far smaller than the catalogue: 99 of the 689 transposed vendors declare an OAuth2 contract,
+ * and only those have a connection flow to admit anybody to.
+ */
+const UNJUDGED_PROVIDER_ADMISSIBLE_CONNECTIONS = [
+    { ownerScope: ExternalProvider_Connection_OwnerScope.APPLICATION, delegation: ExternalProvider_Connection_DelegationMode.SERVICE },
+];
 let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBackendService {
     logger;
     configService;
     errorBuilder;
     backendProviderRegistry;
+    container;
     logDebug;
     registry = null;
     isInitialized = false;
-    constructor(logger, configService, errorBuilder, backendProviderRegistry) {
+    constructor(logger, configService, errorBuilder, backendProviderRegistry, container) {
         this.logger = logger;
         this.configService = configService;
         this.errorBuilder = errorBuilder;
         this.backendProviderRegistry = backendProviderRegistry;
+        this.container = container;
         this.logDebug = this.logger.debugByType('ExternalProvidersRegistryBackendService');
         this.logger.setDebugTypeLogging('ExternalProvidersRegistryBackendService', false);
         this.logDebug('External providers registry service created (not yet initialized)');
@@ -105,12 +136,72 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             await this.configService.initialize();
         }
         const registry = this.buildRuntimeRegistryFromProviderModules();
+        this.reportMissingProviderRuntimePeers();
         this.registry = registry;
         this.isInitialized = true;
         this.logDebug('External providers registry initialized from backend provider modules', {
             totalProviders: Object.keys(registry).length,
         });
     }
+    /**
+     * Report a registered provider whose optional runtime peer is not installed (#438).
+     *
+     * `requiredPackages` declares the npm packages a provider LAZY-LOADS — a vendor SDK that is
+     * never an engine or application dependency, installed only in a runtime that enables the
+     * provider. Two providers declare it (immudb -> `immudb-node`, posthog -> `posthog-node`), and
+     * until 2026-09-08 the field had NO READER anywhere: no start-up check, no installation step,
+     * no diagnostic. A provider could be registered with its SDK absent and the first sign was the
+     * feature quietly not working.
+     *
+     * A REPORT, never a refusal, and the asymmetry is deliberate: a declared provider may
+     * legitimately never be reached (a fan-out audit sink in an environment that emits nothing),
+     * so an absent optional peer is information rather than a misconfiguration. The capability
+     * DISAGREEMENT check in `define-saas-config` refuses, because a wrong declaration is wrong
+     * whatever happens next.
+     *
+     * Resolution is attempted from the RUNNING APPLICATION first and from this module second. The
+     * peer is installed in the application's own `backend-api`, not in the engine package, so
+     * resolving only from here would report a false absence — and a diagnostic that cries wolf is
+     * worse than the silence it replaces.
+     */
+    reportMissingProviderRuntimePeers() {
+        const resolvers = [
+            (() => { try {
+                return createRequire(join(process.cwd(), 'package.json'));
+            }
+            catch {
+                return undefined;
+            } })(),
+            (() => { try {
+                return createRequire(import.meta.url);
+            }
+            catch {
+                return undefined;
+            } })(),
+        ].filter((resolver) => Boolean(resolver));
+        const isResolvable = (packageName) => resolvers.some((resolver) => {
+            try {
+                resolver.resolve(packageName);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const provider of this.backendProviderRegistry.getRegistry().modules.values()) {
+            const declaredPackages = provider.requiredPackages ?? [];
+            const missing = declaredPackages.filter((packageName) => !isResolvable(packageName));
+            if (missing.length === 0) {
+                continue;
+            }
+            this.logger.warn('Provider is registered without its declared optional runtime peer(s)', {
+                providerRef: provider.metadata.ref,
+                missingPackages: missing,
+                detail: 'The provider lazy-loads these and degrades without them, so the capability it serves will not work. '
+                    + 'Install them in the runtime that enables this provider, or stop declaring the provider in that scope.',
+            });
+        }
+    }
     buildRuntimeRegistryFromProviderModules() {
         const registry = {};
         for (const provider of this.backendProviderRegistry.getRegistry().modules.values()) {
@@ -187,7 +278,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
                 && (selection?.engineCapabilities ?? []).includes(capability);
         });
         // A FAN_OUT capability ignores any `selection` policy: every declared
-        // provider is active, so primary/fallback ordering is meaningless (and the
+        // provider is active, so primary/substitute ordering is meaningless (and the
         // config validator rejects authoring one). Guarding here is defense-in-
         // depth — a stray selection on a fan-out cap from a legacy/hand-authored
         // artifact never reorders or truncates the fan-out set.
@@ -204,7 +295,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             ? undefined
             : selectionForCapability;
         if (policy) {
-            const orderedPolicyRefs = [policy.primary, ...(policy.fallbacks ?? [])]
+            const orderedPolicyRefs = [policy.primary, ...(policy.whenUnavailable ?? [])]
                 .filter((providerRef) => availableProviders.includes(providerRef));
             const remainingRefs = availableProviders.filter((providerRef) => !orderedPolicyRefs.includes(providerRef));
             return [...orderedPolicyRefs, ...remainingRefs];
@@ -222,7 +313,10 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
      * Resolve the provider ref(s) that should be ACTIVE for a capability,
      * honouring its declared `EngineCapabilityResolutionMode`:
      *   - `SELECT_ONE` (the default — billing, email, observability, …): the
-     *     single primary (fallbacks tried on failure), as a 0- or 1-element list.
+     *     single primary, as a 0- or 1-element list. A declared `whenUnavailable` entry
+     *     only orders the candidate list ahead of this call — it substitutes for a
+     *     primary that is not AVAILABLE, and nothing tries a second provider when a
+     *     call to the first one FAILS.
      *   - `FAN_OUT` (e.g. `COMPLIANCE_AUDIT_TRAIL`): EVERY declared + available
      *     provider — all active simultaneously (no primary, no failover).
      *
@@ -270,25 +364,63 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
      * Audit (`COMPLIANCE_AUDIT_TRAIL`, when marked required) is the FIRST user, not
      * a special case: this generalizes the coherence to EVERY capability.
      */
-    getRequiredCapabilitiesWithoutProvider() {
+    getRequiredCapabilitiesWithoutProvider(options = { includeEngineFloor: true }) {
         this.ensureInitialized();
         if (!this.configService.isInitialized()) {
-            return [];
+            // Used to answer `[]` here, which read as "nothing missing" on a host whose config
+            // had never loaded — a floor that cannot see its inputs must refuse, not reassure.
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'The required-capability floor was evaluated before the application configuration '
+                        + 'was initialized; it cannot decide what is required.',
+                },
+            });
         }
         const activations = this.configService.config.engineCapabilities ?? {};
         const missing = [];
-        for (const capability of Object.keys(activations)) {
-            if (activations[capability]?.required === true
+        // Swept over the ENUM, not over the authored keys (#328), so the population and its order
+        // are the engine's. Requiredness itself always needs an activation entry — an absent key is
+        // neither `enabled` nor `required` — so this is about which list is authoritative, not about
+        // catching an omitted key.
+        for (const capability of Object.values(EngineCapability)) {
+            const activation = activations[capability];
+            const requiredByApplication = activation?.required === true;
+            const requiredByEngine = options.includeEngineFloor
+                && activation?.enabled === true
+                && ENGINE_CAPABILITIES_REQUIRING_A_PROVIDER_WHEN_ENABLED.has(capability);
+            if ((requiredByApplication || requiredByEngine)
                 && this.getResolvedProviderRefsForCapability(capability).length === 0) {
                 missing.push(capability);
             }
         }
         return missing;
     }
+    /**
+     * The floor as a single fail-closed door (#328): every host that serves the application
+     * calls this after its registry is ready — the application backend, and the platform
+     * services after `refreshFromConfig()` — so "required with nothing serving it" cannot pass
+     * one host's boot because the check happened to live on another's branch.
+     */
+    assertRequiredCapabilityFloor(options) {
+        const missingRequiredCapabilities = this.getRequiredCapabilitiesWithoutProvider(options);
+        if (missingRequiredCapabilities.length === 0)
+            return;
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+                message: `Required engine capabilities resolve no active provider: [${missingRequiredCapabilities.join(', ')}]. `
+                    + 'Each is either marked `required` in engineCapabilities or is an engine flow that needs a provider '
+                    + 'the moment it is enabled (EMAIL_TRANSACTIONAL, BILLING, SMS) — declare a provider for it '
+                    + '(SELECT_ONE needs a primary; FAN_OUT needs ≥1 declared), or disable the capability.',
+                missingRequiredCapabilities,
+            },
+        });
+    }
     /**
      * Per-environment external-provider selection override, read once from
      * `process.env.WILDO_PROVIDER_SELECTION_OVERRIDES` (a JSON map of
-     * `EngineCapability -> { primary, fallbacks? }`). Projected by the Wildo
+     * `EngineCapability -> { primary, whenUnavailable? }`). Projected by the Wildo
      * CLI's `env-vars-builder` from `wildo.infra.<env>.config.ts > providerSelection`.
      * Read as a string literal (not via a `platform-config-lib` import) to
      * preserve the engine → platform dependency direction — mirrors how
@@ -335,8 +467,8 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             return undefined;
         if (typeof override.primary !== 'string'
             || override.primary.length === 0
-            || (override.fallbacks !== undefined && (!Array.isArray(override.fallbacks)
-                || !override.fallbacks.every((fallback) => typeof fallback === 'string' && fallback.length > 0)))) {
+            || (override.whenUnavailable !== undefined && (!Array.isArray(override.whenUnavailable)
+                || !override.whenUnavailable.every((substitute) => typeof substitute === 'string' && substitute.length > 0)))) {
             this.malformedProviderSelectionOverrides.add(capability);
             return undefined;
         }
@@ -364,9 +496,9 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
                     ? ExternalProviderSelectionOverrideStatus.APPLIED
                     : ExternalProviderSelectionOverrideStatus.ABSENT,
             applicationPrimaryProviderRef: runtimeSelection?.primary ?? null,
-            applicationFallbackProviderRefs: Object.freeze([...(runtimeSelection?.fallbacks ?? [])]),
+            applicationSubstituteProviderRefs: Object.freeze([...(runtimeSelection?.whenUnavailable ?? [])]),
             environmentPrimaryProviderRef: environmentSelection?.primary ?? null,
-            environmentFallbackProviderRefs: Object.freeze([...(environmentSelection?.fallbacks ?? [])]),
+            environmentSubstituteProviderRefs: Object.freeze([...(environmentSelection?.whenUnavailable ?? [])]),
             providerRuntimeArtifact: this.configService.getProviderRuntimeArtifactEvidenceMetadata(),
         });
     }
@@ -519,12 +651,66 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
         }
         return merged;
     }
+    /**
+     * WHAT a declared secret identifies — the integration, or an account.
+     *
+     * DECLARED wins; otherwise DERIVED, and the derivation is deliberately narrow. A ref the REST
+     * runtime contract names as the OAuth2 client id or client secret is a REGISTRATION. Everything
+     * else answers CREDENTIAL.
+     *
+     * The fallback exists because the field arrived after 689 provider packages had been emitted,
+     * from catalogues that live outside this repository — a mark that only worked once every package
+     * had been re-emitted would enforce nothing until then, which for a guard is the same as not
+     * existing.
+     *
+     * It is a FLOOR, not a complete answer, and the direction of its error matters. Deriving
+     * CREDENTIAL for a registration secret the contract does not name in those two slots is the
+     * permissive mistake: such a secret would still be storable as a tenant's own. That is exactly
+     * the case a provider must declare explicitly, and it is why `scope` is authorable at all rather
+     * than purely computed.
+     */
+    getProviderSecretScope(providerRef, secretRef) {
+        const entry = this.findSecretsContractEntry(providerRef, secretRef);
+        if (entry?.scope !== undefined) {
+            return entry.scope;
+        }
+        // Compare on the ENV-VAR NAME, not on the ref as supplied. A ref may arrive as either the
+        // authoring slug (`accessToken`) or the env-var name (`SLACK_API_KEY`), while a runtime
+        // contract only ever references the latter — so deriving from the raw ref answered CREDENTIAL
+        // for `clientSecret` and REGISTRATION for `SLACK_CLIENT_SECRET`, two names for one secret.
+        const comparableRef = entry?.envVarName ?? secretRef;
+        const contract = this.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);
+        const oauth2 = contract?.kind === ProviderProtocolRuntimeKind.REST ? contract.oauth2 : undefined;
+        const namesRegistration = oauth2 !== undefined
+            && (oauth2.clientIdSecretRef === comparableRef || oauth2.clientSecretSecretRef === comparableRef);
+        return namesRegistration
+            ? ExternalProvider_SecretScope.REGISTRATION
+            : ExternalProvider_SecretScope.CREDENTIAL;
+    }
+    /**
+     * The contract entry for a ref, found by ENV-VAR NAME or by SLUG.
+     *
+     * Both are real addresses for the same thing and callers use both: the map key is the authoring
+     * slug (`accessToken`), while runtime contracts reference the env-var name (`SLACK_API_KEY`).
+     * Matching only one would leave half the callers unable to find an entry that is plainly there.
+     */
+    findSecretsContractEntry(providerRef, secretRef) {
+        const contract = this.backendProviderRegistry.getProvider(providerRef)?.secretsContract;
+        if (contract === undefined) {
+            return undefined;
+        }
+        const bySlug = contract[secretRef];
+        if (bySlug !== undefined) {
+            return bySlug;
+        }
+        return Object.values(contract).find((entry) => entry.envVarName === secretRef);
+    }
     getProviderRuntimeContract(providerRef, protocolKind) {
         return this.getProviderConfiguration(providerRef, protocolKind)?.runtimeContract;
     }
     getLLMSemanticOperationKeys(providerRef) {
         const runtimeContract = this.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
-        if (runtimeContract?.kind !== 'llm') {
+        if (runtimeContract?.kind !== ProviderProtocolRuntimeKind.LLM) {
             return [];
         }
         return this.toSemanticOperationKeys(runtimeContract.operations);
@@ -537,7 +723,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
      */
     getEmbeddingsSemanticOperationKeys(providerRef) {
         const runtimeContract = this.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.EMBEDDINGS_PROVIDER);
-        if (runtimeContract?.kind !== 'embeddings') {
+        if (runtimeContract?.kind !== ProviderProtocolRuntimeKind.EMBEDDINGS) {
             return [];
         }
         return runtimeContract.operations
@@ -553,7 +739,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
      */
     getDocumentExtractionSemanticOperationKeys(providerRef) {
         const runtimeContract = this.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.DOCUMENT_EXTRACTION_PROVIDER);
-        if (runtimeContract?.kind !== 'document-extraction') {
+        if (runtimeContract?.kind !== ProviderProtocolRuntimeKind.DOCUMENT_EXTRACTION) {
             return [];
         }
         return runtimeContract.operations
@@ -566,7 +752,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
     }
     getAgentClientProtocolProfile(providerRef) {
         const runtimeContract = this.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL);
-        if (runtimeContract?.kind !== 'agent-client-protocol') {
+        if (runtimeContract?.kind !== ProviderProtocolRuntimeKind.AGENT_CLIENT_PROTOCOL) {
             return undefined;
         }
         const supportedModels = [
@@ -585,6 +771,22 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             ...(runtimeContract.sessionMetaExtensionsByHostConfigurationInheritance
                 ? { sessionMetaExtensionsByHostConfigurationInheritance: runtimeContract.sessionMetaExtensionsByHostConfigurationInheritance }
                 : {}),
+            ...(runtimeContract.modelDelivery ? { modelDelivery: runtimeContract.modelDelivery } : {}),
+            ...(runtimeContract.modelTransportIds
+                ? { modelTransportIds: { ...runtimeContract.modelTransportIds } }
+                : {}),
+            ...(runtimeContract.inheritedEnvironmentVariables
+                ? { inheritedEnvironmentVariables: [...runtimeContract.inheritedEnvironmentVariables] }
+                : {}),
+            // Normalised to the AUTHORED vocabulary: the contract spells these
+            // with hyphens and the profile enum with underscores, and comparing
+            // the two spellings directly is a guard that never fires.
+            supportedAuthModes: runtimeContract.authModes.map((mode) => mode.replace(/-/g, '_')),
+            ...(runtimeContract.sessionModeIdsByPermissionCeiling
+                ? {
+                    sessionModeIdsByPermissionCeiling: Object.fromEntries(Object.entries(runtimeContract.sessionModeIdsByPermissionCeiling).map(([ceiling, modeIds]) => [ceiling, [...(modeIds ?? [])]])),
+                }
+                : {}),
         };
     }
     /**
@@ -649,7 +851,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
                 this.logDebug(`Runtime contract not found: ${providerRef}:${protocolKind}`);
                 return undefined;
             }
-            if (runtimeContract.kind === 'agent-client-protocol') {
+            if (runtimeContract.kind === ProviderProtocolRuntimeKind.AGENT_CLIENT_PROTOCOL) {
                 const defaultExecutionProfileRef = 'default';
                 const hasExplicitSecretBinding = Boolean(runtimeContract.secretRef
                     && runtimeContract.secretEnvVarName
@@ -703,7 +905,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
                         },
                     }
                     : {}),
-                ...(runtimeContract.kind === 'webhook-originator'
+                ...(runtimeContract.kind === ProviderProtocolRuntimeKind.WEBHOOK_ORIGINATOR
                     ? { endpoints: this.buildWebhookEndpoints(runtimeContract) }
                     : {}),
                 runtimeContract,
@@ -726,31 +928,31 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
     }
     secretRefForRuntimeContract(runtimeContract) {
         switch (runtimeContract.kind) {
-            case 'email':
+            case ProviderProtocolRuntimeKind.EMAIL:
                 // A `delivery: 'log'` email contract (the dev `preview`
                 // provider) has NO endpoint and NO apiKey — it renders +
                 // logs instead of sending. No secretRef to resolve; the
                 // caller emits no `authConfig` and the email service skips
                 // the API-key requirement. Contract-driven, not ref-keyed.
                 return runtimeContract.delivery === 'log' ? undefined : runtimeContract.apiKey.secretRef;
-            case 'llm':
+            case ProviderProtocolRuntimeKind.LLM:
                 return runtimeContract.apiKey.secretRef;
-            case 'image':
+            case ProviderProtocolRuntimeKind.IMAGE:
                 return runtimeContract.apiKey.secretRef;
-            case 'embeddings':
+            case ProviderProtocolRuntimeKind.EMBEDDINGS:
                 return runtimeContract.apiKey.secretRef;
-            case 'document-extraction':
+            case ProviderProtocolRuntimeKind.DOCUMENT_EXTRACTION:
                 return runtimeContract.apiKey.secretRef;
-            case 'oauth2-sso':
+            case ProviderProtocolRuntimeKind.OAUTH2_SSO:
                 return runtimeContract.clientSecretRef;
-            case 'billing':
-            case 'webhook-originator':
+            case ProviderProtocolRuntimeKind.BILLING:
+            case ProviderProtocolRuntimeKind.WEBHOOK_ORIGINATOR:
                 return runtimeContract.secretRef;
-            case 'sms':
+            case ProviderProtocolRuntimeKind.SMS:
                 return runtimeContract.auth.secretRef;
-            case 'rest':
+            case ProviderProtocolRuntimeKind.REST:
                 return runtimeContract.apiKey.secretRef;
-            case 'agent-client-protocol':
+            case ProviderProtocolRuntimeKind.AGENT_CLIENT_PROTOCOL:
                 // An ACP agent that needs a credential carries it on the
                 // contract; a host-managed one (the default for a coding agent
                 // running under an operator's own login) carries none.
@@ -787,25 +989,25 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
      */
     authKindForRuntimeContract(runtimeContract) {
         switch (runtimeContract.kind) {
-            case 'llm':
-            case 'image':
-            case 'embeddings':
+            case ProviderProtocolRuntimeKind.LLM:
+            case ProviderProtocolRuntimeKind.IMAGE:
+            case ProviderProtocolRuntimeKind.EMBEDDINGS:
             // Document extraction authenticates with an opaque API key in a request header, like
             // its siblings above; the header SHAPE (name/prefix) stays on the contract because
             // this family builds its own HTTPS request rather than handing a key to an SDK.
-            case 'document-extraction':
-            case 'email':
-            case 'sms':
-            case 'billing':
+            case ProviderProtocolRuntimeKind.DOCUMENT_EXTRACTION:
+            case ProviderProtocolRuntimeKind.EMAIL:
+            case ProviderProtocolRuntimeKind.SMS:
+            case ProviderProtocolRuntimeKind.BILLING:
             // `rest` authenticates with an opaque API key supplied via env var, like its siblings
             // above; the header SHAPE (name/prefix) stays on the contract for its consumer.
-            case 'rest':
+            case ProviderProtocolRuntimeKind.REST:
                 return ExternalProvider_Auth_Kind.API_KEY;
-            case 'webhook-originator':
+            case ProviderProtocolRuntimeKind.WEBHOOK_ORIGINATOR:
                 return ExternalProvider_Auth_Kind.HMAC_SIGNATURE;
-            case 'oauth2-sso':
+            case ProviderProtocolRuntimeKind.OAUTH2_SSO:
                 return ExternalProvider_Auth_Kind.OAUTH2;
-            case 'agent-client-protocol':
+            case ProviderProtocolRuntimeKind.AGENT_CLIENT_PROTOCOL:
                 throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
                     customMessageReference: ErrorCustomMessageReference.EXTERNAL_PROVIDER_REGISTRY_INITIALIZATION_FAILED,
                     context: {
@@ -923,6 +1125,296 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             return undefined;
         }
     }
+    /**
+     * WHICH connections this provider admits — the recorded decision, or the FLOOR.
+     *
+     * The floor is an APPLICATION-owned, undelegated connection and nothing else, and it is what a
+     * provider that has recorded no decision gets. It is not a permissive default: it is the one
+     * answer always available (an operator can author an environment variable) and the one that
+     * cannot produce a cross-tenant mistake (it has exactly one instance).
+     *
+     * Never derived here from a provider's auth shape. Whether a vendor can be connected per tenant
+     * is a fact about that vendor's product and about what somebody verified — see the catalogue
+     * record for a generated provider, or the module itself for a hand-authored one.
+     */
+    getProviderAdmissibleConnections(providerRef) {
+        const declared = this.backendProviderRegistry.getProvider(providerRef)?.admissibleConnections;
+        const catalogue = declared === undefined || declared.length === 0
+            ? UNJUDGED_PROVIDER_ADMISSIBLE_CONNECTIONS
+            : declared;
+        return this.narrowToApplicationConnectionPolicy(providerRef, catalogue);
+    }
+    /**
+     * What the VENDOR admits, before this application's policy narrows it.
+     *
+     * Exists so a refusal can name the right cause. Once a policy can subtract, "this provider does
+     * not admit that connection" has two meanings — nobody recorded the vendor's capability, or this
+     * application switched it off — and they are repaired in different files by different people.
+     * A diagnostic that always blamed the catalogue would send an operator to edit a decision record
+     * that is already correct.
+     */
+    getProviderCatalogueAdmissibleConnections(providerRef) {
+        const declared = this.backendProviderRegistry.getProvider(providerRef)?.admissibleConnections;
+        return declared === undefined || declared.length === 0
+            ? UNJUDGED_PROVIDER_ADMISSIBLE_CONNECTIONS
+            : declared;
+    }
+    /**
+     * Intersect what the VENDOR admits with what THIS application permits.
+     *
+     * Two layers answering different questions, and the intersection is what makes them composable:
+     * the catalogue record says an organization-owned Slack connection is possible because Slack is
+     * installed per workspace, while `providers.connections.slack` says whether this product offers
+     * one. A vendor opening a capability and a product deciding to use it are different events, and
+     * a single list would make them look identical.
+     *
+     * NARROWING ONLY, and that direction is the guarantee rather than a convention. An application
+     * cannot declare a connection the vendor does not support into existence — the connect leg would
+     * build an authorize URL the vendor rejects, or store a grant nothing can spend — so a policy
+     * entry naming an unadmitted shape contributes nothing instead of granting it.
+     *
+     * An ABSENT policy means "everything the catalogue admits", never "nothing". Most applications
+     * will never author one, and reading their silence as a refusal would switch off the whole
+     * connect surface for every product that has not yet thought about it.
+     *
+     * An intersection that empties is a legitimate outcome, not a misconfiguration: it is how an
+     * application switches a provider's connect surface off without removing the provider, which it
+     * may still need for its own application-scope credential.
+     */
+    narrowToApplicationConnectionPolicy(providerRef, catalogue) {
+        const permitted = this.configService.config.providers?.connections?.[providerRef]?.admissible;
+        if (permitted === undefined) {
+            return catalogue;
+        }
+        return catalogue.filter((shape) => permitted.some((allowed) => allowed.ownerScope === shape.ownerScope && allowed.delegation === shape.delegation));
+    }
+    /**
+     * One provider secret for ONE connection target — strictly, with no substitution.
+     *
+     * ## Why this exists beside `resolveProviderSecretForOrganization` rather than extending it
+     *
+     * That method FALLS BACK: an organization with no credential of its own silently spends the
+     * deployment's. This one does not, and the difference is not a tightening of the same idea —
+     * it is the opposite policy. A fallback means the vendor sees the application's identity while
+     * the application believes it acted as the tenant, so every artifact the call leaves behind —
+     * a message, a record, a line in the vendor's own audit log — is attributed to the wrong party,
+     * and nothing downstream can detect it.
+     *
+     * An application that wants "the tenant's key when they have connected one, otherwise ours"
+     * still has it: it names an APPLICATION target for that usage, in its own code, where the
+     * choice is visible. What is removed is the engine performing the swap underneath a call that
+     * asked for a tenant.
+     *
+     * `resolveProviderSecretForOrganization` is superseded and is removed once its remaining
+     * consumers move; it is left standing only because its test currently carries another session's
+     * uncommitted work.
+     */
+    async resolveProviderSecretForTarget(target, providerRef, protocolKind, secretRef) {
+        this.ensureInitialized();
+        if (target.delegation === ExternalProvider_Connection_DelegationMode.USER) {
+            throw this.buildConnectionRefusal(providerRef, `a call delegated to user '${target.actingForUserId}' cannot be resolved: no outbound per-principal token store exists yet. `
+                + 'Declare an undelegated target, or build the delegated-token subsystem (#333).');
+        }
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {
+            // An envelope failure is NOT caught here, deliberately, for the organization branch's
+            // reason: a person who HAS a credential which cannot be opened must refuse loudly rather
+            // than be treated as a person who has none. The two are indistinguishable to a caller
+            // and only one of them is a safe thing to continue from.
+            const userResolver = this.resolveUserCredentialResolver();
+            if (!userResolver) {
+                throw this.buildConnectionRefusal(providerRef, 'no user credential store is bound, so a person-owned connection cannot be read at all. '
+                    + 'This is a wiring fault rather than a missing credential.');
+            }
+            const ownedByUser = await userResolver.resolveUserCredential({
+                userId: target.ownerId,
+                providerRef,
+                secretSlug: secretRef,
+            });
+            if (!ownedByUser) {
+                throw this.buildConnectionRefusal(providerRef, `user '${target.ownerId}' has not connected '${secretRef}'. It is not substituted with the `
+                    + "deployment's or their organization's: the call asked to act as this person, and acting as "
+                    + 'anyone else would put the wrong name on the record the provider keeps.');
+            }
+            return {
+                value: ownedByUser.value,
+                source: ProviderCredentialResolutionSource.USER_CREDENTIAL,
+                credentialId: ownedByUser.credentialId,
+            };
+        }
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION) {
+            const fromEnvironment = this.getProviderSecret(providerRef, protocolKind, secretRef);
+            if (fromEnvironment) {
+                return { value: fromEnvironment, source: ProviderCredentialResolutionSource.DEPLOYMENT_ENVIRONMENT };
+            }
+            const environmentVariableName = this.getProviderSecretEnvVarName(providerRef, protocolKind, secretRef) ?? secretRef;
+            throw this.buildConnectionRefusal(providerRef, `the application's own credential for '${secretRef}' is not set. Author '${environmentVariableName}' in the deployment environment.`);
+        }
+        // ORGANIZATION. An envelope failure is NOT caught, deliberately: a tenant that HAS a
+        // credential which cannot be opened must refuse loudly rather than be treated as a tenant
+        // that has none — the two are indistinguishable to a caller and only one is safe.
+        const resolver = this.resolveOrganizationCredentialResolver();
+        if (!resolver) {
+            throw this.buildConnectionRefusal(providerRef, 'no organization credential store is bound, so a tenant-owned connection cannot be read at all. '
+                + 'This is a wiring fault rather than a missing credential.');
+        }
+        const owned = await resolver.resolveOrganizationCredential({
+            organizationId: target.ownerId,
+            providerRef,
+            secretSlug: secretRef,
+        });
+        if (!owned) {
+            throw this.buildConnectionRefusal(providerRef, `organization '${target.ownerId}' has no credential for '${secretRef}'. It is not substituted with the deployment's: `
+                + 'the call asked to act as this tenant, and acting as someone else instead would be attributed to the wrong party.');
+        }
+        return {
+            value: owned.value,
+            source: ProviderCredentialResolutionSource.ORGANIZATION_CREDENTIAL,
+            credentialId: owned.credentialId,
+        };
+    }
+    /** One shape for every connection refusal, so an operator reads the same sentence everywhere. */
+    buildConnectionRefusal(providerRef, detail) {
+        return new Error(`Provider '${providerRef}': ${detail}`);
+    }
+    // ══════════════════════════════════════════════════════════════════════════════════════════
+    // PER-ORGANIZATION SECRET RESOLUTION (#357)
+    //
+    // ## Why these are separate methods and not a change to `getProviderSecret`
+    //
+    // `getProviderSecret` is synchronous, and six consumers across four other workstreams' files
+    // call it that way. A per-organization credential lives in the database, so resolving one is
+    // necessarily asynchronous — making the existing method async would reshape every one of those
+    // call sites at once, in files this slice may not touch. So the environment path stays exactly
+    // as it was, and the tenant-aware path is added beside it.
+    //
+    // This is a seam, not a duplication: the async path CALLS `getProviderSecret` for its second
+    // step, so there remains exactly one implementation of "what does the environment say".
+    //
+    // ## The ORDER, and why the third step is a throw
+    //
+    //   1. the organization's OWN credential
+    //   2. the deployment's env-projected `SecretsContract`
+    //   3. refuse, BY NAME
+    //
+    // Step 3 is the one that matters. Before this existed, an unresolvable secret returned
+    // `undefined`, and every caller then decided for itself what that meant — several of them by
+    // passing it onward, so a vendor received an empty Authorization header and answered 401. A 401
+    // from a vendor is indistinguishable from a revoked credential, so the real fault (nobody ever
+    // configured one) was invisible. Naming both places that were checked turns that into a
+    // sentence an operator can act on.
+    //
+    // assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — resolving which principal this
+    // application acts as toward a third party, per tenant.
+    // ══════════════════════════════════════════════════════════════════════════════════════════
+    /**
+     * Lazy getter for the per-organization credential store — see the `container` constructor
+     * param's JSDoc for why this cannot be a constructor injection.
+     *
+     * `isBound` is what preserves the old `@optional()` semantics: a host that binds no store
+     * (a minion, a unit harness) resolves nothing here and falls through to the deployment
+     * environment, exactly as it did before the store existed.
+     */
+    resolveOrganizationCredentialResolver() {
+        if (!this.container?.isBound(SAAS_SERVICE_TYPES.OrganizationProviderCredentialResolver))
+            return undefined;
+        return this.container.get(SAAS_SERVICE_TYPES.OrganizationProviderCredentialResolver);
+    }
+    /**
+     * Lazy getter for the per-user credential store — same mechanics as the organization one above,
+     * and the OPPOSITE meaning when it resolves nothing.
+     *
+     * An unbound organization store falls through to the deployment environment, because a tenant
+     * legitimately may not have its own credential. An unbound USER store REFUSES, because there is
+     * nothing a person's credential could fall through to: spending the deployment's shared
+     * principal on someone's behalf would attribute the act to the wrong party at the vendor. So a
+     * host that forgot to bind this gets a refusal naming the wiring fault, never a silent
+     * substitution.
+     */
+    resolveUserCredentialResolver() {
+        if (!this.container?.isBound(SAAS_SERVICE_TYPES.UserProviderCredentialResolver))
+            return undefined;
+        return this.container.get(SAAS_SERVICE_TYPES.UserProviderCredentialResolver);
+    }
+    /**
+     * Resolve one provider secret FOR A TENANT, or refuse naming what is missing.
+     *
+     * @param organizationId the tenant on whose behalf the call will be made. Must come from a
+     *   trusted execution scope — this method cannot verify it, and the envelope binding is what
+     *   keeps a mistake here from becoming a cross-tenant disclosure.
+     */
+    async resolveProviderSecretForOrganization(organizationId, providerRef, protocolKind, secretRef) {
+        this.ensureInitialized();
+        // ── 1. the organization's own credential ────────────────────────────────────────────────
+        //
+        // An envelope failure is deliberately NOT caught. A tenant that HAS a credential which
+        // cannot be opened must not quietly fall through to the deployment's shared one: that
+        // substitution is exactly the silent cross-principal action this resource exists to remove,
+        // and it would present to the operator as "the integration works" while the wrong identity
+        // is on the wire.
+        const organizationCredentialResolver = this.resolveOrganizationCredentialResolver();
+        if (organizationCredentialResolver) {
+            const owned = await organizationCredentialResolver.resolveOrganizationCredential({
+                organizationId,
+                providerRef,
+                secretSlug: secretRef,
+            });
+            if (owned) {
+                return {
+                    value: owned.value,
+                    source: ProviderCredentialResolutionSource.ORGANIZATION_CREDENTIAL,
+                    credentialId: owned.credentialId,
+                };
+            }
+        }
+        // ── 2. the deployment environment ───────────────────────────────────────────────────────
+        const fromEnvironment = this.getProviderSecret(providerRef, protocolKind, secretRef);
+        if (fromEnvironment) {
+            return { value: fromEnvironment, source: ProviderCredentialResolutionSource.DEPLOYMENT_ENVIRONMENT };
+        }
+        // ── 3. refuse, by name ──────────────────────────────────────────────────────────────────
+        const environmentVariableName = this.getProviderSecretEnvVarName(providerRef, protocolKind, secretRef) ?? secretRef;
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.EXTERNAL_PROVIDER_REGISTRY_INITIALIZATION_FAILED,
+            context: {
+                message: `No credential resolves for provider '${providerRef}' (protocol '${protocolKind}', secret '${secretRef}') `
+                    + `on behalf of organization '${organizationId}'. Two places were checked and both are empty: the `
+                    + `organization has no provider credential for this slug, and the deployment environment variable `
+                    + `'${environmentVariableName}' is not set. Either the organization's administrator sets its own `
+                    + `credential, or the operator sets that environment variable for every tenant to share.`,
+                providerRef,
+                protocolKind,
+                secretRef,
+                organizationId,
+                environmentVariableName,
+            },
+        });
+    }
+    /**
+     * The tenant-aware sibling of `getProviderApiKey` — the provider's configured `authConfig`
+     * secret, resolved for one organization.
+     *
+     * Refuses rather than returning `undefined` when the provider declares NO `authConfig.secretRef`
+     * at all, because that is a different fault from an unset value and an operator fixing it edits
+     * a different file: the provider module, not the environment.
+     */
+    async resolveProviderApiKeyForOrganization(organizationId, providerRef, protocolKind) {
+        this.ensureInitialized();
+        const secretRef = this.getConfiguredProviderSecretRef(providerRef, protocolKind);
+        if (!secretRef) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.EXTERNAL_PROVIDER_REGISTRY_INITIALIZATION_FAILED,
+                context: {
+                    message: `Provider '${providerRef}' declares no authConfig.secretRef for protocol '${protocolKind}', so there `
+                        + `is no secret to resolve for organization '${organizationId}'. This is a provider-module defect, not `
+                        + 'a deployment one — the module must declare which secret its protocol authenticates with.',
+                    providerRef,
+                    protocolKind,
+                    organizationId,
+                },
+            });
+        }
+        return this.resolveProviderSecretForOrganization(organizationId, providerRef, protocolKind, secretRef);
+    }
     isProviderEnabled(providerRef, protocolKind) {
         this.ensureInitialized();
         try {
@@ -1026,7 +1518,9 @@ ExternalProvidersRegistryBackendService = __decorate([
     __param(1, inject(SAAS_SERVICE_TYPES.AppConfigService)),
     __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
     __param(3, inject(SAAS_SERVICE_TYPES.BackendProviderRegistryService)),
-    __metadata("design:paramtypes", [Function, Function, ErrorBuilderBackendService, Function])
+    __param(4, inject('Container')),
+    __param(4, optional()),
+    __metadata("design:paramtypes", [Function, Function, ErrorBuilderBackendService, Function, Function])
 ], ExternalProvidersRegistryBackendService);
 export { ExternalProvidersRegistryBackendService };
 //# sourceMappingURL=external-providers-registry.backend.service.js.map