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

package/dist/esm/security/connected-accounts/controllers/provider-connection.controller.backend.service.js

@@ -0,0 +1,953 @@
+/**
+ * Connecting a third-party account — the two HTTP legs of the authorization-code flow.
+ *
+ * `POST /connections/:providerRef/start` answers with the URL to send somebody to.
+ * `GET  /connections/callback`           receives them back and stores the grant.
+ *
+ * ## The opposite direction from the OAuth controller next door
+ *
+ * `oauth-provider-controller` makes this application an OAuth PROVIDER, and
+ * `authentication-controller` signs people IN using a vendor as their identity provider. This
+ * connects a vendor account so the application can act AS that account. Same RFC, opposite arrow,
+ * and nothing is shared but the specification.
+ *
+ * ## Everything arriving on the callback is attacker-controllable
+ *
+ * The callback is reached by a redirect through the person's own browser. Its query string is
+ * whatever somebody put there. So the callback trusts NOTHING from its own URL except the `state`,
+ * which it uses only as a lookup key — the provider, the owner, the PKCE verifier and the redirect
+ * URI all come from the record that was written when the redirect went out. A callback that read the
+ * owner from a query parameter would let anybody choose whose account a grant is stored against.
+ *
+ * ## Why the start leg returns a URL instead of redirecting
+ *
+ * The caller is a fetch from a settings screen, not a browser navigation. A 302 to a vendor would be
+ * followed by the fetch, produce an opaque cross-origin response, and never reach the person — the
+ * consent screen would render into a response body nobody sees. The screen navigates itself.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a principal authorizes this
+ * application to act toward a named third party on their behalf.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { inject, injectable } from 'inversify';
+import { z } from 'zod';
+import { ErrorType, MANUAL_CONTROLLER_ROUTES_URLS, ManualControllerRouteKey, WildoHeaderKeys, isWildoBackendError, } from '@wildo-ai/saas-models';
+import { ExternalProvider_Connection_OwnerScope, ExternalProvider_ConnectionTargetSchema, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_SecretScope, ProviderProtocolRuntimeKind, } from '@wildo-ai/external-connectors-models';
+import { ProviderAuthMethod, ProviderConnectabilityBlocker } from '@wildo-ai/saas-models';
+import { AbstractControllerBackendService } from '../../../base-classes/services/controllers/abstract-controller.backend.service.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { resolveUserDelegatedAccessTokenSlot, UserDelegatedAccessTokenRefusal } from '../../../security/connected-accounts/utils/user-delegated-access-token-slot.backend.utils.js';
+import { AuthControllerUtils } from '../../../security/authentications/services/utils/auth-controller.utils.js';
+import { describeCaughtError } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
+import { buildProviderOAuth2AuthorizeUrl, createProviderOAuth2Pkce, createProviderOAuth2State, exchangeProviderOAuth2Code, } from '../services/provider-oauth2-exchange.backend.js';
+/**
+ * The start request.
+ *
+ * `target` is validated by the connection-target schema, which already refuses the incoherent
+ * combinations — an APPLICATION target naming an owner, a SERVICE call naming somebody to act for.
+ * Reusing it here means the connect leg and the call leg cannot disagree about what a target is.
+ */
+const StartConnectionRequestSchema = z.object({
+    target: ExternalProvider_ConnectionTargetSchema,
+    secretSlug: z.string().min(1).max(200).optional(),
+    scopes: z.array(z.string().min(1)).optional(),
+    /** Answers for the endpoints' `{placeholders}` — which cloud, which directory, which region. */
+    connectionParameters: z.record(z.string(), z.string()).optional(),
+});
+/**
+ * A typed credential, one value per slot the provider declares.
+ *
+ * Keyed by SLUG rather than carrying a `secretSlug` field, because the shape then says what the rule
+ * is: a provider needing three values gets three keys, and there is no single slot for a caller to
+ * point somewhere unintended. The keys are validated against the contract, so the schema's job here
+ * is only to refuse an empty value.
+ */
+const StoreCredentialRequestSchema = z.object({
+    target: ExternalProvider_ConnectionTargetSchema,
+    values: z.record(z.string().min(1), z.string().min(1)),
+});
+/**
+ * The approval, handed back by the frontend that received it.
+ *
+ * Nothing here identifies an owner, and that is deliberate: the target lives in the remembered
+ * attempt, so a caller cannot choose whose account a grant is stored against by editing a body.
+ */
+const CompleteConnectionRequestSchema = z.object({
+    state: z.string().min(1).max(500),
+    code: z.string().min(1).max(4000),
+});
+/** Where the vendor sends people back. One URI for every provider — see the route's own JSDoc. */
+const CALLBACK_PATH = MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_CALLBACK];
+/**
+ * Where the person lands afterwards, on the FRONTEND — CHOSEN BY THE OWNER SCOPE.
+ *
+ * The settings hub routes by section ref, and connected accounts live at TWO of them: a personal
+ * one and a tenant one, each with its own Connect panel and its own credential list. So the
+ * destination is a function of whose account was connected, not a constant.
+ *
+ * It was `my-provider-credentials` unconditionally until 2026-09-10, which meant somebody who
+ * connected their ORGANIZATION's account was returned to their PERSONAL settings — a screen whose
+ * credential list shows their own rows and therefore says nothing about the tenant credential that
+ * had just been created. The connection worked and looked as though it had not, which is the
+ * report that found this. The organization destination's own definition already asserted the
+ * opposite ("Connect comes first because it is where the connection callback returns"), so the two
+ * halves disagreed and only one of them was executable.
+ *
+ * An APPLICATION-owned connection has no settings screen of its own — the deployment's credential
+ * is authored in the environment — and cannot reach the start leg's store check anyway, so it takes
+ * the personal destination as the one that exists rather than inventing a third.
+ */
+const PROVIDER_CONNECTION_RETURN_PATHS = {
+    [ExternalProvider_Connection_OwnerScope.USER]: '/settings/my-provider-credentials',
+    [ExternalProvider_Connection_OwnerScope.ORGANIZATION]: '/settings/provider-credentials',
+    [ExternalProvider_Connection_OwnerScope.APPLICATION]: '/settings/my-provider-credentials',
+};
+/** The destination for an attempt whose record is gone, so its owner cannot be known. */
+const PROVIDER_CONNECTION_FALLBACK_RETURN_PATH = PROVIDER_CONNECTION_RETURN_PATHS[ExternalProvider_Connection_OwnerScope.USER];
+/**
+ * This deployment has not registered an application with the vendor.
+ *
+ * Its own class because the answer it deserves is nothing like the catch-all's. A vendor's token
+ * endpoint misbehaving IS an upstream failure and 502 says so correctly; a client id that was never
+ * configured is entirely local, and answering 502 made a browser report "upstream server error" and
+ * sent an operator looking at infrastructure that is working perfectly.
+ */
+class ProviderRegistrationMissingError extends Error {
+    providerRef;
+    secretRef;
+    constructor(providerRef, secretRef) {
+        super(`Provider '${providerRef}' cannot be connected: the application's OAuth2 registration is not configured (${secretRef}).`);
+        this.providerRef = providerRef;
+        this.secretRef = secretRef;
+        this.name = 'ProviderRegistrationMissingError';
+    }
+}
+let ProviderConnectionControllerBackendService = class ProviderConnectionControllerBackendService extends AbstractControllerBackendService {
+    authJwtGuard;
+    authEcFactory;
+    registry;
+    pending;
+    targetAuthorization;
+    userCredentials;
+    organizationCredentials;
+    appConfig;
+    ecCreator;
+    constructor(logger, errorBuilder, errorHandler, authJwtGuard, authEcFactory, registry, pending, targetAuthorization, userCredentials, organizationCredentials, appConfig, ecCreator) {
+        super(logger, errorBuilder, errorHandler, 'ProviderConnectionController');
+        this.authJwtGuard = authJwtGuard;
+        this.authEcFactory = authEcFactory;
+        this.registry = registry;
+        this.pending = pending;
+        this.targetAuthorization = targetAuthorization;
+        this.userCredentials = userCredentials;
+        this.organizationCredentials = organizationCredentials;
+        this.appConfig = appConfig;
+        this.ecCreator = ecCreator;
+    }
+    setupRoutes() {
+        this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_START], this.asyncHandler(this.handleStart.bind(this)));
+        this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_START], 'Begin connecting a third-party account');
+        this.router.get(CALLBACK_PATH, this.asyncHandler(this.handleCallback.bind(this)));
+        this.logRouteRegistration('GET', CALLBACK_PATH, 'Receive the authorization code and hand it to the application');
+        this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_COMPLETE], this.asyncHandler(this.handleComplete.bind(this)));
+        this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_COMPLETE], 'Finish an approved connection as the person who began it');
+        this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_STORE_CREDENTIAL], this.asyncHandler(this.handleStoreCredential.bind(this)));
+        this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_STORE_CREDENTIAL], 'Store a typed credential');
+        this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_ACCESS_TOKEN], this.asyncHandler(this.handleAccessToken.bind(this)));
+        this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_ACCESS_TOKEN], 'Hand the caller their own short-lived access token');
+        this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_CATALOGUE], this.asyncHandler(this.handleCatalogue.bind(this)));
+        this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_CATALOGUE], 'What can be connected');
+    }
+    /**
+     * What can be connected — the question the stored-credential list cannot answer.
+     *
+     * A settings screen listing somebody's connections shows an empty table on the day they have none,
+     * which is precisely the day they need to learn what they might connect. So the CATALOGUE and the
+     * ROWS are two reads, deliberately: this one is about the provider, the resource LIST is about the
+     * person, and merging them would make "nothing connected" and "nothing connectable" indistinguishable.
+     *
+     * ## It reports a DECISION, and computes nothing
+     *
+     * `admissibleConnections` is the recorded decision in the provider's catalogue record — never
+     * derived from what a vendor's API happens to support. A vendor with a personal-token endpoint does
+     * not thereby become a provider a person may connect individually; somebody decided that, and this
+     * route repeats what they decided.
+     *
+     * ## It answers ADMISSIBILITY, not AUTHORIZATION, and that split is not laziness
+     *
+     * Whether this caller may act for a given owner depends on the owner's ID, which a catalogue has
+     * none of — an organization-scoped shape is admissible for the provider while the caller may be
+     * entitled to act for one tenant and not another. So the start leg keeps both gates in the same
+     * order every credential path uses, and a screen that renders an owner it cannot act for gets a
+     * 403 there rather than a silently missing row here.
+     *
+     * ## Nothing here is a secret
+     *
+     * Which vendors an application integrates with is a property of the application, visible on its own
+     * marketing pages. No token, no client secret, no env-var VALUE is reported — `connectionParameters`
+     * names the placeholders a connection must ANSWER, which is an input to ask a person for.
+     */
+    /**
+     * Hands the CALLER their own short-lived access token for one provider (#394 P4).
+     *
+     * ## Why a browser is handed a token at all
+     *
+     * A vendor's picker authorizes as the signed-in user. Drive's cannot render without that user's
+     * OAuth2 token, so the token is in the browser during picking whether the selected bytes are later
+     * fetched by the backend (`REMOTE_REFERENCE`) or not. #383 named a user-consented token a
+     * browser-safe grant for exactly this reason: it is the PERSON's grant, not the tenant's credential.
+     *
+     * ## What keeps this the one safe door
+     *
+     * - **The caller's own account, and nobody else's.** The row is resolved as `{ userId: caller }`;
+     *   there is no target in the request to name another owner, so `mayActFor` has nothing to decide.
+     * - **Admissibility is the provider's recorded decision**, the same catalogue `start` consults: a
+     *   provider that does not admit a user-owned, self-delegated connection has no grant to hand out.
+     * - **Never the refresh token.** The resolution carries the access token, its expiry and its
+     *   scopes; the refresh token stays in the sealed row and the renewal happens here, server-side.
+     * - **Every hand-out is a USE.** `recordCredentialUse` emits `USER_PROVIDER_CREDENTIAL_USED` and
+     *   stamps `lastUsedAt`, so a token that left the process is visible against the revocation and
+     *   erasure that end it.
+     * - **404 when nothing is connected**, so a surface can offer the connection instead of opening a
+     *   picker on nobody's files — the picker's own `onError` then names what is missing.
+     *
+     * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a person's delegated grant reaches
+     * the browser only as their own, only as an access token, and only as a recorded use.
+     */
+    async handleAccessToken(req, res) {
+        try {
+            const { userId } = await this.extractCaller(req);
+            const providerRef = String(req.params.providerRef ?? '');
+            // The same predicate the Drive storage reads a linked file through (#394 P5): one answer to
+            // "does this provider hand a person their own token", not two.
+            const requestedSlug = typeof req.query.secretSlug === 'string' ? req.query.secretSlug : undefined;
+            const slot = resolveUserDelegatedAccessTokenSlot(this.registry, providerRef, requestedSlug);
+            if (slot.admitted === false) {
+                if (slot.refusal === UserDelegatedAccessTokenRefusal.PROVIDER_NOT_CONNECTABLE) {
+                    res.status(400).json({
+                        error: slot.refusal,
+                        message: `Provider '${providerRef}' does not declare an OAuth2 contract, so there is no delegated token to hand out.`,
+                    });
+                    return;
+                }
+                res.status(409).json({
+                    error: slot.refusal,
+                    message: `Provider '${providerRef}' does not admit a user-owned connection, so there is no personal token to hand out.`,
+                });
+                return;
+            }
+            const { secretSlug } = slot;
+            const resolution = await this.userCredentials.resolveUserCredential({ userId, providerRef, secretSlug });
+            if (resolution === undefined) {
+                res.status(404).json({
+                    error: 'NOT_CONNECTED',
+                    message: `You have not connected '${providerRef}'. Connect it first; the picker cannot open on nobody's files.`,
+                });
+                return;
+            }
+            // Best-effort by design (see the store): the token is about to leave the process either way,
+            // and a bookkeeping failure must not turn a working picker into an error. Awaited so the audit
+            // row lands BEFORE the response that carries the token out.
+            await this.userCredentials.recordCredentialUse({ userId, providerRef, secretSlug, credentialId: resolution.credentialId });
+            res.status(200).json({
+                accessToken: resolution.value,
+                expiresAt: resolution.expiresAt,
+                grantedScopes: resolution.grantedScopes,
+            });
+        }
+        catch (error) {
+            this.handleControllerError(error, res, 'hand out an access token');
+        }
+    }
+    async handleCatalogue(req, res) {
+        try {
+            // Authenticated, though nothing here is owner-specific: an unauthenticated reader has no
+            // screen to render it on, and an integration inventory is not something to hand to anybody who
+            // can reach the port.
+            await this.extractCaller(req);
+            const providers = this.registry.getProviderTypes()
+                .map((providerRef) => {
+                const contract = this.registry.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);
+                const oauth2 = contract?.kind === ProviderProtocolRuntimeKind.REST ? contract.oauth2 : undefined;
+                const blocker = this.connectabilityBlocker(providerRef, oauth2);
+                const slots = this.registry.getProviderSecretSlots(providerRef);
+                return {
+                    providerRef,
+                    /**
+                     * Whether THIS DEPLOYMENT can begin a connection — not whether the vendor supports one.
+                     *
+                     * Those were the same field until somebody pressed Connect on Asana and got a 502. Asana
+                     * supports OAuth2 perfectly well and this application has never registered with it, so
+                     * the button could only ever fail. A provider that is not connectable still APPEARS, with
+                     * the reason: a supported vendor rendered as absent is a worse answer than one rendered
+                     * with what is missing.
+                     */
+                    connectable: blocker === undefined,
+                    notConnectableBecause: blocker,
+                    /**
+                     * HOW this provider is connected, so the screen can be the right screen. A vendor with an
+                     * authorization flow gets the consent round trip; one whose credential is typed gets a
+                     * form over the fields BELOW, and never a free-text slug.
+                     */
+                    authMethods: oauth2 === undefined
+                        ? [ProviderAuthMethod.DECLARED_SECRET]
+                        : [ProviderAuthMethod.OAUTH2_AUTHORIZATION_CODE],
+                    /**
+                     * The account-identifying slots a person fills, DECLARED by the provider rather than typed.
+                     *
+                     * This is what removes the free-text `secretSlug`: a vendor needing three values says so,
+                     * and the form asks for those three by name. Empty for a vendor whose only credential is
+                     * minted by an exchange.
+                     */
+                    credentialFields: slots
+                        .filter((slot) => slot.scope === ExternalProvider_SecretScope.CREDENTIAL)
+                        .map(({ slug, envVarName, required, description, configured }) => ({ slug, envVarName, required, description, configured })),
+                    /**
+                     * What an OPERATOR still has to set for this provider to be connectable at all.
+                     *
+                     * Reported rather than used to hide the provider: an absent vendor answers "we do not
+                     * support Asana", which is false and unfixable, while a named missing variable is true and
+                     * is the thing that gets it set. Only the REQUIRED ones — an optional slot that is unset
+                     * is not a gap, and listing it would make the real gaps harder to see.
+                     */
+                    missingRegistration: slots
+                        .filter((slot) => slot.scope === ExternalProvider_SecretScope.REGISTRATION && slot.required && !slot.configured)
+                        .map(({ slug, envVarName, description }) => ({ slug, envVarName, description })),
+                    admissibleConnections: this.registry.getProviderAdmissibleConnections(providerRef)
+                        .map(({ ownerScope, delegation }) => ({ ownerScope, delegation })),
+                    // Absent, not empty, when the endpoints are plain — the same distinction the contract
+                    // draws, so "no placeholder" stays separable from "nobody has looked".
+                    connectionParameters: oauth2?.connectionParameters,
+                    scopes: oauth2?.scopes,
+                };
+            })
+                // Keep only what somebody could actually connect: a provider admitting at least one
+                // NON-APPLICATION owner.
+                //
+                // The obvious test — "admits nothing" — is INERT here, and measuring is what showed it. A
+                // provider with no recorded decision does not admit an empty set:
+                // `getProviderAdmissibleConnections` defaults it to APPLICATION/SERVICE, so the length is
+                // never zero and that filter removed exactly nothing. With 689 transposed providers and one
+                // recorded decision, this route was returning all 689 to a screen that can show one.
+                //
+                // APPLICATION is the right thing to exclude rather than an approximation of it. That scope
+                // means the DEPLOYMENT's own credential, authored in the environment — `storeGrantForTarget`
+                // refuses an APPLICATION target outright and says so — leaving no flow to begin, so a
+                // Connect button for one could only ever fail.
+                .filter((entry) => entry.admissibleConnections.some((shape) => shape.ownerScope !== ExternalProvider_Connection_OwnerScope.APPLICATION));
+            res.status(200).json({ providers });
+        }
+        catch (error) {
+            this.handleControllerError(error, res, 'list the connectable providers');
+        }
+    }
+    /**
+     * Store a credential somebody typed — the whole flow for a vendor with no authorization dance.
+     *
+     * ## The slugs are CHECKED, not trusted
+     *
+     * Every key must be a slot the provider declares as identifying an ACCOUNT. That refusal is the
+     * point of the route: a screen can offer only declared fields and still be bypassed by anything
+     * that posts JSON, so "nothing is typed by hand" has to be enforced where the write happens.
+     *
+     * Two refusals rather than one, because the causes differ. A name the provider never declared is a
+     * caller inventing a slot. A name it declares as a REGISTRATION is worse and looks reasonable: the
+     * application's own client secret has a slug like any other, and writing an account token there
+     * would store a value nothing ever reads — the connect reports success and every call afterwards
+     * resolves as absent.
+     *
+     * ## Required slots must all arrive
+     *
+     * A partial credential is not a smaller credential; it is one that cannot authenticate. Refusing
+     * here costs a round trip, where accepting costs a stored row that fails at the vendor with an
+     * error naming the vendor rather than the omission.
+     *
+     * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — an account credential is recorded
+     * against the owner an authorized caller named.
+     */
+    async handleStoreCredential(req, res) {
+        try {
+            const { userId } = await this.extractCaller(req);
+            const providerRef = String(req.params.providerRef ?? '');
+            const parsed = StoreCredentialRequestSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'VALIDATION_FAILED', message: 'The credential request is not valid.' });
+                return;
+            }
+            const { target, values } = parsed.data;
+            const admitted = this.registry.getProviderAdmissibleConnections(providerRef)
+                .some((shape) => shape.ownerScope === target.ownerScope && shape.delegation === target.delegation);
+            if (!admitted) {
+                res.status(409).json({
+                    error: 'CONNECTION_NOT_ADMISSIBLE',
+                    message: `Provider '${providerRef}' does not admit a ${target.ownerScope}-owned, ${target.delegation}-delegated connection.`,
+                });
+                return;
+            }
+            if (!await this.mayActFor(target, userId, req)) {
+                res.status(403).json({ error: 'FORBIDDEN', message: 'You may not store a credential on behalf of that owner.' });
+                return;
+            }
+            const slots = this.registry.getProviderSecretSlots(providerRef);
+            const credentialSlots = slots.filter((slot) => slot.scope === ExternalProvider_SecretScope.CREDENTIAL);
+            const declared = new Map(credentialSlots.map((slot) => [slot.slug, slot]));
+            for (const slug of Object.keys(values)) {
+                const slot = slots.find((candidate) => candidate.slug === slug);
+                if (slot === undefined) {
+                    res.status(400).json({
+                        error: 'SECRET_SLUG_NOT_DECLARED',
+                        message: `Provider '${providerRef}' declares no secret named '${slug}'. It declares: `
+                            + `${credentialSlots.map((candidate) => candidate.slug).join(', ') || 'none'}.`,
+                    });
+                    return;
+                }
+                if (!declared.has(slug)) {
+                    res.status(400).json({
+                        error: 'SECRET_SLUG_NOT_A_CREDENTIAL',
+                        message: `'${slug}' identifies provider '${providerRef}'\u2019s own registration, not an account, `
+                            + 'so a credential cannot be stored there. It is authored in the deployment environment.',
+                    });
+                    return;
+                }
+            }
+            const missing = credentialSlots
+                .filter((slot) => slot.required && (values[slot.slug] ?? '').length === 0)
+                .map((slot) => slot.slug);
+            if (missing.length > 0) {
+                res.status(400).json({
+                    error: 'CREDENTIAL_INCOMPLETE',
+                    message: `Provider '${providerRef}' requires ${missing.join(', ')}. A partial credential cannot authenticate.`,
+                });
+                return;
+            }
+            // STORED UNDER THE SAME REFERENCE EVERY READER USES, which is the env-var name.
+            //
+            // A slot has two names — the authoring slug (`accessToken`) and its `envVarName`
+            // (`ASANA_API_KEY`) — and a credential row's business key is
+            // `(owner, providerRef, secretSlug)`, matched EXACTLY. Every runtime reader arrives holding
+            // `runtimeContract.apiKey.secretRef`, and a runtime contract only ever references a secret by
+            // its env-var name, so a row written under the slug is a row nothing can ever find.
+            //
+            // This door wrote the slug and the OAuth2 door wrote the env-var name, so the same account
+            // stored through the two paths produced two rows that could not see each other — and the
+            // typed one resolved as absent forever. It reported success, which is the shape this
+            // controller already refuses for registration slugs ("a value NOTHING reads").
+            //
+            // Canonicalising on the env-var name rather than on the slug follows the decision this
+            // subsystem already took for exactly this "two names for one secret" problem — see
+            // `getProviderSecretScope`, which compares on the env-var name for the same reason.
+            const stored = {};
+            for (const [slug, value] of Object.entries(values)) {
+                const secretRef = this.canonicalSecretRef(providerRef, slug);
+                stored[slug] = await this.storeDeclaredSecretForTarget(providerRef, secretRef, value, target);
+            }
+            // Never the values, and never how many characters they were.
+            this.logger.info?.('[oauth2-connect] typed credential stored', {
+                providerRef,
+                ownerScope: target.ownerScope,
+                slugs: Object.keys(stored),
+            });
+            res.status(200).json({ stored });
+        }
+        catch (error) {
+            this.handleControllerError(error, res, 'store a provider credential');
+        }
+    }
+    /**
+     * Route a typed credential to the store that owns the owner's table.
+     *
+     * An APPLICATION target has no store — the deployment's own credential lives in the environment —
+     * so a value arriving for one would be written where nothing reads it.
+     */
+    async storeDeclaredSecretForTarget(providerRef, secretSlug, value, target) {
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {
+            return this.userCredentials.storeDeclaredSecret({ userId: target.ownerId, providerRef, secretSlug }, value);
+        }
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.ORGANIZATION) {
+            return this.organizationCredentials.storeDeclaredSecret({ organizationId: target.ownerId, providerRef, secretSlug }, value);
+        }
+        throw new Error(`A typed credential for provider '${providerRef}' named an APPLICATION-owned target, which has no `
+            + "credential store: the deployment's own credential is authored in the environment.");
+    }
+    /**
+     * Leg one: decide whether this caller may connect this target, and hand back the URL.
+     *
+     * The two gates are the SAME pair every credential path goes through, in the same order.
+     * ADMISSIBLE — does this provider admit this owner scope at all? AUTHORIZED — may this execution
+     * act for that owner? Running them here rather than only at the callback means a person who cannot
+     * connect is told so before being sent to a vendor, rather than after granting consent.
+     */
+    async handleStart(req, res) {
+        try {
+            const { userId } = await this.extractCaller(req);
+            const providerRef = String(req.params.providerRef ?? '');
+            const parsed = StartConnectionRequestSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'VALIDATION_FAILED', message: 'The connection request is not valid.' });
+                return;
+            }
+            const { target, scopes, connectionParameters } = parsed.data;
+            const contract = this.registry.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);
+            if (contract?.kind !== ProviderProtocolRuntimeKind.REST || contract.oauth2 === undefined) {
+                res.status(400).json({
+                    error: 'PROVIDER_NOT_CONNECTABLE',
+                    message: `Provider '${providerRef}' does not declare an OAuth2 contract, so there is nothing to connect. `
+                        + 'A provider whose credential is pasted is authored on the credential screen instead.',
+                });
+                return;
+            }
+            const admitted = this.registry.getProviderAdmissibleConnections(providerRef)
+                .some((shape) => shape.ownerScope === target.ownerScope && shape.delegation === target.delegation);
+            if (!admitted) {
+                res.status(409).json({
+                    error: 'CONNECTION_NOT_ADMISSIBLE',
+                    message: `Provider '${providerRef}' does not admit a ${target.ownerScope}-owned, ${target.delegation}-delegated connection.`,
+                });
+                return;
+            }
+            if (!await this.mayActFor(target, userId, req)) {
+                // 403 rather than 404: the caller is authenticated and the provider exists; what they may not
+                // do is act for THIS owner. Answering 404 would make an authorization decision look like a
+                // missing provider and send an operator looking for a registration problem.
+                res.status(403).json({
+                    error: 'FORBIDDEN',
+                    message: 'You may not connect an account on behalf of that owner.',
+                });
+                return;
+            }
+            // Canonical, because `secretSlug` is caller-supplied and optional: a caller naming the
+            // authoring slug would otherwise have the minted grant written where no reader looks.
+            const secretSlug = this.canonicalSecretRef(providerRef, parsed.data.secretSlug ?? contract.apiKey.secretRef);
+            // WHERE the grant will be stored, and it must be a slug that holds an ACCOUNT.
+            //
+            // `secretSlug` is caller-supplied and optional, so without this a request could name the
+            // provider's OAuth2 client-secret slug and have a minted grant written to it. Nothing would
+            // ever read that row — the exchange takes the client secret from the deployment environment,
+            // never from a credential row — so the connect would report success and the connection would
+            // resolve as absent forever. A refusal that says which slug is wrong is worth more than a
+            // silent write to a slot nobody consults.
+            const scope = this.registry.getProviderSecretScope(providerRef, secretSlug);
+            if (scope !== ExternalProvider_SecretScope.CREDENTIAL) {
+                res.status(400).json({
+                    error: 'SECRET_SLUG_NOT_A_CREDENTIAL',
+                    message: `'${secretSlug}' identifies provider '${providerRef}'\u2019s own registration, not an account, `
+                        + 'so a minted grant cannot be stored there. Omit `secretSlug` to use the credential slot the '
+                        + 'provider declares, or name one that holds an account token.',
+                });
+                return;
+            }
+            const state = createProviderOAuth2State();
+            const pkce = createProviderOAuth2Pkce();
+            const redirectUri = this.callbackUrlFor(req);
+            const authorizeUrl = buildProviderOAuth2AuthorizeUrl({
+                oauth2: contract.oauth2,
+                providerRef,
+                clientId: this.requireClientId(providerRef, contract.oauth2.clientIdSecretRef),
+                redirectUri,
+                state,
+                pkce,
+                connectionParameters,
+                scopes,
+            });
+            // Recorded BEFORE the URL is handed out. The other order has a window in which somebody
+            // completes a flow whose record does not exist yet, and the callback would answer as though
+            // their state were forged.
+            await this.pending.remember(state, {
+                providerRef,
+                secretSlug,
+                target,
+                pkceVerifier: pkce.verifier,
+                redirectUri,
+                connectionParameters,
+                initiatedByUserId: userId,
+                // The header only exists on this leg. See the field's own JSDoc.
+                frontendServiceName: typeof req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] === 'string'
+                    ? req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME]
+                    : undefined,
+                startedAt: new Date().toISOString(),
+            });
+            res.status(200).json({ authorizeUrl });
+        }
+        catch (error) {
+            this.handleControllerError(error, res, 'start a provider connection');
+        }
+    }
+    /**
+     * Leg two: the person comes back with a code.
+     *
+     * Consuming the record is the first thing that happens, and it is atomic — so a replayed callback
+     * finds nothing and there is no window in which two concurrent callbacks both proceed.
+     */
+    async handleCallback(req, res) {
+        try {
+            const state = typeof req.query.state === 'string' ? req.query.state : '';
+            const code = typeof req.query.code === 'string' ? req.query.code : '';
+            // PEEKED, never consumed. This leg only needs the frontend to send the person back to; taking
+            // the attempt here would destroy it before the authenticated half could redeem it.
+            const pending = state === '' ? null : await this.pending.peek(state);
+            // A vendor that reports a refusal reports it HERE, in the redirect, not at the token endpoint.
+            // Treating a missing code as a forged state would tell somebody who simply pressed "Deny" that
+            // their request was invalid.
+            if (typeof req.query.error === 'string') {
+                // The vendor reports a refusal HERE, in the redirect. Somebody who pressed "Deny" is not an
+                // error case to explain — they are a person who changed their mind, and they go back to the
+                // screen they started from.
+                this.finishInBrowser(res, pending?.frontendServiceName, { connectionError: 'declined' }, pending?.target.ownerScope);
+                return;
+            }
+            if (pending === null || code === '') {
+                // ONE answer for expired, already-used, never-existed and missing-code. Distinguishing them
+                // would confirm to somebody probing that a state they hold is real.
+                //
+                // No frontend to return to either: the record that would have named one is exactly what is
+                // missing, so this is the one exit that cannot land anywhere but a bare page.
+                this.finishInBrowser(res, undefined, { connectionError: 'invalid' });
+                return;
+            }
+            // Handed to the application to finish, because THIS request cannot.
+            //
+            // A vendor redirect is a top-level navigation: no script ran to set an `Authorization` header,
+            // and the application's only auth cookie is `SameSite=Strict` on `Path=/api/v1/auth`, so it is
+            // not sent here either. There is therefore no credential on this request and no way to obtain
+            // one — which is why the initiator check moved to the completion route rather than being
+            // dropped. It used to be attempted here, and every consent answered 401 with the attempt
+            // already consumed, so the person could not even retry.
+            //
+            // The code crosses the browser a second time. That is not a new exposure — the vendor already
+            // put it in this URL — and the frontend strips it from history once it has been redeemed.
+            this.finishInBrowser(res, pending.frontendServiceName, { state, code }, pending.target.ownerScope);
+        }
+        catch (error) {
+            this.handleControllerError(error, res, 'receive a provider connection callback');
+        }
+    }
+    /**
+     * Finish an approval, as the person who began it.
+     *
+     * The authenticated half of the callback, and a POST because it is a FETCH — which is the whole
+     * point: a fetch carries the bearer token that a redirect cannot. Everything the callback used to
+     * guarantee is guaranteed here instead, in the same order.
+     *
+     * - **The attempt is consumed once, atomically**, so two concurrent completions cannot both
+     *   proceed and a replay finds nothing.
+     * - **The finisher must be the initiator.** Without it, somebody who obtained a valid `state`
+     *   could redeem their own approval against the original initiator's target — connecting THEIR
+     *   vendor account into somebody else's organization.
+     * - **The owner comes from the RECORD**, never from this request. A caller naming their own target
+     *   here would be choosing whose account a grant is stored against.
+     *
+     * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the grant is recorded against the
+     * owner the ATTEMPT named, by the person who began it, and by nobody else.
+     */
+    async handleComplete(req, res) {
+        try {
+            const { userId } = await this.extractCaller(req);
+            const parsed = CompleteConnectionRequestSchema.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({ error: 'VALIDATION_FAILED', message: 'The completion request is not valid.' });
+                return;
+            }
+            const { state, code } = parsed.data;
+            const pending = await this.pending.consume(state);
+            if (pending === null) {
+                // The same single answer the callback gives, for the same reason: expired, already used and
+                // never existed must not be distinguishable to somebody holding a state they are probing.
+                res.status(400).json({ error: 'CONNECTION_ATTEMPT_INVALID', message: 'This connection attempt is no longer valid. Start it again.' });
+                return;
+            }
+            if (pending.initiatedByUserId !== undefined && pending.initiatedByUserId !== userId) {
+                res.status(403).json({ error: 'NOT_YOURS', message: 'This connection attempt was started by somebody else.' });
+                return;
+            }
+            const contract = this.registry.getProviderRuntimeContract(pending.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);
+            if (contract?.kind !== ProviderProtocolRuntimeKind.REST || contract.oauth2 === undefined) {
+                res.status(400).json({
+                    error: 'PROVIDER_NOT_CONNECTABLE',
+                    message: `Provider '${pending.providerRef}' does not declare an OAuth2 contract.`,
+                });
+                return;
+            }
+            const grant = await exchangeProviderOAuth2Code({
+                oauth2: contract.oauth2,
+                providerRef: pending.providerRef,
+                clientId: this.requireClientId(pending.providerRef, contract.oauth2.clientIdSecretRef),
+                clientSecret: this.requireClientSecret(pending.providerRef, contract.oauth2.clientSecretSecretRef),
+                connectionParameters: pending.connectionParameters,
+                code,
+                // The SAME redirect URI that was authorized, from the record rather than rebuilt: vendors
+                // verify it byte-for-byte, and a proxy or a host header could make a rebuilt one differ.
+                redirectUri: pending.redirectUri,
+                pkceVerifier: pending.pkceVerifier,
+            });
+            const credentialId = await this.storeGrantForTarget(pending, grant);
+            // Logged AFTER the write, so the line means the connection EXISTS rather than that an exchange
+            // succeeded. `grantedScopes` is the fact worth having: a vendor may issue a token for fewer
+            // scopes than were asked for, and the resulting failure arrives on an unrelated operation
+            // weeks later with nothing to correlate against.
+            this.logger.info?.('[oauth2-connect] account connected', {
+                providerRef: pending.providerRef,
+                ownerScope: pending.target.ownerScope,
+                credentialId,
+                grantedScopes: grant.grantedScopes,
+                // Never the token, and never the grant.
+            });
+            res.status(200).json({ connected: pending.providerRef });
+        }
+        catch (error) {
+            this.handleControllerError(error, res, 'complete a provider connection');
+        }
+    }
+    /**
+     * End the callback the way a BROWSER expects: a redirect, never a payload.
+     *
+     * This leg is reached by the vendor redirecting the person's own browser. Whatever it writes is
+     * rendered as a page, so answering `res.json(...)` — which this flow did until it was driven —
+     * shows somebody who has just granted consent a raw JSON blob on a backend origin, with no way
+     * back. Every exit therefore lands them on the settings screen they started from, with the outcome
+     * in the query string for that screen to render.
+     *
+     * The frontend is resolved from the RECORD's `frontendServiceName`, never from a header: the
+     * vendor's redirect carries none of Wildo's own headers. When it cannot be resolved — an attempt
+     * whose record is exactly what is missing, or a caller that omitted the header at start — the
+     * fallback is a minimal HTML page rather than JSON. It says the same thing in the same medium the
+     * browser is already rendering.
+     *
+     * Status is 303, not 302: the callback arrives as a GET and the destination is a different
+     * resource to fetch with GET, which is what 303 means.
+     * spec-cite: RFC 9110 §15.4.4 (303 See Other).
+     */
+    finishInBrowser(res, frontendServiceName, outcome, ownerScope) {
+        const base = frontendServiceName === undefined
+            ? null
+            : AuthControllerUtils.lookupFrontendPublicUrl(this.appConfig.config, frontendServiceName);
+        if (base === null) {
+            // No origin to return to. Say so in HTML — a person on a vendor redirect is looking at a page,
+            // and the one thing not to give them is a payload.
+            const detail = outcome.connectionError === undefined
+                ? 'The account was connected. You can close this tab and return to the application.'
+                : 'This connection attempt could not be completed. Return to the application and start again.';
+            res.status(outcome.connectionError === undefined ? 200 : 400)
+                .type('html')
+                .send(`<!doctype html><meta charset="utf-8"><title>Connection</title><p>${detail}</p>`);
+            return;
+        }
+        const destination = new URL(ownerScope === undefined
+            ? PROVIDER_CONNECTION_FALLBACK_RETURN_PATH
+            : PROVIDER_CONNECTION_RETURN_PATHS[ownerScope], base);
+        for (const [key, value] of Object.entries(outcome))
+            destination.searchParams.set(key, value);
+        res.redirect(303, destination.toString());
+    }
+    /**
+     * Route the minted grant to the store that owns the owner's table.
+     *
+     * The target comes from the PENDING RECORD, so the row is written for whoever the authorized
+     * attempt named. Reading it from the callback's request instead would let somebody choose whose
+     * account a grant lands on — the failure the whole state mechanism exists to prevent.
+     *
+     * An APPLICATION target has no store: the deployment's own credential lives in the environment,
+     * and a connect flow that produced one would be writing a row nobody reads.
+     */
+    async storeGrantForTarget(pending, grant) {
+        const { providerRef, secretSlug, target, connectionParameters } = pending;
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {
+            return this.userCredentials.storeGrant({ userId: target.ownerId, providerRef, secretSlug }, grant, connectionParameters);
+        }
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.ORGANIZATION) {
+            return this.organizationCredentials.storeGrant({ organizationId: target.ownerId, providerRef, secretSlug }, grant, connectionParameters);
+        }
+        throw new Error(`A connection for provider '${providerRef}' completed with an APPLICATION-owned target, which has `
+            + 'no credential store: the deployment\'s own credential is authored in the environment. The '
+            + 'attempt should have been refused at the start leg.');
+    }
+    /**
+     * Why this deployment cannot begin a connection to a provider, or `undefined` when it can.
+     *
+     * Two different gaps that a boolean could not tell apart, and they are repaired by different people:
+     * a vendor with no authorization flow is authored on the credential screen by an APPLICATION
+     * AUTHOR, while a vendor this deployment has not registered with needs an OPERATOR to create an
+     * application at the vendor and set two environment variables.
+     *
+     * The client SECRET is checked as well as the id. Checking only the id would let a half-configured
+     * deployment advertise a provider as connectable and then fail at the token exchange — after the
+     * person had already granted consent at the vendor, which is the worst moment to discover it.
+     */
+    connectabilityBlocker(providerRef, oauth2) {
+        if (oauth2 === undefined)
+            return ProviderConnectabilityBlocker.NO_AUTHORIZATION_FLOW;
+        const secret = (ref) => (ref === undefined
+            ? undefined
+            : this.registry.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, ref));
+        return secret(oauth2.clientIdSecretRef) && secret(oauth2.clientSecretSecretRef)
+            ? undefined
+            : ProviderConnectabilityBlocker.APPLICATION_NOT_REGISTERED;
+    }
+    /**
+     * May this caller act for that owner?
+     *
+     * An APPLICATION target has exactly one instance and the application IS the caller, so there is no
+     * second party whose account might be spent. Every other target goes through the same membership
+     * port the resolution path uses — one answer to "may this execution act for that owner", not two
+     * that can disagree.
+     *
+     * ## The context is built from the REQUEST, and that is the whole correctness of this method
+     *
+     * The port decides an ORGANIZATION target by asking `initiatorRoles` which tenants the caller
+     * belongs to organization-wide. So it can only answer from a context whose roles were built from
+     * real memberships — which is what `createExecutionContextForManualController` does, and what the
+     * auth-flow factory deliberately does not.
+     *
+     * This asked `authEcFactory.createForAuthenticatedAuthOperation` until 2026-09-10, and that
+     * factory hardcodes `initiatorRoles` to a single APPLICATION-scoped `APP_USER` entry — correct for
+     * its own audience (token issuance, password change, TOTP), which asks no membership question, and
+     * taken verbatim by the creator rather than enriched. `organizationWideMembershipsOf` filters that
+     * array on `relatedPrimaryScope === ORGANIZATIONS`, so it was ALWAYS empty and every organization
+     * target was refused — for every caller, every tenant, both routes. Measured on the running stack:
+     * `application × service` and `user × service` minted an authorize URL while an `ORG_OWNER`'s
+     * `organization × user` answered 403, which is the one combination 75 vendors declare and the one
+     * this lane exists for.
+     *
+     * The fix is here rather than in the factory on purpose: giving that factory a membership read
+     * would put a repository round trip on every token refresh to answer a question its callers never
+     * ask. This path is a settings-screen click.
+     *
+     * Built only on the ORGANIZATION branch, for the same reason: APPLICATION admits without a caller
+     * and USER compares two ids, so neither reads a role and neither should pay for one.
+     */
+    async mayActFor(target, userId, req) {
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION)
+            return true;
+        if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {
+            // A person connects their OWN account and nobody else's. There is no administrative variant of
+            // this resource at any tier, so the only admissible user target is the caller themselves.
+            return target.ownerId === userId;
+        }
+        const ec = await this.ecCreator.createExecutionContextForManualController(req);
+        return this.targetAuthorization.mayActFor(target, ec);
+    }
+    /**
+     * The ONE name a credential row is keyed by, whichever of a slot's two names arrived.
+     *
+     * A declared slot has an authoring slug (`accessToken`) and an `envVarName` (`ASANA_API_KEY`), and
+     * both circulate: an authoring surface names the slug, while a runtime contract only ever
+     * references the env-var name. A credential row's business key is
+     * `(owner, providerRef, secretSlug)` and it is matched EXACTLY, so the two spellings are two
+     * different rows — and since every reader arrives holding `runtimeContract.apiKey.secretRef`, a
+     * row written under the slug is one nothing can ever find.
+     *
+     * The env-var name is the canonical form because it is the one a runtime contract carries, which
+     * is the same decision {@link ExternalProvidersRegistryBackendService.getProviderSecretScope} took
+     * for this subsystem's other "two names for one secret" defect. Choosing the slug instead would
+     * mean translating at every reader, and readers are the population that grows.
+     *
+     * An UNDECLARED ref is returned unchanged rather than rewritten: this normalises names the
+     * provider declares and is not a place to invent one. The callers refuse an undeclared ref on
+     * their own terms, and doing it here as well would answer the wrong error.
+     */
+    canonicalSecretRef(providerRef, ref) {
+        const slot = this.registry.getProviderSecretSlots(providerRef)
+            .find((candidate) => candidate.slug === ref || candidate.envVarName === ref);
+        return slot?.envVarName ?? ref;
+    }
+    requireClientId(providerRef, secretRef) {
+        const value = secretRef === undefined
+            ? undefined
+            : this.registry.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, secretRef);
+        if (!value) {
+            throw new ProviderRegistrationMissingError(providerRef, secretRef ?? 'the provider\'s client-id secret ref');
+        }
+        return value;
+    }
+    requireClientSecret(providerRef, secretRef) {
+        const value = secretRef === undefined
+            ? undefined
+            : this.registry.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, secretRef);
+        if (!value) {
+            throw new Error(`Provider '${providerRef}' cannot be connected: the application's OAuth2 client secret is not configured `
+                + `(${secretRef ?? 'no client secret declared'}). This is a deployment configuration gap.`);
+        }
+        return value;
+    }
+    /**
+     * The redirect URI, built once and then carried in the pending record.
+     *
+     * Derived from the request's own origin so a deployment needs no extra configuration, and stored
+     * rather than rebuilt at the callback: a vendor verifies it byte-for-byte, and a proxy that
+     * rewrites the host would make the rebuilt one differ from the authorized one.
+     */
+    callbackUrlFor(req) {
+        const forwardedProto = req.get('x-forwarded-proto');
+        const protocol = typeof forwardedProto === 'string' && forwardedProto.length > 0
+            ? forwardedProto.split(',')[0].trim()
+            : req.protocol;
+        return `${protocol}://${req.get('host') ?? 'localhost'}${req.baseUrl}${CALLBACK_PATH}`;
+    }
+    async extractCaller(req) {
+        const guardEc = await this.authEcFactory.createForPreAuthOperation(this.authEcFactory.getUsersReadOperationPath());
+        return this.authJwtGuard.extractAuthenticatedUser(guardEc, req);
+    }
+    /**
+     * One shape for every failure, and never the vendor's response body.
+     *
+     * A token endpoint's reply carries credentials even when it fails — several vendors echo the
+     * submitted client secret back in a validation message — so the message is logged with its detail
+     * and answered without it.
+     */
+    handleControllerError(error, res, action) {
+        this.logger.error?.(`[oauth2-connect] failed to ${action}`, { error: describeCaughtError(error) });
+        if (isWildoBackendError(error) && error.type === ErrorType.AUTHENTICATION) {
+            res.status(401).json({ error: 'UNAUTHENTICATED', message: 'Sign in and try again.' });
+            return;
+        }
+        if (error instanceof ProviderRegistrationMissingError) {
+            // 503, not 502. The deployment cannot service this request and an operator can fix it by
+            // registering an application with the vendor — where 502 asserts an upstream failure and sends
+            // that same operator to look at infrastructure that is working.
+            //
+            // The secret ref is NAMED because it is not a secret: it is the environment variable's NAME,
+            // which is exactly what somebody needs in order to act, and withholding it would leave the
+            // message true and useless.
+            res.status(503).json({
+                error: 'PROVIDER_REGISTRATION_MISSING',
+                providerRef: error.providerRef,
+                secretRef: error.secretRef,
+                message: `This application has not registered with '${error.providerRef}'. Create an application at the vendor and set ${error.secretRef} (and its client-secret pair) in this deployment's environment.`,
+            });
+            return;
+        }
+        res.status(502).json({
+            error: 'CONNECTION_FAILED',
+            message: `Could not ${action}. The detail is in the application log.`,
+        });
+    }
+};
+ProviderConnectionControllerBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorHandlerService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.AuthJwtGuardService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.ProviderOAuth2PendingAuthorizationService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.ConnectionTargetAuthorizationPort)),
+    __param(8, inject(SAAS_SERVICE_TYPES.UserProviderCredentialResolver)),
+    __param(9, inject(SAAS_SERVICE_TYPES.OrganizationProviderCredentialResolver)),
+    __param(10, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(11, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __metadata("design:paramtypes", [Function, Function, Function, Function, Function, Function, Function, Object, Function, Function, Function, Function])
+], ProviderConnectionControllerBackendService);
+export { ProviderConnectionControllerBackendService };
+//# sourceMappingURL=provider-connection.controller.backend.service.js.map