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

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

@@ -0,0 +1,299 @@
+/**
+ * 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.
+ */
+import 'reflect-metadata';
+import { AbstractControllerBackendService } from '../../../base-classes/services/controllers/abstract-controller.backend.service';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+import type { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service';
+import type { ErrorHandlerService } from '../../../errors/services/error-handler.backend.service';
+import type { AuthJwtGuardBackendService } from '../../../security/jwt/services/auth-jwt-guard.backend.service';
+import type { AuthExecutionContextFactoryBackendService } from '../../../security/authentications/services/auth-execution-context-factory.backend.service';
+import type { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service';
+import type { ExternalProvidersRegistryBackendService } from '../../../external-providers/services/external-providers-registry.backend.service';
+import type { ConnectionTargetAuthorizationPort } from '../../../base-classes/services/repositories/http-api/http-api-provider-access.backend';
+import type { AppConfigurationService } from '../../../config/services/app-configuration.backend.service';
+import type { ProviderOAuth2PendingAuthorizationBackendService } from '../services/provider-oauth2-pending-authorization.backend.service';
+import type { UserProviderCredentialStoreBackendService } from '../services/user-provider-credential-store.backend.service';
+import type { OrganizationProviderCredentialStoreBackendService } from '../services/organization-provider-credential-store.backend.service';
+export declare class ProviderConnectionControllerBackendService extends AbstractControllerBackendService {
+    private readonly authJwtGuard;
+    private readonly authEcFactory;
+    private readonly registry;
+    private readonly pending;
+    private readonly targetAuthorization;
+    private readonly userCredentials;
+    private readonly organizationCredentials;
+    private readonly appConfig;
+    private readonly ecCreator;
+    constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, authJwtGuard: AuthJwtGuardBackendService, authEcFactory: AuthExecutionContextFactoryBackendService, registry: ExternalProvidersRegistryBackendService, pending: ProviderOAuth2PendingAuthorizationBackendService, targetAuthorization: ConnectionTargetAuthorizationPort, userCredentials: UserProviderCredentialStoreBackendService, organizationCredentials: OrganizationProviderCredentialStoreBackendService, appConfig: AppConfigurationService, ecCreator: ExecutionContextCreatorBackendService);
+    protected setupRoutes(): void;
+    /**
+     * What can be connected — the question the stored-credential list cannot answer.
+     *
+     * A settings screen listing somebody's connections shows an empty table on the day they have none,
+     * which is precisely the day they need to learn what they might connect. So the CATALOGUE and the
+     * ROWS are two reads, deliberately: this one is about the provider, the resource LIST is about the
+     * person, and merging them would make "nothing connected" and "nothing connectable" indistinguishable.
+     *
+     * ## It reports a DECISION, and computes nothing
+     *
+     * `admissibleConnections` is the recorded decision in the provider's catalogue record — never
+     * derived from what a vendor's API happens to support. A vendor with a personal-token endpoint does
+     * not thereby become a provider a person may connect individually; somebody decided that, and this
+     * route repeats what they decided.
+     *
+     * ## It answers ADMISSIBILITY, not AUTHORIZATION, and that split is not laziness
+     *
+     * Whether this caller may act for a given owner depends on the owner's ID, which a catalogue has
+     * none of — an organization-scoped shape is admissible for the provider while the caller may be
+     * entitled to act for one tenant and not another. So the start leg keeps both gates in the same
+     * order every credential path uses, and a screen that renders an owner it cannot act for gets a
+     * 403 there rather than a silently missing row here.
+     *
+     * ## Nothing here is a secret
+     *
+     * Which vendors an application integrates with is a property of the application, visible on its own
+     * marketing pages. No token, no client secret, no env-var VALUE is reported — `connectionParameters`
+     * names the placeholders a connection must ANSWER, which is an input to ask a person for.
+     */
+    /**
+     * Hands the CALLER their own short-lived access token for one provider (#394 P4).
+     *
+     * ## Why a browser is handed a token at all
+     *
+     * A vendor's picker authorizes as the signed-in user. Drive's cannot render without that user's
+     * OAuth2 token, so the token is in the browser during picking whether the selected bytes are later
+     * fetched by the backend (`REMOTE_REFERENCE`) or not. #383 named a user-consented token a
+     * browser-safe grant for exactly this reason: it is the PERSON's grant, not the tenant's credential.
+     *
+     * ## What keeps this the one safe door
+     *
+     * - **The caller's own account, and nobody else's.** The row is resolved as `{ userId: caller }`;
+     *   there is no target in the request to name another owner, so `mayActFor` has nothing to decide.
+     * - **Admissibility is the provider's recorded decision**, the same catalogue `start` consults: a
+     *   provider that does not admit a user-owned, self-delegated connection has no grant to hand out.
+     * - **Never the refresh token.** The resolution carries the access token, its expiry and its
+     *   scopes; the refresh token stays in the sealed row and the renewal happens here, server-side.
+     * - **Every hand-out is a USE.** `recordCredentialUse` emits `USER_PROVIDER_CREDENTIAL_USED` and
+     *   stamps `lastUsedAt`, so a token that left the process is visible against the revocation and
+     *   erasure that end it.
+     * - **404 when nothing is connected**, so a surface can offer the connection instead of opening a
+     *   picker on nobody's files — the picker's own `onError` then names what is missing.
+     *
+     * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a person's delegated grant reaches
+     * the browser only as their own, only as an access token, and only as a recorded use.
+     */
+    private handleAccessToken;
+    private handleCatalogue;
+    /**
+     * 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.
+     */
+    private handleStoreCredential;
+    /**
+     * 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.
+     */
+    private storeDeclaredSecretForTarget;
+    /**
+     * 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.
+     */
+    private handleStart;
+    /**
+     * 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.
+     */
+    private handleCallback;
+    /**
+     * 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.
+     */
+    private handleComplete;
+    /**
+     * 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).
+     */
+    private finishInBrowser;
+    /**
+     * 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.
+     */
+    private storeGrantForTarget;
+    /**
+     * 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.
+     */
+    private connectabilityBlocker;
+    /**
+     * May this caller act for that owner?
+     *
+     * An APPLICATION target has exactly one instance and the application IS the caller, so there is no
+     * second party whose account might be spent. Every other target goes through the same membership
+     * port the resolution path uses — one answer to "may this execution act for that owner", not two
+     * that can disagree.
+     *
+     * ## The context is built from the REQUEST, and that is the whole correctness of this method
+     *
+     * The port decides an ORGANIZATION target by asking `initiatorRoles` which tenants the caller
+     * belongs to organization-wide. So it can only answer from a context whose roles were built from
+     * real memberships — which is what `createExecutionContextForManualController` does, and what the
+     * auth-flow factory deliberately does not.
+     *
+     * This asked `authEcFactory.createForAuthenticatedAuthOperation` until 2026-09-10, and that
+     * factory hardcodes `initiatorRoles` to a single APPLICATION-scoped `APP_USER` entry — correct for
+     * its own audience (token issuance, password change, TOTP), which asks no membership question, and
+     * taken verbatim by the creator rather than enriched. `organizationWideMembershipsOf` filters that
+     * array on `relatedPrimaryScope === ORGANIZATIONS`, so it was ALWAYS empty and every organization
+     * target was refused — for every caller, every tenant, both routes. Measured on the running stack:
+     * `application × service` and `user × service` minted an authorize URL while an `ORG_OWNER`'s
+     * `organization × user` answered 403, which is the one combination 75 vendors declare and the one
+     * this lane exists for.
+     *
+     * The fix is here rather than in the factory on purpose: giving that factory a membership read
+     * would put a repository round trip on every token refresh to answer a question its callers never
+     * ask. This path is a settings-screen click.
+     *
+     * Built only on the ORGANIZATION branch, for the same reason: APPLICATION admits without a caller
+     * and USER compares two ids, so neither reads a role and neither should pay for one.
+     */
+    private mayActFor;
+    /**
+     * 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.
+     */
+    private canonicalSecretRef;
+    private requireClientId;
+    private requireClientSecret;
+    /**
+     * 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.
+     */
+    private callbackUrlFor;
+    private extractCaller;
+    /**
+     * 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.
+     */
+    private handleControllerError;
+}
+//# sourceMappingURL=provider-connection.controller.backend.service.d.ts.map

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;AAuB1B,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,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAC1J,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,iGAAiG,CAAC;AAIzJ,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;AAwF5I,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;IACL,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAXzD,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,EACb,SAAS,EAAE,qCAAqC;IAKrI,SAAS,CAAC,WAAW,IAAI,IAAI;IAmC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,iBAAiB;YAiDjB,eAAe;IAsF7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;YACW,qBAAqB;IAgGnC;;;;;OAKG;YACW,4BAA4B;IAoB1C;;;;;;;OAOG;YACW,WAAW;IAwGzB;;;;;OAKG;YACW,cAAc;IA+C5B;;;;;;;;;;;;;;;;;OAiBG;YACW,cAAc;IAkE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,eAAe;IAgCvB;;;;;;;;;OASG;YACW,mBAAmB;IA2BjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;YACW,SAAS;IAevB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,mBAAmB;IAa3B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;YAQR,aAAa;IAK3B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;CA2B9B"}