@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/encryption/index.js

@@ -0,0 +1,602 @@
+// src/encryption/Encrypter.ts
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2, createHmac } from "crypto";
+
+// src/encryption/app-key.ts
+import { hkdfSync, randomBytes } from "crypto";
+var APP_KEY_PREFIX = "base64:";
+var APP_KEY_BYTES = 32;
+function decodeAppKey(rawKey, envName) {
+  const trimmed = rawKey.trim();
+  if (!trimmed) {
+    throw new Error(`${envName} is required and must be a base64-encoded 32-byte key.`);
+  }
+  const encoded = trimmed.startsWith(APP_KEY_PREFIX) ? trimmed.slice(APP_KEY_PREFIX.length) : trimmed;
+  const decoded = Buffer.from(encoded, "base64");
+  if (decoded.length !== APP_KEY_BYTES || decoded.toString("base64") !== encoded.replace(/\s+/gu, "")) {
+    throw new Error(`${envName} must be a base64-encoded 32-byte key.`);
+  }
+  return decoded;
+}
+function normalizeAppKey(rawKey, envName = "APP_KEY") {
+  return `${APP_KEY_PREFIX}${decodeAppKey(rawKey, envName).toString("base64")}`;
+}
+function parseAppKey(rawKey, envName = "APP_KEY") {
+  return decodeAppKey(rawKey, envName);
+}
+function parsePreviousAppKeys(rawKeys, envName = "APP_PREVIOUS_KEYS") {
+  if (!rawKeys) {
+    return [];
+  }
+  return rawKeys.split(",").map((value) => value.trim()).filter(Boolean).map((value, index) => decodeAppKey(value, `${envName}[${index}]`));
+}
+function getAppKeyringFromEnv(env = process.env) {
+  return {
+    current: parseAppKey(env.APP_KEY ?? "", "APP_KEY"),
+    previous: parsePreviousAppKeys(env.APP_PREVIOUS_KEYS)
+  };
+}
+function deriveAppKey(rootKey, purpose) {
+  return Buffer.from(
+    hkdfSync("sha256", rootKey, Buffer.alloc(0), Buffer.from(`guren:${purpose}`, "utf8"), APP_KEY_BYTES)
+  );
+}
+function deriveAppKeyring(keyring, purpose) {
+  return {
+    current: deriveAppKey(keyring.current, purpose),
+    previous: keyring.previous.map((key) => deriveAppKey(key, purpose))
+  };
+}
+function encodeDerivedKey(key) {
+  return `${APP_KEY_PREFIX}${key.toString("base64")}`;
+}
+function generateAppKey() {
+  return `${APP_KEY_PREFIX}${randomBytes(APP_KEY_BYTES).toString("base64")}`;
+}
+
+// src/encryption/Encrypter.ts
+var Encrypter = class {
+  /**
+   * Encryption key.
+   */
+  key;
+  previousKeys;
+  /**
+   * Cipher algorithm.
+   */
+  cipher;
+  constructor(config) {
+    this.key = Buffer.from(normalizeAppKey(config.key).slice("base64:".length), "base64");
+    this.previousKeys = (config.previousKeys ?? []).map(
+      (key) => Buffer.from(normalizeAppKey(key).slice("base64:".length), "base64")
+    );
+    this.cipher = config.cipher ?? "aes-256-gcm";
+  }
+  /**
+   * Encrypt a value.
+   */
+  encrypt(value, options = {}) {
+    const serialize = options.serialize !== false;
+    const data = serialize ? JSON.stringify(value) : String(value);
+    if (this.cipher === "aes-256-gcm") {
+      return this.encryptGcm(data);
+    }
+    return this.encryptCbc(data);
+  }
+  /**
+   * Decrypt a value.
+   */
+  decrypt(payload, options = {}) {
+    const deserialize = options.deserialize !== false;
+    let parsed;
+    try {
+      parsed = JSON.parse(Buffer.from(payload, "base64").toString("utf8"));
+    } catch {
+      throw new Error("Invalid encrypted payload.");
+    }
+    let decrypted;
+    if (parsed.tag) {
+      decrypted = this.decryptGcm(parsed);
+    } else if (parsed.mac) {
+      decrypted = this.decryptCbc(parsed);
+    } else {
+      throw new Error("Invalid encrypted payload format.");
+    }
+    if (deserialize) {
+      try {
+        return JSON.parse(decrypted);
+      } catch {
+        return decrypted;
+      }
+    }
+    return decrypted;
+  }
+  /**
+   * Encrypt a string (no serialization).
+   */
+  encryptString(value) {
+    return this.encrypt(value, { serialize: false });
+  }
+  /**
+   * Decrypt a string (no deserialization).
+   */
+  decryptString(payload) {
+    return this.decrypt(payload, { deserialize: false });
+  }
+  /**
+   * Encrypt using AES-256-GCM.
+   */
+  encryptGcm(data) {
+    const iv = randomBytes2(12);
+    const cipher = createCipheriv("aes-256-gcm", this.key, iv);
+    const encrypted = Buffer.concat([
+      cipher.update(data, "utf8"),
+      cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    const payload = {
+      iv: iv.toString("base64"),
+      value: encrypted.toString("base64"),
+      tag: tag.toString("base64")
+    };
+    return Buffer.from(JSON.stringify(payload)).toString("base64");
+  }
+  /**
+   * Decrypt using AES-256-GCM.
+   */
+  decryptGcm(payload) {
+    return this.tryDecryptWithKeys((key) => {
+      const iv = Buffer.from(payload.iv, "base64");
+      const encrypted = Buffer.from(payload.value, "base64");
+      const tag = Buffer.from(payload.tag, "base64");
+      const decipher = createDecipheriv("aes-256-gcm", key, iv);
+      decipher.setAuthTag(tag);
+      const decrypted = Buffer.concat([
+        decipher.update(encrypted),
+        decipher.final()
+      ]);
+      return decrypted.toString("utf8");
+    });
+  }
+  /**
+   * Encrypt using AES-256-CBC with HMAC.
+   */
+  encryptCbc(data) {
+    const iv = randomBytes2(16);
+    const cipher = createCipheriv("aes-256-cbc", this.key, iv);
+    const encrypted = Buffer.concat([
+      cipher.update(data, "utf8"),
+      cipher.final()
+    ]);
+    const mac = this.createMac(iv, encrypted);
+    const payload = {
+      iv: iv.toString("base64"),
+      value: encrypted.toString("base64"),
+      mac
+    };
+    return Buffer.from(JSON.stringify(payload)).toString("base64");
+  }
+  /**
+   * Decrypt using AES-256-CBC with HMAC verification.
+   */
+  decryptCbc(payload) {
+    return this.tryDecryptWithKeys((key) => {
+      const iv = Buffer.from(payload.iv, "base64");
+      const encrypted = Buffer.from(payload.value, "base64");
+      const expectedMac = this.createMac(iv, encrypted, key);
+      if (!this.secureCompare(payload.mac, expectedMac)) {
+        throw new Error("MAC verification failed.");
+      }
+      const decipher = createDecipheriv("aes-256-cbc", key, iv);
+      const decrypted = Buffer.concat([
+        decipher.update(encrypted),
+        decipher.final()
+      ]);
+      return decrypted.toString("utf8");
+    });
+  }
+  /**
+   * Create HMAC for CBC mode.
+   */
+  createMac(iv, encrypted, key = this.key) {
+    const hmac2 = createHmac("sha256", key);
+    hmac2.update(iv);
+    hmac2.update(encrypted);
+    return hmac2.digest("hex");
+  }
+  /**
+   * Constant-time string comparison.
+   */
+  secureCompare(a, b) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+  }
+  /**
+   * Get the encryption key (base64).
+   */
+  getKey() {
+    return this.key.toString("base64");
+  }
+  tryDecryptWithKeys(run) {
+    const keys = [this.key, ...this.previousKeys];
+    let lastError;
+    for (const key of keys) {
+      try {
+        return run(key);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError ?? new Error("Failed to decrypt payload.");
+  }
+};
+function generateKey() {
+  return generateAppKey();
+}
+var globalEncrypter = null;
+function createEncrypter(config) {
+  return new Encrypter(config);
+}
+function setEncrypter(encrypter) {
+  globalEncrypter = encrypter;
+}
+function getEncrypter() {
+  if (!globalEncrypter) {
+    throw new Error("Encrypter not initialized. Call setEncrypter() first.");
+  }
+  return globalEncrypter;
+}
+function encrypt(value, options) {
+  return getEncrypter().encrypt(value, options);
+}
+function decrypt(payload, options) {
+  return getEncrypter().decrypt(payload, options);
+}
+
+// src/encryption/MessageSigner.ts
+import { createHmac as createHmac2, timingSafeEqual } from "crypto";
+function encodeBase64Url(value) {
+  return Buffer.from(value).toString("base64url");
+}
+function decodeBase64Url(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+function createSignature(input, key) {
+  return encodeBase64Url(createHmac2("sha256", key).update(input).digest());
+}
+function signaturesMatch(actual, expected) {
+  const actualBuffer = Buffer.from(actual, "utf8");
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  if (actualBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(actualBuffer, expectedBuffer);
+}
+var MessageSigner = class {
+  constructor(keyring) {
+    this.keyring = keyring;
+  }
+  sign(payload, options = {}) {
+    const now = Date.now();
+    const claims = {
+      ...payload,
+      iat: Math.floor(now / 1e3),
+      ...options.purpose ? { purpose: options.purpose } : {},
+      ...typeof options.expiresIn === "number" ? { exp: Math.floor((now + options.expiresIn) / 1e3) } : {}
+    };
+    const encodedPayload = encodeBase64Url(JSON.stringify(claims));
+    const signature = createSignature(encodedPayload, this.keyring.current);
+    return `${encodedPayload}.${signature}`;
+  }
+  verify(token, options = {}) {
+    const [encodedPayload, signature, extra] = token.split(".");
+    if (!encodedPayload || !signature || extra) {
+      return null;
+    }
+    const verified = [this.keyring.current, ...this.keyring.previous].some(
+      (key) => signaturesMatch(signature, createSignature(encodedPayload, key))
+    );
+    if (!verified) {
+      return null;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(decodeBase64Url(encodedPayload));
+    } catch {
+      return null;
+    }
+    if (options.purpose && payload.purpose !== options.purpose) {
+      return null;
+    }
+    if (typeof payload.exp === "number" && Math.floor(Date.now() / 1e3) > payload.exp && options.allowExpired !== true) {
+      return null;
+    }
+    return payload;
+  }
+};
+
+// src/encryption/signed-url.ts
+var PURPOSE = "signed-url";
+var SIGNATURE_PARAM = "signature";
+var EXPIRES_PARAM = "expires";
+function canonicalizeUrl(value) {
+  const url = new URL(value);
+  url.searchParams.delete(SIGNATURE_PARAM);
+  const params = Array.from(url.searchParams.entries()).sort(([left], [right]) => left.localeCompare(right));
+  url.search = "";
+  for (const [key, paramValue] of params) {
+    url.searchParams.append(key, paramValue);
+  }
+  return { canonical: `${url.pathname}${url.search}`, url };
+}
+function signUrl(value, keyring, options = {}) {
+  const url = new URL(value);
+  if (typeof options.expiresIn === "number") {
+    url.searchParams.set(EXPIRES_PARAM, String(Math.floor((Date.now() + options.expiresIn) / 1e3)));
+  }
+  const { canonical } = canonicalizeUrl(url.toString());
+  const signer = new MessageSigner(keyring);
+  const signature = signer.sign({ url: canonical }, { purpose: PURPOSE });
+  url.searchParams.set(SIGNATURE_PARAM, signature);
+  return url.toString();
+}
+function verifySignedUrl(value, keyring, options = {}) {
+  const url = new URL(value);
+  const signature = url.searchParams.get(SIGNATURE_PARAM);
+  if (!signature) {
+    return false;
+  }
+  const expires = url.searchParams.get(EXPIRES_PARAM);
+  if (options.requireExpiration && !expires) {
+    return false;
+  }
+  if (expires && Number(expires) < Math.floor(Date.now() / 1e3)) {
+    return false;
+  }
+  const { canonical } = canonicalizeUrl(value);
+  const signer = new MessageSigner(keyring);
+  const payload = signer.verify(signature, { purpose: PURPOSE });
+  return payload?.url === canonical;
+}
+
+// src/encryption/Hash.ts
+import {
+  createHash,
+  createHmac as createHmac3,
+  randomBytes as randomBytes3,
+  scrypt,
+  timingSafeEqual as timingSafeEqual2
+} from "crypto";
+import { promisify } from "util";
+var scryptAsync = promisify(scrypt);
+function hash(value, algorithm = "sha256", encoding = "hex") {
+  return createHash(algorithm).update(value).digest(encoding);
+}
+function hmac(value, key, options = {}) {
+  const { algorithm = "sha256", encoding = "hex" } = options;
+  return createHmac3(algorithm, key).update(value).digest(encoding);
+}
+function verifyHmac(value, signature, key, options = {}) {
+  const expected = hmac(value, key, options);
+  return secureCompare(signature, expected);
+}
+function sha256(value) {
+  return hash(value, "sha256");
+}
+function sha512(value) {
+  return hash(value, "sha512");
+}
+function md5(value) {
+  return hash(value, "md5");
+}
+async function hashPassword(password, options = {}) {
+  const {
+    cost = 16384,
+    // N
+    memory = 8,
+    // r (block size)
+    saltLength = 16,
+    keyLength = 64
+  } = options;
+  const salt = randomBytes3(saltLength);
+  const derived = await scryptAsync(password, salt, keyLength, {
+    N: cost,
+    r: memory,
+    p: 1
+  });
+  const params = `N=${cost},r=${memory},p=1`;
+  return `$scrypt$${params}$${salt.toString("base64")}$${derived.toString("base64")}`;
+}
+async function verifyPassword(password, hash2) {
+  if (!hash2.startsWith("$scrypt$")) {
+    throw new Error("Invalid password hash format.");
+  }
+  const parts = hash2.split("$");
+  if (parts.length !== 5) {
+    throw new Error("Invalid password hash format.");
+  }
+  const [, , paramsStr, saltB64, hashB64] = parts;
+  const params = {};
+  for (const param of paramsStr.split(",")) {
+    const [key, value] = param.split("=");
+    params[key] = parseInt(value, 10);
+  }
+  const salt = Buffer.from(saltB64, "base64");
+  const expectedHash = Buffer.from(hashB64, "base64");
+  const derived = await scryptAsync(password, salt, expectedHash.length, {
+    N: params.N,
+    r: params.r,
+    p: params.p ?? 1
+  });
+  return timingSafeEqual2(derived, expectedHash);
+}
+function needsRehash(hash2, options = {}) {
+  const { cost = 16384, memory = 8 } = options;
+  if (!hash2.startsWith("$scrypt$")) {
+    return true;
+  }
+  const parts = hash2.split("$");
+  if (parts.length !== 5) {
+    return true;
+  }
+  const paramsStr = parts[2];
+  const params = {};
+  for (const param of paramsStr.split(",")) {
+    const [key, value] = param.split("=");
+    params[key] = parseInt(value, 10);
+  }
+  return params.N !== cost || params.r !== memory;
+}
+function secureCompare(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  return timingSafeEqual2(bufA, bufB);
+}
+function check(value, hash2, algorithm = "sha256") {
+  const computed = createHash(algorithm).update(value).digest("hex");
+  return secureCompare(computed, hash2);
+}
+
+// src/encryption/Random.ts
+import { randomBytes as randomBytes4, randomUUID, randomInt as cryptoRandomInt } from "crypto";
+var CHARSETS = {
+  alphanumeric: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
+  alphabetic: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  numeric: "0123456789",
+  hex: "0123456789abcdef",
+  "base64": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+  "url-safe": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+};
+function randomString(length, options = {}) {
+  const { charset = "alphanumeric" } = options;
+  const chars = CHARSETS[charset];
+  const bytes = randomBytes4(length);
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars[bytes[i] % chars.length];
+  }
+  return result;
+}
+function random(length) {
+  return randomBytes4(length);
+}
+function randomHex(length) {
+  return randomBytes4(length).toString("hex");
+}
+function randomBase64(length) {
+  return randomBytes4(length).toString("base64");
+}
+function randomBase64Url(length) {
+  return randomBytes4(length).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function uuid() {
+  return randomUUID();
+}
+function randomInt(min, max) {
+  return cryptoRandomInt(min, max + 1);
+}
+function urlSafeToken(length = 32) {
+  return randomBase64Url(Math.ceil(length * 0.75)).slice(0, length);
+}
+function generatePassword(length = 16, options = {}) {
+  const {
+    uppercase = true,
+    lowercase = true,
+    numbers = true,
+    symbols = true
+  } = options;
+  let chars = "";
+  if (uppercase) chars += "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  if (lowercase) chars += "abcdefghijklmnopqrstuvwxyz";
+  if (numbers) chars += "0123456789";
+  if (symbols) chars += "!@#$%^&*()-_=+[]{}|;:,.<>?";
+  if (chars.length === 0) {
+    chars = CHARSETS.alphanumeric;
+  }
+  const bytes = randomBytes4(length);
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars[bytes[i] % chars.length];
+  }
+  return result;
+}
+function generateOtp(length = 6) {
+  return randomString(length, { charset: "numeric" });
+}
+function generateSlug(length = 10) {
+  return randomString(length, { charset: "hex" });
+}
+function shuffle(array) {
+  const result = [...array];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = randomInt(0, i);
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+function pick(array) {
+  if (array.length === 0) {
+    throw new Error("Cannot pick from empty array.");
+  }
+  return array[randomInt(0, array.length - 1)];
+}
+function sample(array, count) {
+  if (count > array.length) {
+    throw new Error("Sample count exceeds array length.");
+  }
+  const shuffled = shuffle(array);
+  return shuffled.slice(0, count);
+}
+export {
+  Encrypter,
+  MessageSigner,
+  check,
+  createEncrypter,
+  decrypt,
+  deriveAppKey,
+  deriveAppKeyring,
+  encodeDerivedKey,
+  encrypt,
+  generateAppKey,
+  generateKey,
+  generateOtp,
+  generatePassword,
+  generateSlug,
+  getAppKeyringFromEnv,
+  getEncrypter,
+  hash,
+  hashPassword,
+  hmac,
+  md5,
+  needsRehash,
+  normalizeAppKey,
+  parseAppKey,
+  parsePreviousAppKeys,
+  pick,
+  random,
+  randomBase64,
+  randomBase64Url,
+  randomHex,
+  randomInt,
+  randomString,
+  sample,
+  secureCompare,
+  setEncrypter,
+  sha256,
+  sha512,
+  shuffle,
+  signUrl,
+  urlSafeToken,
+  uuid,
+  verifyHmac,
+  verifyPassword,
+  verifySignedUrl
+};