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

package/dist/esm/security/connected-accounts/services/provider-oauth2-exchange.backend.js

@@ -0,0 +1,266 @@
+/**
+ * The OAuth2 authorization-code exchange, as three pure-ish functions.
+ *
+ * This is the half of the connect flow that has no HTTP route, no session and no database: build the
+ * URL a person is sent to, turn the code they come back with into a grant, and renew a grant that is
+ * about to expire. The route, the state record and the store are a thin shell around it.
+ *
+ * Written as functions over an explicit contract rather than as a service with injected collaborators
+ * for one reason: every interesting failure here is a WRONG STRING — a placeholder that was never
+ * resolved, a scope set that silently shrank, a redirect URI that does not match the one registered.
+ * Those are answerable by a unit test only if the inputs are arguments, and they are the failures
+ * that reach a person as "the vendor says no" with nothing local to look at.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not store anything, does not read a credential, and does not decide WHO may connect. The
+ * connection target (whose account is being connected) and its admissibility are decided before this
+ * is reached, by the same two gates every other credential path goes through.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization exchange by which a
+ * principal grants this application access to a third party on their behalf.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { ProviderStoredCredentialKind } from '@wildo-ai/saas-models';
+/** Raised when an exchange cannot be built or completed. Never carries a token or a client secret. */
+export class ProviderOAuth2ExchangeError extends Error {
+    /**
+     * The vendor's own OAuth2 error code, when the failure was one the vendor NAMED.
+     *
+     * Carried structurally rather than only inside the message, because one caller has to act on it
+     * differently from every other failure: a grant the vendor has permanently rejected must stop
+     * presenting itself as a working connection, while a token endpoint that was merely unreachable
+     * must not. Both arrive here as the same class, and a message substring is not something to branch
+     * a person's account state on.
+     *
+     * Absent for transport failures, unparseable bodies and bare HTTP statuses — cases where the
+     * vendor said nothing about the grant, and where assuming anything about it would be a guess.
+     */
+    oauth2ErrorCode;
+    constructor(message, oauth2ErrorCode) {
+        super(message);
+        this.name = 'ProviderOAuth2ExchangeError';
+        this.oauth2ErrorCode = oauth2ErrorCode;
+    }
+}
+/**
+ * Is this failure the vendor saying the grant itself is finished?
+ *
+ * TRUE for exactly one code. `invalid_grant` is defined as an authorization grant or refresh token
+ * that is invalid, expired, revoked, or was issued to another client — every one of which is
+ * permanent for THIS connection and none of which a retry improves.
+ * spec-cite: RFC 6749 §5.2 (invalid_grant).
+ *
+ * Deliberately NOT `invalid_client`, and that exclusion is the substantive half. `invalid_client`
+ * means the APPLICATION's own registration was rejected — a wrong client secret, a deleted vendor
+ * app — which is an operator's problem affecting every connection at once. Treating it as a dead
+ * grant would mark every person's account invalid and invite them all to reconnect, which cannot
+ * work and would blame them for a misconfiguration they cannot see.
+ *
+ * Also FALSE for every failure the vendor did not name: a transport error, a non-JSON body, a bare
+ * 500. A vendor that was unreachable has said nothing about the grant, and a connection must not be
+ * retired on our inability to ask.
+ */
+export function providerOAuth2GrantWasPermanentlyRejected(error) {
+    return error instanceof ProviderOAuth2ExchangeError && error.oauth2ErrorCode === 'invalid_grant';
+}
+export function createProviderOAuth2Pkce() {
+    // 32 bytes base64url is 43 characters — the minimum the specification allows for a verifier, and
+    // the length every major vendor's documentation uses.
+    // spec-cite: RFC 7636 §4.1 (code_verifier: 43–128 characters).
+    const verifier = randomBytes(32).toString('base64url');
+    return {
+        verifier,
+        challenge: createHash('sha256').update(verifier).digest('base64url'),
+        method: 'S256',
+    };
+}
+/**
+ * Compare two opaque values in constant time.
+ *
+ * Used for the `state` echo. A plain `===` leaks the position of the first differing byte through
+ * timing, and `state` is the CSRF defence for the whole flow: an attacker who can guess it can graft
+ * their own authorization code onto somebody else's connect attempt.
+ */
+export function providerOAuth2ValuesMatch(left, right) {
+    const a = Buffer.from(left, 'utf8');
+    const b = Buffer.from(right, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** A fresh, unguessable `state` for one authorization attempt. */
+export function createProviderOAuth2State() {
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Resolve the `{placeholder}` holes an endpoint carries from the connection's own parameters.
+ *
+ * REFUSES on a missing value rather than leaving the brace in place. A URL still carrying
+ * `{tenantId}` is not a URL: it would be sent to the person's browser, fail to resolve as a
+ * hostname, and present as "the vendor is down" — a very long way from "nobody asked which
+ * directory". 21 of the 96 vendors that recovered both endpoints are in this population.
+ */
+export function resolveEndpointPlaceholders(url, connectionParameters, providerRef) {
+    return url.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+        const value = connectionParameters[name];
+        if (value === undefined || value === '') {
+            throw new ProviderOAuth2ExchangeError(`Provider '${providerRef}' needs a value for '${name}' before its OAuth2 endpoints are usable — `
+                + `'${url}' still carries the placeholder. This is a fact about the ACCOUNT being connected `
+                + '(which cloud, which directory, which region), so it is asked for at connect time and is not '
+                + 'application configuration.');
+        }
+        return encodeURIComponent(value);
+    });
+}
+/**
+ * The URL a person is sent to in order to grant access.
+ *
+ * Query parameters are MERGED into whatever the vendor's own authorize URL already carries rather
+ * than appended blindly. That is not tidiness: Slack's catalogue-declared authorize URL arrives with
+ * a `?user_scope=…` query string baked in, so appending `?client_id=…` would produce a URL with two
+ * `?` and a vendor that rejects it. One vendor of 129 does this today, which is exactly the kind of
+ * single-instance shape that a naive concatenation gets wrong forever.
+ */
+export function buildProviderOAuth2AuthorizeUrl(input) {
+    const resolved = resolveEndpointPlaceholders(input.oauth2.authorizeUrl, input.connectionParameters ?? {}, input.providerRef);
+    let url;
+    try {
+        url = new URL(resolved);
+    }
+    catch {
+        throw new ProviderOAuth2ExchangeError(`Provider '${input.providerRef}' declares an authorize URL that is not a URL: '${resolved}'. `
+            + 'Correct it in the provider\'s authored supplement rather than at the call site.');
+    }
+    const scopes = input.scopes ?? input.oauth2.scopes ?? [];
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', input.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('state', input.state);
+    url.searchParams.set('code_challenge', input.pkce.challenge);
+    url.searchParams.set('code_challenge_method', input.pkce.method);
+    if (scopes.length > 0) {
+        // Space-delimited, which is the specification's encoding; `URLSearchParams` percent-encodes the
+        // spaces. Vendors that want commas are a per-vendor deviation and belong in an authored
+        // supplement, not in a guess here.
+        // spec-cite: RFC 6749 §3.3 (scope is expressed as a list of space-delimited strings).
+        url.searchParams.set('scope', scopes.join(' '));
+    }
+    return url.toString();
+}
+/**
+ * Turn the authorization code into a grant.
+ *
+ * The client credentials go in the BODY (`client_secret_post`) rather than a Basic header. Both are
+ * specified and a server must support Basic, but the body form is what every major vendor's own
+ * documentation shows and what their sandboxes accept; a vendor that requires Basic is a per-vendor
+ * deviation for an authored supplement.
+ * spec-cite: RFC 6749 §2.3.1 (client_secret_basic is required of servers; the body form is permitted).
+ */
+export async function exchangeProviderOAuth2Code(input) {
+    return postToTokenEndpoint(input, {
+        grant_type: 'authorization_code',
+        code: input.code,
+        redirect_uri: input.redirectUri,
+        code_verifier: input.pkceVerifier,
+    });
+}
+/**
+ * Renew a grant that is expiring.
+ *
+ * Carries the PREVIOUS grant's refresh token forward when the vendor does not return a new one.
+ * That is the difference between a connection that survives and one that dies on its second
+ * refresh: some vendors rotate the refresh token on every use and return the replacement, and
+ * others return only an access token and expect the original refresh token to be reused. Dropping
+ * it in the second case leaves a grant that cannot be refreshed again, and the failure arrives an
+ * hour later with nothing pointing at this function.
+ * spec-cite: RFC 6749 §6 (the authorization server MAY issue a new refresh token).
+ */
+export async function refreshProviderOAuth2Grant(input) {
+    if (input.grant.refreshToken === undefined) {
+        throw new ProviderOAuth2ExchangeError(`The stored grant for provider '${input.providerRef}' has no refresh token, so it cannot be renewed. `
+            + 'Reconnect the account. This is not a fault: several vendors issue non-expiring tokens with no '
+            + 'refresh, and a grant that reaches here has both an expiry and no way to renew it.');
+    }
+    const renewed = await postToTokenEndpoint(input, {
+        grant_type: 'refresh_token',
+        refresh_token: input.grant.refreshToken,
+    });
+    return {
+        ...renewed,
+        refreshToken: renewed.refreshToken ?? input.grant.refreshToken,
+        // The vendor need not restate the account or the scopes on a refresh; losing them would make a
+        // renewed connection describe itself less well than a fresh one.
+        accountRef: renewed.accountRef ?? input.grant.accountRef,
+        grantedScopes: renewed.grantedScopes ?? input.grant.grantedScopes,
+    };
+}
+async function postToTokenEndpoint(input, parameters) {
+    const tokenUrl = resolveEndpointPlaceholders(input.oauth2.tokenUrl, input.connectionParameters ?? {}, input.providerRef);
+    const body = new URLSearchParams({
+        ...parameters,
+        client_id: input.clientId,
+        client_secret: input.clientSecret,
+    });
+    const doFetch = input.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await doFetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                // Several vendors default to form-encoded responses without it, and one that does is
+                // indistinguishable from a malformed body at the parse below.
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+    }
+    catch (error) {
+        throw new ProviderOAuth2ExchangeError(`Could not reach the token endpoint for provider '${input.providerRef}' at ${tokenUrl}: `
+            + `${error instanceof Error ? error.message : 'unknown transport failure'}.`);
+    }
+    const text = await response.text();
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new ProviderOAuth2ExchangeError(`Provider '${input.providerRef}' answered its token endpoint with a non-JSON body (HTTP ${response.status}). `
+            + 'The body is not reproduced here because a token endpoint\'s response carries credentials.');
+    }
+    // An OAuth2 error can arrive with HTTP 200 — several vendors do this, Slack among them — so the
+    // status is not the authority on whether the exchange succeeded. Checking only `response.ok`
+    // would treat `{"ok":false,"error":"invalid_code"}` as a grant and store a row with no token.
+    if (typeof payload.error === 'string') {
+        throw new ProviderOAuth2ExchangeError(`Provider '${input.providerRef}' refused the token exchange: ${payload.error}`
+            + `${typeof payload.error_description === 'string' ? ` — ${payload.error_description}` : ''}.`, 
+        // The one failure the vendor NAMED. Carried structurally so a caller can tell a dead grant
+        // from an unreachable endpoint without matching on prose.
+        payload.error);
+    }
+    if (!response.ok) {
+        throw new ProviderOAuth2ExchangeError(`Provider '${input.providerRef}' answered HTTP ${response.status} to the token exchange with no error code.`);
+    }
+    if (typeof payload.access_token !== 'string' || payload.access_token.length === 0) {
+        throw new ProviderOAuth2ExchangeError(`Provider '${input.providerRef}' answered the token exchange without an access token. `
+            + 'Storing the response would create a connection that cannot authenticate anything.');
+    }
+    return {
+        kind: ProviderStoredCredentialKind.OAUTH2_GRANT,
+        accessToken: payload.access_token,
+        refreshToken: typeof payload.refresh_token === 'string' && payload.refresh_token.length > 0
+            ? payload.refresh_token
+            : undefined,
+        expiresAt: typeof payload.expires_in === 'number' && Number.isFinite(payload.expires_in)
+            ? new Date(Date.now() + payload.expires_in * 1000).toISOString()
+            : undefined,
+        // What the vendor actually GRANTED, which is not always what was asked for. Space-delimited per
+        // the specification; a vendor returning a comma-separated string is a per-vendor deviation.
+        // spec-cite: RFC 6749 §5.1 (scope, present if different from the one requested).
+        grantedScopes: typeof payload.scope === 'string' && payload.scope.length > 0
+            ? payload.scope.split(/\s+/).filter((scope) => scope.length > 0)
+            : undefined,
+    };
+}
+//# sourceMappingURL=provider-oauth2-exchange.backend.js.map

package/dist/esm/security/connected-accounts/services/provider-oauth2-exchange.backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-exchange.backend.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/provider-oauth2-exchange.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The OAuth2 authorization-code exchange, as three pure-ish functions.\n *\n * This is the half of the connect flow that has no HTTP route, no session and no database: build the\n * URL a person is sent to, turn the code they come back with into a grant, and renew a grant that is\n * about to expire. The route, the state record and the store are a thin shell around it.\n *\n * Written as functions over an explicit contract rather than as a service with injected collaborators\n * for one reason: every interesting failure here is a WRONG STRING — a placeholder that was never\n * resolved, a scope set that silently shrank, a redirect URI that does not match the one registered.\n * Those are answerable by a unit test only if the inputs are arguments, and they are the failures\n * that reach a person as \"the vendor says no\" with nothing local to look at.\n *\n * ## What this deliberately does NOT do\n *\n * It does not store anything, does not read a credential, and does not decide WHO may connect. The\n * connection target (whose account is being connected) and its admissibility are decided before this\n * is reached, by the same two gates every other credential path goes through.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization exchange by which a\n * principal grants this application access to a third party on their behalf.\n */\n\nimport { createHash, randomBytes, timingSafeEqual } from 'node:crypto';\n\nimport type { ProviderRestOAuth2 } from '@wildo-ai/external-connectors-models';\nimport { ProviderStoredCredentialKind, type ProviderOAuth2Grant } from '@wildo-ai/saas-models';\n\n/** Raised when an exchange cannot be built or completed. Never carries a token or a client secret. */\nexport class ProviderOAuth2ExchangeError extends Error {\n  /**\n   * The vendor's own OAuth2 error code, when the failure was one the vendor NAMED.\n   *\n   * Carried structurally rather than only inside the message, because one caller has to act on it\n   * differently from every other failure: a grant the vendor has permanently rejected must stop\n   * presenting itself as a working connection, while a token endpoint that was merely unreachable\n   * must not. Both arrive here as the same class, and a message substring is not something to branch\n   * a person's account state on.\n   *\n   * Absent for transport failures, unparseable bodies and bare HTTP statuses — cases where the\n   * vendor said nothing about the grant, and where assuming anything about it would be a guess.\n   */\n  public readonly oauth2ErrorCode?: string;\n\n  constructor(message: string, oauth2ErrorCode?: string) {\n    super(message);\n    this.name = 'ProviderOAuth2ExchangeError';\n    this.oauth2ErrorCode = oauth2ErrorCode;\n  }\n}\n\n/**\n * Is this failure the vendor saying the grant itself is finished?\n *\n * TRUE for exactly one code. `invalid_grant` is defined as an authorization grant or refresh token\n * that is invalid, expired, revoked, or was issued to another client — every one of which is\n * permanent for THIS connection and none of which a retry improves.\n * spec-cite: RFC 6749 §5.2 (invalid_grant).\n *\n * Deliberately NOT `invalid_client`, and that exclusion is the substantive half. `invalid_client`\n * means the APPLICATION's own registration was rejected — a wrong client secret, a deleted vendor\n * app — which is an operator's problem affecting every connection at once. Treating it as a dead\n * grant would mark every person's account invalid and invite them all to reconnect, which cannot\n * work and would blame them for a misconfiguration they cannot see.\n *\n * Also FALSE for every failure the vendor did not name: a transport error, a non-JSON body, a bare\n * 500. A vendor that was unreachable has said nothing about the grant, and a connection must not be\n * retired on our inability to ask.\n */\nexport function providerOAuth2GrantWasPermanentlyRejected(error: unknown): boolean {\n  return error instanceof ProviderOAuth2ExchangeError && error.oauth2ErrorCode === 'invalid_grant';\n}\n\n/**\n * The PKCE pair for one authorization attempt.\n *\n * PKCE is applied to EVERY exchange, including confidential-client ones that hold a secret, and that\n * is a deliberate default rather than a requirement of the grant type. It costs one hash and it\n * closes authorization-code interception, which is reachable here because the code arrives on a\n * redirect through the person's own browser — a channel this application does not control.\n * spec-cite: RFC 7636 §4.1–4.2 (code_verifier, code_challenge, S256).\n */\nexport interface ProviderOAuth2Pkce {\n  readonly verifier: string;\n  readonly challenge: string;\n  readonly method: 'S256';\n}\n\nexport function createProviderOAuth2Pkce(): ProviderOAuth2Pkce {\n  // 32 bytes base64url is 43 characters — the minimum the specification allows for a verifier, and\n  // the length every major vendor's documentation uses.\n  // spec-cite: RFC 7636 §4.1 (code_verifier: 43–128 characters).\n  const verifier = randomBytes(32).toString('base64url');\n  return {\n    verifier,\n    challenge: createHash('sha256').update(verifier).digest('base64url'),\n    method: 'S256',\n  };\n}\n\n/**\n * Compare two opaque values in constant time.\n *\n * Used for the `state` echo. A plain `===` leaks the position of the first differing byte through\n * timing, and `state` is the CSRF defence for the whole flow: an attacker who can guess it can graft\n * their own authorization code onto somebody else's connect attempt.\n */\nexport function providerOAuth2ValuesMatch(left: string, right: string): boolean {\n  const a = Buffer.from(left, 'utf8');\n  const b = Buffer.from(right, 'utf8');\n  if (a.length !== b.length) return false;\n  return timingSafeEqual(a, b);\n}\n\n/** A fresh, unguessable `state` for one authorization attempt. */\nexport function createProviderOAuth2State(): string {\n  return randomBytes(32).toString('base64url');\n}\n\n/**\n * Resolve the `{placeholder}` holes an endpoint carries from the connection's own parameters.\n *\n * REFUSES on a missing value rather than leaving the brace in place. A URL still carrying\n * `{tenantId}` is not a URL: it would be sent to the person's browser, fail to resolve as a\n * hostname, and present as \"the vendor is down\" — a very long way from \"nobody asked which\n * directory\". 21 of the 96 vendors that recovered both endpoints are in this population.\n */\nexport function resolveEndpointPlaceholders(\n  url: string,\n  connectionParameters: Readonly<Record<string, string>>,\n  providerRef: string,\n): string {\n  return url.replace(/\\{([A-Za-z_][A-Za-z0-9_]*)\\}/g, (_match, name: string) => {\n    const value = connectionParameters[name];\n    if (value === undefined || value === '') {\n      throw new ProviderOAuth2ExchangeError(\n        `Provider '${providerRef}' needs a value for '${name}' before its OAuth2 endpoints are usable — `\n        + `'${url}' still carries the placeholder. This is a fact about the ACCOUNT being connected `\n        + '(which cloud, which directory, which region), so it is asked for at connect time and is not '\n        + 'application configuration.',\n      );\n    }\n    return encodeURIComponent(value);\n  });\n}\n\nexport interface BuildAuthorizeUrlInput {\n  readonly oauth2: ProviderRestOAuth2;\n  readonly providerRef: string;\n  readonly clientId: string;\n  /** Where the vendor sends the person back. Must be byte-identical to what is registered there. */\n  readonly redirectUri: string;\n  readonly state: string;\n  readonly pkce: ProviderOAuth2Pkce;\n  /** Values for the endpoints' `{placeholders}`, supplied by whoever is connecting. */\n  readonly connectionParameters?: Readonly<Record<string, string>>;\n  /**\n   * Scopes to request. Falls back to the vendor's own catalogue-declared set.\n   *\n   * Overridable because the catalogue's set is what the SOURCE asked for across every action it\n   * described, which is routinely broader than one application needs — and an over-broad consent\n   * screen is a thing a person refuses.\n   */\n  readonly scopes?: readonly string[];\n}\n\n/**\n * The URL a person is sent to in order to grant access.\n *\n * Query parameters are MERGED into whatever the vendor's own authorize URL already carries rather\n * than appended blindly. That is not tidiness: Slack's catalogue-declared authorize URL arrives with\n * a `?user_scope=…` query string baked in, so appending `?client_id=…` would produce a URL with two\n * `?` and a vendor that rejects it. One vendor of 129 does this today, which is exactly the kind of\n * single-instance shape that a naive concatenation gets wrong forever.\n */\nexport function buildProviderOAuth2AuthorizeUrl(input: BuildAuthorizeUrlInput): string {\n  const resolved = resolveEndpointPlaceholders(\n    input.oauth2.authorizeUrl,\n    input.connectionParameters ?? {},\n    input.providerRef,\n  );\n\n  let url: URL;\n  try {\n    url = new URL(resolved);\n  } catch {\n    throw new ProviderOAuth2ExchangeError(\n      `Provider '${input.providerRef}' declares an authorize URL that is not a URL: '${resolved}'. `\n      + 'Correct it in the provider\\'s authored supplement rather than at the call site.',\n    );\n  }\n\n  const scopes = input.scopes ?? input.oauth2.scopes ?? [];\n  url.searchParams.set('response_type', 'code');\n  url.searchParams.set('client_id', input.clientId);\n  url.searchParams.set('redirect_uri', input.redirectUri);\n  url.searchParams.set('state', input.state);\n  url.searchParams.set('code_challenge', input.pkce.challenge);\n  url.searchParams.set('code_challenge_method', input.pkce.method);\n  if (scopes.length > 0) {\n    // Space-delimited, which is the specification's encoding; `URLSearchParams` percent-encodes the\n    // spaces. Vendors that want commas are a per-vendor deviation and belong in an authored\n    // supplement, not in a guess here.\n    // spec-cite: RFC 6749 §3.3 (scope is expressed as a list of space-delimited strings).\n    url.searchParams.set('scope', scopes.join(' '));\n  }\n  return url.toString();\n}\n\n/** What a token endpoint gives back, before it becomes a stored grant. */\ninterface TokenEndpointResponse {\n  readonly access_token?: unknown;\n  readonly refresh_token?: unknown;\n  readonly expires_in?: unknown;\n  readonly scope?: unknown;\n  readonly token_type?: unknown;\n  readonly error?: unknown;\n  readonly error_description?: unknown;\n}\n\nexport interface TokenExchangeInput {\n  readonly oauth2: ProviderRestOAuth2;\n  readonly providerRef: string;\n  readonly clientId: string;\n  readonly clientSecret: string;\n  readonly connectionParameters?: Readonly<Record<string, string>>;\n  readonly fetchImpl?: typeof fetch;\n}\n\n/**\n * Turn the authorization code into a grant.\n *\n * The client credentials go in the BODY (`client_secret_post`) rather than a Basic header. Both are\n * specified and a server must support Basic, but the body form is what every major vendor's own\n * documentation shows and what their sandboxes accept; a vendor that requires Basic is a per-vendor\n * deviation for an authored supplement.\n * spec-cite: RFC 6749 §2.3.1 (client_secret_basic is required of servers; the body form is permitted).\n */\nexport async function exchangeProviderOAuth2Code(\n  input: TokenExchangeInput & { readonly code: string; readonly redirectUri: string; readonly pkceVerifier: string },\n): Promise<ProviderOAuth2Grant> {\n  return postToTokenEndpoint(input, {\n    grant_type: 'authorization_code',\n    code: input.code,\n    redirect_uri: input.redirectUri,\n    code_verifier: input.pkceVerifier,\n  });\n}\n\n/**\n * Renew a grant that is expiring.\n *\n * Carries the PREVIOUS grant's refresh token forward when the vendor does not return a new one.\n * That is the difference between a connection that survives and one that dies on its second\n * refresh: some vendors rotate the refresh token on every use and return the replacement, and\n * others return only an access token and expect the original refresh token to be reused. Dropping\n * it in the second case leaves a grant that cannot be refreshed again, and the failure arrives an\n * hour later with nothing pointing at this function.\n * spec-cite: RFC 6749 §6 (the authorization server MAY issue a new refresh token).\n */\nexport async function refreshProviderOAuth2Grant(\n  input: TokenExchangeInput & { readonly grant: ProviderOAuth2Grant },\n): Promise<ProviderOAuth2Grant> {\n  if (input.grant.refreshToken === undefined) {\n    throw new ProviderOAuth2ExchangeError(\n      `The stored grant for provider '${input.providerRef}' has no refresh token, so it cannot be renewed. `\n      + 'Reconnect the account. This is not a fault: several vendors issue non-expiring tokens with no '\n      + 'refresh, and a grant that reaches here has both an expiry and no way to renew it.',\n    );\n  }\n  const renewed = await postToTokenEndpoint(input, {\n    grant_type: 'refresh_token',\n    refresh_token: input.grant.refreshToken,\n  });\n  return {\n    ...renewed,\n    refreshToken: renewed.refreshToken ?? input.grant.refreshToken,\n    // The vendor need not restate the account or the scopes on a refresh; losing them would make a\n    // renewed connection describe itself less well than a fresh one.\n    accountRef: renewed.accountRef ?? input.grant.accountRef,\n    grantedScopes: renewed.grantedScopes ?? input.grant.grantedScopes,\n  };\n}\n\nasync function postToTokenEndpoint(\n  input: TokenExchangeInput,\n  parameters: Readonly<Record<string, string>>,\n): Promise<ProviderOAuth2Grant> {\n  const tokenUrl = resolveEndpointPlaceholders(\n    input.oauth2.tokenUrl,\n    input.connectionParameters ?? {},\n    input.providerRef,\n  );\n\n  const body = new URLSearchParams({\n    ...parameters,\n    client_id: input.clientId,\n    client_secret: input.clientSecret,\n  });\n\n  const doFetch = input.fetchImpl ?? fetch;\n  let response: Response;\n  try {\n    response = await doFetch(tokenUrl, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/x-www-form-urlencoded',\n        // Several vendors default to form-encoded responses without it, and one that does is\n        // indistinguishable from a malformed body at the parse below.\n        accept: 'application/json',\n      },\n      body: body.toString(),\n    });\n  } catch (error) {\n    throw new ProviderOAuth2ExchangeError(\n      `Could not reach the token endpoint for provider '${input.providerRef}' at ${tokenUrl}: `\n      + `${error instanceof Error ? error.message : 'unknown transport failure'}.`,\n    );\n  }\n\n  const text = await response.text();\n  let payload: TokenEndpointResponse;\n  try {\n    payload = JSON.parse(text) as TokenEndpointResponse;\n  } catch {\n    throw new ProviderOAuth2ExchangeError(\n      `Provider '${input.providerRef}' answered its token endpoint with a non-JSON body (HTTP ${response.status}). `\n      + 'The body is not reproduced here because a token endpoint\\'s response carries credentials.',\n    );\n  }\n\n  // An OAuth2 error can arrive with HTTP 200 — several vendors do this, Slack among them — so the\n  // status is not the authority on whether the exchange succeeded. Checking only `response.ok`\n  // would treat `{\"ok\":false,\"error\":\"invalid_code\"}` as a grant and store a row with no token.\n  if (typeof payload.error === 'string') {\n    throw new ProviderOAuth2ExchangeError(\n      `Provider '${input.providerRef}' refused the token exchange: ${payload.error}`\n      + `${typeof payload.error_description === 'string' ? ` — ${payload.error_description}` : ''}.`,\n      // The one failure the vendor NAMED. Carried structurally so a caller can tell a dead grant\n      // from an unreachable endpoint without matching on prose.\n      payload.error,\n    );\n  }\n  if (!response.ok) {\n    throw new ProviderOAuth2ExchangeError(\n      `Provider '${input.providerRef}' answered HTTP ${response.status} to the token exchange with no error code.`,\n    );\n  }\n  if (typeof payload.access_token !== 'string' || payload.access_token.length === 0) {\n    throw new ProviderOAuth2ExchangeError(\n      `Provider '${input.providerRef}' answered the token exchange without an access token. `\n      + 'Storing the response would create a connection that cannot authenticate anything.',\n    );\n  }\n\n  return {\n    kind: ProviderStoredCredentialKind.OAUTH2_GRANT,\n    accessToken: payload.access_token,\n    refreshToken: typeof payload.refresh_token === 'string' && payload.refresh_token.length > 0\n      ? payload.refresh_token\n      : undefined,\n    expiresAt: typeof payload.expires_in === 'number' && Number.isFinite(payload.expires_in)\n      ? new Date(Date.now() + payload.expires_in * 1000).toISOString()\n      : undefined,\n    // What the vendor actually GRANTED, which is not always what was asked for. Space-delimited per\n    // the specification; a vendor returning a comma-separated string is a per-vendor deviation.\n    // spec-cite: RFC 6749 §5.1 (scope, present if different from the one requested).\n    grantedScopes: typeof payload.scope === 'string' && payload.scope.length > 0\n      ? payload.scope.split(/\\s+/).filter((scope) => scope.length > 0)\n      : undefined,\n  };\n}\n"]}

package/dist/esm/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The record of ONE in-flight authorization attempt, from the redirect out to the callback back.
+ *
+ * ## Why this is ephemeral state and not a resource
+ *
+ * It exists for the seconds a person spends on a vendor's consent screen and is worthless
+ * afterwards. Deleting the whole store costs those people one retry and nothing else — the test
+ * `one-source-of-truth.md` applies: losing it costs TIME, never TRUTH, so it is a cache and must not
+ * become a table. A resource would also mean three migrations, a retention policy and an erasure
+ * question, for data whose correct lifetime is ten minutes.
+ *
+ * ## Single-use BY CONSTRUCTION, not by a flag
+ *
+ * Consumption is `GETDEL` — one round trip that returns the record and removes it atomically. So a
+ * replayed callback finds nothing, and there is no window in which two concurrent callbacks both
+ * read a record and both proceed. A `consumed: true` flag would have that window, and the attack it
+ * opens is real: an authorization code delivered twice is how a stolen code gets grafted onto a
+ * legitimate attempt.
+ *
+ * ## What it holds, and what it must never hold
+ *
+ * It holds the PKCE verifier, which is a secret for the length of the flow, and the connection
+ * target — whose account is being connected. It holds no token, because none exists yet.
+ *
+ * The TARGET is here rather than in the callback's query string for the reason the whole `state`
+ * mechanism exists: everything that comes back from the vendor arrives through the person's own
+ * browser and is therefore attacker-controllable. A callback that read the owner from its own URL
+ * would let somebody choose whose account a grant is stored against.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization attempt is bound to
+ * the principal who started it.
+ */
+import type { ExternalProvider_ConnectionTarget } from '@wildo-ai/external-connectors-models';
+import type { RedisService } from '../../../databases/services/redis.service';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+/**
+ * Ten minutes.
+ *
+ * Long enough for somebody to read a consent screen, find the right account and sign in to the
+ * vendor if they were signed out. Short enough that an abandoned attempt — and the PKCE verifier
+ * inside it — does not sit in the cache for a day. Every major vendor's own authorization codes
+ * expire in this range, so a longer window would keep a record whose code is already dead.
+ */
+export declare const PROVIDER_OAUTH2_PENDING_TTL_SECONDS = 600;
+export interface ProviderOAuth2PendingAuthorization {
+    /** Which provider is being connected. */
+    readonly providerRef: string;
+    /** The slot in the provider's secrets contract this grant will satisfy. */
+    readonly secretSlug: string;
+    /** WHOSE account is being connected. Never read back from the callback's URL. */
+    readonly target: ExternalProvider_ConnectionTarget;
+    /** The PKCE verifier, presented at the token exchange. Secret for the life of the record. */
+    readonly pkceVerifier: string;
+    /** The redirect URI sent at authorize; re-sent at the exchange and verified by the vendor. */
+    readonly redirectUri: string;
+    /** Values for the endpoints' `{placeholders}`, needed again to build the token URL. */
+    readonly connectionParameters?: Readonly<Record<string, string>>;
+    /**
+     * Who started the attempt, for the audit trail and for the callback's own authorization check.
+     *
+     * The callback re-checks that the person completing the flow is the person who began it. Without
+     * it, somebody who obtained a valid `state` could complete a connection while signed in as
+     * themselves and have the grant stored against the original initiator's target.
+     */
+    readonly initiatedByUserId?: string;
+    /**
+     * WHICH frontend the person came from, so the callback can send them back to it.
+     *
+     * Captured at START and carried here because the two legs reach the backend differently: the start
+     * leg is a FETCH from the application and carries Wildo's own headers, while the callback is a
+     * BROWSER NAVIGATION arriving from the vendor with none of them. Resolving the return URL at the
+     * callback from a header would therefore resolve nothing, and answering the browser with JSON —
+     * which this flow did until the omission was noticed — shows a person a raw payload instead of
+     * their settings screen.
+     *
+     * Optional because a caller that omits the header still gets a working CONNECTION; it only loses
+     * the redirect home, which is a worse experience rather than a broken one.
+     */
+    readonly frontendServiceName?: string;
+    /** When it was started, as an ISO instant — so an audit event can state how long consent took. */
+    readonly startedAt: string;
+}
+export declare class ProviderOAuth2PendingAuthorizationBackendService {
+    private readonly redis;
+    private readonly logger;
+    constructor(redis: RedisService, logger: LoggerService);
+    /**
+     * Remember one attempt against its `state`.
+     *
+     * The `state` IS the key. It is 32 random bytes, so it is unguessable, and using it directly means
+     * there is no second identifier that could get out of step with the one the vendor echoes back.
+     */
+    remember(state: string, pending: ProviderOAuth2PendingAuthorization): Promise<void>;
+    /**
+     * Take the attempt, removing it in the same round trip.
+     *
+     * `null` covers three situations a caller must treat identically — expired, already used, or never
+     * existed — and they MUST NOT be distinguished in any answer that reaches a browser. Telling an
+     * attacker that a `state` was valid but expired confirms they hold a real one.
+     */
+    consume(state: string): Promise<ProviderOAuth2PendingAuthorization | null>;
+    /**
+     * Namespaced, so nothing else in the cache can be addressed by supplying a crafted `state`.
+     *
+     * The state is used verbatim rather than hashed: it is already high-entropy and opaque, and
+     * hashing would only obscure which record a diagnostic is about while protecting nothing that the
+     * TTL does not already bound.
+     */
+    private keyFor;
+}
+//# sourceMappingURL=provider-oauth2-pending-authorization.backend.service.d.ts.map

package/dist/esm/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-pending-authorization.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,sCAAsC,CAAC;AAG9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAElG;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAIvD,MAAM,WAAW,kCAAkC;IACjD,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAC;IACnD,6FAA6F;IAC7F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kGAAkG;IAClG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBACa,gDAAgD;IAEhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADA,KAAK,EAAE,YAAY,EACzB,MAAM,EAAE,aAAa;IAG3E;;;;;OAKG;IACU,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kCAAkC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhG;;;;;;OAMG;IACU,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kCAAkC,GAAG,IAAI,CAAC;IAIvF;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;CAGf"}

package/dist/esm/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.js

@@ -0,0 +1,107 @@
+/**
+ * The record of ONE in-flight authorization attempt, from the redirect out to the callback back.
+ *
+ * ## Why this is ephemeral state and not a resource
+ *
+ * It exists for the seconds a person spends on a vendor's consent screen and is worthless
+ * afterwards. Deleting the whole store costs those people one retry and nothing else — the test
+ * `one-source-of-truth.md` applies: losing it costs TIME, never TRUTH, so it is a cache and must not
+ * become a table. A resource would also mean three migrations, a retention policy and an erasure
+ * question, for data whose correct lifetime is ten minutes.
+ *
+ * ## Single-use BY CONSTRUCTION, not by a flag
+ *
+ * Consumption is `GETDEL` — one round trip that returns the record and removes it atomically. So a
+ * replayed callback finds nothing, and there is no window in which two concurrent callbacks both
+ * read a record and both proceed. A `consumed: true` flag would have that window, and the attack it
+ * opens is real: an authorization code delivered twice is how a stolen code gets grafted onto a
+ * legitimate attempt.
+ *
+ * ## What it holds, and what it must never hold
+ *
+ * It holds the PKCE verifier, which is a secret for the length of the flow, and the connection
+ * target — whose account is being connected. It holds no token, because none exists yet.
+ *
+ * The TARGET is here rather than in the callback's query string for the reason the whole `state`
+ * mechanism exists: everything that comes back from the vendor arrives through the person's own
+ * browser and is therefore attacker-controllable. A callback that read the owner from its own URL
+ * would let somebody choose whose account a grant is stored against.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization attempt is bound to
+ * the principal who started it.
+ */
+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 { inject, injectable } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+/**
+ * Ten minutes.
+ *
+ * Long enough for somebody to read a consent screen, find the right account and sign in to the
+ * vendor if they were signed out. Short enough that an abandoned attempt — and the PKCE verifier
+ * inside it — does not sit in the cache for a day. Every major vendor's own authorization codes
+ * expire in this range, so a longer window would keep a record whose code is already dead.
+ */
+export const PROVIDER_OAUTH2_PENDING_TTL_SECONDS = 600;
+const KEY_PREFIX = 'oauth2-connect';
+let ProviderOAuth2PendingAuthorizationBackendService = class ProviderOAuth2PendingAuthorizationBackendService {
+    redis;
+    logger;
+    constructor(redis, logger) {
+        this.redis = redis;
+        this.logger = logger;
+    }
+    /**
+     * Remember one attempt against its `state`.
+     *
+     * The `state` IS the key. It is 32 random bytes, so it is unguessable, and using it directly means
+     * there is no second identifier that could get out of step with the one the vendor echoes back.
+     */
+    async remember(state, pending) {
+        await this.redis.set(this.keyFor(state), pending, { ttl: PROVIDER_OAUTH2_PENDING_TTL_SECONDS });
+        this.logger.debug?.('[oauth2-connect] authorization attempt recorded', {
+            providerRef: pending.providerRef,
+            ownerScope: pending.target.ownerScope,
+            // Never the state and never the verifier: both are secrets for the life of the record, and a
+            // debug log is the one place a secret most often escapes.
+        });
+    }
+    /**
+     * Take the attempt, removing it in the same round trip.
+     *
+     * `null` covers three situations a caller must treat identically — expired, already used, or never
+     * existed — and they MUST NOT be distinguished in any answer that reaches a browser. Telling an
+     * attacker that a `state` was valid but expired confirms they hold a real one.
+     */
+    async consume(state) {
+        return this.redis.getDel(this.keyFor(state));
+    }
+    /**
+     * Namespaced, so nothing else in the cache can be addressed by supplying a crafted `state`.
+     *
+     * The state is used verbatim rather than hashed: it is already high-entropy and opaque, and
+     * hashing would only obscure which record a diagnostic is about while protecting nothing that the
+     * TTL does not already bound.
+     */
+    keyFor(state) {
+        return `${KEY_PREFIX}:${state}`;
+    }
+};
+ProviderOAuth2PendingAuthorizationBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.RedisService)),
+    __param(1, inject(SAAS_SERVICE_TYPES.Logger)),
+    __metadata("design:paramtypes", [Function, Function])
+], ProviderOAuth2PendingAuthorizationBackendService);
+export { ProviderOAuth2PendingAuthorizationBackendService };
+//# sourceMappingURL=provider-oauth2-pending-authorization.backend.service.js.map

package/dist/esm/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-pending-authorization.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;;;;;;;;;;;AAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAIpF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AAEvD,MAAM,UAAU,GAAG,gBAAgB,CAAC;AA0C7B,IAAM,gDAAgD,GAAtD,MAAM,gDAAgD;IAEC;IACN;IAFtD,YAC4D,KAAmB,EACzB,MAAqB;QADf,UAAK,GAAL,KAAK,CAAc;QACzB,WAAM,GAAN,MAAM,CAAe;IACxE,CAAC;IAEJ;;;;;OAKG;IACI,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,OAA2C;QAC9E,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,mCAAmC,EAAE,CAAC,CAAC;QAChG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,iDAAiD,EAAE;YACrE,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU;YACrC,6FAA6F;YAC7F,0DAA0D;SAC3D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAO,CAAC,KAAa;QAChC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAqC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,KAAa;QAC1B,OAAO,GAAG,UAAU,IAAI,KAAK,EAAE,CAAC;IAClC,CAAC;CACF,CAAA;AA3CY,gDAAgD;IAD5D,UAAU,EAAE;IAGR,WAAA,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA;IACvC,WAAA,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;;GAHzB,gDAAgD,CA2C5D","sourcesContent":["/**\n * The record of ONE in-flight authorization attempt, from the redirect out to the callback back.\n *\n * ## Why this is ephemeral state and not a resource\n *\n * It exists for the seconds a person spends on a vendor's consent screen and is worthless\n * afterwards. Deleting the whole store costs those people one retry and nothing else — the test\n * `one-source-of-truth.md` applies: losing it costs TIME, never TRUTH, so it is a cache and must not\n * become a table. A resource would also mean three migrations, a retention policy and an erasure\n * question, for data whose correct lifetime is ten minutes.\n *\n * ## Single-use BY CONSTRUCTION, not by a flag\n *\n * Consumption is `GETDEL` — one round trip that returns the record and removes it atomically. So a\n * replayed callback finds nothing, and there is no window in which two concurrent callbacks both\n * read a record and both proceed. A `consumed: true` flag would have that window, and the attack it\n * opens is real: an authorization code delivered twice is how a stolen code gets grafted onto a\n * legitimate attempt.\n *\n * ## What it holds, and what it must never hold\n *\n * It holds the PKCE verifier, which is a secret for the length of the flow, and the connection\n * target — whose account is being connected. It holds no token, because none exists yet.\n *\n * The TARGET is here rather than in the callback's query string for the reason the whole `state`\n * mechanism exists: everything that comes back from the vendor arrives through the person's own\n * browser and is therefore attacker-controllable. A callback that read the owner from its own URL\n * would let somebody choose whose account a grant is stored against.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization attempt is bound to\n * the principal who started it.\n */\n\nimport { inject, injectable } from 'inversify';\nimport type { ExternalProvider_ConnectionTarget } from '@wildo-ai/external-connectors-models';\n\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { RedisService } from '~wildo-backend-lib/databases/services/redis.service';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\n\n/**\n * Ten minutes.\n *\n * Long enough for somebody to read a consent screen, find the right account and sign in to the\n * vendor if they were signed out. Short enough that an abandoned attempt — and the PKCE verifier\n * inside it — does not sit in the cache for a day. Every major vendor's own authorization codes\n * expire in this range, so a longer window would keep a record whose code is already dead.\n */\nexport const PROVIDER_OAUTH2_PENDING_TTL_SECONDS = 600;\n\nconst KEY_PREFIX = 'oauth2-connect';\n\nexport interface ProviderOAuth2PendingAuthorization {\n  /** Which provider is being connected. */\n  readonly providerRef: string;\n  /** The slot in the provider's secrets contract this grant will satisfy. */\n  readonly secretSlug: string;\n  /** WHOSE account is being connected. Never read back from the callback's URL. */\n  readonly target: ExternalProvider_ConnectionTarget;\n  /** The PKCE verifier, presented at the token exchange. Secret for the life of the record. */\n  readonly pkceVerifier: string;\n  /** The redirect URI sent at authorize; re-sent at the exchange and verified by the vendor. */\n  readonly redirectUri: string;\n  /** Values for the endpoints' `{placeholders}`, needed again to build the token URL. */\n  readonly connectionParameters?: Readonly<Record<string, string>>;\n  /**\n   * Who started the attempt, for the audit trail and for the callback's own authorization check.\n   *\n   * The callback re-checks that the person completing the flow is the person who began it. Without\n   * it, somebody who obtained a valid `state` could complete a connection while signed in as\n   * themselves and have the grant stored against the original initiator's target.\n   */\n  readonly initiatedByUserId?: string;\n  /**\n   * WHICH frontend the person came from, so the callback can send them back to it.\n   *\n   * Captured at START and carried here because the two legs reach the backend differently: the start\n   * leg is a FETCH from the application and carries Wildo's own headers, while the callback is a\n   * BROWSER NAVIGATION arriving from the vendor with none of them. Resolving the return URL at the\n   * callback from a header would therefore resolve nothing, and answering the browser with JSON —\n   * which this flow did until the omission was noticed — shows a person a raw payload instead of\n   * their settings screen.\n   *\n   * Optional because a caller that omits the header still gets a working CONNECTION; it only loses\n   * the redirect home, which is a worse experience rather than a broken one.\n   */\n  readonly frontendServiceName?: string;\n  /** When it was started, as an ISO instant — so an audit event can state how long consent took. */\n  readonly startedAt: string;\n}\n\n@injectable()\nexport class ProviderOAuth2PendingAuthorizationBackendService {\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redis: RedisService,\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n  ) {}\n\n  /**\n   * Remember one attempt against its `state`.\n   *\n   * The `state` IS the key. It is 32 random bytes, so it is unguessable, and using it directly means\n   * there is no second identifier that could get out of step with the one the vendor echoes back.\n   */\n  public async remember(state: string, pending: ProviderOAuth2PendingAuthorization): Promise<void> {\n    await this.redis.set(this.keyFor(state), pending, { ttl: PROVIDER_OAUTH2_PENDING_TTL_SECONDS });\n    this.logger.debug?.('[oauth2-connect] authorization attempt recorded', {\n      providerRef: pending.providerRef,\n      ownerScope: pending.target.ownerScope,\n      // Never the state and never the verifier: both are secrets for the life of the record, and a\n      // debug log is the one place a secret most often escapes.\n    });\n  }\n\n  /**\n   * Take the attempt, removing it in the same round trip.\n   *\n   * `null` covers three situations a caller must treat identically — expired, already used, or never\n   * existed — and they MUST NOT be distinguished in any answer that reaches a browser. Telling an\n   * attacker that a `state` was valid but expired confirms they hold a real one.\n   */\n  public async consume(state: string): Promise<ProviderOAuth2PendingAuthorization | null> {\n    return this.redis.getDel<ProviderOAuth2PendingAuthorization>(this.keyFor(state));\n  }\n\n  /**\n   * Namespaced, so nothing else in the cache can be addressed by supplying a crafted `state`.\n   *\n   * The state is used verbatim rather than hashed: it is already high-entropy and opaque, and\n   * hashing would only obscure which record a diagnostic is about while protecting nothing that the\n   * TTL does not already bound.\n   */\n  private keyFor(state: string): string {\n    return `${KEY_PREFIX}:${state}`;\n  }\n}\n"]}

package/dist/esm/security/connected-accounts/services/provider-oauth2-refresher.backend.service.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The token refresher — the port implementation over the provider registry.
+ *
+ * It reads the provider's OAuth2 contract and the application's client registration, performs the
+ * refresh exchange, and hands the renewed grant back. It persists nothing: the store that asked owns
+ * the table.
+ *
+ * ## Single-flight, and why it is not an optimisation
+ *
+ * Concurrent calls for the SAME connection collapse onto one exchange. Skipping this would be a
+ * correctness defect, not a performance one, for vendors that ROTATE the refresh token: two
+ * simultaneous refreshes both present the same refresh token, the vendor issues two grants and
+ * invalidates the first, and whichever write lands second stores a token the vendor has already
+ * revoked. The connection then fails on its next call, with two successful-looking refreshes in the
+ * log and nothing saying which one broke it.
+ *
+ * ## What it does NOT cover, stated rather than implied
+ *
+ * The flight is IN-PROCESS. Two backend instances refreshing the same connection at the same instant
+ * still race, and against a rotating vendor one of them still loses. Closing that needs a
+ * distributed lock, which is a Redis round trip on a path that runs before every outbound call — a
+ * cost worth paying only once a real deployment shows the collision. The narrower in-process case is
+ * the common one by a wide margin, because a burst of calls for one connection almost always arrives
+ * at one instance.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — delegated authority is renewed without
+ * a new act of consent, so the renewal is bounded by what the original grant carried.
+ */
+import type { ProviderOAuth2Grant } from '@wildo-ai/saas-models';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+import type { ExternalProvidersRegistryBackendService } from '../../../external-providers/services/external-providers-registry.backend.service';
+import type { ProviderOAuth2RefreshRequest, ProviderOAuth2RefresherPort } from '../provider-oauth2-refresher.port';
+export declare class ProviderOAuth2RefresherBackendService implements ProviderOAuth2RefresherPort {
+    private readonly logger;
+    private readonly externalProvidersRegistry;
+    /**
+     * One in-flight exchange per connection, keyed by the whole identity.
+     *
+     * Entries are removed in a `finally`, so a failed refresh does not wedge the connection — the next
+     * call starts a fresh attempt rather than awaiting a promise that already rejected.
+     */
+    private readonly inFlight;
+    constructor(logger: LoggerService, externalProvidersRegistry: ExternalProvidersRegistryBackendService);
+    refreshGrant(request: ProviderOAuth2RefreshRequest): Promise<ProviderOAuth2Grant>;
+    private performRefresh;
+    /**
+     * The whole connection identity, so two owners of the same provider never share a flight.
+     *
+     * Keying on the provider alone would make one tenant's refresh satisfy another's call and return
+     * the wrong account's token — the exact cross-owner substitution the resolution path refuses.
+     */
+    private flightKeyFor;
+}
+//# sourceMappingURL=provider-oauth2-refresher.backend.service.d.ts.map

package/dist/esm/security/connected-accounts/services/provider-oauth2-refresher.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-refresher.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/provider-oauth2-refresher.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAO1J,OAAO,KAAK,EACV,4BAA4B,EAC5B,2BAA2B,EAC5B,MAAM,mCAAmC,CAAC;AAE3C,qBACa,qCAAsC,YAAW,2BAA2B;IAUlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAE1D,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAX5C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmD;gBAGtB,MAAM,EAAE,aAAa,EAExD,yBAAyB,EAAE,uCAAuC;IAGxE,YAAY,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,mBAAmB,CAAC;YAkBhF,cAAc;IAoE5B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CASrB"}