@luisotaviopilotto/cryptmp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Otávio
+
+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,96 @@
+# Cryptmp — Node.js
+
+Implementação em Node.js com `node:crypto` nativo (zero dependências).
+Interoperável com as versões
+[**Go**](https://github.com/luisotaviopilotto/cryptmp-go) e
+[**Python**](https://github.com/luisotaviopilotto/cryptmp-py): um hash gerado
+aqui verifica lá e vice-versa, com a mesma chave global.
+
+Requer **Node 16+** (OpenSSL 1.1.1+, para `sha3-256` e `shake256`).
+
+## Instalação
+
+```bash
+npm install cryptmp
+```
+
+> O comando acima só funciona depois que o pacote estiver **publicado no npm**
+> com esse nome. Enquanto não publicar, dá para instalar do jeito local — mesmo
+> nome, mesmo `require('cryptmp')`:
+>
+> ```bash
+> # a) direto da pasta do projeto
+> npm install /caminho/para/cryptmp-js
+>
+> # b) via tarball (gera cryptmp-1.0.0.tgz)
+> cd cryptmp-js && npm pack
+> npm install /caminho/para/cryptmp-1.0.0.tgz
+>
+> # c) direto do GitHub
+> npm install git+https://github.com/luisotaviopilotto/cryptmp-js.git
+> ```
+
+### Publicar no npm (para o `npm install cryptmp` funcionar para todos)
+
+```bash
+cd cryptmp-js
+npm login
+npm publish            # nome "cryptmp" precisa estar livre no npm
+```
+
+Se o nome `cryptmp` já estiver ocupado, use um nome com escopo — troque
+`"name"` no `package.json` para `"@luisotaviopilotto/cryptmp"` e rode
+`npm publish --access public`; a instalação vira
+`npm install @luisotaviopilotto/cryptmp`.
+
+## Uso
+
+```js
+const th = require('cryptmp'); // instalado; ou require('./cryptmp') local
+
+// 1. Chave global de 32 bytes — de um segredo, nunca do banco.
+const key = th.Key.fromHex(1, '…64 hex chars…'); // ou th.Key.generate(1)
+const kr = new th.Keyring(key);
+
+// 2. Hasher (calibre o custo).
+const hasher = new th.Cryptmp(kr, { cost: 12 });
+
+// 3. Cadastro / login.
+const encoded = hasher.hash('minha_senha');          // grave no banco
+const ok = hasher.verify('minha_senha', encoded);    // true
+
+// 4. Upgrade transparente.
+if (ok && hasher.needsRehash(encoded)) {
+  // regrave hasher.hash('minha_senha')
+}
+```
+
+### Rotação de chave
+
+```js
+const k1 = th.Key.fromHex(1, '…antiga…');
+const k2 = th.Key.generate(2);
+const kr = new th.Keyring(k2, k1);        // k2 ativa, k1 legada
+const hasher = new th.Cryptmp(kr, { cost: 12 });
+hasher.verify(pw, hashAntigo);            // acha k1 pelo keyid automaticamente
+```
+
+## CLI
+
+```bash
+export CRYPTMP_KEY=$(node bin/cryptmp.js gen-key)
+printf 'minha_senha' | node bin/cryptmp.js hash --cost 12
+node bin/cryptmp.js verify '$th$1$12$1$...' 'minha_senha'
+```
+
+## Testes
+
+```bash
+npm test        # ou: node test.js  (KAT + roundtrip)
+```
+
+Os vetores em `vectors.json` são idênticos aos das versões Go e Python.
+
+> ⚠️ Construção educacional/de pesquisa, não auditada. Para produção prefira
+> `argon2`/`scrypt`. Modelo de segurança e limitações no
+> [README do cryptmp-go](https://github.com/luisotaviopilotto/cryptmp-go#limitações-de-segurança).

package/bin/cryptmp.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict';
+// Cryptmp CLI (Node).
+//   cryptmp gen-key
+//   cryptmp hash   [--cost N] [--key HEX | env CRYPTMP_KEY] [password]
+//   cryptmp verify [--key HEX | env CRYPTMP_KEY] <encoded> [password]
+const th = require('../cryptmp');
+
+function loadKey(hexFlag) {
+  const val = hexFlag || process.env.CRYPTMP_KEY || '';
+  if (!val) {
+    console.error('error: no key (pass --key or set CRYPTMP_KEY)');
+    process.exit(1);
+  }
+  return th.Key.fromHex(1, val);
+}
+
+function readPassword(arg) {
+  if (arg !== undefined) return arg;
+  try {
+    const data = require('fs').readFileSync(0, 'utf8');
+    return data.replace(/[\r\n]+$/, '');
+  } catch {
+    return '';
+  }
+}
+
+function popFlag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  const val = args[i + 1];
+  args.splice(i, 2);
+  return val;
+}
+
+function main() {
+  const [, , cmd, ...rest] = process.argv;
+  if (cmd === 'gen-key') {
+    console.log(th.Key.generate(1).hex);
+    return;
+  }
+  if (cmd === 'hash') {
+    const cost = Number(popFlag(rest, '--cost') ?? th.DEFAULT_COST);
+    const key = loadKey(popFlag(rest, '--key'));
+    const hasher = new th.Cryptmp(new th.Keyring(key), { cost });
+    console.log(hasher.hash(readPassword(rest[0])));
+    return;
+  }
+  if (cmd === 'verify') {
+    const key = loadKey(popFlag(rest, '--key'));
+    const encoded = rest[0];
+    if (!encoded) {
+      console.error('usage: cryptmp verify [--key HEX] <encoded> [password]');
+      process.exit(1);
+    }
+    const hasher = new th.Cryptmp(new th.Keyring(key));
+    const ok = hasher.verify(readPassword(rest[1]), encoded);
+    console.log(ok ? 'OK: password matches' : 'FAIL: password does not match');
+    process.exit(ok ? 0 : 1);
+  }
+  console.error('usage: cryptmp <gen-key|hash|verify> ...');
+  process.exit(2);
+}
+
+main();

package/cryptmp.js

@@ -0,0 +1,254 @@
+'use strict';
+/**
+ * Cryptmp — password hashing with a temporal pepper (Node.js, zero deps).
+ *
+ * Interoperable with the Go and Python implementations: a hash produced by any
+ * one verifies in the others given the same global key. All primitives are the
+ * standard SHA-3 family via node:crypto (requires OpenSSL 1.1.1+, Node 16+):
+ *
+ *   - SHA3-256        fixed 256-bit digests
+ *   - HMAC-SHA3-256   temporal pepper + blinding
+ *   - SHAKE256 (XOF)  memory-hard KDF row/seed expansion
+ *
+ * WARNING: educational/research construction, not independently audited. Prefer
+ * argon2/scrypt for production unless reviewed by a cryptographer.
+ */
+const crypto = require('crypto');
+
+// ---- Parameters ----------------------------------------------------------
+const VERSION = 1;
+const TIME_WINDOW = 30;
+const MEMORY_COL = 1024;
+const MIN_COST = 4;
+const MAX_COST = 31;
+const DEFAULT_COST = 12;
+const DEFAULT_SALT_SIZE = 16;
+const HASH_OUTPUT = 32;
+const KEY_SIZE = 32;
+
+// ---- Primitives ----------------------------------------------------------
+const sha3_256 = (buf) => crypto.createHash('sha3-256').update(buf).digest();
+const hmacSha3_256 = (key, msg) =>
+  crypto.createHmac('sha3-256', key).update(msg).digest();
+const shake256 = (data, n) =>
+  crypto.createHash('shake256', { outputLength: n }).update(data).digest();
+
+function u16(x) {
+  const b = Buffer.alloc(2);
+  b.writeUInt16BE(x);
+  return b;
+}
+function u32(x) {
+  const b = Buffer.alloc(4);
+  b.writeUInt32BE(x >>> 0);
+  return b;
+}
+function u64(x) {
+  const b = Buffer.alloc(8);
+  b.writeBigUInt64BE(BigInt(x));
+  return b;
+}
+function xorBuf(a, b) {
+  const out = Buffer.allocUnsafe(a.length);
+  for (let i = 0; i < a.length; i++) out[i] = a[i] ^ b[i];
+  return out;
+}
+
+// ---- Core functions ------------------------------------------------------
+function normalizePassword(password) {
+  return sha3_256(Buffer.from(password.normalize('NFC'), 'utf8'));
+}
+
+function derivePepper(key, t, salt, cost) {
+  return hmacSha3_256(key, Buffer.concat([u64(t), salt, u16(cost)]));
+}
+
+function blindPassword(b, pepper, salt) {
+  return hmacSha3_256(pepper, Buffer.concat([b, salt]));
+}
+
+function memoryHardKDF(blinded, salt, cost) {
+  const rows = cost * 1024;
+  const seed = shake256(Buffer.concat([blinded, salt]), 32);
+
+  const m = new Array(rows);
+  m[0] = shake256(Buffer.concat([seed, u32(0)]), MEMORY_COL);
+  for (let i = 1; i < rows; i++) {
+    m[i] = shake256(Buffer.concat([m[i - 1], u32(i)]), MEMORY_COL);
+  }
+
+  for (let rnd = 0; rnd < 3; rnd++) {
+    const rb = u32(rnd);
+    for (let i = 0; i < rows; i++) {
+      const j = m[i].readUInt32BE(0) % rows;
+      const mixed = xorBuf(m[i], m[j]);
+      m[i] = shake256(Buffer.concat([mixed, rb, u32(i)]), MEMORY_COL);
+    }
+  }
+
+  const final = Buffer.concat([
+    m[rows - 4], m[rows - 3], m[rows - 2], m[rows - 1], salt, u16(cost),
+  ]);
+  return sha3_256(final);
+}
+
+function computeHash(key, keyId, salt, cost, t, password) {
+  const b = normalizePassword(password);
+  const pepper = derivePepper(key, t, salt, cost);
+  const blinded = blindPassword(b, pepper, salt);
+  const digest = memoryHardKDF(blinded, salt, cost);
+  return { encoded: encode(VERSION, cost, keyId, salt, digest, t), digest };
+}
+
+// ---- Encoding ------------------------------------------------------------
+function encode(version, cost, keyId, salt, digest, t) {
+  return `$th$${version}$${cost}$${keyId}$${salt.toString('hex')}$${digest.toString('hex')}$${t.toString()}`;
+}
+
+const DIGITS_RE = /^[0-9]+$/;
+const MAX_T = 2n ** 64n - 1n;
+
+// Strict ASCII decimal only: Number()/BigInt() would also accept "0x10",
+// "1e2" and surrounding whitespace, which Go/Python reject.
+function parseUint(s, lo, hi) {
+  if (!DIGITS_RE.test(s)) throw new Error('cryptmp: malformed hash string');
+  const n = Number(s);
+  if (!Number.isSafeInteger(n) || n < lo || n > hi)
+    throw new Error('cryptmp: malformed hash string');
+  return n;
+}
+
+function parse(encoded) {
+  const parts = encoded.split('$');
+  // Leading "$" -> parts[0] === ""
+  if (parts.length !== 8 || parts[0] !== '' || parts[1] !== 'th') {
+    throw new Error('cryptmp: malformed hash string');
+  }
+  const version = parseUint(parts[2], 1, 255);
+  const cost = parseUint(parts[3], MIN_COST, MAX_COST);
+  const keyId = parseUint(parts[4], 0, 0xffffffff);
+  const salt = Buffer.from(parts[5], 'hex');
+  const digest = Buffer.from(parts[6], 'hex');
+  if (!DIGITS_RE.test(parts[7])) throw new Error('cryptmp: malformed hash string');
+  const t = BigInt(parts[7]);
+  if (t > MAX_T) throw new Error('cryptmp: malformed hash string');
+  // salt hex must round-trip and be 16..32 bytes
+  if (salt.length < 16 || salt.length > 32 || salt.toString('hex') !== parts[5].toLowerCase())
+    throw new Error('cryptmp: malformed hash string');
+  if (digest.length !== HASH_OUTPUT || digest.toString('hex') !== parts[6].toLowerCase())
+    throw new Error('cryptmp: malformed hash string');
+  return { version, cost, keyId, salt, digest, t };
+}
+
+// ---- Keys ----------------------------------------------------------------
+class Key {
+  constructor(id, bytes) {
+    if (!Buffer.isBuffer(bytes) || bytes.length !== KEY_SIZE)
+      throw new Error('cryptmp: global key must be exactly 32 bytes');
+    this.id = id;
+    this.bytes = bytes;
+  }
+  static generate(id) {
+    return new Key(id, crypto.randomBytes(32));
+  }
+  static fromHex(id, hex) {
+    return new Key(id, Buffer.from(hex, 'hex'));
+  }
+  get hex() {
+    return this.bytes.toString('hex');
+  }
+}
+
+class Keyring {
+  constructor(active, ...legacy) {
+    this._keys = new Map([[active.id, active]]);
+    this._active = active.id;
+    for (const k of legacy) {
+      if (this._keys.has(k.id)) throw new Error(`duplicate key id ${k.id}`);
+      this._keys.set(k.id, k);
+    }
+  }
+  active() {
+    return this._keys.get(this._active);
+  }
+  byId(id) {
+    return this._keys.get(id);
+  }
+  add(k) {
+    this._keys.set(k.id, k);
+  }
+  setActive(id) {
+    if (!this._keys.has(id)) throw new Error('cryptmp: unknown key id');
+    this._active = id;
+  }
+}
+
+// ---- Hasher --------------------------------------------------------------
+class Cryptmp {
+  /**
+   * @param {Keyring} keyring
+   * @param {{cost?:number, saltSize?:number, timeWindow?:number,
+   *          tolerance?:number, now?:() => number}} [opts]
+   */
+  constructor(keyring, opts = {}) {
+    this.keyring = keyring;
+    this.cost = opts.cost ?? DEFAULT_COST;
+    this.saltSize = opts.saltSize ?? DEFAULT_SALT_SIZE;
+    this.timeWindow = opts.timeWindow ?? TIME_WINDOW;
+    this.tolerance = opts.tolerance ?? 1;
+    this.now = opts.now ?? (() => Date.now() / 1000);
+    if (this.cost < MIN_COST || this.cost > MAX_COST)
+      throw new Error('cryptmp: cost out of range [4,31]');
+    if (this.saltSize < 16 || this.saltSize > 32)
+      throw new Error('cryptmp: salt size must be 16..32');
+  }
+
+  hash(password) {
+    const salt = crypto.randomBytes(this.saltSize);
+    const t = BigInt(Math.floor(Math.floor(this.now()) / this.timeWindow));
+    const key = this.keyring.active();
+    return computeHash(key.bytes, key.id, salt, this.cost, t, password).encoded;
+  }
+
+  verify(password, encoded) {
+    const p = parse(encoded);
+    const key = this.keyring.byId(p.keyId);
+    if (!key) throw new Error('cryptmp: unknown key id in hash');
+    const b = normalizePassword(password);
+    let match = 0;
+    const tol = BigInt(this.tolerance);
+    for (let d = -tol; d <= tol; d++) {
+      const tw = p.t + d;
+      if (tw < 0n || tw > MAX_T) continue;
+      const pepper = derivePepper(key.bytes, tw, p.salt, p.cost);
+      const blinded = blindPassword(b, pepper, p.salt);
+      const cand = memoryHardKDF(blinded, p.salt, p.cost);
+      // constant-time; accumulate without early return
+      if (cand.length === p.digest.length && crypto.timingSafeEqual(cand, p.digest)) {
+        match |= 1;
+      }
+    }
+    return match === 1;
+  }
+
+  needsRehash(encoded) {
+    let p;
+    try {
+      p = parse(encoded);
+    } catch {
+      return true;
+    }
+    if (p.version !== VERSION) return true;
+    if (p.keyId !== this.keyring.active().id) return true;
+    if (p.cost < this.cost) return true;
+    return false;
+  }
+}
+
+module.exports = {
+  VERSION, MIN_COST, MAX_COST, DEFAULT_COST, TIME_WINDOW,
+  Key, Keyring, Cryptmp,
+  // low-level (for tests / advanced use)
+  normalizePassword, derivePepper, blindPassword, memoryHardKDF,
+  computeHash, encode, parse,
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@luisotaviopilotto/cryptmp",
+  "version": "1.0.0",
+  "description": "Password hashing with a temporal pepper (SHA-3 family). Interoperable with the Go and Python implementations.",
+  "main": "cryptmp.js",
+  "type": "commonjs",
+  "bin": {
+    "cryptmp": "bin/cryptmp.js"
+  },
+  "files": [
+    "cryptmp.js",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "password",
+    "hashing",
+    "sha3",
+    "shake256",
+    "pepper",
+    "kdf",
+    "cryptmp",
+    "crypt"
+  ],
+  "author": "Luis Otavio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luisotaviopilotto/cryptmp-js.git"
+  }
+}