kerliix-oauth 1.0.3 → 2.0.0

package/.github/FUNDING.yml

@@ -0,0 +1,13 @@
+github: [Kerliix]
+patreon: Kerliix
+open_collective: kerliix
+ko_fi: kerliix
+tidelift: npm/kerliix-oauth
+community_bridge: kerliix
+liberapay: kerliix
+issuehunt: kerliix
+lfx_crowdfunding: kerliix
+polar: kerliix
+buy_me_a_coffee: kerliix
+thanks_dev: kerliix
+# custom: ['https://dev.kerliix.com/donate', 'https://kerliix.com/support']

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    name: Lint & syntax check
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check syntax (all JS entry points)
+        run: |
+          node --check index.js
+          node --check lib/client.js
+          node --check lib/token.js
+          node --check lib/jwks.js
+          node --check lib/middleware.js
+          node --check lib/pkce.js
+          node --check lib/utils.js

package/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    name: Publish to npmjs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check syntax
+        run: |
+          node --check index.js
+          node --check lib/client.js
+          node --check lib/token.js
+          node --check lib/jwks.js
+          node --check lib/middleware.js
+          node --check lib/pkce.js
+          node --check lib/utils.js
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION="v$(node -p "require('./package.json').version")"
+          TAG_VERSION="${GITHUB_REF_NAME}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag ($TAG_VERSION) does not match package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,151 +1,203 @@
-# Kerliix OAuth SDK
-
-> Official Kerliix OAuth 2.0 SDK for Node.js and Browser
-
-[![npm version](https://img.shields.io/npm/v/kerliix-oauth.svg?style=flat-square)](https://www.npmjs.com/package/kerliix-oauth)
-[![Downloads](https://img.shields.io/npm/dt/kerliix-oauth?style=flat-square)](https://www.npmjs.com/package/kerliix-oauth)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://github.com/kerliix-corp/kerliix-oauth-nodejs/blob/main/LICENSE)
-[![Build Status](https://github.com/kerliix-corp/kerliix-oauth-nodejs/actions/workflows/build.yml/badge.svg)](https://github.com/kerliix-corp/kerliix-oauth-nodejs/actions)
-[![Node.js Version](https://img.shields.io/node/v/kerliix-oauth?style=flat-square)](https://www.npmjs.com/package/kerliix-oauth)
-
----
-
-## Overview
-
-**Kerliix OAuth** provides a simple and secure way to integrate Kerliix authentication into your Node.js or browser-based apps.
-It handles the full OAuth 2.0 flow including:
-
-* Building authorization URLs
-* Exchanging authorization codes for tokens
-* Token caching & auto-refresh
-* Fetching user profile data
-* Revoking tokens
-
-Built with **TypeScript**, compatible with both **Node.js** and **browser environments**.
-
----
-
-## Installation
-
-```bash
-npm install kerliix-oauth
-```
-
-or using yarn:
-
-```bash
-yarn add kerliix-oauth
-```
-
----
-
-## Quick Start
-
-```js
-import KerliixOAuth from "kerliix-oauth";
-
-const client = new KerliixOAuth({
-  clientId: "YOUR_CLIENT_ID",
-  clientSecret: "YOUR_CLIENT_SECRET",
-  redirectUri: "https://yourapp.com/callback",
-  baseUrl: "https://api.kerliix.com"
-});
-
-// Step 1: Redirect user to login
-const authUrl = client.getAuthUrl(["openid", "profile", "email"]);
-console.log("Login via:", authUrl);
-
-// Step 2: Exchange the code for tokens
-// const token = await client.exchangeCodeForToken("OAUTH_CODE");
-
-// Step 3: Fetch user profile
-// const user = await client.getUserInfo(token.access_token);
-```
-
----
-
-## Configuration Options
-
-| Option         | Required | Description                                                  |
-| -------------- | -------- | ------------------------------------------------------------ |
-| `clientId`     | ✅        | Your app’s client ID from Kerliix developer portal           |
-| `clientSecret` | ⚙️       | Required for server-side (authorization code flow)           |
-| `redirectUri`  | ✅        | The callback URI registered in your app                      |
-| `baseUrl`      | ✅        | Your Kerliix OAuth base URL, e.g. `https://auth.kerliix.com` |
-
----
-
-## OAuth Flow
-
-1. **User clicks login** → Redirect to Kerliix via `getAuthUrl()`
-2. **Kerliix authenticates** → Redirects back with `?code=XYZ`
-3. **Your app exchanges code** → `exchangeCodeForToken(code)`
-4. **Use token** → Access user data via `getUserInfo()`
-5. **Optional** → Automatically refresh expired tokens
-
----
-
-## API Reference
-
-### `new KerliixOAuth(config)`
-
-Initializes the client.
-
-```js
-const client = new KerliixOAuth({
-  clientId: "...",
-  clientSecret: "...",
-  redirectUri: "...",
-  baseUrl: "https://api.kerliix.com"
-});
-```
-
----
-
-### `getAuthUrl(scopes?: string[], state?: string): string`
-
-Generates an authorization URL for login/consent.
-
-```js
-const url = client.getAuthUrl(["openid", "profile", "email"], "xyz123");
-```
-
----
-
-### `exchangeCodeForToken(code: string): Promise<TokenResponse>`
-
-Exchanges an authorization code for access and refresh tokens.
-
----
-
-### `refreshTokenIfNeeded(): Promise<TokenResponse | null>`
-
-Checks if the token is expiring and automatically refreshes it if needed.
-
----
-
-### `getUserInfo(accessToken?: string): Promise<UserInfo>`
-
-Fetches the user’s profile data using a valid access token.
-
----
-
-### `revokeToken(token: string): Promise<boolean>`
-
-Revokes an access or refresh token.
-
----
-
-## Token Caching
-
-The SDK automatically caches tokens in memory and:
-
-* Refreshes them **30 seconds before expiry**
-* Clears cache when tokens are revoked
-* Works seamlessly in Node.js and browser environments
-
----
-
-## License
-
-MIT © Kerliix Corporation
+# kerliix-oauth
+
+Official Kerliix OAuth 2.0 / OIDC SDK for Node.js — v2.0.0.
+
+Supports the full authorization code flow with PKCE, token refresh, introspection, revocation, client credentials, and RP-initiated logout against the Kerliix Accounts Center.
+
+## Install
+
+```bash
+npm install kerliix-oauth
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- ESM project (`"type": "module"` in `package.json`)
+
+---
+
+## Quick start
+
+```js
+import { kerliixClient } from "kerliix-oauth";
+
+const auth = kerliixClient({
+  clientId:     "YOUR_CLIENT_ID",
+  clientSecret: "YOUR_CLIENT_SECRET",   // omit for public clients
+  redirectUri:  "https://yourapp.com/auth/callback",
+  // issuer defaults to "https://accounts.kerliix.com"
+  // scope  defaults to "openid profile email"
+});
+```
+
+---
+
+## Authorization code flow (with PKCE)
+
+### 1 — Build the login URL
+
+```js
+app.get("/auth/login", async (req, res) => {
+  const { url, codeVerifier, state, nonce } = await auth.getLoginUrl();
+
+  // Persist PKCE state in the user's session before redirecting
+  req.session.oauthCodeVerifier = codeVerifier;
+  req.session.oauthState        = state;
+  req.session.oauthNonce        = nonce;
+
+  res.redirect(url);
+});
+```
+
+### 2 — Handle the callback
+
+```js
+app.get("/auth/callback", async (req, res) => {
+  const { code, state } = req.query;
+
+  // Validate state to prevent CSRF
+  if (state !== req.session.oauthState) {
+    return res.status(400).send("State mismatch");
+  }
+
+  const { tokens, user } = await auth.handleCallback(
+    code,
+    req.session.oauthCodeVerifier,
+    { expectedNonce: req.session.oauthNonce }
+  );
+
+  // Clean up PKCE state
+  delete req.session.oauthCodeVerifier;
+  delete req.session.oauthState;
+  delete req.session.oauthNonce;
+
+  // Store tokens in session
+  req.session.accessToken  = tokens.access_token;
+  req.session.refreshToken = tokens.refresh_token;
+  req.session.user         = user;
+
+  res.redirect("/dashboard");
+});
+```
+
+---
+
+## Token operations
+
+### Refresh
+
+```js
+const newTokens = await auth.refresh(req.session.refreshToken);
+req.session.accessToken  = newTokens.access_token;
+req.session.refreshToken = newTokens.refresh_token;
+```
+
+### Fetch user info
+
+```js
+const user = await auth.getUser(req.session.accessToken);
+// { sub, name, email, email_verified, ... }
+```
+
+### Introspect a token
+
+```js
+const info = await auth.introspect(req.session.accessToken);
+if (!info.active) {
+  // token is expired or revoked
+}
+```
+
+### Revoke a token
+
+```js
+await auth.revoke(req.session.refreshToken);
+```
+
+### Client credentials
+
+```js
+// Server-to-server — no user involved
+const tokens = await auth.clientCredentials({ scope: "openid" });
+```
+
+---
+
+## Logout
+
+```js
+app.get("/auth/logout", async (req, res) => {
+  const logoutUrl = await auth.getLogoutUrl({
+    idTokenHint:            req.session.idToken,
+    postLogoutRedirectUri:  "https://yourapp.com",
+  });
+  req.session.destroy();
+  res.redirect(logoutUrl);
+});
+```
+
+---
+
+## Pre-built Express routes (optional helper)
+
+```js
+import { middleware } from "kerliix-oauth";
+
+// Mount login + callback routes at /auth
+app.use("/auth", middleware.routes(auth));
+
+// After /auth/callback succeeds, req.oauthResult contains { tokens, user }
+// Add your own handler at /auth/callback to redirect:
+app.get("/auth/callback", (req, res) => {
+  req.session.user = req.oauthResult.user;
+  res.redirect("/dashboard");
+});
+
+// Protect routes
+app.get("/api/me", middleware.protect(auth), (req, res) => {
+  res.json(req.user);
+});
+```
+
+> **Note:** `middleware.routes()` requires `express-session` (or compatible) to be configured before the route.
+
+---
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `clientId` | `string` | **required** | Your OAuth client ID |
+| `clientSecret` | `string` | `undefined` | Client secret (omit for public clients) |
+| `redirectUri` | `string` | **required** | Registered redirect URI |
+| `issuer` | `string` | `"https://accounts.kerliix.com"` | Accounts Center base URL |
+| `scope` | `string` | `"openid profile email"` | Default scope |
+
+---
+
+## Migration from v1
+
+| v1 | v2 |
+|---|---|
+| `auth.loginUrl(scope)` | `auth.getLoginUrl({ scope })` — also returns `codeVerifier`, `state`, `nonce` |
+| `auth.handleCallback(req)` | `auth.handleCallback(code, codeVerifier, { expectedNonce })` — PKCE state no longer stored on the client instance |
+| `createVerifier(issuer)` (jwks.js) | Internal — JWKS URI is taken from the discovery document |
+| No introspect / revoke | `auth.introspect(token)`, `auth.revoke(token)` |
+| No client credentials | `auth.clientCredentials({ scope })` |
+| No logout URL | `auth.getLogoutUrl({ idTokenHint, postLogoutRedirectUri })` |
+
+---
+
+## Contributing
+
+1. Fork the repository.
+2. Create a branch for your feature or fix.
+3. Commit with clear messages.
+4. Open a pull request.
+
+Questions? [Open an issue](https://github.com/Kerliix/kerliix-oauth-js/issues) or email [dev@kerliix.com](mailto:dev@kerliix.com).
+
+## License
+
+Apache 2.0 — © Kerliix Corporation Limited

package/index.js

@@ -0,0 +1,8 @@
+import { KerliixClient } from "./lib/client.js";
+import * as middleware from "./lib/middleware.js";
+
+export function kerliixClient(config) {
+  return new KerliixClient(config);
+}
+
+export { KerliixClient, middleware };