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

package/dist/esm/security/connected-accounts/controllers/provider-connection.controller.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-connection.controller.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/controllers/provider-connection.controller.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,kBAAkB,CAAC;AAsB1B,OAAO,EAAE,gCAAgC,EAAE,MAAM,0FAA0F,CAAC;AAC5I,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAC5G,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,yEAAyE,CAAC;AAC1H,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AACrK,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAC1J,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,iGAAiG,CAAC;AAGzJ,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AASpH,OAAO,KAAK,EAEV,gDAAgD,EACjD,MAAM,mEAAmE,CAAC;AAC3E,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,4DAA4D,CAAC;AAC5H,OAAO,KAAK,EAAE,iDAAiD,EAAE,MAAM,oEAAoE,CAAC;AA6B5I,qBACa,0CAA2C,SAAQ,gCAAgC;IAK5C,OAAO,CAAC,QAAQ,CAAC,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAChC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe;IACxB,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAVpC,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EACxC,YAAY,EAAE,mBAAmB,EAChB,YAAY,EAAE,0BAA0B,EAChC,aAAa,EAAE,yCAAyC,EACnD,QAAQ,EAAE,uCAAuC,EACxC,OAAO,EAAE,gDAAgD,EACjE,mBAAmB,EAAE,iCAAiC,EACzD,eAAe,EAAE,yCAAyC,EAClD,uBAAuB,EAAE,iDAAiD,EAChG,SAAS,EAAE,uBAAuB;IAKlG,SAAS,CAAC,WAAW,IAAI,IAAI;IAiB7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;YACW,eAAe;IAkD7B;;;;;;;OAOG;YACW,WAAW;IAsGzB;;;;;OAKG;YACW,cAAc;IAiF5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,eAAe;IA0BvB;;;;;;;;;OASG;YACW,mBAAmB;IA2BjC;;;;;;;OAOG;YACW,SAAS;IAavB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,mBAAmB;IAa3B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;YAQR,aAAa;IAK3B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;CAW9B"}

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

@@ -0,0 +1,512 @@
+/**
+ * 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, ProviderProtocolRuntimeKind, ExternalProvider_SecretScope, } from '@wildo-ai/external-connectors-models';
+import { AbstractControllerBackendService } from '../../../base-classes/services/controllers/abstract-controller.backend.service.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.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(),
+});
+/** 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.
+ *
+ * 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.
+ */
+const PROVIDER_CONNECTION_RETURN_PATH = '/settings/my-provider-credentials';
+let ProviderConnectionControllerBackendService = class ProviderConnectionControllerBackendService extends AbstractControllerBackendService {
+    authJwtGuard;
+    authEcFactory;
+    registry;
+    pending;
+    targetAuthorization;
+    userCredentials;
+    organizationCredentials;
+    appConfig;
+    constructor(logger, errorBuilder, errorHandler, authJwtGuard, authEcFactory, registry, pending, targetAuthorization, userCredentials, organizationCredentials, appConfig) {
+        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;
+    }
+    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.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.
+     */
+    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;
+                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.
+                     */
+                    connectable: oauth2 !== undefined,
+                    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');
+        }
+    }
+    /**
+     * 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)) {
+                // 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;
+            }
+            const secretSlug = 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 : '';
+            // 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, undefined, { connectionError: 'declined' });
+                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.
+                //
+                // 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;
+            }
+            // 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.
+            const { userId } = await this.extractCaller(req);
+            if (pending.initiatedByUserId !== undefined && pending.initiatedByUserId !== userId) {
+                this.finishInBrowser(res, pending.frontendServiceName, { connectionError: 'not-yours' });
+                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,
+                });
+                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,
+            });
+            // 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
+            // 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.
+            });
+            this.finishInBrowser(res, pending.frontendServiceName, { 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) {
+        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(PROVIDER_CONNECTION_RETURN_PATH, 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.');
+    }
+    /**
+     * 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.
+     */
+    async mayActFor(target, userId) {
+        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.authEcFactory.createForAuthenticatedAuthOperation(userId, this.authEcFactory.getUsersReadOperationPath());
+        return this.targetAuthorization.mayActFor(target, ec);
+    }
+    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.`);
+        }
+        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;
+        }
+        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)),
+    __metadata("design:paramtypes", [Function, Function, Function, Function, Function, Function, Function, Object, Function, Function, Function])
+], ProviderConnectionControllerBackendService);
+export { ProviderConnectionControllerBackendService };
+//# sourceMappingURL=provider-connection.controller.backend.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-connection.controller.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/controllers/provider-connection.controller.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Connecting a third-party account — the two HTTP legs of the authorization-code flow.\n *\n * `POST /connections/:providerRef/start` answers with the URL to send somebody to.\n * `GET  /connections/callback`           receives them back and stores the grant.\n *\n * ## The opposite direction from the OAuth controller next door\n *\n * `oauth-provider-controller` makes this application an OAuth PROVIDER, and\n * `authentication-controller` signs people IN using a vendor as their identity provider. This\n * connects a vendor account so the application can act AS that account. Same RFC, opposite arrow,\n * and nothing is shared but the specification.\n *\n * ## Everything arriving on the callback is attacker-controllable\n *\n * The callback is reached by a redirect through the person's own browser. Its query string is\n * whatever somebody put there. So the callback trusts NOTHING from its own URL except the `state`,\n * which it uses only as a lookup key — the provider, the owner, the PKCE verifier and the redirect\n * URI all come from the record that was written when the redirect went out. A callback that read the\n * owner from a query parameter would let anybody choose whose account a grant is stored against.\n *\n * ## Why the start leg returns a URL instead of redirecting\n *\n * The caller is a fetch from a settings screen, not a browser navigation. A 302 to a vendor would be\n * followed by the fetch, produce an opaque cross-origin response, and never reach the person — the\n * consent screen would render into a response body nobody sees. The screen navigates itself.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a principal authorizes this\n * application to act toward a named third party on their behalf.\n */\n\nimport 'reflect-metadata';\nimport { inject, injectable } from 'inversify';\nimport type { Request, Response } from 'express';\nimport { z } from 'zod';\nimport {\n  ErrorType,\n  MANUAL_CONTROLLER_ROUTES_URLS,\n  ManualControllerRouteKey,\n  WildoHeaderKeys,\n  isWildoBackendError,\n} from '@wildo-ai/saas-models';\nimport {\n  ExternalProvider_Connection_DelegationMode,\n  ExternalProvider_Connection_OwnerScope,\n  ExternalProvider_ConnectionTargetSchema,\n  ExternalProvider_ExchangeProtocol_Kind,\n  ProviderProtocolRuntimeKind,\n  ExternalProvider_SecretScope,\n} from '@wildo-ai/external-connectors-models';\nimport type { ExternalProvider_ConnectionTarget } from '@wildo-ai/external-connectors-models';\nimport type { ProviderOAuth2Grant } from '@wildo-ai/saas-models';\n\nimport { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport type { ErrorHandlerService } from '~wildo-backend-lib/errors/services/error-handler.backend.service';\nimport type { AuthJwtGuardBackendService } from '~wildo-backend-lib/security/jwt/services/auth-jwt-guard.backend.service';\nimport type { AuthExecutionContextFactoryBackendService } from '~wildo-backend-lib/security/authentications/services/auth-execution-context-factory.backend.service';\nimport type { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';\nimport type { ConnectionTargetAuthorizationPort } from '~wildo-backend-lib/base-classes/services/repositories/http-api/http-api-provider-access.backend';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { AuthControllerUtils } from '~wildo-backend-lib/security/authentications/services/utils/auth-controller.utils';\nimport type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport { describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\n\nimport {\n  buildProviderOAuth2AuthorizeUrl,\n  createProviderOAuth2Pkce,\n  createProviderOAuth2State,\n  exchangeProviderOAuth2Code,\n} from '../services/provider-oauth2-exchange.backend';\nimport type {\n  ProviderOAuth2PendingAuthorization,\n  ProviderOAuth2PendingAuthorizationBackendService,\n} from '../services/provider-oauth2-pending-authorization.backend.service';\nimport type { UserProviderCredentialStoreBackendService } from '../services/user-provider-credential-store.backend.service';\nimport type { OrganizationProviderCredentialStoreBackendService } from '../services/organization-provider-credential-store.backend.service';\n\n/**\n * The start request.\n *\n * `target` is validated by the connection-target schema, which already refuses the incoherent\n * combinations — an APPLICATION target naming an owner, a SERVICE call naming somebody to act for.\n * Reusing it here means the connect leg and the call leg cannot disagree about what a target is.\n */\nconst StartConnectionRequestSchema = z.object({\n  target: ExternalProvider_ConnectionTargetSchema,\n  secretSlug: z.string().min(1).max(200).optional(),\n  scopes: z.array(z.string().min(1)).optional(),\n  /** Answers for the endpoints' `{placeholders}` — which cloud, which directory, which region. */\n  connectionParameters: z.record(z.string(), z.string()).optional(),\n});\n\n/** Where the vendor sends people back. One URI for every provider — see the route's own JSDoc. */\nconst CALLBACK_PATH = MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_CALLBACK];\n\n/**\n * Where the person lands afterwards, on the FRONTEND.\n *\n * The settings hub routes by section ref, and `my-provider-credentials` is the destination this flow\n * connects an account for — so somebody returns to the screen they pressed Connect on rather than to\n * an application home that says nothing about what just happened.\n */\nconst PROVIDER_CONNECTION_RETURN_PATH = '/settings/my-provider-credentials';\n\n@injectable()\nexport class ProviderConnectionControllerBackendService extends AbstractControllerBackendService {\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: ErrorHandlerService,\n    @inject(SAAS_SERVICE_TYPES.AuthJwtGuardService) private readonly authJwtGuard: AuthJwtGuardBackendService,\n    @inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory) private readonly authEcFactory: AuthExecutionContextFactoryBackendService,\n    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService) private readonly registry: ExternalProvidersRegistryBackendService,\n    @inject(SAAS_SERVICE_TYPES.ProviderOAuth2PendingAuthorizationService) private readonly pending: ProviderOAuth2PendingAuthorizationBackendService,\n    @inject(SAAS_SERVICE_TYPES.ConnectionTargetAuthorizationPort) private readonly targetAuthorization: ConnectionTargetAuthorizationPort,\n    @inject(SAAS_SERVICE_TYPES.UserProviderCredentialResolver) private readonly userCredentials: UserProviderCredentialStoreBackendService,\n    @inject(SAAS_SERVICE_TYPES.OrganizationProviderCredentialResolver) private readonly organizationCredentials: OrganizationProviderCredentialStoreBackendService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfig: AppConfigurationService,\n  ) {\n    super(logger, errorBuilder, errorHandler, 'ProviderConnectionController');\n  }\n\n  protected setupRoutes(): void {\n    this.router.post(\n      MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_START],\n      this.asyncHandler(this.handleStart.bind(this)),\n    );\n    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_START], 'Begin connecting a third-party account');\n\n    this.router.get(CALLBACK_PATH, this.asyncHandler(this.handleCallback.bind(this)));\n    this.logRouteRegistration('GET', CALLBACK_PATH, 'Receive the authorization code and store the grant');\n\n    this.router.get(\n      MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_CATALOGUE],\n      this.asyncHandler(this.handleCatalogue.bind(this)),\n    );\n    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.PROVIDER_CONNECTION_CATALOGUE], 'What can be connected');\n  }\n\n  /**\n   * What can be connected — the question the stored-credential list cannot answer.\n   *\n   * A settings screen listing somebody's connections shows an empty table on the day they have none,\n   * which is precisely the day they need to learn what they might connect. So the CATALOGUE and the\n   * ROWS are two reads, deliberately: this one is about the provider, the resource LIST is about the\n   * person, and merging them would make \"nothing connected\" and \"nothing connectable\" indistinguishable.\n   *\n   * ## It reports a DECISION, and computes nothing\n   *\n   * `admissibleConnections` is the recorded decision in the provider's catalogue record — never\n   * derived from what a vendor's API happens to support. A vendor with a personal-token endpoint does\n   * not thereby become a provider a person may connect individually; somebody decided that, and this\n   * route repeats what they decided.\n   *\n   * ## It answers ADMISSIBILITY, not AUTHORIZATION, and that split is not laziness\n   *\n   * Whether this caller may act for a given owner depends on the owner's ID, which a catalogue has\n   * none of — an organization-scoped shape is admissible for the provider while the caller may be\n   * entitled to act for one tenant and not another. So the start leg keeps both gates in the same\n   * order every credential path uses, and a screen that renders an owner it cannot act for gets a\n   * 403 there rather than a silently missing row here.\n   *\n   * ## Nothing here is a secret\n   *\n   * Which vendors an application integrates with is a property of the application, visible on its own\n   * marketing pages. No token, no client secret, no env-var VALUE is reported — `connectionParameters`\n   * names the placeholders a connection must ANSWER, which is an input to ask a person for.\n   */\n  private async handleCatalogue(req: Request, res: Response): Promise<void> {\n    try {\n      // Authenticated, though nothing here is owner-specific: an unauthenticated reader has no\n      // screen to render it on, and an integration inventory is not something to hand to anybody who\n      // can reach the port.\n      await this.extractCaller(req);\n\n      const providers = this.registry.getProviderTypes()\n        .map((providerRef) => {\n          const contract = this.registry.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);\n          const oauth2 = contract?.kind === ProviderProtocolRuntimeKind.REST ? contract.oauth2 : undefined;\n          return {\n            providerRef,\n            /**\n             * FALSE for a provider whose credential is pasted rather than granted. Such a provider is\n             * still a real integration and still appears — it is authored on the credential screen\n             * instead — so omitting it would make a supported vendor look unsupported.\n             */\n            connectable: oauth2 !== undefined,\n            admissibleConnections: this.registry.getProviderAdmissibleConnections(providerRef)\n              .map(({ ownerScope, delegation }) => ({ ownerScope, delegation })),\n            // Absent, not empty, when the endpoints are plain — the same distinction the contract\n            // draws, so \"no placeholder\" stays separable from \"nobody has looked\".\n            connectionParameters: oauth2?.connectionParameters,\n            scopes: oauth2?.scopes,\n          };\n        })\n        // Keep only what somebody could actually connect: a provider admitting at least one\n        // NON-APPLICATION owner.\n        //\n        // The obvious test — \"admits nothing\" — is INERT here, and measuring is what showed it. A\n        // provider with no recorded decision does not admit an empty set:\n        // `getProviderAdmissibleConnections` defaults it to APPLICATION/SERVICE, so the length is\n        // never zero and that filter removed exactly nothing. With 689 transposed providers and one\n        // recorded decision, this route was returning all 689 to a screen that can show one.\n        //\n        // APPLICATION is the right thing to exclude rather than an approximation of it. That scope\n        // means the DEPLOYMENT's own credential, authored in the environment — `storeGrantForTarget`\n        // refuses an APPLICATION target outright and says so — leaving no flow to begin, so a\n        // Connect button for one could only ever fail.\n        .filter((entry) => entry.admissibleConnections.some(\n          (shape) => shape.ownerScope !== ExternalProvider_Connection_OwnerScope.APPLICATION,\n        ));\n\n      res.status(200).json({ providers });\n    } catch (error) {\n      this.handleControllerError(error, res, 'list the connectable providers');\n    }\n  }\n\n  /**\n   * Leg one: decide whether this caller may connect this target, and hand back the URL.\n   *\n   * The two gates are the SAME pair every credential path goes through, in the same order.\n   * ADMISSIBLE — does this provider admit this owner scope at all? AUTHORIZED — may this execution\n   * act for that owner? Running them here rather than only at the callback means a person who cannot\n   * connect is told so before being sent to a vendor, rather than after granting consent.\n   */\n  private async handleStart(req: Request, res: Response): Promise<void> {\n    try {\n      const { userId } = await this.extractCaller(req);\n      const providerRef = String(req.params.providerRef ?? '');\n      const parsed = StartConnectionRequestSchema.safeParse(req.body);\n      if (!parsed.success) {\n        res.status(400).json({ error: 'VALIDATION_FAILED', message: 'The connection request is not valid.' });\n        return;\n      }\n      const { target, scopes, connectionParameters } = parsed.data;\n\n      const contract = this.registry.getProviderRuntimeContract(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);\n      if (contract?.kind !== ProviderProtocolRuntimeKind.REST || contract.oauth2 === undefined) {\n        res.status(400).json({\n          error: 'PROVIDER_NOT_CONNECTABLE',\n          message: `Provider '${providerRef}' does not declare an OAuth2 contract, so there is nothing to connect. `\n            + 'A provider whose credential is pasted is authored on the credential screen instead.',\n        });\n        return;\n      }\n\n      const admitted = this.registry.getProviderAdmissibleConnections(providerRef)\n        .some((shape) => shape.ownerScope === target.ownerScope && shape.delegation === target.delegation);\n      if (!admitted) {\n        res.status(409).json({\n          error: 'CONNECTION_NOT_ADMISSIBLE',\n          message: `Provider '${providerRef}' does not admit a ${target.ownerScope}-owned, ${target.delegation}-delegated connection.`,\n        });\n        return;\n      }\n\n      if (!await this.mayActFor(target, userId)) {\n        // 403 rather than 404: the caller is authenticated and the provider exists; what they may not\n        // do is act for THIS owner. Answering 404 would make an authorization decision look like a\n        // missing provider and send an operator looking for a registration problem.\n        res.status(403).json({\n          error: 'FORBIDDEN',\n          message: 'You may not connect an account on behalf of that owner.',\n        });\n        return;\n      }\n\n      const secretSlug = parsed.data.secretSlug ?? contract.apiKey.secretRef;\n\n      // WHERE the grant will be stored, and it must be a slug that holds an ACCOUNT.\n      //\n      // `secretSlug` is caller-supplied and optional, so without this a request could name the\n      // provider's OAuth2 client-secret slug and have a minted grant written to it. Nothing would\n      // ever read that row — the exchange takes the client secret from the deployment environment,\n      // never from a credential row — so the connect would report success and the connection would\n      // resolve as absent forever. A refusal that says which slug is wrong is worth more than a\n      // silent write to a slot nobody consults.\n      const scope = this.registry.getProviderSecretScope(providerRef, secretSlug);\n      if (scope !== ExternalProvider_SecretScope.CREDENTIAL) {\n        res.status(400).json({\n          error: 'SECRET_SLUG_NOT_A_CREDENTIAL',\n          message: `'${secretSlug}' identifies provider '${providerRef}'\\u2019s own registration, not an account, `\n            + 'so a minted grant cannot be stored there. Omit `secretSlug` to use the credential slot the '\n            + 'provider declares, or name one that holds an account token.',\n        });\n        return;\n      }\n\n      const state = createProviderOAuth2State();\n      const pkce = createProviderOAuth2Pkce();\n      const redirectUri = this.callbackUrlFor(req);\n\n      const authorizeUrl = buildProviderOAuth2AuthorizeUrl({\n        oauth2: contract.oauth2,\n        providerRef,\n        clientId: this.requireClientId(providerRef, contract.oauth2.clientIdSecretRef),\n        redirectUri,\n        state,\n        pkce,\n        connectionParameters,\n        scopes,\n      });\n\n      // Recorded BEFORE the URL is handed out. The other order has a window in which somebody\n      // completes a flow whose record does not exist yet, and the callback would answer as though\n      // their state were forged.\n      await this.pending.remember(state, {\n        providerRef,\n        secretSlug,\n        target,\n        pkceVerifier: pkce.verifier,\n        redirectUri,\n        connectionParameters,\n        initiatedByUserId: userId,\n        // The header only exists on this leg. See the field's own JSDoc.\n        frontendServiceName: typeof req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] === 'string'\n          ? (req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string)\n          : undefined,\n        startedAt: new Date().toISOString(),\n      });\n\n      res.status(200).json({ authorizeUrl });\n    } catch (error) {\n      this.handleControllerError(error, res, 'start a provider connection');\n    }\n  }\n\n  /**\n   * Leg two: the person comes back with a code.\n   *\n   * Consuming the record is the first thing that happens, and it is atomic — so a replayed callback\n   * finds nothing and there is no window in which two concurrent callbacks both proceed.\n   */\n  private async handleCallback(req: Request, res: Response): Promise<void> {\n    try {\n      const state = typeof req.query.state === 'string' ? req.query.state : '';\n      const code = typeof req.query.code === 'string' ? req.query.code : '';\n\n      // A vendor that reports a refusal reports it HERE, in the redirect, not at the token endpoint.\n      // Treating a missing code as a forged state would tell somebody who simply pressed \"Deny\" that\n      // their request was invalid.\n      if (typeof req.query.error === 'string') {\n        // The vendor reports a refusal HERE, in the redirect. Somebody who pressed \"Deny\" is not an\n        // error case to explain — they are a person who changed their mind, and they go back to the\n        // screen they started from.\n        this.finishInBrowser(res, undefined, { connectionError: 'declined' });\n        return;\n      }\n\n      const pending = state === '' ? null : await this.pending.consume(state);\n      if (pending === null || code === '') {\n        // ONE answer for expired, already-used, never-existed and missing-code. Distinguishing them\n        // would confirm to somebody probing that a state they hold is real.\n        //\n        // No frontend to return to either: the record that would have named one is exactly what is\n        // missing, so this is the one exit that cannot land anywhere but a bare page.\n        this.finishInBrowser(res, undefined, { connectionError: 'invalid' });\n        return;\n      }\n\n      // Re-check that the person finishing the flow is the person who began it. Without it, somebody\n      // who obtained a valid state could complete the connection while signed in as themselves and\n      // have the grant stored against the original initiator's target.\n      const { userId } = await this.extractCaller(req);\n      if (pending.initiatedByUserId !== undefined && pending.initiatedByUserId !== userId) {\n        this.finishInBrowser(res, pending.frontendServiceName, { connectionError: 'not-yours' });\n        return;\n      }\n\n      const contract = this.registry.getProviderRuntimeContract(pending.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);\n      if (contract?.kind !== ProviderProtocolRuntimeKind.REST || contract.oauth2 === undefined) {\n        this.finishInBrowser(res, pending.frontendServiceName, {\n          connectionError: 'not-connectable',\n          providerRef: pending.providerRef,\n        });\n        return;\n      }\n\n      const grant = await exchangeProviderOAuth2Code({\n        oauth2: contract.oauth2,\n        providerRef: pending.providerRef,\n        clientId: this.requireClientId(pending.providerRef, contract.oauth2.clientIdSecretRef),\n        clientSecret: this.requireClientSecret(pending.providerRef, contract.oauth2.clientSecretSecretRef),\n        connectionParameters: pending.connectionParameters,\n        code,\n        // The SAME redirect URI that was authorized, from the record rather than rebuilt: vendors\n        // verify it byte-for-byte, and a proxy or a host header could make a rebuilt one differ.\n        redirectUri: pending.redirectUri,\n        pkceVerifier: pending.pkceVerifier,\n      });\n\n      // assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the grant is recorded against\n      // the owner the ATTEMPT named, never one the callback's own URL could carry.\n      const credentialId = await this.storeGrantForTarget(pending, grant);\n\n      // Logged AFTER the write, so the line means the connection EXISTS rather than that an exchange\n      // succeeded. `grantedScopes` is the fact worth having: a vendor may issue a token for fewer\n      // scopes than were asked for, and the resulting failure arrives on an unrelated operation\n      // weeks later with nothing to correlate against.\n      this.logger.info?.('[oauth2-connect] account connected', {\n        providerRef: pending.providerRef,\n        ownerScope: pending.target.ownerScope,\n        credentialId,\n        grantedScopes: grant.grantedScopes,\n        // Never the token, and never the grant.\n      });\n\n      this.finishInBrowser(res, pending.frontendServiceName, { connected: pending.providerRef });\n    } catch (error) {\n      this.handleControllerError(error, res, 'complete a provider connection');\n    }\n  }\n\n\n  /**\n   * End the callback the way a BROWSER expects: a redirect, never a payload.\n   *\n   * This leg is reached by the vendor redirecting the person's own browser. Whatever it writes is\n   * rendered as a page, so answering `res.json(...)` — which this flow did until it was driven —\n   * shows somebody who has just granted consent a raw JSON blob on a backend origin, with no way\n   * back. Every exit therefore lands them on the settings screen they started from, with the outcome\n   * in the query string for that screen to render.\n   *\n   * The frontend is resolved from the RECORD's `frontendServiceName`, never from a header: the\n   * vendor's redirect carries none of Wildo's own headers. When it cannot be resolved — an attempt\n   * whose record is exactly what is missing, or a caller that omitted the header at start — the\n   * fallback is a minimal HTML page rather than JSON. It says the same thing in the same medium the\n   * browser is already rendering.\n   *\n   * Status is 303, not 302: the callback arrives as a GET and the destination is a different\n   * resource to fetch with GET, which is what 303 means.\n   * spec-cite: RFC 9110 §15.4.4 (303 See Other).\n   */\n  private finishInBrowser(\n    res: Response,\n    frontendServiceName: string | undefined,\n    outcome: Readonly<Record<string, string>>,\n  ): void {\n    const base = frontendServiceName === undefined\n      ? null\n      : AuthControllerUtils.lookupFrontendPublicUrl(this.appConfig.config, frontendServiceName);\n\n    if (base === null) {\n      // No origin to return to. Say so in HTML — a person on a vendor redirect is looking at a page,\n      // and the one thing not to give them is a payload.\n      const detail = outcome.connectionError === undefined\n        ? 'The account was connected. You can close this tab and return to the application.'\n        : 'This connection attempt could not be completed. Return to the application and start again.';\n      res.status(outcome.connectionError === undefined ? 200 : 400)\n        .type('html')\n        .send(`<!doctype html><meta charset=\"utf-8\"><title>Connection</title><p>${detail}</p>`);\n      return;\n    }\n\n    const destination = new URL(PROVIDER_CONNECTION_RETURN_PATH, base);\n    for (const [key, value] of Object.entries(outcome)) destination.searchParams.set(key, value);\n    res.redirect(303, destination.toString());\n  }\n\n  /**\n   * Route the minted grant to the store that owns the owner's table.\n   *\n   * The target comes from the PENDING RECORD, so the row is written for whoever the authorized\n   * attempt named. Reading it from the callback's request instead would let somebody choose whose\n   * account a grant lands on — the failure the whole state mechanism exists to prevent.\n   *\n   * An APPLICATION target has no store: the deployment's own credential lives in the environment,\n   * and a connect flow that produced one would be writing a row nobody reads.\n   */\n  private async storeGrantForTarget(\n    pending: ProviderOAuth2PendingAuthorization,\n    grant: ProviderOAuth2Grant,\n  ): Promise<string> {\n    const { providerRef, secretSlug, target, connectionParameters } = pending;\n\n    if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {\n      return this.userCredentials.storeGrant(\n        { userId: target.ownerId!, providerRef, secretSlug },\n        grant,\n        connectionParameters,\n      );\n    }\n    if (target.ownerScope === ExternalProvider_Connection_OwnerScope.ORGANIZATION) {\n      return this.organizationCredentials.storeGrant(\n        { organizationId: target.ownerId!, providerRef, secretSlug },\n        grant,\n        connectionParameters,\n      );\n    }\n    throw new Error(\n      `A connection for provider '${providerRef}' completed with an APPLICATION-owned target, which has `\n      + 'no credential store: the deployment\\'s own credential is authored in the environment. The '\n      + 'attempt should have been refused at the start leg.',\n    );\n  }\n\n  /**\n   * May this caller act for that owner?\n   *\n   * An APPLICATION target has exactly one instance and the application IS the caller, so there is no\n   * second party whose account might be spent. Every other target goes through the same membership\n   * port the resolution path uses — one answer to \"may this execution act for that owner\", not two\n   * that can disagree.\n   */\n  private async mayActFor(target: ExternalProvider_ConnectionTarget, userId: string): Promise<boolean> {\n    if (target.ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION) return true;\n    if (target.ownerScope === ExternalProvider_Connection_OwnerScope.USER) {\n      // A person connects their OWN account and nobody else's. There is no administrative variant of\n      // this resource at any tier, so the only admissible user target is the caller themselves.\n      return target.ownerId === userId;\n    }\n    const ec = await this.authEcFactory.createForAuthenticatedAuthOperation(\n      userId, this.authEcFactory.getUsersReadOperationPath(),\n    );\n    return this.targetAuthorization.mayActFor(target, ec);\n  }\n\n  private requireClientId(providerRef: string, secretRef: string | undefined): string {\n    const value = secretRef === undefined\n      ? undefined\n      : this.registry.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, secretRef);\n    if (!value) {\n      throw new Error(\n        `Provider '${providerRef}' cannot be connected: the application's OAuth2 client id is not configured `\n        + `(${secretRef ?? 'no client id declared'}). This is a deployment configuration gap.`,\n      );\n    }\n    return value;\n  }\n\n  private requireClientSecret(providerRef: string, secretRef: string | undefined): string {\n    const value = secretRef === undefined\n      ? undefined\n      : this.registry.getProviderSecret(providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, secretRef);\n    if (!value) {\n      throw new Error(\n        `Provider '${providerRef}' cannot be connected: the application's OAuth2 client secret is not configured `\n        + `(${secretRef ?? 'no client secret declared'}). This is a deployment configuration gap.`,\n      );\n    }\n    return value;\n  }\n\n  /**\n   * The redirect URI, built once and then carried in the pending record.\n   *\n   * Derived from the request's own origin so a deployment needs no extra configuration, and stored\n   * rather than rebuilt at the callback: a vendor verifies it byte-for-byte, and a proxy that\n   * rewrites the host would make the rebuilt one differ from the authorized one.\n   */\n  private callbackUrlFor(req: Request): string {\n    const forwardedProto = req.get('x-forwarded-proto');\n    const protocol = typeof forwardedProto === 'string' && forwardedProto.length > 0\n      ? forwardedProto.split(',')[0]!.trim()\n      : req.protocol;\n    return `${protocol}://${req.get('host') ?? 'localhost'}${req.baseUrl}${CALLBACK_PATH}`;\n  }\n\n  private async extractCaller(req: Request): Promise<{ userId: string }> {\n    const guardEc = await this.authEcFactory.createForPreAuthOperation(this.authEcFactory.getUsersReadOperationPath());\n    return this.authJwtGuard.extractAuthenticatedUser(guardEc, req);\n  }\n\n  /**\n   * One shape for every failure, and never the vendor's response body.\n   *\n   * A token endpoint's reply carries credentials even when it fails — several vendors echo the\n   * submitted client secret back in a validation message — so the message is logged with its detail\n   * and answered without it.\n   */\n  private handleControllerError(error: unknown, res: Response, action: string): void {\n    this.logger.error?.(`[oauth2-connect] failed to ${action}`, { error: describeCaughtError(error) });\n    if (isWildoBackendError(error) && error.type === ErrorType.AUTHENTICATION) {\n      res.status(401).json({ error: 'UNAUTHENTICATED', message: 'Sign in and try again.' });\n      return;\n    }\n    res.status(502).json({\n      error: 'CONNECTION_FAILED',\n      message: `Could not ${action}. The detail is in the application log.`,\n    });\n  }\n}\n"]}