Manual · API

`security`

Passwords and the keychain. Deliberately small: who may do what is your application's question — these are the tools to answer it with.

Every command on this page carries a worked example.

hashPassword function

security.hashPassword(password)

Turns a password into the hash you store — never the password itself; a .passwordField refuses to be bound to a column for exactly this reason.

Worked example

// Setting a password — the record stores the hash, never the password:
person.passwordHash = security.hashPassword(form.newPasswordField.value);
person.save();

verifyPassword function

security.verifyPassword(password, hash)

Whether the typed password matches the stored hash.

Right after a successful check, ask passwordNeedsRehashing — it is the one moment you hold the real password and can silently upgrade an old hash.

Worked example

// Signing in, in app.onStart.js:
const person = database.users.where("name", "=", typedName).first();
if (person === null ||
    !security.verifyPassword(typedPassword, person.passwordHash)) {
    messages.showError("Wrong name or password.");
    application.quit();
}
// After a proven sign-in, keep the hash current:
if (security.passwordNeedsRehashing(person.passwordHash)) {
    person.passwordHash = security.hashPassword(typedPassword);
    person.save();
}

passwordNeedsRehashing function

security.passwordNeedsRehashing(hash)

After a proven sign-in: whether the stored hash uses yesterday's parameters and should be re-made from the fresh password while you have it.

Worked example

// Right after a successful sign-in — the one moment you hold the real password:
if (security.passwordNeedsRehashing(person.passwordHash)) {
    person.passwordHash = security.hashPassword(typedPassword);
    person.save();
}

storeSecret function

security.storeSecret(name, value)

Puts a value into the Mac's keychain — for API keys and the like, never for your customer's rows.

Worked example

security.storeSecret("apiKey", form.keyField.value);   // the Mac's keychain

loadSecret function

security.loadSecret(name)

Reads it back, or null.

Worked example

const key = security.loadSecret("apiKey");
if (key === null) { forms.open("Setup"); }

removeSecret function

security.removeSecret(name)

Forgets it.

Worked example

security.removeSecret("apiKey");