argon2
The argon2 namespace provides Argon2id password hashing with configurable parameters.
import { CryptoError, argon2, jwt, rand } from "tyrus:crypto";
interface SessionClaims {
role: string;
}
// Password hashing
match (await argon2.hash("my-password")) {
Ok(hash) => {
match (await argon2.verify(hash, "my-password")) {
Ok(valid) => { print(valid); } // true
Err(error) => { printError(error.code); } // ERR_CRYPTO_ARGON2_*
}
match (argon2.needsRehash(hash)) {
Ok(migrate) => { print(migrate); } // false
Err(error) => { printError(error.code); } // ERR_CRYPTO_ARGON2_INVALID_HASH
}
}
Err(error) => { printError(error.code); } // ERR_CRYPTO_ARGON2_*
}
// JWT HMAC requires at least 32 bytes of secret material.
try {
const key: string = "0123456789abcdef0123456789abcdef";
const inputClaims: SessionClaims = { role: "reader" };
const signed: Result<string, CryptoError> = jwt.sign(inputClaims, key, { algorithm: "HS384", expiresIn: "1h", subject: "123" });
match (signed) {
Ok(token) => {
const verified: Result<SessionClaims, CryptoError> = jwt.verify<SessionClaims>(token, key, { algorithms: ["HS384"], subject: "123" });
match (verified) {
Ok(claims) => {
print(claims.role); // reader
}
Err(error) => { printError(error.code); } // ERR_CRYPTO_*
}
}
Err(error) => { printError(error.code); } // ERR_CRYPTO_*
}
} catch (error: Error) {
printError(error.message);
}
// Secure random
const id: string = rand.uuidv7();
try {
const bytes: u8[] = rand.randomBytes(32);
print(bytes.length);
} catch (error: Error) {
printError(error.message);
}Functions
| Function | Signature |
|---|---|
argon2.hash | (string | u8[], options?) => Promise<Result<string, CryptoError>> |
argon2.verify | (string, string | u8[], options?) => Promise<Result<boolean, CryptoError>> |
argon2.needsRehash | (string) => Result<boolean, CryptoError> |
argon2.hash fulfills with Ok(hash) on success and Err(CryptoError) on invalid input, invalid options, exhausted concurrency, random source failure, or worker failure. It uses Argon2id with a random 16-byte salt, a 32-byte output, and the default profile m=65536, t=3, p=4. Options may set type: "argon2id", memoryCost from 19,456 to 262,144 KiB, timeCost from 2 to 10, parallelism from 1 to 16, and a non-empty binary secret up to 1,024 bytes. Text and binary passwords are limited to 1,024 bytes.
argon2.verify fulfills with Ok(matches) for a valid hash and Err(CryptoError) for malformed PHC strings, invalid parameters, missing required pepper, exhausted concurrency, or worker failure. PHC strings are limited to 4 KiB and untrusted parameters are validated before allocating work. A peppered hash contains a non-secret authenticated marker; omitting secret returns ERR_CRYPTO_ARGON2_PEPPER_REQUIRED, while a supplied but incorrect secret returns Ok(false). Store and rotate pepper separately from password hashes.
argon2.needsRehash returns Ok(true) when the PHC string is valid but its algorithm, version, parameters, salt length, or output length differs from the default profile. Invalid or oversized PHC strings return Err(CryptoError) with code ERR_CRYPTO_ARGON2_INVALID_HASH.
Concurrency limit
At most four Argon2 operations run concurrently. Additional calls fulfill with Err(CryptoError) using code ERR_CRYPTO_ARGON2_BUSY.
