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

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

@@ -144,8 +144,19 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
         });
     }
     /**
+     * @wildo_source:part:start saas.backend.providers.optional-runtime-peers facet:layer:backend facet:audience:app-developer
+     *
      * Report a registered provider whose optional runtime peer is not installed (#438).
      *
+     * **What this means for an application:** a provider may lazy-load a vendor SDK that is not a
+     * dependency of the engine or of your application. Declaring the provider in a scope does not
+     * install it. YOU install it, in the runtime that enables the provider — which is your own
+     * `backend-api`, not the engine package — and if you do not, the capability that provider serves
+     * quietly does not work.
+     *
+     * The startup warning names the provider and the missing packages, so read it as an
+     * installation instruction rather than as noise.
+     *
      * `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
@@ -202,6 +213,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             });
         }
     }
+    /** @wildo_source:part:end saas.backend.providers.optional-runtime-peers */
     buildRuntimeRegistryFromProviderModules() {
         const registry = {};
         for (const provider of this.backendProviderRegistry.getRegistry().modules.values()) {
@@ -669,6 +681,35 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
      * the case a provider must declare explicitly, and it is why `scope` is authorable at all rather
      * than purely computed.
      */
+    /**
+     * A provider's declared secret slots, each classified and each answered as configured or not.
+     *
+     * The contract already says everything a screen needs — the slug, the environment variable, the
+     * operator-facing description, whether it is required — and nothing was reading it. So a person
+     * connecting an account typed a `secretSlug` into a free-text field, and an operator learned that
+     * `ASANA_CLIENT_ID` was missing only when somebody pressed Connect and got a 502.
+     *
+     * NEVER the value, only whether one is present. The whole point is to make a missing secret
+     * REPORTABLE on a screen, and a report that carried the secret would be the one thing that must
+     * not leave the backend.
+     *
+     * Scope comes from {@link getProviderSecretScope}, so this and the connect leg's refusal cannot
+     * disagree about which slot is a registration and which is an account.
+     */
+    getProviderSecretSlots(providerRef) {
+        const contract = this.backendProviderRegistry.getProvider(providerRef)?.secretsContract;
+        if (contract === undefined)
+            return [];
+        return Object.entries(contract).map(([slug, entry]) => ({
+            slug,
+            envVarName: entry.envVarName,
+            required: entry.required,
+            description: entry.description,
+            scope: this.getProviderSecretScope(providerRef, slug),
+            configured: Boolean(this.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, entry.envVarName)
+                ?? this.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, slug)),
+        }));
+    }
     getProviderSecretScope(providerRef, secretRef) {
         const entry = this.findSecretsContractEntry(providerRef, secretRef);
         if (entry?.scope !== undefined) {
@@ -1272,6 +1313,79 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             credentialId: owned.credentialId,
         };
     }
+    /**
+     * Record that the credential {@link resolveProviderSecretForTarget} just handed out was SPENT,
+     * and what the provider thought of it.
+     *
+     * ## Why the recording lives HERE, beside the resolution
+     *
+     * Because the two must never disagree about which store they are talking about. This method
+     * dispatches on `target.ownerScope` in exactly the same order and by exactly the same rule as
+     * the resolution above, so *the store that was read is the store that is stamped* is a property
+     * of one function rather than an agreement between two.
+     *
+     * The alternative — the caller routing for itself — was tried and is the defect this replaces.
+     * The provider-operation executor held a thunk to A store, typed with an `organizationId` field,
+     * and `target.ownerId` is a USER id whenever `ownerScope` is `USER` (#333's two-axis connection
+     * shape). Wired as it stood, a person-owned call would have stamped a tenant row that does not
+     * exist and emitted an organization audit event naming a user id as the organization. The
+     * caller cannot route this correctly, because the ORDER is this class's knowledge — the same
+     * argument `OrganizationProviderCredentialResolverPort`'s own docstring makes for why the order
+     * does not live on the port.
+     *
+     * ## Fire-and-forget is the CALLER's decision, not this method's
+     *
+     * This returns a promise and lets a store failure reject. The outbound call has already happened
+     * by the time anybody calls this, so the caller must not fail its own request on a bookkeeping
+     * write — but swallowing here would also hide the rejection from the caller's loss counter, and
+     * an observation nobody counts is the shape this whole change exists to remove. The executor
+     * routes it through `emitAuditObservation`, which counts a rejection and never rethrows.
+     *
+     * @param provenance Exactly what {@link resolveProviderSecretForTarget} returned for this call,
+     *   carried through the access resolver. Passing anything else describes a row that was not the
+     *   one spent.
+     */
+    async recordProviderSecretUseForTarget(target, providerRef, provenance, outcome) {
+        if (target.ownerId === undefined) {
+            // An APPLICATION-owned resolution names no owner and has no row. Inventing one would
+            // create a credential the tenant never set, which would then appear on their settings
+            // screen as something they are responsible for rotating.
+            return;
+        }
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {
+            const userResolver = this.resolveUserCredentialResolver();
+            // A person's credential ALWAYS has a row — there is nothing for a person to fall through
+            // to — so an absent id here means the caller did not pass this method the provenance the
+            // resolution produced, and stamping some other row would be worse than stamping none.
+            if (!userResolver || !provenance.credentialId)
+                return;
+            await userResolver.recordCredentialUse({
+                userId: target.ownerId,
+                providerRef,
+                secretSlug: provenance.secretSlug,
+                credentialId: provenance.credentialId,
+                ...(outcome === undefined ? {} : { outcome }),
+            });
+            return;
+        }
+        if (target.ownerScope !== ExternalProvider_Connection_OwnerScope.ORGANIZATION)
+            return;
+        const resolver = this.resolveOrganizationCredentialResolver();
+        if (!resolver)
+            return;
+        // `source` is passed through rather than filtered here: the store emits the use audit for
+        // BOTH sources and stamps a row only for the tenant's own, and that split is its decision to
+        // make. Filtering here would silently drop the audit row for the case a reviewer most wants
+        // — a tenant acting as the shared deployment principal.
+        await resolver.recordCredentialUse({
+            organizationId: target.ownerId,
+            providerRef,
+            secretSlug: provenance.secretSlug,
+            source: provenance.source,
+            ...(provenance.credentialId === undefined ? {} : { credentialId: provenance.credentialId }),
+            ...(outcome === undefined ? {} : { outcome }),
+        });
+    }
     /** One shape for every connection refusal, so an operator reads the same sentence everywhere. */
     buildConnectionRefusal(providerRef, detail) {
         return new Error(`Provider '${providerRef}': ${detail}`);
@@ -1336,8 +1450,44 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
         return this.container.get(SAAS_SERVICE_TYPES.UserProviderCredentialResolver);
     }
     /**
+     * @wildo_source:part:start saas.backend.providers.per-tenant-credential-resolution facet:layer:backend facet:audience:app-developer
+     *
      * Resolve one provider secret FOR A TENANT, or refuse naming what is missing.
      *
+     * Reached as `ExternalProvidersRegistryBackendService` from `@wildo-ai/saas-backend-lib`, through
+     * the container token `SAAS_SERVICE_TYPES.ExternalProvidersRegistryService`.
+     *
+     * ## Why an application reaches for this instead of a provider secret
+     *
+     * A provider's `SecretsContract` names an ENVIRONMENT VARIABLE, so a secret resolved that way is
+     * per-process and per-deployment. One application serving many organizations therefore has ONE
+     * Slack token for all of them — and the failure is silent in the worst direction: the operator
+     * sets one key and every tenant thereafter acts as the SAME third-party principal, with nothing
+     * anywhere saying so. `organizationProviderCredentials` is the resource that lets a tenant's own
+     * administrator supply its own token, and this method is how a call on that tenant's behalf finds
+     * it.
+     *
+     * Note what this does NOT change: provider SELECTION — which module fills an engine capability —
+     * is still per capability and per scope, application-wide. You cannot route one tenant's email
+     * through one vendor and another's through a second. What is per tenant is the CREDENTIAL used
+     * when calling the one selected provider.
+     *
+     * ## The order, and the two refusals that differ
+     *
+     * 1. the organization's own credential, if it has one for this `(providerRef, secretSlug)` pair;
+     * 2. otherwise the deployment environment variable — the shared credential every tenant uses;
+     * 3. otherwise it THROWS, naming both places it looked, so an operator is told either to have the
+     *    tenant's administrator set a credential or to set the environment variable for everyone.
+     *
+     * That third step is the difference from the ordinary secret lookup, which is deliberately
+     * forgiving and returns nothing when a key is absent. Here an absent credential is a refusal, so
+     * a per-tenant call cannot proceed without knowing whose identity is on the wire.
+     *
+     * **A tenant credential that cannot be OPENED is not a fall-through either.** The envelope failure
+     * is deliberately not caught, because falling back to the deployment's shared credential 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 acting.
+     *
      * @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.
@@ -1389,6 +1539,7 @@ let ExternalProvidersRegistryBackendService = class ExternalProvidersRegistryBac
             },
         });
     }
+    /** @wildo_source:part:end saas.backend.providers.per-tenant-credential-resolution */
     /**
      * The tenant-aware sibling of `getProviderApiKey` — the provider's configured `authConfig`
      * secret, resolved for one organization.