Passwords

A password column is the one field where getting the write path wrong is
invisible: the insert succeeds, the row looks right, and the damage only shows
up in a breach. So this page is short, and every example on it is executed by
tests/password-hashing.test.ts.

The shape of it

Hashing happens in a beforeCreate / beforeUpdate hook, so the plain text
never reaches the database no matter which path wrote the row. You supply the
hashing library; the ORM does not bundle one.

import {
  Prorm, DataTypes, Model, Table, Column, PrimaryKey, AutoIncrement, Secure,
} from 'ts-prorm-orm';

@Secure('password', { method: 'scrypt' })
@Table({ tableName: 'users' })
class User extends Model {
  @Column(DataTypes.INTEGER())
  @PrimaryKey
  @AutoIncrement
  declare id: number;

  @Column(DataTypes.STRING(255))
  declare email: string;

  @Column(DataTypes.STRING(255))   // wide enough for the hash, not the password
  declare password: string;
}

const prorm = new Prorm({ dialect: 'sqlite', storage: ':memory:' });
const Users = prorm.addModel(User);
await prorm.sync();

Every write path goes through the same two hooks, so there is no way to
reach the table with the plain text:

@Secure is a class decorator naming a field, not a property decorator:
@Secure('password') above the class, not @Secure() above the property.

The method is the whole configuration — there is nothing to register at boot.
'scrypt' is the default and needs nothing installed; 'bcrypt' and
'argon2' load their package the first time they are used.

addModel() wires the hooks for you — there is no applySecureHooks() call to
forget. (It still exists, and is idempotent, for a model you built another way.)
Writing a user is then ordinary:

const Users = prorm.model('User')!;   // the model registered above
const user = await Users.create({ email: 'a@b.com', password: 'hunter2' });
user.password;   // '$scrypt$…' — the hash, on the instance too

And checking one at sign-in:

const Users = prorm.model('User')!;
const user = await Users.findOne({ where: { email } });
if (!user || !(await user.validate(submittedPassword))) {
  throw new Error('Invalid credentials');
}

validate() on an instance is this check. It used to be the model's
validation rules; those kept their behaviour and moved to
validateRules(), because checking a password is what the
name is reached for far more often.

With more than one secure field, name it: user.validate(pin, 'pin').

Choosing the method

Method	Needs	Notes
`'scrypt'`	nothing	Node's own `crypto`. The default. Its parameters are stored with each hash, so raising the cost later does not invalidate existing passwords.
`'bcrypt'`	`npm install bcrypt`, or `bcryptjs`	Loaded on first use. Cost factor 12.
`'argon2'`	`npm install argon2`	Loaded on first use.

Naming a method whose package is missing fails with the install command rather
than a module-not-found trace.

All three are deliberately slow — a login endpoint that hashes on every
request is doing the right thing.

Your own

method also takes an adapter, which is two functions:

@Secure('password', {
  method: {
    hash: (value) => myLib.hash(value),
    verify: (plain, hashed) => myLib.verify(plain, hashed),
  },
})
class User extends Model { /* … */ }

Each field carries its own method, which is what a migration between two of them
needs — the old column keeps verifying under the old algorithm while the new one
is written under the new:

@Secure('password', { method: 'argon2' })
@Secure('legacyPassword', { method: 'bcrypt' })
class User extends Model { /* … */ }

const user = await prorm.addModel(User).findOne({ where: { email } });
await user.validate(submitted, 'password');
await user.validate(submitted, 'legacyPassword');

A hash cannot be converted, only replaced when the user next types their
password. Keep the old column verifying under its old method, and move each
user across as they sign in:

import {
  Prorm, DataTypes, Model, Table, Column, PrimaryKey, AutoIncrement, AllowNull, Secure,
} from 'ts-prorm-orm';

@Secure('password', { method: 'argon2' })
@Secure('legacyPassword', { method: 'bcrypt' })
@Table({ tableName: 'users' })
class User extends Model {
  @Column(DataTypes.INTEGER())
  @PrimaryKey
  @AutoIncrement
  declare id: number;

  @Column(DataTypes.STRING(255))
  declare email: string;

  @AllowNull(true)
  @Column(DataTypes.STRING(255))
  declare password: string | null;        // argon2: everyone who has signed in since the move

  @AllowNull(true)
  @Column(DataTypes.STRING(255))
  declare legacyPassword: string | null;  // bcrypt: everyone who has not
}

const prorm = new Prorm({ dialect: 'postgres', url: process.env.DATABASE_URL });
const Users = prorm.addModel(User);

export async function signIn(email: string, submitted: string): Promise<User> {
  const user = await Users.findOne({ where: { email } });
  if (!user) throw new Error('Invalid credentials');

  if (user.password) {
    if (await user.validate(submitted, 'password')) return user;
  } else if (user.legacyPassword && (await user.validate(submitted, 'legacyPassword'))) {
    // Right password, old method: write it under the new one and drop the old hash.
    await user.update({ password: submitted, legacyPassword: null });
    return user;
  }
  throw new Error('Invalid credentials');
}

Both branches answer with the same error, so a caller cannot tell which
method an account is on. When legacyPassword is null on every row, drop the
column and its @Secure.

The older API

setEncryptionAdapter(), createBcryptAdapter(), createArgon2Adapter() and
verifySecureField() still work and are deprecated. They required a
boot-time call that, if forgotten, meant the password reached the database in
clear; method cannot be forgotten, because it is on the field.

Re-saving a hash does not hash it twice

The hook skips a value that already looks like a hash — bcrypt's $2a$ / $2b$ /
$2y$ , argon2's $argon2…, scrypt's $scrypt$ . Without that, loading a user,
changing their email and saving would hash the hash and lock them out.

const user = await Users.findByPk(1);
user.email = 'new@example.com';
await user.save();               // password untouched

Turn it off with { skipIfHashed: false } only if you know your stored values
do not look like hashes.

A single write fires more than one hook, so the value hashed during a write is
remembered for that instance as well — otherwise a custom adapter, whose output
the format check does not recognise, would be asked to hash its own hash.

Changing a password is just a write:

await user.update({ password: 'a new one' });   // hashed on the way in

Without decorators

prorm.define() declares it on the column, which is the same thing @Secure
says about a class:

secure: true is scrypt, which needs nothing installed. The other forms are the
ones method takes:

Everything else on this page is unchanged — the write hashes, save() does not
re-hash, and sign-in is await user.validate(submitted). Two secure columns on
one model each keep their own method, so a migration between algorithms works
the same way here:

There is no wiring call: define() reads the column and registers the hooks,
the same way addModel() does for the decorator.

What this does not do

[!WARNING]
It does not hide the column. findAll() returns the hash like any other
field, and JSON.stringify(user) includes it. Exclude it
(attributes: { exclude: ['password'] }) or use
@CannotView so it never leaves the process by accident.

It does not rate-limit sign-ins. Hashing cost slows an attacker per
guess; it does not stop them guessing.

It does not validate strength. That is a
validation rule: @Len([12, 128]) and whatever policy you
keep.

It is not encryption. A hash is one-way and cannot be read back. For a
value you need to recover — an API token you must present later — see the
field-encryption tooling in Compliance.

Decorators — the wider decorator set

Validation — length and format rules on the same field

Hooks — the lifecycle events these are built on

Compliance — reversible field encryption, masking, audit

The shape of it#

Choosing the method#

Your own#

Moving users to a new method at sign-in#

The older API#

Re-saving a hash does not hash it twice#

Without decorators#

What this does not do#

Related reading#