@forgedevstack/forge-auth

Node.js auth toolkit with zero runtime dependencies — everything is built on node:crypto. Part of the ForgeStack ecosystem and designed to plug into @forgedevstack/harbor or any HTTP framework.

Not AuthMaster. This package is server-side only (sessions, API keys, scrypt, OIDC helpers, Harbor middleware). The React OAuth UI formerly associated with “AuthMaster” is a different product and should not be published under @forgedevstack/forge-auth. Recommended future npm name: @forgedevstack/auth-master.

• HMAC-SHA256 signed session tokens with TTL
• Refresh tokens + rotation (createSessionPair / rotateSessionPair)
• Cookie serialize/parse helpers and Harbor cookie session middleware
• Harbor middleware wrappers for bearer session and API key auth
• scrypt password hashing with self-describing hash strings
• API key generation and SHA-256 hash verification
• OIDC authorization-code helpers with PKCE (S256) + refresh grant body helper
• Framework-agnostic guards over a minimal { headers } request shape

Install

npm install @forgedevstack/forge-auth

Current version: 2.0.1

Quick Example

Session plus Harbor middleware:

import {
  createSessionPair,
  createHarborSessionMiddleware,
  setSessionCookie,
  setRefreshCookie,
} from '@forgedevstack/forge-auth';

const secret = process.env.SESSION_SECRET!;

app.post('/login', (req, res) => {
  const pair = createSessionPair({
    secret,
    accessPayload: { userId: 'user-1', role: 'admin' },
  });
  setSessionCookie(res, pair.accessToken, { httpOnly: true, sameSite: 'Lax' });
  setRefreshCookie(res, pair.refreshToken, { httpOnly: true, sameSite: 'Lax' });
  res.json({ ok: true });
});

app.use(createHarborSessionMiddleware({ secret }));

app.get('/profile', (req, res) => {
  res.json({ userId: req.forgeSession?.payload.userId });
});

Cookie-based session (no Authorization header):

import { createHarborCookieSessionMiddleware } from '@forgedevstack/forge-auth';

app.use(createHarborCookieSessionMiddleware({ secret }));

API Overview

Sessions

• createSession(payload, secret, options?) — compact token: base64url(claims) + '.' + base64url(hmac). Default TTL 3600s.
• verifySession(token, secret) — { valid: true, claims } or { valid: false, reason }.

Refresh / rotation

• createRefreshToken(payload, secret, options?) — long-lived refresh token (tokenType: 'refresh', random jti). Default TTL 7 days.
• verifyRefreshToken(token, secret) — validates signature, expiry, and refresh shape.
• createSessionPair({ secret, accessPayload, ... }) — access + refresh pair.
• rotateSessionPair({ secret, refreshToken, accessPayload, ... }) — verifies refresh and issues a new pair (rotation).

Cookies

• parseCookieHeader(header) / serializeCookie(name, value, options?) / clearCookie(name, options?)
• setSessionCookie / setRefreshCookie / clearSessionCookie / clearRefreshCookie / readCookieValue for Harbor-style responses

Harbor middleware

• createHarborSessionMiddleware({ secret }) — bearer session → req.forgeSession
• createHarborApiKeyMiddleware({ hashes }) — API key → req.forgeApiKey
• createHarborCookieSessionMiddleware({ secret }) — HttpOnly cookie session → req.forgeSession

Passwords

• hashPassword(password, options?) / verifyPassword(password, stored)

API Keys

• generateApiKey() / hashApiKey(key) / verifyApiKey(key, hash)

OIDC

• generateState() / generatePkcePair()
• buildAuthorizationUrl(config, params)
• buildTokenRequestBody(config, params) — authorization_code grant
• buildRefreshTokenRequestBody(config, params) — refresh_token grant

Full Harbor + OIDC walkthrough: docs/oidc-flow.md

Guards

• extractBearerToken(request, headerName?)
• createSessionGuard(options) / createApiKeyGuard(options)

Guards are plain functions of { headers } returning { authorized: true, context } or { authorized: false, reason }.

Security Notes

• Session tokens are signed with HMAC-SHA256; payloads are encoded, not encrypted — do not put secrets in the payload.
• Refresh tokens include a jti; rotate on use and invalidate previous jti values in your store when you need server-side revocation.
• Password hashing uses scrypt; comparisons use crypto.timingSafeEqual.
• Prefer HttpOnly + Secure + SameSite=Lax (or Strict) for session cookies.

Related packages

| Package | Role | |---|---| | @forgedevstack/forge-auth (this) | Node auth toolkit | | @forgedevstack/auth-master (recommended name) | React OAuth UI (AuthMaster) — separate product, not this package | | @forgedevstack/harbor | Backend framework these middleware helpers target |

License

MIT — part of the ForgeStack family of libraries.