Add an even more streamlined verification function

[cbodin]

According to your #469 issue, this library will be more streamlined towards password hashing moving forward.

The current API is pretty similar to the PHP password functions, with the hash, verify and needsRehash functions.

I would like to propose a new API combining the verify and needsRehash functions to increase the adoption of password re-hashing when parameters change or a new version is released. These could then be the recommended methods for developers who just want to hash passwords and use the defaults provided by the library.

My proposal is something like the ASP.NET Core Identity PasswordHasher.VerifyHashedPassword method:

// Always uses the default options
async hashPassword(password: string): string {
  return await argon2.hash(password);
}

async verifyPassword(digest: string, password: string): "success" | "success-rehash-needed" | false {
  const result = await argon2.verify(digest, password);
  if (!result) {
    return false;
  }

  // Always compares against the default options
  if (argon2.needsRehash(digest)) {
    return "success-needs-rehash";
  }

  return "success";
}

Returning false instead of something like fail (like the .NET implementation) when verification does not succeed ensures that code checking for truthy values won't bypass verification:

const verified = await verifyPassword("...");
if (verified) {
  // success
} else {
  // failed
}

I'm not sure if this only introduces clutter, but a quick search on github seems to reveal that needsRehash is not widely used:
argon2.verify language:TypeScript : 10.3k results
argon2.verify language:JavaScript: 5.4k results
argon2.needsRehash language:TypeScript: 59 results
argon2.needsRehash language:JavaScript: 23 results

[ranisalt]

I'm unsure about this, the signature looks odd when returning strings. I wish JS had the possibility of overloading conversion operators such that I could return a meaningful object that coerces to false when verification fails...

I'll keep looking into options meanwhile to see if I figure out something that feels better. What do you think about an integer enum, just like the ASP.NET function you linked?

[cbodin]

Yeah, i agree. A union would also not be particularly helpful for non-typescript users.

Maybe something like this?

enum PasswordVerificationResult {
  Fail = 0,
  Success = 1,
  SuccessRehashNeeded = 2,
};

// Always uses the default options
async function hashPassword(password: string): Promise<string> {
    return await argon2.hash(password);
}

async function verifyPassword(digest: string, password: string): Promise<PasswordVerificationResult> {
    const result = await argon2.verify(digest, password);
    if (!result) {
        return PasswordVerificationResult.Fail;
    }

    // Always compares against the default options
    if (argon2.needsRehash(digest)) {
        return PasswordVerificationResult.SuccessRehashNeeded;
    }

    return PasswordVerificationResult.Success;
}

Or if avoiding enums:

const PasswordVerificationResult = {
    Fail: 0,
    Success: 1,
    SuccessRehashNeeded: 2,
} as const;

type PasswordVerificationResult = typeof PasswordVerificationResult[
    keyof typeof PasswordVerificationResult
];