kerliix-oauth 1.0.3 → 2.0.0

package/lib/client.js

@@ -0,0 +1,214 @@
+import axios from "axios";
+import { generatePKCE } from "./pkce.js";
+import { createVerifier } from "./jwks.js";
+import { generateState, generateNonce } from "./utils.js";
+import {
+  exchangeCode,
+  refreshAccessToken,
+  introspectToken,
+  revokeToken,
+  clientCredentialsGrant,
+} from "./token.js";
+
+export class KerliixClient {
+  /**
+   * @param {object} config
+   * @param {string} config.clientId
+   * @param {string} [config.clientSecret]          - omit for public clients
+   * @param {string} config.redirectUri
+   * @param {string} [config.issuer]                - accounts-center base URL, default https://accounts.kerliix.com
+   * @param {string} [config.scope]                 - default scope, default "openid profile email"
+   */
+  constructor({
+    clientId,
+    clientSecret,
+    redirectUri,
+    issuer = "https://accounts.kerliix.com",
+    scope = "openid profile email",
+  }) {
+    this.clientId = clientId;
+    this.clientSecret = clientSecret || null;
+    this.redirectUri = redirectUri;
+    this.issuer = issuer.replace(/\/$/, "");
+    this.defaultScope = scope;
+    this._endpoints = null;
+    this._verify = null;
+  }
+
+  // ─── Discovery ──────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch the OIDC discovery document and cache it.
+   * The discovery URL is <issuer>/oauth/.well-known/openid-configuration.
+   */
+  async init() {
+    if (this._endpoints) return;
+    const discoveryUrl = `${this.issuer}/oauth/.well-known/openid-configuration`;
+    const res = await axios.get(discoveryUrl);
+    this._endpoints = res.data;
+    this._verify = createVerifier(this._endpoints.jwks_uri, this._endpoints.issuer);
+  }
+
+  // ─── Authorization ──────────────────────────────────────────────────────────
+
+  /**
+   * Build an authorization URL and return it alongside the PKCE verifier, state,
+   * and nonce that MUST be persisted in the user session before redirecting.
+   *
+   * @param {object} [opts]
+   * @param {string} [opts.scope]   - overrides the default scope
+   * @param {string} [opts.state]   - supply your own; one is auto-generated if omitted
+   * @param {string} [opts.nonce]   - supply your own; one is auto-generated if omitted
+   * @returns {{ url: string, codeVerifier: string, state: string, nonce: string }}
+   */
+  async getLoginUrl({ scope, state, nonce } = {}) {
+    await this.init();
+    const pkce = generatePKCE();
+    const usedState = state ?? generateState();
+    const usedNonce = nonce ?? generateNonce();
+
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      response_type: "code",
+      scope: scope ?? this.defaultScope,
+      code_challenge: pkce.challenge,
+      code_challenge_method: "S256",
+      state: usedState,
+      nonce: usedNonce,
+    });
+
+    return {
+      url: `${this._endpoints.authorization_endpoint}?${params.toString()}`,
+      codeVerifier: pkce.verifier,
+      state: usedState,
+      nonce: usedNonce,
+    };
+  }
+
+  // ─── Callback ───────────────────────────────────────────────────────────────
+
+  /**
+   * Exchange the authorization code for tokens and verify the ID token.
+   *
+   * @param {string} code           - `code` query param from the callback URL
+   * @param {string} codeVerifier   - PKCE verifier from getLoginUrl()
+   * @param {object} [opts]
+   * @param {string} [opts.expectedNonce] - nonce from getLoginUrl(); verified if supplied
+   * @returns {{ tokens: object, user: object|null }}
+   */
+  async handleCallback(code, codeVerifier, { expectedNonce } = {}) {
+    await this.init();
+
+    const tokens = await exchangeCode({
+      code,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      redirectUri: this.redirectUri,
+      codeVerifier,
+      tokenEndpoint: this._endpoints.token_endpoint,
+    });
+
+    let user = null;
+    if (tokens.id_token) {
+      user = await this._verify(tokens.id_token, this.clientId, expectedNonce);
+    }
+
+    return { tokens, user };
+  }
+
+  // ─── Token management ───────────────────────────────────────────────────────
+
+  /**
+   * Refresh an access token using a refresh token.
+   * @param {string} token - the refresh_token
+   */
+  async refresh(token) {
+    await this.init();
+    return refreshAccessToken({
+      refreshToken: token,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      tokenEndpoint: this._endpoints.token_endpoint,
+    });
+  }
+
+  /**
+   * Fetch the UserInfo claims for an access token.
+   * @param {string} accessToken
+   */
+  async getUser(accessToken) {
+    await this.init();
+    const res = await axios.get(this._endpoints.userinfo_endpoint, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    return res.data;
+  }
+
+  /**
+   * Introspect a token (RFC 7662). Requires client credentials.
+   * @param {string} token - access_token or refresh_token to introspect
+   */
+  async introspect(token) {
+    await this.init();
+    return introspectToken({
+      token,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      introspectEndpoint: this._endpoints.introspection_endpoint,
+    });
+  }
+
+  /**
+   * Revoke a token (RFC 7009).
+   * @param {string} token - access_token or refresh_token to revoke
+   */
+  async revoke(token) {
+    await this.init();
+    await revokeToken({
+      token,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      revokeEndpoint: this._endpoints.revocation_endpoint,
+    });
+  }
+
+  /**
+   * Obtain an access token using the client_credentials grant.
+   * Only available for confidential clients.
+   * @param {object} [opts]
+   * @param {string} [opts.scope]
+   */
+  async clientCredentials({ scope } = {}) {
+    await this.init();
+    return clientCredentialsGrant({
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      scope: scope ?? this.defaultScope,
+      tokenEndpoint: this._endpoints.token_endpoint,
+    });
+  }
+
+  // ─── Logout ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Build an RP-initiated logout URL (OIDC Session Management).
+   * Redirect the user's browser to this URL to end their session.
+   *
+   * @param {object} [opts]
+   * @param {string} [opts.idTokenHint]            - ID token from the session
+   * @param {string} [opts.postLogoutRedirectUri]  - where to send the user after logout
+   * @param {string} [opts.state]
+   */
+  async getLogoutUrl({ idTokenHint, postLogoutRedirectUri, state } = {}) {
+    await this.init();
+    const base = this._endpoints.end_session_endpoint;
+    if (!base) throw new Error("end_session_endpoint not advertised by this server.");
+    const params = new URLSearchParams();
+    if (idTokenHint) params.set("id_token_hint", idTokenHint);
+    if (postLogoutRedirectUri) params.set("post_logout_redirect_uri", postLogoutRedirectUri);
+    if (state) params.set("state", state);
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+}

package/lib/jwks.js

@@ -0,0 +1,34 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+// Cache JWKS key sets by URI so we don't refetch on every token verification
+const _jwksCache = new Map();
+
+/**
+ * Create a JWT verifier for RS256 ID tokens.
+ *
+ * @param {string} jwksUri  - from the OIDC discovery document (jwks_uri)
+ * @param {string} issuer   - from the OIDC discovery document (issuer)
+ * @returns {(idToken: string, audience: string, nonce?: string) => Promise<object>}
+ */
+export function createVerifier(jwksUri, issuer) {
+  if (!_jwksCache.has(jwksUri)) {
+    _jwksCache.set(jwksUri, createRemoteJWKSet(new URL(jwksUri)));
+  }
+  const jwks = _jwksCache.get(jwksUri);
+
+  return async function verify(idToken, audience, nonce) {
+    const { payload } = await jwtVerify(idToken, jwks, {
+      issuer,
+      audience,
+      algorithms: ["RS256"],
+    });
+
+    if (nonce !== undefined && payload.nonce !== nonce) {
+      throw new Error(
+        `Nonce mismatch: expected "${nonce}", got "${payload.nonce}"`
+      );
+    }
+
+    return payload;
+  };
+}

package/lib/middleware.js

@@ -0,0 +1,104 @@
+import express from "express";
+
+/**
+ * `protect(client)` — Express middleware that enforces a valid Bearer token.
+ *
+ * Calls client.getUser(accessToken) against the userinfo endpoint.
+ * On success, attaches the claims to req.user and calls next().
+ * On failure, responds 401.
+ *
+ * @param {import("./client.js").KerliixClient} client
+ */
+export function protect(client) {
+  return async (req, res, next) => {
+    const auth = req.headers.authorization;
+    if (!auth || !auth.startsWith("Bearer ")) {
+      return res.status(401).json({
+        error: "unauthorized",
+        error_description: "Bearer token required.",
+      });
+    }
+    try {
+      const token = auth.slice(7);
+      req.user = await client.getUser(token);
+      next();
+    } catch {
+      res.status(401).json({
+        error: "unauthorized",
+        error_description: "Invalid or expired token.",
+      });
+    }
+  };
+}
+
+/**
+ * `routes(client)` — Mounts pre-built login and callback routes on an Express router.
+ *
+ * Requires `express-session` (or compatible session middleware) to be set up
+ * before these routes so that PKCE state can be persisted across the redirect.
+ *
+ * Mounted routes:
+ *   GET /login    — redirect user to Kerliix accounts
+ *   GET /callback — exchange code, store tokens in session, call next()
+ *
+ * After /callback succeeds, req.oauthResult contains { tokens, user }.
+ * Add your own next() handler after this router to redirect or respond.
+ *
+ * @param {import("./client.js").KerliixClient} client
+ */
+export function routes(client) {
+  const router = express.Router();
+
+  router.get("/login", async (req, res, next) => {
+    try {
+      const { url, codeVerifier, state, nonce } = await client.getLoginUrl();
+      // Persist PKCE and CSRF state in session before redirecting
+      req.session = req.session ?? {};
+      req.session.oauthCodeVerifier = codeVerifier;
+      req.session.oauthState = state;
+      req.session.oauthNonce = nonce;
+      res.redirect(url);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  router.get("/callback", async (req, res, next) => {
+    try {
+      const { code, state, error, error_description } = req.query;
+
+      if (error) {
+        return res.status(400).json({ error, error_description });
+      }
+
+      const session = req.session ?? {};
+
+      // Validate state to prevent CSRF
+      if (session.oauthState && state !== session.oauthState) {
+        return res.status(400).json({
+          error: "invalid_state",
+          error_description: "State parameter mismatch.",
+        });
+      }
+
+      const result = await client.handleCallback(
+        code,
+        session.oauthCodeVerifier,
+        { expectedNonce: session.oauthNonce }
+      );
+
+      // Clean up PKCE state from session
+      delete session.oauthCodeVerifier;
+      delete session.oauthState;
+      delete session.oauthNonce;
+
+      // Make result available to the next handler
+      req.oauthResult = result;
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  return router;
+}

package/lib/pkce.js

@@ -0,0 +1,16 @@
+import crypto from "crypto";
+
+/**
+ * Generate a PKCE (Proof Key for Code Exchange) pair.
+ * Returns a random `verifier` and its S256 `challenge`.
+ *
+ * RFC 7636 §4.1 — verifier must be 43-128 characters of [A-Z a-z 0-9 - . _ ~]
+ */
+export function generatePKCE() {
+  const verifier = crypto.randomBytes(48).toString("base64url");
+  const challenge = crypto
+    .createHash("sha256")
+    .update(verifier)
+    .digest("base64url");
+  return { verifier, challenge };
+}

package/lib/token.js

@@ -0,0 +1,107 @@
+import axios from "axios";
+
+/**
+ * Build an HTTP Basic Authorization header from clientId and clientSecret.
+ * Percent-encodes each value per RFC 6749 §2.3.1.
+ */
+function basicAuth(clientId, clientSecret) {
+  const encoded = Buffer.from(
+    `${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`
+  ).toString("base64");
+  return `Basic ${encoded}`;
+}
+
+/**
+ * POST to a token endpoint with application/x-www-form-urlencoded body.
+ * Uses client_secret_basic (Authorization header) when a clientSecret is present,
+ * falling back to including client_id in the body for public clients.
+ */
+async function postToken(endpoint, params, clientId, clientSecret) {
+  const body = new URLSearchParams(params);
+  const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+
+  if (clientSecret) {
+    headers.Authorization = basicAuth(clientId, clientSecret);
+  } else {
+    body.set("client_id", clientId);
+  }
+
+  const res = await axios.post(endpoint, body.toString(), { headers });
+  return res.data;
+}
+
+// ─── Grant handlers ──────────────────────────────────────────────────────────
+
+export async function exchangeCode({
+  code,
+  clientId,
+  clientSecret,
+  redirectUri,
+  codeVerifier,
+  tokenEndpoint,
+}) {
+  const params = {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    ...(codeVerifier ? { code_verifier: codeVerifier } : {}),
+  };
+  return postToken(tokenEndpoint, params, clientId, clientSecret);
+}
+
+export async function refreshAccessToken({
+  refreshToken,
+  clientId,
+  clientSecret,
+  tokenEndpoint,
+}) {
+  return postToken(
+    tokenEndpoint,
+    { grant_type: "refresh_token", refresh_token: refreshToken },
+    clientId,
+    clientSecret
+  );
+}
+
+export async function introspectToken({
+  token,
+  clientId,
+  clientSecret,
+  introspectEndpoint,
+}) {
+  const body = new URLSearchParams({ token });
+  const headers = {
+    "Content-Type": "application/x-www-form-urlencoded",
+    Authorization: basicAuth(clientId, clientSecret),
+  };
+  const res = await axios.post(introspectEndpoint, body.toString(), { headers });
+  return res.data;
+}
+
+export async function revokeToken({
+  token,
+  clientId,
+  clientSecret,
+  revokeEndpoint,
+}) {
+  const body = new URLSearchParams({ token });
+  const headers = {
+    "Content-Type": "application/x-www-form-urlencoded",
+    Authorization: basicAuth(clientId, clientSecret),
+  };
+  await axios.post(revokeEndpoint, body.toString(), { headers });
+}
+
+export async function clientCredentialsGrant({
+  clientId,
+  clientSecret,
+  scope,
+  tokenEndpoint,
+}) {
+  return postToken(
+    tokenEndpoint,
+    { grant_type: "client_credentials", scope },
+    clientId,
+    clientSecret
+  );
+}

package/lib/utils.js

@@ -0,0 +1,17 @@
+import crypto from "crypto";
+
+export function buildQueryString(params) {
+  return Object.entries(params)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}
+
+/** Generate a cryptographically random state value (hex). */
+export function generateState() {
+  return crypto.randomBytes(16).toString("hex");
+}
+
+/** Generate a cryptographically random nonce value (hex). */
+export function generateNonce() {
+  return crypto.randomBytes(16).toString("hex");
+}

package/package.json

@@ -1,31 +1,16 @@
-{
-  "name": "kerliix-oauth",
-  "version": "1.0.3",
-  "description": "Official Kerliix OAuth SDK for Node.js and browser",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build",
-    "test": "node tests/client.test.js"
-  },
-  "keywords": [
-    "oauth2",
-    "kerliix",
-    "nodejs",
-    "sdk",
-    "authentication",
-    "typescript",
-    "oauth"
-  ],
-  "author": "Kerliix Corporation",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kerliix-corp/kerliix-oauth-nodejs.git"
-  },
-  "devDependencies": {
-    "typescript": "^5.6.3"
-  }
-}
+{
+  "name": "kerliix-oauth",
+  "version": "2.0.0",
+  "description": "Official Kerliix OAuth 2.0 / OIDC SDK for Node.js",
+  "main": "index.js",
+  "type": "module",
+  "keywords": ["oauth", "openid", "oidc", "pkce", "kerliix", "authentication", "sdk"],
+  "author": "Kerliix Corporation Limited",
+  "license": "Apache-2.0",
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "express": "^4.18.2",
+    "jose": "^5.0.0"
+  }
+}

package/.github/workflows/build.yml

@@ -1,35 +0,0 @@
-name: Build
-
-# Run workflow on pushes and pull requests to main
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  build:
-    name: Build and Test
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [18, 20] # Test against Node 18 and 20
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build TypeScript
-        run: npm run build
-
-      - name: Run tests
-        run: npm test