oidc-login 1.0.0 → 1.1.1

package/README.md

@@ -82,6 +82,19 @@ await createOidcLogin({ issuerUrl, clientId }).discover()
 The issuer URL must use HTTPS; plain HTTP works only on loopback hosts, such as `localhost`, for local development.
 Validate a URL that users enter with `isSecureIssuerUrl`.
 
+Call `checkClient` with your redirect URI to check the client ID and secret as well, without signing anyone in:
+
+```ts
+await createOidcLogin({ issuerUrl, clientId, clientSecret }).checkClient({ redirectUri })
+```
+
+It exchanges a made-up code and expects the provider to reject only the code.
+When the provider rejects the client, it rejects with `OidcLoginError` with the `client_rejected` code; when the response of the provider is inconclusive, with `client_check_failed`.
+The OAuth error of the provider, if any, is in `error`.
+
+The provider sees each check as a failed code exchange: it may log it as an error and count it against its rate limits.
+Call `checkClient` when an administrator checks the settings, not as a periodic health check.
+
 ## Options
 
 - `scope`: scopes to request besides `openid`, `email`, and `profile`.

package/dist/index.d.mts

@@ -1,18 +1,20 @@
 /**
- * Stage of the sign-in that failed.
+ * Stage of a login or of a check of the provider settings that failed.
  *
  * - `discovery_failed`: the issuer metadata could not be fetched or is invalid.
  * - `authorization_failed`: the provider redirected back with an error, such as `access_denied`.
  * - `callback_failed`: the callback does not match the flow, or the code exchange or ID token validation failed.
  * - `userinfo_failed`: the UserInfo request failed.
+ * - `client_rejected`: `checkClient` found that the provider rejects the client: its ID or secret is wrong, or it may not use the authorization code flow.
+ * - `client_check_failed`: `checkClient` could not tell whether the provider accepts the client.
  */
-type OidcLoginErrorCode = "discovery_failed" | "authorization_failed" | "callback_failed" | "userinfo_failed";
-/** Failure of an OpenID Connect sign-in; the original error is in `cause`. */
+type OidcLoginErrorCode = "discovery_failed" | "authorization_failed" | "callback_failed" | "userinfo_failed" | "client_rejected" | "client_check_failed";
+/** Failure of an OpenID Connect login or of a check of the provider settings; the original error is in `cause`. */
 export declare class OidcLoginError extends Error {
   name: string;
-  /** Stage of the sign-in that failed. */
+  /** Stage that failed. */
   readonly code: OidcLoginErrorCode;
-  /** OAuth error code that the provider returned with `authorization_failed`, such as `access_denied`. */
+  /** OAuth error code that the provider returned, such as `access_denied` with `authorization_failed` or `invalid_client` with `client_rejected`. */
   readonly error?: string;
   constructor(code: OidcLoginErrorCode, options?: {
     cause?: unknown;
@@ -101,6 +103,14 @@ interface OidcLogin {
   finish: (flow: OidcLoginFlow, callback: URL | URLSearchParams | string) => Promise<OidcUser>;
   /** Fetches the issuer metadata to check the issuer URL. */
   discover: () => Promise<void>;
+  /**
+   * Checks that the provider accepts the client ID and secret, without a user.
+   *
+   * It exchanges a made-up authorization code for `redirectUri` and resolves when the provider rejects only the code.
+   */
+  checkClient: (options: {
+    redirectUri: string | URL;
+  }) => Promise<void>;
 }
 /**
  * Creates an OpenID Connect login handler for one provider: the authorization code flow with PKCE, state, and nonce.

package/dist/index.mjs

@@ -1,14 +1,14 @@
 import * as client from "openid-client";
 // src/errors.ts
-/** Failure of an OpenID Connect sign-in; the original error is in `cause`. */
+/** Failure of an OpenID Connect login or of a check of the provider settings; the original error is in `cause`. */
 var OidcLoginError = class extends Error {
 	name = "OidcLoginError";
-	/** Stage of the sign-in that failed. */
+	/** Stage that failed. */
 	code;
-	/** OAuth error code that the provider returned with `authorization_failed`, such as `access_denied`. */
+	/** OAuth error code that the provider returned, such as `access_denied` with `authorization_failed` or `invalid_client` with `client_rejected`. */
 	error;
 	constructor(code, options = {}) {
-		super(options.message ?? `OpenID Connect sign-in failed: ${code}.`, { cause: options.cause });
+		super(options.message ?? `OpenID Connect request failed: ${code}.`, { cause: options.cause });
 		this.code = code;
 		this.error = options.error;
 	}
@@ -93,8 +93,7 @@ function createOidcLogin({ issuerUrl, clientId, clientSecret, clientAuthenticati
 	};
 	return {
 		async start({ redirectUri, loginHint }) {
-			const redirectUrl = new URL(redirectUri);
-			if (/[?#]/.test(redirectUrl.href)) throw new TypeError("The redirect URI must have no query or fragment.");
+			const redirectUrl = parseRedirectUri(redirectUri);
 			const config = await getConfiguration();
 			const codeVerifier = client.randomPKCECodeVerifier();
 			const flow = {
@@ -140,23 +139,61 @@ function createOidcLogin({ issuerUrl, clientId, clientSecret, clientAuthenticati
 		},
 		async discover() {
 			await getConfiguration();
+		},
+		async checkClient({ redirectUri }) {
+			const redirectUrl = parseRedirectUri(redirectUri);
+			const config = await getConfiguration();
+			const failure = await client.genericGrantRequest(config, "authorization_code", {
+				code: client.randomState(),
+				redirect_uri: redirectUrl.href,
+				code_verifier: client.randomPKCECodeVerifier()
+			}).then(() => void 0, (cause) => cause);
+			const error = await readOAuthError(failure);
+			if (error === "invalid_grant") return;
+			throw new OidcLoginError(error === "invalid_client" || error === "unauthorized_client" || error === void 0 && failure instanceof client.WWWAuthenticateChallengeError && failure.status === 401 ? "client_rejected" : "client_check_failed", {
+				cause: failure,
+				error
+			});
 		}
 	};
 }
+/**
+* Parses the redirect URI of a sign-in.
+*
+* It must have no query or fragment: openid-client sends the redirect URI of the token request without its query, which would not match the authorization request.
+*/
+function parseRedirectUri(redirectUri) {
+	const redirectUrl = new URL(redirectUri);
+	if (/[?#]/.test(redirectUrl.href)) throw new TypeError("The redirect URI must have no query or fragment.");
+	return redirectUrl;
+}
+/** Reads the OAuth error code of a failed token request from its JSON body or its `WWW-Authenticate` challenge. */
+async function readOAuthError(failure) {
+	if (failure instanceof client.ResponseBodyError) return failure.error;
+	if (failure instanceof client.WWWAuthenticateChallengeError) {
+		const body = await failure.response.clone().json().catch(() => void 0);
+		if (body && typeof body === "object" && "error" in body && typeof body.error === "string") return body.error;
+		return failure.cause.find((challenge) => challenge.parameters.error)?.parameters.error;
+	}
+}
 async function discover({ issuer, clientId, clientSecret, clientAuthentication, fetch }) {
 	const insecure = issuer.protocol === "http:" && isLoopbackHostname(issuer.hostname);
 	const config = await client.discovery(issuer, clientId, clientSecret, clientSecret === void 0 ? client.None() : clientAuthentication === "client_secret_basic" ? client.ClientSecretBasic(clientSecret) : client.ClientSecretPost(clientSecret), {
 		...fetch ? { [client.customFetch]: fetch } : {},
 		...insecure ? { execute: [client.allowInsecureRequests] } : {}
 	});
-	const { authorization_endpoint, token_endpoint } = config.serverMetadata();
-	if (![authorization_endpoint, token_endpoint].every((endpoint) => isEndpointUrl(endpoint, insecure))) throw new Error("The issuer metadata has no valid authorization or token endpoint.");
+	const { authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri } = config.serverMetadata();
+	if (![authorization_endpoint, token_endpoint].every((endpoint) => isEndpointUrl(endpoint, insecure)) || ![userinfo_endpoint, jwks_uri].every((endpoint) => endpoint === void 0 || isEndpointUrl(endpoint, insecure))) throw new Error("The issuer metadata has an invalid endpoint.");
 	return config;
 }
-/** Checks that an endpoint from the issuer metadata is an absolute URL with an allowed protocol. */
+/**
+* Checks that an endpoint from the issuer metadata is an absolute URL with an allowed protocol.
+*
+* A plain HTTP issuer on a loopback host may name HTTPS endpoints or plain HTTP endpoints on loopback hosts, so that the client secret and tokens do not leave the machine unencrypted.
+*/
 function isEndpointUrl(value, insecure) {
 	if (typeof value !== "string" || !URL.canParse(value)) return false;
-	const { protocol } = new URL(value);
-	return protocol === "https:" || insecure && protocol === "http:";
+	const { protocol, hostname } = new URL(value);
+	return protocol === "https:" || insecure && protocol === "http:" && isLoopbackHostname(hostname);
 }
 export { OidcLoginError, createOidcLogin, isSecureIssuerUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oidc-login",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "OpenID Connect login flow for web apps on top of openid-client",
   "homepage": "https://github.com/IlyaSemenov/oidc-login#readme",
   "bugs": "https://github.com/IlyaSemenov/oidc-login/issues",