@heavstal/auth

[!WARNING] Migration Notice: heavstal-auth has been renamed to @heavstal/auth. The legacy heavstal-auth package is now deprecated. Please update your dependencies to continue receiving security updates and new features.

The official NextAuth.js (Auth.js) provider for the Heavstal Tech Identity Platform.

This package enables seamless integration of Heavstal OAuth 2.0 & OpenID Connect (OIDC) authentication into Next.js and Node.js applications. It pre-configures authorization endpoints, token exchanges, and user profile mapping, ensuring security best practices.

Features

Zero-Configuration: Pre-configured endpoints for Heavstal Identity services.
Dual-Protocol Support: Seamlessly toggle between full OpenID Connect (OIDC) or pure OAuth 2.0 modes.
OIDC Compliant: Fully supports OpenID Connect discovery and ID Token verification.
TypeScript Support: Written in TypeScript with included type definitions.
Secure Defaults: Enforces PKCE (Proof Key for Code Exchange) and state verification by default.

Installation

Ensure you have next-auth installed in your project.

npm install @heavstal/auth
# or
yarn add @heavstal/auth
# or
pnpm add @heavstal/auth

Configuration

1. Obtain Credentials

2. Environment Variables

Add the following to your .env or .env.local file:

HEAVSTAL_CLIENT_ID=ht_id_xxxxxxxxxxxx
HEAVSTAL_CLIENT_SECRET=ht_secret_xxxxxxxxxxxx

3. Basic Usage (OIDC Mode)

Import HeavstalProvider and add it to your NextAuth configuration. By default, the provider runs in modern oidc mode and uses our Discovery Document to fetch configurations automatically.

File: app/api/auth/[...nextauth]/route.ts (App Router) or pages/api/auth/[...nextauth].ts (Pages Router).

import NextAuth from "next-auth";
import HeavstalProvider from "@heavstal/auth";

const handler = NextAuth({
  providers:[
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID!,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
    }),
    // ...other providers
  ],
});

export { handler as GET, handler as POST };

4. Pure OAuth2 Mode (Bypassing JWKS)

If your environment has strict edge-runtime limitations or you simply prefer not to deal with cryptographic JWT verification (JWKS), you can switch the provider into pure oauth2 mode.

This forces NextAuth to ignore the id_token and fetch user data directly from the Heavstal /userinfo API instead.

HeavstalProvider({
  clientId: process.env.HEAVSTAL_CLIENT_ID!,
  clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
  mode: "oauth2", // <-- skips OIDC / JWKS validation
})

Integration with Non-Next.js Applications

Heavstal Tech is a standard OpenID Connect (OIDC) provider. If you are using a different framework (Express, Python, Go, etc.) or a library that supports OIDC Discovery, you do not need this specific SDK.

You can configure your client using the Issuer URL.

OIDC Discovery Configuration

Parameter	Value
Issuer URL	`https://accounts.heavstal.com.ng`
Discovery Document	`https://accounts.heavstal.com.ng/.well-known/openid-configuration`
JWKS Endpoint	`https://accounts.heavstal.com.ng/.well-known/jwks.json`

Example: Generic Node.js OIDC Client

const client = new OIDCClient({
  issuer: 'https://accounts.heavstal.com.ng',
  client_id: process.env.HEAVSTAL_CLIENT_ID,
  client_secret: process.env.HEAVSTAL_CLIENT_SECRET,
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  scope: 'openid profile email'
});

User Profile Data

On successful authentication, the provider returns the following normalized user profile structure:

interface HeavstalProfile {
  id: string;       // The unique Heavstal User ID
  name: string;     // Public Display Name
  email: string;    // Verified Email Address
  image: string;    // Profile Picture URL
}

Resources

License

This project is licensed under the MIT License.