@udibo/oauth2 0.1.0

package/esm/identity/external/oauth2.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Generic plain-OAuth2 connector: fixed authorize/token endpoints, an optional
+ * UserInfo endpoint, and a caller-supplied profile mapper. The connector for
+ * providers that speak OAuth2 but publish no OpenID Connect discovery document
+ * and issue no `id_token` — where {@link oidcProvider} does not apply and
+ * hand-rolling a full {@link ExternalProvider} would be repetitive.
+ *
+ * @module
+ */
+import type { ExternalProvider } from "./provider.js";
+/** The token-endpoint response fields the mapper may read. */
+export interface OAuth2TokenResult {
+    /** The bearer access token issued by the token endpoint. */
+    accessToken: string;
+    /** The token endpoint's full JSON body, for provider-specific fields. */
+    raw: Record<string, unknown>;
+}
+/** The normalized fields a {@link OAuth2ProfileMapper} returns. */
+export interface OAuth2ProfileMapping {
+    /** The provider's stable unique id for the user. Required and non-empty. */
+    subject: string;
+    /** The user's email, when the provider shared one. */
+    email?: string;
+    /**
+     * `true` only when the provider positively asserted the email is verified.
+     * Defaults to `false` — never auto-link on an unverified email.
+     */
+    emailVerified?: boolean;
+    /** Display name, when shared. */
+    name?: string;
+    /** Given (first) name, when shared. */
+    givenName?: string;
+    /** Family (last) name, when shared. */
+    familyName?: string;
+    /** Avatar/profile picture URL, when shared. */
+    picture?: string;
+}
+/**
+ * Maps a provider's raw profile (the UserInfo body, or the token response when
+ * no UserInfo endpoint is configured) to the normalized {@link ExternalProfile}
+ * fields. Throw {@link ExternalAuthError} `provider_error` when a required field
+ * (typically the subject) is absent.
+ */
+export type OAuth2ProfileMapper = (context: {
+    /** The UserInfo JSON, or the token response body when no UserInfo endpoint. */
+    profile: Record<string, unknown>;
+    /** The token-endpoint result, for providers that carry claims in it. */
+    tokens: OAuth2TokenResult;
+}) => OAuth2ProfileMapping;
+/** Options for {@link oauth2Provider}. */
+export interface OAuth2ProviderOptions {
+    /** Provider id used in {@link ExternalProfile.provider} and error messages. */
+    id: string;
+    /** Human-readable name for buttons and logs (e.g. `"Discord"`). */
+    displayName: string;
+    /** The provider's authorization endpoint (browser redirect target). */
+    authorizationEndpoint: string;
+    /** The provider's token endpoint (server-to-server code exchange). */
+    tokenEndpoint: string;
+    /**
+     * The provider's UserInfo endpoint, called with the bearer token to build the
+     * profile. Omit when the profile is carried in the token response itself.
+     */
+    userInfoEndpoint?: string;
+    /** The client id registered with the provider. */
+    clientId: string;
+    /** The matching client secret (sent as `client_secret` in the token body). */
+    clientSecret: string;
+    /** Turns the raw profile into normalized fields. */
+    mapProfile: OAuth2ProfileMapper;
+    /** Scopes requested when the caller passes none. */
+    defaultScopes: string[];
+    /** Scopes override; falls back to `defaultScopes`. */
+    scopes?: string[];
+    /** Separator joining scopes in the authorize URL. Defaults to a space. */
+    scopeSeparator?: string;
+    /** Whether to run PKCE (S256). Defaults to `false`. */
+    usesPkce?: boolean;
+    /** Extra fixed query params to add to the authorize URL. */
+    authorizationParams?: Record<string, string>;
+    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Creates a connector for a plain-OAuth2 provider from its fixed endpoints and
+ * a profile mapper.
+ *
+ * The exchange posts `authorization_code` to `tokenEndpoint` with the client
+ * credentials in the body (`client_secret_post`); the profile is read from
+ * `userInfoEndpoint` with the bearer token when set, else from the token
+ * response, and handed to `mapProfile`. Presets like {@link discordProvider}
+ * are thin wrappers over this.
+ *
+ * @example
+ * ```ts
+ * const provider = oauth2Provider({
+ *   id: "discord",
+ *   displayName: "Discord",
+ *   authorizationEndpoint: "https://discord.com/oauth2/authorize",
+ *   tokenEndpoint: "https://discord.com/api/oauth2/token",
+ *   userInfoEndpoint: "https://discord.com/api/users/@me",
+ *   clientId,
+ *   clientSecret,
+ *   defaultScopes: ["identify", "email"],
+ *   mapProfile: ({ profile }) => ({ subject: String(profile.id) }),
+ * });
+ * const flow = new ExternalAuthFlow({ provider });
+ * ```
+ */
+export declare function oauth2Provider(options: OAuth2ProviderOptions): ExternalProvider;

package/esm/identity/external/oauth2.js

@@ -0,0 +1,158 @@
+/**
+ * Generic plain-OAuth2 connector: fixed authorize/token endpoints, an optional
+ * UserInfo endpoint, and a caller-supplied profile mapper. The connector for
+ * providers that speak OAuth2 but publish no OpenID Connect discovery document
+ * and issue no `id_token` — where {@link oidcProvider} does not apply and
+ * hand-rolling a full {@link ExternalProvider} would be repetitive.
+ *
+ * @module
+ */
+import { generateCodeChallenge } from "../../utils/pkce.js";
+import { describeError, readErrorBody } from "./_shared.js";
+import { runTokenExchange } from "./_token-exchange.js";
+import { ExternalAuthError } from "./errors.js";
+/**
+ * Creates a connector for a plain-OAuth2 provider from its fixed endpoints and
+ * a profile mapper.
+ *
+ * The exchange posts `authorization_code` to `tokenEndpoint` with the client
+ * credentials in the body (`client_secret_post`); the profile is read from
+ * `userInfoEndpoint` with the bearer token when set, else from the token
+ * response, and handed to `mapProfile`. Presets like {@link discordProvider}
+ * are thin wrappers over this.
+ *
+ * @example
+ * ```ts
+ * const provider = oauth2Provider({
+ *   id: "discord",
+ *   displayName: "Discord",
+ *   authorizationEndpoint: "https://discord.com/oauth2/authorize",
+ *   tokenEndpoint: "https://discord.com/api/oauth2/token",
+ *   userInfoEndpoint: "https://discord.com/api/users/@me",
+ *   clientId,
+ *   clientSecret,
+ *   defaultScopes: ["identify", "email"],
+ *   mapProfile: ({ profile }) => ({ subject: String(profile.id) }),
+ * });
+ * const flow = new ExternalAuthFlow({ provider });
+ * ```
+ */
+export function oauth2Provider(options) {
+    const id = options.id;
+    const fetchImpl = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+    const scopeSeparator = options.scopeSeparator ?? " ";
+    async function exchangeCode(input) {
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            client_id: options.clientId,
+            client_secret: options.clientSecret,
+        });
+        if (input.codeVerifier)
+            body.set("code_verifier", input.codeVerifier);
+        const { value, raw } = await runTokenExchange({
+            provider: id,
+            displayName: options.displayName,
+            endpoint: options.tokenEndpoint,
+            body,
+            requiredField: "access_token",
+            fetch: fetchImpl,
+            httpErrorHint: `Check that clientId/clientSecret and the redirect URI ` +
+                `match the ${options.displayName} app registration, then try again.`,
+            tokenErrorHint: oauth2TokenErrorHint,
+        });
+        return { accessToken: value, raw };
+    }
+    async function fetchUserInfo(accessToken) {
+        let res;
+        try {
+            res = await fetchImpl(options.userInfoEndpoint, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    Accept: "application/json",
+                },
+            });
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `could not reach the ${options.displayName} profile endpoint ` +
+                `(${describeError(error)}). Try again.`, { cause: error });
+        }
+        if (!res.ok) {
+            const detail = await readErrorBody(res);
+            throw new ExternalAuthError(id, "provider_error", `profile endpoint responded with HTTP ${res.status}${detail}. The ` +
+                `access token was issued but lacks profile access — ensure the ` +
+                `identity scope is requested.`);
+        }
+        try {
+            return (await res.json());
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `the ${options.displayName} profile endpoint returned a response ` +
+                `that was not valid JSON (${describeError(error)}).`, { cause: error });
+        }
+    }
+    return {
+        id,
+        displayName: options.displayName,
+        defaultScopes: options.scopes ?? options.defaultScopes,
+        usesPkce: options.usesPkce ?? false,
+        usesNonce: false,
+        async buildAuthorizationUrl(input) {
+            const url = new URL(options.authorizationEndpoint);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("client_id", options.clientId);
+            url.searchParams.set("redirect_uri", input.redirectUri);
+            url.searchParams.set("scope", input.scopes.join(scopeSeparator));
+            url.searchParams.set("state", input.state);
+            for (const [key, value] of Object.entries(options.authorizationParams ?? {})) {
+                url.searchParams.set(key, value);
+            }
+            if (input.codeVerifier) {
+                url.searchParams.set("code_challenge", await generateCodeChallenge(input.codeVerifier));
+                url.searchParams.set("code_challenge_method", "S256");
+            }
+            if (input.prompt)
+                url.searchParams.set("prompt", input.prompt);
+            return url.toString();
+        },
+        async fetchProfile(input) {
+            const tokens = await exchangeCode(input);
+            const profile = options.userInfoEndpoint
+                ? await fetchUserInfo(tokens.accessToken)
+                : tokens.raw;
+            const mapped = options.mapProfile({ profile, tokens });
+            if (typeof mapped.subject !== "string" || mapped.subject.length === 0) {
+                throw new ExternalAuthError(id, "provider_error", `the ${options.displayName} profile is missing a stable subject id.`);
+            }
+            return {
+                provider: id,
+                subject: mapped.subject,
+                email: mapped.email,
+                emailVerified: mapped.emailVerified === true,
+                name: mapped.name,
+                givenName: mapped.givenName,
+                familyName: mapped.familyName,
+                picture: mapped.picture,
+                raw: profile,
+            };
+        },
+    };
+}
+function oauth2TokenErrorHint(error) {
+    if (error === "invalid_client" || error === "unauthorized_client") {
+        return `The provider rejected the client credentials — check clientId ` +
+            `and clientSecret against the app registration.`;
+    }
+    if (error === "invalid_grant") {
+        return `The provider rejected the code — it expired, was already used, ` +
+            `or the redirect URI does not match the registered one. Ask the user ` +
+            `to start again.`;
+    }
+    if (error === "invalid_scope") {
+        return `The provider rejected the requested scopes — check the ` +
+            `connector's scopes against what the app registration allows.`;
+    }
+    return `The code may have expired or already been used — ask the user to ` +
+        `start again.`;
+}

package/esm/identity/external/oidc.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Generic OpenID Connect connector: discovery-driven endpoints, PKCE + nonce,
+ * profile from id_token claims merged with the UserInfo response.
+ *
+ * @module
+ */
+import type { DiscoveryCache } from "../../client/discovery-cache.js";
+import { type AzpPolicy } from "./_shared.js";
+import type { ExternalProvider } from "./provider.js";
+/** Options for {@link oidcProvider}. */
+export interface OidcProviderOptions {
+    /** Provider id used in profiles and error messages. Defaults to `"oidc"`. */
+    id?: string;
+    /** Human-readable name for buttons and logs. Defaults to `"OpenID Connect"`. */
+    displayName?: string;
+    /**
+     * The provider's issuer URL. Endpoints are resolved from
+     * `${issuer}/.well-known/openid-configuration` (with an RFC 8414 fallback)
+     * on first use and cached.
+     */
+    issuer: string;
+    /** The client id registered with the provider. */
+    clientId: string;
+    /**
+     * The client secret, for providers that registered this app as a
+     * confidential client (sent via HTTP Basic auth on the token exchange).
+     * Omit for public clients — PKCE is always used either way.
+     */
+    clientSecret?: string;
+    /** Scopes requested by default. Defaults to `["openid", "email", "profile"]`. */
+    scopes?: string[];
+    /**
+     * How the id_token's `azp` claim is checked. Defaults to `"conditional"`
+     * (OpenID Connect Core §3.1.3.7). Set `"ignore"` only for a provider that
+     * reports a different authorized party than the client doing the exchange —
+     * see {@link AzpPolicy}.
+     */
+    azp?: AzpPolicy;
+    /** Fetch implementation for all provider traffic. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Cache the discovery document is read from and written to, shared with any
+     * other connector given the same instance. Supply one when the connector is
+     * rebuilt per request (a server resolving provider config from a database),
+     * or discovery is re-fetched on every sign-in leg. `MemoryDiscoveryCache`
+     * from `@udibo/oauth2/client` is the ready-made implementation.
+     */
+    discoveryCache?: DiscoveryCache;
+}
+/**
+ * Creates a connector for any spec-compliant OpenID Connect provider.
+ *
+ * The exchange reuses the package's `DirectClient` (discovery caching with
+ * both well-known paths, Basic client auth, RFC 6749 error mapping) with PKCE
+ * always on. The profile is built from the id_token claims, merged with the
+ * UserInfo response when the provider advertises a `userinfo_endpoint` (the
+ * UserInfo `sub` must match the id_token `sub` per OIDC Core §5.3.2, and a
+ * UserInfo failure is non-fatal — the id_token claims already suffice).
+ *
+ * **id_token validation:** the `iss`, `aud`, `azp` (when the token has multiple
+ * audiences or an `azp` claim, unless `azp: "ignore"` is configured), `exp`,
+ * and `nonce` claims are checked per OpenID Connect Core §3.1.3.7. The
+ * signature is deliberately **not** verified: the token arrives directly from
+ * the token endpoint over TLS, where §3.1.3.7 permits relying on TLS server
+ * validation instead of signature checks (rule 6). Every other rule —
+ * including expiry (rule 9) — still applies. Do not feed this connector
+ * id_tokens obtained out-of-band.
+ *
+ * @example
+ * ```ts
+ * const provider = oidcProvider({
+ *   id: "acme",
+ *   displayName: "Acme SSO",
+ *   issuer: "https://sso.acme.example",
+ *   clientId: "my-app",
+ *   clientSecret: Deno.env.get("ACME_CLIENT_SECRET")!,
+ * });
+ * const flow = new ExternalAuthFlow({ provider });
+ * ```
+ */
+export declare function oidcProvider(options: OidcProviderOptions): ExternalProvider;

package/esm/identity/external/oidc.js

@@ -0,0 +1,250 @@
+/**
+ * Generic OpenID Connect connector: discovery-driven endpoints, PKCE + nonce,
+ * profile from id_token claims merged with the UserInfo response.
+ *
+ * @module
+ */
+import { DirectClient } from "../../client/direct-client.js";
+import { MemoryAuthRequestStorage } from "../../client/storage.js";
+import { isOAuth2Error } from "../../errors.js";
+import { generateCodeChallenge } from "../../utils/pkce.js";
+import { assertIdTokenClaims, describeError, stripTrailingSlash, } from "./_shared.js";
+import { ExternalAuthError } from "./errors.js";
+/**
+ * Creates a connector for any spec-compliant OpenID Connect provider.
+ *
+ * The exchange reuses the package's `DirectClient` (discovery caching with
+ * both well-known paths, Basic client auth, RFC 6749 error mapping) with PKCE
+ * always on. The profile is built from the id_token claims, merged with the
+ * UserInfo response when the provider advertises a `userinfo_endpoint` (the
+ * UserInfo `sub` must match the id_token `sub` per OIDC Core §5.3.2, and a
+ * UserInfo failure is non-fatal — the id_token claims already suffice).
+ *
+ * **id_token validation:** the `iss`, `aud`, `azp` (when the token has multiple
+ * audiences or an `azp` claim, unless `azp: "ignore"` is configured), `exp`,
+ * and `nonce` claims are checked per OpenID Connect Core §3.1.3.7. The
+ * signature is deliberately **not** verified: the token arrives directly from
+ * the token endpoint over TLS, where §3.1.3.7 permits relying on TLS server
+ * validation instead of signature checks (rule 6). Every other rule —
+ * including expiry (rule 9) — still applies. Do not feed this connector
+ * id_tokens obtained out-of-band.
+ *
+ * @example
+ * ```ts
+ * const provider = oidcProvider({
+ *   id: "acme",
+ *   displayName: "Acme SSO",
+ *   issuer: "https://sso.acme.example",
+ *   clientId: "my-app",
+ *   clientSecret: Deno.env.get("ACME_CLIENT_SECRET")!,
+ * });
+ * const flow = new ExternalAuthFlow({ provider });
+ * ```
+ */
+export function oidcProvider(options) {
+    const id = options.id ?? "oidc";
+    assertSecureIssuer(id, options.issuer);
+    const displayName = options.displayName ?? "OpenID Connect";
+    const defaultScopes = options.scopes ?? ["openid", "email", "profile"];
+    const fetchImpl = (input, init) => {
+        assertSecureIssuer(id, input instanceof Request ? input.url : String(input));
+        return (options.fetch ?? globalThis.fetch)(input, {
+            ...init,
+            redirect: "error",
+        });
+    };
+    const authRequestStorage = new MemoryAuthRequestStorage();
+    const client = new DirectClient({
+        clientId: options.clientId,
+        ...(options.clientSecret === undefined
+            ? {}
+            : { clientSecret: options.clientSecret }),
+        issuer: options.issuer,
+        fetch: fetchImpl,
+        authRequestStorage,
+        discoveryCache: options.discoveryCache,
+    });
+    async function discover() {
+        let meta;
+        try {
+            meta = await client.discover();
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "configuration", `OIDC discovery failed for issuer "${options.issuer}" ` +
+                `(${describeError(error)}). Check that the issuer URL is correct ` +
+                `and serves "${wellKnownUrl(options.issuer)}".`, { cause: error });
+        }
+        if (normalizeIssuer(meta.issuer) !== normalizeIssuer(options.issuer)) {
+            throw new ExternalAuthError(id, "configuration", `discovery document "issuer" is "${String(meta.issuer)}" but the configured issuer is "${options.issuer}" — OpenID Connect ` +
+                `Discovery §4.3 / RFC 8414 §3.3 require them to be identical. The ` +
+                `configured issuer likely points at a proxy or the wrong tenant.`);
+        }
+        for (const endpoint of [
+            meta.authorization_endpoint,
+            meta.token_endpoint,
+            meta.userinfo_endpoint,
+        ]) {
+            if (endpoint !== undefined)
+                assertSecureIssuer(id, endpoint);
+        }
+        return meta;
+    }
+    async function exchangeCode(input) {
+        const exchangeKey = crypto.randomUUID();
+        await authRequestStorage.set(exchangeKey, {
+            codeVerifier: input.codeVerifier ?? "",
+            createdAt: Date.now(),
+        });
+        try {
+            const { raw } = await client.exchangeAuthorizationCode(input.code, exchangeKey, { redirectUri: input.redirectUri });
+            return raw;
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `token exchange failed (${describeError(error)}). ` +
+                tokenExchangeHint(error), { cause: error });
+        }
+        finally {
+            await authRequestStorage.delete(exchangeKey);
+        }
+    }
+    function decodeAndValidateIdToken(response, meta, expectedNonce) {
+        const idToken = response.id_token;
+        if (!idToken) {
+            throw new ExternalAuthError(id, "provider_error", `token response contained no id_token. Ensure the "openid" scope ` +
+                `is requested and that issuer "${options.issuer}" is an OpenID ` +
+                `Connect provider (for plain OAuth2 providers, implement ` +
+                `ExternalProvider directly).`);
+        }
+        let claims;
+        try {
+            claims = client.decodeIdToken(idToken);
+        }
+        catch (error) {
+            throw new ExternalAuthError(id, "provider_error", `token endpoint returned a malformed id_token ` +
+                `(${describeError(error)}).`, { cause: error });
+        }
+        assertIdTokenClaims({
+            provider: id,
+            claims,
+            issuer: meta.issuer,
+            clientId: options.clientId,
+            expectedNonce,
+            azp: options.azp,
+        });
+        return claims;
+    }
+    async function fetchUserInfoClaims(meta, accessToken, idTokenSub) {
+        if (!meta.userinfo_endpoint)
+            return null;
+        try {
+            const res = await fetchImpl(meta.userinfo_endpoint, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    Accept: "application/json",
+                },
+            });
+            if (!res.ok) {
+                await res.body?.cancel();
+                return null;
+            }
+            const info = (await res.json());
+            return info.sub === idTokenSub ? info : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        id,
+        displayName,
+        defaultScopes,
+        usesPkce: true,
+        usesNonce: true,
+        async buildAuthorizationUrl(input) {
+            const meta = await discover();
+            if (!meta.authorization_endpoint) {
+                throw new ExternalAuthError(id, "configuration", `issuer "${options.issuer}" metadata does not advertise an ` +
+                    `authorization_endpoint — it cannot drive a browser sign-in.`);
+            }
+            const url = new URL(meta.authorization_endpoint);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("client_id", options.clientId);
+            url.searchParams.set("redirect_uri", input.redirectUri);
+            url.searchParams.set("scope", input.scopes.join(" "));
+            url.searchParams.set("state", input.state);
+            if (input.nonce)
+                url.searchParams.set("nonce", input.nonce);
+            if (input.codeVerifier) {
+                url.searchParams.set("code_challenge", await generateCodeChallenge(input.codeVerifier));
+                url.searchParams.set("code_challenge_method", "S256");
+            }
+            if (input.prompt)
+                url.searchParams.set("prompt", input.prompt);
+            return url.toString();
+        },
+        async fetchProfile(input) {
+            const meta = await discover();
+            const response = await exchangeCode(input);
+            const claims = decodeAndValidateIdToken(response, meta, input.nonce);
+            const userInfo = await fetchUserInfoClaims(meta, response.access_token, claims.sub);
+            return profileFromOidcClaims(id, { ...claims, ...userInfo });
+        },
+    };
+}
+function profileFromOidcClaims(provider, claims) {
+    const subject = claims.sub;
+    if (typeof subject !== "string" || subject.length === 0) {
+        throw new ExternalAuthError(provider, "provider_error", `id_token is missing the required "sub" claim.`);
+    }
+    return {
+        provider,
+        subject,
+        email: asString(claims.email),
+        emailVerified: claims.email_verified === true,
+        name: asString(claims.name),
+        givenName: asString(claims.given_name),
+        familyName: asString(claims.family_name),
+        picture: asString(claims.picture),
+        raw: claims,
+    };
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function wellKnownUrl(issuer) {
+    return `${stripTrailingSlash(issuer)}/.well-known/openid-configuration`;
+}
+function normalizeIssuer(value) {
+    return stripTrailingSlash(typeof value === "string" ? value : "");
+}
+function assertSecureIssuer(id, issuer) {
+    let url;
+    try {
+        url = new URL(issuer);
+    }
+    catch {
+        throw new ExternalAuthError(id, "configuration", `issuer "${issuer}" is not a valid absolute URL.`);
+    }
+    const loopback = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new ExternalAuthError(id, "configuration", `issuer "${issuer}" must use https — this connector trusts the ` +
+            `id_token because it arrives directly from the token endpoint over ` +
+            `TLS, so a non-TLS issuer removes that guarantee. Only localhost may ` +
+            `use http, for development.`);
+    }
+}
+function tokenExchangeHint(error) {
+    const code = isOAuth2Error(error) ? error.extensions.error : undefined;
+    if (code === "invalid_client") {
+        return `The provider rejected the client credentials — check clientId ` +
+            `and clientSecret against the provider's app registration.`;
+    }
+    if (code === "invalid_grant") {
+        return `The provider rejected the code — most often the redirectUri ` +
+            `does not exactly match the URI registered with the provider, or the ` +
+            `code expired or was already used.`;
+    }
+    return `Check the provider's app registration (client credentials and ` +
+        `redirect URI) if this persists.`;
+}