@natsubate/secrets-token-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 natsubate
+
+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,69 @@
+# @natsubate/secrets-token-generator [![npm version](https://badge.fury.io/js/@natsubate%2Fsecrets-token-generator.svg)](https://www.npmjs.com/package/@natsubate/secrets-token-generator)
+
+A lightweight utility for generating cryptographically secure random tokens in Node.js, similar to Python's secrets module.
+
+## Install
+
+```bash
+npm install @natsubate/secrets-token-generator
+```
+
+## Usage
+
+```TypeScript
+import { tokenBytes, tokenHex, tokenUrlSafe } from "@natsubate/secrets-token-generator";
+
+const tokenByBuffer = tokenBytes(32); // 32bytes secure random bytes
+
+const tokenByHex = tokenHex(32); // 32bytes secure random HEX string
+console.log(tokenByHex); // -> 7b6d3b21cd1a40b3baf2013c475247fa2c577bfef691e4661cce35fc846f328f
+
+const tokenByUrlSafeBase64 = tokenUrlSafe(32); // 32bytes secure random by Base64URL
+console.log(tokenByUrlSafeBase64); // -> 7H8lLtZ6A5C96rfpxtbsRiB2lmXj3ctukOM4kywRIwY
+```
+
+## API
+
+### tokenBytes(bytes: number): Buffer
+
+Generates a random value of the specified byte count using cryptographically secure pseudo-random number generator (CSPRNG) and returns the buffer.
+
+- **`bytes`**: `number` - Random bytes length (e.g., 32).
+- **Returns**: `Buffer` - Raw bytes.
+
+### tokenHex(bytes: number): string
+
+Generates a random value of the specified byte length using CSPRNG and returns the HEX string.
+
+- **`bytes`**: `number` - Random bytes length (e.g., 32).
+- **Returns**: `string` - HEX encoded token.
+
+### tokenUrlSafe(bytes: number): string
+
+Generates a random value of the specified byte length using CSPRNG and returns a Base64 URL string.
+
+- **`bytes`**: `number` - Random bytes length (e.g., 32).
+- **Returns**: `string` - Base64URL encoded token.
+
+## Supported Environments
+
+* Node.js 18 or later
+
+## TypeScript Type Definition
+
+Included.
+
+## Security Notice
+
+* The implementation uses the Node.js standard module `crypto.randomBytes`.
+* While it can be used for security-critical purposes such as CSRF tokens, session IDs, and API keys,
+ensure the required entropy amount (byte length) is appropriately set according to your use case.
+* Also consider the storage and transmission methods for generated tokens (e.g., using HTTPS, setting the Secure cookie flag).
+
+## Notes
+
+* All functions are synchronous.
+
+## License
+
+* MIT License

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export declare const tokenBytes: (bytes: number) => Buffer;
+export declare const tokenHex: (bytes: number) => string;
+export declare const tokenUrlSafe: (bytes: number) => string;

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// -*- coding: utf-8 -*-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenUrlSafe = exports.tokenHex = exports.tokenBytes = void 0;
+const node_crypto_1 = require("node:crypto");
+const tokenBytes = (bytes) => {
+    if (bytes < 1) {
+        throw new Error("bytes must be positive");
+    }
+    ;
+    return (0, node_crypto_1.randomBytes)(bytes);
+};
+exports.tokenBytes = tokenBytes;
+const tokenHex = (bytes) => {
+    return (0, exports.tokenBytes)(bytes).toString("hex");
+};
+exports.tokenHex = tokenHex;
+const tokenUrlSafe = (bytes) => {
+    return (0, exports.tokenBytes)(bytes).toString("base64url");
+};
+exports.tokenUrlSafe = tokenUrlSafe;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@natsubate/secrets-token-generator",
+  "version": "1.0.0",
+  "description": "A lightweight utility for generating cryptographically secure random tokens in Node.js, similar to Python's secrets module.",
+  "repository": "https://github.com/natsubate/secrets-token-generator.git",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "",
+  "keywords": [
+    "secrets",
+    "crypto",
+    "token",
+    "CSPRNG",
+    "base64url"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "typescript": "^5.9.3"
+  }
+}