oidc-login 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# oidc-login
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+"Sign in with SSO" for web applications through any OpenID Connect provider, such as Keycloak, Microsoft Entra ID, Google, or Yandex.
+It wraps [openid-client](https://github.com/panva/openid-client) into 2 calls: start the sign-in and finish it on the callback.
+
+## Install
+
+```sh
+npm install oidc-login
+```
+
+## Usage
+
+Configure the login handler with your provider settings:
+
+```ts
+import { createOidcLogin } from "oidc-login"
+
+const login = createOidcLogin({
+  issuerUrl: "https://keycloak.example.com/realms/company",
+  clientId: "tracker",
+  clientSecret: process.env.OIDC_CLIENT_SECRET,
+})
+```
+
+When the user clicks the sign-in button, start the sign-in, store the flow in the user's session, and redirect the browser to the provider:
+
+```ts
+const { url, flow } = await login.start({ redirectUri: "https://app.example.com/auth/callback" })
+session.oidcFlow = flow
+return redirect(url)
+```
+
+The redirect URI must have no query or fragment.
+Store the flow where only the user's browser session can read it, such as in a signed and encrypted cookie: it holds the PKCE verifier.
+It is a plain JSON object.
+
+When the provider redirects the browser back to the redirect URI, finish the sign-in with the flow and the callback URL:
+
+```ts
+const user = await login.finish(session.oidcFlow, request.url)
+delete session.oidcFlow
+```
+
+`finish` also accepts the query string of the callback or its parameters, such as `location.search` that a client-side callback page sends to the server.
+It returns the user:
+
+```ts
+user.sub // "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
+user.email // "jane@example.com"
+user.emailVerified // true, false, or undefined when the provider does not say
+user.name // "Jane Doe"
+user.claims // ID token claims
+user.userinfo // UserInfo response, if requested
+```
+
+Identify the user by `sub` within the issuer: the provider may change the email.
+Before you link the sign-in to an existing account by email, check `emailVerified`, or trust the provider to verify emails.
+
+Reuse the instance for the same provider settings: it fetches the issuer metadata once, on first use.
+
+## Handle errors
+
+`start` and `finish` reject with `OidcLoginError`, whose `code` names the failed stage:
+
+- `discovery_failed`: the issuer URL is wrong or the provider is unavailable.
+- `authorization_failed`: the provider redirected back with an error in `error`, such as `access_denied` when the user cancels.
+- `callback_failed`: the callback does not belong to the flow, or the provider rejected the code.
+- `userinfo_failed`: the UserInfo request failed.
+
+The original error is in `cause`.
+Invalid arguments, such as a redirect URI with a query, reject with `TypeError`.
+
+## Check the provider settings
+
+Call `discover` to check that the issuer URL points to a working provider, such as when an administrator saves the settings:
+
+```ts
+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`.
+- `userinfo`: when to request the UserInfo endpoint.
+  `auto`, the default, requests it when the ID token has no `email` or `email_verified`; `always` requests it on every sign-in; `never` uses only the ID token.
+- `clientSecret`: omit it for a public client.
+- `clientAuthentication`: how to send the client secret to the token endpoint.
+  `client_secret_basic`, the default, sends it in the `Authorization` header; `client_secret_post` sends it in the request body, for providers that accept only that.
+- `fetch`: sends the HTTP requests to the provider instead of the global `fetch`.
+
+## Test the sign-in
+
+Pass the handler of [oidc-test-issuer](https://github.com/IlyaSemenov/oidc-test-issuer) as `fetch` to run the whole sign-in in a unit test, without a server:
+
+```ts
+import { createTestOidcIssuer } from "oidc-test-issuer"
+
+const issuer = createTestOidcIssuer({ basePath: "/oidc" })
+const login = createOidcLogin({
+  issuerUrl: issuer.getIssuerUrl("https://app.example.com"),
+  clientId: "client-1",
+  fetch: (url, init) => issuer.fetch(new Request(url, init)),
+})
+
+const { url, flow } = await login.start({ redirectUri: "https://app.example.com/auth/callback" })
+const callback = await issuer.fetch(new Request(url))
+const user = await login.finish(flow, callback.headers.get("location")!)
+```

package/dist/index.d.mts

@@ -0,0 +1,122 @@
+/**
+ * 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" | "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 that failed. */
+  readonly code: OidcLoginErrorCode;
+  /** 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;
+    error?: string;
+    message?: string;
+  });
+}
+/**
+ * Checks that an issuer URL is safe to sign in through: HTTPS, or plain HTTP on a loopback host for local development.
+ *
+ * `createOidcLogin` accepts plain HTTP only for such URLs, so validate issuer URLs that users enter with this function.
+ */
+export declare function isSecureIssuerUrl(value: string): boolean;
+/** User that an OpenID Connect sign-in returns. */
+interface OidcUser {
+  /** Subject identifier, unique and stable within the issuer. */
+  sub: string;
+  email?: string;
+  /** Whether the provider verified `email`; `undefined` when it does not say. */
+  emailVerified?: boolean;
+  /** Display name: the `name` claim, or `preferred_username` without it. */
+  name?: string;
+  /** Claims of the ID token as the provider sent them. */
+  claims: Record<string, unknown>;
+  /** UserInfo response as the provider sent it, when the sign-in requested it. */
+  userinfo?: Record<string, unknown>;
+}
+/** Fetch API-compatible function that sends the HTTP requests to the provider. */
+type OidcFetch = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * When the sign-in requests the UserInfo endpoint.
+ *
+ * - `auto`: when the ID token has no `email` or no `email_verified`.
+ * - `always`: on every sign-in.
+ * - `never`: never; the user has only the ID token claims.
+ */
+type OidcUserinfoMode = "auto" | "always" | "never";
+/** How a client with a secret authenticates to the token endpoint. */
+type OidcClientAuthentication = "client_secret_basic" | "client_secret_post";
+/** Options of `createOidcLogin`. */
+interface OidcLoginOptions {
+  /** Issuer URL: HTTPS, or plain HTTP on a loopback host. */
+  issuerUrl: string | URL;
+  clientId: string;
+  /** Client secret; omit it for a public client. */
+  clientSecret?: string;
+  /** How to send the client secret; `client_secret_basic` by default, as OAuth defines. */
+  clientAuthentication?: OidcClientAuthentication;
+  /** Scopes to request besides `openid`, `email`, and `profile`. */
+  scope?: readonly string[];
+  /** When to request the UserInfo endpoint; `auto` by default. */
+  userinfo?: OidcUserinfoMode;
+  /** Sends the HTTP requests to the provider instead of the global `fetch`, such as to a test issuer. */
+  fetch?: OidcFetch;
+}
+/**
+ * State of a started sign-in that `finish` needs.
+ *
+ * Store it between `start` and `finish` where only the user's browser session can read it, such as in a signed and encrypted cookie: it holds the PKCE verifier.
+ * It is a plain JSON object.
+ */
+interface OidcLoginFlow {
+  redirectUri: string;
+  state: string;
+  nonce: string;
+  codeVerifier: string;
+}
+/** Started sign-in. */
+interface OidcLoginStart {
+  /** Authorization URL to redirect the browser to. */
+  url: string;
+  flow: OidcLoginFlow;
+}
+/** OpenID Connect sign-in through one provider. */
+interface OidcLogin {
+  /** Starts a sign-in that returns to `redirectUri`, which must have no query or fragment. */
+  start: (options: {
+    redirectUri: string | URL;
+    loginHint?: string;
+  }) => Promise<OidcLoginStart>;
+  /**
+   * Finishes the sign-in with the query of the request to the redirect URI.
+   *
+   * Pass the full callback URL, its query string, or its parameters.
+   */
+  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.
+ *
+ * The instance fetches the issuer metadata once, on first use; after a failed fetch, the next call fetches it again.
+ * Methods reject with `OidcLoginError` when the sign-in fails, and with `TypeError` for invalid arguments.
+ */
+export declare function createOidcLogin({ issuerUrl, clientId, clientSecret, clientAuthentication, scope, userinfo, fetch }: OidcLoginOptions): OidcLogin;
+export type { OidcClientAuthentication, OidcFetch, OidcLogin, OidcLoginErrorCode, OidcLoginFlow, OidcLoginOptions, OidcLoginStart, OidcUser, OidcUserinfoMode };

package/dist/index.mjs

@@ -0,0 +1,195 @@
+import * as client from "openid-client";
+// src/errors.ts
+/** 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 that failed. */
+	code;
+	/** 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 request failed: ${code}.`, { cause: options.cause });
+		this.code = code;
+		this.error = options.error;
+	}
+};
+// src/issuer-url.ts
+const loopbackHostnames = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+/**
+* Checks that an issuer URL is safe to sign in through: HTTPS, or plain HTTP on a loopback host for local development.
+*
+* `createOidcLogin` accepts plain HTTP only for such URLs, so validate issuer URLs that users enter with this function.
+*/
+function isSecureIssuerUrl(value) {
+	if (!URL.canParse(value)) return false;
+	const url = new URL(value);
+	return url.protocol === "https:" || url.protocol === "http:" && isLoopbackHostname(url.hostname);
+}
+/** Checks whether a hostname points to the local machine. */
+function isLoopbackHostname(hostname) {
+	return loopbackHostnames.has(hostname) || hostname.endsWith(".localhost");
+}
+// src/user.ts
+/** Reads standard claims from an untrusted claims object. */
+function readStandardClaims(claims) {
+	return {
+		email: readString(claims?.email),
+		email_verified: typeof claims?.email_verified === "boolean" ? claims.email_verified : void 0,
+		name: readString(claims?.name),
+		preferred_username: readString(claims?.preferred_username)
+	};
+}
+/** Builds the user from the ID token claims, filling missing claims from UserInfo. */
+function createOidcUser(claims, userinfo) {
+	const fromToken = readStandardClaims(claims);
+	const fromUserinfo = readStandardClaims(userinfo);
+	const email = fromToken.email ?? fromUserinfo.email;
+	return {
+		sub: claims.sub,
+		email,
+		emailVerified: email === void 0 ? void 0 : getEmailVerified(fromToken, email) ?? getEmailVerified(fromUserinfo, email),
+		name: fromToken.name ?? fromToken.preferred_username ?? fromUserinfo.name ?? fromUserinfo.preferred_username,
+		claims,
+		userinfo
+	};
+}
+function getEmailVerified(claims, email) {
+	return claims.email === email ? claims.email_verified : void 0;
+}
+function readString(value) {
+	return typeof value === "string" && value ? value : void 0;
+}
+// src/login.ts
+const defaultScope = [
+	"openid",
+	"email",
+	"profile"
+];
+/**
+* Creates an OpenID Connect login handler for one provider: the authorization code flow with PKCE, state, and nonce.
+*
+* The instance fetches the issuer metadata once, on first use; after a failed fetch, the next call fetches it again.
+* Methods reject with `OidcLoginError` when the sign-in fails, and with `TypeError` for invalid arguments.
+*/
+function createOidcLogin({ issuerUrl, clientId, clientSecret, clientAuthentication = "client_secret_basic", scope = [], userinfo = "auto", fetch }) {
+	const issuer = new URL(issuerUrl);
+	let configuration;
+	const getConfiguration = () => {
+		configuration ??= discover({
+			issuer,
+			clientId,
+			clientSecret,
+			clientAuthentication,
+			fetch
+		}).catch((cause) => {
+			configuration = void 0;
+			throw new OidcLoginError("discovery_failed", { cause });
+		});
+		return configuration;
+	};
+	return {
+		async start({ redirectUri, loginHint }) {
+			const redirectUrl = parseRedirectUri(redirectUri);
+			const config = await getConfiguration();
+			const codeVerifier = client.randomPKCECodeVerifier();
+			const flow = {
+				redirectUri: redirectUrl.href,
+				state: client.randomState(),
+				nonce: client.randomNonce(),
+				codeVerifier
+			};
+			return {
+				url: client.buildAuthorizationUrl(config, {
+					redirect_uri: flow.redirectUri,
+					scope: [.../* @__PURE__ */ new Set([...defaultScope, ...scope])].join(" "),
+					state: flow.state,
+					nonce: flow.nonce,
+					code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
+					code_challenge_method: "S256",
+					...loginHint === void 0 ? {} : { login_hint: loginHint }
+				}).href,
+				flow
+			};
+		},
+		async finish(flow, callback) {
+			const config = await getConfiguration();
+			const callbackUrl = new URL(flow.redirectUri);
+			callbackUrl.search = new URLSearchParams(callback instanceof URL || typeof callback === "string" && URL.canParse(callback) ? new URL(callback).search : callback).toString();
+			const tokens = await client.authorizationCodeGrant(config, callbackUrl, {
+				pkceCodeVerifier: flow.codeVerifier,
+				expectedState: flow.state,
+				expectedNonce: flow.nonce,
+				idTokenExpected: true
+			}).catch((cause) => {
+				throw cause instanceof client.AuthorizationResponseError ? new OidcLoginError("authorization_failed", {
+					cause,
+					error: cause.error
+				}) : new OidcLoginError("callback_failed", { cause });
+			});
+			const claims = tokens.claims();
+			const standardClaims = readStandardClaims(claims);
+			if (!(userinfo === "always" || userinfo === "auto" && (!standardClaims.email || standardClaims.email_verified === void 0))) return createOidcUser(claims);
+			return createOidcUser(claims, { ...await client.fetchUserInfo(config, tokens.access_token, claims.sub).catch((cause) => {
+				throw new OidcLoginError("userinfo_failed", { cause });
+			}) });
+		},
+		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.");
+	return config;
+}
+/** Checks that an endpoint from the issuer metadata is an absolute URL with an allowed protocol. */
+function isEndpointUrl(value, insecure) {
+	if (typeof value !== "string" || !URL.canParse(value)) return false;
+	const { protocol } = new URL(value);
+	return protocol === "https:" || insecure && protocol === "http:";
+}
+export { OidcLoginError, createOidcLogin, isSecureIssuerUrl };

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "oidc-login",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "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",
+  "license": "MIT",
+  "author": "Ilya Semenov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IlyaSemenov/oidc-login.git"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint --fix && oxfmt",
+    "lint:check": "oxlint && oxfmt --check",
+    "prepare": "lefthook install",
+    "prepublishOnly": "bun run build",
+    "release": "changesets-local",
+    "test": "bun test",
+    "types": "bun check && bun check -p tests"
+  },
+  "dependencies": {
+    "openid-client": "^6.9.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@changesets/cli": "^3.0.3",
+    "@ilyasemenov/oxc-config": "^0.1.3",
+    "@tsconfig/bun": "^1.0.12",
+    "@types/bun": "^1.4.4",
+    "changesets-local": "^1.6.0",
+    "oidc-test-issuer": "^1.0.0",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.7",
+    "typescript": "^7.0.2"
+  },
+  "packageManager": "bun@1.4.4"
+}