@prsm/hash 1.0.1 → 2.0.1

package/README.md

@@ -1,41 +1,56 @@
-# hash
+# @prsm/hash
 
-A very simple string hashing library.
+Salted string hashing on top of `node:crypto`. Zero dependencies. Defaults to `scrypt` for password-safe hashing.
 
-# create
+## Installation
 
-```typescript
-import { hash } from "@prsm/hash";
+```bash
+npm install @prsm/hash
+```
+
+## Usage
+
+```js
+import hash from "@prsm/hash"
 
-hash.create("secret");
-hash.create("secret");
-hash.create("secret");
+const encoded = await hash.encode("my password")
+// scrypt:UfH7lmEc5d...:6qG75Cp5hys...
 
-// sha256:UfH7lmEc5dr65iFPmvsKthzAgMHtdV6Qb4FXYSqlnOaQoZmqQWLBrPnJGLZmQontirQZKO9nTIz+zs544n0x7Q==:6qG75Cp5hysNWs+8TO65fzc1FaSZxykaWa3iatPrw4s=
-// sha256:Wq6vrcGG4mKlM7r8DAuDHcYxJlG8fOEoO2sNWofl/snmsZPTaBuy8Dg6i2J28TdcncSgK8EhrCqgv69h5Kk2xA==:QvAc6op8ScJex38AYrZUtFDd69c4OJv5SsVIRgR+FPw=
-// sha256:e16qmZpJiy1qvGycPkJz0qQnCdyAguGAFV8rqCokiFml10nl9lVU1v0hZ6QBy+laI0AYkHsYtt6wMkEOuNhpMw==:L3bHZeriSAjy8wEIz/fURxhOqxa8KltuvpHPE/nE/eQ=
-// sha256:0SA+O819D52jZOqWuzIWa+KLyT+Ck+b5ze4HI7fAJOhRW3FYk527GnuVOS/pricLy1KqwUfk5wWyQx4z5x3fsA==:wPs8DRMOrZEJYeaPxZzccGPJSozGvNqRhhS6f8ITOyM=
+await hash.verify(encoded, "my password")  // true
+await hash.verify(encoded, "wrong")        // false
 ```
 
-# verify
+Each call to `encode()` generates a random salt, so the same input produces different hashes. `verify()` extracts the algorithm and salt from the hash string to compare.
+
+## Algorithms
+
+Default is `scrypt` (password-safe, ~5ms per hash). For fast non-security hashing, use `sha256` or `sha512`.
 
-```typescript
-import { hash } from "@prsm/hash";
+```js
+import { Hasher } from "@prsm/hash"
 
-const valid = hash.verify(
-  "secret",
-  "sha256:0SA+O819D52jZOqWuzIWa+KLyT+Ck+b5ze4HI7fAJOhRW3FYk527GnuVOS/pricLy1KqwUfk5wWyQx4z5x3fsA==:wPs8DRMOrZEJYeaPxZzccGPJSozGvNqRhhS6f8ITOyM=",
-);
-// valid = true
+const fast = new Hasher("sha256")
+await fast.encode("not a password")
+
+const secure = new Hasher("scrypt", 128)  // custom salt length
+await secure.encode("a password")
 ```
 
-# custom hasher
+## API
+
+| Function | Description |
+|---|---|
+| `encode(string)` | Hash a string with a random salt. Returns a promise. |
+| `verify(encoded, unencoded)` | Check if a string matches a hash. Returns a promise. |
 
-```typescript
-import { Hasher } from "@prsm/hash";
+## Hash Format
 
-const hash = new Hasher("sha512", 128);
-// hash.create("..");
-// hash.verify("..", "sha512:...")
 ```
+algorithm:salt:digest
+```
+
+Hashes are self-describing - `verify()` reads the algorithm from the hash string, so a scrypt hash can be verified by a sha256-configured instance and vice versa.
+
+## License
 
+Apache-2.0

package/package.json

@@ -1,32 +1,31 @@
 {
   "name": "@prsm/hash",
-  "version": "1.0.1",
-  "description": "",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "version": "2.0.1",
+  "description": "Simple salted string hashing on top of node:crypto",
   "type": "module",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
   "exports": {
     ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
     }
   },
-  "keywords": [],
+  "types": "./types/index.d.ts",
+  "files": [
+    "src",
+    "types"
+  ],
+  "scripts": {
+    "test": "vitest --reporter=verbose --run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npx tsc --declaration --allowJs --emitDeclarationOnly --skipLibCheck --target es2020 --module nodenext --moduleResolution nodenext --strict false --esModuleInterop true --outDir ./types src/index.js"
+  },
   "author": "nvms",
-  "license": "ISC",
+  "license": "Apache-2.0",
   "devDependencies": {
-    "@types/node": "^20.4.1",
-    "bumpp": "^9.1.1",
-    "tsup": "^7.1.0",
-    "typescript": "^5.1.6"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   },
-  "scripts": {
-    "build": "rm -rf dist && tsup src/index.ts --format cjs,esm --dts --clean --minify",
-    "release": "bumpp package.json --commit 'Release %s' --push --tag && pnpm publish --access public"
+  "engines": {
+    "node": ">=20"
   }
-}
+}

package/src/index.js

@@ -0,0 +1,58 @@
+import crypto from "node:crypto"
+
+export class Hasher {
+  /**
+   * @param {'scrypt' | 'sha256' | 'sha512'} [algorithm]
+   * @param {number} [saltLength]
+   */
+  constructor(algorithm = "scrypt", saltLength = 64) {
+    this.algorithm = algorithm
+    this.saltLength = saltLength
+  }
+
+  /**
+   * @param {string} string
+   * @returns {Promise<string>} encoded hash in format "algorithm:salt:digest"
+   */
+  async encode(string) {
+    const salt = crypto.randomBytes(this.saltLength).toString("base64")
+    return this._hash(string, this.algorithm, salt)
+  }
+
+  /**
+   * @param {string} encoded - hash string to verify against
+   * @param {string} unencoded - plain string to check
+   * @returns {Promise<boolean>}
+   */
+  async verify(encoded, unencoded) {
+    const { algorithm, salt } = this._parse(encoded)
+    return (await this._hash(unencoded, algorithm, salt)) === encoded
+  }
+
+  async _hash(string, algorithm, salt) {
+    if (algorithm === "scrypt") {
+      const key = await new Promise((resolve, reject) => {
+        crypto.scrypt(string, salt, 64, (err, derivedKey) => {
+          if (err) reject(err)
+          else resolve(derivedKey)
+        })
+      })
+      return `scrypt:${salt}:${key.toString("base64")}`
+    }
+    const hash = crypto.createHash(algorithm)
+    hash.update(string)
+    hash.update(salt, "utf8")
+    return `${algorithm}:${salt}:${hash.digest("base64")}`
+  }
+
+  _parse(encoded) {
+    const parts = encoded.split(":")
+    if (parts.length !== 3) {
+      throw new Error(`Invalid hash string. Expected 3 parts, got ${parts.length}`)
+    }
+    return { algorithm: parts[0], salt: parts[1], digest: parts[2] }
+  }
+}
+
+const hash = new Hasher()
+export default hash

package/types/index.d.ts

@@ -0,0 +1,28 @@
+export class Hasher {
+    /**
+     * @param {'scrypt' | 'sha256' | 'sha512'} [algorithm]
+     * @param {number} [saltLength]
+     */
+    constructor(algorithm?: "scrypt" | "sha256" | "sha512", saltLength?: number);
+    algorithm: "scrypt" | "sha256" | "sha512";
+    saltLength: number;
+    /**
+     * @param {string} string
+     * @returns {Promise<string>} encoded hash in format "algorithm:salt:digest"
+     */
+    encode(string: string): Promise<string>;
+    /**
+     * @param {string} encoded - hash string to verify against
+     * @param {string} unencoded - plain string to check
+     * @returns {Promise<boolean>}
+     */
+    verify(encoded: string, unencoded: string): Promise<boolean>;
+    _hash(string: any, algorithm: any, salt: any): Promise<string>;
+    _parse(encoded: any): {
+        algorithm: any;
+        salt: any;
+        digest: any;
+    };
+}
+export default hash;
+declare const hash: Hasher;

package/dist/index.cjs

@@ -1 +0,0 @@
-var l=Object.create;var a=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var c=Object.getPrototypeOf,u=Object.prototype.hasOwnProperty;var d=(r,s)=>{for(var t in s)a(r,t,{get:s[t],enumerable:!0})},g=(r,s,t,h)=>{if(s&&typeof s=="object"||typeof s=="function")for(let i of p(s))!u.call(r,i)&&i!==t&&a(r,i,{get:()=>s[i],enumerable:!(h=m(s,i))||h.enumerable});return r};var A=(r,s,t)=>(t=r!=null?l(c(r)):{},g(s||!r||!r.__esModule?a(t,"default",{value:r,enumerable:!0}):t,r)),b=r=>g(a({},"__esModule",{value:!0}),r);var f={};d(f,{Hasher:()=>n,hash:()=>v});module.exports=b(f);var e=A(require("crypto"),1),n=class{constructor(s="sha256",t=64){this.algorithm=s,this.saltLength=t}verify(s,t){let{algorithm:h,salt:i}=this.parse(s);return this.hash(t,h,i)===s}encode(s){let t=e.default.randomBytes(this.saltLength).toString("base64");return this.hash(s,this.algorithm,t)}hash(s,t,h){let i=e.default.createHash(t);return i.update(s),i.update(h,"utf8"),`${t}:${h}:${i.digest("base64")}`}parse(s){let t=s.split(":");if(t.length!==3)throw new Error(`Invalid hash string. Expected 3 parts, got ${t.length}`);let h=t[0],i=t[1],o=t[2];return{algorithm:h,salt:i,digest:o}}},v=new n;0&&(module.exports={Hasher,hash});

package/dist/index.d.cts

@@ -1,13 +0,0 @@
-type Algorithm = "sha256" | "sha512";
-declare class Hasher {
-    private algorithm;
-    private saltLength;
-    constructor(algorithm?: Algorithm, saltLength?: number);
-    verify(encoded: string, unencoded: string): boolean;
-    encode(string: string): string;
-    hash(string: string, algorithm: Algorithm, salt: string): string;
-    private parse;
-}
-declare const hash: Hasher;
-
-export { Hasher, hash };

package/dist/index.d.ts

@@ -1,13 +0,0 @@
-type Algorithm = "sha256" | "sha512";
-declare class Hasher {
-    private algorithm;
-    private saltLength;
-    constructor(algorithm?: Algorithm, saltLength?: number);
-    verify(encoded: string, unencoded: string): boolean;
-    encode(string: string): string;
-    hash(string: string, algorithm: Algorithm, salt: string): string;
-    private parse;
-}
-declare const hash: Hasher;
-
-export { Hasher, hash };

package/dist/index.js

@@ -1 +0,0 @@
-import a from"crypto";var h=class{constructor(s="sha256",t=64){this.algorithm=s,this.saltLength=t}verify(s,t){let{algorithm:i,salt:r}=this.parse(s);return this.hash(t,i,r)===s}encode(s){let t=a.randomBytes(this.saltLength).toString("base64");return this.hash(s,this.algorithm,t)}hash(s,t,i){let r=a.createHash(t);return r.update(s),r.update(i,"utf8"),`${t}:${i}:${r.digest("base64")}`}parse(s){let t=s.split(":");if(t.length!==3)throw new Error(`Invalid hash string. Expected 3 parts, got ${t.length}`);let i=t[0],r=t[1],n=t[2];return{algorithm:i,salt:r,digest:n}}},o=new h;export{h as Hasher,o as hash};

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "module": "esnext",
-    "target": "es2021",
-    "moduleResolution": "node",
-    "outDir": "./dist",
-    "sourceMap": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "allowSyntheticDefaultImports": true,
-    "noImplicitAny": false,
-    "noImplicitReturns": false,
-    "strictNullChecks": false,
-    "baseUrl": "."
-  },
-  "exclude": [
-    "node_modules",
-    "lib"
-  ]
-}