view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

  return $c->render(json => { user => $c->stash('fuin.identify') });
};

# Per-request override of cookie/session TTLs
post '/login-custom' => sub {
  my $c    = shift;
  my $opts = {
    c_time => $c->param('c_time') // '2h',  # auth cookie TTL
    s_time => $c->param('s_time') // '30m', # session TTL
  };
  my $res = $c->fuin_signin($c->param('user'), $opts);
  return $c->render(status => $res->{code}, json => $res);
};

get '/auth-update-custom' => sub {
  my $c        = shift;
  my $backend  = $c->stash('fuin.backend-id');
  my $res      = $c->fuin_auth_update($backend, {c_time => '45m', s_time => '20m'});
  my $httpcode = $res->{code} // 500;
  return $c->render(status => $httpcode, json => $res);
};

app->start;
```

Mojolicious (non-Lite) looks the same inside `startup`, e.g. `$self->plugin('Hakkefuin' => { ... });`.

On startup the plugin will:

- Ensure the auth table exists on startup. A migration SQL file under `dir` is only written when you pass custom `table_config` (otherwise tables are created directly in the database).
- Attach a shared `Mojo::Hakkefuin::Sessions` instance so session cookies get `max-age` derived from `s.time`.
- Register helpers using your chosen `helper.prefix`.

## Configuration

All options are optional; defaults are shown in parentheses.

- `helper.prefix` (`mhf`): prefix for helpers (`<prefix>_signin`, `<prefix>_csrf`, etc.).
- `stash.prefix` (`mhf`): prefix for stash keys set by `*_has_auth` (`mhf.backend-id`, `mhf.identify`, `mhf.lock_state`).
- `via` (`sqlite`): backend driver: `sqlite`, `mariadb`, or `pg`. `dsn` is required for `mariadb`/`pg`.
- `dsn` (none): DB connection string, e.g. `mariadb://user:pass@db:3306/mhf` or `postgresql://user:pass@localhost/mhf`.
- `dir` (`migrations`): directory for migration SQL and SQLite DB file.
- `csrf.name` (`mhf_csrf_token`): session/header key for the CSRF token.
- `c.time` (`1w`): auth cookie lifetime; also used to set DB expiration.
- `s.time` (`1w`): session cookie lifetime; also sets `max-age` when supported by the browser.
- `cl.time` (`60m`): lock cookie lifetime when `lock` is enabled.
- `lock` (`1`): enable lock/unlock helpers and cookies.
- `cookies` (`{name => 'clg', path => '/', httponly => 1, secure => 0}`): override auth cookie attributes; `expires`/`max_age` are computed from `c.time`.
- `cookies_lock` (`{name => 'clglc', path => '/', httponly => 1, secure => 0}`): override lock cookie attributes; `expires`/`max_age` come from `cl.time`.
- `session` (`{cookie_name => '_mhf', cookie_path => '/', secure => 0}`): base options passed to `Mojo::Hakkefuin::Sessions`; `default_expiration` is derived from `s.time`.
- `callback` (`{lock => sub {}, unlock => sub {}}`): optional coderefs called after lock/unlock operations.

## Helper reference

- `<prefix>_signin($identify)`: create auth cookie + CSRF, store in DB with expiration derived from `c.time`.
- `<prefix>_signout($identify)`: clear session and cookies, remove DB entry.
- `<prefix>_has_auth`: check cookie + CSRF against the backend. Returns `{result => 1}` on success, `{result => 2}` when locked, `{result => 3}` when the CSRF token mismatches, or `{result => 0}` when missing/expired. Stashes backend id, identify, an...
- `<prefix>_auth_update($identify)`: rotate cookie and CSRF token for an active session.
- `<prefix>_lock` / `<prefix>_unlock`: issue or clear the lock cookie when `lock` is enabled.
- `<prefix>_csrf`: ensure a CSRF token exists in the session/response headers.
- `<prefix>_csrf_get`, `<prefix>_csrf_val`, `<prefix>_csrf_regen`: read, validate, or regenerate the CSRF token.
- `<prefix>_backend`: access the underlying backend object (e.g. for inspecting connection status).

### Lock/unlock flow

Call `<prefix>_lock` after `*_has_auth` passes to mark the session locked; a lock cookie is issued and the backend row is marked. Use `<prefix>_unlock` to clear the lock. When locked, `*_has_auth` returns `{result => 2, code => 423, lock_cookie => 0|...

## Backend notes

- SQLite stores data in `dir/mhf_sqlite.db`; a `dir/mhf_sqlite.sql` file is written only when `table_config` is provided. Indexes are created in the database at startup.
- MariaDB/MySQL and PostgreSQL create the tables (and indexes) directly in the database at startup; migration SQL is not dumped to `dir` unless you provide `table_config`.
- The plugin calls `check_migration` on startup, so the table is created automatically when credentials are valid.