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

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

@@ -44,9 +44,11 @@ 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, ProviderProtocolRuntimeKind, ExternalProvider_SecretScope, } from '@wildo-ai/external-connectors-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';
@@ -64,16 +66,74 @@ const StartConnectionRequestSchema = z.object({
     /** 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.
+ * Where the person lands afterwards, on the FRONTEND — CHOSEN BY THE OWNER SCOPE.
  *
- * The settings hub routes by section ref, and `my-provider-credentials` is the destination this flow
- * connects an account for — so somebody returns to the screen they pressed Connect on rather than to
- * an application home that says nothing about what just happened.
+ * 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.
  */
-const PROVIDER_CONNECTION_RETURN_PATH = '/settings/my-provider-credentials';
+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;
@@ -83,7 +143,8 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
     userCredentials;
     organizationCredentials;
     appConfig;
-    constructor(logger, errorBuilder, errorHandler, 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;
@@ -93,12 +154,19 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
         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 store the grant');
+        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');
     }
@@ -131,6 +199,78 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
      * 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
@@ -141,14 +281,50 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 .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,
                     /**
-                     * FALSE for a provider whose credential is pasted rather than granted. Such a provider is
-                     * still a real integration and still appears — it is authored on the credential screen
-                     * instead — so omitting it would make a supported vendor look unsupported.
+                     * 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: oauth2 !== undefined,
+                    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
@@ -177,6 +353,134 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
             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.
      *
@@ -213,7 +517,7 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 });
                 return;
             }
-            if (!await this.mayActFor(target, userId)) {
+            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.
@@ -223,7 +527,9 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 });
                 return;
             }
-            const secretSlug = parsed.data.secretSlug ?? contract.apiKey.secretRef;
+            // 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
@@ -288,6 +594,9 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
         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.
@@ -295,10 +604,9 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 // 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, undefined, { connectionError: 'declined' });
+                this.finishInBrowser(res, pending?.frontendServiceName, { connectionError: 'declined' }, pending?.target.ownerScope);
                 return;
             }
-            const pending = state === '' ? null : await this.pending.consume(state);
             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.
@@ -308,19 +616,66 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 this.finishInBrowser(res, undefined, { connectionError: 'invalid' });
                 return;
             }
-            // Re-check that the person finishing the flow is the person who began it. Without it, somebody
-            // who obtained a valid state could complete the connection while signed in as themselves and
-            // have the grant stored against the original initiator's target.
+            // 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) {
-                this.finishInBrowser(res, pending.frontendServiceName, { connectionError: 'not-yours' });
+                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) {
-                this.finishInBrowser(res, pending.frontendServiceName, {
-                    connectionError: 'not-connectable',
-                    providerRef: pending.providerRef,
+                res.status(400).json({
+                    error: 'PROVIDER_NOT_CONNECTABLE',
+                    message: `Provider '${pending.providerRef}' does not declare an OAuth2 contract.`,
                 });
                 return;
             }
@@ -336,8 +691,6 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 redirectUri: pending.redirectUri,
                 pkceVerifier: pending.pkceVerifier,
             });
-            // assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the grant is recorded against
-            // the owner the ATTEMPT named, never one the callback's own URL could carry.
             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
@@ -350,7 +703,7 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 grantedScopes: grant.grantedScopes,
                 // Never the token, and never the grant.
             });
-            this.finishInBrowser(res, pending.frontendServiceName, { connected: pending.providerRef });
+            res.status(200).json({ connected: pending.providerRef });
         }
         catch (error) {
             this.handleControllerError(error, res, 'complete a provider connection');
@@ -375,7 +728,7 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
      * resource to fetch with GET, which is what 303 means.
      * spec-cite: RFC 9110 §15.4.4 (303 See Other).
      */
-    finishInBrowser(res, frontendServiceName, outcome) {
+    finishInBrowser(res, frontendServiceName, outcome, ownerScope) {
         const base = frontendServiceName === undefined
             ? null
             : AuthControllerUtils.lookupFrontendPublicUrl(this.appConfig.config, frontendServiceName);
@@ -390,7 +743,9 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
                 .send(`<!doctype html><meta charset="utf-8"><title>Connection</title><p>${detail}</p>`);
             return;
         }
-        const destination = new URL(PROVIDER_CONNECTION_RETURN_PATH, base);
+        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());
@@ -417,6 +772,28 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
             + '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?
      *
@@ -424,8 +801,32 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
      * 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) {
+    async mayActFor(target, userId, req) {
         if (target.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION)
             return true;
         if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {
@@ -433,16 +834,39 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
             // this resource at any tier, so the only admissible user target is the caller themselves.
             return target.ownerId === userId;
         }
-        const ec = await this.authEcFactory.createForAuthenticatedAuthOperation(userId, this.authEcFactory.getUsersReadOperationPath());
+        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 Error(`Provider '${providerRef}' cannot be connected: the application's OAuth2 client id is not configured `
-                + `(${secretRef ?? 'no client id declared'}). This is a deployment configuration gap.`);
+            throw new ProviderRegistrationMissingError(providerRef, secretRef ?? 'the provider\'s client-id secret ref');
         }
         return value;
     }
@@ -487,6 +911,22 @@ let ProviderConnectionControllerBackendService = class ProviderConnectionControl
             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.`,
@@ -506,7 +946,8 @@ ProviderConnectionControllerBackendService = __decorate([
     __param(8, inject(SAAS_SERVICE_TYPES.UserProviderCredentialResolver)),
     __param(9, inject(SAAS_SERVICE_TYPES.OrganizationProviderCredentialResolver)),
     __param(10, inject(SAAS_SERVICE_TYPES.AppConfigService)),
-    __metadata("design:paramtypes", [Function, Function, Function, Function, Function, Function, Function, Object, Function, Function, Function])
+    __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