@zezosoft/oauth-core

Core OAuth 2.0 + OpenID Connect client for Zezo Auth.

Features

• OIDC discovery
• Authorization Code flow
• PKCE S256
• State generation and validation
• Nonce generation
• Confidential-client authentication
• Token exchange
• Refresh token exchange
• OIDC UserInfo
• RP-initiated logout URL

Install

npm install @zezosoft/oauth-core

Basic usage

import { ZezoAuth } from "@zezosoft/oauth-core";

const zezo = new ZezoAuth({
  clientId: process.env.ZEZO_CLIENT_ID!,
  clientSecret: process.env.ZEZO_CLIENT_SECRET,
  redirectUri: "http://localhost:3000/auth/callback",
});

Login

const authorization = await zezo.createAuthorizationRequest();

req.session.zezo = {
  state: authorization.state,
  nonce: authorization.nonce,
  codeVerifier: authorization.codeVerifier,
};

res.redirect(authorization.url);

Callback

const tokens = await zezo.handleCallback({
  code: String(req.query.code),
  state: String(req.query.state),
  expectedState: req.session.zezo.state,
  codeVerifier: req.session.zezo.codeVerifier,
});

req.session.tokens = tokens;

UserInfo

const user = await zezo.getUserInfo(req.session.tokens.access_token);

Refresh

const tokens = await zezo.refreshToken(req.session.tokens.refresh_token!);

Logout

const url = await zezo.getLogoutUrl({
  idTokenHint: req.session.tokens.id_token,
  postLogoutRedirectUri: "http://localhost:3000",
  state: "logout-state",
});

res.redirect(url);

If there is no active SSO session, the authorization server should return the appropriate OIDC error instead of silently logging the user in.

Security notes

The core package does not store sessions, cookies, tokens, state, or code verifiers. The host application must store those values securely.

For confidential clients, keep clientSecret on the server only. Never ship a client secret in browser or mobile code.

The SDK generates PKCE values automatically. The application should persist state and codeVerifier between the authorization request and callback.

The ID token's nonce should also be validated against the nonce generated by the application. This package currently generates and returns the nonce but intentionally leaves ID-token verification to the integration layer so platform-specific OIDC/JWT verification can be implemented with the application's key and crypto strategy.