Password Reset

Password reset tokens let the application issue one-time credentials for resetting local passwords.

Introduction

Password reset uses the configured broker and local provider:

import { defineAuthConfig } from '@holo-js/auth'
import { env } from '@holo-js/config'
export default defineAuthConfig({
  passwords: {
    users: {
      provider: 'users',
      table: 'password_reset_tokens',
      expire: 60,
      throttle: 60,
      route: env('AUTH_PASSWORD_RESET_ROUTE', '/reset-password'),
    },
  },
})

Set the route and base app URL in the environment:

APP_URL=http://localhost:3000
AUTH_PASSWORD_RESET_ROUTE=/reset-password

The framework-generated reset email uses APP_URL plus the configured broker route automatically.

The application still owns the reset page and the route that calls resetPassword(...). The framework owns the generated link target and delivery URL composition.

Requesting A Reset Token

import { requestPasswordReset } from '@holo-js/auth'

await requestPasswordReset({
  email: '[email protected]',
})

If the request fails for an expected auth reason, it throws a ValidationException. Its serialized payload contains the status and field errors:

{
  ok: false,
  status: 422,
  valid: false,
  errors: {
    email: ['Email is required to request a password reset.'],
  },
}

The flow:

• looks up the user through the configured broker provider
• invalidates older tokens for that email
• creates a new hashed reset token
• sends the reset email through the configured delivery hook

Resetting The Password

import { resetPassword } from '@holo-js/auth'

const resetUser = await resetPassword({
  token: body.token,
  password: body.password,
  passwordConfirmation: body.passwordConfirmation,
})

The thrown ValidationException targets the submitted auth fields directly, such as token, password, and passwordConfirmation. Successful calls return the updated user.

The reset flow verifies the token, hashes the new password, updates the local user record, and invalidates the used token.

Broker Selection

Use a non-default broker when needed:

await requestPasswordReset({
  email: '[email protected]',
}, {
  broker: 'admins',
})

Delivery

Password reset delivery works the same way as email verification:

• auth creates the token
• core builds the reset URL automatically from APP_URL and the configured broker route
• notifications or direct mail deliver the message when those integrations are installed

If @holo-js/auth and @holo-js/notifications are both installed with mail support, core bridges auth delivery through notifications automatically. If notifications are absent but @holo-js/mail is installed, core falls back to direct mail delivery.

When auth and notifications are scaffolded together, Holo creates editable notification files:

server/notifications/auth/email-verification.ts
server/notifications/auth/password-reset.ts

Existing applications can publish those files later:

npx holo auth:notifications:publish

The published password reset notification is a normal defineNotification(...) file. Its email builder receives a small app-facing data with email, generated url, and expiresAt.

Delivery package required

Publishing notification files only gives the application editable message definitions. Email delivery still needs @holo-js/mail or another configured notification mailer. Without delivery, auth creates the reset token and logs that the email was skipped.

Applications do not need to manually create reset-password?token=... URLs in normal usage.