@wener/common 1.0.1

package/src/password/PHC.ts

@@ -0,0 +1,247 @@
+import { ArrayBuffers } from '@wener/utils';
+
+export namespace PHC {
+  // https://github.com/simonepri/phc-format/blob/master/index.js
+
+  const idRegex = /^[a-z0-9-]{1,32}$/;
+  const nameRegex = /^[a-z0-9-]{1,32}$/;
+  const valueRegex = /^[a-zA-Z0-9/+.-]+$/;
+  const b64Regex = /^([a-zA-Z0-9/+.-]+|)$/;
+  const decimalRegex = /^((-)?[1-9]\d*|0)$/;
+  const versionRegex = /^v=(\d+)$/;
+
+  const fromBase64 = ArrayBuffers.fromBase64;
+  const toBase64 = ArrayBuffers.toBase64;
+  const isBuffer = (v: any): v is Uint8Array => {
+    return v instanceof Uint8Array;
+  };
+
+  function objToKeyVal(obj: Record<string, any>): string {
+    return objectKeys(obj)
+      .map((k) => [k, obj[k]].join('='))
+      .join(',');
+  }
+
+  function keyValtoObj(str: string): Record<string, string> {
+    const obj: Record<string, string> = {};
+    str.split(',').forEach((ps) => {
+      const pss = ps.split('=');
+      if (pss.length < 2) {
+        throw new TypeError(`params must be in the format name=value`);
+      }
+
+      const key = pss.shift();
+      if (key !== undefined) {
+        obj[key] = pss.join('=');
+      }
+    });
+    return obj;
+  }
+
+  function objectKeys<T extends object>(object: T): Array<keyof T> {
+    return Object.keys(object) as Array<keyof T>;
+  }
+
+  function objectValues<T extends object>(object: T): Array<T[keyof T]> {
+    if (typeof Object.values === 'function') return Object.values(object);
+    return objectKeys(object).map((k) => object[k]);
+  }
+
+  interface SerializeOptions {
+    id: string;
+    version?: number;
+    params?: Record<string, string | number | Uint8Array>;
+    salt?: Uint8Array;
+    hash?: Uint8Array;
+  }
+
+  /**
+   * Generates a PHC string using the data provided.
+   * @param  {SerializeOptions} opts Object that holds the data needed to generate the PHC string.
+   * @return {string} The hash string adhering to the PHC format.
+   */
+  export function serialize(opts: SerializeOptions): string {
+    const fields: string[] = [''];
+
+    if (typeof opts !== 'object' || opts === null) {
+      throw new TypeError('opts must be an object');
+    }
+
+    // Identifier Validation
+    if (typeof opts.id !== 'string') {
+      throw new TypeError('id must be a string');
+    }
+
+    if (!idRegex.test(opts.id)) {
+      throw new TypeError(`id must satisfy ${idRegex}`);
+    }
+
+    fields.push(opts.id);
+
+    if (typeof opts.version !== 'undefined') {
+      if (typeof opts.version !== 'number' || opts.version < 0 || !Number.isInteger(opts.version)) {
+        throw new TypeError('version must be a positive integer number');
+      }
+
+      fields.push(`v=${opts.version}`);
+    }
+
+    // Parameters Validation
+    if (typeof opts.params !== 'undefined') {
+      if (typeof opts.params !== 'object' || opts.params === null) {
+        throw new TypeError('params must be an object');
+      }
+
+      const pk = objectKeys(opts.params);
+      if (!pk.every((p) => nameRegex.test(p.toString()))) {
+        throw new TypeError(`params names must satisfy ${nameRegex}`);
+      }
+
+      // Convert Numbers into Numeric Strings and Buffers into B64 encoded strings.
+      pk.forEach((k) => {
+        const value = opts.params![k];
+        if (typeof value === 'number') {
+          opts.params![k] = value.toString();
+        } else if (value instanceof Uint8Array) {
+          opts.params![k] = toBase64(value).split('=')[0];
+        }
+      });
+      const pv = objectValues(opts.params);
+      if (!pv.every((v) => typeof v === 'string')) {
+        throw new TypeError('params values must be strings');
+      }
+
+      if (!pv.every((v) => valueRegex.test(v))) {
+        throw new TypeError(`params values must satisfy ${valueRegex}`);
+      }
+
+      const strpar = objToKeyVal(opts.params as Record<string, string>);
+      fields.push(strpar);
+    }
+
+    if (typeof opts.salt !== 'undefined') {
+      // Salt Validation
+      if (!isBuffer(opts.salt)) {
+        throw new TypeError('salt must be a Buffer');
+      }
+
+      fields.push(toBase64(opts.salt).split('=')[0]);
+
+      if (typeof opts.hash !== 'undefined') {
+        // Hash Validation
+        if (!isBuffer(opts.hash)) {
+          throw new TypeError('hash must be a Buffer');
+        }
+
+        fields.push(toBase64(opts.hash).split('=')[0]);
+      }
+    }
+
+    // Create the PHC formatted string
+    const phcstr = fields.join('$');
+
+    return phcstr;
+  }
+
+  interface DeserializeResult {
+    id: string;
+    version?: number;
+    params?: Record<string, string | number>;
+    salt?: Uint8Array;
+    hash?: Uint8Array;
+  }
+
+  /**
+   * Parses data from a PHC string.
+   * @param  {string} phcstr A PHC string to parse.
+   * @return {DeserializeResult} The object containing the data parsed from the PHC string.
+   */
+  export function deserialize(phcstr: string): DeserializeResult {
+    if (typeof phcstr !== 'string' || phcstr === '') {
+      throw new TypeError('pchstr must be a non-empty string');
+    }
+
+    if (phcstr[0] !== '$') {
+      throw new TypeError('pchstr must contain a $ as first char');
+    }
+
+    const fields = phcstr.split('$');
+    // Remove first empty $
+    fields.shift();
+
+    // Parse Fields
+    let maxf = 5;
+    if (!versionRegex.test(fields[1])) maxf--;
+    if (fields.length > maxf) {
+      throw new TypeError(`pchstr contains too many fileds: ${fields.length}/${maxf}`);
+    }
+
+    // Parse Identifier
+    const id = fields.shift();
+    if (!id || !idRegex.test(id)) {
+      throw new TypeError(`id must satisfy ${idRegex}`);
+    }
+
+    let version: number | undefined;
+    // Parse Version
+    if (fields[0] && versionRegex.test(fields[0])) {
+      const versionMatch = fields.shift()?.match(versionRegex);
+      version = versionMatch ? parseInt(versionMatch[1], 10) : undefined;
+    }
+
+    let hash: Uint8Array | undefined;
+    let salt: Uint8Array | undefined;
+    if (fields[fields.length - 1] && b64Regex.test(fields[fields.length - 1])) {
+      if (fields.length > 1 && b64Regex.test(fields[fields.length - 2])) {
+        // Parse Hash
+        const hashStr = fields.pop();
+        if (hashStr) hash = fromBase64(hashStr);
+        // Parse Salt
+        const saltStr = fields.pop();
+        if (saltStr !== undefined) salt = fromBase64(saltStr);
+      } else {
+        // Parse Salt
+        const saltStr = fields.pop();
+        if (saltStr !== undefined) salt = fromBase64(saltStr);
+      }
+    }
+
+    // Parse Parameters
+    let params: Record<string, string | number> | undefined;
+    if (fields.length > 0) {
+      const parstr = fields.pop();
+      if (parstr) {
+        params = keyValtoObj(parstr);
+        if (!Object.keys(params).every((p) => nameRegex.test(p))) {
+          throw new TypeError(`params names must satisfy ${nameRegex}}`);
+        }
+
+        const pv = Object.values(params);
+        if (!pv.every((v) => valueRegex.test(String(v)))) {
+          throw new TypeError(`params values must satisfy ${valueRegex}`);
+        }
+
+        // Convert Decimal Strings into Numbers
+        Object.keys(params).forEach((k) => {
+          const value = params![k];
+          if (typeof value === 'string' && decimalRegex.test(value)) {
+            params![k] = parseInt(value, 10);
+          }
+        });
+      }
+    }
+
+    if (fields.length > 0) {
+      throw new TypeError(`pchstr contains unrecognized fileds: ${fields}`);
+    }
+
+    // Build the output object
+    const phcobj: DeserializeResult = { id };
+    if (version !== undefined) phcobj.version = version;
+    if (params) phcobj.params = params;
+    if (salt) phcobj.salt = salt;
+    if (hash) phcobj.hash = hash;
+
+    return phcobj;
+  }
+}

package/src/password/Password.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'vitest';
+import { createArgon2PasswordAlgorithm } from './createArgon2PasswordAlgorithm';
+import { createBase64PasswordAlgorithm } from './createBase64PasswordAlgorithm';
+import { createBcryptPasswordAlgorithm } from './createBcryptPasswordAlgorithm';
+import { Password } from './Password';
+
+describe('Password', () => {
+  const check = async ({
+    password = '1',
+    ...rest
+  }: Password.PasswordHashOptions & {
+    password?: string;
+  }) => {
+    let out = await Password.hash(password, rest);
+    console.log(`${rest.algorithm || 'default'}: hash ${out}`);
+    let result = await Password.verify(password, out);
+    expect(result).toBe(true);
+  };
+
+  Password.addAlgorithm(createBcryptPasswordAlgorithm());
+  Password.addAlgorithm(createBase64PasswordAlgorithm());
+  Password.addAlgorithm(
+    createArgon2PasswordAlgorithm({
+      provide: import('argon2'),
+    }),
+  );
+  // Password.addAlgorithm(createScryptPasswordAlgorithm());
+
+  test('base', async () => {
+    await check({});
+
+    await check({ algorithm: 'bcrypt' });
+
+    await check({ algorithm: 'base64' });
+    // invalid base 64
+    await check({ algorithm: 'base64', password: '你好' });
+
+    await check({ algorithm: '5' });
+    await check({ algorithm: '6' });
+    await check({ algorithm: '7' });
+  });
+
+  test('should verify manual created hash', async () => {
+    const tests: Array<{
+      password?: string;
+      hash: string;
+    }> = [
+      { hash: '$2y$10$MQ057tMbDG6/lVkGFWrNwOR9kh/5rzbkhBPrwNPTPuZ5wBpGNbWLa' },
+      { hash: '$argon2i$v=19$m=16,t=2,p=1$SDZBU29LRUp0eTJyRDJqZg$76L95nAjG4SjjdoR0YZyFw' },
+      { hash: '$argon2d$v=19$m=16,t=2,p=1$SDZBU29LRUp0eTJyRDJqZg$+cB2R45sauVlfxbGslAmOw' },
+      { hash: '$argon2id$v=19$m=16,t=2,p=1$SDZBU29LRUp0eTJyRDJqZg$iP9HYuSDXgG2lW7KARBuQQ' },
+    ];
+
+    for (const { password = '1', hash } of tests) {
+      expect(await Password.verify(password, hash)).toBe(true);
+    }
+  });
+});

package/src/password/Password.ts

@@ -0,0 +1,113 @@
+import { Errors } from '@wener/utils';
+import { createPBKDF2PasswordAlgorithm } from './createPBKDF2PasswordAlgorithm';
+import { PHC } from './PHC';
+
+export namespace Password {
+  export interface ParsedPassword {
+    id: string;
+    version?: number;
+    params?: Record<string, string | number>;
+    salt?: Uint8Array;
+    hash?: Uint8Array;
+  }
+
+  type PasswordAlgorithmHashOptions = {
+    rounds?: number;
+    salt?: Uint8Array;
+    id?: string;
+  };
+  type PasswordAlgorithmVerifyOptions = ParsedPassword;
+  export type PasswordAlgorithm = {
+    readonly name: string;
+    readonly ids?: string[];
+    hash(password: string, opts?: PasswordAlgorithmHashOptions): Promise<string>;
+    verify(password: string, hash: string, opts: PasswordAlgorithmVerifyOptions): Promise<boolean>;
+  };
+
+  const Algorithms: Record<string, string | PasswordAlgorithm> = {
+    1: 'md5',
+    '2a': 'bcrypt', // original
+    '2b': 'bcrypt', // February 2014
+    '2x': 'bcrypt', // June 2011
+    '2y': 'bcrypt', // June 2011
+    5: 'sha256',
+    6: 'sha512',
+    7: 'scrypt',
+  };
+  let DefaultAlgorithm: string = '6';
+
+  export function setDefaultAlgorithm(algorithm: string) {
+    Errors.BadRequest.check(Algorithms[algorithm], `Unknown algorithm ${algorithm}`);
+    DefaultAlgorithm = algorithm;
+  }
+
+  export function getDefaultAlgorithm() {
+    return DefaultAlgorithm;
+  }
+
+  export function addAlgorithm(algorithm: PasswordAlgorithm) {
+    Algorithms[algorithm.name] = algorithm;
+    if (algorithm.ids) {
+      for (const id of algorithm.ids) {
+        Algorithms[id] = algorithm;
+      }
+    }
+  }
+
+  addAlgorithm(
+    createPBKDF2PasswordAlgorithm({
+      id: 'sha256',
+      digest: 'SHA-256',
+    }),
+  );
+  addAlgorithm(
+    createPBKDF2PasswordAlgorithm({
+      id: 'sha512',
+      digest: 'SHA-512',
+    }),
+  );
+
+  export async function parse(hash: string) {
+    return PHC.deserialize(hash);
+  }
+
+  function resolveAlgorithm(id: string | PasswordAlgorithm): PasswordAlgorithm {
+    let f = id;
+    while (typeof f === 'string') {
+      f = Algorithms[f];
+    }
+    if (!f) {
+      throw new Error(`Unknown algorithm ${id}`);
+    }
+    return f;
+  }
+
+  export async function check(password: string, hash: string) {
+    let res = await parse(hash);
+    let f = resolveAlgorithm(res.id);
+    return {
+      result: f.verify(password, hash, res),
+      parsed: res,
+    };
+  }
+
+  export async function verify(password: string, hash: string) {
+    let res = await parse(hash);
+    let f = resolveAlgorithm(res.id);
+    return f.verify(password, hash, res);
+  }
+
+  export type PasswordHashOptions = PasswordAlgorithmHashOptions & {
+    algorithm?: string | PasswordAlgorithm;
+  };
+
+  export async function hash(password: string, { algorithm, ...opts }: PasswordHashOptions = {}) {
+    let f = resolveAlgorithm(algorithm ?? DefaultAlgorithm);
+    let id = algorithm ?? DefaultAlgorithm;
+    typeof id !== 'string' && (id = f.name);
+    return f.hash(password, {
+      id,
+      ...opts,
+    });
+  }
+}

package/src/password/createArgon2PasswordAlgorithm.ts

@@ -0,0 +1,80 @@
+import { maybeFunction, type MaybeFunction, type MaybePromise } from '@wener/utils';
+import { Password } from './Password';
+
+type Provide = {
+  hash: (password: string, options: { salt?: Buffer; raw?: boolean; type?: 0 | 1 | 2 }) => Promise<string>;
+  verify: (hash: string, password: string) => Promise<boolean>;
+};
+
+export function createArgon2PasswordAlgorithm({
+  type,
+  provide = async () => {
+    throw new Error('Please provide argon2');
+    // const { default: wasm } = await import('argon2-browser/dist/argon2.wasm');
+    // const argon2 = await WebAssembly.instantiateStreaming(fetch(wasm), {
+    //   env: {
+    //     memoryBase: 0,
+    //     tableBase: 0,
+    //     memory: new WebAssembly.Memory({ initial: 256 }),
+    //     table: new WebAssembly.Table({ initial: 0, element: 'anyfunc' }),
+    //     __memory_base: 0,
+    //     __table_base: 0,
+    //   },
+    // });
+    // console.log(argon2.instance.exports);
+    // const { hash } = argon2.instance.exports as any as typeof import('argon2-browser');
+  },
+  // argon2-browser/dist/argon2-bundled.min.js
+  // import('argon2-browser').then(({ default: { hash, verify } }) => {
+  //   return {
+  //     hash(password, options) {
+  //       return hash({
+  //         pass: password,
+  //       });
+  //     },
+  //     verify(hash, password) {
+  //       return verify({
+  //         pass: password,
+  //         hash: hash,
+  //       })
+  //         .then(() => true)
+  //         .catch(() => false);
+  //     },
+  //   };
+  // }),
+  // provide = () => import('argon2'),
+}: {
+  type?: 'argon2d' | 'argon2i' | 'argon2id';
+  provide?: MaybeFunction<MaybePromise<Provide>>;
+} = {}): Password.PasswordAlgorithm {
+  // 0=Argon2d, 1=Argon2i, 2=Argon2id
+  const toType: Record<string, 0 | 1 | 2 | undefined> = {
+    argon2d: 0,
+    argon2i: 1,
+    argon2id: 2,
+  } as const;
+
+  let mod: Provide;
+  const resolve = () => {
+    if (mod) return mod;
+    return Promise.resolve(maybeFunction(provide)).then((v) => (mod = v));
+  };
+  return {
+    name: 'argon2',
+    ids: ['argon2i', 'argon2d', 'argon2id'],
+    async hash(password: string, opts) {
+      // const { hash } = await import('argon2');
+      const { hash } = await resolve();
+      const id = opts?.id;
+      return hash(password, {
+        salt: opts?.salt ? Buffer.from(opts.salt) : undefined,
+        raw: false,
+        type: toType[id || ''] ?? toType[type || ''],
+      });
+    },
+    async verify(password: string, hash: string) {
+      const { verify } = await resolve();
+      return verify(hash, password);
+    },
+  };
+}

package/src/password/createBase64PasswordAlgorithm.ts

@@ -0,0 +1,14 @@
+import { ArrayBuffers } from '@wener/utils';
+import { Password } from './Password';
+
+export function createBase64PasswordAlgorithm({ id = 'base64' }: { id?: string } = {}): Password.PasswordAlgorithm {
+  return {
+    name: id,
+    async hash(password: string) {
+      return `$${id}$$${ArrayBuffers.toBase64(password).replace(/=/g, '')}`;
+    },
+    async verify(password: string, hash: string, opts) {
+      return Boolean(opts.hash) && ArrayBuffers.toString(opts.hash!) === password;
+    },
+  };
+}

package/src/password/createBcryptPasswordAlgorithm.ts

@@ -0,0 +1,30 @@
+import type { MaybePromise } from '@wener/utils';
+import { Password } from './Password';
+
+type ProviderType = () => MaybePromise<{
+  hash: (password: string, rounds: number | string) => Promise<string>;
+  compare: (password: string, hash: string) => Promise<boolean>;
+}>;
+
+export function createBcryptPasswordAlgorithm({
+  // provider = () => import('bcrypt').then((v) => v.default),
+  provider = () => import('bcryptjs').then((v) => v.default),
+}: {
+  provider?: ProviderType;
+} = {}): Password.PasswordAlgorithm {
+  // bcrypt or bcryptjs
+  return {
+    name: 'bcrypt',
+    async hash(password: string, opts) {
+      const { hash } = await provider();
+      return hash(password, opts?.rounds ?? 10);
+    },
+    async verify(password: string, hash: string) {
+      const { compare } = await provider();
+      if (hash.startsWith('$2y$')) {
+        hash = hash.replace(/^\$2y\$/, '$2a$');
+      }
+      return compare(password, hash);
+    },
+  };
+}

package/src/password/createPBKDF2PasswordAlgorithm.ts

@@ -0,0 +1,73 @@
+import { Errors } from '@wener/utils';
+import { Password } from './Password';
+import { PHC } from './PHC';
+
+export function createPBKDF2PasswordAlgorithm({
+  id,
+  digest,
+  iterations = 100000,
+  saltlen = 16,
+  keylen = digest === 'SHA-256' ? 32 : 64,
+}: {
+  id: string;
+  digest: 'SHA-256' | 'SHA-512';
+  iterations?: number;
+  keylen?: number;
+  saltlen?: number;
+}): Password.PasswordAlgorithm {
+  return {
+    name: id,
+    async hash(password: string, opts) {
+      let salt: Uint8Array;
+
+      if (opts?.salt) {
+        salt = opts.salt;
+      } else {
+        salt = new Uint8Array(saltlen);
+        crypto.getRandomValues(salt);
+      }
+
+      const rounds = opts?.rounds ?? iterations;
+
+      let key = await crypto.subtle.importKey('raw', new TextEncoder().encode(password), 'PBKDF2', false, [
+        'deriveBits',
+      ]);
+      let hash = await crypto.subtle.deriveBits(
+        { name: 'PBKDF2', iterations: rounds, salt, hash: digest },
+        key,
+        keylen * 8,
+      );
+      return PHC.serialize({
+        id: opts?.id ?? id,
+        params: {
+          rounds,
+        },
+        salt,
+        hash: new Uint8Array(hash),
+      });
+    },
+    async verify(password: string, _: string, opts) {
+      const rounds = opts?.params?.rounds ?? iterations;
+      const salt = opts.salt;
+      const storedHash = opts.hash;
+      Errors.BadRequest.check(typeof rounds === 'number', 'Invalid rounds');
+      Errors.BadRequest.check(salt instanceof Uint8Array, 'Invalid salt');
+      Errors.BadRequest.check(storedHash instanceof Uint8Array, 'Invalid hash');
+
+      let key = await crypto.subtle.importKey('raw', new TextEncoder().encode(password), 'PBKDF2', false, [
+        'deriveBits',
+      ]);
+      let hash = await crypto.subtle.deriveBits(
+        {
+          name: 'PBKDF2',
+          iterations: rounds,
+          salt,
+          hash: digest,
+        },
+        key,
+        storedHash.length * 8,
+      );
+      return new Uint8Array(hash).every((v, i) => v === storedHash![i]);
+    },
+  };
+}

package/src/password/createScryptPasswordAlgorithm.ts

@@ -0,0 +1,72 @@
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
+import { Errors } from '@wener/utils';
+import { Password } from './Password';
+import { PHC } from './PHC';
+
+export function createScryptPasswordAlgorithm(
+  options: {
+    id?: string;
+    cost?: number;
+    blocksize?: number;
+    parallelism?: number;
+    saltlen?: number;
+    keylen?: number;
+  } = {},
+): Password.PasswordAlgorithm {
+  let id = options.id || 'scrypt';
+  options.cost ||= Math.pow(2, 14);
+  options.blocksize ||= 8;
+  options.parallelism ||= 1;
+  options.saltlen ||= 16;
+  options.keylen ||= 32;
+  return {
+    name: id,
+    async hash(password: string, opts): Promise<string> {
+      const salt = opts?.salt || randomBytes(options.saltlen!);
+      return new Promise((resolve, reject) => {
+        let N = options.cost!;
+        let r = options.blocksize!;
+        let p = options.parallelism!;
+        scrypt(password, salt, options.keylen!, { N, r, p }, (err, derivedKey) => {
+          if (err) return reject(err);
+
+          resolve(
+            PHC.serialize({
+              id: opts?.id ?? id,
+              params: {
+                ln: N!,
+                r: r!,
+                p: p!,
+              },
+              salt,
+              hash: derivedKey,
+            }),
+          );
+        });
+      });
+    },
+
+    async verify(password: string, hash: string, opts): Promise<boolean> {
+      try {
+        const salt = Errors.BadRequest.require(opts.salt);
+        const storedHash = Errors.BadRequest.require(opts.hash);
+
+        const N = parseInt(opts.params?.ln as string, 10);
+        const r = parseInt(opts.params?.r as string, 10);
+        const p = parseInt(opts.params?.p as string, 10);
+        const keylen = storedHash.length;
+
+        return new Promise((resolve, reject) => {
+          scrypt(password, salt, keylen, { N, r, p }, (err, derivedKey) => {
+            if (err) return reject(err);
+
+            const isMatch = timingSafeEqual(derivedKey, storedHash);
+            resolve(isMatch);
+          });
+        });
+      } catch (error) {
+        return Promise.resolve(false);
+      }
+    },
+  };
+}

package/src/password/index.ts

@@ -0,0 +1,5 @@
+export { PHC } from './PHC';
+export { Password } from './Password';
+export { createArgon2PasswordAlgorithm } from './createArgon2PasswordAlgorithm';
+export { createBase64PasswordAlgorithm } from './createBase64PasswordAlgorithm';
+export { createBcryptPasswordAlgorithm } from './createBcryptPasswordAlgorithm';

package/src/password/server/index.ts

@@ -0,0 +1 @@
+export { createScryptPasswordAlgorithm } from '../createScryptPasswordAlgorithm';