@blamejs/core 0.8.42 → 0.8.49

package/lib/credential-hash.js

@@ -1,73 +1,44 @@
 "use strict";
 /**
- * b.credentialHash — envelope-versioned credential hashing.
+ * @module b.credentialHash
+ * @nav    Identity
+ * @title  Credential Hash
  *
- * Stores a verifiable digest of a credential (API key secret, shared
- * bearer token, etc.) as a base64-encoded envelope:
+ * @intro
+ *   Derive a deterministic, verifiable hash for credential lookup
+ *   (API-key secret, shared bearer token, webhook signing key) without
+ *   storing the credential itself. The default is an Argon2id-style
+ *   fingerprint over a SHAKE256 MAC — same chassis the password
+ *   primitive uses, but tuned for high-entropy machine-generated
+ *   secrets where memory-hard work is unnecessary.
  *
- *     byte 0: 0xC1 (CREDENTIAL_MAGIC)
- *     byte 1: <algorithm ID>
- *     bytes 2..N: algorithm-specific payload
+ *   Rows persist a base64 envelope:
  *
- * The verify path dispatches on byte 1, so old credentials remain
- * verifiable regardless of what ACTIVE.CRED_HASH points at today.
- * When a new algorithm becomes the framework default, existing rows
- * surface via `needsRehash()` and the next successful verify rotates
- * them transparently — same pattern as `b.auth.password.needsRehash`.
+ *     byte 0:    0xC1 (CREDENTIAL_MAGIC)
+ *     byte 1:    algorithm ID (0x01 SHAKE256 | 0x02 Argon2id)
+ *     bytes 2-N: algorithm-specific payload
  *
- *   var env = await b.credentialHash.hash(secretBytes);
- *   // → "wQEx..." (base64)
+ *   `verify` dispatches on the algorithm byte so old rows remain
+ *   verifiable regardless of what `ACTIVE.CRED_HASH` is today. When a
+ *   new algorithm becomes the framework default, existing rows surface
+ *   via `needsRehash()` and the next successful verify rotates them
+ *   transparently — same pattern as `b.auth.password.needsRehash`.
  *
- *   var ok = await b.credentialHash.verify(secretBytes, env);
- *   // → true / false
- *
- *   var info = b.credentialHash.inspect(env);
- *   // → { algoId, algoName, payloadBytes }
- *
- *   if (b.credentialHash.needsRehash(env)) {
- *     await db.update({ credentialHash: await b.credentialHash.hash(secretBytes) });
- *   }
- *
- * Active algorithm: SHAKE256 (0x01). Suitable for high-entropy random
- * secrets (≥ 128 bits) — fast verify (microseconds), brute-force
- * infeasible at the entropy level the framework generates. SHAKE256
- * is an XOF: the envelope payload length drives the digest size, so
- * a future operator can request a 96-byte (or 32-byte) digest without
- * a primitive change — the same algorithm ID covers all output sizes.
- * Operators with low-entropy or operator-supplied secrets should pin
- * Argon2id (0x02) per-registry: `hash(s, { algo: "argon2id" })`.
- *
- * Why SHAKE256 over SHA3-512 as the active:
- *   - SHAKE256 is an extensible-output function (XOF). The envelope
- *     payload's actual byte length tells the verify path how many
- *     bytes to recompute. Changing digest size = no algo rotation.
- *   - Same family as the framework KDF (`crypto.kdf`), so one
- *     primitive does double duty.
- *   - SHA-3 family fixed-size mode locks the byte count at 64 — the
- *     moment we want a different size, we'd have to rotate algos.
- *
- * Why not Argon2id by default for api-key:
- *   - Argon2id at framework defaults costs ~250ms per verify call.
- *     For request-path verification that's a real latency hit.
- *     SHAKE256 is microseconds.
- *   - For ≥128-bit random secrets, the memory-hard property buys
- *     nothing — brute force is infeasible regardless of hash.
- *
- * Why the envelope still matters with SHAKE256 as active:
- *   - Algorithm agility — when SHA-3 family ever shows weakness, or
- *     a stronger XOF lands, ACTIVE.CRED_HASH rotates with no need
- *     to re-issue every credential. Old rows verify under their
- *     stored algo byte; new rows use the active.
- *   - Transparent rehash via needsRehash() drains old algos at the
- *     pace of organic verify traffic.
+ *   Active algorithm: SHAKE256 (0x01). Suitable for high-entropy random
+ *   secrets (>= 128 bits) — verify is microseconds, brute force is
+ *   infeasible at the entropy level the framework generates. SHAKE256
+ *   is an XOF: the envelope payload length drives the digest size, so
+ *   a future operator can request a 96-byte (or 32-byte) digest with no
+ *   algorithm rotation. Operators with low-entropy or operator-supplied
+ *   secrets pin Argon2id per-registry via `{ algo: "argon2id" }`.
  *
- * Validation policy:
+ *   Validation tiers:
+ *     - hash() opts and secret shape — throw at call site (config-time)
+ *     - verify() malformed envelope or unknown algo ID — return false
+ *     - inspect() malformed envelope — return null
  *
- *   - hash() opts (algo, params)         → throw at call site
- *   - hash() secret type / length        → throw at call site
- *   - verify() envelope shape unparsable → return false (tolerant read)
- *   - verify() unknown algo ID           → return false (tolerant read)
- *   - inspect() bad envelope             → return null (tolerant read)
+ * @card
+ *   Derive a deterministic, verifiable hash for credential lookup (API-key secret, shared bearer token, webhook signing key) without storing the credential itself.
  */
 
 var crypto = require("./crypto");
@@ -196,6 +167,37 @@ function _decodeEnvelope(env) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive  b.credentialHash.hash
+ * @signature  b.credentialHash.hash(secret, opts?)
+ * @since      0.2.28
+ * @status     stable
+ * @compliance pci-dss, soc2, hipaa
+ * @related    b.credentialHash.verify, b.credentialHash.needsRehash, b.auth.password.hash
+ *
+ * Hash a credential secret into a base64 envelope ready for storage in
+ * a `credentialHash` column. Default algorithm is SHAKE256 with a
+ * 128-byte output; pass `{ algo: "argon2id" }` for low-entropy or
+ * operator-supplied secrets. Throws on a non-string-or-Buffer secret,
+ * an unknown algorithm, a non-object `params`, or a SHAKE256 length
+ * below the 16-byte (128-bit) collision-space floor.
+ *
+ * @opts
+ *   algo:   "shake256" | "argon2id",
+ *   params: {
+ *     length: number,                             // SHAKE256 output bytes (default 128)
+ *     ...                                         // Argon2id m / t / p forwarded to b.auth.password
+ *   },
+ *
+ * @example
+ *   var token = b.crypto.generateToken();          // 32 random bytes, base64url
+ *   var env   = await b.credentialHash.hash(token);
+ *   // → "wQE..." (base64 envelope)
+ *
+ *   // Operator-supplied (low-entropy) secret pins Argon2id:
+ *   var humanEnv = await b.credentialHash.hash("partner-shared-key", { algo: "argon2id" });
+ *   // → "wQI..." (base64 envelope, algo byte 0x02)
+ */
 async function hash(secret, opts) {
   _validateSecret(secret);
   _validateOpts(opts);
@@ -228,6 +230,29 @@ async function hash(secret, opts) {
     "credential-hash/unsupported");
 }
 
+/**
+ * @primitive  b.credentialHash.verify
+ * @signature  b.credentialHash.verify(secret, envelope)
+ * @since      0.2.28
+ * @status     stable
+ * @compliance pci-dss, soc2, hipaa
+ * @related    b.credentialHash.hash, b.credentialHash.needsRehash
+ *
+ * Constant-time check that `secret` matches the stored envelope.
+ * Tolerant read: malformed envelope / unknown algorithm / payload
+ * shorter than 16 bytes returns `false` without throwing, so callers
+ * write a single `if (!await verify(...))` branch without try/catch
+ * ceremony. Emits `credentialHash.verify` observability events with
+ * outcome + reason for SIEM dashboards.
+ *
+ * @example
+ *   var ok = await b.credentialHash.verify(presented, row.credentialHash);
+ *   if (!ok) {
+ *     res.statusCode = 401;
+ *     return res.end();
+ *   }
+ *   // → true / false
+ */
 async function verify(secret, envelope) {
   // Tolerant read: any malformed envelope → false. Lets operators write
   //   if (!await ch.verify(s, row.hash)) return res.status(401);
@@ -285,6 +310,26 @@ async function verify(secret, envelope) {
   return false;
 }
 
+/**
+ * @primitive  b.credentialHash.inspect
+ * @signature  b.credentialHash.inspect(envelope)
+ * @since      0.2.28
+ * @status     stable
+ * @related    b.credentialHash.needsRehash
+ *
+ * Decode the envelope's algorithm byte and payload length without
+ * verifying the secret. Returns `null` for any malformed envelope
+ * (missing magic byte, unknown algorithm, truncated). Used by
+ * operator dashboards to count rows-by-algorithm during a rotation
+ * window.
+ *
+ * @example
+ *   var info = b.credentialHash.inspect(row.credentialHash);
+ *   if (info && info.algoName === "shake256" && info.payloadBytes < 64) {
+ *     console.warn("legacy SHAKE256 row, will be rotated on next verify");
+ *   }
+ *   // → { algoId: 0x01, algoName: "shake256", payloadBytes: 128 }
+ */
 function inspect(envelope) {
   var decoded = _decodeEnvelope(envelope);
   if (!decoded) return null;
@@ -295,6 +340,33 @@ function inspect(envelope) {
   };
 }
 
+/**
+ * @primitive  b.credentialHash.needsRehash
+ * @signature  b.credentialHash.needsRehash(envelope, opts?)
+ * @since      0.2.28
+ * @status     stable
+ * @related    b.credentialHash.hash, b.credentialHash.verify, b.auth.password.needsRehash
+ *
+ * Returns `true` when the stored envelope was produced under an
+ * algorithm or parameter set that no longer matches the framework
+ * default. Operators wrap a successful `verify` with this and re-issue
+ * the credential transparently — same shape as `b.auth.password`.
+ * Argon2id rows defer the parameter-lag check to the password
+ * primitive's own `needsRehash` so the threshold lives in one place.
+ *
+ * @opts
+ *   algo:   "shake256" | "argon2id",              // pin the comparison target
+ *   params: object,                               // Argon2id m / t / p targets
+ *
+ * @example
+ *   if (await b.credentialHash.verify(secret, row.credentialHash)) {
+ *     if (b.credentialHash.needsRehash(row.credentialHash)) {
+ *       var fresh = await b.credentialHash.hash(secret);
+ *       db.from("apiKeys").where({ _id: row._id }).update({ credentialHash: fresh });
+ *     }
+ *   }
+ *   // → true / false
+ */
 function needsRehash(envelope, opts) {
   var decoded = _decodeEnvelope(envelope);
   if (!decoded) return true;     // unrecognized → migrate aggressively