@volcanicminds/tools 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Volcanic Minds
+
+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,64 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![opensource](https://img.shields.io/badge/open-source-blue)](https://en.wikipedia.org/wiki/Open_source)
+[![volcanic-typeorm](https://img.shields.io/badge/volcanic-minds-orange)](https://github.com/volcanicminds/volcanic-typeorm)
+[![npm](https://img.shields.io/badge/package-npm-white)](https://www.npmjs.com/package/@volcanicminds/tools)
+
+# volcanic-tools
+
+Tools for the volcanic (minds) backend. This library provides a collection of modular utilities designed to be tree-shakeable.
+
+## Installation
+
+```bash
+npm install @volcanicminds/tools
+```
+
+## How to upgrade packages
+
+```bash
+npm run upgrade-deps
+```
+
+## Environment
+
+```bash
+# or automatically use LOG_LEVEL
+SOME_KEY=true
+```
+
+## Usage
+
+This package supports both root imports and sub-path imports to optimize bundle size.
+
+### Import everything
+
+```typescript
+import { mfa, log } from '@volcanicminds/tools'
+```
+
+### Import specific features (Recommended for smaller bundles)
+
+```typescript
+import * as mfa from '@volcanicminds/tools/mfa'
+import * as logger from '@volcanicminds/tools/logger'
+```
+
+## Features
+
+### MFA (Multi-Factor Authentication)
+
+Utilities for generating secrets, QR codes, and verifying TOTP tokens.
+
+```typescript
+import * as mfa from '@volcanicminds/tools/mfa'
+
+// Generate Setup
+const { secret, uri, qrCode } = await mfa.generateSetupDetails('MyApp', 'user@example.com')
+
+// Verify Token
+const isValid = mfa.verifyToken('123456', secret)
+```
+
+## Logging
+
+Use Pino logger if in your project you have a `global.log` with a valid instance.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * as mfa from './lib/mfa/index.js';
+export * as log from './lib/util/logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * as mfa from './lib/mfa/index.js';
+export * as log from './lib/util/logger.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}

package/dist/lib/main.d.ts

@@ -0,0 +1,2 @@
+export declare function main(): void;
+//# sourceMappingURL=main.d.ts.map

package/dist/lib/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../lib/main.ts"],"names":[],"mappings":"AAAA,wBAAgB,IAAI,SAEnB"}

package/dist/lib/main.js

@@ -0,0 +1,4 @@
+export function main() {
+    console.log('This is the main export');
+}
+//# sourceMappingURL=main.js.map

package/dist/lib/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../lib/main.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,IAAI;IAClB,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAA;AACxC,CAAC"}

package/dist/lib/mfa/index.d.ts

@@ -0,0 +1,10 @@
+export interface MfaSetupDetails {
+    secret: string;
+    uri: string;
+    qrCode: string;
+}
+export declare function generateSecret(size?: number): string;
+export declare function generateSetupDetails(appName: string, username: string, secret?: string): Promise<MfaSetupDetails>;
+export declare function verifyToken(token: string, secret: string, window?: number): boolean;
+export declare function generateToken(secret: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/mfa/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/mfa/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;CACf;AAOD,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAW,GAAG,MAAM,CAGxD;AAQD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CAqB1B;AASD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,OAAO,CAatF;AAOD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASpD"}

package/dist/lib/mfa/index.js

@@ -0,0 +1,47 @@
+import * as OTPAuth from 'otpauth';
+import QRCode from 'qrcode';
+export function generateSecret(size = 20) {
+    const secret = new OTPAuth.Secret({ size });
+    return secret.base32;
+}
+export async function generateSetupDetails(appName, username, secret) {
+    const mfaSecret = secret ? OTPAuth.Secret.fromBase32(secret) : new OTPAuth.Secret({ size: 20 });
+    const base32Secret = mfaSecret.base32;
+    const totp = new OTPAuth.TOTP({
+        issuer: appName,
+        label: username,
+        algorithm: 'SHA1',
+        digits: 6,
+        period: 30,
+        secret: mfaSecret
+    });
+    const uri = totp.toString();
+    const qrCode = await QRCode.toDataURL(uri);
+    return {
+        secret: base32Secret,
+        uri,
+        qrCode
+    };
+}
+export function verifyToken(token, secret, window = 1) {
+    if (!token || !secret)
+        return false;
+    const totp = new OTPAuth.TOTP({
+        algorithm: 'SHA1',
+        digits: 6,
+        period: 30,
+        secret: OTPAuth.Secret.fromBase32(secret)
+    });
+    const delta = totp.validate({ token, window });
+    return delta !== null;
+}
+export function generateToken(secret) {
+    const totp = new OTPAuth.TOTP({
+        algorithm: 'SHA1',
+        digits: 6,
+        period: 30,
+        secret: OTPAuth.Secret.fromBase32(secret)
+    });
+    return totp.generate();
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/mfa/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/mfa/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,MAAM,MAAM,QAAQ,CAAA;AAa3B,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE;IAC9C,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3C,OAAO,MAAM,CAAC,MAAM,CAAA;AACtB,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAe,EACf,QAAgB,EAChB,MAAe;IAEf,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IAC/F,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,CAAA;IAErC,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;QAC5B,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,QAAQ;QACf,SAAS,EAAE,MAAM;QACjB,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,SAAS;KAClB,CAAC,CAAA;IAEF,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IAE1C,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,GAAG;QACH,MAAM;KACP,CAAA;AACH,CAAC;AASD,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,MAAc,EAAE,SAAiB,CAAC;IAC3E,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAEnC,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;QAC5B,SAAS,EAAE,MAAM;QACjB,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;KAC1C,CAAC,CAAA;IAGF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IAC9C,OAAO,KAAK,KAAK,IAAI,CAAA;AACvB,CAAC;AAOD,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;QAC5B,SAAS,EAAE,MAAM;QACjB,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;KAC1C,CAAC,CAAA;IAEF,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAA;AACxB,CAAC"}

package/dist/lib/util/logger.d.ts

@@ -0,0 +1,7 @@
+export declare function trace(data: any): void;
+export declare function debug(data: any): void;
+export declare function info(data: any): void;
+export declare function warn(data: any): void;
+export declare function error(data: any): void;
+export declare function fatal(data: any): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/util/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../lib/util/logger.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,IAAI,KAAA,QAEzB;AAED,wBAAgB,KAAK,CAAC,IAAI,KAAA,QAEzB;AAED,wBAAgB,IAAI,CAAC,IAAI,KAAA,QAExB;AAED,wBAAgB,IAAI,CAAC,IAAI,KAAA,QAExB;AAED,wBAAgB,KAAK,CAAC,IAAI,KAAA,QAEzB;AAED,wBAAgB,KAAK,CAAC,IAAI,KAAA,QAEzB"}

package/dist/lib/util/logger.js

@@ -0,0 +1,19 @@
+export function trace(data) {
+    global.isLoggingEnabled && global.log?.trace && global.log.trace(data);
+}
+export function debug(data) {
+    global.isLoggingEnabled && global.log?.debug && global.log.debug(data);
+}
+export function info(data) {
+    global.isLoggingEnabled && global.log?.info && global.log.info(data);
+}
+export function warn(data) {
+    global.isLoggingEnabled && global.log?.warn && global.log.warn(data);
+}
+export function error(data) {
+    global.isLoggingEnabled && global.log?.error && global.log.error(data);
+}
+export function fatal(data) {
+    global.isLoggingEnabled && global.log?.fatal && global.log.fatal(data);
+}
+//# sourceMappingURL=logger.js.map

package/dist/lib/util/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../lib/util/logger.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,KAAK,CAAC,IAAI;IACxB,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,GAAG,EAAE,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACxE,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAI;IACxB,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,GAAG,EAAE,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACxE,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAI;IACvB,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACtE,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAI;IACvB,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACtE,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAI;IACxB,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,GAAG,EAAE,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACxE,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAI;IACxB,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,GAAG,EAAE,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACxE,CAAC"}

package/lib/main.ts

@@ -0,0 +1,3 @@
+export function main() {
+  console.log('This is the main export')
+}

package/lib/mfa/index.ts

@@ -0,0 +1,89 @@
+import * as OTPAuth from 'otpauth'
+import QRCode from 'qrcode'
+
+export interface MfaSetupDetails {
+  secret: string
+  uri: string
+  qrCode: string
+}
+
+/**
+ * Generates a new random base32 secret.
+ * @param size The size of the secret in bytes (default 20).
+ * @returns The base32 string representation of the secret.
+ */
+export function generateSecret(size: number = 20): string {
+  const secret = new OTPAuth.Secret({ size })
+  return secret.base32
+}
+
+/**
+ * Generates setup details for the client, including the secret, the otpauth URI, and a QR code Data URL.
+ * @param appName The name of the application (Issuer).
+ * @param username The username (Label).
+ * @param secret The base32 secret (optional, will be generated if not provided).
+ */
+export async function generateSetupDetails(
+  appName: string,
+  username: string,
+  secret?: string
+): Promise<MfaSetupDetails> {
+  const mfaSecret = secret ? OTPAuth.Secret.fromBase32(secret) : new OTPAuth.Secret({ size: 20 })
+  const base32Secret = mfaSecret.base32
+
+  const totp = new OTPAuth.TOTP({
+    issuer: appName,
+    label: username,
+    algorithm: 'SHA1',
+    digits: 6,
+    period: 30,
+    secret: mfaSecret
+  })
+
+  const uri = totp.toString()
+  const qrCode = await QRCode.toDataURL(uri)
+
+  return {
+    secret: base32Secret,
+    uri,
+    qrCode
+  }
+}
+
+/**
+ * Validates a TOTP token against a secret.
+ * @param token The token to verify.
+ * @param secret The base32 secret.
+ * @param window The acceptable time window (default 1, meaning +/- 30 seconds).
+ * @returns True if valid, false otherwise.
+ */
+export function verifyToken(token: string, secret: string, window: number = 1): boolean {
+  if (!token || !secret) return false
+
+  const totp = new OTPAuth.TOTP({
+    algorithm: 'SHA1',
+    digits: 6,
+    period: 30,
+    secret: OTPAuth.Secret.fromBase32(secret)
+  })
+
+  // validate returns null if invalid, or the delta (integer) if valid
+  const delta = totp.validate({ token, window })
+  return delta !== null
+}
+
+/**
+ * Generates the current TOTP token for a given secret.
+ * Useful for testing or recovery scenarios.
+ * @param secret The base32 secret.
+ */
+export function generateToken(secret: string): string {
+  const totp = new OTPAuth.TOTP({
+    algorithm: 'SHA1',
+    digits: 6,
+    period: 30,
+    secret: OTPAuth.Secret.fromBase32(secret)
+  })
+
+  return totp.generate()
+}

package/lib/util/logger.ts

@@ -0,0 +1,23 @@
+export function trace(data) {
+  global.isLoggingEnabled && global.log?.trace && global.log.trace(data)
+}
+
+export function debug(data) {
+  global.isLoggingEnabled && global.log?.debug && global.log.debug(data)
+}
+
+export function info(data) {
+  global.isLoggingEnabled && global.log?.info && global.log.info(data)
+}
+
+export function warn(data) {
+  global.isLoggingEnabled && global.log?.warn && global.log.warn(data)
+}
+
+export function error(data) {
+  global.isLoggingEnabled && global.log?.error && global.log.error(data)
+}
+
+export function fatal(data) {
+  global.isLoggingEnabled && global.log?.fatal && global.log.fatal(data)
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@volcanicminds/tools",
+  "version": "0.0.2",
+  "description": "Tools for the volcanic (minds) backend",
+  "keywords": [
+    "volcanic",
+    "open source",
+    "tools",
+    "typescript",
+    "esm",
+    "mfa",
+    "otp",
+    "totp"
+  ],
+  "homepage": "https://volcanicminds.com",
+  "bugs": {
+    "url": "https://github.com/volcanicminds/volcanic-tools/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volcanicminds/volcanic-tools.git"
+  },
+  "license": "MIT",
+  "author": "Volcanic Minds <developers@volcanicminds.com> (https://volcanicminds.com)",
+  "maintainers": [
+    {
+      "name": "Developers",
+      "email": "developers@volcanicminds.com",
+      "url": "https://volcanicminds.com"
+    }
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./mfa": {
+      "types": "./dist/lib/mfa/index.d.ts",
+      "import": "./dist/lib/mfa/index.js",
+      "require": "./dist/lib/mfa/index.js"
+    },
+    "./logger": {
+      "types": "./dist/lib/util/logger.d.ts",
+      "import": "./dist/lib/util/logger.js",
+      "require": "./dist/lib/util/logger.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "dist",
+    "lib"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "reset": "npm install && npm update && npm run build",
+    "upgrade-deps": "npx npm-check-updates -u",
+    "combine": "node combine.js"
+  },
+  "dependencies": {
+    "otpauth": "^9.3.5",
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/qrcode": "^1.5.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "module": "dist/index.js",
+  "sideEffects": false,
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/index.d.ts"
+      ],
+      "mfa": [
+        "dist/lib/mfa/index.d.ts"
+      ],
+      "logger": [
+        "dist/lib/util/logger.d.ts"
+      ]
+    }
+  }
+}