kerliix-oauth 1.0.1

package/README.md

@@ -0,0 +1,149 @@
+# 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)
+[![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)
+
+---
+
+## 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

package/changelog.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),  
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## Quick Start / Known Issues (Local Development)
+- **TypeScript syntax cannot run directly in Node.js** without compiling. Use `tsc` to build before running.
+- **Do not use `!` non-null assertions** in runtime code (`CLIENT_ID!`) – they are TypeScript-only and will break Node.js execution.
+- Exported functions with TypeScript types (e.g., `code: string`) will throw syntax errors if run uncompiled.
+- Always handle runtime errors from SDK methods:
+  - `"Missing required config: clientId, redirectUri, or baseUrl"`
+  - `"Token exchange failed: <statusText>"`
+  - `"Failed to refresh token"`
+  - `"Missing access token"`
+  - `"Failed to fetch user info"`
+  - `revokeToken()` may return `false` if revocation fails.
+- Use compiled `dist/` files for testing locally instead of raw `.ts` files.
+
+---
+
+## [1.0.1] - 2025-10-27
+### Added
+- **Runtime error documentation** for the SDK:
+  - `"Missing required config: clientId, redirectUri, or baseUrl"` in `KerliixOAuth` constructor.
+  - `"Token exchange failed: <statusText>"` in `exchangeCodeForToken()`.
+  - `"Failed to refresh token"` in `refreshTokenIfNeeded()`.
+  - `null` returned from `refreshTokenIfNeeded()` or `TokenCache.get()` if no valid token exists.
+  - `"Missing access token"` in `getUserInfo()` if no access token is available.
+  - `"Failed to fetch user info"` if user info request fails.
+  - `revokeToken()` returns `false` if token revocation fails.
+- Enhanced **developer experience** with clearer SDK error messages and handling instructions.
+- Minor improvements to TypeScript typings and internal caching logic.
+
+### Changed
+- SDK version bumped from `1.0.0-beta.1` to `1.0.1`.
+- Documentation and examples updated to highlight error handling.
+
+### Fixed
+- N/A (no functional changes; only runtime errors clarified).
+
+---
+
+## [1.0.0-beta.1] - 2025-10-15
+### Added
+- **Initial beta release** of the official **Kerliix OAuth SDK** for Node.js and browser.
+- Support for **OAuth 2.0 Authorization Code Flow**.
+- `KerliixOAuth` main client class for authentication and token management.
+- `getAuthUrl()` method to generate authorization URLs.
+- `exchangeCodeForToken()` to exchange authorization codes for tokens.
+- `refreshTokenIfNeeded()` to refresh tokens automatically.
+- `getUserInfo()` to fetch authenticated user profile information.
+- `revokeToken()` to revoke issued tokens.
+- In-memory **token caching** with early refresh via `TokenCache`.
+- TypeScript support with full type definitions (`types.ts`).
+
+### Fixed
+- N/A (initial release).
+
+### Changed
+- N/A (initial release).
+
+---
+
+## [Unreleased]
+### Planned
+- Add PKCE (Proof Key for Code Exchange) support for better security.
+- Persistent caching options (file system or Redis).
+- Improved browser compatibility and npm publishing.
+- Unit tests and CI/CD integration.
+
+---
+
+**Repository:** [kerliix-corp/kerliix-oauth-nodejs](https://github.com/kerliix-corp/kerliix-oauth-nodejs)  
+**License:** MIT © Kerliix Corporation

package/dist/cache.d.ts

@@ -0,0 +1,7 @@
+import type { TokenResponse } from "./types.js";
+export declare class TokenCache {
+    private tokenData;
+    set(token: TokenResponse): void;
+    get(): TokenResponse | null;
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,23 @@
+export class TokenCache {
+    constructor() {
+        this.tokenData = null;
+    }
+    set(token) {
+        token.created_at = Math.floor(Date.now() / 1000);
+        this.tokenData = token;
+    }
+    get() {
+        if (!this.tokenData)
+            return null;
+        const now = Math.floor(Date.now() / 1000);
+        const expiry = (this.tokenData.created_at || 0) + (this.tokenData.expires_in || 0);
+        if (now >= expiry - 30) {
+            console.warn("TokenCache: token expired or near expiry");
+            return null;
+        }
+        return this.tokenData;
+    }
+    clear() {
+        this.tokenData = null;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import type { KerliixConfig, TokenResponse, UserInfo } from "./types.js";
+export default class KerliixOAuth {
+    private config;
+    private cache;
+    constructor(config: KerliixConfig);
+    getAuthUrl(scopes?: string[], state?: string): string;
+    exchangeCodeForToken(code: string): Promise<TokenResponse>;
+    refreshTokenIfNeeded(): Promise<TokenResponse | null>;
+    getUserInfo(accessToken?: string): Promise<UserInfo>;
+    revokeToken(token: string): Promise<boolean>;
+}

package/dist/client.js

@@ -0,0 +1,116 @@
+import { TokenCache } from "./cache.js";
+export default class KerliixOAuth {
+    constructor(config) {
+        if (!config.clientId || !config.redirectUri || !config.baseUrl)
+            throw new Error("Missing required config: clientId, redirectUri, or baseUrl");
+        this.config = {
+            ...config,
+            baseUrl: config.baseUrl.replace(/\/$/, "")
+        };
+        this.cache = new TokenCache();
+    }
+    getAuthUrl(scopes = ["openid", "profile", "email"], state = "") {
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            response_type: "code",
+            scope: scopes.join(" "),
+            state
+        });
+        return `${this.config.baseUrl}/oauth/authorize?${params.toString()}`;
+    }
+    async exchangeCodeForToken(code) {
+        if (!code)
+            throw new Error("exchangeCodeForToken: code is required");
+        try {
+            const res = await fetch(`${this.config.baseUrl}/oauth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "authorization_code",
+                    code,
+                    redirect_uri: this.config.redirectUri,
+                    client_id: this.config.clientId,
+                    client_secret: this.config.clientSecret
+                })
+            });
+            if (!res.ok) {
+                throw new Error(`Token exchange failed: ${res.statusText}`);
+            }
+            const token = await res.json();
+            this.cache.set(token);
+            return token;
+        }
+        catch (err) {
+            console.error("exchangeCodeForToken error:", err);
+            throw err;
+        }
+    }
+    async refreshTokenIfNeeded() {
+        try {
+            const cached = this.cache.get();
+            if (cached)
+                return cached;
+            const last = this.cache["tokenData"];
+            if (!last?.refresh_token)
+                return null;
+            const res = await fetch(`${this.config.baseUrl}/oauth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    grant_type: "refresh_token",
+                    refresh_token: last.refresh_token,
+                    client_id: this.config.clientId,
+                    client_secret: this.config.clientSecret
+                })
+            });
+            if (!res.ok)
+                throw new Error("Failed to refresh token");
+            const token = await res.json();
+            this.cache.set(token);
+            return token;
+        }
+        catch (err) {
+            console.error("refreshTokenIfNeeded error:", err);
+            return null; // Fail gracefully, user may need re-auth
+        }
+    }
+    async getUserInfo(accessToken) {
+        try {
+            const token = accessToken || (await this.refreshTokenIfNeeded())?.access_token;
+            if (!token)
+                throw new Error("Missing access token");
+            const res = await fetch(`${this.config.baseUrl}/oauth/userinfo`, {
+                headers: { Authorization: `Bearer ${token}` }
+            });
+            if (!res.ok)
+                throw new Error("Failed to fetch user info");
+            return res.json();
+        }
+        catch (err) {
+            console.error("getUserInfo error:", err);
+            throw err;
+        }
+    }
+    async revokeToken(token) {
+        try {
+            const res = await fetch(`${this.config.baseUrl}/oauth/revoke`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ token })
+            });
+            if (!res.ok) {
+                console.warn("revokeToken failed: server rejected token");
+                this.cache.clear(); // clear cache anyway
+                return false;
+            }
+            this.cache.clear();
+            return true;
+        }
+        catch (err) {
+            console.error("revokeToken error:", err);
+            this.cache.clear();
+            return false;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import KerliixOAuth from "./client.js";
+export default KerliixOAuth;
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+import KerliixOAuth from "./client.js";
+export default KerliixOAuth;
+export * from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export interface KerliixConfig {
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    baseUrl: string;
+}
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+    created_at?: number;
+}
+export interface UserInfo {
+    id: string;
+    email?: string;
+    name?: string;
+    picture?: string;
+    [key: string]: any;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "kerliix-oauth",
+  "version": "1.0.1",
+  "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"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,28 @@
+import type { TokenResponse } from "./types.js";
+
+export class TokenCache {
+  private tokenData: TokenResponse | null = null;
+
+  set(token: TokenResponse) {
+    token.created_at = Math.floor(Date.now() / 1000);
+    this.tokenData = token;
+  }
+
+  get(): TokenResponse | null {
+    if (!this.tokenData) return null;
+
+    const now = Math.floor(Date.now() / 1000);
+    const expiry = (this.tokenData.created_at || 0) + (this.tokenData.expires_in || 0);
+
+    if (now >= expiry - 30) {
+      console.warn("TokenCache: token expired or near expiry");
+      return null;
+    }
+
+    return this.tokenData;
+  }
+
+  clear() {
+    this.tokenData = null;
+  }
+}

package/src/client.ts

@@ -0,0 +1,132 @@
+import type { KerliixConfig, TokenResponse, UserInfo } from "./types.js";
+import { TokenCache } from "./cache.js";
+
+export default class KerliixOAuth {
+  private config: KerliixConfig;
+  private cache: TokenCache;
+
+  constructor(config: KerliixConfig) {
+    if (!config.clientId || !config.redirectUri || !config.baseUrl)
+      throw new Error("Missing required config: clientId, redirectUri, or baseUrl");
+
+    this.config = {
+      ...config,
+      baseUrl: config.baseUrl.replace(/\/$/, "")
+    };
+    this.cache = new TokenCache();
+  }
+
+  getAuthUrl(scopes: string[] = ["openid", "profile", "email"], state = ""): string {
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      response_type: "code",
+      scope: scopes.join(" "),
+      state
+    });
+    return `${this.config.baseUrl}/oauth/authorize?${params.toString()}`;
+  }
+
+  async exchangeCodeForToken(code: string): Promise<TokenResponse> {
+    if (!code) throw new Error("exchangeCodeForToken: code is required");
+
+    try {
+      const res = await fetch(`${this.config.baseUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          grant_type: "authorization_code",
+          code,
+          redirect_uri: this.config.redirectUri,
+          client_id: this.config.clientId,
+          client_secret: this.config.clientSecret
+        })
+      });
+
+      if (!res.ok) {
+        throw new Error(`Token exchange failed: ${res.statusText}`);
+      }
+
+      const token = await res.json() as TokenResponse;
+      this.cache.set(token);
+      return token;
+
+    } catch (err: any) {
+      console.error("exchangeCodeForToken error:", err);
+      throw err;
+    }
+  }
+
+  async refreshTokenIfNeeded(): Promise<TokenResponse | null> {
+    try {
+      const cached = this.cache.get();
+      if (cached) return cached;
+
+      const last = this.cache["tokenData"];
+      if (!last?.refresh_token) return null;
+
+      const res = await fetch(`${this.config.baseUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          grant_type: "refresh_token",
+          refresh_token: last.refresh_token,
+          client_id: this.config.clientId,
+          client_secret: this.config.clientSecret
+        })
+      });
+
+      if (!res.ok) throw new Error("Failed to refresh token");
+
+      const token = await res.json() as TokenResponse;
+      this.cache.set(token);
+      return token;
+
+    } catch (err: any) {
+      console.error("refreshTokenIfNeeded error:", err);
+      return null; // Fail gracefully, user may need re-auth
+    }
+  }
+
+  async getUserInfo(accessToken?: string): Promise<UserInfo> {
+    try {
+      const token = accessToken || (await this.refreshTokenIfNeeded())?.access_token;
+      if (!token) throw new Error("Missing access token");
+
+      const res = await fetch(`${this.config.baseUrl}/oauth/userinfo`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+
+      if (!res.ok) throw new Error("Failed to fetch user info");
+      return res.json() as Promise<UserInfo>;
+
+    } catch (err: any) {
+      console.error("getUserInfo error:", err);
+      throw err;
+    }
+  }
+
+  async revokeToken(token: string): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.config.baseUrl}/oauth/revoke`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ token })
+      });
+
+      if (!res.ok) {
+        console.warn("revokeToken failed: server rejected token");
+        this.cache.clear(); // clear cache anyway
+        return false;
+      }
+
+      this.cache.clear();
+      return true;
+
+    } catch (err: any) {
+      console.error("revokeToken error:", err);
+      this.cache.clear();
+      return false;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import KerliixOAuth from "./client.js";
+export default KerliixOAuth;
+export * from "./types.js";

package/src/types.ts

@@ -0,0 +1,23 @@
+export interface KerliixConfig {
+  clientId: string;
+  clientSecret?: string;
+  redirectUri: string;
+  baseUrl: string;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  token_type: string;
+  expires_in: number;
+  scope?: string;
+  created_at?: number;
+}
+
+export interface UserInfo {
+  id: string;
+  email?: string;
+  name?: string;
+  picture?: string;
+  [key: string]: any;
+}

package/tests/client.test.js

@@ -0,0 +1,12 @@
+import KerliixOAuth from "../dist/index.js";
+
+(async () => {
+  const client = new KerliixOAuth({
+    clientId: "demo-client",
+    redirectUri: "https://example.com/callback",
+    baseUrl: "https://api.kerliix.com"
+  });
+
+  console.log("✅ Authorization URL:");
+  console.log(client.getAuthUrl(["openid", "profile", "email"], "test123"));
+})();

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}