@knsdev330/node-utils 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khandaker Sajjat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @knsdev330/node-utils
+
+TypeScript utilities for Node.js backends: passwords, JWT, cookies, OAuth helpers, env parsing, IDs, and small shared primitives.
+
+This library is built for reuse across projects. It is somewhat opinionated and not optimized for minimal install size—review modules before production use.
+
+## Disclaimer
+
+- Utilities reflect personal conventions and may include niche helpers.
+- **Security-sensitive code** (password hashing, JWT, OAuth, Turnstile) should be reviewed and tested in your environment.
+- No stability guarantee for semver until you explicitly commit to a versioning policy.
+
+## Requirements
+
+- **Node.js** with ESM (`"type": "module"` in consuming packages, or a bundler that handles ESM).
+- **Express** is a **peer dependency** (v4 or v5). Install it in your app; it is required for cookie helpers that use `express` response types.
+
+Runtime dependencies installed with this package include `bcrypt`, `jsonwebtoken`, and `jose`.
+
+## Installation
+
+```bash
+npm install @knsdev330/node-utils express
+```
+
+```bash
+pnpm add @knsdev330/node-utils express
+```
+
+### Releases (CI)
+
+Pushes to `main` run [.github/workflows/publish.yml](.github/workflows/publish.yml), which publishes with **[npm trusted publishing (OIDC)](https://docs.npmjs.com/trusted-publishers)**—no long-lived **`NPM_TOKEN`** for publish. On npmjs.com, add this repo as the package’s trusted publisher (GitHub org/user, repository, workflow file **`publish.yml`**). The [`repository`](https://docs.npmjs.com/trusted-publishers#troubleshooting) field in `package.json` must match this GitHub repo exactly. **Bump `version` in `package.json`** before each release; npm rejects duplicate versions.
+
+## Usage
+
+Default entry re-exports the public API:
+
+```ts
+import {
+	PasswordUtils,
+	JwtUtils,
+	CookieUtils,
+	getEnvv,
+	tryCatch,
+} from "@knsdev330/node-utils";
+```
+
+Subpath imports map to built files under `dist/` (see `package.json` `"exports"`):
+
+```ts
+import { PasswordUtils } from "@knsdev330/node-utils/PasswordUtils.js";
+```
+
+Use the `.js` extension in import specifiers to match Node ESM resolution.
+
+## What is included
+
+| Area | Exports (examples) |
+|------|---------------------|
+| Passwords | `PasswordUtils` — bcrypt hash/compare, strength bounds |
+| JWT | `JwtUtils` — sign/verify via `jsonwebtoken` |
+| Cookies | `CookieUtils` — set/get/delete on Express `Response` |
+| OAuth | `GoogleUtils`, `FacebookUtils` — token / user helpers |
+| Crypto / integrity | `HMACUtils` |
+| HTTP / API | `HttpCodes`, `EApiCodes`, `ErrorClasses` |
+| Env | `getEnvv` — typed env from a schema |
+| IDs / random | `IDUtils`, `Rand` |
+| Numbers / bigint | `Nums`, `bnUtils` |
+| Validation | `validateUUID`, `TurnstileValidator` |
+| Control flow | `tryCatch`, `tryCatch2` |
+
+See `src/index.ts` for the full export list and each module for behavior and parameters.
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+```
+
+`prepublishOnly` runs `pnpm run build` so `dist/` is fresh before publish.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/Cookies.d.ts

@@ -0,0 +1,33 @@
+import { type Response } from "express";
+declare class cookieUtils {
+    /**
+     * Set an HTTP-only cookie with common security defaults.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param value - Cookie value.
+     * @param maxAgeMs - Cookie max age in milliseconds (Express `maxAge`).
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    readonly setCookie: (res: Response, name: string, value: string, maxAgeMs: number, domain: string, APP_ENV: "dev" | "test" | "prod", path?: string, sameSite?: "lax" | "strict" | "none") => void;
+    /**
+     * Clear an HTTP-only cookie by setting it expired immediately.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    readonly clearCookie: (res: Response, name: string, domain: string, APP_ENV: "dev" | "test" | "prod", path?: string, sameSite?: "lax" | "strict" | "none") => void;
+}
+/**
+ * Singleton instance of cookie helper utilities.
+ */
+export declare const CookieUtils: cookieUtils;
+export {};
+//# sourceMappingURL=Cookies.d.ts.map

package/dist/Cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cookies.d.ts","sourceRoot":"","sources":["../src/Cookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,cAAM,WAAW;IAChB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,GAAI,KAAK,QAAQ,EAAE,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,UAAU,MAAM,EAAE,QAAQ,MAAM,EAAE,SAAS,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,OAAM,MAAY,EAAE,WAAU,KAAK,GAAG,QAAQ,GAAG,MAAc,UAYpM;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,GAAI,KAAK,QAAQ,EAAE,MAAM,MAAM,EAAE,QAAQ,MAAM,EAAE,SAAS,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,OAAM,MAAY,EAAE,WAAU,KAAK,GAAG,QAAQ,GAAG,MAAc,UAYrK;CACD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/dist/Cookies.js

@@ -0,0 +1,54 @@
+import {} from "express";
+class cookieUtils {
+    /**
+     * Set an HTTP-only cookie with common security defaults.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param value - Cookie value.
+     * @param maxAgeMs - Cookie max age in milliseconds (Express `maxAge`).
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    setCookie = (res, name, value, maxAgeMs, domain, APP_ENV, path = '/', sameSite = 'lax') => {
+        // If sameSite is 'none', secure must be true for most modern browsers
+        const isSecure = sameSite === 'none' ? true : APP_ENV !== 'dev';
+        res.cookie(name, value, {
+            httpOnly: true,
+            secure: isSecure,
+            maxAge: maxAgeMs,
+            path: path,
+            sameSite: sameSite,
+            domain: domain
+        });
+    };
+    /**
+     * Clear an HTTP-only cookie by setting it expired immediately.
+     * @param res - Express response object.
+     * @param name - Cookie name.
+     * @param domain - Cookie domain.
+     * @param APP_ENV - Current application environment.
+     * @param path - Cookie path.
+     * @param sameSite - SameSite policy.
+     * @returns Nothing.
+     */
+    clearCookie = (res, name, domain, APP_ENV, path = '/', sameSite = 'lax') => {
+        const isSecure = sameSite === 'none' ? true : APP_ENV !== 'dev';
+        res.cookie(name, 'invalid', {
+            httpOnly: true,
+            secure: isSecure,
+            maxAge: 0,
+            expires: new Date(0),
+            path: path,
+            sameSite: sameSite,
+            domain: domain
+        });
+    };
+}
+/**
+ * Singleton instance of cookie helper utilities.
+ */
+export const CookieUtils = new cookieUtils();
+//# sourceMappingURL=Cookies.js.map

package/dist/Cookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cookies.js","sourceRoot":"","sources":["../src/Cookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW;IAChB;;;;;;;;;;;OAWG;IACM,SAAS,GAAG,CAAC,GAAa,EAAE,IAAY,EAAE,KAAa,EAAE,QAAgB,EAAE,MAAc,EAAE,OAAgC,EAAE,OAAe,GAAG,EAAE,WAAsC,KAAK,EAAE,EAAE;QACxM,sEAAsE;QACtE,MAAM,QAAQ,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;QAEhE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;YACvB,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,MAAM;SACd,CAAC,CAAC;IACJ,CAAC,CAAA;IAED;;;;;;;;;OASG;IACM,WAAW,GAAG,CAAC,GAAa,EAAE,IAAY,EAAE,MAAc,EAAE,OAAgC,EAAE,OAAe,GAAG,EAAE,WAAsC,KAAK,EAAE,EAAE;QACzK,MAAM,QAAQ,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;QAEhE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE;YAC3B,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,CAAC;YACT,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;YACpB,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,MAAM;SACd,CAAC,CAAC;IACJ,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/EApiCodes.d.ts

@@ -0,0 +1,2 @@
+export type EApiCodes = `API_ERROR` | `SUCCESS` | `BAD_REQUEST` | `UNAUTHORIZED` | `FORBIDDEN` | `NOT_FOUND` | `INTERNAL_SERVER_ERROR` | `TOO_MANY_REQUESTS` | `JWT__ENCRYPTION_FAILED` | `JWT__INVALID_OR_EXPIRED` | `CAPTCHA__VALIDATION_FAILED` | `ID__INVALID`;
+//# sourceMappingURL=EApiCodes.d.ts.map

package/dist/EApiCodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EApiCodes.d.ts","sourceRoot":"","sources":["../src/EApiCodes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,WAAW,GAClC,SAAS,GACT,aAAa,GACb,cAAc,GACd,WAAW,GACX,WAAW,GACX,uBAAuB,GACvB,mBAAmB,GACnB,wBAAwB,GACxB,yBAAyB,GACzB,4BAA4B,GAC5B,aAAa,CAAC"}

package/dist/EApiCodes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=EApiCodes.js.map

package/dist/EApiCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EApiCodes.js","sourceRoot":"","sources":["../src/EApiCodes.ts"],"names":[],"mappings":""}

package/dist/ErrorClasses.d.ts

@@ -0,0 +1,78 @@
+import type { EApiCodes } from "./EApiCodes.js";
+/**
+ * Base error type for API responses.
+ * Extends {@link Error} with an HTTP status code and an API error code.
+ */
+export declare class ApiError extends Error {
+    status: number;
+    message: EApiCodes;
+    retryAfterDate: Date | undefined;
+    /**
+     * @param status - HTTP status code associated with the error.
+     * @param message - API error code (defaults to `API_ERROR`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     * @param retryAfterDate - Optional date used for rate-limit responses (e.g. `429`).
+     */
+    constructor(status: number, message?: EApiCodes, stack?: string, retryAfterDate?: Date);
+}
+/**
+ * 500 Internal Server Error.
+ */
+export declare class InternalServerError extends ApiError {
+    /**
+     * @param message - API error code (defaults to `INTERNAL_SERVER_ERROR`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 429 Too Many Requests.
+ */
+export declare class TooManyRequests extends ApiError {
+    /**
+     * @param message - API error code (defaults to `TOO_MANY_REQUESTS`).
+     * @param retryAfterDate - Optional date when clients may retry.
+     */
+    constructor(message?: EApiCodes, retryAfterDate?: Date);
+}
+/**
+ * 400 Bad Request.
+ */
+export declare class BadRequest extends ApiError {
+    /**
+     * @param message - API error code (defaults to `BAD_REQUEST`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 403 Forbidden.
+ */
+export declare class Forbidden extends ApiError {
+    /**
+     * @param message - API error code (defaults to `FORBIDDEN`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 401 Unauthorized.
+ */
+export declare class Unauthorized extends ApiError {
+    /**
+     * @param message - API error code (defaults to `UNAUTHORIZED`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+/**
+ * 404 Not Found.
+ */
+export declare class NotFound extends ApiError {
+    /**
+     * @param message - API error code (defaults to `NOT_FOUND`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message?: EApiCodes, stack?: string);
+}
+//# sourceMappingURL=ErrorClasses.d.ts.map

package/dist/ErrorClasses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorClasses.d.ts","sourceRoot":"","sources":["../src/ErrorClasses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,CAAC;IACnB,cAAc,EAAE,IAAI,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,SAAK,EAAE,cAAc,CAAC,EAAE,IAAI;CAQlF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAChD;;;OAGG;gBACS,OAAO,GAAE,SAAmC,EAAE,KAAK,SAAK;CAKpE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC5C;;;OAGG;gBACS,OAAO,GAAE,SAA+B,EAAE,cAAc,CAAC,EAAE,IAAI;CAG3E;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACvC;;;OAGG;gBACS,OAAO,GAAE,SAAyB,EAAE,KAAK,SAAK;CAK1D;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,QAAQ;IACtC;;;OAGG;gBACS,OAAO,GAAE,SAAuB,EAAE,KAAK,SAAK;CAKxD;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACzC;;;OAGG;gBACS,OAAO,GAAE,SAA0B,EAAE,KAAK,SAAK;CAK3D;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IACrC;;;OAGG;gBACS,OAAO,GAAE,SAAuB,EAAE,KAAK,SAAK;CAKxD"}

package/dist/ErrorClasses.js

@@ -0,0 +1,118 @@
+/**
+ * Base error type for API responses.
+ * Extends {@link Error} with an HTTP status code and an API error code.
+ */
+export class ApiError extends Error {
+    status;
+    message;
+    retryAfterDate;
+    /**
+     * @param status - HTTP status code associated with the error.
+     * @param message - API error code (defaults to `API_ERROR`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     * @param retryAfterDate - Optional date used for rate-limit responses (e.g. `429`).
+     */
+    constructor(status, message, stack = "", retryAfterDate) {
+        super(message || 'API_ERROR');
+        this.status = status;
+        this.message = message || 'API_ERROR';
+        this.retryAfterDate = retryAfterDate;
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 500 Internal Server Error.
+ */
+export class InternalServerError extends ApiError {
+    /**
+     * @param message - API error code (defaults to `INTERNAL_SERVER_ERROR`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message = 'INTERNAL_SERVER_ERROR', stack = "") {
+        super(500, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 429 Too Many Requests.
+ */
+export class TooManyRequests extends ApiError {
+    /**
+     * @param message - API error code (defaults to `TOO_MANY_REQUESTS`).
+     * @param retryAfterDate - Optional date when clients may retry.
+     */
+    constructor(message = 'TOO_MANY_REQUESTS', retryAfterDate) {
+        super(429, message, undefined, retryAfterDate);
+    }
+}
+/**
+ * 400 Bad Request.
+ */
+export class BadRequest extends ApiError {
+    /**
+     * @param message - API error code (defaults to `BAD_REQUEST`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message = 'BAD_REQUEST', stack = "") {
+        super(400, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 403 Forbidden.
+ */
+export class Forbidden extends ApiError {
+    /**
+     * @param message - API error code (defaults to `FORBIDDEN`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message = 'FORBIDDEN', stack = "") {
+        super(403, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 401 Unauthorized.
+ */
+export class Unauthorized extends ApiError {
+    /**
+     * @param message - API error code (defaults to `UNAUTHORIZED`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message = 'UNAUTHORIZED', stack = "") {
+        super(401, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * 404 Not Found.
+ */
+export class NotFound extends ApiError {
+    /**
+     * @param message - API error code (defaults to `NOT_FOUND`).
+     * @param stack - Optional stack trace override (empty string means "use default").
+     */
+    constructor(message = 'NOT_FOUND', stack = "") {
+        super(404, message);
+        if (stack)
+            this.stack = stack;
+        else
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+//# sourceMappingURL=ErrorClasses.js.map

package/dist/ErrorClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorClasses.js","sourceRoot":"","sources":["../src/ErrorClasses.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAClC,MAAM,CAAS;IACf,OAAO,CAAY;IACnB,cAAc,CAAmB;IAEjC;;;;;OAKG;IACH,YAAY,MAAc,EAAE,OAAmB,EAAE,KAAK,GAAG,EAAE,EAAE,cAAqB;QACjF,KAAK,CAAC,OAAO,IAAI,WAAW,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,WAAW,CAAC;QACtC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IAChD;;;OAGG;IACH,YAAY,UAAqB,uBAAuB,EAAE,KAAK,GAAG,EAAE;QACnE,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC5C;;;OAGG;IACH,YAAY,UAAqB,mBAAmB,EAAE,cAAqB;QAC1E,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IAChD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,QAAQ;IACvC;;;OAGG;IACH,YAAY,UAAqB,aAAa,EAAE,KAAK,GAAG,EAAE;QACzD,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACtC;;;OAGG;IACH,YAAY,UAAqB,WAAW,EAAE,KAAK,GAAG,EAAE;QACvD,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACzC;;;OAGG;IACH,YAAY,UAAqB,cAAc,EAAE,KAAK,GAAG,EAAE;QAC1D,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACrC;;;OAGG;IACH,YAAY,UAAqB,WAAW,EAAE,KAAK,GAAG,EAAE;QACvD,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;;YACzB,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,CAAC;CACD"}

package/dist/FBUtils.d.ts

@@ -0,0 +1,22 @@
+declare class facebookUtils {
+    /**
+     * Validates a Facebook access token and fetches user profile details.
+     * Uses POST bodies so tokens and app secrets are not placed in request URLs (fewer access-log leaks).
+     * @param token - Facebook user access token.
+     * @param appId - Facebook application ID.
+     * @param appSecret - Facebook application secret.
+     * @returns Normalized user profile or `null` if token/profile lookup fails.
+     */
+    readonly getUserFromJwt: (token: string, appId: string, appSecret: string) => Promise<{
+        name: string | undefined;
+        email: string | undefined;
+        picture: string | undefined;
+        oauth_id: string;
+    } | null>;
+}
+/**
+ * Singleton instance of Facebook OAuth utilities.
+ */
+export declare const FacebookUtils: facebookUtils;
+export {};
+//# sourceMappingURL=FBUtils.d.ts.map

package/dist/FBUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FBUtils.d.ts","sourceRoot":"","sources":["../src/FBUtils.ts"],"names":[],"mappings":"AAWA,cAAM,aAAa;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,GAAU,OAAO,MAAM,EAAE,OAAO,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC;QAC1F,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC,CA4DR;CACD;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/FBUtils.js

@@ -0,0 +1,68 @@
+import { tryCatch } from "./tryCatch.js";
+const FORM_URLENCODED = "application/x-www-form-urlencoded";
+class facebookUtils {
+    /**
+     * Validates a Facebook access token and fetches user profile details.
+     * Uses POST bodies so tokens and app secrets are not placed in request URLs (fewer access-log leaks).
+     * @param token - Facebook user access token.
+     * @param appId - Facebook application ID.
+     * @param appSecret - Facebook application secret.
+     * @returns Normalized user profile or `null` if token/profile lookup fails.
+     */
+    getUserFromJwt = async (token, appId, appSecret) => {
+        const debugBody = new URLSearchParams({
+            input_token: token,
+            access_token: `${appId}|${appSecret}`,
+        });
+        const [response, error] = await tryCatch(fetch("https://graph.facebook.com/v19.0/debug_token", {
+            method: "POST",
+            headers: { "Content-Type": FORM_URLENCODED },
+            body: debugBody.toString(),
+        }));
+        if (error) {
+            return null;
+        }
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        if (!data.data?.is_valid || data.data.app_id !== appId) {
+            return null;
+        }
+        // `expires_at === 0` is treated as non-expiring (avoid rejecting valid long-lived tokens).
+        const nowSec = Date.now() / 1000;
+        if (data.data.expires_at !== 0 && data.data.expires_at < nowSec) {
+            return null;
+        }
+        const meBody = new URLSearchParams({
+            fields: "id,name,email,picture.type(large)",
+            access_token: token,
+        });
+        const [user, userError] = await tryCatch(fetch("https://graph.facebook.com/v19.0/me", {
+            method: "POST",
+            headers: { "Content-Type": FORM_URLENCODED },
+            body: meBody.toString(),
+        }));
+        if (userError) {
+            return null;
+        }
+        if (!user.ok) {
+            return null;
+        }
+        const userData = (await user.json());
+        if (!userData.id) {
+            return null;
+        }
+        return {
+            oauth_id: userData.id,
+            name: userData.name ?? 'Anonymous',
+            email: userData.email,
+            picture: userData.picture?.data?.url ?? ``,
+        };
+    };
+}
+/**
+ * Singleton instance of Facebook OAuth utilities.
+ */
+export const FacebookUtils = new facebookUtils();
+//# sourceMappingURL=FBUtils.js.map

package/dist/FBUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FBUtils.js","sourceRoot":"","sources":["../src/FBUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AASzC,MAAM,eAAe,GAAG,mCAAmC,CAAC;AAE5D,MAAM,aAAa;IAClB;;;;;;;OAOG;IACM,cAAc,GAAG,KAAK,EAAE,KAAa,EAAE,KAAa,EAAE,SAAiB,EAKtE,EAAE;QAEX,MAAM,SAAS,GAAG,IAAI,eAAe,CAAC;YACrC,WAAW,EAAE,KAAK;YAClB,YAAY,EAAE,GAAG,KAAK,IAAI,SAAS,EAAE;SACrC,CAAC,CAAC;QAEH,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,8CAA8C,EAAE;YAC9F,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE;YAC5C,IAAI,EAAE,SAAS,CAAC,QAAQ,EAAE;SAC1B,CAAC,CAAC,CAAC;QACJ,IAAI,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyE,CAAC;QAC7G,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YACxD,OAAO,IAAI,CAAC;QACb,CAAC;QAED,2FAA2F;QAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC;YACjE,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YAClC,MAAM,EAAE,mCAAmC;YAC3C,YAAY,EAAE,KAAK;SACnB,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,qCAAqC,EAAE;YACrF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE;YAC5C,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE;SACvB,CAAC,CAAC,CAAC;QACJ,IAAI,SAAS,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAkB,CAAC;QACtD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,OAAO;YACN,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,WAAW;YAClC,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE;SAC1C,CAAC;IACH,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC"}

package/dist/GoogleUtils.d.ts

@@ -0,0 +1,43 @@
+declare class googleUtils {
+    /**
+     * Verifies a Google ID token and returns normalized user info.
+     * @param jwtToken - Google ID token.
+     * @param client_id - OAuth client ID expected in token audience.
+     * @returns Normalized user object, or `null` when verification fails.
+     */
+    readonly getUserFromJwt: (jwtToken: string, client_id: string) => Promise<{
+        name: string;
+        email: string | undefined;
+        picture: string;
+        oauth_id: string;
+    } | null>;
+    /**
+     * Exchanges an authorization code for an ID token, then resolves user info.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns Normalized user object, or `null` on failure.
+     */
+    readonly getUserFromCode: (code: string, client_id: string, client_secret: string, redirect_uri: string) => Promise<{
+        name: string | undefined;
+        email: string | undefined;
+        picture: string | undefined;
+        oauth_id: string;
+    } | null>;
+    /**
+     * Exchange Google OAuth authorization code for an ID token.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns ID token string, or `null` on failure.
+     */
+    private readonly jwtFromCode;
+}
+/**
+ * Singleton instance of Google OAuth utilities.
+ */
+export declare const GoogleUtils: googleUtils;
+export {};
+//# sourceMappingURL=GoogleUtils.d.ts.map

package/dist/GoogleUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleUtils.d.ts","sourceRoot":"","sources":["../src/GoogleUtils.ts"],"names":[],"mappings":"AA8BA,cAAM,WAAW;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,GAAU,UAAU,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC;QAC9E,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC,CAeR;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,GAAU,MAAM,MAAM,EAAE,WAAW,MAAM,EAAE,eAAe,MAAM,EAAE,cAAc,MAAM,KAAG,OAAO,CAAC;QACxH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC,CAIR;IAGD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAqB3B;CACD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/dist/GoogleUtils.js

@@ -0,0 +1,80 @@
+import { createRemoteJWKSet } from "jose/jwks/remote";
+import { tryCatch } from "./tryCatch.js";
+import { jwtVerify } from "jose";
+import { randInt } from "./Rand.js";
+const Google_JWK = createRemoteJWKSet(new URL("https://www.googleapis.com/oauth2/v3/certs"));
+class googleUtils {
+    /**
+     * Verifies a Google ID token and returns normalized user info.
+     * @param jwtToken - Google ID token.
+     * @param client_id - OAuth client ID expected in token audience.
+     * @returns Normalized user object, or `null` when verification fails.
+     */
+    getUserFromJwt = async (jwtToken, client_id) => {
+        if (!Google_JWK)
+            return null;
+        const [data, error] = await tryCatch(jwtVerify(jwtToken, Google_JWK, {
+            issuer: "https://accounts.google.com",
+            audience: client_id,
+        }));
+        if (error)
+            return null;
+        return {
+            name: data.payload.name ?? 'Anonymous',
+            email: data.payload.email,
+            picture: data.payload.picture ?? `/images/avatars/default_${randInt(1, 10)}.svg`,
+            oauth_id: data.payload.sub,
+        };
+    };
+    /**
+     * Exchanges an authorization code for an ID token, then resolves user info.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns Normalized user object, or `null` on failure.
+     */
+    getUserFromCode = async (code, client_id, client_secret, redirect_uri) => {
+        const id_token = await this.jwtFromCode(code, client_id, client_secret, redirect_uri);
+        if (!id_token)
+            return null;
+        return await this.getUserFromJwt(id_token, client_id);
+    };
+    /**
+     * Exchange Google OAuth authorization code for an ID token.
+     * @param code - Google OAuth authorization code.
+     * @param client_id - OAuth client ID.
+     * @param client_secret - OAuth client secret.
+     * @param redirect_uri - Redirect URI used for the OAuth flow.
+     * @returns ID token string, or `null` on failure.
+     */
+    jwtFromCode = async (code, client_id, client_secret, redirect_uri) => {
+        const [resData, error] = await tryCatch(fetch(`https://oauth2.googleapis.com/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            body: JSON.stringify({
+                code,
+                client_id,
+                client_secret,
+                redirect_uri,
+                grant_type: 'authorization_code'
+            })
+        }));
+        if (error)
+            return null;
+        if (!resData.ok)
+            return null;
+        const data = await resData.json();
+        if (!data.id_token)
+            return null;
+        return data.id_token;
+    };
+}
+/**
+ * Singleton instance of Google OAuth utilities.
+ */
+export const GoogleUtils = new googleUtils();
+//# sourceMappingURL=GoogleUtils.js.map

package/dist/GoogleUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleUtils.js","sourceRoot":"","sources":["../src/GoogleUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC,MAAM,UAAU,GAAG,kBAAkB,CACpC,IAAI,GAAG,CAAC,4CAA4C,CAAC,CACrD,CAAC;AAEF,MAAM,WAAW;IAChB;;;;;OAKG;IACM,cAAc,GAAG,KAAK,EAAE,QAAgB,EAAE,SAAiB,EAK1D,EAAE;QACX,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAE7B,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAoB,QAAQ,EAAE,UAAU,EAAE;YACvF,MAAM,EAAE,6BAA6B;YACrC,QAAQ,EAAE,SAAS;SACnB,CAAC,CAAC,CAAC;QAEJ,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACvB,OAAO;YACN,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,WAAW;YACtC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;YACzB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,2BAA2B,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;YAChF,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;SAC1B,CAAC;IACH,CAAC,CAAA;IAED;;;;;;;OAOG;IACM,eAAe,GAAG,KAAK,EAAE,IAAY,EAAE,SAAiB,EAAE,aAAqB,EAAE,YAAoB,EAKpG,EAAE;QACX,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;QACtF,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3B,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC,CAAA;IAGD;;;;;;;OAOG;IACc,WAAW,GAAG,KAAK,EAAE,IAAY,EAAE,SAAiB,EAAE,aAAqB,EAAE,YAAoB,EAA0B,EAAE;QAC7I,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,qCAAqC,EAAE;YACpF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACR,cAAc,EAAE,kBAAkB;gBAClC,QAAQ,EAAE,kBAAkB;aAC5B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACpB,IAAI;gBACJ,SAAS;gBACT,aAAa;gBACb,YAAY;gBACZ,UAAU,EAAE,oBAAoB;aAChC,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAgC,CAAC;QAChE,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}